Address Phase 4 UX review (document annotations)

Changes for the UX review items on PAP-9436:

- Highlights are now translucent boxes with state-specific outlines instead
  of baseline borders. Focused open anchors get a 2px primary outline plus
  fill so they read as a real "lift"; stale anchors get a dashed amber
  outline plus a ⚠ glyph at the run end; resolved anchors stay dashed and
  dim.
- Document count chip lives inside the document header row (next to the
  rev/updated chrome) via a new DocumentAnnotationsCountChip component, so
  it stays visible while the document is folded and conforms to neighbor
  rhythm. IssueDocumentAnnotations now exposes only the body wrapper +
  side panel and accepts controlled panelOpen state from the section.
- Comment authors render as `<name> · <role>` (e.g. `Dotta · board`,
  `UXDesigner · agent`) using the same agentMap / userProfileMap that
  IssueDetail already builds for IssueComments. Maps flow through
  IssueDocumentsSection → IssueDocumentAnnotations → DocumentAnnotationPanel.
- Side panel header drops the duplicate "PLAN" pill — the doc key already
  brought the user here. Header now reads `Comments / rev N`.
- Filter chips are real low-contrast chips (rounded ghost buttons with an
  active background tint) instead of three-weight Button variants.
- Thread action row is now Resolve (secondary) + Reply (primary), with
  Copy link collapsed into a `…` overflow dropdown.
- Persistent "+ New comment on selection" CTA pinned to the bottom of the
  panel with a ⌘⇧M keyboard shortcut. The CTA disables itself when a draft
  is dirty / conflicted / previewing history, matching the same gate the
  body selection toolbar already enforced.
- ThreadCard expanded state now uses `ring-1 ring-ring/70` rather than
  `border-primary/60` so the focus affordance is the standard
  design-system ring.
- Mobile bottom sheet is now the real shadcn Sheet (`SheetContent
  side="bottom"`) — backdrop, focus trap, drag handle, motion all come
  from the primitive.
- IssueDocumentsSection accepts storybook-only seeds
  (`defaultAnnotationPanelOpenKeys`, `defaultAnnotationFocusedThreadIds`,
  `forceEditDocumentKey`) so we can capture deterministic integrated
  screenshots instead of Storybook-isolated panel mocks.
- New integrated Storybook stories render the real IssueDocumentsSection
  chrome at 1440×900 desktop + 390×844 mobile, with edit-mode and dirty-
  draft variants. Stale state-only stories kept for visual debugging.
- design/PAP-9436-doc-annotation-ui/screenshots/ refreshed: the old
  Storybook-isolated captures are removed; 5 new integrated captures
  (01–05) replace them, and 4 isolated state captures (10–13) remain for
  reference.

Tests:
- Existing unit tests updated to the controlled-panel contract; new tests
  cover author identity rendering (`<name> · <role>`) and the persistent
  CTA.
- `pnpm vitest run` over the annotation surface (4 files, 23 tests) green.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

scripts/screenshot-doc-annotations.mjs

@@ -54,29 +54,41 @@ async function main() {
   const browser = await chromium.launch();
   try {
     const stories = [
-      { id: "product-documents-annotations--desktop-open-focused", file: "01-desktop-open-focused.png", width: 1280, height: 900 },
-      { id: "product-documents-annotations--desktop-resolved-focused", file: "02-desktop-resolved-focused.png", width: 1280, height: 900 },
-      { id: "product-documents-annotations--desktop-stale-focused", file: "03-desktop-stale-focused.png", width: 1280, height: 900 },
-      { id: "product-documents-annotations--desktop-orphaned-focused", file: "04-desktop-orphaned-focused.png", width: 1280, height: 900 },
-      { id: "product-documents-annotations--dirty-draft-disables-new-comments", file: "05-dirty-draft-disabled.png", width: 720, height: 720 },
-      { id: "product-documents-annotations--mobile-bottom-sheet-view", file: "06-mobile-bottom-sheet.png", width: 375, height: 812 },
+      // INTEGRATED — these are the captures the UX gate requires. They render
+      // IssueDocumentsSection chrome (count chip in header row, body + side panel
+      // wired together, edit mode wrapping the layer, real shadcn Sheet on mobile).
+      { id: "product-documents-annotations--integrated-desktop-open", file: "01-integrated-desktop-open.png", width: 1440, height: 900 },
+      { id: "product-documents-annotations--integrated-desktop-zero-comments", file: "02-integrated-desktop-zero-count.png", width: 1440, height: 900 },
+      { id: "product-documents-annotations--integrated-desktop-edit-mode", file: "03-integrated-desktop-edit-mode.png", width: 1440, height: 900 },
+      { id: "product-documents-annotations--integrated-desktop-dirty-draft", file: "04-integrated-desktop-dirty-draft.png", width: 1440, height: 900 },
+      { id: "product-documents-annotations--integrated-mobile-bottom-sheet", file: "05-integrated-mobile-sheet.png", width: 390, height: 844 },
+      // ISOLATED — kept around for visual debugging of state pieces.
+      { id: "product-documents-annotations--desktop-open-focused", file: "10-states-open-focused.png", width: 1280, height: 900 },
+      { id: "product-documents-annotations--desktop-resolved-focused", file: "11-states-resolved-focused.png", width: 1280, height: 900 },
+      { id: "product-documents-annotations--desktop-stale-focused", file: "12-states-stale-focused.png", width: 1280, height: 900 },
+      { id: "product-documents-annotations--desktop-orphaned-focused", file: "13-states-orphaned-focused.png", width: 1280, height: 900 },
     ];
 
+    const themeArg = (process.env.SCREENSHOT_THEME || "dark").toLowerCase();
+    const theme = themeArg === "light" ? "light" : "dark";
+
     for (const story of stories) {
       const ctx = await browser.newContext({
         viewport: { width: story.width, height: story.height },
         deviceScaleFactor: 2,
-        colorScheme: "light",
+        colorScheme: theme,
       });
       const page = await ctx.newPage();
-      const url = `${baseUrl}?id=${story.id}&viewMode=story`;
+      const url = `${baseUrl}?id=${story.id}&viewMode=story&globals=theme:${theme}`;
       await page.goto(url, { waitUntil: "networkidle" });
-      await page.evaluate(() => {
-        document.documentElement.style.colorScheme = "light";
-      });
-      await page.waitForTimeout(700);
+      await page.evaluate((appliedTheme) => {
+        document.documentElement.classList.toggle("dark", appliedTheme === "dark");
+        document.documentElement.style.colorScheme = appliedTheme;
+      }, theme);
+      // Allow async query prefill + the layer's interval-driven layout pass to settle.
+      await page.waitForTimeout(900);
       const out = path.join(outDir, story.file);
-      await page.screenshot({ path: out, fullPage: true });
+      await page.screenshot({ path: out, fullPage: false });
       console.log("wrote", out);
       await ctx.close();
     }