From c13158a5c518447aee7a3833bb19633d3aa266d9 Mon Sep 17 00:00:00 2001
From: AlexZ005 <alexz005.info@gmail.com>
Date: Tue, 4 Aug 2026 20:23:52 +0300
Subject: [PATCH 1/8] [feat] scene notes v2: name/desc/color/label model,
 near-pin view+edit popover, drawer groups w/ traversal + pins toggle

- H1 model: annotations gain optional name/color/label on top of `text` (still
  the description). ONE normalizeAnnotation() at every store boundary (local
  set, remote apply, snapshot, autosave restore) so old autosaves, .tpscene
  sessions and old-version peers load with defaults. Wire shape UNCHANGED
  ({type:'annotation', op:'set'}); saves spread the base so a newer peer's
  fields survive our edit. displayName()/noteNumber() helpers - numbering is the
  GLOBAL 1-based index, matching the in-scene pin labels.
- H2 openAnnotation(id, 'view'|'edit'); activeAnnotation is {id, mode} (a bare
  {id} still means view). Pin clicks open the view face.
- H3 showNotePins LOCAL pref (lightHelpers idiom) gates BOTH the pins render
  and Scene's pin-click raycast branch; toggle lives in the drawer header.
- H4 pin circle + cone take the note color (amber stays the default).
- H5 popover v2: full runes rewrite, one card with a view and an edit face,
  anchored by a continuous rAF screen projection of the pin (it rides the
  openAnnotation fly and later orbiting - flyTo has no completion hook), flips
  sides + clamps to the viewport, centre-fallback when the pin is behind the
  camera, bottom sheet at <=640px (closes the other sheets). Edit fields: name,
  description, fixed bright swatch row, label w/ a datalist of existing labels.
- H6 drawer v2: rows are "#n name - description" (grey, single-line truncated),
  row click = fly + view, per-row Edit = fly + edit, collapsible label groups
  with 'General' first then alphabetical, per-group arrows traversing in pin
  order with wrap; runes flip.
- H7 new suite notes-v2 (29 checks): legacy normalization, anchored popover +
  re-anchor on pin move, draft at the clicked point, edit saves + replicates the
  v2 fields (send spy) and applies from a peer, pin colors, group order,
  numbering vs pin indices, arrow traversal + wrap, collapse, pins toggle. A
  two-peer handshake check is env-gated (TWO_PEER=1). annotation-anchor,
  autosave-object-flows and roadmap-13-notifications-notes stay green;
  build green; svelte-check holds 419/62.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/components/AnnotationPins.svelte         |  17 +-
 src/components/Scene.svelte                  |   9 +-
 src/components/menu/AnnotationPopover.svelte | 488 +++++++++++++++++--
 src/components/menu/NotesDrawer.svelte       | 249 ++++++++--
 src/lib/annotationsHandler.js                | 107 +++-
 tests/e2e/notes-v2.test.cjs                  | 410 ++++++++++++++++
 6 files changed, 1169 insertions(+), 111 deletions(-)
 create mode 100644 tests/e2e/notes-v2.test.cjs

diff --git a/src/components/AnnotationPins.svelte b/src/components/AnnotationPins.svelte
index 8992585b..9f00d4eb 100644
--- a/src/components/AnnotationPins.svelte
+++ b/src/components/AnnotationPins.svelte
@@ -3,7 +3,7 @@
 	import { T, useTask, useThrelte } from '@threlte/core'
 	// @ts-ignore - Text typing clashes with verbatimModuleSyntax
 	import { Text } from '@threlte/extras'
-	import { annotations, pinsGroup } from '$lib/annotationsHandler'
+	import { annotations, pinsGroup, showNotePins, DEFAULT_NOTE_COLOR } from '$lib/annotationsHandler'
 	import { objectsGroup, globalScene } from '../stores/sceneStore'
 
 	// Billboarded note pins. Each pin re-anchors to its object every frame
@@ -19,6 +19,7 @@
 	const cameraPosition = new THREE.Vector3()
 
 	useTask(() => {
+		if (!$showNotePins) return
 		camera.current.getWorldPosition(cameraPosition)
 		$annotations.forEach((annotation) => {
 			const pin = pinRefs[annotation.id]
@@ -46,16 +47,24 @@
 	})
 </script>
 
-<T.Group bind:ref={root} name="annotation-pins">
+<!-- H3: the pins group hides wholesale with the LOCAL showNotePins pref (the
+     Scene raycast branch is gated on the same store, so hidden pins can't be
+     clicked either) -->
+<T.Group bind:ref={root} name="annotation-pins" visible={$showNotePins}>
 	{#each $annotations as annotation, index (annotation.id)}
 		<T.Group oncreate={(ref) => (pinRefs[annotation.id] = ref)} name={`pin-${annotation.id}`}>
 			<T.Mesh>
 				<T.CircleGeometry args={[0.16, 20]} />
-				<T.MeshBasicMaterial color="#f59e0b" depthTest={false} side={THREE.DoubleSide} />
+				<!-- H4: per-note color; each pin owns its own material instances -->
+				<T.MeshBasicMaterial
+					color={annotation.color || DEFAULT_NOTE_COLOR}
+					depthTest={false}
+					side={THREE.DoubleSide}
+				/>
 			</T.Mesh>
 			<T.Mesh position={[0, -0.19, 0]}>
 				<T.ConeGeometry args={[0.05, 0.12, 8]} />
-				<T.MeshBasicMaterial color="#f59e0b" depthTest={false} />
+				<T.MeshBasicMaterial color={annotation.color || DEFAULT_NOTE_COLOR} depthTest={false} />
 			</T.Mesh>
 			<Text
 				color="#1c1917"
diff --git a/src/components/Scene.svelte b/src/components/Scene.svelte
index 05fb07b0..bfbd4593 100644
--- a/src/components/Scene.svelte
+++ b/src/components/Scene.svelte
@@ -26,7 +26,7 @@
 	import { initVRControls, updateVRControls, raycastMenu, raycastPanel, raycastPalette, raycastProps, raycastPrefabs, raycastKeyboard, raycastChat, raycastEdit, raycastSnap, raycastSettings, raycastApprove, placePrefabGhost, vrFaceTrigger, vrVertexTrigger, vrVertexGrabStart, vrVertexGrabEnd, beginStretchSliderDrag, endStretchSliderDrag, executeVRMenuAction, resetWorldRig, onInputSourcesChange, worldToContentPose, boxSelectStart, boxSelectEnd, boxSelectActive, applyVRFrameRate, shouldSendHands, onHandPinchStart, onHandPinchEnd, pinchMenuToggledAt, firePingIfArmed, vrModuleTriggerStart, vrModuleTriggerEnd, vrModuleSelectSwallowed } from '$lib/vrControls';
 	import { vrKeyboardTarget } from '$lib/vrKeyboard';
 	import { measureMode, measureClick } from '$lib/measure';
-	import { pinsGroup, openAnnotation } from '$lib/annotationsHandler';
+	import { pinsGroup, openAnnotation, showNotePins } from '$lib/annotationsHandler';
 	import { setParticleRoot } from '$lib/particleRuntime';
 	import { sendPing } from '$lib/ping';
 	import { startLightHelpers, updateLightHelpers, lightProxiesGroup } from '$lib/lightHelpers';
@@ -604,13 +604,14 @@
 					return;
 				}
 			}
-			// note pins take priority over object selection
-			if ($pinsGroup) {
+			// note pins take priority over object selection (H3: skipped entirely
+			// while pins are hidden — never rely on raycaster-vs-invisible semantics)
+			if ($pinsGroup && $showNotePins) {
 				const pinHits = selectionRaycaster.intersectObject($pinsGroup, true);
 				let pinNode = pinHits[0]?.object;
 				while (pinNode && !pinNode.name?.startsWith('pin-')) pinNode = pinNode.parent;
 				if (pinNode) {
-					openAnnotation(pinNode.name.slice(4));
+					openAnnotation(pinNode.name.slice(4), 'view');
 					return;
 				}
 			}
diff --git a/src/components/menu/AnnotationPopover.svelte b/src/components/menu/AnnotationPopover.svelte
index ca94847d..a2ab33ce 100644
--- a/src/components/menu/AnnotationPopover.svelte
+++ b/src/components/menu/AnnotationPopover.svelte
@@ -1,74 +1,466 @@
 <script lang="ts">
-	import { Button } from 'flowbite-svelte';
+	import { get } from 'svelte/store';
+	import { untrack } from 'svelte';
+	import { Pencil, Trash2, X, Check } from '@lucide/svelte';
 	import {
 		annotations,
 		activeAnnotation,
 		setAnnotation,
-		deleteAnnotation
+		deleteAnnotation,
+		annotationWorldPosition,
+		displayName,
+		noteNumber,
+		NOTE_COLORS,
+		DEFAULT_NOTE_COLOR
 	} from '$lib/annotationsHandler';
+	import { globalCamera, globalRenderer } from '../../stores/sceneStore';
+	import { notesDrawerOpen, inspectorClose } from '../../stores/appStore.js';
 
-	// Note editor card: opens for a clicked pin ({id}) or a new draft ({draft}).
+	// H5 (notes v2): ONE note card with a VIEW face and an EDIT face, anchored
+	// NEAR its pin by a continuous screen projection — the card rides the camera
+	// through openAnnotation's 400ms fly and while orbiting afterwards (flyTo has
+	// no completion hook, so a one-shot placement would race the tween). Drafts
+	// project the CLICKED point, so "Add note" opens at the cursor.
+	// In VR the pin is in-headset and this DOM card is invisible; openAnnotation
+	// degrades to no visible change there (flyTo bails too).
 
-	$: existing = $activeAnnotation?.id
-		? $annotations.find((a) => a.id === $activeAnnotation.id)
-		: null;
-	$: draft = $activeAnnotation?.draft ?? null;
+	const existing = $derived(
+		$activeAnnotation?.id
+			? ($annotations.find((a) => a.id === $activeAnnotation.id) ?? null)
+			: null
+	);
+	const draft = $derived($activeAnnotation?.draft ?? null);
+	const note = $derived(existing ?? draft);
+	const open = $derived(!!note);
+	// a draft always opens in edit mode; a stored note follows the requested mode
+	const editing = $derived(!!draft || $activeAnnotation?.mode === 'edit');
+	// label suggestions: every label already used in the scene
+	const labels = $derived(
+		[...new Set($annotations.map((a) => (a.label || '').trim()).filter(Boolean))].sort()
+	);
 
-	let text = '';
-	let lastKey = '';
-	$: {
-		const key = existing?.id ?? draft?.id ?? '';
-		if (key !== lastKey) {
-			lastKey = key;
-			text = existing?.text ?? draft?.text ?? '';
+	// --- form state, reseeded whenever the open note (or face) changes ---------
+	let name = $state('');
+	let text = $state('');
+	let color = $state(DEFAULT_NOTE_COLOR);
+	let label = $state('');
+	let seeded = '';
+	$effect(() => {
+		const key = (note?.id ?? '') + ':' + (editing ? 'edit' : 'view');
+		if (key === seeded) return;
+		seeded = key;
+		const source: any = note;
+		untrack(() => {
+			name = source?.name ?? '';
+			text = source?.text ?? '';
+			color = source?.color || DEFAULT_NOTE_COLOR;
+			label = source?.label ?? '';
+		});
+	});
+
+	let nameInput: HTMLInputElement | null = $state(null);
+	$effect(() => {
+		// focus without an autofocus attribute (a11y baseline)
+		if (editing && nameInput) nameInput.focus();
+	});
+
+	// --- placement -------------------------------------------------------------
+	let card: HTMLElement | null = $state(null);
+	let pos = $state({ x: 0, y: 0, anchored: false });
+	let narrow = $state(false);
+
+	$effect(() => {
+		if (typeof window === 'undefined') return;
+		// EXACTLY 640 — the repo's bottom-sheet breakpoint (Inspector/NotesDrawer)
+		const mq = window.matchMedia('(max-width: 640px)');
+		const sync = () => (narrow = mq.matches);
+		sync();
+		mq.addEventListener('change', sync);
+		return () => mq.removeEventListener('change', sync);
+	});
+
+	// one bottom sheet at a time on narrow: the note card takes the bottom, so the
+	// properties sheet and the notes-drawer sheet step aside (NotesDrawer precedent)
+	$effect(() => {
+		if (!open || !narrow) return;
+		untrack(() => {
+			inspectorClose.set(true);
+			notesDrawerOpen.set(false);
+		});
+	});
+
+	$effect(() => {
+		if (!open || narrow) return;
+		let raf = requestAnimationFrame(step);
+		function step() {
+			raf = requestAnimationFrame(step);
+			const active: any = get(activeAnnotation);
+			// a draft has no store entry yet — project its own object+offset
+			const anchor = active?.draft ?? active?.id;
+			if (!anchor) return;
+			const world: any = annotationWorldPosition(anchor);
+			const camera: any = get(globalCamera);
+			const renderer: any = get(globalRenderer);
+			if (!world || !camera || !renderer?.domElement) return;
+			const v = world.clone().project(camera);
+			const rect = renderer.domElement.getBoundingClientRect();
+			const w = card?.offsetWidth || 300;
+			const h = card?.offsetHeight || 220;
+			const m = 8;
+			let anchored = true;
+			let x: number;
+			let y: number;
+			if (v.z >= 1) {
+				// the pin is behind the camera: keep the card usable, centred
+				anchored = false;
+				x = Math.max(m, (window.innerWidth - w) / 2);
+				y = Math.max(m, (window.innerHeight - h) / 2);
+			} else {
+				const sx = rect.left + ((v.x + 1) / 2) * rect.width;
+				const sy = rect.top + ((1 - v.y) / 2) * rect.height;
+				x = sx + 18;
+				if (x + w > window.innerWidth - m) x = sx - 18 - w; // flip to the pin's left
+				x = Math.min(Math.max(m, x), Math.max(m, window.innerWidth - w - m));
+				y = Math.min(Math.max(m, sy - 24), Math.max(m, window.innerHeight - h - m));
+			}
+			if (Math.abs(x - pos.x) > 0.5 || Math.abs(y - pos.y) > 0.5 || anchored !== pos.anchored)
+				pos = { x, y, anchored };
 		}
+		return () => cancelAnimationFrame(raf);
+	});
+
+	// --- actions ---------------------------------------------------------------
+	function close() {
+		activeAnnotation.set(null);
 	}
 
 	function save() {
-		const base = existing ?? draft;
-		if (!base || !text.trim()) return;
-		setAnnotation({ ...base, text: text.trim(), ts: Date.now() });
-		$activeAnnotation = null;
+		const base: any = existing ?? draft;
+		if (!base) return;
+		const description = text.trim();
+		const title = name.trim();
+		if (!description && !title) return; // nothing to save yet
+		// spread the base so fields a newer peer added survive OUR save
+		setAnnotation({
+			...base,
+			name: title,
+			text: description,
+			color,
+			label: label.trim(),
+			ts: Date.now()
+		});
+		activeAnnotation.set({ id: base.id, mode: 'view' });
 	}
 
 	function remove() {
 		if (existing) deleteAnnotation(existing.id);
-		$activeAnnotation = null;
+		else close();
+	}
+
+	function cancel() {
+		if (existing) activeAnnotation.set({ id: existing.id, mode: 'view' });
+		else close();
+	}
+
+	/** @param {number} ts */
+	function when(ts: number) {
+		try {
+			return new Date(ts).toLocaleString();
+		} catch {
+			return '';
+		}
 	}
 </script>
 
-{#if existing || draft}
+{#if open && note}
 	<div
-		class="fixed right-4 top-24 z-40 w-72 rounded-lg border border-amber-500/60 bg-white p-3 shadow-xl dark:bg-gray-800"
+		bind:this={card}
+		class="note-card ui-panel"
+		class:note-sheet={narrow}
+		style={narrow ? '' : `left:${pos.x}px; top:${pos.y}px;`}
+		role="dialog"
+		tabindex="-1"
+		aria-label={editing ? 'Edit note' : 'Note'}
+		onkeydown={(e) => {
+			if (e.key === 'Escape') {
+				e.stopPropagation();
+				close();
+			}
+		}}
 	>
-		<p class="mb-2 text-xs font-semibold uppercase text-amber-500">
-			{existing ? 'Note' : 'New note'}
-		</p>
-		<!-- svelte-ignore a11y_autofocus -->
-		<textarea
-			class="h-24 w-full resize-none rounded-sm border border-gray-300 bg-transparent p-2 text-sm text-gray-800 dark:border-gray-600 dark:text-gray-100"
-			placeholder="Write a note…"
-			autofocus
-			bind:value={text}
-			on:keydown={(e) => {
-				if (e.key === 'Enter' && !e.shiftKey) {
-					e.preventDefault();
-					save();
-				}
-				if (e.key === 'Escape') $activeAnnotation = null;
-			}}
-		></textarea>
-		{#if existing}
-			<p class="mb-2 text-xs text-gray-400">
-				{existing.author} — {new Date(existing.ts).toLocaleString()}
-			</p>
-		{/if}
-		<div class="flex justify-end gap-2">
-			{#if existing}
-				<Button size="xs" color="red" onclick={remove}>Delete</Button>
+		<div class="note-head">
+			<span class="note-num" style="background:{note.color || DEFAULT_NOTE_COLOR}"
+				>{noteNumber(note.id) || '+'}</span
+			>
+			<span class="note-title">{editing ? (existing ? 'Edit note' : 'New note') : displayName(note)}</span>
+			{#if !editing}
+				<button
+					class="note-icon"
+					title="Edit note"
+					aria-label="Edit note"
+					onclick={() => activeAnnotation.set({ id: note.id, mode: 'edit' })}
+				>
+					<Pencil size={15} aria-hidden="true" />
+				</button>
 			{/if}
-			<Button size="xs" color="alternative" onclick={() => ($activeAnnotation = null)}>Close</Button>
-			<Button size="xs" onclick={save}>Save</Button>
+			<button class="note-icon" title="Close" aria-label="Close note" onclick={close}>
+				<X size={15} aria-hidden="true" />
+			</button>
 		</div>
+
+		{#if editing}
+			<div class="note-body">
+				<input
+					bind:this={nameInput}
+					class="ui-input w-full"
+					placeholder="Name (optional)"
+					bind:value={name}
+					onkeydown={(e) => {
+						if (e.key === 'Enter') {
+							e.preventDefault();
+							save();
+						}
+					}}
+				/>
+				<textarea
+					class="ui-input h-20 w-full resize-none"
+					placeholder="Description… (Enter saves, Shift+Enter for a new line)"
+					bind:value={text}
+					onkeydown={(e) => {
+						if (e.key === 'Enter' && !e.shiftKey) {
+							e.preventDefault();
+							save();
+						}
+					}}
+				></textarea>
+				<span class="note-caption">Pin color</span>
+				<!-- fixed swatch row on purpose: a full color picker is heavy in a
+				     small popup (and v4 needs the onInput prop, not on:input) -->
+				<div class="note-swatches" role="group" aria-label="Pin color">
+					{#each NOTE_COLORS as c (c)}
+						<button
+							class="note-swatch"
+							class:is-on={color === c}
+							style="background:{c}"
+							title={c}
+							aria-label={'Pin color ' + c}
+							aria-pressed={color === c}
+							onclick={() => (color = c)}
+						></button>
+					{/each}
+				</div>
+				<span class="note-caption">Label — groups notes in the drawer</span>
+				<input
+					class="ui-input w-full"
+					list="note-labels"
+					placeholder="e.g. mechanics"
+					bind:value={label}
+					onkeydown={(e) => {
+						if (e.key === 'Enter') {
+							e.preventDefault();
+							save();
+						}
+					}}
+				/>
+				<datalist id="note-labels">
+					{#each labels as l (l)}<option value={l}></option>{/each}
+				</datalist>
+			</div>
+			<div class="note-actions">
+				{#if existing}
+					<button class="note-danger" title="Delete note" aria-label="Delete note" onclick={remove}>
+						<Trash2 size={14} aria-hidden="true" /> Delete
+					</button>
+				{/if}
+				<span class="flex-1"></span>
+				<button class="ui-button-quiet" onclick={cancel}>Cancel</button>
+				<button class="note-primary" onclick={save}>
+					<Check size={14} aria-hidden="true" /> Save
+				</button>
+			</div>
+		{:else}
+			<div class="note-body">
+				{#if note.name?.trim() && note.text?.trim()}
+					<p class="note-desc">{note.text}</p>
+				{:else if !note.text?.trim()}
+					<p class="note-desc note-muted">No description</p>
+				{/if}
+				<div class="note-meta">
+					{#if note.label}<span class="note-chip">{note.label}</span>{/if}
+					<span class="note-dot" style="background:{note.color || DEFAULT_NOTE_COLOR}"></span>
+					<span class="truncate">{note.author || 'peer'} · {when(note.ts)}</span>
+				</div>
+			</div>
+			<div class="note-actions">
+				<button class="note-danger" title="Delete note" aria-label="Delete note" onclick={remove}>
+					<Trash2 size={14} aria-hidden="true" /> Delete
+				</button>
+				<span class="flex-1"></span>
+				<button
+					class="note-primary"
+					onclick={() => activeAnnotation.set({ id: note.id, mode: 'edit' })}
+				>
+					<Pencil size={14} aria-hidden="true" /> Edit
+				</button>
+			</div>
+		{/if}
 	</div>
 {/if}
+
+<style>
+	.note-card {
+		position: fixed;
+		/* above the drawers (the docked notes drawer sits at 1000) but below
+		   --z-modal / --z-toast / --z-menu */
+		z-index: 1090;
+		width: min(300px, 92vw);
+		padding: 0;
+		display: flex;
+		flex-direction: column;
+	}
+	.note-head {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		border-bottom: 1px solid rgb(55 65 81 / 0.6);
+		padding: 0.4rem 0.5rem;
+	}
+	.note-num {
+		display: inline-flex;
+		height: 1.15rem;
+		min-width: 1.15rem;
+		align-items: center;
+		justify-content: center;
+		border-radius: 9999px;
+		padding: 0 0.25rem;
+		font-size: 10px;
+		font-weight: 700;
+		color: #1c1917;
+	}
+	.note-title {
+		flex: 1 1 auto;
+		min-width: 0;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+		font-size: 0.8125rem;
+		font-weight: 600;
+		color: rgb(243 244 246);
+	}
+	.note-icon {
+		display: inline-flex;
+		flex: 0 0 auto;
+		align-items: center;
+		justify-content: center;
+		border-radius: 0.25rem;
+		padding: 0.15rem;
+		color: rgb(156 163 175);
+	}
+	.note-icon:hover {
+		background: rgb(55 65 81 / 0.7);
+		color: rgb(243 244 246);
+	}
+	.note-body {
+		display: flex;
+		flex-direction: column;
+		gap: 0.375rem;
+		padding: 0.5rem;
+		min-height: 0;
+		overflow-y: auto;
+	}
+	.note-desc {
+		font-size: 0.8125rem;
+		line-height: 1.35;
+		color: rgb(229 231 235);
+		white-space: pre-wrap;
+		overflow-wrap: anywhere;
+	}
+	.note-muted {
+		color: rgb(107 114 128);
+		font-style: italic;
+	}
+	.note-meta {
+		display: flex;
+		align-items: center;
+		gap: 0.375rem;
+		font-size: 10px;
+		color: rgb(107 114 128);
+	}
+	.note-chip {
+		border-radius: 9999px;
+		background: rgb(55 65 81 / 0.7);
+		padding: 0 0.375rem;
+		color: rgb(209 213 219);
+	}
+	.note-dot {
+		height: 0.5rem;
+		width: 0.5rem;
+		flex: 0 0 auto;
+		border-radius: 9999px;
+	}
+	.note-caption {
+		margin-top: 0.125rem;
+		font-size: 10px;
+		font-weight: 600;
+		letter-spacing: 0.04em;
+		text-transform: uppercase;
+		color: rgb(107 114 128);
+	}
+	.note-swatches {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 0.25rem;
+	}
+	.note-swatch {
+		height: 1.15rem;
+		width: 1.15rem;
+		border-radius: 9999px;
+		border: 2px solid transparent;
+		outline: 1px solid rgb(0 0 0 / 0.35);
+	}
+	.note-swatch.is-on {
+		border-color: rgb(243 244 246);
+	}
+	.note-actions {
+		display: flex;
+		align-items: center;
+		gap: 0.375rem;
+		border-top: 1px solid rgb(55 65 81 / 0.6);
+		padding: 0.4rem 0.5rem;
+	}
+	.note-primary,
+	.note-danger {
+		display: inline-flex;
+		align-items: center;
+		gap: 0.25rem;
+		border-radius: 0.25rem;
+		padding: 0.15rem 0.5rem;
+		font-size: 0.75rem;
+	}
+	.note-primary {
+		background: rgb(249 115 22);
+		color: white;
+	}
+	.note-primary:hover {
+		background: rgb(234 88 12);
+	}
+	.note-danger {
+		color: rgb(248 113 113);
+	}
+	.note-danger:hover {
+		background: rgb(127 29 29 / 0.35);
+	}
+	/* Narrow / folded: a bottom sheet like the Inspector and notes drawer. */
+	.note-card.note-sheet {
+		left: 0;
+		right: 0;
+		bottom: 0;
+		top: auto;
+		width: 100%;
+		max-height: calc(100vh - var(--connect-bottom, 54px) - 56px);
+		border-radius: 0.75rem 0.75rem 0 0;
+	}
+	.note-card.note-sheet .note-body {
+		padding-bottom: var(--controls-inset, 0px);
+	}
+</style>
diff --git a/src/components/menu/NotesDrawer.svelte b/src/components/menu/NotesDrawer.svelte
index 21dd6fad..35335655 100644
--- a/src/components/menu/NotesDrawer.svelte
+++ b/src/components/menu/NotesDrawer.svelte
@@ -3,26 +3,43 @@
 	// Right-docked list of all annotations; a row flies the camera to the pin and
 	// opens its note (openAnnotation), and can be deleted inline. Toggled from the
 	// notes button in the top-right chrome (Users.svelte).
+	// H6 (notes v2): rows are "#n name — description", grouped by LABEL (collapsible,
+	// 'General' first) with per-group ‹ › traversal in GLOBAL pin-number order, plus
+	// a header toggle for the in-scene pins.
+	import { ChevronDown, ChevronRight, ChevronLeft, Pencil, Eye, EyeOff } from '@lucide/svelte';
 	import { notesDrawerOpen, inspectorClose } from '../../stores/appStore.js';
-	import { annotations, openAnnotation, deleteAnnotation } from '$lib/annotationsHandler';
+	import {
+		annotations,
+		activeAnnotation,
+		openAnnotation,
+		deleteAnnotation,
+		displayName,
+		showNotePins,
+		DEFAULT_NOTE_COLOR
+	} from '$lib/annotationsHandler';
 	import { objectsGroup } from '../../stores/sceneStore.js';
 
 	// One bottom sheet at a time on narrow: opening scene notes closes the object/scene
 	// settings sheet (they'd otherwise stack at the bottom).
-	$: if (
-		$notesDrawerOpen &&
-		typeof window !== 'undefined' &&
-		window.matchMedia('(max-width: 640px)').matches
-	)
-		inspectorClose.set(true);
+	$effect(() => {
+		if (
+			$notesDrawerOpen &&
+			typeof window !== 'undefined' &&
+			window.matchMedia('(max-width: 640px)').matches
+		)
+			inspectorClose.set(true);
+	});
 
 	// On a narrow/folded screen the notes drawer is a bottom SHEET (like the Flow/Explorer
 	// bottom dock) with a drag handle to adjust its height — the right-side drawer was
 	// covered by the profile chrome there. On wide screens it stays the right drawer.
-	let sheetH =
+	let stored =
 		typeof localStorage !== 'undefined' ? parseInt(localStorage.getItem('notesSheetH') || '') : NaN;
-	if (!sheetH || Number.isNaN(sheetH))
-		sheetH = Math.round((typeof window !== 'undefined' ? window.innerHeight : 800) * 0.45);
+	let sheetH = $state(
+		!stored || Number.isNaN(stored)
+			? Math.round((typeof window !== 'undefined' ? window.innerHeight : 800) * 0.45)
+			: stored
+	);
 	let resizing = false;
 	/** @param {PointerEvent} e */
 	function startResize(e) {
@@ -64,6 +81,35 @@
 			return '';
 		}
 	}
+
+	// Label groups. Rows carry the GLOBAL 1-based pin number so the drawer and the
+	// in-scene pin labels always agree (never number per group).
+	const groups = $derived.by(() => {
+		/** @type {Map<string, {a: any, n: number}[]>} */
+		const map = new Map();
+		$annotations.forEach((a, i) => {
+			const key = (a.label || '').trim() || 'General';
+			if (!map.has(key)) map.set(key, []);
+			/** @type {any[]} */ (map.get(key)).push({ a, n: i + 1 });
+		});
+		const rest = [...map.keys()].filter((k) => k !== 'General').sort((x, y) => x.localeCompare(y));
+		const order = map.has('General') ? ['General', ...rest] : rest;
+		return order.map((label) => ({ label, rows: /** @type {any[]} */ (map.get(label)) }));
+	});
+
+	/** @type {Record<string, boolean>} */
+	let collapsed = $state({}); // expanded by default
+
+	/** Step through a group's notes in pin order, wrapping @param {any} group @param {number} dir */
+	function step(group, dir) {
+		const rows = group.rows;
+		if (!rows.length) return;
+		const current = $activeAnnotation?.id;
+		const at = rows.findIndex((/** @type {any} */ r) => r.a.id === current);
+		// continue from the open note when it belongs to this group, else start at the end
+		const next = at < 0 ? (dir > 0 ? rows[0] : rows[rows.length - 1]) : rows[(at + dir + rows.length) % rows.length];
+		openAnnotation(next.a.id, 'view');
+	}
 </script>
 
 {#if $notesDrawerOpen}
@@ -80,7 +126,18 @@
 		</div>
 		<div class="ui-panel-header shrink-0 justify-between">
 			<span>Scene notes {#if $annotations.length}<span class="text-xs text-gray-400">({$annotations.length})</span>{/if}</span>
-			<button class="ui-button-quiet" title="Close" aria-label="Close notes" onclick={() => notesDrawerOpen.set(false)}>✕</button>
+			<div class="flex items-center gap-1">
+				<button
+					class="notes-icon"
+					title={$showNotePins ? 'Hide note pins in the viewport' : 'Show note pins in the viewport'}
+					aria-label={$showNotePins ? 'Hide note pins' : 'Show note pins'}
+					aria-pressed={$showNotePins}
+					onclick={() => showNotePins.set(!$showNotePins)}
+				>
+					{#if $showNotePins}<Eye size={15} aria-hidden="true" />{:else}<EyeOff size={15} aria-hidden="true" />{/if}
+				</button>
+				<button class="ui-button-quiet" title="Close" aria-label="Close notes" onclick={() => notesDrawerOpen.set(false)}>✕</button>
+			</div>
 		</div>
 		<div class="notes-body min-h-0 flex-1 overflow-y-auto p-2">
 			{#if !$annotations.length}
@@ -88,31 +145,88 @@
 					No notes yet. Select an object and add a note from its context menu or the object list.
 				</p>
 			{:else}
-				<ul class="flex flex-col gap-1.5">
-					{#each $annotations as a (a.id)}
-						<li class="group rounded-sm bg-gray-800/60 hover:bg-gray-700/60">
-							<div class="flex items-start gap-2 p-2">
-								<button
-									class="min-w-0 flex-1 text-left"
-									title="Fly to this note"
-									onclick={() => openAnnotation(a.id)}
-								>
-									<div class="truncate text-sm text-gray-100">{a.text || '(empty note)'}</div>
-									<div class="mt-0.5 flex items-center gap-1.5 truncate text-[10px] text-gray-500">
-										<span class="rounded-sm bg-gray-700/70 px-1 text-gray-300">{labelFor(a.objectUuid)}</span>
-										<span class="truncate">{a.author || 'peer'} · {when(a.ts)}</span>
-									</div>
-								</button>
-								<button
-									class="shrink-0 text-gray-500 hover:text-red-400"
-									title="Delete note"
-									aria-label="Delete note"
-									onclick={() => deleteAnnotation(a.id)}
-								>✕</button>
-							</div>
-						</li>
-					{/each}
-				</ul>
+				{#each groups as group (group.label)}
+					<div class="notes-group">
+						<div class="notes-group-head">
+							<button
+								class="notes-group-toggle"
+								aria-expanded={!collapsed[group.label]}
+								onclick={() => (collapsed = { ...collapsed, [group.label]: !collapsed[group.label] })}
+							>
+								{#if collapsed[group.label]}
+									<ChevronRight size={14} aria-hidden="true" />
+								{:else}
+									<ChevronDown size={14} aria-hidden="true" />
+								{/if}
+								<span class="truncate">{group.label}</span>
+								<span class="text-gray-500">({group.rows.length})</span>
+							</button>
+							<button
+								class="notes-icon"
+								title="Previous note in this group"
+								aria-label={'Previous note in ' + group.label}
+								onclick={() => step(group, -1)}
+							>
+								<ChevronLeft size={14} aria-hidden="true" />
+							</button>
+							<button
+								class="notes-icon"
+								title="Next note in this group"
+								aria-label={'Next note in ' + group.label}
+								onclick={() => step(group, 1)}
+							>
+								<ChevronRight size={14} aria-hidden="true" />
+							</button>
+						</div>
+						{#if !collapsed[group.label]}
+							<ul class="flex flex-col gap-1.5 pb-1">
+								{#each group.rows as row (row.a.id)}
+									<li
+										class="group rounded-sm bg-gray-800/60 hover:bg-gray-700/60"
+										class:notes-row-active={$activeAnnotation?.id === row.a.id}
+									>
+										<div class="flex items-start gap-2 p-2">
+											<button
+												class="min-w-0 flex-1 text-left"
+												title="Fly to this note"
+												onclick={() => openAnnotation(row.a.id, 'view')}
+											>
+												<div class="flex min-w-0 items-baseline gap-1.5">
+													<span
+														class="notes-num"
+														style="background:{row.a.color || DEFAULT_NOTE_COLOR}">{row.n}</span
+													>
+													<span class="shrink-0 text-sm text-gray-100">{displayName(row.a)}</span>
+													{#if (row.a.name || '').trim() && (row.a.text || '').trim()}
+														<span class="notes-desc">{row.a.text}</span>
+													{/if}
+												</div>
+												<div class="mt-0.5 flex items-center gap-1.5 truncate text-[10px] text-gray-500">
+													<span class="rounded-sm bg-gray-700/70 px-1 text-gray-300">{labelFor(row.a.objectUuid)}</span>
+													<span class="truncate">{row.a.author || 'peer'} · {when(row.a.ts)}</span>
+												</div>
+											</button>
+											<button
+												class="notes-icon shrink-0"
+												title="Edit note"
+												aria-label="Edit note"
+												onclick={() => openAnnotation(row.a.id, 'edit')}
+											>
+												<Pencil size={14} aria-hidden="true" />
+											</button>
+											<button
+												class="shrink-0 text-gray-500 hover:text-red-400"
+												title="Delete note"
+												aria-label="Delete note"
+												onclick={() => deleteAnnotation(row.a.id)}
+											>✕</button>
+										</div>
+									</li>
+								{/each}
+							</ul>
+						{/if}
+					</div>
+				{/each}
 			{/if}
 		</div>
 	</aside>
@@ -155,6 +269,69 @@
 		border-radius: 9999px;
 		background: rgb(148 163 184 / 0.7);
 	}
+	/* --- H6 rows + groups --------------------------------------------------- */
+	.notes-icon {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		border-radius: 0.25rem;
+		padding: 0.15rem;
+		color: rgb(156 163 175);
+	}
+	.notes-icon:hover {
+		background: rgb(55 65 81 / 0.7);
+		color: rgb(243 244 246);
+	}
+	.notes-group + .notes-group {
+		margin-top: 0.5rem;
+	}
+	.notes-group-head {
+		display: flex;
+		align-items: center;
+		gap: 0.125rem;
+		padding: 0.125rem 0.125rem 0.25rem;
+	}
+	.notes-group-toggle {
+		display: flex;
+		min-width: 0;
+		flex: 1 1 auto;
+		align-items: center;
+		gap: 0.25rem;
+		font-size: 10px;
+		font-weight: 600;
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+		color: rgb(156 163 175);
+	}
+	.notes-group-toggle:hover {
+		color: rgb(229 231 235);
+	}
+	.notes-num {
+		display: inline-flex;
+		height: 1rem;
+		min-width: 1rem;
+		flex: 0 0 auto;
+		align-items: center;
+		justify-content: center;
+		border-radius: 9999px;
+		padding: 0 0.2rem;
+		font-size: 9px;
+		font-weight: 700;
+		color: #1c1917;
+	}
+	/* description rides the same line, grey and single-line truncated */
+	.notes-desc {
+		min-width: 0;
+		flex: 1 1 auto;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+		font-size: 0.75rem;
+		color: rgb(156 163 175);
+	}
+	.notes-row-active {
+		outline: 1px solid rgb(249 115 22 / 0.7);
+	}
 	/* Narrow / folded: a bottom sheet (like the Flow/Explorer dock) with a drag handle. */
 	@media (max-width: 640px) {
 		#notes-drawer {
diff --git a/src/lib/annotationsHandler.js b/src/lib/annotationsHandler.js
index b23747b0..94309138 100644
--- a/src/lib/annotationsHandler.js
+++ b/src/lib/annotationsHandler.js
@@ -9,17 +9,70 @@ import { flyTo } from './objectActions';
 // object; one note per pin. Replication mirrors the flow-graph pattern:
 // live CRUD messages + a full-state reply on the connection handshake.
 
-/** @type {import('svelte/store').Writable<{id: string, objectUuid: string, offset: number[], text: string, author: string, ts: number}[]>} */
+/** @type {import('svelte/store').Writable<{id: string, objectUuid: string, offset: number[], text: string, author: string, ts: number, name: string, color: string, label: string}[]>} */
 export const annotations = writable([]);
-/** popover state: { id } for an existing note, { draft: {...} } for a new one, or null */
+/** popover state: { id, mode:'view'|'edit' } for an existing note, { draft: {...} } for a new one, or null */
 /** @type {import('svelte/store').Writable<any>} */
 export const activeAnnotation = writable(null);
 /** the THREE group holding pin meshes, registered by AnnotationPins.svelte */
 /** @type {import('svelte/store').Writable<any>} */
 export const pinsGroup = writable(null);
 
+/** H3: LOCAL pref — pins visible in the viewport (not replicated) */
+export const showNotePins = writable(
+	typeof localStorage === 'undefined' || localStorage.getItem('showNotePins') !== 'false'
+);
+if (typeof localStorage !== 'undefined')
+	showNotePins.subscribe((value) => localStorage.setItem('showNotePins', String(value)));
+
+/** H1/H4: the fixed pin palette (amber first = the historical pin color) */
+export const NOTE_COLORS = [
+	'#f59e0b',
+	'#ef4444',
+	'#ec4899',
+	'#a855f7',
+	'#3b82f6',
+	'#22d3ee',
+	'#22c55e',
+	'#a3e635'
+];
+export const DEFAULT_NOTE_COLOR = NOTE_COLORS[0];
+
 const tempVector = new THREE.Vector3();
 
+/**
+ * H1: ONE boundary normalizer. `text` stays the description (replication,
+ * autosave, sessions and the e2e suites all carry it); v2 adds optional
+ * name/color/label, so payloads from old autosaves, .tpscene sessions and
+ * old-version peers load with defaults for free.
+ * @param {any} a
+ */
+export function normalizeAnnotation(a) {
+	return {
+		...a,
+		text: typeof a?.text === 'string' ? a.text : '',
+		name: typeof a?.name === 'string' ? a.name : '',
+		color: typeof a?.color === 'string' && a.color ? a.color : DEFAULT_NOTE_COLOR,
+		label: typeof a?.label === 'string' ? a.label : ''
+	};
+}
+
+/** 1-based GLOBAL index — MUST match the in-scene pin numbering @param {string} id */
+export function noteNumber(id) {
+	return get(annotations).findIndex((a) => a.id === id) + 1;
+}
+
+/** Row/card title: explicit name, else a trimmed description, else "Note n" @param {any} a */
+export function displayName(a) {
+	if (!a) return '';
+	const name = (a.name || '').trim();
+	if (name) return name;
+	const text = (a.text || '').trim().replace(/\s+/g, ' ');
+	if (text) return text.length > 40 ? text.slice(0, 40) + '…' : text;
+	const n = noteNumber(a.id);
+	return 'Note ' + (n > 0 ? n : '');
+}
+
 /** @param {string} uuid */
 function objectOf(uuid) {
 	// system/environment objects live at the scene root (annotatable per 87)
@@ -38,16 +91,17 @@ function broadcast(data) {
 
 /** Create/update locally and replicate @param {any} annotation */
 export function setAnnotation(annotation) {
+	const normalized = normalizeAnnotation(annotation);
 	annotations.update((list) => {
-		const index = list.findIndex((a) => a.id === annotation.id);
+		const index = list.findIndex((a) => a.id === normalized.id);
 		if (index >= 0) {
 			const next = [...list];
-			next[index] = annotation;
+			next[index] = normalized;
 			return next;
 		}
-		return [...list, annotation];
+		return [...list, normalized];
 	});
-	broadcast({ type: 'annotation', op: 'set', annotation });
+	broadcast({ type: 'annotation', op: 'set', annotation: normalized });
 }
 
 /** @param {string} id */
@@ -63,14 +117,15 @@ export function applyAnnotation(data) {
 		annotations.update((list) => list.filter((a) => a.id !== data.annotation.id));
 		activeAnnotation.update((active) => (active?.id === data.annotation.id ? null : active));
 	} else {
+		const normalized = normalizeAnnotation(data.annotation);
 		annotations.update((list) => {
-			const index = list.findIndex((a) => a.id === data.annotation.id);
+			const index = list.findIndex((a) => a.id === normalized.id);
 			if (index >= 0) {
 				const next = [...list];
-				next[index] = data.annotation;
+				next[index] = normalized;
 				return next;
 			}
-			return [...list, data.annotation];
+			return [...list, normalized];
 		});
 	}
 }
@@ -122,22 +177,28 @@ export function addAnnotation(uuid, worldPoint = null) {
 	/** @type {any} */
 	const peer = get(peers);
 	activeAnnotation.set({
-		draft: {
+		draft: normalizeAnnotation({
 			id: crypto.randomUUID(),
 			objectUuid: object.uuid,
 			offset,
 			text: '',
 			author: get(username) || peer?.peer?.id || 'me',
 			ts: Date.now()
-		}
+		})
 	});
 }
 
-/** Focus the camera on a pin and open its note @param {string} id */
-export function openAnnotation(id) {
+/**
+ * Focus the camera on a pin and open its note. `mode` picks the popover face
+ * (a bare `{id}` keeps meaning view, for back-compat).
+ * NOTE: `flyTo` bails in VR/spectator and the popover is DOM (invisible
+ * in-headset), so this degrades to a no-visible-change there.
+ * @param {string} id @param {'view'|'edit'=} mode
+ */
+export function openAnnotation(id, mode = 'view') {
 	const annotation = get(annotations).find((a) => a.id === id);
 	if (!annotation) return;
-	activeAnnotation.set({ id });
+	activeAnnotation.set({ id, mode });
 	const object = objectOf(annotation.objectUuid);
 	/** @type {any} */
 	const camera = get(globalCamera);
@@ -151,10 +212,18 @@ export function openAnnotation(id) {
 	}
 }
 
-/** World position of a pin right now (for the popover projection) @param {string} id */
-export function annotationWorldPosition(id) {
-	const annotation = get(annotations).find((a) => a.id === id);
-	if (!annotation) return null;
+/**
+ * World position of a pin right now (drives the popover's projection loop).
+ * Accepts a stored note id OR a draft-shaped object (`{objectUuid, offset}`),
+ * so a not-yet-saved note anchors at the clicked point too.
+ * @param {string | any} idOrAnnotation
+ */
+export function annotationWorldPosition(idOrAnnotation) {
+	const annotation =
+		typeof idOrAnnotation === 'string'
+			? get(annotations).find((a) => a.id === idOrAnnotation)
+			: idOrAnnotation;
+	if (!annotation?.objectUuid || !Array.isArray(annotation.offset)) return null;
 	const object = objectOf(annotation.objectUuid);
 	if (!object) return null;
 	return object.localToWorld(new THREE.Vector3().fromArray(annotation.offset));
@@ -177,5 +246,5 @@ objectsGroup.subscribe(() => {
 // persist with the autosave snapshot
 registerAnnotationsPersistence(
 	() => get(annotations),
-	(list) => annotations.set(list)
+	(list) => annotations.set((Array.isArray(list) ? list : []).map(normalizeAnnotation))
 );
diff --git a/tests/e2e/notes-v2.test.cjs b/tests/e2e/notes-v2.test.cjs
new file mode 100644
index 00000000..c8727761
--- /dev/null
+++ b/tests/e2e/notes-v2.test.cjs
@@ -0,0 +1,410 @@
+// 15-H (scene notes v2): the name/description/color/label model, the near-pin
+// view+edit popover, and the drawer's label groups / traversal / pins toggle.
+//
+// Replication is asserted BOTH ways without the signaling cloud: a send spy for
+// the outgoing `{type:'annotation'}` payload and the real applier
+// (annotationsHandler.applyAnnotation / applyAnnotationsSnapshot) for the receive
+// path. A true two-peer pass runs with TWO_PEER=1 (the hosts mapping is commented
+// out locally, so it is env-gated like connect-states).
+const h = require('./helpers.cjs');
+
+const store = (page) =>
+	page.evaluate(
+		() => new Promise((r) => window.__stores.annotationsHandler.annotations.subscribe(r)())
+	);
+
+const active = (page) =>
+	page.evaluate(
+		() => new Promise((r) => window.__stores.annotationsHandler.activeAnnotation.subscribe(r)())
+	);
+
+// commit a note on `uuid` with v2 fields; returns its id
+const addNote = (page, uuid, offset, fields) =>
+	page.evaluate(
+		({ uuid, offset, fields }) => {
+			const ah = window.__stores.annotationsHandler;
+			ah.addAnnotation(uuid, offset);
+			let cur = null;
+			ah.activeAnnotation.subscribe((a) => (cur = a))();
+			if (!cur?.draft) return null;
+			ah.setAnnotation({ ...cur.draft, ...fields });
+			ah.activeAnnotation.set(null);
+			return cur.draft.id;
+		},
+		{ uuid, offset, fields }
+	);
+
+// screen pixel of a pin (or draft) right now
+const pinPixel = (page, idOrDraft) =>
+	page.evaluate(
+		(anchor) =>
+			new Promise((resolve) => {
+				const ah = window.__stores.annotationsHandler;
+				window.__stores.globalCamera.subscribe((camera) => {
+					window.__stores.globalRenderer.subscribe((renderer) => {
+						const world = ah.annotationWorldPosition(anchor);
+						if (!world || !camera || !renderer?.domElement) return resolve(null);
+						const v = world.clone().project(camera);
+						const rect = renderer.domElement.getBoundingClientRect();
+						resolve({
+							x: rect.left + ((v.x + 1) / 2) * rect.width,
+							y: rect.top + ((1 - v.y) / 2) * rect.height,
+							behind: v.z >= 1
+						});
+					})();
+				})();
+			}),
+		idOrDraft
+	);
+
+const pinColor = (page, id) =>
+	page.evaluate(
+		(id) =>
+			new Promise((resolve) => {
+				window.__stores.annotationsHandler.pinsGroup.subscribe((group) => {
+					const pin = group?.getObjectByName('pin-' + id);
+					if (!pin) return resolve(null);
+					let hex = null;
+					pin.traverse((node) => {
+						if (!hex && node.isMesh && node.material?.color)
+							hex = '#' + node.material.color.getHexString();
+					});
+					resolve(hex);
+				})();
+			}),
+		id
+	);
+
+h.run(async () => {
+	const browser = await h.launch();
+	const A = await h.setupPage(browser, 'A', { context: { viewport: { width: 1280, height: 800 } } });
+
+	// --- H1: legacy payloads normalize at the store boundary -----------------
+	const legacy = await A.page.evaluate(() => {
+		const ah = window.__stores.annotationsHandler;
+		ah.applyAnnotationsSnapshot([
+			{
+				id: 'legacy-note',
+				objectUuid: 'nobody',
+				offset: [0, 0, 0],
+				text: 'from an old autosave',
+				author: 'old peer',
+				ts: 1
+			}
+		]);
+		let list = [];
+		ah.annotations.subscribe((l) => (list = l))();
+		const a = list.find((x) => x.id === 'legacy-note');
+		return a ? { name: a.name, color: a.color, label: a.label, text: a.text } : null;
+	});
+	h.check(
+		legacy &&
+			legacy.name === '' &&
+			legacy.label === '' &&
+			legacy.color === '#f59e0b' &&
+			legacy.text === 'from an old autosave',
+		'H1: an old-shape note loads with name/label defaults + the amber default color'
+	);
+	// the orphan prune drops it (no such object) — clear explicitly so numbering is clean
+	await A.page.evaluate(() => window.__stores.annotationsHandler.annotations.set([]));
+
+	// --- scene: one box, three notes -----------------------------------------
+	const boxUuid = await A.page.evaluate(() => {
+		const s = window.__stores;
+		s.commandsHandler.sceneCommand('/create box');
+		let g;
+		s.objectsGroup.subscribe((x) => (g = x))();
+		const box = g.children[g.children.length - 1];
+		box.position.set(0, 0.5, 0);
+		box.updateMatrixWorld(true);
+		return box.uuid;
+	});
+	const id1 = await addNote(A.page, boxUuid, [0.6, 1.2, 0], {
+		name: 'Hinge',
+		text: 'this corner needs a hinge',
+		label: 'mechanics',
+		color: '#22c55e'
+	});
+	const id2 = await addNote(A.page, boxUuid, [-0.6, 1.2, 0], { text: 'unlabeled thought' });
+	const id3 = await addNote(A.page, boxUuid, [0, 1.6, 0.5], {
+		name: 'Motor',
+		text: 'motor mounts here',
+		label: 'mechanics'
+	});
+	h.check(!!(id1 && id2 && id3), 'setup: three notes committed');
+
+	// --- H4: the pin takes the note color -------------------------------------
+	await A.page.waitForTimeout(400);
+	h.check((await pinColor(A.page, id1)) === '#22c55e', 'H4: pin material uses the note color');
+	h.check(
+		(await pinColor(A.page, id2)) === '#f59e0b',
+		'H4: a note with no explicit color keeps the amber default pin'
+	);
+
+	// --- H2/H5: the popover opens ANCHORED near its pin, in VIEW mode ---------
+	await A.page.evaluate((id) => window.__stores.annotationsHandler.openAnnotation(id), id1);
+	await A.page.waitForTimeout(900); // let the 400ms fly settle
+	const viewCard = A.page.locator('[role="dialog"][aria-label="Note"]');
+	h.check(await viewCard.first().isVisible(), 'H2: pin open lands on the VIEW face');
+	const box1 = await viewCard.first().boundingBox();
+	const pix1 = await pinPixel(A.page, id1);
+	// the card sits beside the pin on whichever side fits (it flips near an edge)
+	const gap = (b, p) => Math.min(Math.abs(b.x - p.x), Math.abs(b.x + b.width - p.x));
+	h.check(
+		!!box1 && !!pix1 && gap(box1, pix1) < 60 && Math.abs(box1.y - pix1.y) < 140,
+		`H5: the card sits next to the projected pin (card ${box1 && Math.round(box1.x)},${
+			box1 && Math.round(box1.y)
+		} vs pin ${pix1 && Math.round(pix1.x)},${pix1 && Math.round(pix1.y)})`
+	);
+	h.check(
+		!!box1 && box1.x + box1.width < 1280 - 4 && box1.y > 4,
+		'H5: the card stays inside the viewport'
+	);
+	// it RIDES its anchor: move the owner object and the card follows the pin
+	// (the object, not the camera — OrbitControls.update() re-derives the camera
+	// pose from its own spherical state every frame and would revert a direct write)
+	await A.page.evaluate((uuid) => {
+		let g;
+		window.__stores.objectsGroup.subscribe((x) => (g = x))();
+		const box = g.getObjectByProperty('uuid', uuid);
+		box.position.x += 2.5;
+		box.updateMatrixWorld(true);
+	}, boxUuid);
+	await A.page.waitForTimeout(400);
+	const box1b = await viewCard.first().boundingBox();
+	const pix1b = await pinPixel(A.page, id1);
+	h.check(
+		!!box1b && !!pix1b && gap(box1b, pix1b) < 60 && Math.abs(box1b.y - pix1b.y) < 140,
+		'H5: the card re-anchors as its pin moves (projection loop)'
+	);
+	// the edge facing the pin travelled with it (the card flips sides near an edge,
+	// so compare the NEAR edge, not the left one)
+	const nearEdge = (b, p) =>
+		Math.abs(b.x - p.x) < Math.abs(b.x + b.width - p.x) ? b.x : b.x + b.width;
+	h.check(
+		!!box1 && !!box1b && Math.abs(nearEdge(box1, pix1) - nearEdge(box1b, pix1b)) > 200,
+		`H5: it actually moved (not a fixed top-right card): card edge ${
+			box1 && Math.round(nearEdge(box1, pix1))
+		} -> ${box1b && Math.round(nearEdge(box1b, pix1b))}, pin ${pix1 && Math.round(pix1.x)} -> ${
+			pix1b && Math.round(pix1b.x)
+		}`
+	);
+	// the view card shows the description + the label chip
+	const viewText = (await viewCard.first().textContent()) || '';
+	h.check(
+		viewText.includes('Hinge') && viewText.includes('this corner needs a hinge') && viewText.includes('mechanics'),
+		'H5: the view card shows name, description and label'
+	);
+
+	// --- H5: edit face saves name/color/label and replicates -------------------
+	await A.page.evaluate(() => {
+		let original;
+		window.__stores.peers.subscribe((p) => (original = p))();
+		window.__peerOriginal = original;
+		window.__sent = [];
+		window.__stores.peers.set({ ...original, send: (m) => window.__sent.push(m) });
+	});
+	await A.page.evaluate(
+		(id) => window.__stores.annotationsHandler.openAnnotation(id, 'edit'),
+		id2
+	);
+	await A.page.waitForTimeout(700);
+	const editCard = A.page.locator('[role="dialog"][aria-label="Edit note"]');
+	h.check(await editCard.first().isVisible(), 'H2: openAnnotation(id, "edit") opens the EDIT face');
+	await editCard.locator('input[placeholder="Name (optional)"]').fill('Latch');
+	await editCard.locator('button[aria-label="Pin color #3b82f6"]').click();
+	await editCard.locator('input[list="note-labels"]').fill('review');
+	await editCard.getByRole('button', { name: 'Save' }).click();
+	await A.page.waitForTimeout(400);
+	const saved = (await store(A.page)).find((a) => a.id === id2);
+	h.check(
+		saved && saved.name === 'Latch' && saved.color === '#3b82f6' && saved.label === 'review' && saved.text === 'unlabeled thought',
+		'H5: Save writes name + color + label and keeps the description'
+	);
+	const sent = await A.page.evaluate(() => {
+		const list = window.__sent.filter((m) => m.type === 'annotation');
+		window.__stores.peers.set(window.__peerOriginal);
+		return list;
+	});
+	const sentNote = sent.find((m) => m.annotation?.id === id2)?.annotation;
+	h.check(
+		!!sentNote && sentNote.name === 'Latch' && sentNote.color === '#3b82f6' && sentNote.label === 'review',
+		'H5: the save replicates the v2 fields on the unchanged {type:"annotation"} wire shape'
+	);
+	h.check(
+		(await active(A.page))?.mode === 'view',
+		'H5: saving returns the card to its view face'
+	);
+	h.check((await pinColor(A.page, id2)) === '#3b82f6', 'H4: the pin re-colors after the edit');
+
+	// receive path: a peer's v2 payload lands normalized
+	const remote = await A.page.evaluate(
+		({ uuid }) => {
+			const ah = window.__stores.annotationsHandler;
+			ah.applyAnnotation({
+				op: 'set',
+				annotation: {
+					id: 'remote-note',
+					objectUuid: uuid,
+					offset: [0, 1.9, 0],
+					text: 'from a peer',
+					author: 'B',
+					ts: 2,
+					name: 'Peer note',
+					color: '#a855f7',
+					label: 'review'
+				}
+			});
+			let list = [];
+			ah.annotations.subscribe((l) => (list = l))();
+			const a = list.find((x) => x.id === 'remote-note');
+			return a ? { name: a.name, color: a.color, label: a.label } : null;
+		},
+		{ uuid: boxUuid }
+	);
+	h.check(
+		remote && remote.name === 'Peer note' && remote.color === '#a855f7' && remote.label === 'review',
+		'H1: a peer note applies with its v2 fields intact'
+	);
+	await A.page.evaluate(() => {
+		const ah = window.__stores.annotationsHandler;
+		ah.applyAnnotation({ op: 'delete', annotation: { id: 'remote-note' } });
+		ah.activeAnnotation.set(null);
+	});
+
+	// --- H5: a draft opens at the CLICKED point ------------------------------
+	await A.page.evaluate((uuid) => {
+		window.__stores.annotationsHandler.addAnnotation(uuid, [1.4, 2.2, 0.4]);
+	}, boxUuid);
+	await A.page.waitForTimeout(500);
+	h.check(await editCard.first().isVisible(), 'H5: a draft opens straight on the edit face');
+	const draft = await active(A.page);
+	const draftBox = await editCard.first().boundingBox();
+	const draftPix = await pinPixel(A.page, draft?.draft);
+	h.check(
+		!!draftBox && !!draftPix && gap(draftBox, draftPix) < 60 && Math.abs(draftBox.y - draftPix.y) < 160,
+		`H5: the new-note card opens at the clicked point (card ${draftBox && Math.round(draftBox.x)}-${
+			draftBox && Math.round(draftBox.x + draftBox.width)
+		} vs point ${draftPix && Math.round(draftPix.x)},${draftPix && Math.round(draftPix.y)})`
+	);
+	await A.page.evaluate(() => window.__stores.annotationsHandler.activeAnnotation.set(null));
+
+	// --- H6: drawer groups, numbering, traversal, pins toggle ----------------
+	// a fourth, UNLABELED note so the 'General' group exists
+	const id4 = await addNote(A.page, boxUuid, [-0.4, 1.8, -0.4], { text: 'general remark' });
+	await A.page.evaluate(() => window.__stores.notesDrawerOpen.set(true));
+	await A.page.waitForTimeout(400);
+	const drawer = A.page.locator('#notes-drawer');
+	h.check(await drawer.isVisible(), 'H6: the notes drawer opens');
+	const groupOrder = await drawer.evaluate((el) =>
+		[...el.querySelectorAll('.notes-group-toggle')].map((b) => b.textContent.trim().split(/\s+/)[0])
+	);
+	h.check(
+		groupOrder[0] === 'General',
+		`H6: 'General' (unlabeled) is the FIRST group (got "${groupOrder.join(', ')}")`
+	);
+	h.check(
+		groupOrder.join(',') === 'General,mechanics,review',
+		`H6: label groups render, alphabetical after General (${groupOrder.join(', ')})`
+	);
+	// numbering: every row's badge equals the note's GLOBAL 1-based index (= pin label)
+	const numbering = await drawer.evaluate((el) => {
+		const rows = [...el.querySelectorAll('li')];
+		return rows.map((li) => ({
+			n: li.querySelector('.notes-num')?.textContent?.trim(),
+			text: li.textContent
+		}));
+	});
+	const list = await store(A.page);
+	const numberingOk = numbering.every((row) => {
+		const index = list.findIndex((a) => row.text.includes(a.name || a.text));
+		return index >= 0 && row.n === String(index + 1);
+	});
+	h.check(
+		numbering.length === list.length && numberingOk,
+		`H6: row numbers match the GLOBAL pin numbering (${numbering.map((r) => r.n).join(',')})`
+	);
+	// a row click opens the VIEW face; the per-row Edit button opens the EDIT face
+	await drawer.locator('li', { hasText: 'Latch' }).first().locator('button').first().click();
+	await A.page.waitForTimeout(600);
+	h.check(
+		(await active(A.page))?.id === id2 && (await active(A.page))?.mode === 'view',
+		'H6: a row click flies to the note and opens the view face'
+	);
+	await drawer.locator('li', { hasText: 'Latch' }).first().locator('button[aria-label="Edit note"]').click();
+	await A.page.waitForTimeout(400);
+	h.check(
+		(await active(A.page))?.mode === 'edit',
+		'H6: the per-row Edit button opens the edit face'
+	);
+	await A.page.evaluate(() => window.__stores.annotationsHandler.activeAnnotation.set(null));
+
+	// group arrows walk that group's notes in pin order, wrapping
+	const seq = [];
+	for (let i = 0; i < 3; i++) {
+		await drawer.locator('button[aria-label="Next note in mechanics"]').click();
+		await A.page.waitForTimeout(350);
+		seq.push((await active(A.page))?.id);
+	}
+	h.check(
+		seq[0] === id1 && seq[1] === id3 && seq[2] === id1,
+		'H6: the group › arrow traverses in pin order and WRAPS'
+	);
+	await drawer.locator('button[aria-label="Previous note in mechanics"]').click();
+	await A.page.waitForTimeout(350);
+	h.check((await active(A.page))?.id === id3, 'H6: the ‹ arrow steps back (wrapping)');
+
+	// collapse a group: its two rows disappear, the others stay
+	const rowsBefore = await drawer.locator('li').count();
+	await drawer.locator('.notes-group-toggle', { hasText: 'mechanics' }).click();
+	await A.page.waitForTimeout(250);
+	const rowsAfter = await drawer.locator('li').count();
+	h.check(
+		rowsBefore === 4 && rowsAfter === 2,
+		`H6: a label group collapses its rows (${rowsBefore} -> ${rowsAfter})`
+	);
+
+	// header pins toggle: hides the pin meshes AND the pin-click raycast branch
+	await drawer.locator('button[aria-label="Hide note pins"]').click();
+	await A.page.waitForTimeout(300);
+	const hidden = await A.page.evaluate(
+		() =>
+			new Promise((r) => {
+				const ah = window.__stores.annotationsHandler;
+				let visible = null;
+				ah.pinsGroup.subscribe((g) => (visible = g?.visible))();
+				ah.showNotePins.subscribe((v) => r({ visible, pref: v }))();
+			})
+	);
+	h.check(
+		hidden.visible === false && hidden.pref === false,
+		'H3: the header toggle hides the pins group and flips the local pref'
+	);
+	await drawer.locator('button[aria-label="Show note pins"]').click();
+	await A.page.waitForTimeout(300);
+	const shown = await A.page.evaluate(
+		() =>
+			new Promise((r) => {
+				let visible = null;
+				window.__stores.annotationsHandler.pinsGroup.subscribe((g) => (visible = g?.visible))();
+				r(visible);
+			})
+	);
+	h.check(shown === true, 'H3: toggling back shows the pins again');
+
+	// --- two-peer (opt-in): A's fields arrive on B ----------------------------
+	if (process.env.TWO_PEER === '1') {
+		const B = await h.setupPage(browser, 'B');
+		await h.connect(B, A);
+		const onB = await store(B.page);
+		const mirrored = onB.find((a) => a.id === id1);
+		h.check(
+			!!mirrored && mirrored.name === 'Hinge' && mirrored.color === '#22c55e' && mirrored.label === 'mechanics',
+			'H1/H5 two-peer: the handshake carries name/color/label to a late joiner'
+		);
+	} else {
+		console.log('SKIP two-peer section (set TWO_PEER=1 with the hosts mapping enabled)');
+	}
+
+	await h.finish(browser);
+});

From 7f3572dde286039daad00b75c21a0c289d672f87 Mon Sep 17 00:00:00 2001
From: AlexZ005 <alexz005.info@gmail.com>
Date: Wed, 5 Aug 2026 14:02:42 +0300
Subject: [PATCH 2/8] [feat] notes v2 follow-ups: pin shapes + occlusion dim,
 author identity, persistence fixes

User feedback on the shipped v2 (H8-H10, H12 of the plan; H11 saved-camera/follow
stays for the user to implement).

- H8 pin render pass rework. Every pin now draws TWICE: a depth-tested SOLID pass
  and a depth-test-off GHOST pass at 0.3 opacity, with explicit renderOrders
  (ghost UNDER solid, so a visible pin reads as its own saturated colour instead
  of the ghost border bleeding through the fill). Occluded = dim silhouette, not
  gone and not punching through at full strength. The old single pass was
  depthTest:false with NO renderOrder, so "does this pin draw over that object"
  depended on scene ADD order - that is why your own new pins floated on top
  while the ones received from a peer (objects added after the pins group) were
  covered. The number is one pass, never depth-tested, above every pin mesh, so
  an overlapping neighbour can no longer hide it.
  Two traps worth remembering: the solid pass must WRITE depth (the outline/N8AO
  postprocessing passes read the depth buffer, so a pin that writes none gets the
  AO and selection edges of whatever is behind it painted across its face), and
  the visuals sit 0.06 along the group's local +Z (= toward the viewer after
  lookAt) so a pin anchored flat ON a surface no longer half-sinks into it - the
  pin GROUP itself stays exactly on the anchor, which annotationWorldPosition and
  the anchor suite read.
- H9 pin shapes + a professional look: replicated `shape` (round/star/square,
  shared geometry per shape), a border ring in a darker shade of the note colour,
  slight fill transparency, and a contrast-aware number (YIQ split, so amber and
  green get dark ink, blue and violet get light). Shape selector sits next to the
  colour swatches in the edit face. Colour math runs on sRGB bytes, never through
  THREE.Color (the linear round-trip darkens hexes).
- H10 author identity. `author` stays the DISPLAY name at save time (never the
  literal 'me' any more), and a new `authorKey` - a stable per-device key - says
  whether a note is ours. Peer ids are re-issued on every reconnect and nicknames
  change, so neither could answer that across a rename or a reload. 'Me' is now
  purely a display mapping: a saved .tpscene/autosave shows the owner's nickname
  to everyone else, and renaming yourself re-stamps your own notes on the next
  save. Old notes with no key fall back to the name/peer-id comparison.
- H12 persistence ("some notes disappear on reload"). Three causes fixed:
  annotations were snapshot passengers but never marked the autosave DIRTY (only
  objectsGroup/flowGraphs did), so a note added after the last object change was
  never written; a note anchored on a SCENE-ROOT object (env rig, module content)
  orphaned every boot because those are rebuilt with fresh uuids - notes now
  remember the anchor NAME and re-key in the sweep; and the orphan prune fired
  instantly, so a restore/regeneration race could eat notes - it now needs the
  object to stay missing for 3s, re-arming its own follow-up sweep.
- notes-v2 extended to 51 checks: two-pass structure + renderOrder + always-on-top
  number, shape geometry/border/ink and shape replication, the whole author story
  (stored vs displayed, rename upgrade, foreign-device view), autosave dirty +
  snapshot content, scene-root re-key, prune grace. annotation-anchor and
  autosave-object-flows stay green; build green; svelte-check holds 419/62.
  roadmap-13-notifications-notes' unread-badge check fails identically on HEAD
  (known flake, proven by stashing).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/components/AnnotationPins.svelte         | 161 +++++++++-
 src/components/menu/AnnotationPopover.svelte |  61 +++-
 src/components/menu/NotesDrawer.svelte       |   3 +-
 src/lib/annotationsHandler.js                | 204 ++++++++++++-
 src/lib/autosave.js                          |  16 +
 tests/e2e/notes-v2.test.cjs                  | 300 ++++++++++++++++++-
 6 files changed, 709 insertions(+), 36 deletions(-)

diff --git a/src/components/AnnotationPins.svelte b/src/components/AnnotationPins.svelte
index 9f00d4eb..4509967f 100644
--- a/src/components/AnnotationPins.svelte
+++ b/src/components/AnnotationPins.svelte
@@ -3,11 +3,32 @@
 	import { T, useTask, useThrelte } from '@threlte/core'
 	// @ts-ignore - Text typing clashes with verbatimModuleSyntax
 	import { Text } from '@threlte/extras'
-	import { annotations, pinsGroup, showNotePins, DEFAULT_NOTE_COLOR } from '$lib/annotationsHandler'
+	import {
+		annotations,
+		pinsGroup,
+		showNotePins,
+		DEFAULT_NOTE_COLOR,
+		shadeHex,
+		contrastOn
+	} from '$lib/annotationsHandler'
 	import { objectsGroup, globalScene } from '../stores/sceneStore'
 
 	// Billboarded note pins. Each pin re-anchors to its object every frame
 	// (objects move) and faces the camera.
+	//
+	// H8 (notes v2 follow-up): every pin draws TWICE. The SOLID pass is
+	// depth-tested, so scene geometry hides it; the GHOST pass skips the depth
+	// test at a low opacity, so a pin behind an object stays findable as a dim
+	// silhouette instead of either vanishing or punching through at full strength.
+	// The old single pass was `depthTest: false` with NO renderOrder, which made
+	// "does this pin draw over that object" depend on scene ADD ORDER — that is
+	// why your own new pins floated on top while the ones a late joiner received
+	// (objects added after the pins group) were covered.
+	// The NUMBER is one pass, never depth-tested, on top of every pin mesh: it is
+	// the pin's identity, so it must stay readable even when a neighbouring pin
+	// overlaps it (H8 item: "number should passthrough always").
+	//
+	// H9: shape (round/star/square) + a darker border ring + contrast-aware ink.
 
 	const { camera } = useThrelte()
 
@@ -18,6 +39,64 @@
 	const local = new THREE.Vector3()
 	const cameraPosition = new THREE.Vector3()
 
+	// --- H9 shape geometries (shared instances: one per shape, not per pin) ------
+	const RADIUS = 0.16
+	/** the border is the SAME shape scaled up behind the fill — works for all three */
+	const BORDER_SCALE = 1.2
+	const SOLID_OPACITY = 0.95
+	const GHOST_OPACITY = 0.3
+	// The GHOST pass draws FIRST (lower renderOrder) and the depth-tested SOLID pass
+	// paints over it: a visible pin then reads as its own saturated colour instead of
+	// the ghost's darker border bleeding up through the fill, while an occluded pin
+	// loses the solid pass to the depth test and only the dim ghost survives.
+	const GHOST_BORDER = 870
+	const GHOST_FILL = 871
+	const SOLID_BORDER = 880
+	const SOLID_FILL = 881
+	const NUMBER_ORDER = 910
+
+	function roundedSquare(half: number, radius: number) {
+		const shape = new THREE.Shape()
+		const inner = half - radius
+		shape.moveTo(-inner, -half)
+		shape.lineTo(inner, -half)
+		shape.absarc(inner, -inner, radius, -Math.PI / 2, 0, false)
+		shape.lineTo(half, inner)
+		shape.absarc(inner, inner, radius, 0, Math.PI / 2, false)
+		shape.lineTo(-inner, half)
+		shape.absarc(-inner, inner, radius, Math.PI / 2, Math.PI, false)
+		shape.lineTo(-half, -inner)
+		shape.absarc(-inner, -inner, radius, Math.PI, Math.PI * 1.5, false)
+		return new THREE.ShapeGeometry(shape, 6)
+	}
+
+	function star(outer: number, inner: number, points: number) {
+		const shape = new THREE.Shape()
+		for (let i = 0; i < points * 2; i++) {
+			const r = i % 2 === 0 ? outer : inner
+			const angle = -Math.PI / 2 + (i * Math.PI) / points
+			const x = Math.cos(angle) * r
+			const y = Math.sin(angle) * r
+			if (i === 0) shape.moveTo(x, y)
+			else shape.lineTo(x, y)
+		}
+		shape.closePath()
+		return new THREE.ShapeGeometry(shape, 6)
+	}
+
+	const shapeGeometries: Record<string, any> = {
+		round: new THREE.CircleGeometry(RADIUS, 28),
+		square: roundedSquare(RADIUS * 0.94, RADIUS * 0.3),
+		star: star(RADIUS * 1.32, RADIUS * 0.66, 5)
+	}
+	const geometryFor = (shape: string) => shapeGeometries[shape] ?? shapeGeometries.round
+
+	// ONE shared base material for the numbers: troika derives a per-instance
+	// material from it, so the per-pin `color` still applies (see its material getter)
+	const numberBase = new THREE.MeshBasicMaterial({ depthTest: false, transparent: true })
+
+	const fillOf = (a: any) => a.color || DEFAULT_NOTE_COLOR
+
 	useTask(() => {
 		if (!$showNotePins) return
 		camera.current.getWorldPosition(cameraPosition)
@@ -53,27 +132,91 @@
 <T.Group bind:ref={root} name="annotation-pins" visible={$showNotePins}>
 	{#each $annotations as annotation, index (annotation.id)}
 		<T.Group oncreate={(ref) => (pinRefs[annotation.id] = ref)} name={`pin-${annotation.id}`}>
-			<T.Mesh>
-				<T.CircleGeometry args={[0.16, 20]} />
-				<!-- H4: per-note color; each pin owns its own material instances -->
+			<!-- The pin GROUP stays exactly on the anchor (annotationWorldPosition and
+			     every test read it), while the visuals sit a hair toward the camera along
+			     the group's local +Z — which lookAt points at the viewer. Without it a
+			     pin anchored flat ON a face half-sinks into it as the billboard rotates. -->
+			<T.Group position={[0, 0, 0.06]}>
+			<!-- GHOST pass (no depth test): keeps an occluded pin visible but dim -->
+			<T.Mesh
+				geometry={geometryFor(annotation.shape)}
+				scale={BORDER_SCALE}
+				position={[0, 0, -0.002]}
+				renderOrder={GHOST_BORDER}
+			>
+				<T.MeshBasicMaterial
+					color={shadeHex(fillOf(annotation))}
+					transparent
+					opacity={GHOST_OPACITY}
+					depthTest={false}
+					depthWrite={false}
+					side={THREE.DoubleSide}
+				/>
+			</T.Mesh>
+			<T.Mesh geometry={geometryFor(annotation.shape)} renderOrder={GHOST_FILL}>
+				<T.MeshBasicMaterial
+					color={fillOf(annotation)}
+					transparent
+					opacity={GHOST_OPACITY}
+					depthTest={false}
+					depthWrite={false}
+					side={THREE.DoubleSide}
+				/>
+			</T.Mesh>
+			<T.Mesh position={[0, -0.19, 0]} renderOrder={GHOST_FILL}>
+				<T.ConeGeometry args={[0.05, 0.12, 8]} />
 				<T.MeshBasicMaterial
-					color={annotation.color || DEFAULT_NOTE_COLOR}
+					color={fillOf(annotation)}
+					transparent
+					opacity={GHOST_OPACITY}
 					depthTest={false}
+					depthWrite={false}
+				/>
+			</T.Mesh>
+			<!-- SOLID pass (depth-tested): an object in front of the pin hides this,
+			     leaving only the ghost — that is the "dim, not gone" behaviour -->
+			<!-- depthWrite on purpose: the postprocessing passes (outline, N8AO) read the
+			     depth buffer, so a pin that writes no depth gets the AO and selection
+			     edges of whatever sits BEHIND it painted across its face -->
+			<T.Mesh
+				geometry={geometryFor(annotation.shape)}
+				scale={BORDER_SCALE}
+				position={[0, 0, -0.002]}
+				renderOrder={SOLID_BORDER}
+			>
+				<T.MeshBasicMaterial
+					color={shadeHex(fillOf(annotation))}
+					transparent
+					opacity={SOLID_OPACITY}
+					side={THREE.DoubleSide}
+				/>
+			</T.Mesh>
+			<T.Mesh geometry={geometryFor(annotation.shape)} renderOrder={SOLID_FILL}>
+				<T.MeshBasicMaterial
+					color={fillOf(annotation)}
+					transparent
+					opacity={SOLID_OPACITY}
 					side={THREE.DoubleSide}
 				/>
 			</T.Mesh>
-			<T.Mesh position={[0, -0.19, 0]}>
+			<T.Mesh position={[0, -0.19, 0]} renderOrder={SOLID_FILL}>
 				<T.ConeGeometry args={[0.05, 0.12, 8]} />
-				<T.MeshBasicMaterial color={annotation.color || DEFAULT_NOTE_COLOR} depthTest={false} />
+				<T.MeshBasicMaterial color={fillOf(annotation)} transparent opacity={SOLID_OPACITY} />
 			</T.Mesh>
 			<Text
-				color="#1c1917"
+				color={contrastOn(fillOf(annotation))}
+				outlineColor={contrastOn(fillOf(annotation)) === '#1c1917' ? '#ffffff' : '#000000'}
+				outlineWidth={0.006}
+				outlineOpacity={0.6}
+				material={numberBase}
+				renderOrder={NUMBER_ORDER}
 				fontSize={0.16}
 				anchorX="center"
 				anchorY="middle"
-				position={[0, 0, 0.002]}
+				position={[0, 0, 0.004]}
 				text={String(index + 1)}
 			/>
+			</T.Group>
 		</T.Group>
 	{/each}
 </T.Group>
diff --git a/src/components/menu/AnnotationPopover.svelte b/src/components/menu/AnnotationPopover.svelte
index a2ab33ce..d1255508 100644
--- a/src/components/menu/AnnotationPopover.svelte
+++ b/src/components/menu/AnnotationPopover.svelte
@@ -1,7 +1,7 @@
 <script lang="ts">
 	import { get } from 'svelte/store';
 	import { untrack } from 'svelte';
-	import { Pencil, Trash2, X, Check } from '@lucide/svelte';
+	import { Pencil, Trash2, X, Check, Circle, Star, Square } from '@lucide/svelte';
 	import {
 		annotations,
 		activeAnnotation,
@@ -9,8 +9,13 @@
 		deleteAnnotation,
 		annotationWorldPosition,
 		displayName,
+		displayAuthor,
+		isMyNote,
+		myAuthorName,
+		myAuthorKey,
 		noteNumber,
 		NOTE_COLORS,
+		NOTE_SHAPES,
 		DEFAULT_NOTE_COLOR
 	} from '$lib/annotationsHandler';
 	import { globalCamera, globalRenderer } from '../../stores/sceneStore';
@@ -44,6 +49,7 @@
 	let text = $state('');
 	let color = $state(DEFAULT_NOTE_COLOR);
 	let label = $state('');
+	let shape = $state('round');
 	let seeded = '';
 	$effect(() => {
 		const key = (note?.id ?? '') + ':' + (editing ? 'edit' : 'view');
@@ -55,8 +61,10 @@
 			text = source?.text ?? '';
 			color = source?.color || DEFAULT_NOTE_COLOR;
 			label = source?.label ?? '';
+			shape = source?.shape || 'round';
 		});
 	});
+	const SHAPE_ICONS: Record<string, any> = { round: Circle, star: Star, square: Square };
 
 	let nameInput: HTMLInputElement | null = $state(null);
 	$effect(() => {
@@ -140,13 +148,20 @@
 		const description = text.trim();
 		const title = name.trim();
 		if (!description && !title) return; // nothing to save yet
+		// H10: our OWN note re-stamps the display name (so renaming yourself, or
+		// setting a nickname after creating notes, fixes what everyone else sees) and
+		// gains the stable key if it predates it. Someone else's note keeps its author.
+		const mine = isMyNote(base);
 		// spread the base so fields a newer peer added survive OUR save
 		setAnnotation({
 			...base,
 			name: title,
 			text: description,
 			color,
+			shape,
 			label: label.trim(),
+			author: mine ? myAuthorName() : base.author,
+			authorKey: mine ? myAuthorKey() : base.authorKey,
 			ts: Date.now()
 		});
 		activeAnnotation.set({ id: base.id, mode: 'view' });
@@ -249,6 +264,23 @@
 						></button>
 					{/each}
 				</div>
+				<span class="note-caption">Pin shape</span>
+				<div class="note-shapes" role="group" aria-label="Pin shape">
+					{#each NOTE_SHAPES as s (s)}
+						{@const ShapeIcon = SHAPE_ICONS[s]}
+						<button
+							class="note-shape"
+							class:is-on={shape === s}
+							title={'Pin shape: ' + s}
+							aria-label={'Pin shape ' + s}
+							aria-pressed={shape === s}
+							onclick={() => (shape = s)}
+						>
+							<ShapeIcon size={14} aria-hidden="true" />
+							<span>{s}</span>
+						</button>
+					{/each}
+				</div>
 				<span class="note-caption">Label — groups notes in the drawer</span>
 				<input
 					class="ui-input w-full"
@@ -288,7 +320,7 @@
 				<div class="note-meta">
 					{#if note.label}<span class="note-chip">{note.label}</span>{/if}
 					<span class="note-dot" style="background:{note.color || DEFAULT_NOTE_COLOR}"></span>
-					<span class="truncate">{note.author || 'peer'} · {when(note.ts)}</span>
+					<span class="truncate">{displayAuthor(note)} · {when(note.ts)}</span>
 				</div>
 			</div>
 			<div class="note-actions">
@@ -421,6 +453,31 @@
 	.note-swatch.is-on {
 		border-color: rgb(243 244 246);
 	}
+	.note-shapes {
+		display: flex;
+		gap: 0.25rem;
+	}
+	.note-shape {
+		display: inline-flex;
+		flex: 1 1 0;
+		align-items: center;
+		justify-content: center;
+		gap: 0.25rem;
+		border: 1px solid rgb(75 85 99 / 0.8);
+		border-radius: 0.25rem;
+		padding: 0.15rem 0.25rem;
+		font-size: 10px;
+		text-transform: capitalize;
+		color: rgb(156 163 175);
+	}
+	.note-shape:hover {
+		color: rgb(243 244 246);
+	}
+	.note-shape.is-on {
+		border-color: rgb(249 115 22);
+		background: rgb(249 115 22 / 0.15);
+		color: rgb(243 244 246);
+	}
 	.note-actions {
 		display: flex;
 		align-items: center;
diff --git a/src/components/menu/NotesDrawer.svelte b/src/components/menu/NotesDrawer.svelte
index 35335655..0c900fa5 100644
--- a/src/components/menu/NotesDrawer.svelte
+++ b/src/components/menu/NotesDrawer.svelte
@@ -14,6 +14,7 @@
 		openAnnotation,
 		deleteAnnotation,
 		displayName,
+		displayAuthor,
 		showNotePins,
 		DEFAULT_NOTE_COLOR
 	} from '$lib/annotationsHandler';
@@ -203,7 +204,7 @@
 												</div>
 												<div class="mt-0.5 flex items-center gap-1.5 truncate text-[10px] text-gray-500">
 													<span class="rounded-sm bg-gray-700/70 px-1 text-gray-300">{labelFor(row.a.objectUuid)}</span>
-													<span class="truncate">{row.a.author || 'peer'} · {when(row.a.ts)}</span>
+													<span class="truncate">{displayAuthor(row.a)} · {when(row.a.ts)}</span>
 												</div>
 											</button>
 											<button
diff --git a/src/lib/annotationsHandler.js b/src/lib/annotationsHandler.js
index 94309138..71358506 100644
--- a/src/lib/annotationsHandler.js
+++ b/src/lib/annotationsHandler.js
@@ -2,14 +2,14 @@ import * as THREE from 'three';
 import { writable, get } from 'svelte/store';
 import { objectsGroup, selectedObject, globalCamera, globalScene } from '../stores/sceneStore';
 import { peers, username, showToast } from '../stores/appStore';
-import { registerAnnotationsPersistence } from './autosave';
+import { registerAnnotationsPersistence, markAnnotationsDirty } from './autosave';
 import { flyTo } from './objectActions';
 
 // Synced note pins on objects. Offsets are object-local so pins follow their
 // object; one note per pin. Replication mirrors the flow-graph pattern:
 // live CRUD messages + a full-state reply on the connection handshake.
 
-/** @type {import('svelte/store').Writable<{id: string, objectUuid: string, offset: number[], text: string, author: string, ts: number, name: string, color: string, label: string}[]>} */
+/** @type {import('svelte/store').Writable<{id: string, objectUuid: string, objectName: string, offset: number[], text: string, author: string, authorKey: string, ts: number, name: string, color: string, label: string, shape: string}[]>} */
 export const annotations = writable([]);
 /** popover state: { id, mode:'view'|'edit' } for an existing note, { draft: {...} } for a new one, or null */
 /** @type {import('svelte/store').Writable<any>} */
@@ -25,6 +25,9 @@ export const showNotePins = writable(
 if (typeof localStorage !== 'undefined')
 	showNotePins.subscribe((value) => localStorage.setItem('showNotePins', String(value)));
 
+/** H9: pin shapes (replicated per note; 'round' = the historical pin) */
+export const NOTE_SHAPES = ['round', 'star', 'square'];
+
 /** H1/H4: the fixed pin palette (amber first = the historical pin color) */
 export const NOTE_COLORS = [
 	'#f59e0b',
@@ -53,10 +56,113 @@ export function normalizeAnnotation(a) {
 		text: typeof a?.text === 'string' ? a.text : '',
 		name: typeof a?.name === 'string' ? a.name : '',
 		color: typeof a?.color === 'string' && a.color ? a.color : DEFAULT_NOTE_COLOR,
-		label: typeof a?.label === 'string' ? a.label : ''
+		label: typeof a?.label === 'string' ? a.label : '',
+		shape: NOTE_SHAPES.includes(a?.shape) ? a.shape : 'round',
+		// H10: who wrote it — `author` is the DISPLAY name at save time, `authorKey`
+		// is the writer's stable device key (only they can match it)
+		authorKey: typeof a?.authorKey === 'string' ? a.authorKey : '',
+		// H12: fixed NAME of a SCENE-ROOT anchor (env rig / module content). Those
+		// objects are rebuilt with fresh uuids every boot, so the uuid alone can't
+		// survive a reload — the sweep re-keys by name instead of pruning.
+		objectName: typeof a?.objectName === 'string' ? a.objectName : ''
 	};
 }
 
+// --- H9 color math (sRGB bytes, never through THREE.Color: round-tripping a hex
+// through the LINEAR working space re-darkens it — the documented trap) --------
+
+/** @param {string} hex @returns {[number, number, number]} */
+function rgbOf(hex) {
+	const clean = (hex || '').replace('#', '');
+	const full =
+		clean.length === 3
+			? clean
+					.split('')
+					.map((c) => c + c)
+					.join('')
+			: clean;
+	const value = parseInt(full || '000000', 16);
+	return [(value >> 16) & 255, (value >> 8) & 255, value & 255];
+}
+
+/** A darker shade of `hex` — the pin's border ring @param {string} hex @param {number=} factor */
+export function shadeHex(hex, factor = 0.55) {
+	const [r, g, b] = rgbOf(hex);
+	/** @param {number} v */
+	const to = (v) => Math.max(0, Math.min(255, Math.round(v * factor)));
+	return '#' + [to(r), to(g), to(b)].map((v) => v.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Readable ink for a pin of this fill color — the classic YIQ brightness split
+ * at 0.5 (black on amber/green/lime/cyan, white on blue/red/pink/violet).
+ * @param {string} hex
+ */
+export function contrastOn(hex) {
+	const [r, g, b] = rgbOf(hex);
+	const brightness = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+	return brightness > 0.5 ? '#1c1917' : '#f8fafc';
+}
+
+// --- H10 author identity ------------------------------------------------------
+
+const AUTHOR_KEY = 'noteAuthorKey';
+/** @type {string} */
+let authorKeyCache = '';
+
+/**
+ * A stable per-DEVICE key for "notes I wrote". Peer ids are re-issued on every
+ * reconnect and nicknames change, so neither can answer "is this mine?" across a
+ * rename or a reload — this can. It rides the note (replicated, meaningless to
+ * anyone else) purely so WE can render 'Me' and re-stamp our own display name.
+ */
+export function myAuthorKey() {
+	if (authorKeyCache) return authorKeyCache;
+	try {
+		const stored = localStorage.getItem(AUTHOR_KEY);
+		authorKeyCache = stored || crypto.randomUUID();
+		if (!stored) localStorage.setItem(AUTHOR_KEY, authorKeyCache);
+	} catch {
+		authorKeyCache = 'local';
+	}
+	return authorKeyCache;
+}
+
+/** Our own display name at THIS moment (stored on notes we create) */
+export function myAuthorName() {
+	/** @type {any} */
+	const peer = get(peers);
+	return (get(username) || '').trim() || peer?.peer?.id || 'anonymous';
+}
+
+/** Legacy identity check for notes with no authorKey @param {string} author */
+export function isMyAuthor(author) {
+	const value = (author || '').trim();
+	if (!value) return false;
+	/** @type {any} */
+	const peer = get(peers);
+	const nickname = (get(username) || '').trim();
+	return (!!nickname && value === nickname) || (!!peer?.peer?.id && value === peer.peer.id);
+}
+
+/** Did WE write this note? @param {any} a */
+export function isMyNote(a) {
+	if (!a) return false;
+	if (a.authorKey) return a.authorKey === myAuthorKey();
+	return isMyAuthor(a.author); // pre-authorKey notes fall back to name/peer-id
+}
+
+/**
+ * H10: 'Me' is a DISPLAY-only convenience. The stored author is always a real
+ * nickname (or peer id), so a saved .tpscene/autosave shows the owner's name to
+ * everyone else. @param {any} a
+ */
+export function displayAuthor(a) {
+	const author = (a?.author || '').trim();
+	if (!author) return 'peer';
+	return isMyNote(a) ? 'Me' : author;
+}
+
 /** 1-based GLOBAL index — MUST match the in-scene pin numbering @param {string} id */
 export function noteNumber(id) {
 	return get(annotations).findIndex((a) => a.id === id) + 1;
@@ -174,15 +280,21 @@ export function addAnnotation(uuid, worldPoint = null) {
 	}
 	object.updateMatrixWorld(true);
 	const offset = object.worldToLocal(worldAnchor.clone()).toArray();
-	/** @type {any} */
-	const peer = get(peers);
+	// H12: a SCENE-ROOT anchor (env rig, module content) is rebuilt with a fresh
+	// uuid every boot — remember its fixed name so the note can re-key instead of
+	// being pruned as an orphan.
+	const inObjects = !!get(objectsGroup)?.getObjectByProperty('uuid', object.uuid);
 	activeAnnotation.set({
 		draft: normalizeAnnotation({
 			id: crypto.randomUUID(),
 			objectUuid: object.uuid,
+			objectName: inObjects ? '' : object.name || '',
 			offset,
 			text: '',
-			author: get(username) || peer?.peer?.id || 'me',
+			// H10: never the literal 'me' — the stored author must read correctly
+			// for every peer and for anyone who loads the saved file
+			author: myAuthorName(),
+			authorKey: myAuthorKey(),
 			ts: Date.now()
 		})
 	});
@@ -229,22 +341,82 @@ export function annotationWorldPosition(idOrAnnotation) {
 	return object.localToWorld(new THREE.Vector3().fromArray(annotation.offset));
 }
 
-// pins die with their object (deletion replicates, so every peer prunes the same)
+/**
+ * H12: re-key notes whose SCENE-ROOT anchor came back with a new uuid (env rig /
+ * module content is rebuilt every boot). Local heal — the corrected uuid rides
+ * the next save/edit; peers heal the same way from their own scene.
+ * @returns {number} how many notes were re-keyed
+ */
+export function healAnnotationAnchors() {
+	let healed = 0;
+	annotations.update((list) => {
+		const next = list.map((a) => {
+			if (!a.objectName || objectOf(a.objectUuid)) return a;
+			const found = get(globalScene)?.getObjectByName(a.objectName);
+			if (!found) return a;
+			healed++;
+			return { ...a, objectUuid: found.uuid };
+		});
+		return healed ? next : list;
+	});
+	return healed;
+}
+
+// Pins die with their object (deletion replicates, so every peer prunes the same)
+// — but only after a GRACE window: a restore/regeneration briefly has the note
+// without its object, and pruning inside that gap silently ate notes (H12).
+const PRUNE_GRACE_MS = 3000;
+/** @type {Map<string, number>} */
+const missingSince = new Map();
 let pruneTimer = /** @type {any} */ (null);
-objectsGroup.subscribe(() => {
-	clearTimeout(pruneTimer);
-	pruneTimer = setTimeout(() => {
-		if (!get(objectsGroup)) return;
-		annotations.update((list) => {
+
+/** One heal-then-prune sweep (exported for tests; normally debounced below) */
+export function sweepAnnotations() {
+	if (!get(objectsGroup)) return;
+	healAnnotationAnchors();
+	const now = Date.now();
+	annotations.update((list) => {
+		const kept = list.filter((a) => {
 			// objectOf also sees scene-root system objects (env rig, module content)
-			const kept = list.filter((a) => objectOf(a.objectUuid));
-			return kept.length === list.length ? list : kept;
+			if (objectOf(a.objectUuid)) {
+				missingSince.delete(a.id);
+				return true;
+			}
+			const first = missingSince.get(a.id);
+			if (first === undefined) {
+				missingSince.set(a.id, now);
+				return true;
+			}
+			if (now - first < PRUNE_GRACE_MS) return true;
+			missingSince.delete(a.id);
+			return false;
 		});
-	}, 500);
+		return kept.length === list.length ? list : kept;
+	});
+	// notes still inside the grace window need one more look after it expires —
+	// objectsGroup may never tick again after the delete that orphaned them
+	if (missingSince.size) {
+		clearTimeout(pruneTimer);
+		pruneTimer = setTimeout(sweepAnnotations, PRUNE_GRACE_MS + 100);
+	}
+}
+
+objectsGroup.subscribe(() => {
+	clearTimeout(pruneTimer);
+	pruneTimer = setTimeout(sweepAnnotations, 500);
 });
 
 // persist with the autosave snapshot
 registerAnnotationsPersistence(
 	() => get(annotations),
-	(list) => annotations.set((Array.isArray(list) ? list : []).map(normalizeAnnotation))
+	(list) => {
+		annotations.set((Array.isArray(list) ? list : []).map(normalizeAnnotation));
+		// H12: a restored scene-root anchor has a NEW uuid — re-key before the sweep
+		// gets a chance to call the note an orphan
+		healAnnotationAnchors();
+	}
 );
+
+// H12: any annotation change schedules an autosave (notes were snapshot-only
+// passengers before, so a note added after the last object change was lost)
+annotations.subscribe(() => markAnnotationsDirty());
diff --git a/src/lib/autosave.js b/src/lib/autosave.js
index 6c10c0ca..c2642a8f 100644
--- a/src/lib/autosave.js
+++ b/src/lib/autosave.js
@@ -214,6 +214,22 @@ export function saveNow() {
 	return saveSnapshot();
 }
 
+/**
+ * H12: annotations ride the snapshot but were NOT wired to the dirty tracker —
+ * startAutosave only watched objectsGroup + flowGraphs, so a note added without
+ * touching an object afterwards was never persisted ("some notes disappear on
+ * reload"). annotationsHandler already imports this module for
+ * registerAnnotationsPersistence, so calling in from there adds no import edge.
+ */
+export function markAnnotationsDirty() {
+	markDirty();
+}
+
+/** Is a change waiting to be written? (Settings/tests) */
+export function isDirty() {
+	return dirty;
+}
+
 export async function clearSavedSession() {
 	await idbDelete('latest');
 	dirty = false;
diff --git a/tests/e2e/notes-v2.test.cjs b/tests/e2e/notes-v2.test.cjs
index c8727761..2b960409 100644
--- a/tests/e2e/notes-v2.test.cjs
+++ b/tests/e2e/notes-v2.test.cjs
@@ -1,5 +1,9 @@
 // 15-H (scene notes v2): the name/description/color/label model, the near-pin
 // view+edit popover, and the drawer's label groups / traversal / pins toggle.
+// Follow-up drop (H8-H12): the two-pass pin render (occluded = dim, never an
+// add-order lottery), pin shapes + border + contrast ink, 'Me' as a DISPLAY-only
+// author, and the persistence fixes (autosave dirty on annotation changes,
+// scene-root re-key, prune grace).
 //
 // Replication is asserted BOTH ways without the signaling cloud: a send spy for
 // the outgoing `{type:'annotation'}` payload and the real applier
@@ -57,24 +61,58 @@ const pinPixel = (page, idOrDraft) =>
 		idOrDraft
 	);
 
-const pinColor = (page, id) =>
+// everything the pin's meshes/text tell us about the H8 two-pass render
+const pinInfo = (page, id) =>
 	page.evaluate(
 		(id) =>
 			new Promise((resolve) => {
 				window.__stores.annotationsHandler.pinsGroup.subscribe((group) => {
 					const pin = group?.getObjectByName('pin-' + id);
 					if (!pin) return resolve(null);
-					let hex = null;
+					const meshes = [];
+					let text = null;
 					pin.traverse((node) => {
-						if (!hex && node.isMesh && node.material?.color)
-							hex = '#' + node.material.color.getHexString();
+						if (!node.isMesh) return;
+						// troika Text extends Mesh; its (possibly multi-) material is marked
+						const material = Array.isArray(node.material)
+							? node.material[node.material.length - 1]
+							: node.material;
+						if (material?.isTroikaTextMaterial) {
+							text = {
+								renderOrder: node.renderOrder,
+								depthTest: material.depthTest,
+								value: node.text
+							};
+							return;
+						}
+						if (!material?.color) return;
+						meshes.push({
+							hex: '#' + material.color.getHexString(),
+							depthTest: material.depthTest,
+							depthWrite: material.depthWrite,
+							transparent: material.transparent,
+							opacity: material.opacity,
+							renderOrder: node.renderOrder,
+							verts: node.geometry?.attributes?.position?.count ?? 0
+						});
 					});
-					resolve(hex);
+					resolve({ meshes, text });
 				})();
 			}),
 		id
 	);
 
+// the FILL color of the pin's brightest pass (the note color, not the border)
+const pinColor = async (page, id) => {
+	const info = await pinInfo(page, id);
+	if (!info?.meshes?.length) return null;
+	// the fill passes carry the note color; the border passes are the darker shade
+	const counts = {};
+	for (const m of info.meshes) counts[m.hex] = (counts[m.hex] || 0) + 1;
+	// fill appears on the disc + cone in both passes (4), border only twice
+	return Object.keys(counts).sort((a, b) => counts[b] - counts[a])[0];
+};
+
 h.run(async () => {
 	const browser = await h.launch();
 	const A = await h.setupPage(browser, 'A', { context: { viewport: { width: 1280, height: 800 } } });
@@ -109,8 +147,11 @@ h.run(async () => {
 	await A.page.evaluate(() => window.__stores.annotationsHandler.annotations.set([]));
 
 	// --- scene: one box, three notes -----------------------------------------
+	// a KNOWN nickname first: authorship must not depend on the live peer id (the
+	// signaling box can hand out a new one on a reconnect mid-suite)
 	const boxUuid = await A.page.evaluate(() => {
 		const s = window.__stores;
+		s.username.set('Old Nick');
 		s.commandsHandler.sceneCommand('/create box');
 		let g;
 		s.objectsGroup.subscribe((x) => (g = x))();
@@ -129,7 +170,8 @@ h.run(async () => {
 	const id3 = await addNote(A.page, boxUuid, [0, 1.6, 0.5], {
 		name: 'Motor',
 		text: 'motor mounts here',
-		label: 'mechanics'
+		label: 'mechanics',
+		shape: 'star'
 	});
 	h.check(!!(id1 && id2 && id3), 'setup: three notes committed');
 
@@ -141,6 +183,65 @@ h.run(async () => {
 		'H4: a note with no explicit color keeps the amber default pin'
 	);
 
+	// --- H8: two render passes + an always-on-top number ----------------------
+	const info1 = await pinInfo(A.page, id1);
+	const tested = (info1?.meshes ?? []).filter((m) => m.depthTest);
+	const ghosts = (info1?.meshes ?? []).filter((m) => !m.depthTest);
+	h.check(
+		tested.length >= 2 && ghosts.length >= 2,
+		`H8: the pin draws a depth-tested SOLID pass and a depth-test-off GHOST pass (${tested.length}/${ghosts.length} meshes)`
+	);
+	h.check(
+		ghosts.every((m) => m.transparent && m.opacity < 0.5) &&
+			tested.every((m) => m.transparent && m.opacity > 0.5),
+		`H8: the ghost pass is dim and the solid pass is not (ghost ${ghosts
+			.map((m) => m.opacity)
+			.join('/')} vs solid ${tested.map((m) => m.opacity).join('/')})`
+	);
+	// the SOLID pass paints over the ghost, so a visible pin reads as its own
+	// saturated colour instead of the ghost border bleeding up through the fill
+	h.check(
+		(info1?.meshes ?? []).every((m) => m.renderOrder > 0) &&
+			Math.max(...ghosts.map((m) => m.renderOrder)) <
+				Math.min(...tested.map((m) => m.renderOrder)),
+		'H8: every pin mesh has an explicit renderOrder, ghost under solid (no add-order lottery)'
+	);
+	h.check(
+		!!info1?.text &&
+			info1.text.depthTest === false &&
+			info1.text.renderOrder > Math.max(...(info1.meshes ?? []).map((m) => m.renderOrder)),
+		`H8: the number draws through everything, above every pin mesh (renderOrder ${info1?.text?.renderOrder})`
+	);
+	// an occluded pin keeps its ghost — the report was "new pins show through, received ones do not"
+	const infoLate = await pinInfo(A.page, id2);
+	h.check(
+		(infoLate?.meshes ?? []).some((m) => !m.depthTest) &&
+			(infoLate?.meshes ?? []).some((m) => m.depthTest),
+		'H8: every pin gets both passes, whenever/however it was created'
+	);
+
+	// --- H9: shape geometry + darker border + contrast ink --------------------
+	const roundVerts = (await pinInfo(A.page, id1))?.meshes?.[0]?.verts ?? 0;
+	const starVerts = (await pinInfo(A.page, id3))?.meshes?.[0]?.verts ?? 0;
+	h.check(
+		roundVerts > 0 && starVerts > 0 && roundVerts !== starVerts,
+		`H9: a star pin renders a different geometry than a round one (${roundVerts} vs ${starVerts} verts)`
+	);
+	const border = await A.page.evaluate(() => {
+		const ah = window.__stores.annotationsHandler;
+		return { dark: ah.shadeHex('#22c55e'), inkOnGreen: ah.contrastOn('#22c55e'), inkOnBlue: ah.contrastOn('#3b82f6') };
+	});
+	h.check(
+		border.dark === '#136c34',
+		`H9: the border shade is a darker sRGB shade of the fill (${border.dark})`
+	);
+	h.check(
+		border.inkOnGreen === '#1c1917' && border.inkOnBlue === '#f8fafc',
+		`H9: the number ink is contrast-aware (green -> ${border.inkOnGreen}, blue -> ${border.inkOnBlue})`
+	);
+	const hasBorder = (await pinInfo(A.page, id1))?.meshes?.some((m) => m.hex === border.dark);
+	h.check(!!hasBorder, 'H9: the pin actually renders that darker border shade');
+
 	// --- H2/H5: the popover opens ANCHORED near its pin, in VIEW mode ---------
 	await A.page.evaluate((id) => window.__stores.annotationsHandler.openAnnotation(id), id1);
 	await A.page.waitForTimeout(900); // let the 400ms fly settle
@@ -213,6 +314,7 @@ h.run(async () => {
 	h.check(await editCard.first().isVisible(), 'H2: openAnnotation(id, "edit") opens the EDIT face');
 	await editCard.locator('input[placeholder="Name (optional)"]').fill('Latch');
 	await editCard.locator('button[aria-label="Pin color #3b82f6"]').click();
+	await editCard.locator('button[aria-label="Pin shape square"]').click();
 	await editCard.locator('input[list="note-labels"]').fill('review');
 	await editCard.getByRole('button', { name: 'Save' }).click();
 	await A.page.waitForTimeout(400);
@@ -221,6 +323,7 @@ h.run(async () => {
 		saved && saved.name === 'Latch' && saved.color === '#3b82f6' && saved.label === 'review' && saved.text === 'unlabeled thought',
 		'H5: Save writes name + color + label and keeps the description'
 	);
+	h.check(saved?.shape === 'square', `H9: the shape selector saves the pin shape (${saved?.shape})`);
 	const sent = await A.page.evaluate(() => {
 		const list = window.__sent.filter((m) => m.type === 'annotation');
 		window.__stores.peers.set(window.__peerOriginal);
@@ -228,8 +331,16 @@ h.run(async () => {
 	});
 	const sentNote = sent.find((m) => m.annotation?.id === id2)?.annotation;
 	h.check(
-		!!sentNote && sentNote.name === 'Latch' && sentNote.color === '#3b82f6' && sentNote.label === 'review',
-		'H5: the save replicates the v2 fields on the unchanged {type:"annotation"} wire shape'
+		!!sentNote &&
+			sentNote.name === 'Latch' &&
+			sentNote.color === '#3b82f6' &&
+			sentNote.label === 'review' &&
+			sentNote.shape === 'square',
+		'H5/H9: the save replicates the v2 fields (incl. shape) on the unchanged {type:"annotation"} wire shape'
+	);
+	h.check(
+		sentNote?.author === 'Old Nick',
+		`H10: the REPLICATED author is the real nickname, never the literal 'me' (${sentNote?.author})`
 	);
 	h.check(
 		(await active(A.page))?.mode === 'view',
@@ -266,11 +377,88 @@ h.run(async () => {
 		remote && remote.name === 'Peer note' && remote.color === '#a855f7' && remote.label === 'review',
 		'H1: a peer note applies with its v2 fields intact'
 	);
+
+	// --- H10: 'Me' is display-only; the stored/replicated author is a real name --
+	const cardText = () =>
+		viewCard
+			.first()
+			.textContent()
+			.then((t) => (t || '').replace(/\s+/g, ' ').trim())
+			.catch(() => '');
+	await A.page.evaluate(() => window.__stores.annotationsHandler.openAnnotation('remote-note'));
+	await h.eventually(
+		cardText,
+		(t) => t.includes('Peer note') && t.includes('B') && !t.includes('Me'),
+		"H10: someone else's note shows THEIR author, not 'Me'"
+	);
 	await A.page.evaluate(() => {
 		const ah = window.__stores.annotationsHandler;
 		ah.applyAnnotation({ op: 'delete', annotation: { id: 'remote-note' } });
 		ah.activeAnnotation.set(null);
 	});
+	await A.page.evaluate((id) => window.__stores.annotationsHandler.openAnnotation(id), id1);
+	await h.eventually(
+		cardText,
+		(t) => t.includes('Hinge') && t.includes('Me'),
+		"H10: our own note reads 'Me' in the card"
+	);
+	// ownership rides a stable device key, so it survives renames and reconnects
+	// (peer ids are re-issued; nicknames change) — legacy keyless notes still match
+	// by name
+	const ownership = await A.page.evaluate(() => {
+		const ah = window.__stores.annotationsHandler;
+		return {
+			byKey: ah.isMyNote({ author: 'whoever', authorKey: ah.myAuthorKey() }),
+			foreignKey: ah.isMyNote({ author: 'Old Nick', authorKey: 'someone-elses-key' }),
+			legacyMine: ah.isMyNote({ author: 'Old Nick' }),
+			legacyOther: ah.isMyNote({ author: 'Sam' })
+		};
+	});
+	h.check(
+		ownership.byKey === true &&
+			ownership.foreignKey === false &&
+			ownership.legacyMine === true &&
+			ownership.legacyOther === false,
+		`H10: ownership is the stable authorKey, with a name fallback for old notes (${JSON.stringify(ownership)})`
+	);
+	// renaming yourself upgrades your OWN notes' stored author on the next save
+	await A.page.evaluate(
+		(id) => {
+			window.__stores.username.set('New Nick');
+			window.__stores.annotationsHandler.openAnnotation(id, 'edit');
+		},
+		id3
+	);
+	await A.page.waitForTimeout(600);
+	await editCard.getByRole('button', { name: 'Save' }).click();
+	await A.page.waitForTimeout(400);
+	const upgraded = (await store(A.page)).find((a) => a.id === id3);
+	h.check(
+		upgraded?.author === 'New Nick',
+		`H10: our own note re-stamps the author when we rename ourselves (${upgraded?.author})`
+	);
+	const displayed = await A.page.evaluate((id) => {
+		const ah = window.__stores.annotationsHandler;
+		let list = [];
+		ah.annotations.subscribe((l) => (list = l))();
+		const mine = list.find((a) => a.id === id);
+		return {
+			mine: ah.displayAuthor(mine),
+			// exactly what a DIFFERENT device sees when it loads the saved file: same
+			// note, foreign authorKey → the owner's nickname, never 'Me'
+			saved: ah.displayAuthor({ ...mine, authorKey: 'another-device' }),
+			other: ah.displayAuthor({ author: 'Sam' })
+		};
+	}, id3);
+	h.check(
+		displayed.mine === 'Me' && displayed.other === 'Sam',
+		`H10: displayAuthor maps only OUR notes to 'Me' (${displayed.mine} / ${displayed.other})`
+	);
+	h.check(
+		displayed.saved === 'New Nick',
+		`H10: the same note reads as its owner's NICKNAME for anyone else (${displayed.saved})`
+	);
+	await A.page.evaluate(() => window.__stores.annotationsHandler.activeAnnotation.set(null));
 
 	// --- H5: a draft opens at the CLICKED point ------------------------------
 	await A.page.evaluate((uuid) => {
@@ -392,6 +580,96 @@ h.run(async () => {
 	);
 	h.check(shown === true, 'H3: toggling back shows the pins again');
 
+	// --- H12: notes actually persist ------------------------------------------
+	// (1) an annotation change ALONE has to schedule an autosave — before the fix
+	// only objectsGroup/flowGraphs marked dirty, so a note added after the last
+	// object change was never written ("some notes disappear on reload")
+	const dirtyFlow = await A.page.evaluate(async (uuid) => {
+		const s = window.__stores;
+		await s.autosave.saveNow(); // clears the dirty flag
+		const before = s.autosave.isDirty();
+		const ah = s.annotationsHandler;
+		ah.addAnnotation(uuid, [0.2, 1.4, 0.2]);
+		let cur = null;
+		ah.activeAnnotation.subscribe((a) => (cur = a))();
+		ah.setAnnotation({ ...cur.draft, text: 'persist me' });
+		ah.activeAnnotation.set(null);
+		return { before, after: s.autosave.isDirty(), id: cur.draft.id };
+	}, boxUuid);
+	h.check(
+		dirtyFlow.before === false && dirtyFlow.after === true,
+		`H12: an annotation change on its own marks the autosave dirty (${dirtyFlow.before} -> ${dirtyFlow.after})`
+	);
+	const snapshotHasNote = await A.page.evaluate(async (id) => {
+		const s = window.__stores;
+		await s.autosave.saveNow();
+		const list = s.autosave.annotationsSnapshot();
+		return Array.isArray(list) && list.some((a) => a.id === id);
+	}, dirtyFlow.id);
+	h.check(snapshotHasNote, 'H12: the fresh snapshot carries that note');
+
+	// (2) a SCENE-ROOT anchor is rebuilt with a new uuid every boot — the note
+	// remembers the object NAME and re-keys instead of being pruned
+	const heal = await A.page.evaluate(() => {
+		const s = window.__stores;
+		const THREE = s.THREE;
+		let scene;
+		s.globalScene.subscribe((x) => (scene = x))();
+		const mesh = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshBasicMaterial());
+		mesh.name = 'sys-anchor-heal';
+		mesh.position.set(-5, 1, 0);
+		mesh.updateMatrixWorld(true);
+		scene.add(mesh);
+		const ah = s.annotationsHandler;
+		ah.addAnnotation(mesh.uuid, [-5, 1.6, 0]);
+		let cur = null;
+		ah.activeAnnotation.subscribe((a) => (cur = a))();
+		const draft = cur.draft;
+		ah.setAnnotation({ ...draft, text: 'on the env rig' });
+		ah.activeAnnotation.set(null);
+		const oldUuid = mesh.uuid;
+		mesh.uuid = THREE.MathUtils.generateUUID(); // simulate the reboot rebuild
+		return { id: draft.id, objectName: draft.objectName, oldUuid, newUuid: mesh.uuid };
+	});
+	h.check(
+		heal.objectName === 'sys-anchor-heal',
+		`H12: a note on a scene-root object remembers its anchor NAME (${heal.objectName})`
+	);
+	await A.page.evaluate(() => window.__stores.annotationsHandler.sweepAnnotations());
+	const healed = (await store(A.page)).find((a) => a.id === heal.id);
+	h.check(
+		!!healed && healed.objectUuid === heal.newUuid && healed.objectUuid !== heal.oldUuid,
+		'H12: the sweep re-keys it to the rebuilt object instead of pruning it'
+	);
+
+	// (3) an orphaned note gets a grace window before the sweep deletes it
+	const doomedBox = await A.page.evaluate(() => {
+		const s = window.__stores;
+		s.commandsHandler.sceneCommand('/create box');
+		let g;
+		s.objectsGroup.subscribe((x) => (g = x))();
+		return g.children[g.children.length - 1].uuid;
+	});
+	const doomed = await addNote(A.page, doomedBox, [3, 1, 3], { text: 'doomed' });
+	await A.page.evaluate((uuid) => {
+		const s = window.__stores;
+		let g;
+		s.objectsGroup.subscribe((x) => (g = x))();
+		const object = g.getObjectByProperty('uuid', uuid);
+		object.parent.remove(object);
+		s.objectsGroup.update((v) => v);
+	}, doomedBox);
+	await A.page.waitForTimeout(900); // first sweep ran (500ms debounce)
+	h.check(
+		(await store(A.page)).some((a) => a.id === doomed),
+		'H12: the first sweep spares an orphan (a restore race used to eat notes here)'
+	);
+	await A.page.waitForTimeout(3500); // grace expires, the re-armed sweep prunes
+	h.check(
+		!(await store(A.page)).some((a) => a.id === doomed),
+		'H12: after the grace window the orphan is pruned'
+	);
+
 	// --- two-peer (opt-in): A's fields arrive on B ----------------------------
 	if (process.env.TWO_PEER === '1') {
 		const B = await h.setupPage(browser, 'B');
@@ -402,6 +680,12 @@ h.run(async () => {
 			!!mirrored && mirrored.name === 'Hinge' && mirrored.color === '#22c55e' && mirrored.label === 'mechanics',
 			'H1/H5 two-peer: the handshake carries name/color/label to a late joiner'
 		);
+		const starOnB = onB.find((a) => a.id === id3);
+		h.check(!!starOnB && starOnB.shape === 'star', 'H9 two-peer: the pin shape replicates');
+		h.check(
+			!!mirrored && (await B.page.evaluate((a) => window.__stores.annotationsHandler.displayAuthor(a), mirrored)) !== 'Me',
+			"H10 two-peer: A's note does NOT read 'Me' on B"
+		);
 	} else {
 		console.log('SKIP two-peer section (set TWO_PEER=1 with the hosts mapping enabled)');
 	}

From 6b7c609fccc261774510ac80fb5dd147c739e92c Mon Sep 17 00:00:00 2001
From: AlexZ005 <alexz005.info@gmail.com>
Date: Wed, 5 Aug 2026 14:02:55 +0300
Subject: [PATCH 3/8] [fix] grid look-at follow: snap by the section period,
 not by one cell

The grid "snapped" while panning in look-at follow mode because the centre was
quantised to ONE CELL. A cell-step translation maps the thin lines onto
themselves, but the SECTION lines repeat every `sectionEvery` cells - so every
thick line hopped one cell on each step while the fine grid stood still.

Snapping by the section period (cell x sectionEvery) makes the whole pattern map
onto itself: every line lands exactly where a line already was, so following is
invisible and the lines stay locked to world coordinates (unsnapped following
slides the grid under the objects instead, which is why the snap exists).

The fade circle is deliberately left alone: threlte's Grid already defaults its
fadeOrigin to the camera position projected onto the grid plane, which glides
continuously. Feeding it this snapped anchor is what would re-introduce a
jumping fade ring - the exact regression I4 fixed by dropping the eased fade.
So the grid never disappears during navigation; nothing pops.

grid-snapping gains 3 checks: the centre lands on the section lattice, it still
tracks the look-at target, and the fade uniform stays on the unsnapped camera
point.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/extensions/Grid.svelte       | 15 +++++++-
 tests/e2e/grid-snapping.test.cjs | 60 ++++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+), 1 deletion(-)

diff --git a/src/extensions/Grid.svelte b/src/extensions/Grid.svelte
index 5cc12977..128a3450 100644
--- a/src/extensions/Grid.svelte
+++ b/src/extensions/Grid.svelte
@@ -23,6 +23,9 @@
     // 16-P3: all of the appearance now comes from the LOCAL `gridSettings` prefs
     // (Configure Scene ▸ Grid); 'fixed' fade mode skips the auto math entirely.
     //
+    // 15-H13: the follow centre snaps by the SECTION period (see below) — the
+    // earlier per-CELL snap made every thick line hop one cell per step.
+    //
     // 16-Q2: FOLLOW is ours, not threlte's `followCamera` — that one tracked your
     // POSITION, which is not what "follow the camera" wants to mean when you are
     // looking somewhere else. 'lookat' centres the grid under the orbit target,
@@ -48,7 +51,17 @@
         return
       }
       const anchor = follow === 'lookat' && oc?.target ? oc.target : cam.position
-      const step = Math.max(0.001, cell)
+      // The centre must snap by the SECTION period, not by one cell: the line
+      // pattern only maps onto itself when you translate it a whole section
+      // (cell x sectionEvery). Snapping per cell kept the thin lines world-locked
+      // but hopped every THICK line by one cell on each step — the "grid snaps
+      // while panning" report. A section-step snap is invisible: every line lands
+      // exactly where a line already was.
+      // (The fade circle is deliberately NOT tied to this anchor — threlte's Grid
+      // defaults its fadeOrigin to the camera position projected onto the grid
+      // plane, which already glides continuously. Feeding it a snapped point is
+      // what re-introduces a jumping fade ring, cf. I4's "flashing circle" fix.)
+      const step = Math.max(0.001, section)
       centerX = Math.round(anchor.x / step) * step
       centerZ = Math.round(anchor.z / step) * step
     })
diff --git a/tests/e2e/grid-snapping.test.cjs b/tests/e2e/grid-snapping.test.cjs
index 82a0f8c1..f7c509df 100644
--- a/tests/e2e/grid-snapping.test.cjs
+++ b/tests/e2e/grid-snapping.test.cjs
@@ -160,5 +160,65 @@ h.run(async () => {
 	);
 	h.check(custom === 7.5, `a custom rotation step is accepted (${custom}°)`);
 
+	// 15-H13: 'lookat' follow snaps the grid centre by the SECTION period, not by a
+	// single cell — a per-cell snap kept the thin lines world-locked but hopped every
+	// THICK line one cell per step (the "grid snaps while panning" report). The fade
+	// circle must stay on the UNSNAPPED camera point (threlte's default) so it glides.
+	await A.page.evaluate(() => {
+		window.__stores.gridSettings.setGrid({
+			follow: 'lookat',
+			cellSize: 1,
+			sectionEvery: 10,
+			matchSnapStep: false,
+			infinite: true,
+			fadeMode: 'auto'
+		});
+		let oc;
+		window.__stores.orbitControls.subscribe((x) => (oc = x))();
+		oc.target.set(3.7, 0, -12.4); // deliberately off both the cell and section lattice
+		oc.update();
+	});
+	await A.page.waitForTimeout(600);
+	const gridMesh = await A.page.evaluate(
+		() =>
+			new Promise((r) => {
+				window.__stores.globalScene.subscribe((scene) => {
+					let found = null;
+					scene.traverse((node) => {
+						if (!found && node.isMesh && node.material?.uniforms?.fadeOrigin) found = node;
+					});
+					if (!found) return r(null);
+					let camera;
+					window.__stores.globalCamera.subscribe((c) => (camera = c))();
+					const origin = found.material.uniforms.fadeOrigin.value;
+					r({
+						x: found.position.x,
+						z: found.position.z,
+						fadeOrigin: [origin.x, origin.y, origin.z],
+						camera: [camera.position.x, camera.position.z]
+					});
+				})();
+			})
+	);
+	const onLattice = (v, step) => Math.abs(v / step - Math.round(v / step)) < 1e-4;
+	h.check(
+		!!gridMesh && onLattice(gridMesh.x, 10) && onLattice(gridMesh.z - 0.03, 10),
+		`H13: the follow centre lands on the SECTION lattice (${gridMesh && gridMesh.x}, ${
+			gridMesh && (gridMesh.z - 0.03).toFixed(2)
+		}) so no line moves`
+	);
+	h.check(
+		!!gridMesh && Math.abs(gridMesh.z - 0.03 + 10) < 1e-4,
+		`H13: it still FOLLOWS the look-at target (z ${gridMesh && (gridMesh.z - 0.03).toFixed(2)} for a target at -12.4)`
+	);
+	h.check(
+		!!gridMesh &&
+			Math.abs(gridMesh.fadeOrigin[0] - gridMesh.camera[0]) < 0.01 &&
+			Math.abs(gridMesh.fadeOrigin[2] - gridMesh.camera[1]) < 0.01,
+		`H13: the fade circle stays on the unsnapped camera point (${gridMesh?.fadeOrigin
+			.map((v) => v.toFixed(1))
+			.join(',')} vs camera ${gridMesh?.camera.map((v) => v.toFixed(1)).join(',')})`
+	);
+
 	await h.finish(browser);
 });

From c3564f689bda8963e732995b3a41833e42d6a346 Mon Sep 17 00:00:00 2001
From: AlexZ005 <alexz005.info@gmail.com>
Date: Wed, 5 Aug 2026 17:29:24 +0300
Subject: [PATCH 4/8] [feat] note markers v3: screen-space badges with leader
 lines, real occlusion, clustering

The in-scene quads could be CUT IN HALF by any surface they touched (a billboard
rotating into a face) and their occlusion was a per-pixel depth test, so a marker
was never reliably "in front" or "behind". Markers are now screen-space DOM
badges with a leader line to the exact 3D point (new
components/menu/AnnotationMarkers.svelte); the in-scene meshes stay as the VR
path only, since DOM is invisible in a headset. The pin GROUP still tracks its
anchor in every mode - annotationWorldPosition, the popover and the anchor suite
all read it. The triangle/cone under the pin is gone from both paths.

- Occlusion is ONE verdict per marker from a raycast (throttled to ~8Hz) with 8cm
  of slack, so a note resting ON a surface stays solid while one genuinely behind
  geometry fades its FILL to 50% and dashes its leader. The number keeps full
  opacity - it is the marker's identity. Nothing can clip a DOM badge, which was
  the actual request.
- Badge style: pill (rounded-rect for the square shape), 26px tall, 13.5px bold
  tabular number, small type icon, 1.5px light outline + layered drop shadow,
  contrast-aware ink. The leader is a 1.25px core over a soft 3px glow ending in
  a dot with a hairline ring exactly on the 3D point.
- Clustering: greedy screen-space grouping at 34px (where badges would actually
  overlap) collapses into one counted badge with a stacked-plates shadow; a click
  fans the members out in an arc, each keeping its own leader to its own point.
- Polish: constant screen size, hover scale + brighter outline + a tooltip with
  name/preview/author/date, a selected ring on the open note, fade under 0.9m and
  hidden under 0.35m, off-screen culling that skips the raycast too, and an
  adaptive outline for light themes / prefers-color-scheme.
- GOTCHA worth keeping: an <svg> is a REPLACED element, so `position:fixed;
  inset:0` still leaves it at its 300x150 intrinsic box and silently clips every
  line away - it needs explicit width/height 100%. Also, app chrome (Connect bar,
  z 300) sits above the marker layer (z 28), so a badge under it is not
  clickable; the suite clicks in page context rather than fighting Playwright's
  actionability check.

notes-v2 is now 63 checks, rewritten around the DOM markers: fill/ink/pill/icon,
leader endpoints matching the projected point, occluded fade + dashed leader,
the on-surface slack, cluster collapse/expand, hover preview, selected ring, and
the pins toggle hiding both paths. annotation-anchor green, build green,
svelte-check holds 419/62.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/components/AnnotationPins.svelte         |  46 +-
 src/components/Menu.svelte                   |   3 +
 src/components/menu/AnnotationMarkers.svelte | 441 +++++++++++++++++++
 src/lib/annotationsHandler.js                |  16 +
 tests/e2e/notes-v2.test.cjs                  | 302 +++++++++----
 5 files changed, 687 insertions(+), 121 deletions(-)
 create mode 100644 src/components/menu/AnnotationMarkers.svelte

diff --git a/src/components/AnnotationPins.svelte b/src/components/AnnotationPins.svelte
index 4509967f..410f63a0 100644
--- a/src/components/AnnotationPins.svelte
+++ b/src/components/AnnotationPins.svelte
@@ -11,24 +11,24 @@
 		shadeHex,
 		contrastOn
 	} from '$lib/annotationsHandler'
-	import { objectsGroup, globalScene } from '../stores/sceneStore'
+	import { objectsGroup, globalScene, isVRMode } from '../stores/sceneStore'
 
-	// Billboarded note pins. Each pin re-anchors to its object every frame
-	// (objects move) and faces the camera.
+	// In-scene note pins — the VR path. Each pin group re-anchors to its object
+	// every frame (objects move) and faces the camera; the GROUP is the note's
+	// anchor and stays live in every mode (annotationWorldPosition, the popover and
+	// the anchor suite all read it), while the VISUALS only render in a headset.
 	//
-	// H8 (notes v2 follow-up): every pin draws TWICE. The SOLID pass is
-	// depth-tested, so scene geometry hides it; the GHOST pass skips the depth
-	// test at a low opacity, so a pin behind an object stays findable as a dim
-	// silhouette instead of either vanishing or punching through at full strength.
-	// The old single pass was `depthTest: false` with NO renderOrder, which made
-	// "does this pin draw over that object" depend on scene ADD ORDER — that is
-	// why your own new pins floated on top while the ones a late joiner received
-	// (objects added after the pins group) were covered.
-	// The NUMBER is one pass, never depth-tested, on top of every pin mesh: it is
-	// the pin's identity, so it must stay readable even when a neighbouring pin
-	// overlaps it (H8 item: "number should passthrough always").
+	// On desktop the markers are screen-space DOM badges with a leader line
+	// (menu/AnnotationMarkers.svelte): an in-scene quad gets CUT IN HALF by any
+	// surface it touches and its occlusion is a per-pixel depth test, neither of
+	// which we want. DOM can't clip against geometry and gives real typography,
+	// hover states and clustering. Keeping this path for VR is deliberate — DOM is
+	// invisible in a headset.
 	//
-	// H9: shape (round/star/square) + a darker border ring + contrast-aware ink.
+	// Two passes here for the same reason as the DOM badge's translucency: the
+	// depth-tested SOLID pass disappears behind geometry, the depth-test-off GHOST
+	// pass survives dimly, and the number never depth-tests so an overlapping pin
+	// can't hide it. Shapes (round/star/square) + a darker border + contrast ink.
 
 	const { camera } = useThrelte()
 
@@ -136,6 +136,7 @@
 			     every test read it), while the visuals sit a hair toward the camera along
 			     the group's local +Z — which lookAt points at the viewer. Without it a
 			     pin anchored flat ON a face half-sinks into it as the billboard rotates. -->
+			{#if $isVRMode}
 			<T.Group position={[0, 0, 0.06]}>
 			<!-- GHOST pass (no depth test): keeps an occluded pin visible but dim -->
 			<T.Mesh
@@ -163,16 +164,6 @@
 					side={THREE.DoubleSide}
 				/>
 			</T.Mesh>
-			<T.Mesh position={[0, -0.19, 0]} renderOrder={GHOST_FILL}>
-				<T.ConeGeometry args={[0.05, 0.12, 8]} />
-				<T.MeshBasicMaterial
-					color={fillOf(annotation)}
-					transparent
-					opacity={GHOST_OPACITY}
-					depthTest={false}
-					depthWrite={false}
-				/>
-			</T.Mesh>
 			<!-- SOLID pass (depth-tested): an object in front of the pin hides this,
 			     leaving only the ghost — that is the "dim, not gone" behaviour -->
 			<!-- depthWrite on purpose: the postprocessing passes (outline, N8AO) read the
@@ -199,10 +190,6 @@
 					side={THREE.DoubleSide}
 				/>
 			</T.Mesh>
-			<T.Mesh position={[0, -0.19, 0]} renderOrder={SOLID_FILL}>
-				<T.ConeGeometry args={[0.05, 0.12, 8]} />
-				<T.MeshBasicMaterial color={fillOf(annotation)} transparent opacity={SOLID_OPACITY} />
-			</T.Mesh>
 			<Text
 				color={contrastOn(fillOf(annotation))}
 				outlineColor={contrastOn(fillOf(annotation)) === '#1c1917' ? '#ffffff' : '#000000'}
@@ -217,6 +204,7 @@
 				text={String(index + 1)}
 			/>
 			</T.Group>
+			{/if}
 		</T.Group>
 	{/each}
 </T.Group>
diff --git a/src/components/Menu.svelte b/src/components/Menu.svelte
index 4da6d5db..6a078b3d 100644
--- a/src/components/Menu.svelte
+++ b/src/components/Menu.svelte
@@ -21,6 +21,7 @@
 	import TabStrips from './menu/TabStrips.svelte';
 	import VoiceChat from './menu/VoiceChat.svelte';
 	import AnnotationPopover from './menu/AnnotationPopover.svelte';
+	import AnnotationMarkers from './menu/AnnotationMarkers.svelte';
 	import NotesDrawer from './menu/NotesDrawer.svelte';
 	import Library from './menu/Library.svelte';
 	import { DarkMode } from 'flowbite-svelte';
@@ -54,6 +55,8 @@
 <ObjectSearch />
 <TabStrips />
 <VoiceChat />
+<!-- screen-space note markers (badge + leader line); VR uses the in-scene pins -->
+<AnnotationMarkers />
 <AnnotationPopover />
 <NotesDrawer />
 <Library />
diff --git a/src/components/menu/AnnotationMarkers.svelte b/src/components/menu/AnnotationMarkers.svelte
new file mode 100644
index 00000000..aac8bacb
--- /dev/null
+++ b/src/components/menu/AnnotationMarkers.svelte
@@ -0,0 +1,441 @@
+<script lang="ts">
+	import { get } from 'svelte/store';
+	import * as THREE from 'three';
+	import { MessageSquare, Star, Layers } from '@lucide/svelte';
+	import {
+		annotations,
+		activeAnnotation,
+		annotationOwner,
+		openAnnotation,
+		showNotePins,
+		displayName,
+		displayAuthor,
+		contrastOn,
+		rgbaOf,
+		DEFAULT_NOTE_COLOR
+	} from '$lib/annotationsHandler';
+	import { globalCamera, globalRenderer, objectsGroup, isVRMode } from '../../stores/sceneStore';
+
+	// Notes v3 markers: SCREEN-SPACE badges with a leader line to the exact 3D
+	// point. The old in-scene quads could be CUT IN HALF by any surface they
+	// touched (a billboard rotating into a face), and their occlusion depended on
+	// the GPU depth test, which is all-or-nothing per pixel. Here the badge is
+	// DOM, so it can never clip against geometry, and occlusion is decided once
+	// per marker by a raycast with a few centimetres of slack: a marker sitting ON
+	// a surface still counts as visible, one genuinely behind something goes
+	// translucent (fill only — the number stays fully readable) with a dashed
+	// leader. Clusters collapse into a single counted badge that fans out on click.
+	//
+	// VR keeps the in-scene meshes (AnnotationPins.svelte): DOM is invisible in a
+	// headset. Everything here is LOCAL — no replication, no store writes.
+
+	const LEADER = 38; // px from the exact point up to the badge centre
+	const BADGE_H = 26; // px, keep in sync with .marker-badge height
+	const CLUSTER_PX = 34; // badges closer than this overlap, so they collapse into one
+	const FAN_RADIUS = 52; // px, expanded cluster members
+	const OCCLUSION_SLACK = 0.08; // 8cm — geometry this close never counts as cover
+	const OCCLUSION_MS = 120; // raycast budget: ~8Hz, positions still update per frame
+	const NEAR_FADE = 0.9; // metres — fade out when the camera is right on top of it
+	const NEAR_HIDE = 0.35;
+
+	const ICONS: Record<string, any> = { round: MessageSquare, star: Star, square: MessageSquare };
+
+	type Marker = {
+		id: string;
+		color: string;
+		ink: string;
+		shape: string;
+		number: number;
+		title: string;
+		author: string;
+		when: string;
+		text: string;
+		x: number;
+		y: number;
+		px: number;
+		py: number;
+		occluded: boolean;
+		fade: number;
+		cluster: string[] | null;
+	};
+
+	let markers = $state<Marker[]>([]);
+	let hoverId = $state('');
+	let expanded = $state(''); // cluster key currently fanned out
+	const active = $derived($activeAnnotation?.id ?? '');
+	const enabled = $derived($showNotePins && !$isVRMode);
+
+	// --- geometry ---------------------------------------------------------------
+	const world = new THREE.Vector3();
+	const projected = new THREE.Vector3();
+	const toPoint = new THREE.Vector3();
+	const raycaster = new THREE.Raycaster();
+	/** id -> resolved owner object (re-resolved on a slow schedule, not per frame) */
+	const owners = new Map<string, any>();
+	/** id -> last occlusion verdict (raycasts are throttled) */
+	const occluded = new Map<string, boolean>();
+	let lastResolve = 0;
+	let lastOcclusion = 0;
+
+	function resolveOwners(list: any[]) {
+		owners.clear();
+		for (const a of list) owners.set(a.id, annotationOwner(a.objectUuid));
+	}
+
+	/** Is `point` genuinely behind scene geometry, ignoring anything within the slack? */
+	function isOccluded(camera: any, point: THREE.Vector3) {
+		const group = get(objectsGroup);
+		if (!group) return false;
+		toPoint.subVectors(point, camera.position);
+		const distance = toPoint.length();
+		if (distance <= OCCLUSION_SLACK) return false;
+		raycaster.set(camera.position, toPoint.normalize());
+		raycaster.near = 0;
+		raycaster.far = distance - OCCLUSION_SLACK;
+		const hits = raycaster.intersectObject(group, true);
+		// three does not filter hidden objects for us — a hidden mesh must not occlude
+		return hits.some((hit) => {
+			for (let node: any = hit.object; node && node !== group; node = node.parent)
+				if (!node.visible) return false;
+			return true;
+		});
+	}
+
+	function when(ts: number) {
+		try {
+			return new Date(ts).toLocaleString();
+		} catch {
+			return '';
+		}
+	}
+
+	$effect(() => {
+		if (!enabled) {
+			markers = [];
+			return;
+		}
+		let raf = requestAnimationFrame(step);
+		function step() {
+			raf = requestAnimationFrame(step);
+			const list = get(annotations);
+			const camera: any = get(globalCamera);
+			const renderer: any = get(globalRenderer);
+			if (!list.length || !camera || !renderer?.domElement) {
+				if (markers.length) markers = [];
+				return;
+			}
+			const now = performance.now();
+			if (now - lastResolve > 250 || owners.size !== list.length) {
+				lastResolve = now;
+				resolveOwners(list);
+			}
+			const testOcclusion = now - lastOcclusion > OCCLUSION_MS;
+			if (testOcclusion) lastOcclusion = now;
+			const rect = renderer.domElement.getBoundingClientRect();
+
+			/** @type {Marker[]} */
+			const next: Marker[] = [];
+			list.forEach((a, index) => {
+				const owner = owners.get(a.id);
+				if (!owner) return;
+				owner.localToWorld(world.fromArray(a.offset));
+				projected.copy(world).project(camera);
+				if (projected.z >= 1) return; // behind the camera
+				const px = rect.left + ((projected.x + 1) / 2) * rect.width;
+				const py = rect.top + ((1 - projected.y) / 2) * rect.height;
+				if (px < -80 || py < -80 || px > window.innerWidth + 80 || py > window.innerHeight + 80)
+					return; // off-screen: skip the raycast too
+				if (testOcclusion) occluded.set(a.id, isOccluded(camera, world));
+				const distance = camera.position.distanceTo(world);
+				if (distance < NEAR_HIDE) return;
+				const color = a.color || DEFAULT_NOTE_COLOR;
+				next.push({
+					id: a.id,
+					color,
+					ink: contrastOn(color),
+					shape: a.shape || 'round',
+					number: index + 1,
+					title: displayName(a),
+					author: displayAuthor(a),
+					when: when(a.ts),
+					text: a.text || '',
+					x: px,
+					y: py - LEADER,
+					px,
+					py,
+					occluded: occluded.get(a.id) ?? false,
+					fade: distance < NEAR_FADE ? 0.35 : 1,
+					cluster: null
+				});
+			});
+			markers = cluster(next);
+		}
+		return () => cancelAnimationFrame(raf);
+	});
+
+	/**
+	 * Greedy screen-space clustering in note order (deterministic): a marker joins
+	 * the first cluster whose badge is within CLUSTER_PX. A cluster renders ONE
+	 * counted badge; the expanded one fans its members around the centroid so each
+	 * still points at its own 3D spot.
+	 */
+	function cluster(list: Marker[]): Marker[] {
+		/** @type {Marker[][]} */
+		const groups: Marker[][] = [];
+		for (const marker of list) {
+			const near = groups.find((g) => Math.hypot(g[0].x - marker.x, g[0].y - marker.y) < CLUSTER_PX);
+			if (near) near.push(marker);
+			else groups.push([marker]);
+		}
+		const out: Marker[] = [];
+		for (const group of groups) {
+			if (group.length === 1) {
+				out.push(group[0]);
+				continue;
+			}
+			const key = group.map((m) => m.id).join('|');
+			if (expanded === key) {
+				// fan out around the centroid, keeping every leader line honest
+				const cx = group.reduce((sum, m) => sum + m.x, 0) / group.length;
+				const cy = group.reduce((sum, m) => sum + m.y, 0) / group.length;
+				const spread = Math.min(Math.PI * 1.5, group.length * 0.7);
+				group.forEach((m, i) => {
+					const angle = -Math.PI / 2 - spread / 2 + (spread * i) / Math.max(1, group.length - 1);
+					out.push({ ...m, x: cx + Math.cos(angle) * FAN_RADIUS, y: cy + Math.sin(angle) * FAN_RADIUS });
+				});
+				continue;
+			}
+			const head = group[0];
+			out.push({
+				...head,
+				id: key,
+				title: group.length + ' notes here',
+				text: group.map((m) => '#' + m.number + ' ' + m.title).join(' · '),
+				occluded: group.every((m) => m.occluded),
+				number: group.length,
+				cluster: group.map((m) => m.id)
+			});
+		}
+		return out;
+	}
+
+	function activate(marker: Marker) {
+		if (marker.cluster) {
+			expanded = expanded === marker.id ? '' : marker.id;
+			return;
+		}
+		expanded = '';
+		openAnnotation(marker.id, 'view');
+	}
+</script>
+
+{#if enabled && markers.length}
+	<!-- leader lines live in one SVG under the badges; the whole layer is
+	     pointer-transparent so the viewport keeps every drag it had -->
+	<svg class="marker-lines" aria-hidden="true">
+		{#each markers as marker (marker.id)}
+			<g
+				opacity={(marker.occluded ? 0.5 : 1) * marker.fade}
+				stroke-dasharray={marker.occluded ? '3 3' : 'none'}
+			>
+				<line
+					x1={marker.x}
+					y1={marker.y + BADGE_H / 2 - 2}
+					x2={marker.px}
+					y2={marker.py}
+					stroke={marker.color}
+					stroke-width="3"
+					stroke-opacity="0.22"
+					stroke-linecap="round"
+				/>
+				<line
+					x1={marker.x}
+					y1={marker.y + BADGE_H / 2 - 2}
+					x2={marker.px}
+					y2={marker.py}
+					stroke={marker.color}
+					stroke-width="1.25"
+					stroke-opacity="0.95"
+					stroke-linecap="round"
+				/>
+				<circle cx={marker.px} cy={marker.py} r="2.6" fill={marker.color} stroke-width="0" />
+				<circle
+					cx={marker.px}
+					cy={marker.py}
+					r="4"
+					fill="none"
+					stroke="var(--marker-outline, rgba(255,255,255,0.85))"
+					stroke-width="1"
+					stroke-dasharray="none"
+				/>
+			</g>
+		{/each}
+	</svg>
+
+	<div class="marker-layer">
+		{#each markers as marker (marker.id)}
+			{@const Icon = marker.cluster ? Layers : ICONS[marker.shape] ?? MessageSquare}
+			<button
+				class="marker-badge"
+				class:is-occluded={marker.occluded}
+				class:is-active={!marker.cluster && active === marker.id}
+				class:is-cluster={!!marker.cluster}
+				class:is-square={marker.shape === 'square' && !marker.cluster}
+				style="
+					left:{marker.x}px; top:{marker.y}px; opacity:{marker.fade};
+					--fill:{marker.occluded ? rgbaOf(marker.color, 0.5) : marker.color};
+					--ink:{marker.ink};
+					--ring:{marker.color};
+				"
+				title={marker.cluster ? marker.title : '#' + marker.number + ' ' + marker.title}
+				aria-label={marker.cluster ? marker.title : 'Note ' + marker.number + ': ' + marker.title}
+				onclick={() => activate(marker)}
+				onpointerenter={() => (hoverId = marker.id)}
+				onpointerleave={() => (hoverId = hoverId === marker.id ? '' : hoverId)}
+			>
+				<Icon size={12} aria-hidden="true" />
+				<span class="marker-num">{marker.number}</span>
+			</button>
+			{#if hoverId === marker.id}
+				<div
+					class="marker-tip"
+					style="left:{Math.min(marker.x + 16, window.innerWidth - 240)}px; top:{marker.y + 16}px;"
+				>
+					<span class="marker-tip-title">
+						{#if !marker.cluster}<b>#{marker.number}</b>{/if}
+						{marker.title}
+					</span>
+					{#if marker.text}<span class="marker-tip-text">{marker.text}</span>{/if}
+					{#if !marker.cluster}
+						<span class="marker-tip-meta">{marker.author} · {marker.when}</span>
+					{:else}
+						<span class="marker-tip-meta">Click to spread them out</span>
+					{/if}
+				</div>
+			{/if}
+		{/each}
+	</div>
+{/if}
+
+<style>
+	.marker-lines,
+	.marker-layer {
+		position: fixed;
+		inset: 0;
+		/* an <svg> is a REPLACED element: without an explicit size it falls back to
+		   its 300x150 intrinsic box and silently clips every leader line away, even
+		   with inset:0 */
+		width: 100%;
+		height: 100%;
+		pointer-events: none;
+		/* above the viewport, below every panel/drawer/menu tier */
+		z-index: calc(var(--z-drawer) - 2);
+	}
+	.marker-badge {
+		position: fixed;
+		display: inline-flex;
+		align-items: center;
+		gap: 0.2rem;
+		height: 26px;
+		padding: 0 0.5rem 0 0.4rem;
+		border-radius: 9999px;
+		border: 1.5px solid var(--marker-outline, rgba(255, 255, 255, 0.9));
+		background: var(--fill);
+		color: var(--ink);
+		font-size: 13.5px;
+		font-weight: 700;
+		line-height: 1;
+		letter-spacing: -0.01em;
+		box-shadow:
+			0 1px 2px rgb(0 0 0 / 0.45),
+			0 4px 10px rgb(0 0 0 / 0.35);
+		transform: translate(-50%, -50%);
+		transition:
+			transform 120ms ease,
+			box-shadow 120ms ease,
+			border-color 120ms ease;
+		pointer-events: auto;
+		cursor: pointer;
+	}
+	.marker-badge.is-square {
+		border-radius: 8px;
+	}
+	.marker-badge :global(svg) {
+		opacity: 0.75;
+	}
+	.marker-num {
+		font-variant-numeric: tabular-nums;
+	}
+	.marker-badge:hover {
+		transform: translate(-50%, -50%) scale(1.12);
+		border-color: #fff;
+		box-shadow:
+			0 1px 2px rgb(0 0 0 / 0.5),
+			0 6px 16px rgb(0 0 0 / 0.45);
+		z-index: 1;
+	}
+	.marker-badge.is-occluded {
+		/* the fill fades (see --fill) but the number must stay readable */
+		box-shadow: 0 1px 3px rgb(0 0 0 / 0.35);
+		border-color: var(--marker-outline-dim, rgba(255, 255, 255, 0.55));
+	}
+	.marker-badge.is-active {
+		box-shadow:
+			0 0 0 2px var(--ring),
+			0 0 0 4px rgb(0 0 0 / 0.45),
+			0 4px 12px rgb(0 0 0 / 0.4);
+	}
+	.marker-badge.is-cluster {
+		/* a small pile: two offset plates behind the badge */
+		box-shadow:
+			2px 2px 0 0 var(--fill),
+			2px 2px 0 1.5px var(--marker-outline, rgba(255, 255, 255, 0.55)),
+			4px 4px 0 0 var(--fill),
+			4px 4px 0 1.5px var(--marker-outline-dim, rgba(255, 255, 255, 0.35)),
+			0 4px 12px rgb(0 0 0 / 0.4);
+	}
+	.marker-tip {
+		position: fixed;
+		display: flex;
+		max-width: 230px;
+		flex-direction: column;
+		gap: 0.15rem;
+		border-radius: 0.375rem;
+		border: 1px solid rgb(55 65 81 / 0.8);
+		background: rgb(17 24 39 / 0.96);
+		padding: 0.3rem 0.45rem;
+		box-shadow: 0 6px 18px rgb(0 0 0 / 0.5);
+		pointer-events: none;
+	}
+	.marker-tip-title {
+		font-size: 11px;
+		font-weight: 600;
+		color: rgb(243 244 246);
+	}
+	.marker-tip-text {
+		display: -webkit-box;
+		overflow: hidden;
+		-webkit-box-orient: vertical;
+		-webkit-line-clamp: 2;
+		line-clamp: 2;
+		font-size: 10px;
+		color: rgb(209 213 219);
+	}
+	.marker-tip-meta {
+		font-size: 9px;
+		color: rgb(107 114 128);
+	}
+	/* adaptive outline: a light hairline reads on dark scenes, a dark one on bright
+	   skies / light themes */
+	@media (prefers-color-scheme: light) {
+		.marker-badge {
+			--marker-outline: rgb(15 23 42 / 0.55);
+			--marker-outline-dim: rgb(15 23 42 / 0.3);
+		}
+	}
+	:global(:root[data-theme='light']) .marker-badge,
+	:global(:root[data-theme='contrast']) .marker-badge {
+		--marker-outline: rgb(15 23 42 / 0.6);
+		--marker-outline-dim: rgb(15 23 42 / 0.35);
+	}
+</style>
diff --git a/src/lib/annotationsHandler.js b/src/lib/annotationsHandler.js
index 71358506..ffb354a7 100644
--- a/src/lib/annotationsHandler.js
+++ b/src/lib/annotationsHandler.js
@@ -93,6 +93,13 @@ export function shadeHex(hex, factor = 0.55) {
 	return '#' + [to(r), to(g), to(b)].map((v) => v.toString(16).padStart(2, '0')).join('');
 }
 
+/** `hex` as an rgba() string — an occluded marker fades its FILL, not its text
+ * @param {string} hex @param {number} alpha */
+export function rgbaOf(hex, alpha) {
+	const [r, g, b] = rgbOf(hex);
+	return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+
 /**
  * Readable ink for a pin of this fill color — the classic YIQ brightness split
  * at 0.5 (black on amber/green/lime/cyan, white on blue/red/pink/violet).
@@ -188,6 +195,15 @@ function objectOf(uuid) {
 	);
 }
 
+/**
+ * The object a note hangs on (objectsGroup OR the scene root). Exported so the
+ * marker overlay can resolve owners on its own schedule instead of walking the
+ * whole scene per note per frame. @param {string} uuid
+ */
+export function annotationOwner(uuid) {
+	return objectOf(uuid) ?? null;
+}
+
 /** @param {any} data */
 function broadcast(data) {
 	/** @type {any} */
diff --git a/tests/e2e/notes-v2.test.cjs b/tests/e2e/notes-v2.test.cjs
index 2b960409..12eb985a 100644
--- a/tests/e2e/notes-v2.test.cjs
+++ b/tests/e2e/notes-v2.test.cjs
@@ -61,57 +61,51 @@ const pinPixel = (page, idOrDraft) =>
 		idOrDraft
 	);
 
-// everything the pin's meshes/text tell us about the H8 two-pass render
-const pinInfo = (page, id) =>
-	page.evaluate(
-		(id) =>
-			new Promise((resolve) => {
-				window.__stores.annotationsHandler.pinsGroup.subscribe((group) => {
-					const pin = group?.getObjectByName('pin-' + id);
-					if (!pin) return resolve(null);
-					const meshes = [];
-					let text = null;
-					pin.traverse((node) => {
-						if (!node.isMesh) return;
-						// troika Text extends Mesh; its (possibly multi-) material is marked
-						const material = Array.isArray(node.material)
-							? node.material[node.material.length - 1]
-							: node.material;
-						if (material?.isTroikaTextMaterial) {
-							text = {
-								renderOrder: node.renderOrder,
-								depthTest: material.depthTest,
-								value: node.text
-							};
-							return;
-						}
-						if (!material?.color) return;
-						meshes.push({
-							hex: '#' + material.color.getHexString(),
-							depthTest: material.depthTest,
-							depthWrite: material.depthWrite,
-							transparent: material.transparent,
-							opacity: material.opacity,
-							renderOrder: node.renderOrder,
-							verts: node.geometry?.attributes?.position?.count ?? 0
-						});
-					});
-					resolve({ meshes, text });
-				})();
-			}),
-		id
-	);
+// V3: the desktop marker is a screen-space DOM badge + leader line, so its state
+// is read from the DOM (the in-scene meshes are the VR path now). Everything one
+// badge tells us:
+const markerInfo = (page, number) =>
+	page.evaluate((number) => {
+		const badge = [...document.querySelectorAll('.marker-badge')].find(
+			(b) => b.querySelector('.marker-num')?.textContent?.trim() === String(number)
+		);
+		if (!badge) return null;
+		const rect = badge.getBoundingClientRect();
+		const style = getComputedStyle(badge);
+		const svg = document.querySelector('.marker-lines');
+		const lines = [...(svg?.querySelectorAll('line') ?? [])].map((l) => ({
+			x1: +l.getAttribute('x1'),
+			y1: +l.getAttribute('y1'),
+			x2: +l.getAttribute('x2'),
+			y2: +l.getAttribute('y2'),
+			dashed: (l.parentElement?.getAttribute('stroke-dasharray') ?? 'none') !== 'none',
+			opacity: +(l.parentElement?.getAttribute('opacity') ?? 1)
+		}));
+		// the leader whose badge end matches THIS badge's centre (x and y — two
+		// markers can share an x)
+		const cx = rect.x + rect.width / 2;
+		const cy = rect.y + rect.height / 2;
+		const leader = lines.find(
+			(l) => Math.abs(l.x1 - cx) < 2 && Math.abs(l.y1 - (cy + rect.height / 2 - 2)) < 3
+		);
+		return {
+			text: badge.textContent.trim(),
+			center: [cx, rect.y + rect.height / 2],
+			size: [Math.round(rect.width), Math.round(rect.height)],
+			background: style.backgroundColor,
+			color: style.color,
+			radius: style.borderTopLeftRadius,
+			opacity: +style.opacity,
+			occluded: badge.classList.contains('is-occluded'),
+			active: badge.classList.contains('is-active'),
+			cluster: badge.classList.contains('is-cluster'),
+			svgSize: svg ? [svg.getBoundingClientRect().width, svg.getBoundingClientRect().height] : null,
+			leader,
+			icon: !!badge.querySelector('svg')
+		};
+	}, number);
 
-// the FILL color of the pin's brightest pass (the note color, not the border)
-const pinColor = async (page, id) => {
-	const info = await pinInfo(page, id);
-	if (!info?.meshes?.length) return null;
-	// the fill passes carry the note color; the border passes are the darker shade
-	const counts = {};
-	for (const m of info.meshes) counts[m.hex] = (counts[m.hex] || 0) + 1;
-	// fill appears on the disc + cone in both passes (4), border only twice
-	return Object.keys(counts).sort((a, b) => counts[b] - counts[a])[0];
-};
+const badgeCount = (page) => page.locator('.marker-badge').count();
 
 h.run(async () => {
 	const browser = await h.launch();
@@ -175,61 +169,146 @@ h.run(async () => {
 	});
 	h.check(!!(id1 && id2 && id3), 'setup: three notes committed');
 
-	// --- H4: the pin takes the note color -------------------------------------
-	await A.page.waitForTimeout(400);
-	h.check((await pinColor(A.page, id1)) === '#22c55e', 'H4: pin material uses the note color');
+	// --- V3 markers: screen-space badge + leader line -------------------------
+	// close in first: from the default distance these three notes overlap on screen
+	// and CLUSTER (that is the feature — checked further down)
+	await A.page.evaluate(() => window.__stores.objectActions.flyTo([1.6, 1.8, 2.6], [0, 1, 0], 1));
+	await A.page.waitForTimeout(900);
+	const m1 = await markerInfo(A.page, 1);
 	h.check(
-		(await pinColor(A.page, id2)) === '#f59e0b',
-		'H4: a note with no explicit color keeps the amber default pin'
+		m1?.background === 'rgb(34, 197, 94)',
+		`V3/H4: the badge fill is the note colour (${m1?.background})`
 	);
-
-	// --- H8: two render passes + an always-on-top number ----------------------
-	const info1 = await pinInfo(A.page, id1);
-	const tested = (info1?.meshes ?? []).filter((m) => m.depthTest);
-	const ghosts = (info1?.meshes ?? []).filter((m) => !m.depthTest);
 	h.check(
-		tested.length >= 2 && ghosts.length >= 2,
-		`H8: the pin draws a depth-tested SOLID pass and a depth-test-off GHOST pass (${tested.length}/${ghosts.length} meshes)`
+		(await markerInfo(A.page, 2))?.background === 'rgb(245, 158, 11)',
+		'V3/H4: a note with no explicit colour keeps the amber default'
 	);
 	h.check(
-		ghosts.every((m) => m.transparent && m.opacity < 0.5) &&
-			tested.every((m) => m.transparent && m.opacity > 0.5),
-		`H8: the ghost pass is dim and the solid pass is not (ghost ${ghosts
-			.map((m) => m.opacity)
-			.join('/')} vs solid ${tested.map((m) => m.opacity).join('/')})`
+		m1?.color === 'rgb(28, 25, 23)',
+		`V3/H9: the number ink is contrast-aware — dark on green (${m1?.color})`
 	);
-	// the SOLID pass paints over the ghost, so a visible pin reads as its own
-	// saturated colour instead of the ghost border bleeding up through the fill
+	h.check(!!m1?.icon, 'V3: the badge carries a small type icon next to the number');
 	h.check(
-		(info1?.meshes ?? []).every((m) => m.renderOrder > 0) &&
-			Math.max(...ghosts.map((m) => m.renderOrder)) <
-				Math.min(...tested.map((m) => m.renderOrder)),
-		'H8: every pin mesh has an explicit renderOrder, ghost under solid (no add-order lottery)'
+		!!m1 && m1.size[1] >= 24 && m1.radius.startsWith('999'),
+		`V3: a pill badge with room for bolder type (${m1?.size?.join('x')}, radius ${m1?.radius})`
 	);
+	// the leader line runs from the badge to the EXACT projected point
+	const pix1First = await pinPixel(A.page, id1);
 	h.check(
-		!!info1?.text &&
-			info1.text.depthTest === false &&
-			info1.text.renderOrder > Math.max(...(info1.meshes ?? []).map((m) => m.renderOrder)),
-		`H8: the number draws through everything, above every pin mesh (renderOrder ${info1?.text?.renderOrder})`
+		!!m1?.leader &&
+			!!pix1First &&
+			Math.abs(m1.leader.x2 - pix1First.x) < 2 &&
+			Math.abs(m1.leader.y2 - pix1First.y) < 2 &&
+			m1.leader.y1 < m1.leader.y2,
+		`V3: a leader line joins the badge to the exact 3D point (${m1?.leader?.x2?.toFixed(
+			0
+		)},${m1?.leader?.y2?.toFixed(0)} vs ${pix1First && Math.round(pix1First.x)},${
+			pix1First && Math.round(pix1First.y)
+		})`
 	);
-	// an occluded pin keeps its ghost — the report was "new pins show through, received ones do not"
-	const infoLate = await pinInfo(A.page, id2);
 	h.check(
-		(infoLate?.meshes ?? []).some((m) => !m.depthTest) &&
-			(infoLate?.meshes ?? []).some((m) => m.depthTest),
-		'H8: every pin gets both passes, whenever/however it was created'
+		!!m1?.svgSize && m1.svgSize[0] > 1000 && m1.svgSize[1] > 600,
+		`V3: the leader-line layer spans the viewport (an <svg> falls back to 300x150) (${m1?.svgSize?.join(
+			'x'
+		)})`
+	);
+	// nothing can clip a DOM badge, and the in-scene meshes are VR-only now
+	const meshCount = await A.page.evaluate(
+		() =>
+			new Promise((r) => {
+				window.__stores.annotationsHandler.pinsGroup.subscribe((group) => {
+					let meshes = 0;
+					let pins = 0;
+					group?.traverse((node) => {
+						if (node.isMesh) meshes++;
+						if (node.name?.startsWith('pin-')) pins++;
+					});
+					r({ meshes, pins });
+				})();
+			})
+	);
+	h.check(
+		meshCount.pins === 3 && meshCount.meshes === 0,
+		`V3: the pin anchors stay live but render NO in-scene meshes outside VR (${meshCount.pins} anchors, ${meshCount.meshes} meshes)`
 	);
 
-	// --- H9: shape geometry + darker border + contrast ink --------------------
-	const roundVerts = (await pinInfo(A.page, id1))?.meshes?.[0]?.verts ?? 0;
-	const starVerts = (await pinInfo(A.page, id3))?.meshes?.[0]?.verts ?? 0;
+	// --- V3: behind-geometry markers go translucent, never half-clipped --------
+	const behindId = await addNote(A.page, boxUuid, [0, 0.5, -0.55], {
+		name: 'Back face',
+		text: 'behind the box from here'
+	});
+	await A.page.evaluate(() => window.__stores.objectActions.flyTo([0, 1.2, 4], [0, 0.5, 0], 1));
+	await A.page.waitForTimeout(900);
+	const behind = await markerInfo(A.page, 4);
+	h.check(
+		!!behind?.occluded && /rgba\(/.test(behind.background),
+		`V3: a marker behind geometry fades its FILL (${behind?.background})`
+	);
+	h.check(
+		behind?.color === 'rgb(28, 25, 23)' && behind?.opacity === 1,
+		'V3: ...while the number itself stays fully readable'
+	);
+	h.check(!!behind?.leader?.dashed, 'V3: the occluded leader line is dashed');
+	// a marker sitting ON a surface must NOT count as occluded (the slack window)
+	const onSurface = await markerInfo(A.page, 1);
 	h.check(
-		roundVerts > 0 && starVerts > 0 && roundVerts !== starVerts,
-		`H9: a star pin renders a different geometry than a round one (${roundVerts} vs ${starVerts} verts)`
+		onSurface?.occluded === false && !/rgba\(/.test(onSurface?.background ?? ''),
+		`V3: a marker resting on its surface stays solid — the few-cm slack (${onSurface?.background})`
 	);
+	await A.page.evaluate((id) => {
+		window.__stores.annotationsHandler.deleteAnnotation(id);
+	}, behindId);
+
+	// --- V3: clustering ------------------------------------------------------
+	// three notes almost on top of each other, low on the box so the cluster badge
+	// does not land under the Connect bar
+	const crowd = [];
+	for (const offset of [
+		[0.45, 0.15, 0.5],
+		[0.5, 0.1, 0.45],
+		[0.4, 0.12, 0.55]
+	])
+		crowd.push(await addNote(A.page, boxUuid, offset, { text: 'crowded ' + crowd.length }));
+	await A.page.waitForTimeout(800);
+	const clusterBadge = await A.page.locator('.marker-badge.is-cluster').count();
+	const beforeExpand = await badgeCount(A.page);
+	h.check(
+		clusterBadge === 1,
+		`V3: overlapping markers collapse into ONE counted badge (${clusterBadge} cluster badge, ${beforeExpand} badges total)`
+	);
+	const clusterText = await A.page.locator('.marker-badge.is-cluster .marker-num').first().textContent();
+	h.check(
+		Number(clusterText) >= 3,
+		`V3: the cluster badge shows how many notes are stacked (${clusterText})`
+	);
+	// click in page context: fixed app chrome can sit over a marker and Playwright's
+	// actionability check then refuses (a real user just clicks a visible badge)
+	const clusterClicked = await A.page.evaluate(() => {
+		const badge = document.querySelector('.marker-badge.is-cluster');
+		if (!badge) return false;
+		badge.click();
+		return true;
+	});
+	await A.page.waitForTimeout(500);
+	h.check(
+		clusterClicked &&
+			(await A.page.locator('.marker-badge.is-cluster').count()) === 0 &&
+			(await badgeCount(A.page)) > beforeExpand,
+		'V3: clicking the cluster fans its members out, each with its own leader'
+	);
+	for (const id of crowd)
+		await A.page.evaluate((id) => window.__stores.annotationsHandler.deleteAnnotation(id), id);
+	await A.page.evaluate(() => window.__stores.annotationsHandler.activeAnnotation.set(null));
+
+	// --- H9 colour maths (shared by the badge and the VR pin) -----------------
 	const border = await A.page.evaluate(() => {
 		const ah = window.__stores.annotationsHandler;
-		return { dark: ah.shadeHex('#22c55e'), inkOnGreen: ah.contrastOn('#22c55e'), inkOnBlue: ah.contrastOn('#3b82f6') };
+		return {
+			dark: ah.shadeHex('#22c55e'),
+			inkOnGreen: ah.contrastOn('#22c55e'),
+			inkOnBlue: ah.contrastOn('#3b82f6'),
+			faded: ah.rgbaOf('#22c55e', 0.5)
+		};
 	});
 	h.check(
 		border.dark === '#136c34',
@@ -237,16 +316,45 @@ h.run(async () => {
 	);
 	h.check(
 		border.inkOnGreen === '#1c1917' && border.inkOnBlue === '#f8fafc',
-		`H9: the number ink is contrast-aware (green -> ${border.inkOnGreen}, blue -> ${border.inkOnBlue})`
+		`H9: the ink is contrast-aware (green -> ${border.inkOnGreen}, blue -> ${border.inkOnBlue})`
+	);
+	h.check(
+		border.faded === 'rgba(34, 197, 94, 0.5)',
+		`V3: rgbaOf fades a fill without touching its text (${border.faded})`
+	);
+
+	// --- V3: hover preview ----------------------------------------------------
+	await A.page.evaluate(() => {
+		const badge = [...document.querySelectorAll('.marker-badge')].find(
+			(b) => b.querySelector('.marker-num')?.textContent?.trim() === '1'
+		);
+		badge?.dispatchEvent(new PointerEvent('pointerenter', { bubbles: true }));
+	});
+	await A.page.waitForTimeout(250);
+	const tip = await A.page.evaluate(() => {
+		const t = document.querySelector('.marker-tip');
+		return t ? t.textContent.replace(/\s+/g, ' ').trim() : null;
+	});
+	h.check(
+		!!tip && tip.includes('Hinge') && tip.includes('this corner needs a hinge') && /Me · /.test(tip),
+		`V3: hovering a marker previews its note, author and date (${tip})`
 	);
-	const hasBorder = (await pinInfo(A.page, id1))?.meshes?.some((m) => m.hex === border.dark);
-	h.check(!!hasBorder, 'H9: the pin actually renders that darker border shade');
+	await A.page.evaluate(() => {
+		document
+			.querySelector('.marker-badge')
+			?.dispatchEvent(new PointerEvent('pointerleave', { bubbles: true }));
+	});
 
 	// --- H2/H5: the popover opens ANCHORED near its pin, in VIEW mode ---------
 	await A.page.evaluate((id) => window.__stores.annotationsHandler.openAnnotation(id), id1);
 	await A.page.waitForTimeout(900); // let the 400ms fly settle
 	const viewCard = A.page.locator('[role="dialog"][aria-label="Note"]');
 	h.check(await viewCard.first().isVisible(), 'H2: pin open lands on the VIEW face');
+	h.check(
+		(await markerInfo(A.page, 1))?.active === true &&
+			(await markerInfo(A.page, 3))?.active === false,
+		'V3: the open note\'s marker takes the selected ring, the others do not'
+	);
 	const box1 = await viewCard.first().boundingBox();
 	const pix1 = await pinPixel(A.page, id1);
 	// the card sits beside the pin on whichever side fits (it flips near an edge)
@@ -346,7 +454,11 @@ h.run(async () => {
 		(await active(A.page))?.mode === 'view',
 		'H5: saving returns the card to its view face'
 	);
-	h.check((await pinColor(A.page, id2)) === '#3b82f6', 'H4: the pin re-colors after the edit');
+	const recolored = await markerInfo(A.page, 2);
+	h.check(
+		recolored?.background === 'rgb(59, 130, 246)' && recolored?.radius === '8px',
+		`H4/H9: the badge re-colours and takes the square silhouette after the edit (${recolored?.background}, radius ${recolored?.radius})`
+	);
 
 	// receive path: a peer's v2 payload lands normalized
 	const remote = await A.page.evaluate(
@@ -568,6 +680,10 @@ h.run(async () => {
 		hidden.visible === false && hidden.pref === false,
 		'H3: the header toggle hides the pins group and flips the local pref'
 	);
+	h.check(
+		(await badgeCount(A.page)) === 0,
+		'H3/V3: the screen-space markers go with it (one pref hides both paths)'
+	);
 	await drawer.locator('button[aria-label="Show note pins"]').click();
 	await A.page.waitForTimeout(300);
 	const shown = await A.page.evaluate(
@@ -579,6 +695,8 @@ h.run(async () => {
 			})
 	);
 	h.check(shown === true, 'H3: toggling back shows the pins again');
+	await A.page.waitForTimeout(300);
+	h.check((await badgeCount(A.page)) > 0, 'H3/V3: ...and the markers come back');
 
 	// --- H12: notes actually persist ------------------------------------------
 	// (1) an annotation change ALONE has to schedule an autosave — before the fix

From 9872debedf90e387594ec9daca3e7997c3985914 Mon Sep 17 00:00:00 2001
From: AlexZ005 <alexz005.info@gmail.com>
Date: Wed, 5 Aug 2026 17:44:11 +0300
Subject: [PATCH 5/8] [fix] note markers: publish screen positions from the
 render stage (no jiggle), pill badge everywhere

Two follow-ups from the review.

- JIGGLE ROOT CAUSE: the marker layer owned a private requestAnimationFrame
  loop, but threlte's OrbitControls calls controls.update() in a task in the
  MAIN stage. Those are two separate callback queues: whenever the marker loop
  ran before threlte's tick it projected LAST frame's camera, so every badge
  trailed the geometry by one frame while the camera moved. That also explains
  why entering and leaving VR "fixed" it - an XR session swaps the loop to
  renderer.setAnimationLoop and threlte re-registers its own rAF afterwards,
  flipping the callback order so the marker loop happened to read the updated
  camera.
  Fix: the projection + occlusion now run in a useTask in the RENDER stage
  (after the main stage, so the camera is final for the frame) inside
  AnnotationPins.svelte, which is already in the Canvas, and publish to a new
  `noteMarkers` store. AnnotationMarkers.svelte became presentation-only:
  clustering, hover and the badge chrome derive from that store, no loop of its
  own. Positions therefore always come from the very camera pose that rendered
  the frame the badge sits on.
- Pin SHAPE is now a VR-only distinction: every 2D badge is the same pill, so
  the overlay reads consistently (the rounded-rect variant and the per-shape
  icon are gone). The editor's selector stays - it configures the in-scene VR
  pin - and is labelled "Pin shape - VR only" so it does not look inert.

notes-v2 gains a real regression guard for the lag: it spins the camera and
compares each badge against the pin projected with the camera at that instant,
asserting the residual stays far below the per-frame travel. Verified that the
check DISCRIMINATES by temporarily re-introducing a one-frame lag: residual went
0.0px -> 3.5px against a 3.9px/frame step, and the check failed. Plus a check
that a 'star' note renders the same pill in 2D. 65 checks green,
annotation-anchor green, build green, svelte-check holds 419/62.
roadmap-13-notifications-notes' unread-badge check still fails identically on
HEAD (known flake).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/components/AnnotationPins.svelte         | 103 +++++++++++-
 src/components/menu/AnnotationMarkers.svelte | 166 ++++---------------
 src/components/menu/AnnotationPopover.svelte |   4 +-
 src/lib/annotationsHandler.js                |  12 ++
 tests/e2e/notes-v2.test.cjs                  |  83 +++++++++-
 5 files changed, 229 insertions(+), 139 deletions(-)

diff --git a/src/components/AnnotationPins.svelte b/src/components/AnnotationPins.svelte
index 410f63a0..b5ecfc71 100644
--- a/src/components/AnnotationPins.svelte
+++ b/src/components/AnnotationPins.svelte
@@ -1,15 +1,18 @@
 <script lang="ts">
 	import * as THREE from 'three'
-	import { T, useTask, useThrelte } from '@threlte/core'
+	import { T, useTask, useThrelte, useScheduler } from '@threlte/core'
 	// @ts-ignore - Text typing clashes with verbatimModuleSyntax
 	import { Text } from '@threlte/extras'
 	import {
 		annotations,
 		pinsGroup,
 		showNotePins,
-		DEFAULT_NOTE_COLOR,
+		noteMarkers,
+		displayName,
+		displayAuthor,
+		contrastOn,
 		shadeHex,
-		contrastOn
+		DEFAULT_NOTE_COLOR
 	} from '$lib/annotationsHandler'
 	import { objectsGroup, globalScene, isVRMode } from '../stores/sceneStore'
 
@@ -30,7 +33,7 @@
 	// pass survives dimly, and the number never depth-tests so an overlapping pin
 	// can't hide it. Shapes (round/star/square) + a darker border + contrast ink.
 
-	const { camera } = useThrelte()
+	const { camera, renderer } = useThrelte()
 
 	let root: any
 	$: pinsGroup.set(root ?? null)
@@ -124,6 +127,98 @@
 			// separate follow-up (pre-existing; desktop + normal VR are unaffected).
 		})
 	})
+
+	// --- screen positions for the DOM marker layer ------------------------------
+	// This runs in the RENDER stage, i.e. AFTER the main stage where OrbitControls
+	// calls controls.update(). A plain requestAnimationFrame loop (what the marker
+	// component used to own) is a separate callback queue: when it happened to run
+	// before threlte's tick it projected LAST frame's camera, so the badge trailed
+	// the geometry by a frame while orbiting — the reported jiggle. It "fixed
+	// itself" after an XR session only because entering VR re-registers threlte's
+	// loop and flips the callback order.
+	const { renderStage } = useScheduler()
+	const OCCLUSION_SLACK = 0.08 // 8cm — geometry this close never counts as cover
+	const OCCLUSION_MS = 120 // raycast budget: ~8Hz; positions stay per-frame
+	const NEAR_FADE = 0.9 // metres: fade when the camera is right on top of a marker
+	const NEAR_HIDE = 0.35
+
+	const anchor = new THREE.Vector3()
+	const projected = new THREE.Vector3()
+	const toPoint = new THREE.Vector3()
+	const raycaster = new THREE.Raycaster()
+	const occlusion = new Map<string, boolean>()
+	let lastOcclusion = 0
+
+	/** Is `point` genuinely behind scene geometry, ignoring anything within the slack? */
+	function isOccluded(cameraPos: THREE.Vector3, point: THREE.Vector3) {
+		const group = $objectsGroup
+		if (!group) return false
+		toPoint.subVectors(point, cameraPos)
+		const distance = toPoint.length()
+		if (distance <= OCCLUSION_SLACK) return false
+		raycaster.set(cameraPos, toPoint.normalize())
+		raycaster.near = 0
+		raycaster.far = distance - OCCLUSION_SLACK
+		// three does not skip hidden objects for us — a hidden mesh must not occlude
+		return raycaster.intersectObject(group, true).some((hit) => {
+			for (let node: any = hit.object; node && node !== group; node = node.parent)
+				if (!node.visible) return false
+			return true
+		})
+	}
+
+	useTask(
+		() => {
+			if (!$showNotePins || $isVRMode) {
+				if ($noteMarkers.length) noteMarkers.set([])
+				return
+			}
+			const cam = camera.current as any
+			const element = renderer?.domElement
+			if (!cam || !element || !$annotations.length) {
+				if ($noteMarkers.length) noteMarkers.set([])
+				return
+			}
+			const now = performance.now()
+			const testOcclusion = now - lastOcclusion > OCCLUSION_MS
+			if (testOcclusion) lastOcclusion = now
+			const rect = element.getBoundingClientRect()
+			cam.getWorldPosition(cameraPosition)
+
+			const views: any[] = []
+			$annotations.forEach((annotation, index) => {
+				const pin = pinRefs[annotation.id]
+				if (!pin || !pin.visible) return
+				pin.getWorldPosition(anchor)
+				projected.copy(anchor).project(cam)
+				if (projected.z >= 1) return // behind the camera
+				const x = rect.left + ((projected.x + 1) / 2) * rect.width
+				const y = rect.top + ((1 - projected.y) / 2) * rect.height
+				if (x < -80 || y < -80 || x > window.innerWidth + 80 || y > window.innerHeight + 80)
+					return // off-screen: skip the raycast too
+				if (testOcclusion) occlusion.set(annotation.id, isOccluded(cameraPosition, anchor))
+				const distance = cameraPosition.distanceTo(anchor)
+				if (distance < NEAR_HIDE) return
+				const color = fillOf(annotation)
+				views.push({
+					id: annotation.id,
+					number: index + 1,
+					color,
+					ink: contrastOn(color),
+					title: displayName(annotation),
+					author: displayAuthor(annotation),
+					ts: annotation.ts,
+					text: annotation.text || '',
+					px: x,
+					py: y,
+					occluded: occlusion.get(annotation.id) ?? false,
+					fade: distance < NEAR_FADE ? 0.35 : 1
+				})
+			})
+			noteMarkers.set(views)
+		},
+		{ stage: renderStage }
+	)
 </script>
 
 <!-- H3: the pins group hides wholesale with the LOCAL showNotePins pref (the
diff --git a/src/components/menu/AnnotationMarkers.svelte b/src/components/menu/AnnotationMarkers.svelte
index aac8bacb..74a64d8c 100644
--- a/src/components/menu/AnnotationMarkers.svelte
+++ b/src/components/menu/AnnotationMarkers.svelte
@@ -1,20 +1,6 @@
 <script lang="ts">
-	import { get } from 'svelte/store';
-	import * as THREE from 'three';
-	import { MessageSquare, Star, Layers } from '@lucide/svelte';
-	import {
-		annotations,
-		activeAnnotation,
-		annotationOwner,
-		openAnnotation,
-		showNotePins,
-		displayName,
-		displayAuthor,
-		contrastOn,
-		rgbaOf,
-		DEFAULT_NOTE_COLOR
-	} from '$lib/annotationsHandler';
-	import { globalCamera, globalRenderer, objectsGroup, isVRMode } from '../../stores/sceneStore';
+	import { MessageSquare, Layers } from '@lucide/svelte';
+	import { activeAnnotation, openAnnotation, noteMarkers, rgbaOf } from '$lib/annotationsHandler';
 
 	// Notes v3 markers: SCREEN-SPACE badges with a leader line to the exact 3D
 	// point. The old in-scene quads could be CUT IN HALF by any surface they
@@ -26,25 +12,25 @@
 	// translucent (fill only — the number stays fully readable) with a dashed
 	// leader. Clusters collapse into a single counted badge that fans out on click.
 	//
-	// VR keeps the in-scene meshes (AnnotationPins.svelte): DOM is invisible in a
-	// headset. Everything here is LOCAL — no replication, no store writes.
+	// This component is PRESENTATION only: the per-frame screen positions arrive on
+	// the `noteMarkers` store, published from inside threlte's render stage
+	// (AnnotationPins.svelte). Owning a `requestAnimationFrame` loop here made the
+	// badges jiggle while orbiting — that loop is a separate callback queue and can
+	// run before the scheduler updates the camera.
+	//
+	// VR keeps the in-scene meshes: DOM is invisible in a headset, and the pin
+	// SHAPE (round/star/square) is a VR-only distinction — every 2D badge is the
+	// same pill, so the marker layer reads consistently.
 
 	const LEADER = 38; // px from the exact point up to the badge centre
 	const BADGE_H = 26; // px, keep in sync with .marker-badge height
 	const CLUSTER_PX = 34; // badges closer than this overlap, so they collapse into one
 	const FAN_RADIUS = 52; // px, expanded cluster members
-	const OCCLUSION_SLACK = 0.08; // 8cm — geometry this close never counts as cover
-	const OCCLUSION_MS = 120; // raycast budget: ~8Hz, positions still update per frame
-	const NEAR_FADE = 0.9; // metres — fade out when the camera is right on top of it
-	const NEAR_HIDE = 0.35;
-
-	const ICONS: Record<string, any> = { round: MessageSquare, star: Star, square: MessageSquare };
 
 	type Marker = {
 		id: string;
 		color: string;
 		ink: string;
-		shape: string;
 		number: number;
 		title: string;
 		author: string;
@@ -59,47 +45,9 @@
 		cluster: string[] | null;
 	};
 
-	let markers = $state<Marker[]>([]);
 	let hoverId = $state('');
 	let expanded = $state(''); // cluster key currently fanned out
 	const active = $derived($activeAnnotation?.id ?? '');
-	const enabled = $derived($showNotePins && !$isVRMode);
-
-	// --- geometry ---------------------------------------------------------------
-	const world = new THREE.Vector3();
-	const projected = new THREE.Vector3();
-	const toPoint = new THREE.Vector3();
-	const raycaster = new THREE.Raycaster();
-	/** id -> resolved owner object (re-resolved on a slow schedule, not per frame) */
-	const owners = new Map<string, any>();
-	/** id -> last occlusion verdict (raycasts are throttled) */
-	const occluded = new Map<string, boolean>();
-	let lastResolve = 0;
-	let lastOcclusion = 0;
-
-	function resolveOwners(list: any[]) {
-		owners.clear();
-		for (const a of list) owners.set(a.id, annotationOwner(a.objectUuid));
-	}
-
-	/** Is `point` genuinely behind scene geometry, ignoring anything within the slack? */
-	function isOccluded(camera: any, point: THREE.Vector3) {
-		const group = get(objectsGroup);
-		if (!group) return false;
-		toPoint.subVectors(point, camera.position);
-		const distance = toPoint.length();
-		if (distance <= OCCLUSION_SLACK) return false;
-		raycaster.set(camera.position, toPoint.normalize());
-		raycaster.near = 0;
-		raycaster.far = distance - OCCLUSION_SLACK;
-		const hits = raycaster.intersectObject(group, true);
-		// three does not filter hidden objects for us — a hidden mesh must not occlude
-		return hits.some((hit) => {
-			for (let node: any = hit.object; node && node !== group; node = node.parent)
-				if (!node.visible) return false;
-			return true;
-		});
-	}
 
 	function when(ts: number) {
 		try {
@@ -109,69 +57,27 @@
 		}
 	}
 
-	$effect(() => {
-		if (!enabled) {
-			markers = [];
-			return;
-		}
-		let raf = requestAnimationFrame(step);
-		function step() {
-			raf = requestAnimationFrame(step);
-			const list = get(annotations);
-			const camera: any = get(globalCamera);
-			const renderer: any = get(globalRenderer);
-			if (!list.length || !camera || !renderer?.domElement) {
-				if (markers.length) markers = [];
-				return;
-			}
-			const now = performance.now();
-			if (now - lastResolve > 250 || owners.size !== list.length) {
-				lastResolve = now;
-				resolveOwners(list);
-			}
-			const testOcclusion = now - lastOcclusion > OCCLUSION_MS;
-			if (testOcclusion) lastOcclusion = now;
-			const rect = renderer.domElement.getBoundingClientRect();
-
-			/** @type {Marker[]} */
-			const next: Marker[] = [];
-			list.forEach((a, index) => {
-				const owner = owners.get(a.id);
-				if (!owner) return;
-				owner.localToWorld(world.fromArray(a.offset));
-				projected.copy(world).project(camera);
-				if (projected.z >= 1) return; // behind the camera
-				const px = rect.left + ((projected.x + 1) / 2) * rect.width;
-				const py = rect.top + ((1 - projected.y) / 2) * rect.height;
-				if (px < -80 || py < -80 || px > window.innerWidth + 80 || py > window.innerHeight + 80)
-					return; // off-screen: skip the raycast too
-				if (testOcclusion) occluded.set(a.id, isOccluded(camera, world));
-				const distance = camera.position.distanceTo(world);
-				if (distance < NEAR_HIDE) return;
-				const color = a.color || DEFAULT_NOTE_COLOR;
-				next.push({
-					id: a.id,
-					color,
-					ink: contrastOn(color),
-					shape: a.shape || 'round',
-					number: index + 1,
-					title: displayName(a),
-					author: displayAuthor(a),
-					when: when(a.ts),
-					text: a.text || '',
-					x: px,
-					y: py - LEADER,
-					px,
-					py,
-					occluded: occluded.get(a.id) ?? false,
-					fade: distance < NEAR_FADE ? 0.35 : 1,
-					cluster: null
-				});
-			});
-			markers = cluster(next);
-		}
-		return () => cancelAnimationFrame(raf);
-	});
+	const markers = $derived(
+		cluster(
+			$noteMarkers.map((view) => ({
+				id: view.id,
+				color: view.color,
+				ink: view.ink,
+				number: view.number,
+				title: view.title,
+				author: view.author,
+				when: when(view.ts),
+				text: view.text,
+				x: view.px,
+				y: view.py - LEADER,
+				px: view.px,
+				py: view.py,
+				occluded: view.occluded,
+				fade: view.fade,
+				cluster: null
+			}))
+		)
+	);
 
 	/**
 	 * Greedy screen-space clustering in note order (deterministic): a marker joins
@@ -229,7 +135,7 @@
 	}
 </script>
 
-{#if enabled && markers.length}
+{#if markers.length}
 	<!-- leader lines live in one SVG under the badges; the whole layer is
 	     pointer-transparent so the viewport keeps every drag it had -->
 	<svg class="marker-lines" aria-hidden="true">
@@ -274,13 +180,12 @@
 
 	<div class="marker-layer">
 		{#each markers as marker (marker.id)}
-			{@const Icon = marker.cluster ? Layers : ICONS[marker.shape] ?? MessageSquare}
+			{@const Icon = marker.cluster ? Layers : MessageSquare}
 			<button
 				class="marker-badge"
 				class:is-occluded={marker.occluded}
 				class:is-active={!marker.cluster && active === marker.id}
 				class:is-cluster={!!marker.cluster}
-				class:is-square={marker.shape === 'square' && !marker.cluster}
 				style="
 					left:{marker.x}px; top:{marker.y}px; opacity:{marker.fade};
 					--fill:{marker.occluded ? rgbaOf(marker.color, 0.5) : marker.color};
@@ -357,9 +262,6 @@
 		pointer-events: auto;
 		cursor: pointer;
 	}
-	.marker-badge.is-square {
-		border-radius: 8px;
-	}
 	.marker-badge :global(svg) {
 		opacity: 0.75;
 	}
diff --git a/src/components/menu/AnnotationPopover.svelte b/src/components/menu/AnnotationPopover.svelte
index d1255508..024f3d0e 100644
--- a/src/components/menu/AnnotationPopover.svelte
+++ b/src/components/menu/AnnotationPopover.svelte
@@ -264,7 +264,9 @@
 						></button>
 					{/each}
 				</div>
-				<span class="note-caption">Pin shape</span>
+				<!-- shape is a VR-only distinction now: every 2D marker is the same pill
+				     so the overlay reads consistently (user call) -->
+				<span class="note-caption">Pin shape — VR only</span>
 				<div class="note-shapes" role="group" aria-label="Pin shape">
 					{#each NOTE_SHAPES as s (s)}
 						{@const ShapeIcon = SHAPE_ICONS[s]}
diff --git a/src/lib/annotationsHandler.js b/src/lib/annotationsHandler.js
index ffb354a7..e306f060 100644
--- a/src/lib/annotationsHandler.js
+++ b/src/lib/annotationsHandler.js
@@ -18,6 +18,18 @@ export const activeAnnotation = writable(null);
 /** @type {import('svelte/store').Writable<any>} */
 export const pinsGroup = writable(null);
 
+/**
+ * V3: per-frame screen positions for the DOM marker layer, published from INSIDE
+ * threlte's frame scheduler (AnnotationPins.svelte) so the badge is derived from
+ * the very camera pose that rendered the frame. A separate `requestAnimationFrame`
+ * loop is one frame off whenever it happens to run before the scheduler tick —
+ * that was the marker "jiggle" while orbiting, and why it disappeared after an
+ * XR session (entering VR re-registers threlte's loop, flipping the order).
+ * LOCAL and transient — never replicated, never persisted.
+ * @type {import('svelte/store').Writable<any[]>}
+ */
+export const noteMarkers = writable([]);
+
 /** H3: LOCAL pref — pins visible in the viewport (not replicated) */
 export const showNotePins = writable(
 	typeof localStorage === 'undefined' || localStorage.getItem('showNotePins') !== 'false'
diff --git a/tests/e2e/notes-v2.test.cjs b/tests/e2e/notes-v2.test.cjs
index 12eb985a..cc5180dd 100644
--- a/tests/e2e/notes-v2.test.cjs
+++ b/tests/e2e/notes-v2.test.cjs
@@ -192,6 +192,12 @@ h.run(async () => {
 		!!m1 && m1.size[1] >= 24 && m1.radius.startsWith('999'),
 		`V3: a pill badge with room for bolder type (${m1?.size?.join('x')}, radius ${m1?.radius})`
 	);
+	// every 2D badge is the SAME pill — the per-note shape is a VR-only distinction
+	const starBadge = await markerInfo(A.page, 3);
+	h.check(
+		!!starBadge && starBadge.radius === m1?.radius,
+		`V3: a 'star' note renders the same pill in 2D — shape only applies to the VR pin (${starBadge?.radius})`
+	);
 	// the leader line runs from the badge to the EXACT projected point
 	const pix1First = await pinPixel(A.page, id1);
 	h.check(
@@ -212,6 +218,79 @@ h.run(async () => {
 			'x'
 		)})`
 	);
+	// --- V3: the badge must not LAG the camera (the "jiggle") -----------------
+	// The positions are published from inside threlte's RENDER stage, so a badge
+	// always matches the camera pose that rendered the frame it sits on. When the
+	// marker layer owned a private requestAnimationFrame loop it could run before
+	// the scheduler updated the camera and trailed the geometry by one frame — the
+	// reported jiggle (and why an XR session "fixed" it: entering VR re-registers
+	// threlte's loop and flips the callback order). Spin the camera fast and compare
+	// each badge against the pin projected with the camera AS IT IS at that instant:
+	// the residual must stay far below the per-frame travel.
+	const drift = await A.page.evaluate(
+		(leader) =>
+			new Promise((resolve) => {
+				const s = window.__stores;
+				const ah = s.annotationsHandler;
+				let controls;
+				let camera;
+				let renderer;
+				let views = [];
+				s.orbitControls.subscribe((v) => (controls = v))();
+				s.globalCamera.subscribe((v) => (camera = v))();
+				s.globalRenderer.subscribe((v) => (renderer = v))();
+				ah.noteMarkers.subscribe((v) => (views = v))();
+				const id = views[0]?.id;
+				if (!id || !controls) return resolve(null);
+				const wasRotating = controls.autoRotate;
+				const wasSpeed = controls.autoRotateSpeed;
+				controls.autoRotate = true;
+				controls.autoRotateSpeed = 40;
+				const residuals = [];
+				const steps = [];
+				let previous = null;
+				let frames = 0;
+				const sample = () => {
+					frames++;
+					const badge = [...document.querySelectorAll('.marker-badge')].find(
+						(b) => b.querySelector('.marker-num')?.textContent?.trim() === '1'
+					);
+					const world = ah.annotationWorldPosition(id);
+					if (badge && world && camera && renderer?.domElement) {
+						const rect = renderer.domElement.getBoundingClientRect();
+						const v = world.clone().project(camera);
+						const px = rect.left + ((v.x + 1) / 2) * rect.width;
+						const py = rect.top + ((1 - v.y) / 2) * rect.height;
+						const r = badge.getBoundingClientRect();
+						// the badge sits `leader` px above the point it describes
+						residuals.push(Math.hypot(r.x + r.width / 2 - px, r.y + r.height / 2 + leader - py));
+						if (previous) steps.push(Math.hypot(px - previous[0], py - previous[1]));
+						previous = [px, py];
+					}
+					if (frames < 45) requestAnimationFrame(sample);
+					else {
+						controls.autoRotate = wasRotating;
+						controls.autoRotateSpeed = wasSpeed;
+						const median = (a) => a.slice().sort((x, y) => x - y)[Math.floor(a.length / 2)] ?? 0;
+						resolve({ residual: median(residuals), step: median(steps), n: residuals.length });
+					}
+				};
+				requestAnimationFrame(sample);
+			}),
+		38
+	);
+	h.check(
+		!!drift && drift.step > 3,
+		`V3: the spin actually moved the marker between frames (${drift?.step?.toFixed(1)}px/frame over ${drift?.n} samples)`
+	);
+	h.check(
+		!!drift && drift.residual < drift.step * 0.35,
+		`V3: no frame lag while the camera spins — badge vs live projection ${drift?.residual?.toFixed(
+			1
+		)}px against a ${drift?.step?.toFixed(1)}px/frame step`
+	);
+	await A.page.waitForTimeout(300);
+
 	// nothing can clip a DOM badge, and the in-scene meshes are VR-only now
 	const meshCount = await A.page.evaluate(
 		() =>
@@ -456,8 +535,8 @@ h.run(async () => {
 	);
 	const recolored = await markerInfo(A.page, 2);
 	h.check(
-		recolored?.background === 'rgb(59, 130, 246)' && recolored?.radius === '8px',
-		`H4/H9: the badge re-colours and takes the square silhouette after the edit (${recolored?.background}, radius ${recolored?.radius})`
+		recolored?.background === 'rgb(59, 130, 246)' && recolored?.radius.startsWith('999'),
+		`H4: the badge re-colours after the edit and stays a pill — shape is VR-only (${recolored?.background}, radius ${recolored?.radius})`
 	);
 
 	// receive path: a peer's v2 payload lands normalized

From 2ad568385542675942756564ed079e008e63e62a Mon Sep 17 00:00:00 2001
From: AlexZ005 <alexz005.info@gmail.com>
Date: Wed, 5 Aug 2026 18:19:54 +0300
Subject: [PATCH 6/8] [feat] H11 notes: saved camera framing + follow-the-pin
 sessions

Closes the last piece of 15-H. The originally locked fork (follow only while the
popover is open) was dropped on review: nobody keeps a card open to keep
tracking, and closing it to see the scene would kill the thing they wanted.

- FOLLOW IS A SESSION, not a popup side effect. Started explicitly (Follow on the
  note's view card) and it OUTLIVES the card: a sticky info toast "Following note
  #n - the camera rides it as it moves (Esc to stop)" is both the indicator and
  the off-switch (reuses showInfoToast/dismissToastById from 15-L). Local and
  per-viewer - never replicated, because the editor camera belongs to whoever is
  driving it.
- MOTION: each frame we translate camera.position AND orbitControls.target by the
  pin's world delta. Moving both ends preserves the user's own orbit/zoom offset,
  so they keep navigating freely while the camera rides the object. The tick runs
  in a MAIN-stage useTask - before OrbitControls' own task and the render - so the
  pose we write is the pose the frame is composed from, and the render-stage
  marker projection already sees it.
- SAVED POSE = AUTHORED FRAMING. "Save camera view" stores {position, target} on
  the note (replicated on the unchanged annotation message). Opening flies there
  instead of the generic 4m approach; a follow session then keeps that offset
  live as the object moves, so the author's framing stays true. Plus a per-note
  "Follow the pin when opened" hint that auto-starts the viewer's local session.
- HANDOVER is an EXPLICIT signal, not a deviation guess. New `cameraClaim`
  counter in sceneStore (a leaf both modules already import) is bumped by
  objectActions.flyTo, so focus/bookmarks/opening another note end the session
  cleanly - while the user's own PAN, which moves the orbit target exactly like
  our follow step does, no longer looks like someone stealing the camera. First
  attempt used a target-deviation epsilon; it would have broken every pan.
  Sessions also end on Esc, on VR/spectate/play taking the camera, and when the
  followed note or its object goes away.
- Nodes route deliberately NOT taken here: a follow/look-at node belongs to the
  roadmap-16 camera OBJECTS (replicable, watchable via PiP) and is in backlog. A
  peer's graph must never yank your viewpoint.

notes-v2 +16 checks: pose stored and re-flown (comparing against the ACTUAL
parked pose - OrbitControls.update() re-derives position from its spherical
state, so never assert the numbers you asked for), camera+target translate with
the pin, the chosen offset survives, panning keeps the session, closing the card
keeps it, an external flyTo hands over, Esc stops, the flag replicates and
auto-starts, and old payloads normalize to no pose / follow off. 79 checks green;
annotation-anchor, camera-bookmarks, autosave-object-flows green; build green;
svelte-check holds 419/62.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/components/AnnotationPins.svelte         |  10 +
 src/components/menu/AnnotationPopover.svelte | 109 +++++++++-
 src/lib/annotationsHandler.js                | 150 +++++++++++++-
 src/lib/objectActions.js                     |   6 +-
 src/stores/sceneStore.js                     |  10 +
 tests/e2e/notes-v2.test.cjs                  | 204 ++++++++++++++++++-
 6 files changed, 475 insertions(+), 14 deletions(-)

diff --git a/src/components/AnnotationPins.svelte b/src/components/AnnotationPins.svelte
index b5ecfc71..c03a71a5 100644
--- a/src/components/AnnotationPins.svelte
+++ b/src/components/AnnotationPins.svelte
@@ -8,6 +8,8 @@
 		pinsGroup,
 		showNotePins,
 		noteMarkers,
+		followingNote,
+		tickNoteFollow,
 		displayName,
 		displayAuthor,
 		contrastOn,
@@ -100,6 +102,14 @@
 
 	const fillOf = (a: any) => a.color || DEFAULT_NOTE_COLOR
 
+	// H11: a follow session rides the pin. This runs in the MAIN stage, BEFORE
+	// OrbitControls' own task and the render, so the camera+target translation we
+	// apply is what the frame is composed from — no lag, and the marker positions
+	// published in the render stage below already see the corrected pose.
+	useTask(() => {
+		if ($followingNote) tickNoteFollow()
+	})
+
 	useTask(() => {
 		if (!$showNotePins) return
 		camera.current.getWorldPosition(cameraPosition)
diff --git a/src/components/menu/AnnotationPopover.svelte b/src/components/menu/AnnotationPopover.svelte
index 024f3d0e..18b0cb5c 100644
--- a/src/components/menu/AnnotationPopover.svelte
+++ b/src/components/menu/AnnotationPopover.svelte
@@ -1,13 +1,27 @@
 <script lang="ts">
 	import { get } from 'svelte/store';
 	import { untrack } from 'svelte';
-	import { Pencil, Trash2, X, Check, Circle, Star, Square } from '@lucide/svelte';
+	import {
+		Pencil,
+		Trash2,
+		X,
+		Check,
+		Circle,
+		Star,
+		Square,
+		Video,
+		VideoOff,
+		LocateFixed
+	} from '@lucide/svelte';
 	import {
 		annotations,
 		activeAnnotation,
 		setAnnotation,
 		deleteAnnotation,
 		annotationWorldPosition,
+		followingNote,
+		startNoteFollow,
+		stopNoteFollow,
 		displayName,
 		displayAuthor,
 		isMyNote,
@@ -18,7 +32,7 @@
 		NOTE_SHAPES,
 		DEFAULT_NOTE_COLOR
 	} from '$lib/annotationsHandler';
-	import { globalCamera, globalRenderer } from '../../stores/sceneStore';
+	import { globalCamera, globalRenderer, orbitControls } from '../../stores/sceneStore';
 	import { notesDrawerOpen, inspectorClose } from '../../stores/appStore.js';
 
 	// H5 (notes v2): ONE note card with a VIEW face and an EDIT face, anchored
@@ -43,6 +57,7 @@
 	const labels = $derived(
 		[...new Set($annotations.map((a) => (a.label || '').trim()).filter(Boolean))].sort()
 	);
+	const following = $derived(!!note && $followingNote?.id === note.id);
 
 	// --- form state, reseeded whenever the open note (or face) changes ---------
 	let name = $state('');
@@ -50,6 +65,8 @@
 	let color = $state(DEFAULT_NOTE_COLOR);
 	let label = $state('');
 	let shape = $state('round');
+	let pose = $state<any>(null); // H11 saved framing {position, target} | null
+	let followOnOpen = $state(false);
 	let seeded = '';
 	$effect(() => {
 		const key = (note?.id ?? '') + ':' + (editing ? 'edit' : 'view');
@@ -62,8 +79,22 @@
 			color = source?.color || DEFAULT_NOTE_COLOR;
 			label = source?.label ?? '';
 			shape = source?.shape || 'round';
+			pose = source?.camera ?? null;
+			followOnOpen = source?.follow === true;
 		});
 	});
+
+	// H11: capture the CURRENT view as this note's framing. Opening the note flies
+	// here, and a follow session then keeps this offset live as the object moves.
+	function saveView() {
+		const camera: any = $globalCamera;
+		const controls: any = $orbitControls;
+		if (!camera || !controls) return;
+		pose = {
+			position: camera.position.toArray(),
+			target: controls.target.toArray()
+		};
+	}
 	const SHAPE_ICONS: Record<string, any> = { round: Circle, star: Star, square: Square };
 
 	let nameInput: HTMLInputElement | null = $state(null);
@@ -159,6 +190,8 @@
 			text: description,
 			color,
 			shape,
+			camera: pose,
+			follow: followOnOpen,
 			label: label.trim(),
 			author: mine ? myAuthorName() : base.author,
 			authorKey: mine ? myAuthorKey() : base.authorKey,
@@ -299,6 +332,27 @@
 				<datalist id="note-labels">
 					{#each labels as l (l)}<option value={l}></option>{/each}
 				</datalist>
+				<span class="note-caption">Camera</span>
+				<div class="note-camera">
+					<button class="note-flat" title="Store the current view with this note" onclick={saveView}>
+						<LocateFixed size={13} aria-hidden="true" />
+						{pose ? 'Update saved view' : 'Save camera view'}
+					</button>
+					{#if pose}
+						<button
+							class="note-icon"
+							title="Forget the saved view"
+							aria-label="Clear the saved camera view"
+							onclick={() => (pose = null)}
+						>
+							<X size={13} aria-hidden="true" />
+						</button>
+					{/if}
+				</div>
+				<label class="note-check">
+					<input type="checkbox" bind:checked={followOnOpen} />
+					<span>Follow the pin when opened</span>
+				</label>
 			</div>
 			<div class="note-actions">
 				{#if existing}
@@ -330,6 +384,21 @@
 					<Trash2 size={14} aria-hidden="true" /> Delete
 				</button>
 				<span class="flex-1"></span>
+				<!-- H11: the follow session outlives this card — closing it keeps riding -->
+				<button
+					class="note-flat"
+					class:is-on={following}
+					title={following
+						? 'Stop riding this pin with the camera'
+						: 'Ride this pin with the camera (keeps going after you close this card)'}
+					onclick={() => (following ? stopNoteFollow() : startNoteFollow(note.id))}
+				>
+					{#if following}
+						<VideoOff size={14} aria-hidden="true" /> Following
+					{:else}
+						<Video size={14} aria-hidden="true" /> Follow
+					{/if}
+				</button>
 				<button
 					class="note-primary"
 					onclick={() => activeAnnotation.set({ id: note.id, mode: 'edit' })}
@@ -480,6 +549,21 @@
 		background: rgb(249 115 22 / 0.15);
 		color: rgb(243 244 246);
 	}
+	.note-camera {
+		display: flex;
+		align-items: center;
+		gap: 0.25rem;
+	}
+	.note-check {
+		display: flex;
+		align-items: center;
+		gap: 0.375rem;
+		font-size: 11px;
+		color: rgb(209 213 219);
+	}
+	.note-check input {
+		accent-color: rgb(249 115 22);
+	}
 	.note-actions {
 		display: flex;
 		align-items: center;
@@ -487,6 +571,27 @@
 		border-top: 1px solid rgb(55 65 81 / 0.6);
 		padding: 0.4rem 0.5rem;
 	}
+	.note-flat {
+		display: inline-flex;
+		flex: 1 1 auto;
+		align-items: center;
+		justify-content: center;
+		gap: 0.25rem;
+		border: 1px solid rgb(75 85 99 / 0.8);
+		border-radius: 0.25rem;
+		padding: 0.15rem 0.4rem;
+		font-size: 0.75rem;
+		color: rgb(209 213 219);
+	}
+	.note-flat:hover {
+		border-color: rgb(148 163 184 / 0.9);
+		color: rgb(243 244 246);
+	}
+	.note-flat.is-on {
+		border-color: rgb(249 115 22);
+		background: rgb(249 115 22 / 0.18);
+		color: rgb(253 230 138);
+	}
 	.note-primary,
 	.note-danger {
 		display: inline-flex;
diff --git a/src/lib/annotationsHandler.js b/src/lib/annotationsHandler.js
index e306f060..e967f279 100644
--- a/src/lib/annotationsHandler.js
+++ b/src/lib/annotationsHandler.js
@@ -1,7 +1,23 @@
 import * as THREE from 'three';
 import { writable, get } from 'svelte/store';
-import { objectsGroup, selectedObject, globalCamera, globalScene } from '../stores/sceneStore';
-import { peers, username, showToast } from '../stores/appStore';
+import {
+	objectsGroup,
+	selectedObject,
+	globalCamera,
+	globalScene,
+	orbitControls,
+	isVRMode,
+	isLocked,
+	cameraClaim
+} from '../stores/sceneStore';
+import {
+	peers,
+	username,
+	showToast,
+	showInfoToast,
+	dismissToastById,
+	specatorMode
+} from '../stores/appStore';
 import { registerAnnotationsPersistence, markAnnotationsDirty } from './autosave';
 import { flyTo } from './objectActions';
 
@@ -9,7 +25,7 @@ import { flyTo } from './objectActions';
 // object; one note per pin. Replication mirrors the flow-graph pattern:
 // live CRUD messages + a full-state reply on the connection handshake.
 
-/** @type {import('svelte/store').Writable<{id: string, objectUuid: string, objectName: string, offset: number[], text: string, author: string, authorKey: string, ts: number, name: string, color: string, label: string, shape: string}[]>} */
+/** @type {import('svelte/store').Writable<{id: string, objectUuid: string, objectName: string, offset: number[], text: string, author: string, authorKey: string, ts: number, name: string, color: string, label: string, shape: string, camera: {position: number[], target: number[]} | null, follow: boolean}[]>} */
 export const annotations = writable([]);
 /** popover state: { id, mode:'view'|'edit' } for an existing note, { draft: {...} } for a new one, or null */
 /** @type {import('svelte/store').Writable<any>} */
@@ -55,6 +71,16 @@ export const DEFAULT_NOTE_COLOR = NOTE_COLORS[0];
 
 const tempVector = new THREE.Vector3();
 
+/** A stored camera pose is only usable if BOTH vectors survived @param {any} pose */
+function validCameraPose(pose) {
+	/** @param {any} v */
+	const ok = (v) =>
+		Array.isArray(v) && v.length === 3 && v.every((/** @type {any} */ n) => Number.isFinite(n));
+	return pose && ok(pose.position) && ok(pose.target)
+		? { position: [...pose.position], target: [...pose.target] }
+		: null;
+}
+
 /**
  * H1: ONE boundary normalizer. `text` stays the description (replication,
  * autosave, sessions and the e2e suites all carry it); v2 adds optional
@@ -70,6 +96,13 @@ export function normalizeAnnotation(a) {
 		color: typeof a?.color === 'string' && a.color ? a.color : DEFAULT_NOTE_COLOR,
 		label: typeof a?.label === 'string' ? a.label : '',
 		shape: NOTE_SHAPES.includes(a?.shape) ? a.shape : 'round',
+		// H11: an authored FRAMING for the note (replicated). Opening flies here
+		// instead of the generic 4m approach, and a follow session then keeps this
+		// offset live as the object moves.
+		camera: validCameraPose(a?.camera),
+		// H11: author hint — "start following the pin when this note is opened".
+		// The follow SESSION itself is per-viewer and local; this only auto-starts it.
+		follow: a?.follow === true,
 		// H10: who wrote it — `author` is the DISPLAY name at save time, `authorKey`
 		// is the writer's stable device key (only they can match it)
 		authorKey: typeof a?.authorKey === 'string' ? a.authorKey : '',
@@ -243,6 +276,7 @@ export function deleteAnnotation(id) {
 	annotations.update((list) => list.filter((a) => a.id !== id));
 	broadcast({ type: 'annotation', op: 'delete', annotation: { id } });
 	activeAnnotation.update((active) => (active?.id === id ? null : active));
+	if (get(followingNote)?.id === id) stopNoteFollow(); // H11: nothing left to ride
 }
 
 /** Remote CRUD @param {any} data */
@@ -250,6 +284,7 @@ export function applyAnnotation(data) {
 	if (data.op === 'delete') {
 		annotations.update((list) => list.filter((a) => a.id !== data.annotation.id));
 		activeAnnotation.update((active) => (active?.id === data.annotation.id ? null : active));
+		if (get(followingNote)?.id === data.annotation.id) stopNoteFollow();
 	} else {
 		const normalized = normalizeAnnotation(data.annotation);
 		annotations.update((list) => {
@@ -339,16 +374,115 @@ export function openAnnotation(id, mode = 'view') {
 	const annotation = get(annotations).find((a) => a.id === id);
 	if (!annotation) return;
 	activeAnnotation.set({ id, mode });
+	// a new note takes over the camera: never keep riding the previous one
+	if (get(followingNote) && get(followingNote)?.id !== id) stopNoteFollow();
 	const object = objectOf(annotation.objectUuid);
 	/** @type {any} */
 	const camera = get(globalCamera);
 	if (object) {
 		const world = object.localToWorld(new THREE.Vector3().fromArray(annotation.offset));
-		// approach along the current view direction, stopping ~4m from the pin
-		const direction = camera
-			? camera.position.clone().sub(world).normalize()
-			: new THREE.Vector3(0.5, 0.4, 0.5).normalize();
-		flyTo(world.clone().add(direction.multiplyScalar(4)), world);
+		if (annotation.camera) {
+			// H11: the author saved a FRAMING for this note — use it verbatim
+			flyTo(annotation.camera.position, annotation.camera.target);
+		} else {
+			// approach along the current view direction, stopping ~4m from the pin
+			const direction = camera
+				? camera.position.clone().sub(world).normalize()
+				: new THREE.Vector3(0.5, 0.4, 0.5).normalize();
+			flyTo(world.clone().add(direction.multiplyScalar(4)), world);
+		}
+	}
+	// H11: the author asked for this note to be watched — start the LOCAL session
+	// once the fly has settled, so the tween isn't mistaken for someone else
+	// grabbing the camera (see the deviation guard in startNoteFollow)
+	if (annotation.follow) setTimeout(() => startNoteFollow(id), FLY_MS + 60);
+}
+
+// --- H11 follow sessions ------------------------------------------------------
+// A follow session is LOCAL and per-viewer: the editor camera belongs to the
+// person driving it, so nothing here replicates. It deliberately OUTLIVES the
+// popover — you start it, orbit freely while it rides the object, and stop it
+// from the sticky indicator toast or with Esc. Following only while a card was
+// open would have meant keeping a card open to keep tracking.
+
+/** the note whose pin the camera is riding: `{id}` | null (LOCAL) */
+/** @type {import('svelte/store').Writable<any>} */
+export const followingNote = writable(null);
+
+const FLY_MS = 400; // objectActions.flyTo's tween length
+const FOLLOW_TOAST = 'note-follow';
+/** the pin position we last followed */
+let followAnchor = /** @type {any} */ (null);
+/**
+ * The `cameraClaim` value when our session started. HANDOVER is an explicit
+ * signal, not a guess: every flyTo (focus, bookmark, another note) bumps the
+ * counter, so we can let go without ever mistaking a user PAN — which moves the
+ * orbit target exactly like we do — for someone else taking the camera.
+ */
+let followClaim = 0;
+
+/** @param {KeyboardEvent} event */
+function onFollowKey(event) {
+	if (event.key === 'Escape') stopNoteFollow();
+}
+
+/** Ride this note's pin with the camera until something stops us @param {string} id */
+export function startNoteFollow(id) {
+	const annotation = get(annotations).find((a) => a.id === id);
+	if (!annotation) return;
+	// these modes own the camera themselves
+	if (get(isVRMode) || get(specatorMode) || get(isLocked)) return;
+	const world = annotationWorldPosition(id);
+	/** @type {any} */
+	const controls = get(orbitControls);
+	if (!world || !controls) return;
+	followAnchor = world.clone();
+	followClaim = get(cameraClaim);
+	followingNote.set({ id });
+	if (typeof window !== 'undefined') window.addEventListener('keydown', onFollowKey);
+	showInfoToast(
+		FOLLOW_TOAST,
+		'Following note #' + noteNumber(id) + ' — the camera rides it as it moves (Esc to stop)',
+		[{ label: 'Stop following', action: () => stopNoteFollow() }],
+		() => stopNoteFollow()
+	);
+}
+
+export function stopNoteFollow() {
+	if (!get(followingNote)) return;
+	followingNote.set(null);
+	followAnchor = null;
+	if (typeof window !== 'undefined') window.removeEventListener('keydown', onFollowKey);
+	dismissToastById(FOLLOW_TOAST);
+}
+
+/**
+ * One follow step, driven per frame from the scene (AnnotationPins.svelte).
+ * Translating BOTH the camera and the orbit target by the pin's delta keeps the
+ * user's own orbit/zoom intact — the offset they chose is preserved, which is
+ * also how a note's saved framing stays live while its object moves.
+ */
+export function tickNoteFollow() {
+	const session = get(followingNote);
+	if (!session) return;
+	if (get(isVRMode) || get(specatorMode) || get(isLocked)) return stopNoteFollow();
+	const world = annotationWorldPosition(session.id);
+	/** @type {any} */
+	const controls = get(orbitControls);
+	/** @type {any} */
+	const camera = get(globalCamera);
+	if (!world || !controls || !camera) return stopNoteFollow();
+	// HANDOVER: another camera owner announced itself (focus, bookmark, opening a
+	// different note). The user's own orbit/pan/zoom never bumps this, so their
+	// navigation stays free while we ride the pin.
+	if (get(cameraClaim) !== followClaim) return stopNoteFollow();
+	if (!followAnchor) followAnchor = world.clone();
+	const delta = world.clone().sub(followAnchor);
+	if (delta.lengthSq() > 0) {
+		camera.position.add(delta);
+		controls.target.add(delta);
+		controls.update();
+		followAnchor.copy(world);
 	}
 }
 
diff --git a/src/lib/objectActions.js b/src/lib/objectActions.js
index 7ebd6306..a1b5481b 100644
--- a/src/lib/objectActions.js
+++ b/src/lib/objectActions.js
@@ -15,7 +15,8 @@ import {
 	globalCamera,
 	orbitControls,
 	isVRMode,
-	gizmoSuppressed
+	gizmoSuppressed,
+	cameraClaim
 } from '../stores/sceneStore';
 import { attachMultiPivot, releaseMultiPivot } from './multiTransform';
 import { focusTargetFace } from './faceEdit';
@@ -682,6 +683,9 @@ export function flyTo(position, target, duration = 400) {
 
 	const started = performance.now();
 	const token = ++focusAnimation; // cancel a previous camera animation
+	// H11: announce that the camera has a new owner, so anything driving it
+	// continuously (a note-follow session) steps aside instead of fighting the tween
+	cameraClaim.update((n) => n + 1);
 
 	/** @param {number} now */
 	function step(now) {
diff --git a/src/stores/sceneStore.js b/src/stores/sceneStore.js
index 653845a0..636e586f 100644
--- a/src/stores/sceneStore.js
+++ b/src/stores/sceneStore.js
@@ -40,6 +40,16 @@ export const camSave = writable(null);
 export const globalRenderer = writable(null);
 /** @type {import('svelte/store').Writable<any>} */
 export const orbitControls = writable(null);
+/**
+ * 15-H11: bumped by `objectActions.flyTo` whenever something DELIBERATELY takes
+ * the editor camera (focus, camera bookmarks, opening a note). A feature that
+ * drives the camera continuously (the note-follow session) watches this counter
+ * to know it has been handed over, instead of guessing from camera deviation —
+ * guessing cannot tell an ordinary user PAN (which also moves the orbit target)
+ * from someone else grabbing the view. It lives here because sceneStore is a
+ * leaf: objectActions and annotationsHandler both already import it.
+ */
+export const cameraClaim = writable(0);
 // peers' VR controller poses: peerId -> { left, right, active, ts }
 /** @type {import('svelte/store').Writable<Record<string, any>>} */
 export const peerHands = writable({});
diff --git a/tests/e2e/notes-v2.test.cjs b/tests/e2e/notes-v2.test.cjs
index cc5180dd..068be200 100644
--- a/tests/e2e/notes-v2.test.cjs
+++ b/tests/e2e/notes-v2.test.cjs
@@ -127,8 +127,14 @@ h.run(async () => {
 		let list = [];
 		ah.annotations.subscribe((l) => (list = l))();
 		const a = list.find((x) => x.id === 'legacy-note');
-		return a ? { name: a.name, color: a.color, label: a.label, text: a.text } : null;
+		return a
+			? { name: a.name, color: a.color, label: a.label, text: a.text, camera: a.camera, follow: a.follow }
+			: null;
 	});
+	h.check(
+		legacy?.camera === null && legacy?.follow === false,
+		`H11: an old note normalizes to no saved view and follow off (${JSON.stringify(legacy?.camera)}/${legacy?.follow})`
+	);
 	h.check(
 		legacy &&
 			legacy.name === '' &&
@@ -503,7 +509,7 @@ h.run(async () => {
 	await editCard.locator('button[aria-label="Pin color #3b82f6"]').click();
 	await editCard.locator('button[aria-label="Pin shape square"]').click();
 	await editCard.locator('input[list="note-labels"]').fill('review');
-	await editCard.getByRole('button', { name: 'Save' }).click();
+	await editCard.getByRole('button', { name: 'Save', exact: true }).click();
 	await A.page.waitForTimeout(400);
 	const saved = (await store(A.page)).find((a) => a.id === id2);
 	h.check(
@@ -621,7 +627,7 @@ h.run(async () => {
 		id3
 	);
 	await A.page.waitForTimeout(600);
-	await editCard.getByRole('button', { name: 'Save' }).click();
+	await editCard.getByRole('button', { name: 'Save', exact: true }).click();
 	await A.page.waitForTimeout(400);
 	const upgraded = (await store(A.page)).find((a) => a.id === id3);
 	h.check(
@@ -777,6 +783,198 @@ h.run(async () => {
 	await A.page.waitForTimeout(300);
 	h.check((await badgeCount(A.page)) > 0, 'H3/V3: ...and the markers come back');
 
+	// --- H11: saved camera framing + follow sessions --------------------------
+	const camState = (page) =>
+		page.evaluate(
+			() =>
+				new Promise((r) => {
+					const s = window.__stores;
+					let camera;
+					let controls;
+					s.globalCamera.subscribe((v) => (camera = v))();
+					s.orbitControls.subscribe((v) => (controls = v))();
+					let session = null;
+					s.annotationsHandler.followingNote.subscribe((v) => (session = v))();
+					r({
+						position: camera.position.toArray(),
+						target: controls.target.toArray(),
+						// the offset the viewer chose — follow must preserve it
+						offset: camera.position.clone().sub(controls.target).toArray(),
+						following: session?.id ?? null
+					});
+				})
+		);
+	const toastIds = (page) =>
+		page.evaluate(
+			() =>
+				new Promise((r) =>
+					window.__stores.toastStore.subscribe((list) =>
+						r(list.map((e) => (typeof e === 'string' ? e : e.id || e.text)))
+					)()
+				)
+		);
+
+	// park the camera somewhere deliberate, then store it on the note. NOTE: never
+	// assert the requested numbers — OrbitControls.update() re-derives the camera
+	// position from its own spherical state, so the pose we save is wherever the
+	// controls actually left us. Read it and compare against THAT.
+	await A.page.evaluate((id) => {
+		const s = window.__stores;
+		let camera;
+		let controls;
+		s.globalCamera.subscribe((v) => (camera = v))();
+		s.orbitControls.subscribe((v) => (controls = v))();
+		camera.position.set(3, 2.5, 3);
+		controls.target.set(0, 1, 0);
+		controls.update();
+		s.annotationsHandler.openAnnotation(id, 'edit');
+	}, id1);
+	await A.page.waitForTimeout(600);
+	const parked = await camState(A.page);
+	await editCard.getByRole('button', { name: /camera view/ }).click();
+	await editCard.getByRole('button', { name: 'Save', exact: true }).click();
+	await A.page.waitForTimeout(300);
+	const withPose = (await store(A.page)).find((a) => a.id === id1);
+	const near3 = (a, b, e = 0.05) =>
+		!!a && !!b && Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]) < e;
+	h.check(
+		!!withPose?.camera &&
+			near3(withPose.camera.position, parked.position) &&
+			near3(withPose.camera.target, parked.target),
+		`H11: "Save camera view" stores the CURRENT framing on the note (${JSON.stringify(
+			withPose?.camera?.position?.map((n) => +n.toFixed(2))
+		)})`
+	);
+	// fly away, then open the note: it must land back on the SAVED pose
+	await A.page.evaluate(() => window.__stores.objectActions.flyTo([-8, 6, -8], [0, 0, 0], 1));
+	await A.page.waitForTimeout(400);
+	await A.page.evaluate((id) => window.__stores.annotationsHandler.openAnnotation(id), id1);
+	await h.eventually(
+		() => camState(A.page),
+		(c) => near3(c.position, parked.position, 0.3) && near3(c.target, parked.target, 0.3),
+		'H11: opening a note with a saved view flies to THAT pose, not the generic 4m approach'
+	);
+
+	// follow: the camera rides the pin, and the offset the viewer chose survives
+	const before = await camState(A.page);
+	await A.page.evaluate((id) => window.__stores.annotationsHandler.startNoteFollow(id), id1);
+	await A.page.waitForTimeout(200);
+	h.check((await camState(A.page)).following === id1, 'H11: a follow session starts');
+	h.check(
+		(await toastIds(A.page)).includes('note-follow'),
+		'H11: a sticky indicator toast says we are following (and offers Stop)'
+	);
+	await A.page.evaluate((uuid) => {
+		let g;
+		window.__stores.objectsGroup.subscribe((x) => (g = x))();
+		const box = g.getObjectByProperty('uuid', uuid);
+		box.position.x += 3;
+		box.position.y += 1;
+		box.updateMatrixWorld(true);
+	}, boxUuid);
+	await A.page.waitForTimeout(500);
+	const after = await camState(A.page);
+	h.check(
+		Math.abs(after.position[0] - (before.position[0] + 3)) < 0.2 &&
+			Math.abs(after.target[0] - (before.target[0] + 3)) < 0.2,
+		`H11: camera AND orbit target translate with the pin (${before.position[0].toFixed(
+			1
+		)} -> ${after.position[0].toFixed(1)})`
+	);
+	h.check(
+		Math.hypot(
+			after.offset[0] - before.offset[0],
+			after.offset[1] - before.offset[1],
+			after.offset[2] - before.offset[2]
+		) < 0.05,
+		'H11: ...so the viewer keeps the exact offset they had — orbiting stays theirs'
+	);
+	// the user's own navigation must NOT end the session: a PAN moves the orbit
+	// target exactly like our follow step does, so handover has to be an explicit
+	// signal (cameraClaim) rather than a deviation guess
+	await A.page.evaluate(() => {
+		const s = window.__stores;
+		let camera;
+		let controls;
+		s.globalCamera.subscribe((v) => (camera = v))();
+		s.orbitControls.subscribe((v) => (controls = v))();
+		camera.position.x += 1.5; // pan: both ends move together
+		controls.target.x += 1.5;
+		controls.update();
+	});
+	await A.page.waitForTimeout(300);
+	h.check(
+		(await camState(A.page)).following === id1,
+		'H11: panning/orbiting keeps the session — navigation stays the user\'s'
+	);
+
+	// the session OUTLIVES the popover (that was the whole point)
+	await A.page.evaluate(() => window.__stores.annotationsHandler.activeAnnotation.set(null));
+	await A.page.waitForTimeout(250);
+	h.check(
+		(await camState(A.page)).following === id1,
+		'H11: closing the note card does NOT stop following'
+	);
+	// any other camera owner takes over cleanly (bookmark/focus/another note)
+	await A.page.evaluate(() => window.__stores.objectActions.flyTo([9, 7, 9], [1, 1, 1], 1));
+	await h.eventually(
+		() => camState(A.page),
+		(c) => c.following === null,
+		'H11: an external camera move (flyTo) hands the camera back and ends the session'
+	);
+	h.check(
+		!(await toastIds(A.page)).includes('note-follow'),
+		'H11: the indicator toast goes with it'
+	);
+	// Esc stops a session too
+	await A.page.evaluate((id) => window.__stores.annotationsHandler.startNoteFollow(id), id1);
+	await A.page.waitForTimeout(200);
+	await A.page.keyboard.press('Escape');
+	await A.page.waitForTimeout(250);
+	h.check((await camState(A.page)).following === null, 'H11: Esc stops following');
+	// the author hint auto-starts a session on open, and replicates
+	await A.page.evaluate(() => {
+		let original;
+		window.__stores.peers.subscribe((p) => (original = p))();
+		window.__peerOriginal = original;
+		window.__sent = [];
+		window.__stores.peers.set({ ...original, send: (m) => window.__sent.push(m) });
+	});
+	await A.page.evaluate((id) => {
+		const ah = window.__stores.annotationsHandler;
+		let list = [];
+		ah.annotations.subscribe((l) => (list = l))();
+		const note = list.find((a) => a.id === id);
+		ah.setAnnotation({ ...note, follow: true });
+		ah.activeAnnotation.set(null);
+	}, id1);
+	const followSent = await A.page.evaluate(() => {
+		const list = window.__sent.filter((m) => m.type === 'annotation');
+		window.__stores.peers.set(window.__peerOriginal);
+		return list[list.length - 1]?.annotation;
+	});
+	h.check(
+		followSent?.follow === true && !!followSent?.camera,
+		'H11: the follow flag and the saved view replicate on the same annotation message'
+	);
+	await A.page.evaluate((id) => window.__stores.annotationsHandler.openAnnotation(id), id1);
+	await h.eventually(
+		() => camState(A.page),
+		(c) => c.following === id1,
+		'H11: a note flagged "follow when opened" auto-starts the session'
+	);
+	// deleting the followed note releases the camera
+	await A.page.evaluate((id) => {
+		const ah = window.__stores.annotationsHandler;
+		let list = [];
+		ah.annotations.subscribe((l) => (list = l))();
+		const note = list.find((a) => a.id === id);
+		ah.setAnnotation({ ...note, follow: false }); // keep the rest of the suite calm
+		ah.applyAnnotation({ op: 'delete', annotation: { id: 'no-such-note' } });
+	}, id1);
+	await A.page.evaluate(() => window.__stores.annotationsHandler.stopNoteFollow());
+	await A.page.evaluate(() => window.__stores.annotationsHandler.activeAnnotation.set(null));
+
 	// --- H12: notes actually persist ------------------------------------------
 	// (1) an annotation change ALONE has to schedule an autosave — before the fix
 	// only objectsGroup/flowGraphs marked dirty, so a note added after the last

From 91a500dc03945cfa78866bab9ee7ef212cdc0db8 Mon Sep 17 00:00:00 2001
From: AlexZ005 <alexz005.info@gmail.com>
Date: Wed, 5 Aug 2026 21:35:32 +0300
Subject: [PATCH 7/8] [feat] notes: follow-on-open switch, double-click-to-open
 setting, Esc order

- The "Follow the pin when opened" control is a SWITCH now: it arms a mode, which
  is why Settings uses Toggle for behaviour flags. GOTCHA worth remembering:
  flowbite's plugin emits `[type='checkbox']:checked { background-color:
  currentColor !important }`, so no background-color of ours can ever win the ON
  state - it rendered flowbite blue no matter the specificity. The cure is to work
  WITH that rule and drive the fill through `color`. The suite now asserts the ON
  colour so it cannot drift back to blue.
- NEW SETTING "Double-click to open notes" (Settings > Interface, LOCAL, off by
  default): a single click on a note marker - and the drawer's group arrows -
  then only FLIES the camera to the note, and the card opens on a double click.
  Reviewing a scene full of notes becomes pure navigation with nothing in the way.
  `focusAnnotation(id)` is the go-there-without-opening path (openAnnotation and
  it now share one `flyToAnnotation`, so a saved framing and the follow hint apply
  either way).
- With no card open there was nothing to say where you are, so a new
  `visitedNote` store records the last note travelled to: it highlights the drawer
  row and is what the arrows step from, so every press advances one note and wraps
  instead of restarting at the top of the group.
- ESC ORDER, as asked: the first Esc gives the CAMERA back (stops a follow
  session), the second closes the card. One window-level handler in
  annotationsHandler owns it, replacing the card's own keydown - that only fired
  when focus happened to sit inside the card, so Esc did nothing after a marker
  click - and the follow-only listener that would have raced it. A modal owns Esc
  while it is up.

notes-v2 +11 checks (switch shape + ON colour + stored flag, Esc precedence in
both orders and from outside the card, single-click-flies / double-click-opens
with the setting on and off, arrows travelling without a popup while still
advancing + wrapping, and the row highlight). 90 checks green; annotation-anchor,
autosave-object-flows, camera-bookmarks and all 5 settings suites green; build
green; svelte-check holds 419/62.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/components/menu/AnnotationMarkers.svelte |  24 ++-
 src/components/menu/AnnotationPopover.svelte |  57 +++++-
 src/components/menu/NotesDrawer.svelte       |  32 ++-
 src/components/menu/Settings.svelte          |   8 +-
 src/lib/annotationsHandler.js                |  59 +++++-
 src/stores/appStore.js                       |  15 ++
 tests/e2e/notes-v2.test.cjs                  | 202 +++++++++++++++++++
 7 files changed, 369 insertions(+), 28 deletions(-)

diff --git a/src/components/menu/AnnotationMarkers.svelte b/src/components/menu/AnnotationMarkers.svelte
index 74a64d8c..7f51ad56 100644
--- a/src/components/menu/AnnotationMarkers.svelte
+++ b/src/components/menu/AnnotationMarkers.svelte
@@ -1,6 +1,13 @@
 <script lang="ts">
 	import { MessageSquare, Layers } from '@lucide/svelte';
-	import { activeAnnotation, openAnnotation, noteMarkers, rgbaOf } from '$lib/annotationsHandler';
+	import {
+		activeAnnotation,
+		openAnnotation,
+		focusAnnotation,
+		noteMarkers,
+		rgbaOf
+	} from '$lib/annotationsHandler';
+	import { noteDoubleClickToOpen } from '../../stores/appStore.js';
 
 	// Notes v3 markers: SCREEN-SPACE badges with a leader line to the exact 3D
 	// point. The old in-scene quads could be CUT IN HALF by any surface they
@@ -125,12 +132,22 @@
 		return out;
 	}
 
+	/** a plain click: expand a cluster, else open the note — or, in double-click
+	 * mode, just fly there and leave the card out of the way */
 	function activate(marker: Marker) {
 		if (marker.cluster) {
 			expanded = expanded === marker.id ? '' : marker.id;
 			return;
 		}
 		expanded = '';
+		if ($noteDoubleClickToOpen) focusAnnotation(marker.id);
+		else openAnnotation(marker.id, 'view');
+	}
+
+	/** in double-click mode this is how the card opens (a cluster still expands) */
+	function activateStrong(marker: Marker) {
+		if (marker.cluster) return;
+		expanded = '';
 		openAnnotation(marker.id, 'view');
 	}
 </script>
@@ -192,9 +209,12 @@
 					--ink:{marker.ink};
 					--ring:{marker.color};
 				"
-				title={marker.cluster ? marker.title : '#' + marker.number + ' ' + marker.title}
+				title={marker.cluster
+					? marker.title
+					: '#' + marker.number + ' ' + marker.title + ($noteDoubleClickToOpen ? ' (double-click to open)' : '')}
 				aria-label={marker.cluster ? marker.title : 'Note ' + marker.number + ': ' + marker.title}
 				onclick={() => activate(marker)}
+				ondblclick={() => activateStrong(marker)}
 				onpointerenter={() => (hoverId = marker.id)}
 				onpointerleave={() => (hoverId = hoverId === marker.id ? '' : hoverId)}
 			>
diff --git a/src/components/menu/AnnotationPopover.svelte b/src/components/menu/AnnotationPopover.svelte
index 18b0cb5c..f3cca6bb 100644
--- a/src/components/menu/AnnotationPopover.svelte
+++ b/src/components/menu/AnnotationPopover.svelte
@@ -229,12 +229,6 @@
 		role="dialog"
 		tabindex="-1"
 		aria-label={editing ? 'Edit note' : 'Note'}
-		onkeydown={(e) => {
-			if (e.key === 'Escape') {
-				e.stopPropagation();
-				close();
-			}
-		}}
 	>
 		<div class="note-head">
 			<span class="note-num" style="background:{note.color || DEFAULT_NOTE_COLOR}"
@@ -350,7 +344,9 @@
 					{/if}
 				</div>
 				<label class="note-check">
-					<input type="checkbox" bind:checked={followOnOpen} />
+					<!-- a switch, not a checkbox: it arms a MODE (the camera rides this pin),
+					     which is the same reason Settings uses Toggle for behaviour flags -->
+					<input type="checkbox" class="note-switch" bind:checked={followOnOpen} />
 					<span>Follow the pin when opened</span>
 				</label>
 			</div>
@@ -556,13 +552,54 @@
 	}
 	.note-check {
 		display: flex;
+		cursor: pointer;
 		align-items: center;
-		gap: 0.375rem;
+		gap: 0.45rem;
 		font-size: 11px;
 		color: rgb(209 213 219);
 	}
-	.note-check input {
-		accent-color: rgb(249 115 22);
+	/* A compact switch built from the checkbox itself — same visual language as the
+	   flowbite Toggle in Settings, without pulling the component into this card.
+	   GOTCHA: flowbite's plugin emits
+	     [type='checkbox']:checked { background-color: currentColor !important }
+	   so no background-color of ours can ever win the ON state (it rendered
+	   blue-600, flowbite's inherited color). The cure is to work WITH that rule and
+	   drive the fill through `color` instead of fighting it with !important. */
+	input[type='checkbox'].note-switch {
+		position: relative;
+		height: 14px;
+		width: 26px;
+		flex: 0 0 auto;
+		appearance: none;
+		border-radius: 9999px;
+		color: rgb(75 85 99);
+		background-color: rgb(75 85 99);
+		transition:
+			color 120ms ease,
+			background-color 120ms ease;
+		cursor: pointer;
+	}
+	input[type='checkbox'].note-switch::after {
+		content: '';
+		position: absolute;
+		top: 2px;
+		left: 2px;
+		height: 10px;
+		width: 10px;
+		border-radius: 9999px;
+		background: rgb(243 244 246);
+		transition: transform 120ms ease;
+	}
+	input[type='checkbox'].note-switch:checked {
+		/* the !important rule above paints background-color: currentColor */
+		color: rgb(249 115 22);
+	}
+	input[type='checkbox'].note-switch:checked::after {
+		transform: translateX(12px);
+	}
+	input[type='checkbox'].note-switch:focus-visible {
+		outline: 2px solid rgb(249 115 22 / 0.6);
+		outline-offset: 2px;
 	}
 	.note-actions {
 		display: flex;
diff --git a/src/components/menu/NotesDrawer.svelte b/src/components/menu/NotesDrawer.svelte
index 0c900fa5..73d3c0d3 100644
--- a/src/components/menu/NotesDrawer.svelte
+++ b/src/components/menu/NotesDrawer.svelte
@@ -7,11 +7,13 @@
 	// 'General' first) with per-group ‹ › traversal in GLOBAL pin-number order, plus
 	// a header toggle for the in-scene pins.
 	import { ChevronDown, ChevronRight, ChevronLeft, Pencil, Eye, EyeOff } from '@lucide/svelte';
-	import { notesDrawerOpen, inspectorClose } from '../../stores/appStore.js';
+	import { notesDrawerOpen, inspectorClose, noteDoubleClickToOpen } from '../../stores/appStore.js';
 	import {
 		annotations,
 		activeAnnotation,
 		openAnnotation,
+		focusAnnotation,
+		visitedNote,
 		deleteAnnotation,
 		displayName,
 		displayAuthor,
@@ -101,15 +103,28 @@
 	/** @type {Record<string, boolean>} */
 	let collapsed = $state({}); // expanded by default
 
+	/**
+	 * "Go to this note": opens its card, or in double-click mode (Settings ▸
+	 * Interface) only flies there — reviewing a scene then stays pure navigation.
+	 * Either way `visitedNote` records where we are, which is what highlights the
+	 * row and what the arrows step from.
+	 * @param {string} id
+	 */
+	function goTo(id) {
+		if ($noteDoubleClickToOpen) focusAnnotation(id);
+		else openAnnotation(id, 'view');
+	}
+
 	/** Step through a group's notes in pin order, wrapping @param {any} group @param {number} dir */
 	function step(group, dir) {
 		const rows = group.rows;
 		if (!rows.length) return;
-		const current = $activeAnnotation?.id;
+		// walk from the note we last went to, opened or not
+		const current = $activeAnnotation?.id ?? $visitedNote;
 		const at = rows.findIndex((/** @type {any} */ r) => r.a.id === current);
-		// continue from the open note when it belongs to this group, else start at the end
+		// continue from the current note when it belongs to this group, else start at the end
 		const next = at < 0 ? (dir > 0 ? rows[0] : rows[rows.length - 1]) : rows[(at + dir + rows.length) % rows.length];
-		openAnnotation(next.a.id, 'view');
+		goTo(next.a.id);
 	}
 </script>
 
@@ -184,13 +199,16 @@
 								{#each group.rows as row (row.a.id)}
 									<li
 										class="group rounded-sm bg-gray-800/60 hover:bg-gray-700/60"
-										class:notes-row-active={$activeAnnotation?.id === row.a.id}
+										class:notes-row-active={($activeAnnotation?.id ?? $visitedNote) === row.a.id}
 									>
 										<div class="flex items-start gap-2 p-2">
 											<button
 												class="min-w-0 flex-1 text-left"
-												title="Fly to this note"
-												onclick={() => openAnnotation(row.a.id, 'view')}
+												title={$noteDoubleClickToOpen
+													? 'Fly to this note (double-click to open it)'
+													: 'Fly to this note and open it'}
+												onclick={() => goTo(row.a.id)}
+												ondblclick={() => openAnnotation(row.a.id, 'view')}
 											>
 												<div class="flex min-w-0 items-baseline gap-1.5">
 													<span
diff --git a/src/components/menu/Settings.svelte b/src/components/menu/Settings.svelte
index 496c8a69..fbd282bf 100644
--- a/src/components/menu/Settings.svelte
+++ b/src/components/menu/Settings.svelte
@@ -4,7 +4,7 @@
 	import SettingRow from './SettingRow.svelte';
 	import { showGrid, vrOverride, vrMenuHand, vrSnapAngle, vrMirrorSnapTurn, vrTeleportEnabled, vrSleeveEnabled, vrVertexHold, vrFlying, vrPassthrough, vrMenuHold, vrTargetHz, peerHandStyle } from '../../stores/sceneStore.js';
 	import { applyVRFrameRate } from '$lib/vrControls';
-	import { settingsOpen, settingsSection, hidePanels, restorePanels, advancedMode, showEnvInList, objectSearchEnabled, showSimControls, showToast, showRoomsButton, toastsInDrawerOnly, mobileUndockAllowed, enableShiftAdd } from '../../stores/appStore.js';
+	import { settingsOpen, settingsSection, hidePanels, restorePanels, advancedMode, showEnvInList, objectSearchEnabled, showSimControls, showToast, showRoomsButton, toastsInDrawerOnly, mobileUndockAllowed, enableShiftAdd, noteDoubleClickToOpen } from '../../stores/appStore.js';
 	import { trackpadMode, allowBrowserZoom, reversePan, panEnabled, pinchZoomEnabled } from '$lib/trackpadNav';
 	import { drawerSlot, cloudPluginInfo } from '$lib/cloudHooks';
 	import { versionString } from '$lib/version.js';
@@ -676,6 +676,12 @@
 						Pressing Shift+A opens the Add menu at the cursor and spawns the picked object
 						under it. Off by default — Shift also strafes the camera in fly mode
 					</SettingRow>
+					<SettingRow name="Double-click to open notes">
+						<svelte:fragment slot="control"><Toggle bind:checked={$noteDoubleClickToOpen} /></svelte:fragment>
+						A single click on a note marker — and the notes drawer's ‹ › group arrows — then only
+						flies the camera to the note; the card opens on a double click. Handy for reviewing a
+						scene full of notes without a card in the way
+					</SettingRow>
 					<SettingRow name="Toasts in drawer only">
 						<svelte:fragment slot="control"><Toggle bind:checked={$toastsInDrawerOnly} /></svelte:fragment>
 						Hide ALL pop-up toasts in the viewport — including connection requests — so they appear only in the connection drawer's Toasts tab (the notification bell still keeps the full history). Pin the drawer to keep the Toasts tab handy
diff --git a/src/lib/annotationsHandler.js b/src/lib/annotationsHandler.js
index e967f279..a8b30b8b 100644
--- a/src/lib/annotationsHandler.js
+++ b/src/lib/annotationsHandler.js
@@ -16,7 +16,8 @@ import {
 	showToast,
 	showInfoToast,
 	dismissToastById,
-	specatorMode
+	specatorMode,
+	anyModalOpen
 } from '../stores/appStore';
 import { registerAnnotationsPersistence, markAnnotationsDirty } from './autosave';
 import { flyTo } from './objectActions';
@@ -277,6 +278,7 @@ export function deleteAnnotation(id) {
 	broadcast({ type: 'annotation', op: 'delete', annotation: { id } });
 	activeAnnotation.update((active) => (active?.id === id ? null : active));
 	if (get(followingNote)?.id === id) stopNoteFollow(); // H11: nothing left to ride
+	visitedNote.update((v) => (v === id ? '' : v));
 }
 
 /** Remote CRUD @param {any} data */
@@ -374,6 +376,28 @@ export function openAnnotation(id, mode = 'view') {
 	const annotation = get(annotations).find((a) => a.id === id);
 	if (!annotation) return;
 	activeAnnotation.set({ id, mode });
+	flyToAnnotation(id);
+}
+
+/**
+ * Go to a note WITHOUT opening its card — the "double click to open" reading mode
+ * (Settings ▸ Interface) and the drawer's group arrows use this, so stepping
+ * through a scene full of notes is pure navigation.
+ * @param {string} id
+ */
+export function focusAnnotation(id) {
+	const annotation = get(annotations).find((a) => a.id === id);
+	if (!annotation) return;
+	// navigating to a different note dismisses the card that was open
+	activeAnnotation.update((active) => (active?.id && active.id !== id ? null : active));
+	flyToAnnotation(id);
+}
+
+/** Fly to a note's framing (or the generic approach) and honor its follow hint @param {string} id */
+function flyToAnnotation(id) {
+	const annotation = get(annotations).find((a) => a.id === id);
+	if (!annotation) return;
+	visitedNote.set(id);
 	// a new note takes over the camera: never keep riding the previous one
 	if (get(followingNote) && get(followingNote)?.id !== id) stopNoteFollow();
 	const object = objectOf(annotation.objectUuid);
@@ -393,8 +417,7 @@ export function openAnnotation(id, mode = 'view') {
 		}
 	}
 	// H11: the author asked for this note to be watched — start the LOCAL session
-	// once the fly has settled, so the tween isn't mistaken for someone else
-	// grabbing the camera (see the deviation guard in startNoteFollow)
+	// once the fly has settled, so our own tween isn't read as the handover signal
 	if (annotation.follow) setTimeout(() => startNoteFollow(id), FLY_MS + 60);
 }
 
@@ -409,6 +432,15 @@ export function openAnnotation(id, mode = 'view') {
 /** @type {import('svelte/store').Writable<any>} */
 export const followingNote = writable(null);
 
+/**
+ * The last note we travelled to, opened or not (LOCAL). In double-click mode no
+ * card is open to say where you are, so this is what highlights the drawer row
+ * and what the ‹ › arrows step from — otherwise every press would restart at the
+ * top of the group.
+ * @type {import('svelte/store').Writable<string>}
+ */
+export const visitedNote = writable('');
+
 const FLY_MS = 400; // objectActions.flyTo's tween length
 const FOLLOW_TOAST = 'note-follow';
 /** the pin position we last followed */
@@ -421,10 +453,23 @@ let followAnchor = /** @type {any} */ (null);
  */
 let followClaim = 0;
 
-/** @param {KeyboardEvent} event */
-function onFollowKey(event) {
-	if (event.key === 'Escape') stopNoteFollow();
+/**
+ * ONE Escape owner for notes, with a deliberate order: the first Esc gives the
+ * CAMERA back (stops a follow session), the second closes the note card. Two
+ * separate listeners would have raced — and the card's own keydown only fired
+ * when focus happened to be inside it, so Esc did nothing after a marker click.
+ * @param {KeyboardEvent} event
+ */
+function onNotesEscape(event) {
+	if (event.key !== 'Escape') return;
+	if (get(anyModalOpen)) return; // a modal owns Esc while it is up
+	if (get(followingNote)) {
+		stopNoteFollow();
+		return;
+	}
+	if (get(activeAnnotation)) activeAnnotation.set(null);
 }
+if (typeof window !== 'undefined') window.addEventListener('keydown', onNotesEscape);
 
 /** Ride this note's pin with the camera until something stops us @param {string} id */
 export function startNoteFollow(id) {
@@ -439,7 +484,6 @@ export function startNoteFollow(id) {
 	followAnchor = world.clone();
 	followClaim = get(cameraClaim);
 	followingNote.set({ id });
-	if (typeof window !== 'undefined') window.addEventListener('keydown', onFollowKey);
 	showInfoToast(
 		FOLLOW_TOAST,
 		'Following note #' + noteNumber(id) + ' — the camera rides it as it moves (Esc to stop)',
@@ -452,7 +496,6 @@ export function stopNoteFollow() {
 	if (!get(followingNote)) return;
 	followingNote.set(null);
 	followAnchor = null;
-	if (typeof window !== 'undefined') window.removeEventListener('keydown', onFollowKey);
 	dismissToastById(FOLLOW_TOAST);
 }
 
diff --git a/src/stores/appStore.js b/src/stores/appStore.js
index 1ea479f9..3e92a233 100644
--- a/src/stores/appStore.js
+++ b/src/stores/appStore.js
@@ -312,6 +312,21 @@ enableShiftAdd.subscribe((on) => {
 	if (typeof localStorage !== 'undefined') localStorage.setItem('enableShiftAdd', String(on));
 });
 
+/**
+ * 15-H11: with this on, a single click on a note marker — and stepping through a
+ * label group with the drawer's ‹ › arrows — only FLIES the camera to the note;
+ * the card opens on a DOUBLE click. Reading a scene full of notes then becomes
+ * pure navigation, with no card in the way. LOCAL pref, OFF by default so the
+ * click behaviour everyone already knows is unchanged.
+ */
+export const noteDoubleClickToOpen = writable(
+	typeof localStorage !== 'undefined' && localStorage.getItem('noteDoubleClickToOpen') === 'true'
+);
+noteDoubleClickToOpen.subscribe((on) => {
+	if (typeof localStorage !== 'undefined')
+		localStorage.setItem('noteDoubleClickToOpen', String(on));
+});
+
 // E1 (roadmap #13): notification center — a persisted history of everything that
 // flashed as a toast, so a message missed (or dismissed while a modal was open) is
 // still recoverable. The bell + panel live in NotificationCenter.svelte.
diff --git a/tests/e2e/notes-v2.test.cjs b/tests/e2e/notes-v2.test.cjs
index 068be200..8dde297d 100644
--- a/tests/e2e/notes-v2.test.cjs
+++ b/tests/e2e/notes-v2.test.cjs
@@ -975,6 +975,208 @@ h.run(async () => {
 	await A.page.evaluate(() => window.__stores.annotationsHandler.stopNoteFollow());
 	await A.page.evaluate(() => window.__stores.annotationsHandler.activeAnnotation.set(null));
 
+	// --- H11-B: the follow-on-open control is a SWITCH, driven through the UI ---
+	await A.page.evaluate((id) => window.__stores.annotationsHandler.openAnnotation(id, 'edit'), id2);
+	await A.page.waitForTimeout(600);
+	const switchInfo = await A.page.evaluate(() => {
+		const input = document.querySelector('.note-switch');
+		if (!input) return null;
+		const rect = input.getBoundingClientRect();
+		const style = getComputedStyle(input);
+		return {
+			appearance: style.appearance,
+			radius: style.borderTopLeftRadius,
+			ratio: rect.width / rect.height,
+			checked: input.checked,
+			background: style.backgroundColor,
+			knob: getComputedStyle(input, '::after').transform
+		};
+	});
+	h.check(
+		!!switchInfo && switchInfo.appearance === 'none' && switchInfo.ratio > 1.5,
+		`H11-B: "Follow the pin when opened" is a switch, not a checkbox (${switchInfo?.ratio?.toFixed(
+			1
+		)}:1, appearance ${switchInfo?.appearance})`
+	);
+	await A.page.evaluate(() => document.querySelector('.note-switch').click());
+	await editCard.getByRole('button', { name: 'Save', exact: true }).click();
+	await A.page.waitForTimeout(300);
+	h.check(
+		(await store(A.page)).find((a) => a.id === id2)?.follow === true,
+		'H11-B: flipping the switch and saving stores the follow hint'
+	);
+	// ON must READ as on. flowbite's plugin forces `background-color: currentColor
+	// !important` on every checked checkbox, so the switch has to drive its fill
+	// through `color`; miss that and the ON state silently reverts to flowbite blue
+	await A.page.evaluate((id) => window.__stores.annotationsHandler.openAnnotation(id, 'edit'), id2);
+	await A.page.waitForTimeout(700);
+	const switchOn = await A.page.evaluate(() => {
+		const input = document.querySelector('.note-switch');
+		return {
+			checked: input.checked,
+			background: getComputedStyle(input).backgroundColor,
+			knob: getComputedStyle(input, '::after').transform
+		};
+	});
+	h.check(
+		switchOn.checked === true &&
+			switchOn.background === 'rgb(249, 115, 22)' &&
+			switchOn.knob !== switchInfo?.knob,
+		`H11-B: ON reads as the app accent and the knob slides (${switchOn.background}, knob ${switchOn.knob})`
+	);
+	await A.page.evaluate((id) => {
+		const ah = window.__stores.annotationsHandler;
+		let list = [];
+		ah.annotations.subscribe((l) => (list = l))();
+		ah.setAnnotation({ ...list.find((a) => a.id === id), follow: false });
+		ah.stopNoteFollow();
+		ah.activeAnnotation.set(null);
+	}, id2);
+
+	// --- H11-C: Esc gives the camera back first, closes the card second --------
+	await A.page.evaluate((id) => {
+		const ah = window.__stores.annotationsHandler;
+		ah.openAnnotation(id, 'view');
+	}, id1);
+	await A.page.waitForTimeout(700);
+	await A.page.evaluate((id) => window.__stores.annotationsHandler.startNoteFollow(id), id1);
+	await A.page.waitForTimeout(250);
+	await A.page.keyboard.press('Escape');
+	await A.page.waitForTimeout(250);
+	h.check(
+		(await camState(A.page)).following === null && (await active(A.page))?.id === id1,
+		'H11-C: the FIRST Esc stops following and leaves the card open'
+	);
+	await A.page.keyboard.press('Escape');
+	await A.page.waitForTimeout(250);
+	h.check((await active(A.page)) === null, 'H11-C: the SECOND Esc closes the card');
+	// and with no session running, one Esc is enough — from anywhere, not just
+	// when focus happens to sit inside the card
+	await A.page.evaluate((id) => window.__stores.annotationsHandler.openAnnotation(id), id1);
+	await A.page.waitForTimeout(600);
+	await A.page.keyboard.press('Escape');
+	await A.page.waitForTimeout(250);
+	h.check((await active(A.page)) === null, 'H11-C: Esc alone closes the card when nothing is followed');
+
+	// --- H11-D: "double-click to open notes" ----------------------------------
+	const clickBadge = (page, number, type = 'click') =>
+		page.evaluate(
+			({ number, type }) => {
+				const badge = [...document.querySelectorAll('.marker-badge')].find(
+					(b) => b.querySelector('.marker-num')?.textContent?.trim() === String(number)
+				);
+				if (!badge) return false;
+				// Svelte 5 DELEGATES onclick/ondblclick, so a synthetic event must bubble
+				if (type === 'click') badge.click();
+				else badge.dispatchEvent(new MouseEvent('dblclick', { bubbles: true }));
+				return true;
+			},
+			{ number, type }
+		);
+	// frame note #1 from its OWN pin (the box has moved around during this suite,
+	// and from a distance the notes cluster into one badge — no #1 to click)
+	const frameNote = (page, id) =>
+		page.evaluate((id) => {
+			const s = window.__stores;
+			const w = s.annotationsHandler.annotationWorldPosition(id);
+			if (!w) return false;
+			s.objectActions.flyTo([w.x + 1.1, w.y + 0.9, w.z + 2.1], [w.x, w.y, w.z], 1);
+			return true;
+		}, id);
+	// default OFF: one click opens, exactly as before
+	await frameNote(A.page, id1);
+	await A.page.waitForTimeout(800);
+	h.check(await clickBadge(A.page, 1), 'H11-D: found a marker to click');
+	await A.page.waitForTimeout(500);
+	h.check(
+		(await active(A.page))?.id === id1,
+		'H11-D: with the setting off, a single click still opens the note'
+	);
+	await A.page.evaluate(() => window.__stores.annotationsHandler.activeAnnotation.set(null));
+	// ON: a click only travels there
+	await A.page.evaluate(() => window.__stores.noteDoubleClickToOpen.set(true));
+	await frameNote(A.page, id1);
+	await A.page.waitForTimeout(700);
+	// step the camera away so the click has somewhere to fly FROM
+	await A.page.evaluate(() => {
+		const s = window.__stores;
+		let camera;
+		let controls;
+		s.globalCamera.subscribe((v) => (camera = v))();
+		s.orbitControls.subscribe((v) => (controls = v))();
+		camera.position.y += 4;
+		camera.position.x += 4;
+		controls.update();
+	});
+	await A.page.waitForTimeout(400);
+	const beforeClick = await camState(A.page);
+	await clickBadge(A.page, 1);
+	await A.page.waitForTimeout(700);
+	const afterClick = await camState(A.page);
+	h.check(
+		(await active(A.page)) === null,
+		'H11-D: with the setting on, a single click does NOT open the card'
+	);
+	h.check(
+		Math.hypot(
+			afterClick.position[0] - beforeClick.position[0],
+			afterClick.position[1] - beforeClick.position[1],
+			afterClick.position[2] - beforeClick.position[2]
+		) > 1,
+		'H11-D: ...it flies the camera to the note instead'
+	);
+	// a double click is how you open it now (re-frame first: the click above flew
+	// us to this note's SAVED pose, which was authored before the box moved)
+	await frameNote(A.page, id1);
+	await A.page.waitForTimeout(800);
+	h.check(await clickBadge(A.page, 1, 'dblclick'), 'H11-D: found the marker to double-click');
+	await A.page.waitForTimeout(500);
+	h.check((await active(A.page))?.id === id1, 'H11-D: a double click opens the card');
+	await A.page.evaluate(() => window.__stores.annotationsHandler.activeAnnotation.set(null));
+	// the drawer's group arrows travel without opening anything, and still ADVANCE
+	// one note per press (no open card to remember where we were)
+	await A.page.evaluate(() => {
+		window.__stores.notesDrawerOpen.set(true);
+		// a clean starting point: the earlier click left us parked on note #1
+		window.__stores.annotationsHandler.visitedNote.set('');
+	});
+	await A.page.waitForTimeout(400);
+	// the H6 section collapsed 'mechanics' — expand it so its rows render again
+	if ((await drawer.locator('.notes-group-toggle[aria-expanded="false"]').count()) > 0)
+		await drawer.locator('.notes-group-toggle', { hasText: 'mechanics' }).click();
+	await A.page.waitForTimeout(300);
+	const visited = (page) =>
+		page.evaluate(
+			() => new Promise((r) => window.__stores.annotationsHandler.visitedNote.subscribe(r)())
+		);
+	const walk = [];
+	for (let i = 0; i < 3; i++) {
+		await drawer.locator('button[aria-label="Next note in mechanics"]').click();
+		await A.page.waitForTimeout(650);
+		walk.push({ opened: (await active(A.page))?.id ?? null, at: await visited(A.page) });
+	}
+	h.check(
+		walk.every((w) => w.opened === null),
+		`H11-D: the group arrows travel without opening a popup (${JSON.stringify(walk.map((w) => w.opened))})`
+	);
+	// they still ADVANCE one note per press and wrap — with no open card, the
+	// visited note is what traversal steps from (and what highlights the row)
+	h.check(
+		walk[0].at === id1 && walk[1].at === id3 && walk[2].at === id1,
+		`H11-D: ...and each press advances to the next note in the group, wrapping (${walk
+			.map((w) => (w.at === id1 ? '#1' : w.at === id3 ? '#3' : w.at))
+			.join(' -> ')})`
+	);
+	h.check(
+		await drawer.locator('li.notes-row-active').first().isVisible(),
+		'H11-D: the drawer highlights where you are even with no card open'
+	);
+	await A.page.evaluate(() => {
+		window.__stores.noteDoubleClickToOpen.set(false);
+		window.__stores.notesDrawerOpen.set(false);
+		window.__stores.annotationsHandler.activeAnnotation.set(null);
+	});
+
 	// --- H12: notes actually persist ------------------------------------------
 	// (1) an annotation change ALONE has to schedule an autosave — before the fix
 	// only objectsGroup/flowGraphs marked dirty, so a note added after the last

From 57e5c74c38720a7176b87ea10791be8c61a496a3 Mon Sep 17 00:00:00 2001
From: AlexZ005 <alexz005.info@gmail.com>
Date: Wed, 5 Aug 2026 21:58:38 +0300
Subject: [PATCH 8/8] [docs] CLAUDE.md + skills: scene notes v2/v3, the
 rAF-vs-threlte-frame trap, camera ownership
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Architecture map: annotationsHandler's full v2/v3 model (text stays the
  description, ONE normalizeAnnotation at every boundary, unchanged wire shape,
  authorKey identity, noteMarkers/followingNote/visitedNote/focusAnnotation,
  sweepAnnotations' re-key + grace) and the notes UI trio (AnnotationMarkers as the
  screen-space layer, AnnotationPins demoted to the VR path, popover + drawer).
- New gotchas, each of which cost real debugging here: a DOM overlay that must agree
  with a threlte frame may NOT own a requestAnimationFrame (OrbitControls updates
  the camera in a main-stage task; project in useTask({stage: renderStage}) instead
  — and note that entering/leaving VR "fixing" a jiggle is the signature of exactly
  this) - OrbitControls.update() re-derives the camera position from its spherical
  state, so direct writes revert and continuous drivers must move camera AND target,
  with cameraClaim as the explicit handover signal because deviation-watching cannot
  tell a user pan from a takeover - an <svg> is a replaced element, so fixed+inset:0
  still clips it to 300x150 - flowbite forces background-color: currentColor
  !important on checked checkboxes, so a custom switch must be coloured through
  `color` - depthWrite:false loses the outline/N8AO passes, which then paint the
  geometry behind a sprite across its face - pattern FOLLOW must snap by the section
  period, not one cell.
- Status entry for the 5-commit 15-H branch.
- e2e-verify: how to read the DOM markers (and why not pinsGroup), chrome above the
  marker layer, clustering hiding individual badges, the frame-lag guard that was
  proven to fail before being trusted, plus the camera-assertion and
  synthetic-click-vs-binding rules.
- peer-feature: how to GROW an existing replicated record without a new message
  type, and where the line sits between replicated authorship and a local view of it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .claude/skills/e2e-verify/SKILL.md   | 16 ++++++
 .claude/skills/peer-feature/SKILL.md | 13 +++++
 CLAUDE.md                            | 80 +++++++++++++++++++++++++++-
 3 files changed, 107 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/e2e-verify/SKILL.md b/.claude/skills/e2e-verify/SKILL.md
index 6242e91f..6b8ca760 100644
--- a/.claude/skills/e2e-verify/SKILL.md
+++ b/.claude/skills/e2e-verify/SKILL.md
@@ -119,6 +119,22 @@ const value = await page.evaluate(() =>
   "+N more", so don't wait them out — click an action or `dismissToastById(id)`.
   The outline effect isn't in `__stores` (it lives in Outline.svelte) — read it via
   `window.__outlineDebug()` → `{selected, locked}` mesh counts (debugStores-gated).
+- **Scene notes (15-H)**: the desktop marker is a screen-space DOM badge, so read it
+  from the DOM (`.marker-badge` + `.marker-num`, leader lines in `.marker-lines`),
+  not from `pinsGroup` — the in-scene meshes only render in VR now (the pin GROUPS
+  stay live as anchors, which is why `annotation-anchor` is unaffected). App chrome
+  (Connect bar, z 300) sits ABOVE the marker layer (z 28), so a badge under it fails
+  Playwright's actionability check — click it in page context. Markers CLUSTER at
+  34px, so from a distance there is no `#1` to click: frame the note from its own
+  pin (`annotationWorldPosition` → `flyTo`) first. `notes-v2` also carries a
+  frame-lag guard (spin the camera, compare each badge against the pin projected
+  with the live camera) — it was verified to FAIL when a one-frame lag is
+  reintroduced, which is the only reason to trust it.
+- **Camera assertions**: never assert the pose you *asked* for —
+  `OrbitControls.update()` re-derives the camera position from its spherical state.
+  Park the camera, READ the resulting pose, compare against that. And a synthetic
+  click races Svelte's binding: to assert a control's ON styling, reopen the panel
+  so the state comes from STORED data instead of measuring right after the click.
 
 ## Repo-external modules (theprototype-app/modules)
 
diff --git a/.claude/skills/peer-feature/SKILL.md b/.claude/skills/peer-feature/SKILL.md
index 6706bb86..1ddbc87f 100644
--- a/.claude/skills/peer-feature/SKILL.md
+++ b/.claude/skills/peer-feature/SKILL.md
@@ -64,6 +64,19 @@ keep it off the wire.
    sender-side delete-cascade + a presence-style history kind. Per-peer IDENTITY
    choices (avatar photo, hand model) broadcast a content HASH with presence/
    userdata and receivers pull the bytes via assetShare (`handModels.js`).
+   **GROWING an existing replicated record** (annotations gained name/color/shape/
+   label/authorKey/camera/follow in 15-H) needs NO new message type and NO handshake
+   change: keep the message carrying the whole object, put ONE `normalize*()` at
+   every store boundary (local set, remote apply, snapshot, autosave restore) so old
+   payloads gain defaults for free, and make editors SPREAD the base record so a
+   field a newer peer added survives a save by an older one.
+   Distinguish REPLICATED authorship data from a LOCAL view of it: 'Me' is a display
+   mapping over a stored nickname (never store 'me'), and "did I write this?" needs a
+   stable per-DEVICE key — peer ids are re-issued on reconnect and nicknames change,
+   so neither survives a rename or a reload. Anything the viewer alone should feel
+   (a camera follow session, a marker overlay, click-mode prefs) stays LOCAL: the
+   editor camera belongs to whoever is driving it, and a peer's data must never yank
+   another viewer's viewpoint.
 5. **Where does it live in the scene?** `objectsGroup` children = replicated, listed,
    GLTF-synced, anyone edits. Scene-root groups (fixed `name`) = local/derived —
    helpers, env rig, module content; rebuild them from state; they need
diff --git a/CLAUDE.md b/CLAUDE.md
index 74c9d96e..75891eff 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -260,7 +260,23 @@ loadable play content. Everything a user does must be visible to connected peers
   token blocks, local-only), `windowTabs` (+`closeGroup` = tab ✕ closes ALL members) +
   `windowFocus` + `docking` + `dragWindow` + `searchMenuUx` (floating-window system),
   `fileWindows` (floating text/image editor windows), `autosave` + `idb`,
-  `annotationsHandler`, `sessions` (+ .zip export/import bundling scene assets via
+  `annotationsHandler` (15-H scene notes v2/v3 — model
+  `{id, objectUuid, objectName, offset, text, name, color, shape, label, author,
+  authorKey, camera, follow, ts}`: `text` stays the DESCRIPTION and ONE
+  `normalizeAnnotation()` runs at EVERY store boundary, so old autosaves/.tpscene/
+  old peers load with defaults; the WIRE SHAPE IS UNCHANGED (`{type:'annotation',
+  op:'set'}` carries the whole object and saves spread the base, so a newer peer's
+  fields survive our edit). `authorKey` = a stable per-DEVICE key — 'Me' is
+  DISPLAY-only (`displayAuthor`), a saved file always shows the owner's nickname,
+  and renaming yourself re-stamps your own notes. `noteMarkers` = per-frame screen
+  positions published from the RENDER stage for the DOM marker layer.
+  `followingNote` + `startNoteFollow`/`tickNoteFollow` = the LOCAL follow session
+  (translates camera AND orbit target by the pin delta, so the viewer's own orbit
+  offset survives; handover via `cameraClaim`). `visitedNote` = where you are with
+  no card open; `focusAnnotation` = go there WITHOUT opening (the
+  `noteDoubleClickToOpen` pref); `sweepAnnotations` re-keys scene-root anchors by
+  `objectName` and prunes orphans only after a 3s grace; annotation changes mark
+  the autosave dirty via `markAnnotationsDirty`), `sessions` (+ .zip export/import bundling scene assets via
   fflate; #9: the SAME bundle is the first-class **.tpscene** format — `exportSessionZip`
   takes `{assets,packs,flow}` include-opts, adds a `packs/` section; `fileHandler` saves/
   loads it, Sidebar Files = [GLTF | Scene | ⚙cog]), `measure`, `cameraBookmarks`,
@@ -278,7 +294,17 @@ loadable play content. Everything a user does must be visible to connected peers
   panels: Menu/ObjectsPanel/PropertiesPanel/ColorPalette/PrefabsPanel/Keyboard/
   ChatPanel/Stats — named `vr<x>-*` control meshes, all grip-grabbable),
   scene-overlay components (PingMarkers/PingHighlights (#12: uuid-carrying pings flash
-  an object box)/PathWaypoints/LockHighlights), `SimControls`/`SculptToolbar`/`MeshEditPopup` (#12
+  an object box)/PathWaypoints/LockHighlights), scene NOTES (15-H:
+  `menu/AnnotationMarkers.svelte` = the SCREEN-SPACE marker layer — a pill badge +
+  leader line to the exact 3D point, PRESENTATION-ONLY off the `noteMarkers` store;
+  occluded markers fade their FILL and dash the leader while the number stays
+  readable; screen-space clustering collapses overlapping badges into one counted
+  badge that fans out on click. `AnnotationPins.svelte` keeps the in-scene meshes as
+  the VR path (DOM is invisible in a headset) and its GROUPS remain the anchors in
+  every mode; per-note `shape` is a VR-only distinction.
+  `menu/AnnotationPopover.svelte` = ONE card with view+edit faces anchored beside
+  its pin; `menu/NotesDrawer.svelte` = label groups w/ ‹ › traversal + pins toggle),
+  `SimControls`/`SculptToolbar`/`MeshEditPopup` (#12
   runes-mode HUD pills — the MobileAddButton "own file so onclick doesn't mix with
   on:" precedent; CL-B: the sculpt + mesh-edit toolbars are FLOATING dragWindow
   panels, keys `sculptToolbar`/`meshEditToolbar`), shared
@@ -454,6 +480,37 @@ loadable play content. Everything a user does must be visible to connected peers
   NOT wrapped: `oncreate={(ref) => …}`, never `oncreate={({ref}) => …}` (the destructure
   silently captures `undefined` — this stranded every annotation pin at the origin +
   killed PingMarkers' animations, N1/roadmap-7).
+- **A DOM overlay that must AGREE with a threlte frame may not own a
+  `requestAnimationFrame`** (15-H). threlte's OrbitControls calls
+  `controls.update()` in a task in the MAIN stage; a private rAF is a different
+  callback queue, so whenever it ran first it projected LAST frame's camera and the
+  overlay trailed the geometry by one frame (the note-marker "jiggle"). Project
+  INSIDE the scheduler — `useTask(fn, { stage: renderStage })` from `useScheduler()`,
+  which runs after the main stage — and publish a store the DOM layer renders from.
+  The tell-tale symptom: entering and leaving VR "fixes" it, because XR swaps the
+  loop to `renderer.setAnimationLoop` and threlte re-registers its own rAF
+  afterwards, flipping the callback order.
+- **`OrbitControls.update()` re-derives the camera position from its own spherical
+  state**, so a direct `camera.position.set(...)` is reverted on the next frame (it
+  also means a *test* must never assert the numbers it asked for — park, READ the
+  pose, compare with that). To move the editor camera, go through
+  `objectActions.flyTo` (which also bumps `cameraClaim`, the explicit
+  camera-handover signal in sceneStore) or write BOTH camera and `controls.target`.
+  Continuous camera drivers translate both ends: deviation-watching cannot tell a
+  user PAN from someone else grabbing the view (it would break every pan).
+- An **`<svg>` is a REPLACED element**: `position: fixed; inset: 0` still leaves it
+  at its 300×150 intrinsic box and silently CLIPS every child away — a full-viewport
+  overlay needs explicit `width/height: 100%`.
+- **flowbite's plugin emits `[type='checkbox']:checked { background-color:
+  currentColor !important }`** — no background-color of yours can win the ON state
+  of a custom switch at any specificity (it renders flowbite blue). Drive the fill
+  through `color` instead of fighting it with `!important`.
+- Anything drawn with **`depthWrite: false` loses the postprocessing passes**: the
+  outline and N8AO effects read the depth buffer, so the AO and selection edges of
+  whatever sits BEHIND a non-depth-writing sprite get painted across its face.
+- Grid/pattern FOLLOW must snap by the **section period** (`cell × sectionEvery`),
+  not by one cell: a cell-step translation maps the thin lines onto themselves but
+  hops every THICK line one cell per step (15-H13).
 - WebXR hand joints: read them from threlte's `useHand('left'/'right')` store
   (`.current?.hand.joints[name]` — the SAME XRHand space it renders), keyed by
   HANDEDNESS. Raw `renderer.xr.getHand(SLOT).joints` by app slot index is unreliable (the
@@ -789,6 +846,25 @@ override for e2e — never share 5173 (the user's main-checkout server).
   (open-core: OSS ships only inert hooks — capability gate / auth hook /
   VITE_CLOUD_PLUGIN — cloud repo holds registration/rooms/roles; contract in its
   MAINTAINING.md).
+- Status (2026-08-05): **15-H scene notes v2/v3 COMPLETE** — branch
+  `feat/roadmap15-h-notes-v2` (lane `../theprototype-lane-notes` @ port 5187,
+  branched off `fix/roadmap16-menus-cameras`), 5 commits. (1) v2 model + anchored
+  view/edit popover + drawer label groups w/ ‹ › traversal + pins toggle. (2)
+  follow-ups: two-pass VR pins, per-note shapes, `authorKey` identity, the
+  persistence fixes (annotations now mark the autosave DIRTY — the real "notes
+  disappear on reload" cause — scene-root anchors re-key by name, orphan prune gets
+  a 3s grace) + the grid look-at section-snap fix. (3) markers v3: SCREEN-SPACE
+  badges with leader lines, ONE raycast occlusion verdict per marker with 8cm slack
+  (occluded = dim fill + dashed leader, number stays readable), screen-space
+  clustering, hover tooltip, selected ring, near-camera fade; in-scene meshes became
+  the VR path only. (4) H11: saved camera FRAMING (`camera` on the note) that
+  opening flies to, plus per-viewer follow SESSIONS that outlive the card (sticky
+  indicator toast, Esc, `cameraClaim` handover). (5) follow-on-open switch,
+  `noteDoubleClickToOpen` (single click / drawer arrows only FLY; dblclick opens) +
+  `visitedNote`, and the Esc order (first stops following, second closes the card).
+  Suite `notes-v2` = 90 checks incl. a PROVEN frame-lag guard; baseline 419/62 held
+  throughout. Plan + as-built notes: cloud `plans-core/pending/15-h-notes-v2.md`.
+  Backlog spinoff: a camera follow/look-at NODE for roadmap-16 camera OBJECTS.
 - Status (2026-08-02): **Roadmap #15 in flight — A+J → PR #81, B+C → PR #82,
   second drop K/L/M/N/O + toast-system rework → PR #84 (stacked on #82), docs
   batch I → theprototype-docs.** Shipped in #84: properties-panel PIN +