@plannotator/ui 0.30.0 → 0.32.0

package/README.md

@@ -27,6 +27,9 @@ configurePlannotatorUI({
   skillCatalogTransport,       // skill-reference catalog for comment composers
   skillContentTransport,       // human-only skill contents for feedback injection
   serverSync,
+  webmcp,                      // browser-agent (WebMCP) provider policy: { enabled, namePrefix }
+  mathRendererLoader,          // how KaTeX loads when no renderer is registered before first math render
+  identityGenerator,           // sync generator behind the default "tater" name (no identityProvider)
 });
 ```
 
@@ -47,6 +50,16 @@ The sidebar/panel resize handle exposes seams for hosts that want different edge
 
 Building your own tooltip and removing the built-in double-click reset are host-side concerns (override `onDoubleClick` where you render the handle).
 
+### Lazy renderers and the eager entries (`utils/math`, `utils/generateIdentity`, `utils/mermaid`; 0.32.0)
+
+The Mermaid runtime, the Graphviz engine, KaTeX and the username dictionary are off the static import graph of `Viewer`, so a host that bundles by route does not download them for a plain markdown read. Graphviz needs nothing from you (the block imports the engine inside its render effect and shows the source fence until the SVG lands, as it always did). Mermaid, KaTeX and the dictionary sit behind synchronous slots:
+
+- **Math.** Without registration, a math node renders its TeX as text in the same wrapper (same `data-math-tex` / `data-math-display` / `aria-label` / class names), loads KaTeX via `import('katex')`, and re-renders typeset. To keep math typeset on the very first commit, as Plannotator does, add one line to your entry: `import "@plannotator/ui/utils/math-eager";`. To put KaTeX and its stylesheet on one lazy chunk instead, pass `mathRendererLoader`. The stylesheet remains your job either way (see "Consuming it", step 3).
+- **Mermaid.** Without registration, the first diagram on a page fetches the runtime through `import('mermaid')`; a failed import is dropped from the memo, re-attempted once after a short delay, and the error panel (with the source) offers Retry, which issues another fresh attempt. Plannotator keeps Mermaid eager by policy so it can never fail separately from the app: `import "@plannotator/ui/utils/mermaid-eager";` in your entry does the same for your bundle. Honest limit of any in-page retry: a browser records a failed module fetch in its module map for the page lifetime, so a fresh `import()` of the same chunk URL rejects without a request; the retry recovers failures after the fetch (engine instantiation, initialize) and hosts that version chunk URLs. A host that needs recovery from a failed first fetch uses versioned chunk URLs or a `vite:preloadError` reload at app level.
+- **Identity.** With an `identityProvider` the generator is never called and the word lists stay out of your bundle. Without one, default names come from a small built-in pool of the same `adjective-noun-tater` shape; `import "@plannotator/ui/utils/identity-tater";` registers the full dictionary, or pass your own `identityGenerator`.
+
+Plannotator's own entries import the eager modules (`math-eager` and `identity-tater` in both `packages/editor/App.tsx` and `packages/review-editor/App.tsx`; `mermaid-eager` in the plan editor only, since the review editor never renders a Mermaid block), which is what keeps its single-file builds byte-identical and its portal entry chunk shaped as before; `tests/entry-assets.test.ts` fails if any of them is dropped. See HANDOFF.md "Lazy renderers and eager entries".
+
 ### Markdown editor extensions + wiki links (`MarkdownEditor` / `InlineMarkdown`)
 
 - **`MarkdownEditor` takes CM6 extensions.** `extensions?: readonly Extension[]` (from `@codemirror/state`) is forwarded verbatim into the underlying editor — the seam for `wikiLinks(config)`, `y-codemirror.next` collab bindings, custom keymaps.
@@ -60,6 +73,7 @@ Building your own tooltip and removing the built-in double-click reset are host-
   const editorExtensions = [wikiLinks({ suggest, resolve, onOpen })]; // stable reference!
   <MarkdownEditor markdown={md} documentId={docId} editorHandleRef={ref} extensions={editorExtensions} />
   ```
+- **`embedPicker(config)` and `embedSlashItem()` are re-exported from the same surface.** Compose the static item into `slashCommands({ items: [...] })` and pass the picker beside it in the stable `extensions` array. `getTargets`, `buildInsertLine`, optional `uploadTarget`, and optional `getNotice` stay live through callbacks. The host owns embed grammar and upload error UI; the package owns filtering, async anchor mapping, single-flight upload state, and paragraph-safe insertion through the re-exported `planEmbedInsert()`.
 - **The viewer resolves wiki-links synchronously.** `InlineMarkdown` takes `resolveLinkedDoc?: (target) => { label?; status?: 'active' | 'deleted' } | null` — called with the raw stored target (opaque ids like `doc_01XYZ`, no `.md` normalization). Return a `label` to display live titles (stored label is the fallback, target the last resort); return `status: 'deleted'` for a muted non-link ("Document deleted") instead of a live link. Absent or `null` → rendering is unchanged. Sync-only by design: back it with an in-memory cache.
 
 Requires `@plannotator/markdown-editor ^0.3.2` and `@plannotator/atomic-editor ^0.7.0`. See HANDOFF.md § "Wiki-link seams (0.27.0)".
@@ -84,6 +98,37 @@ Requires `@plannotator/markdown-editor ^0.4.0` and `@plannotator/atomic-editor ^
 
 `components/html-viewer` is supported host surface as of 0.29.0: the overlay-projection annotation viewer for raw HTML (placed comment markers, pinpoint element anchors, shift-click multi-target comments). Its contract is **props plus the validated iframe message protocol** — not `configurePlannotatorUI()`, which only governs the backend surfaces around it. Drive the `annotations` prop (marker numbering derives from its array order); `readOnly` keeps markers painted and clickable while disabling all authoring. **0.29.0 also carries a breaking migration:** highlight.js is gone and `.hljs` selectors are inert — style code via the exported `pn-code` class (`CODE_BLOCK_CLASS` in `utils/codeHighlight`). See HANDOFF.md § "Raw-HTML annotation viewer + syntax-highlighting migration (0.29.0)" before upgrading from 0.28.0.
 
+#### HTML annotation parity seams (0.32.0)
+
+Everything a host needs around `HtmlViewer` to match Plannotator's HTML annotation experience, all additive and all defaulting to today's behavior. Requires `@plannotator/core` 0.25.0 (the `html-anchor` subpath), so install and publish core before ui:
+
+- **`projectHostThreads(threads, { openOnly?, documentLevel?, maxTargets? })`** and **`buildPersistedHtmlAnchor(source, { maxBytes?, maxTargets? })`** from `components/html-viewer` (pure, from `@plannotator/core/html-anchor`): project stored rows onto the `annotations` prop in the order that becomes the marker numbering, and trim a composed comment's anchor for persistence with cap drops and size drops reported separately. A row with nothing restorable projects as a document-level `GLOBAL_COMMENT` by default (`documentLevel: 'global'`, never reported as unanchored) or, with `documentLevel: 'unanchored'`, as a textless page `COMMENT` the unanchored report names.
+- **`onUnanchoredChange`** is keyed to the bridge's restore (one complete report per document after the restore batch, the empty set included) and complete over the `annotations` prop: textless page rows are reported without being posted, and a locally minted id the host swapped out of its list is not. It replaces a host's `mark-applied` bookkeeping for the unanchored set; the local-to-server mark swap itself stays host-side.
+- **`hooks/useHtmlRefresh({ fetchSnapshot, onSnapshot, onUnanchored?, onResult? })`**: the refresh cycle with the stale-response and document-change guards, backend behind `fetchSnapshot`.
+- **`components/HtmlSurfaceControls`**: the eye / refresh / pen header controls with Plannotator's markup and `labels` overrides.
+- **`AnnotationPanel` `unanchoredIds`**: an "Unanchored" chip on the listed cards.
+- **`HtmlViewer` `scrollBehavior`** (`'auto'` for reduced motion) and **`maxAdditionalTargets`** (a product cap the bridge honors too).
+- An `ExternalAnnotationTransport` whose `subscribe` emits `snapshot` on a host push keeps `useExternalAnnotations` off its fallback poll.
+
+See HANDOFF.md § "HTML annotation parity seams".
+
+#### Also blessed in 0.32.0: `shortcuts` and `utils/inputMethod`
+
+- **`@plannotator/ui/shortcuts`**: the declarative keyboard-shortcut engine (`defineShortcutScope`, `useShortcutScope`) and the per-surface scopes, including `useHtmlAnnotateShortcuts` for the Mod+Shift+A Annotate/Interact chord on HTML surfaces. Pure React plus `utils/platform`; no backend.
+- **`@plannotator/ui/utils/inputMethod`**: `getInputMethod(surface)` / `saveInputMethod(method, surface)` / `refreshInputMethodStamp(method)`, the per-surface pinpoint-or-drag preference with its TTL, persisted through the `storageBackend` seam.
+
+### WebMCP provider (`@plannotator/ui/webmcp`; 0.32.0)
+
+The engine that lets a browser-integrated agent (Chrome/Edge WebMCP, `document.modelContext`) call in-page tools on a document surface. Feature-detected once; a browser without the API sees no registration, no DOM, no network, no timers. Seam: `configurePlannotatorUI({ webmcp: { enabled, namePrefix } })`, default enabled with the `plannotator.` prefix; pass `enabled: false` to keep a host page tool-free, or your own prefix to namespace the tools beside your own. There is deliberately no confirmation seam: the catalog is read-and-comment only (no approve / submit / close tools), and the agent may only edit or remove comments stamped `source: "browser-agent"`.
+
+- `modelContext.ts` is the only file that spells the spec surface (local structural types, no `webmcp-types` dependency). A spec rename is a one-file change.
+- `useToolset({ id, active, build, deps, hooks })` attaches a named tool set to the document registry; handlers read through refs, so re-renders never re-register, and `active: false` aborts every registration (what Plannotator's Settings opt-out drives).
+- `AnnotationChangeTracker` / `buildNudges` are pure (no DOM): per-annotation `seq`, tombstones, a per-tab watermark with `since` override, and the nudge vocabulary every response carries.
+- A host with its own document state builds the same adapter-driven catalog Plannotator uses (`packages/editor/webmcp/documentTools.ts`, `buildDocumentTools(adapter, state, options)`) over its own getters and actions; multi-document pages should register one set whose tools take `path` (the folder-session shape) rather than one set per viewer (duplicate names across sets are skipped with a warning, never replaced).
+- Never register tools inside an untrusted iframe: the raw-HTML viewer's `sandbox="allow-scripts"` frame and the live-app frame carry no `allow="tools"`, and that is what keeps a framed page from impersonating the host's tools.
+
+The one additive data-model change that rides with it: `Annotation.inReplyTo` (threaded replies; the panel indents them under the parent, the export nests them, share links drop them).
+
 ## Consuming it (e.g. from Workspaces)
 
 ```bash
@@ -107,7 +152,7 @@ npm install @plannotator/ui @plannotator/core
 - `@plannotator/core` — pure utils + types, zero deps, browser-safe (CI enforces no `node:` imports). Published.
 - `@plannotator/ui` — React components/hooks + theme + `configure()`. Depends on `@plannotator/core` (exact-version lockstep). Published.
 - `@plannotator/shared`, `@plannotator/ai` — stay private to the monorepo; `shared` re-exports `core`'s modules via shims so Plannotator's internals are untouched.
-- Versioned in lockstep with the repo. Publish `core` then `ui`: build each tarball with **`bun pm pack`** (resolves `workspace:*` to the exact version at pack time), then **`npm publish *.tgz --provenance --access public`** — the repo's existing flow.
+- Versioned in lockstep with the repo (currently `@plannotator/core` 0.25.0 with `@plannotator/ui` 0.32.0). Publish `core` then `ui`: build each tarball with **`bun pm pack`** (resolves `workspace:*` to the exact version at pack time, from `bun.lock`, so run `bun install` after a bump), then **`npm publish *.tgz --provenance --access public`** — the repo's existing flow (`--provenance` needs CI OIDC; local publishes drop it, see HANDOFF.md "Publishing & versioning").
 
 ## The one rule
 

package/components/ActionMenu.tsx

@@ -68,6 +68,7 @@ interface ActionMenuItemProps {
   label: string;
   subtitle?: string;
   badge?: React.ReactNode;
+  disabled?: boolean;
 }
 
 export const ActionMenuItem: React.FC<ActionMenuItemProps> = ({
@@ -76,10 +77,14 @@ export const ActionMenuItem: React.FC<ActionMenuItemProps> = ({
   label,
   subtitle,
   badge,
+  disabled = false,
 }) => (
   <button
+    data-pn-touch-target
+    type="button"
     onClick={onClick}
-    className="flex w-full items-center gap-2 px-3 py-2 text-left text-xs transition-colors hover:bg-muted"
+    disabled={disabled}
+    className="flex w-full items-center gap-2 px-3 py-2 text-left text-xs transition-colors hover:bg-muted disabled:cursor-not-allowed disabled:opacity-45 disabled:hover:bg-transparent"
   >
     <span className="text-muted-foreground">{icon}</span>
     {subtitle ? (

package/components/AgentsTab.tsx

@@ -15,6 +15,7 @@ import {
 } from 'lucide-react';
 import type { AgentJobInfo, AgentCapabilities } from '../types';
 import { isTerminalStatus } from '@plannotator/core/agent-jobs';
+import { GUIDE_ENGINE_LABEL } from '@plannotator/core/guide';
 import { cn } from '../lib/utils';
 import { ReviewAgentsIcon } from './ReviewAgentsIcon';
 import { ClaudeIcon, CodexIcon, CopilotIcon, CursorIcon, OpenCodeIcon, PiIcon } from './icons/AgentIcons';
@@ -127,14 +128,7 @@ const ENGINE_ICON: Record<AgentEngine, React.FC<{ className?: string }>> = {
 // review surface offers the wider set (Cursor/OpenCode). Exported so the guide
 // takeover surfaces (GuideScreen, GuideEmptyState in packages/review-editor)
 // share this one source of truth instead of keeping their own copies in sync.
-export const REVIEW_ENGINE_LABEL: Record<ReviewEngine, string> = {
-  claude: 'Claude',
-  codex: 'Codex',
-  cursor: 'Cursor',
-  opencode: 'OpenCode',
-  pi: 'Pi',
-  copilot: 'Copilot',
-};
+export const REVIEW_ENGINE_LABEL: Record<ReviewEngine, string> = GUIDE_ENGINE_LABEL;
 
 // Review-only icon map — the wide set. Tour keeps the narrow ENGINE_ICON.
 const REVIEW_ENGINE_ICON: Record<ReviewEngine, React.FC<{ className?: string }>> = {
@@ -872,7 +866,12 @@ export const AgentsTab: React.FC<AgentsTabProps> = ({
       ? { effort: tourClaudeEffort }
       : { reasoningEffort: tourCodexReasoning, ...(tourCodexFast && { fastMode: true }) }),
   });
-  const buildGuideLaunch = (): LaunchParams => {
+  // Guide extra instructions (#1265) are server-stored: this surface has no
+  // editor, so it sends none and the server applies the stored standing
+  // instructions itself, keeping sidebar launches identical to launch-page
+  // ones without a second read path.
+  const buildGuideLaunch = (): LaunchParams => buildGuideEngineParams();
+  const buildGuideEngineParams = (): LaunchParams => {
     if (guideEngine === 'cursor') {
       // Same omission rules as buildReviewLaunch: auto/empty ⇒ engine default.
       // Guide-scoped model — deliberately NOT the shared cursorModel (see

package/components/AnalysisLayerToggle.tsx

@@ -0,0 +1,48 @@
+import React from 'react';
+
+interface AnalysisLayerToggleProps {
+  readonly checked: boolean;
+  readonly onChange: (checked: boolean) => void;
+  readonly label: React.ReactNode;
+  readonly description: string;
+  readonly disabled?: boolean;
+  readonly className?: string;
+}
+
+/** Full-row switch shared by Settings and the code-review analysis welcome. */
+export function AnalysisLayerToggle({
+  checked,
+  onChange,
+  label,
+  description,
+  disabled = false,
+  className = '',
+}: AnalysisLayerToggleProps) {
+  return (
+    <button
+      type="button"
+      role="switch"
+      aria-checked={checked}
+      disabled={disabled}
+      onClick={() => onChange(!checked)}
+      className={`flex min-h-11 w-full items-center justify-between gap-4 bg-transparent text-left disabled:cursor-not-allowed disabled:opacity-50 ${className}`}
+    >
+      <span className="min-w-0">
+        <span className="block text-sm font-medium text-foreground">{label}</span>
+        <span className="mt-0.5 block text-xs leading-relaxed text-muted-foreground">{description}</span>
+      </span>
+      <span
+        aria-hidden="true"
+        className={`relative h-6 w-11 shrink-0 rounded-full transition-colors duration-150 ease-out motion-reduce:transition-none ${
+          checked ? 'bg-primary' : 'bg-muted'
+        }`}
+      >
+        <span
+          className={`absolute left-1 top-1 h-4 w-4 rounded-full bg-white shadow-sm transition-transform duration-150 ease-out motion-reduce:transition-none ${
+            checked ? 'translate-x-5' : 'translate-x-0'
+          }`}
+        />
+      </span>
+    </button>
+  );
+}

package/components/AnnotationPanel.tsx

@@ -38,6 +38,52 @@ const TrashCardIcon = () => (
   </svg>
 );
 
+/**
+ * Order annotations so every reply follows its parent (replies among
+ * themselves stay in creation order). A reply whose parent is absent renders
+ * as a top-level card. Without any `inReplyTo` the input order is returned
+ * unchanged, so annotations without replies render exactly as before.
+ */
+export function threadReplies(sorted: Annotation[]): Array<{ annotation: Annotation; isReply: boolean }> {
+  if (!sorted.some((a) => a.inReplyTo)) return sorted.map((annotation) => ({ annotation, isReply: false }));
+  const ids = new Set(sorted.map((a) => a.id));
+  const byParent = new Map<string, Annotation[]>();
+  for (const a of sorted) {
+    if (a.inReplyTo && ids.has(a.inReplyTo) && a.inReplyTo !== a.id) {
+      const list = byParent.get(a.inReplyTo) ?? [];
+      list.push(a);
+      byParent.set(a.inReplyTo, list);
+    }
+  }
+  const out: Array<{ annotation: Annotation; isReply: boolean }> = [];
+  const emitted = new Set<string>();
+  const emit = (a: Annotation, isReply: boolean) => {
+    if (emitted.has(a.id)) return;
+    emitted.add(a.id);
+    out.push({ annotation: a, isReply });
+    for (const reply of byParent.get(a.id) ?? []) emit(reply, true);
+  };
+  for (const a of sorted) {
+    if (a.inReplyTo && ids.has(a.inReplyTo) && a.inReplyTo !== a.id) continue;
+    emit(a, false);
+  }
+  for (const a of sorted) emit(a, false);
+  return out;
+}
+
+/** Timeline position of an annotation: its own time, or its thread root's for replies. */
+function threadTs(annotation: Annotation, all: Annotation[]): number {
+  let current = annotation;
+  const seen = new Set<string>();
+  while (current.inReplyTo && !seen.has(current.id)) {
+    seen.add(current.id);
+    const parent = all.find((a) => a.id === current.inReplyTo);
+    if (!parent) break;
+    current = parent;
+  }
+  return current.createdA;
+}
+
 interface DirectEditsPanelItem {
   id: string;
   title?: string;
@@ -86,6 +132,13 @@ interface PanelProps {
     *  gates what belongs in it. Selection and scrolling still work.
     *  Default false — today's behavior. */
   readOnly?: boolean;
+  /** Embed only the timeline body in a host-owned stage. The host owns the
+    *  title, close control, visible-viewport geometry, and focus boundary. */
+  presentation?: 'panel' | 'embedded';
+  /** Ids of annotations with no live location in the document (e.g. the
+    *  HTML viewer's onUnanchoredChange report after a refresh). Matching
+    *  cards show a small "Unanchored" chip. Absent: no chip, DOM unchanged. */
+  unanchoredIds?: ReadonlySet<string>;
 }
 
 export const AnnotationPanel: React.FC<PanelProps> = ({
@@ -111,16 +164,29 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
   directEdits = null,
   renderCardFooter,
   readOnly = false,
+  presentation = 'panel',
+  unanchoredIds,
 }) => {
   const isMobile = useIsMobile();
+  const embedded = presentation === 'embedded';
+  const mobilePanel = isMobile && !embedded;
   const [copiedText, setCopiedText] = useState(false);
   const listRef = useRef<HTMLDivElement>(null);
   const sortedAnnotations = [...annotations].sort((a, b) => a.createdA - b.createdA);
   const sortedCodeAnnotations = [...codeAnnotations].sort((a, b) => a.createdAt - b.createdAt);
+  // Replies (`inReplyTo`) thread under their parent: each reply is lifted to
+  // sit right after its parent (and the parent's earlier replies) at the
+  // parent's timeline position. With no replies the order is untouched.
+  const threadedAnnotations = threadReplies(sortedAnnotations);
   const timelineEntries = [
-    ...sortedAnnotations.map(annotation => ({ kind: 'plan' as const, ts: annotation.createdA, annotation })),
-    ...sortedCodeAnnotations.map(annotation => ({ kind: 'code' as const, ts: annotation.createdAt, annotation })),
-  ].sort((a, b) => a.ts - b.ts);
+    ...threadedAnnotations.map(({ annotation, isReply }) => ({ kind: 'plan' as const, ts: annotation.createdA, annotation, isReply })),
+    ...sortedCodeAnnotations.map(annotation => ({ kind: 'code' as const, ts: annotation.createdAt, annotation, isReply: false })),
+  ].sort((a, b) => {
+    const ta = a.kind === 'plan' ? threadTs(a.annotation, sortedAnnotations) : a.ts;
+    const tb = b.kind === 'plan' ? threadTs(b.annotation, sortedAnnotations) : b.ts;
+    if (ta !== tb) return ta - tb;
+    return a.ts - b.ts;
+  });
   const totalCount = annotations.length + codeAnnotations.length + (editorAnnotations?.length ?? 0);
 
   // Scroll selected annotation card into view
@@ -138,47 +204,61 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
     <aside
       data-annotation-panel="true"
       data-plan-sidebar="right"
-      className={`border-l border-border/50 bg-card flex flex-col flex-shrink-0 ${
-        isMobile ? 'fixed top-12 bottom-0 right-0 z-[60] w-full max-w-sm shadow-2xl bg-card' : ''
+      className={`bg-card flex flex-col ${embedded ? 'h-full min-h-0 w-full flex-1' : 'flex-shrink-0 border-l border-border/50'} ${
+        mobilePanel ? 'fixed top-12 bottom-0 right-0 z-[60] w-full max-w-sm shadow-2xl bg-card' : ''
       }`}
-      style={isMobile ? undefined : { width: width ?? 288 }}
+      style={embedded || mobilePanel ? undefined : { width: width ?? 288 }}
     >
       {/* Header */}
-      <div className="border-b border-border/50">
-        <div className="flex h-10 items-center justify-between px-3">
-          <div className="flex items-center gap-2">
-            <h2 className="text-xs font-medium text-foreground">
-              Annotations
-            </h2>
-            {totalCount > 0 && (
-              <span className="flex h-[18px] min-w-[18px] items-center justify-center rounded-full bg-primary/10 px-1 font-mono text-[10px] font-medium tabular-nums text-primary">
-                {totalCount}
-              </span>
+      {!embedded && (
+        <div className="border-b border-border/50">
+          <div className="flex h-10 items-center justify-between px-3">
+            <div className="flex items-center gap-2">
+              <h2 className="text-xs font-medium text-foreground">
+                Annotations
+              </h2>
+              {totalCount > 0 && (
+                <span className="flex h-[18px] min-w-[18px] items-center justify-center rounded-full bg-primary/10 px-1 font-mono text-[10px] font-medium tabular-nums text-primary">
+                  {totalCount}
+                </span>
+              )}
+            </div>
+            {mobilePanel && onClose && (
+              <button
+                onClick={onClose}
+                className="relative rounded-md p-1.5 text-muted-foreground transition-colors before:absolute before:-inset-1.5 before:content-[''] hover:text-foreground md:hidden"
+                title="Close panel"
+                aria-label="Close panel"
+              >
+                <svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                  <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+                </svg>
+              </button>
             )}
           </div>
-          {isMobile && onClose && (
+          {otherFileAnnotations && otherFileAnnotations.count > 0 && (
             <button
-              onClick={onClose}
-              className="relative rounded-md p-1.5 text-muted-foreground transition-colors before:absolute before:-inset-1.5 before:content-[''] hover:text-foreground md:hidden"
-              title="Close panel"
-              aria-label="Close panel"
+              onClick={onOtherFileAnnotationsClick}
+              className="px-3 pb-2 text-[10px] text-primary/70 hover:text-primary transition-colors cursor-pointer"
+              title="Show annotated files in sidebar"
             >
-              <svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
-              </svg>
+              +{otherFileAnnotations.count} in {otherFileAnnotations.files} other file{otherFileAnnotations.files === 1 ? '' : 's'}
             </button>
           )}
         </div>
-        {otherFileAnnotations && otherFileAnnotations.count > 0 && (
-          <button
-            onClick={onOtherFileAnnotationsClick}
-            className="px-3 pb-2 text-[10px] text-primary/70 hover:text-primary transition-colors cursor-pointer"
-            title="Show annotated files in sidebar"
-          >
-            +{otherFileAnnotations.count} in {otherFileAnnotations.files} other file{otherFileAnnotations.files === 1 ? '' : 's'}
-          </button>
-        )}
-      </div>
+      )}
+
+      {embedded && otherFileAnnotations && otherFileAnnotations.count > 0 && (
+        <button
+          type="button"
+          data-pn-touch-target="true"
+          onClick={onOtherFileAnnotationsClick}
+          className="min-h-11 flex-shrink-0 border-b border-border/50 px-3 text-left text-xs text-primary/80 active:bg-muted"
+          title="Show annotated files in navigator"
+        >
+          {otherFileAnnotations.count} more in {otherFileAnnotations.files} other file{otherFileAnnotations.files === 1 ? '' : 's'}
+        </button>
+      )}
 
       {/* List */}
       <OverlayScrollArea className="flex-1 min-h-0">
@@ -201,6 +281,25 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
           <>
             {timelineEntries.map(entry => (
               entry.kind === 'plan' ? (
+                entry.isReply ? (
+                  <div
+                    key={entry.annotation.id}
+                    data-annotation-reply="true"
+                    className="ml-3 border-l-2 border-border/40 pl-1.5"
+                  >
+                    <AnnotationCard
+                      annotation={entry.annotation}
+                      isSelected={selectedId === entry.annotation.id}
+                      isMe={isCurrentUser(entry.annotation.author)}
+                      onSelect={() => onSelect(entry.annotation.id)}
+                      onDelete={() => onDelete(entry.annotation.id)}
+                      onEdit={onEdit ? (updates: Partial<Annotation>) => onEdit(entry.annotation.id, updates) : undefined}
+                      readOnly={readOnly}
+                      footer={renderCardFooter?.(entry.annotation)}
+                      unanchored={unanchoredIds?.has(entry.annotation.id) ?? false}
+                    />
+                  </div>
+                ) : (
                 <AnnotationCard
                   key={entry.annotation.id}
                   annotation={entry.annotation}
@@ -211,7 +310,9 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                   onEdit={onEdit ? (updates: Partial<Annotation>) => onEdit(entry.annotation.id, updates) : undefined}
                   readOnly={readOnly}
                   footer={renderCardFooter?.(entry.annotation)}
+                  unanchored={unanchoredIds?.has(entry.annotation.id) ?? false}
                 />
+                )
               ) : (
                 <CodeAnnotationCard
                   key={entry.annotation.id}
@@ -297,7 +398,7 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
     </aside>
   );
 
-  if (isMobile) {
+  if (mobilePanel) {
     return (
       <>
         <div
@@ -438,7 +539,9 @@ const AnnotationCard: React.FC<{
   onEdit?: (updates: Partial<Annotation>) => void;
   readOnly?: boolean;
   footer?: React.ReactNode;
-}> = ({ annotation, isSelected, isMe, onSelect, onDelete, onEdit, readOnly = false, footer }) => {
+  /** The annotation has no live location in the document (host-reported). */
+  unanchored?: boolean;
+}> = ({ annotation, isSelected, isMe, onSelect, onDelete, onEdit, readOnly = false, footer, unanchored = false }) => {
   const [isEditing, setIsEditing] = useState(false);
   const [editText, setEditText] = useState(annotation.text || '');
   const textareaRef = useRef<HTMLTextAreaElement>(null);
@@ -493,6 +596,7 @@ const AnnotationCard: React.FC<{
   const editComposer = (
     <div onClick={(e: React.MouseEvent) => e.stopPropagation()}>
       <textarea
+        data-pn-mobile-editable="true"
         ref={textareaRef}
         value={editText}
         onChange={(e: React.ChangeEvent<HTMLTextAreaElement>) => setEditText(e.target.value)}
@@ -534,6 +638,23 @@ const AnnotationCard: React.FC<{
             diff
           </span>
         )}
+        {annotation.pageUrl && (
+          <span
+            className="text-[9px] px-1.5 py-0.5 rounded font-medium bg-muted text-muted-foreground truncate max-w-[10rem]"
+            title={annotation.pageUrl}
+          >
+            {annotation.pageUrl}
+          </span>
+        )}
+        {unanchored && (
+          <span
+            data-annotation-unanchored="true"
+            className="text-[9px] px-1.5 py-0.5 rounded font-medium bg-muted text-muted-foreground"
+            title="This comment no longer matches a location in the document"
+          >
+            Unanchored
+          </span>
+        )}
         <span className="text-[10px] text-muted-foreground/50 truncate">
           {annotation.author ? `${annotation.author}${isMe ? ' (me)' : ''} · ` : ''}{formatTimestamp(annotation.createdA)}
         </span>
@@ -724,6 +845,7 @@ const CodeAnnotationCard: React.FC<{
       {isEditing ? (
         <div className="mt-1.5" onClick={(e) => e.stopPropagation()}>
           <textarea
+            data-pn-mobile-editable="true"
             ref={textareaRef}
             value={editText}
             onChange={(e) => setEditText(e.target.value)}

package/components/AnnotationToolbar.tsx

@@ -2,19 +2,13 @@ import React, { useState, useEffect, useRef, useMemo } from "react";
 import { AnnotationType } from "../types";
 import { createPortal } from "react-dom";
 import { useDismissOnOutsideAndEscape } from "../hooks/useDismissOnOutsideAndEscape";
-import { type QuickLabel, getQuickLabels } from "../utils/quickLabels";
+import { type QuickLabel, getQuickLabels, THUMBS_UP_LABEL } from "../utils/quickLabels";
 import { copyTextToClipboard } from "../utils/clipboard";
+import { acquireTypeToCommentCapture } from "../shortcuts/plan-review/annotationMode.shortcuts";
 import { FloatingQuickLabelPicker } from "./FloatingQuickLabelPicker";
 
 type PositionMode = 'center-above' | 'top-right';
 
-const THUMBS_UP_LABEL: QuickLabel = {
-  id: 'thumbs-up',
-  emoji: '👍',
-  text: 'Looks good',
-  color: 'green',
-};
-
 const isEditableElement = (node: EventTarget | Element | null): boolean => {
   if (!(node instanceof Element)) return false;
   if (node.matches('input, textarea, select, [role="textbox"]')) return true;
@@ -33,6 +27,12 @@ interface AnnotationToolbarProps {
   onQuickLabel?: (label: QuickLabel) => void;
   /** Text to copy when the button is clicked */
   copyText?: string;
+  /** Comment-only surfaces (HTML / live-app viewer): hide the Delete action,
+   *  the quick-label picker, and the Alt+digit label shortcuts. A provided
+   *  onQuickLabel then renders ONLY the hardcoded 👍 "Looks good" button —
+   *  the one label affordance restored to these surfaces. Markdown surfaces
+   *  keep the full toolbar. */
+  commentOnly?: boolean;
   /** Hide the copy button (set when a keyboard copy handler exists) */
   hideCopyButton?: boolean;
   /** Close toolbar when element scrolls out of viewport */
@@ -52,6 +52,7 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
   onRequestComment,
   onQuickLabel,
   copyText,
+  commentOnly = false,
   hideCopyButton = false,
   closeOnScrollOut = false,
   isExiting = false,
@@ -126,14 +127,17 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
         return;
       }
 
-      // Alt+N applies quick label (picker closed)
+      // Alt+N applies quick label (picker closed). Comment-only surfaces
+      // suppress this path: their only label affordance is the 👍 button.
       const isDigit = (e.code >= 'Digit1' && e.code <= 'Digit9') || e.code === 'Digit0';
       if (isDigit && !e.ctrlKey && !e.metaKey && e.altKey) {
         e.preventDefault();
-        const digit = parseInt(e.code.slice(5), 10);
-        const index = digit === 0 ? 9 : digit - 1;
-        if (index < quickLabels.length) {
-          onQuickLabel?.(quickLabels[index]);
+        if (!commentOnly) {
+          const digit = parseInt(e.code.slice(5), 10);
+          const index = digit === 0 ? 9 : digit - 1;
+          if (index < quickLabels.length) {
+            onQuickLabel?.(quickLabels[index]);
+          }
         }
         return;
       }
@@ -146,8 +150,15 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
     };
 
     window.addEventListener("keydown", handleKeyDown);
-    return () => window.removeEventListener("keydown", handleKeyDown);
-  }, [onClose, onRequestComment, onQuickLabel, quickLabels, showQuickLabels]);
+    // While this listener owns printable keys, the Shift+1..4 annotation-mode
+    // shortcuts must not fire: Shift+3 is "#", and a user typing "#" into a
+    // starting comment must not silently arm Redline (#1244 follow-up).
+    const releaseCapture = acquireTypeToCommentCapture();
+    return () => {
+      window.removeEventListener("keydown", handleKeyDown);
+      releaseCapture();
+    };
+  }, [onClose, onRequestComment, onQuickLabel, quickLabels, showQuickLabels, commentOnly]);
 
   useDismissOnOutsideAndEscape({
     enabled: !showQuickLabels,
@@ -197,7 +208,7 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
           to { opacity: 0; transform: translateY(8px)${translateX}; }
         }
       `}</style>
-      <div className="flex items-center p-1 gap-0.5">
+      <div data-pn-annotation-toolbar-row="true" className="flex items-center p-1 gap-0.5">
         {!hideCopyButton && (
           <>
             <ToolbarButton
@@ -209,12 +220,14 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
             <div className="w-px h-5 bg-border mx-0.5" />
           </>
         )}
-        <ToolbarButton
-          onClick={() => handleTypeSelect(AnnotationType.DELETION)}
-          icon={<TrashIcon />}
-          label="Delete"
-          className="text-destructive hover:bg-destructive/10"
-        />
+        {!commentOnly && (
+          <ToolbarButton
+            onClick={() => handleTypeSelect(AnnotationType.DELETION)}
+            icon={<TrashIcon />}
+            label="Delete"
+            className="text-destructive hover:bg-destructive/10"
+          />
+        )}
         <ToolbarButton
           onClick={() => handleTypeSelect(AnnotationType.COMMENT)}
           icon={<CommentIcon />}
@@ -223,20 +236,22 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
         />
         {onQuickLabel && (
           <>
-            <ToolbarButton
-              ref={zapButtonRef}
-              onClick={() => setShowQuickLabels(prev => !prev)}
-              icon={<ZapIcon />}
-              label="Quick label"
-              className={showQuickLabels ? "text-amber-500 bg-amber-500/10" : "text-amber-500 hover:bg-amber-500/10"}
-            />
+            {!commentOnly && (
+              <ToolbarButton
+                ref={zapButtonRef}
+                onClick={() => setShowQuickLabels(prev => !prev)}
+                icon={<ZapIcon />}
+                label="Quick label"
+                className={showQuickLabels ? "text-amber-500 bg-amber-500/10" : "text-amber-500 hover:bg-amber-500/10"}
+              />
+            )}
             <ToolbarButton
               onClick={() => onQuickLabel(THUMBS_UP_LABEL)}
               icon={<span className="block w-4 h-4 text-sm leading-4 text-center">👍</span>}
               label="Looks good"
               className="hover:bg-green-500/10"
             />
-            {showQuickLabels && zapButtonRef.current && (
+            {!commentOnly && showQuickLabels && zapButtonRef.current && (
               <FloatingQuickLabelPicker
                 anchorEl={zapButtonRef.current}
                 onSelect={(label) => {
@@ -306,6 +321,11 @@ const ToolbarButton = React.forwardRef<HTMLButtonElement, {
 }>(({ onClick, icon, label, className }, ref) => (
   <button
     ref={ref}
+    // Icon-only controls: the markers are inert outside the compact touch
+    // scope, where theme.css grows them to var(--pn-touch-target). Desktop
+    // geometry is unchanged.
+    data-pn-touch-target="true"
+    data-pn-touch-target-icon="true"
     onClick={onClick}
     title={label}
     className={`p-1.5 rounded-md transition-colors ${className}`}