comments-ux: figma bubble pins, floating panel, seen/reactions/mentions UI, theme follow (0001 A–E + 0002)

- GAL pin = one closed polygon: round body, squared-off bottom-left corner
  ON the anchor; PIN gains unread (accent ring); tuner knobs; shipped
  defaults r9/ring4/alpha.9. DOM hit/highlight sized+offset from a LIVE
  pin-geometry radius store the tuner feeds.
- Floating comments panel: draggable (shared useDraggablePanel with
  always-onscreen restore; overlay FAB retrofitted), collapsible to header,
  header carries add/show-hide/mark-all; unread badges (rose on mention).
- Reactions (emoji-mart lazy, quick-row) + @-mention autocomplete
  (MentionInput; backend roster with presence/author fallback).
- Theme: ?theme= > storage > OS, no-flash boot, toggles (HomePage + overlay
  View row), boot-seeded pcbjam-dark schematic colors + kicadSetColorTheme /
  kicadSetDarkChrome bridges (canvas + wx chrome live flip), light/dark
  variants across all overlay surfaces.
- e2e: panel/seen/reactions/mentions/theme specs + resize-spec geometry;
  bumps pcbjam-shared (flat-key seen/reactions + listCollaborators) and
  wxwidgets (dark chrome) pointers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HLwn1toiNKi1MgxGKnZTes

tests/web/comments-mentions.spec.ts

@@ -0,0 +1,82 @@
+import { test, expect, type Page } from '@playwright/test';
+import { openOverlayMenu } from './overlay-menu';
+
+/**
+ * @-mention e2e (comments-ux 0001 E): with alice and bob live in the same
+ * room, alice types `@b` in the composer → the combobox offers bob (the
+ * presence-roster fallback covers backends without a members model),
+ * keyboard-accepts → `@bob ` lands in the body, the sent message renders a
+ * mention chip, and bob's unread badge takes the mention accent.
+ */
+
+const SCOPE = 'default';
+const ROUTE = 'demo.kicad_sch';
+const TITLE = /demo — Schematic Editor/i;
+
+async function bootAs(page: Page, user: string): Promise<void> {
+  await page.goto(`/${SCOPE}/projects/demo/${ROUTE}?user=${user}`);
+  await expect(page.locator('#canvas')).toBeVisible({ timeout: 120000 });
+  await expect
+    .poll(() => page.title(), { timeout: 120000, intervals: [1000] })
+    .toMatch(TITLE);
+  await openOverlayMenu(page);
+  await expect(page.getByTestId('comment-mode-toggle')).toBeVisible({ timeout: 30000 });
+}
+
+async function deleteAllThreads(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const ctl = (window as unknown as {
+      __pcbjamComments?: {
+        threads(): Array<{ id: string }>;
+        deleteThread(id: string): void;
+      };
+    }).__pcbjamComments;
+    ctl?.threads().forEach((t) => ctl.deleteThread(t.id));
+  });
+  await expect(page.getByTestId('comment-pin')).toHaveCount(0);
+}
+
+test('mentions: autocomplete from the live roster, chip render, mention-accent badge', async ({
+  page,
+  context,
+}) => {
+  test.setTimeout(360000); // two full tool boots
+
+  await bootAs(page, 'alice');
+  await deleteAllThreads(page);
+  const pageB = await context.newPage();
+  await bootAs(pageB, 'bob');
+
+  // Both present: alice's roster knows bob (fallback mention source).
+  await expect(page.getByTestId('overlay-menu-badge')).toHaveText('1', { timeout: 30000 });
+
+  await page.getByTestId('comment-mode-toggle').click();
+  await page.getByTestId('comment-click-catcher').click({ position: { x: 400, y: 250 } });
+  const textarea = page.getByTestId('comment-composer').locator('textarea');
+  await textarea.fill('please check this ');
+  await textarea.press('End');
+  await textarea.pressSequentially('@b');
+
+  const combobox = page.getByTestId('mention-combobox');
+  await expect(combobox).toBeVisible();
+  await expect(combobox.locator('[data-slug="bob"]')).toBeVisible();
+  await textarea.press('Enter'); // accept the selected completion
+  await expect(textarea).toHaveValue('please check this @bob ');
+  await expect(combobox).toHaveCount(0);
+
+  await page.getByTestId('comment-submit').click();
+
+  // The sent message renders the mention as a chip.
+  await expect(page.getByTestId('comment-popover')).toBeVisible();
+  await expect(page.getByTestId('comment-mention')).toHaveText('@bob');
+
+  // bob's unread badge wears the mention accent (rose, not amber).
+  const badgeB = pageB.getByTestId('overlay-menu-unread-badge');
+  await expect(badgeB).toHaveText('1', { timeout: 20000 });
+  await expect(badgeB).toHaveClass(/bg-rose-500/);
+  // …and on bob's side the message chip carries his slug + amber self accent.
+  await pageB.getByTestId('comment-pin').click();
+  await expect(pageB.getByTestId('comment-mention')).toHaveClass(/text-amber-300/);
+
+  await pageB.close();
+});

tests/web/comments-panel.spec.ts

@@ -0,0 +1,129 @@
+import { test, expect, type Page } from '@playwright/test';
+import { openOverlayMenu } from './overlay-menu';
+
+/**
+ * Floating comments panel e2e (comments-ux 0001 B): the list is a draggable
+ * window with its own scrollbar, independent of the overlay menu, with an
+ * always-onscreen restore guarantee (a stored position that no longer fits
+ * the viewport — e.g. a gone secondary display — resets to the default
+ * anchor; live shrinks clamp it back in).
+ */
+
+const SCOPE = 'default';
+const ROUTE = 'demo.kicad_sch';
+const TITLE = /demo — Schematic Editor/i;
+
+async function bootAs(page: Page, user: string): Promise<void> {
+  await page.goto(`/${SCOPE}/projects/demo/${ROUTE}?user=${user}`);
+  await expect(page.locator('#canvas')).toBeVisible({ timeout: 120000 });
+  await expect
+    .poll(() => page.title(), { timeout: 120000, intervals: [1000] })
+    .toMatch(TITLE);
+  await openOverlayMenu(page);
+  await expect(page.getByTestId('comment-mode-toggle')).toBeVisible({ timeout: 30000 });
+}
+
+async function resetComments(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const ctl = (window as unknown as {
+      __pcbjamComments?: {
+        threads(): Array<{ id: string }>;
+        deleteThread(id: string): void;
+        create(anchor: { pos: { x: number; y: number } }, body: string): string;
+      };
+    }).__pcbjamComments;
+    ctl?.threads().forEach((t) => ctl.deleteThread(t.id));
+  });
+  await expect(page.getByTestId('comment-pin')).toHaveCount(0);
+}
+
+function createThread(page: Page, body: string, x: number): Promise<void> {
+  return page.evaluate(
+    ([bodyText, wx]) => {
+      const ctl = (window as unknown as {
+        __pcbjamComments: {
+          create(anchor: { pos: { x: number; y: number } }, body: string): string;
+        };
+      }).__pcbjamComments;
+      ctl.create({ pos: { x: Number(wx), y: 0 } }, String(bodyText));
+    },
+    [body, String(x)],
+  );
+}
+
+test('floating panel: open, scroll, drag, offscreen-reset, clamp', async ({ page }) => {
+  test.setTimeout(300000); // one full tool boot
+
+  await bootAs(page, 'alice');
+  await resetComments(page);
+
+  for (let i = 0; i < 12; i++) await createThread(page, `note ${i}`, i * 100000);
+
+  // A stored position from a "bigger display" must NOT be honored: the panel
+  // opens at its default anchor instead. (Legacy px entry deliberately.)
+  await page.evaluate(() =>
+    localStorage.setItem('pcbjam:comments-panel-pos', JSON.stringify({ x: 5000, y: 120 })),
+  );
+
+  await openOverlayMenu(page);
+  await page.getByTestId('comment-panel-toggle').click();
+  const panel = page.getByTestId('comments-panel');
+  await expect(panel).toBeVisible();
+  await expect(page.getByTestId('comment-panel-item')).toHaveCount(12);
+
+  const vp = page.viewportSize()!;
+  let box = (await panel.boundingBox())!;
+  expect(box.x + box.width).toBeLessThanOrEqual(vp.width + 1);
+  expect(box.x).toBeGreaterThanOrEqual(-1);
+
+  // The list scrolls inside the panel (12 rows > max height).
+  const scrollable = await page
+    .getByTestId('comments-panel-list')
+    .evaluate((el) => el.scrollHeight > el.clientHeight);
+  expect(scrollable).toBe(true);
+
+  // Header carries the primary comment actions: "+" arms comment mode
+  // (click catcher appears), the eye hides the pin hit targets.
+  await page.getByTestId('comments-panel-add').click();
+  await expect(page.getByTestId('comment-click-catcher')).toBeVisible();
+  await page.getByTestId('comments-panel-add').click(); // cancel again
+  await expect(page.getByTestId('comment-click-catcher')).toHaveCount(0);
+  await page.getByTestId('comments-panel-pins').click();
+  await expect(page.getByTestId('comment-pin')).toHaveCount(0);
+  await page.getByTestId('comments-panel-pins').click();
+  // ≥1, not 12: pins whose anchors fall outside the viewport render no DOM
+  // hit target (culling), and the fit depends on the demo sheet.
+  await expect(page.getByTestId('comment-pin').first()).toBeVisible();
+
+  // Collapse to header-only; the state survives close/reopen.
+  await page.getByTestId('comments-panel-collapse').click();
+  await expect(page.getByTestId('comments-panel-list')).toHaveCount(0);
+  await expect(page.getByTestId('comments-panel-header')).toBeVisible();
+  await page.getByTestId('comments-panel-collapse').click();
+  await expect(page.getByTestId('comments-panel-list')).toBeVisible();
+
+  // Drag by the header to a chosen spot.
+  const header = page.getByTestId('comments-panel-header');
+  const hb = (await header.boundingBox())!;
+  await page.mouse.move(hb.x + 40, hb.y + hb.height / 2);
+  await page.mouse.down();
+  await page.mouse.move(120, 300, { steps: 5 });
+  await page.mouse.up();
+  box = (await panel.boundingBox())!;
+  expect(box.y).toBeGreaterThan(200);
+  expect(box.x).toBeLessThan(200);
+
+  // Live viewport shrink clamps the handle back onscreen.
+  await page.setViewportSize({ width: 700, height: 400 });
+  await expect
+    .poll(async () => {
+      const b = (await panel.boundingBox())!;
+      return b.x >= 0 && b.y >= 0 && b.x + 288 <= 700 + 1 && b.y + 36 <= 400 + 1;
+    })
+    .toBe(true);
+
+  // Close persists; the open state itself is storage-backed.
+  await page.getByTestId('comments-panel-close').click();
+  await expect(panel).toHaveCount(0);
+  expect(await page.evaluate(() => localStorage.getItem('pcbjam:comments-panel-open'))).toBe('0');
+});

tests/web/comments-reactions.spec.ts

@@ -0,0 +1,86 @@
+import { test, expect, type Page } from '@playwright/test';
+import { openOverlayMenu } from './overlay-menu';
+
+/**
+ * Emoji reactions e2e (comments-ux 0001 D): quick-row toggle on/off, two
+ * users reacting with the same emoji both counted (flat own-key writes — no
+ * LWW clobber), and the lazy full picker mounting on demand.
+ */
+
+const SCOPE = 'default';
+const ROUTE = 'demo.kicad_sch';
+const TITLE = /demo — Schematic Editor/i;
+
+async function bootAs(page: Page, user: string): Promise<void> {
+  await page.goto(`/${SCOPE}/projects/demo/${ROUTE}?user=${user}`);
+  await expect(page.locator('#canvas')).toBeVisible({ timeout: 120000 });
+  await expect
+    .poll(() => page.title(), { timeout: 120000, intervals: [1000] })
+    .toMatch(TITLE);
+  await openOverlayMenu(page);
+  await expect(page.getByTestId('comment-mode-toggle')).toBeVisible({ timeout: 30000 });
+}
+
+async function deleteAllThreads(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const ctl = (window as unknown as {
+      __pcbjamComments?: {
+        threads(): Array<{ id: string }>;
+        deleteThread(id: string): void;
+      };
+    }).__pcbjamComments;
+    ctl?.threads().forEach((t) => ctl.deleteThread(t.id));
+  });
+  await expect(page.getByTestId('comment-pin')).toHaveCount(0);
+}
+
+test('reactions: quick-row toggle, concurrent same-emoji, lazy full picker', async ({
+  page,
+  context,
+}) => {
+  test.setTimeout(360000); // two full tool boots
+
+  await bootAs(page, 'alice');
+  await deleteAllThreads(page);
+  const pageB = await context.newPage();
+  await bootAs(pageB, 'bob');
+
+  // alice creates and keeps the popover open.
+  await page.getByTestId('comment-mode-toggle').click();
+  await page.getByTestId('comment-click-catcher').click({ position: { x: 400, y: 250 } });
+  await page.getByTestId('comment-composer').locator('textarea').fill('react to me');
+  await page.getByTestId('comment-submit').click();
+  await expect(page.getByTestId('comment-popover')).toBeVisible();
+
+  // alice: 👍 via the quick row ("add reaction" shows on message hover).
+  await page.getByTestId('comment-message').hover();
+  await page.getByTestId('comment-react').click();
+  await page.getByTestId('comment-quick-react').locator('[data-emoji="👍"]').click();
+  const chip = page.getByTestId('comment-reaction-chip');
+  await expect(chip).toHaveCount(1);
+  await expect(chip).toContainText('1');
+
+  // bob opens the same thread and clicks the existing chip → count 2 in BOTH.
+  await expect(pageB.getByTestId('comment-pin')).toHaveCount(1, { timeout: 20000 });
+  await pageB.getByTestId('comment-pin').click();
+  const chipB = pageB.getByTestId('comment-reaction-chip');
+  await expect(chipB).toContainText('1', { timeout: 20000 });
+  await chipB.click();
+  await expect(chipB).toContainText('2', { timeout: 20000 });
+  await expect(chip).toContainText('2', { timeout: 20000 });
+
+  // Toggle off (bob) → back to 1 everywhere.
+  await chipB.click();
+  await expect(chip).toContainText('1', { timeout: 20000 });
+
+  // Full picker: quick row's "+" mounts the lazy emoji-mart chunk.
+  await page.getByTestId('comment-message').hover();
+  await page.getByTestId('comment-react').click();
+  await page.getByTestId('comment-react-more').click();
+  await expect(page.getByTestId('emoji-picker')).toBeVisible();
+  await expect(page.locator('em-emoji-picker')).toBeVisible({ timeout: 30000 });
+  await page.keyboard.press('Escape');
+  await expect(page.getByTestId('emoji-picker')).toHaveCount(0);
+
+  await pageB.close();
+});

tests/web/comments-seen.spec.ts

@@ -0,0 +1,93 @@
+import { test, expect, type Page } from '@playwright/test';
+import { openOverlayMenu } from './overlay-menu';
+
+/**
+ * Seen/unread e2e (comments-ux 0001 C): alice comments → bob's FAB grows an
+ * unread badge and the panel row an unread dot; opening the thread clears
+ * them (event-driven mark-seen — popover open, own writes); a reply re-arms
+ * alice's badge, and "mark all as seen" clears it without opening.
+ */
+
+const SCOPE = 'default';
+const ROUTE = 'demo.kicad_sch';
+const TITLE = /demo — Schematic Editor/i;
+
+async function bootAs(page: Page, user: string): Promise<void> {
+  await page.goto(`/${SCOPE}/projects/demo/${ROUTE}?user=${user}`);
+  await expect(page.locator('#canvas')).toBeVisible({ timeout: 120000 });
+  await expect
+    .poll(() => page.title(), { timeout: 120000, intervals: [1000] })
+    .toMatch(TITLE);
+  await openOverlayMenu(page);
+  await expect(page.getByTestId('comment-mode-toggle')).toBeVisible({ timeout: 30000 });
+}
+
+async function deleteAllThreads(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const ctl = (window as unknown as {
+      __pcbjamComments?: {
+        threads(): Array<{ id: string }>;
+        deleteThread(id: string): void;
+      };
+    }).__pcbjamComments;
+    ctl?.threads().forEach((t) => ctl.deleteThread(t.id));
+  });
+  await expect(page.getByTestId('comment-pin')).toHaveCount(0);
+}
+
+test('unread badges: create → badge for the peer only → open clears → reply re-arms → mark-all', async ({
+  page,
+  context,
+}) => {
+  test.setTimeout(360000); // two full tool boots
+
+  await bootAs(page, 'alice');
+  await deleteAllThreads(page);
+  const pageB = await context.newPage();
+  await bootAs(pageB, 'bob');
+
+  // alice creates via comment mode (own write = auto-seen for alice).
+  await page.getByTestId('comment-mode-toggle').click();
+  await page.getByTestId('comment-click-catcher').click({ position: { x: 400, y: 250 } });
+  await page.getByTestId('comment-composer').locator('textarea').fill('unseen by bob');
+  await page.getByTestId('comment-submit').click();
+  await expect(page.getByTestId('comment-popover')).toBeVisible();
+
+  // bob: FAB unread badge + menu-row badge + panel unread dot. alice: none.
+  await expect(pageB.getByTestId('overlay-menu-unread-badge')).toHaveText('1', {
+    timeout: 20000,
+  });
+  await expect(page.getByTestId('overlay-menu-unread-badge')).toHaveCount(0);
+
+  await openOverlayMenu(pageB);
+  await expect(pageB.getByTestId('comment-unread-badge')).toHaveText('1');
+  await pageB.getByTestId('comment-panel-toggle').click();
+  await expect(pageB.getByTestId('comment-unread-dot')).toHaveCount(1);
+
+  // Opening the thread marks it seen — badges and dot clear, GAL pins get
+  // unread=false (asserted indirectly: the DOM state is the driver).
+  await pageB.getByTestId('comment-pin').click();
+  await expect(pageB.getByTestId('comment-popover')).toBeVisible();
+  await expect(pageB.getByTestId('overlay-menu-unread-badge')).toHaveCount(0, {
+    timeout: 20000,
+  });
+  await expect(pageB.getByTestId('comment-unread-dot')).toHaveCount(0);
+
+  // bob replies from his open popover → alice (popover closed first) unreads.
+  await page.getByTestId('comment-popover').getByTitle('Close').click();
+  await pageB.getByTestId('comment-reply').fill('now you have mail');
+  await pageB.getByTestId('comment-reply').press('Enter');
+  await expect(page.getByTestId('overlay-menu-unread-badge')).toHaveText('1', {
+    timeout: 20000,
+  });
+
+  // "Mark all as seen" from alice's panel header clears without opening.
+  await openOverlayMenu(page);
+  await page.getByTestId('comment-panel-toggle').click();
+  await page.getByTestId('comments-mark-all-seen').click();
+  await expect(page.getByTestId('overlay-menu-unread-badge')).toHaveCount(0, {
+    timeout: 20000,
+  });
+
+  await pageB.close();
+});

tests/web/comments-viewport-resize.spec.ts

@@ -67,8 +67,13 @@ async function pinDelta(page: Page): Promise<{ dx: number; dy: number }> {
     const r = gl.getBoundingClientRect();
     const ratio = r.width / vp.w;
     const world = win.__pcbjamComments.threads()[0].world;
-    const truthX = r.x + ((world.x - vp.cx) * vp.scale + vp.w / 2) * ratio;
-    const truthY = r.y + ((world.y - vp.cy) * vp.scale + vp.h / 2) * ratio;
+    // Bubble-pin geometry (comments-ux 0001 A): the DOM target centers on the
+    // bubble BODY at anchor + (r, -r) — the anchored point is the bubble's
+    // sharp bottom-left corner. Keep in sync with standalone
+    // src/wasm/collab/pin-geometry.ts (PIN_RADIUS_PX).
+    const bubbleR = 9 * ratio;
+    const truthX = r.x + ((world.x - vp.cx) * vp.scale + vp.w / 2) * ratio + bubbleR;
+    const truthY = r.y + ((world.y - vp.cy) * vp.scale + vp.h / 2) * ratio - bubbleR;
     const pin = document.querySelector('[data-testid="comment-pin"]') as HTMLElement;
     const pr = pin.getBoundingClientRect();
     return { dx: pr.x + pr.width / 2 - truthX, dy: pr.y + pr.height / 2 - truthY };

tests/web/theme.spec.ts

@@ -0,0 +1,36 @@
+import { test, expect } from '@playwright/test';
+
+/**
+ * Standalone theme follow e2e (comments-ux 0002): resolution precedence
+ * (?theme= param > storage > OS), no-flash application before first paint,
+ * persistence across a param-less reload, and the shell toggle. Kept on the
+ * HOME page — no tool boot needed; the canvas half (seeded KiCad color theme
+ * + the kicadSetColorTheme bridge) is covered by unit seeding assertions and
+ * manual Firefox verification per the standalone UI workflow.
+ */
+
+test('?theme=dark applies before paint, persists, and the toggle flips it', async ({ page }) => {
+  await page.goto('/?theme=dark', { waitUntil: 'domcontentloaded' });
+  // The inline boot script ran before first paint — no React needed yet.
+  await expect(page.locator('html')).toHaveClass(/dark/);
+
+  // The param persisted; a param-less reload stays dark.
+  await page.goto('/');
+  await expect(page.locator('html')).toHaveClass(/dark/);
+  expect(await page.evaluate(() => localStorage.getItem('pcbjam-theme'))).toBe('dark');
+
+  // Shell toggle flips class + storage.
+  await page.getByTestId('theme-toggle').click();
+  await expect(page.locator('html')).not.toHaveClass(/dark/);
+  expect(await page.evaluate(() => localStorage.getItem('pcbjam-theme'))).toBe('light');
+
+  // A later ?theme= wins over the stored choice.
+  await page.goto('/?theme=dark', { waitUntil: 'domcontentloaded' });
+  await expect(page.locator('html')).toHaveClass(/dark/);
+});
+
+test('invalid ?theme= falls back to the stored/OS preference', async ({ page }) => {
+  await page.emulateMedia({ colorScheme: 'light' });
+  await page.goto('/?theme=purple', { waitUntil: 'domcontentloaded' });
+  await expect(page.locator('html')).not.toHaveClass(/dark/);
+});