@plannotator/ui 0.29.1 → 0.31.0

package/theme.css

@@ -627,6 +627,14 @@
    * the surface/sidebar-aware components expect. Themes that pin explicit
    * values (e.g. "simple") override these. */
   :root {
+    /* Mobile browser environment. Safe areas are CSS-owned because they are
+     * available before React mounts; the observed viewport values are written
+     * by useViewportEnvironment and fall back cleanly in the utilities below. */
+    --pn-safe-top: env(safe-area-inset-top, 0px);
+    --pn-safe-right: env(safe-area-inset-right, 0px);
+    --pn-safe-bottom: env(safe-area-inset-bottom, 0px);
+    --pn-safe-left: env(safe-area-inset-left, 0px);
+    --pn-touch-target: 2.75rem;
     --surface-0: color-mix(in oklch, var(--muted) 40%, var(--background));
     --surface-1: var(--muted);
     --surface-2: color-mix(in oklch, var(--muted) 70%, var(--foreground));
@@ -704,6 +712,227 @@ body {
   font-feature-settings: "ss01", "ss02", "cv01";
 }
 
+/* Safari extends the page canvas beneath its floating browser controls. The
+ * plan document is a card-colored nested scroller, so leaving the outer canvas
+ * on `--background` produces an opaque dark band around those controls. Match
+ * the browser canvas to the active surface while preserving the incumbent
+ * background for grid, HTML, Review, loading, and non-editor consumers. */
+html:has([data-pn-browser-canvas="card"]),
+body:has([data-pn-browser-canvas="card"]) {
+  background-color: var(--card);
+}
+
+html:has([data-pn-browser-canvas="background"]),
+body:has([data-pn-browser-canvas="background"]) {
+  background-color: var(--background);
+}
+
+/* Mobile Safari only collapses its browser controls for page scrolling; it
+ * deliberately leaves them expanded when a gesture scrolls a nested element.
+ * Plan opts compact coarse-pointer layouts into document scrolling while the
+ * fixed application-stage architecture remains unchanged everywhere else. */
+html:has([data-pn-document-scroll="true"]),
+body:has([data-pn-document-scroll="true"]) {
+  height: auto;
+  overflow-x: hidden;
+  overflow-y: auto;
+  overscroll-behavior: auto;
+}
+
+body:has([data-pn-document-scroll="true"]) > #root {
+  height: auto;
+  overflow: visible;
+}
+
+.pn-app-viewport[data-pn-document-scroll="true"] {
+  height: auto;
+  min-height: 100vh;
+  min-height: 100dvh;
+}
+
+/* The application stage owns the top and lateral safe areas. Bottom-edge
+ * surfaces opt into `.pn-safe-bottom` themselves so the home-indicator inset
+ * is never counted twice. The ordered height declarations preserve desktop
+ * behavior and old-browser support before the observer publishes a value. */
+.pn-app-viewport {
+  box-sizing: border-box;
+  height: 100vh;
+  height: 100dvh;
+  height: var(--pn-viewport-height, 100vh);
+  padding-top: var(--pn-safe-top);
+  padding-right: var(--pn-safe-right);
+  padding-left: var(--pn-safe-left);
+}
+
+.pn-safe-top {
+  padding-top: var(--pn-safe-top);
+}
+
+.pn-safe-inline {
+  padding-right: var(--pn-safe-right);
+  padding-left: var(--pn-safe-left);
+}
+
+.pn-safe-bottom {
+  padding-bottom: var(--pn-safe-bottom);
+}
+
+.pn-viewport-bounded {
+  max-height: calc(
+    var(--pn-viewport-height, 100vh) - var(--pn-safe-top) - var(--pn-safe-bottom)
+  );
+}
+
+/* Portaled overlays cannot inherit the application root's safe-area padding.
+ * This utility gives them the same observed visible stage without assuming
+ * that the software keyboard is a rectangular bottom inset. */
+.pn-visible-viewport-overlay {
+  position: fixed;
+  top: var(--pn-viewport-offset-top, 0px);
+  left: var(--pn-viewport-offset-left, 0px);
+  box-sizing: border-box;
+  width: var(--pn-viewport-width, 100vw);
+  height: var(--pn-viewport-height, 100vh);
+  padding-top: max(1rem, var(--pn-safe-top));
+  padding-right: max(1rem, var(--pn-safe-right));
+  padding-bottom: max(1rem, var(--pn-safe-bottom));
+  padding-left: max(1rem, var(--pn-safe-left));
+}
+
+/* Full-stage compact surfaces (for example the Plan navigator) use the same
+ * observed visual viewport as portaled dialogs without inheriting their 1rem
+ * ornamental margin. The stage owns its safe areas and contains scroll-chain
+ * gestures so the document beneath it does not move at a list boundary. */
+.pn-visible-viewport-stage {
+  position: fixed;
+  top: var(--pn-viewport-offset-top, 0px);
+  left: var(--pn-viewport-offset-left, 0px);
+  box-sizing: border-box;
+  width: var(--pn-viewport-width, 100vw);
+  height: var(--pn-viewport-height, 100vh);
+  padding-top: var(--pn-safe-top);
+  padding-right: var(--pn-safe-right);
+  padding-bottom: var(--pn-safe-bottom);
+  padding-left: var(--pn-safe-left);
+  overscroll-behavior: contain;
+}
+
+/* The navigator reuses information-dense desktop browser content, but its
+ * interactive rows become physical controls on touch. Scope both the 44px
+ * target and the TOC's legible type lift to the compact stage only. */
+[data-pn-plan-navigator="true"] button {
+  min-block-size: var(--pn-touch-target);
+  touch-action: manipulation;
+}
+
+[data-pn-plan-navigator="true"] nav button {
+  font-size: 0.8125rem;
+}
+
+[data-pn-plan-navigator="true"] .file-browser-filter-field {
+  height: var(--pn-touch-target);
+}
+
+[data-pn-plan-navigator="true"] .file-browser-filter-clear {
+  min-inline-size: var(--pn-touch-target);
+}
+
+/* Compact Plan auxiliary stages reuse dense desktop panel contents, but every
+ * nested action remains a physical touch control. This selector is stage-only,
+ * so the incumbent desktop panel geometry stays pixel-identical. */
+[data-pn-compact-plan-stage="true"] button {
+  min-block-size: var(--pn-touch-target);
+  touch-action: manipulation;
+}
+
+/* Existing expanded composers keep their 85dvh desktop proportion. Compact
+ * and touch layouts use the full safe visible stage so the keyboard cannot
+ * strand the footer below an ornamental desktop margin. */
+.pn-responsive-composer-dialog {
+  width: 100%;
+  height: min(36rem, 85vh);
+  height: min(36rem, 85dvh);
+  max-width: 42rem;
+  max-height: 100%;
+}
+
+@media (pointer: coarse), (max-width: 639px), (max-height: 419px) {
+  .pn-responsive-composer-dialog {
+    height: 100%;
+  }
+
+  /* Code review often promotes a line selection straight into the expanded
+   * composer. Keep its idle surface proportional to the content instead of
+   * covering the whole phone; once the keyboard reduces the visible viewport,
+   * the same cap naturally yields to all available space. Plan's explicit
+   * expanded-composer treatment remains unchanged. */
+  .pn-responsive-composer-dialog.pn-review-composer-dialog {
+    height: min(28rem, 100%);
+  }
+}
+
+/* iOS zooms focused text controls below 16px. Scope the correction to
+ * user-authored primary inputs so labels, counters, and diff text stay at the
+ * established desktop scale. The mirror selector keeps skill-token glyphs
+ * metrically identical to the transparent textarea above it. */
+@media (pointer: coarse), (max-width: 639px) {
+  [data-pn-mobile-editable],
+  [data-pn-mobile-editable-mirror] {
+    font-size: 1rem !important;
+  }
+}
+
+/* Shared controls keep their incumbent visual density but gain a physical
+ * 44px target inside the canonical compact touch shell. The root marker comes
+ * from the same JS media query that owns scroll and shell composition, so a
+ * secondary touchscreen cannot reclassify a fine-primary-pointer desktop.
+ * Selecting from `html` also reaches portaled controls outside the app root. */
+html:has([data-pn-compact-touch-layout='true']) [data-pn-touch-target] {
+  min-block-size: var(--pn-touch-target);
+  touch-action: manipulation;
+}
+
+html:has([data-pn-compact-touch-layout='true'])
+  [data-pn-touch-target][data-pn-touch-target-icon] {
+  min-inline-size: var(--pn-touch-target);
+}
+
+html:has([data-pn-compact-touch-layout='true'])
+  [data-pn-compact-diff-options]
+  button {
+  min-block-size: var(--pn-touch-target);
+  touch-action: manipulation;
+}
+
+/* The selection toolbar packs its controls at desktop density (2px gaps), so
+ * 44px targets alone would still leave adjacent destructive and comment
+ * actions a mis-tap apart. Space them only inside the compact scope. */
+html:has([data-pn-compact-touch-layout='true'])
+  [data-pn-annotation-toolbar-row] {
+  gap: 0.5rem;
+}
+
+html:has([data-pn-compact-touch-layout='true'])
+  [data-pn-touch-target]:not(:disabled):not([aria-disabled='true']):active {
+  filter: brightness(0.92);
+  transition: filter 100ms ease-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  html:has([data-pn-compact-touch-layout='true'])
+    [data-pn-touch-target]:not(:disabled):not([aria-disabled='true']):active {
+    filter: brightness(0.9);
+    transition: none;
+  }
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .plan-look-choice-option[aria-pressed='false']:hover {
+    border-color: color-mix(in srgb, var(--muted-foreground) 40%, transparent);
+    background: color-mix(in srgb, var(--muted) 35%, transparent);
+  }
+}
+
 .math-inline {
   display: inline-flex;
   align-items: center;

package/types.ts

@@ -79,6 +79,7 @@ export interface Annotation {
     displayMode: boolean;
   }>; // math elements covered by a mixed text+formula selection
   prUrl?: string; // code-review PR mode: the PR this note belongs to, so it isn't shown/exported against another PR after an in-place switch
+  pageUrl?: string; // set only by live app annotate sessions: the page (pathname + search) the annotation was made on; restore filters to the current page and export groups by page
   htmlAnchor?: HtmlElementAnchor; // raw-HTML pinpoint: serialized element anchor for reliable restoration
   htmlAdditionalTargets?: HtmlAnnotationTarget[]; // raw-HTML shift-click multi-select: extra elements this one comment covers (primary stays htmlAnchor/originalText)
   // web-highlighter metadata for cross-element selections
@@ -155,6 +156,32 @@ export type CodeAnnotationType = 'comment' | 'suggestion' | 'concern';
 // must branch on scope, never read those sentinels as a real path or row.
 export type CodeAnnotationScope = 'line' | 'file' | 'general';
 
+/**
+ * One inferred step selected from the Call Flow analysis surface.
+ *
+ * Source location is optional because CallDiff can surface structural steps
+ * without a concrete line. `CodeAnnotation` uses an in-patch located target
+ * as its native inline anchor when one exists; otherwise the annotation is
+ * file- or review-scoped while this target remains its durable Call Flow
+ * anchor. Raw output selections use a one-based `rawLine` instead of a source
+ * location. This lets every rendered Call Flow row and raw line participate in
+ * feedback without pretending an out-of-hunk or diagnostic line can be posted
+ * as an inline source comment.
+ */
+interface CallFlowAnnotationTargetBase {
+  treePath: string;
+  entry: string;
+  label: string;
+  side: 'old' | 'new';
+}
+
+export type CallFlowAnnotationTarget = CallFlowAnnotationTargetBase & (
+  | { filePath: string; lineStart: number; lineEnd: number; rawLine?: undefined }
+  | { filePath: string; lineStart?: undefined; lineEnd?: undefined; rawLine?: undefined }
+  | { rawLine: number; filePath?: undefined; lineStart?: undefined; lineEnd?: undefined }
+  | { rawLine?: undefined; filePath?: undefined; lineStart?: undefined; lineEnd?: undefined }
+);
+
 /** Conventional Comments label — see https://conventionalcomments.org */
 export type ConventionalLabel =
   | 'praise'
@@ -214,6 +241,13 @@ export interface CodeAnnotation {
    *  line anchor maps to the pristine lines those edits replace, so it is
    *  approximate and the export labels it as such. */
   selectedTextFromEdits?: boolean;
+  /**
+   * Complete Call Flow selection for an annotation authored from that
+   * surface. When any target maps to the patch, one target also supplies this
+   * annotation's primary inline anchor; otherwise the annotation is file- or
+   * review-scoped. Target order always preserves the user's selection order.
+   */
+  callFlowTargets?: CallFlowAnnotationTarget[];
   createdAt: number;
   author?: string;
   source?: string; // External tool identifier (e.g., "eslint") — set when annotation comes from external API

package/utils/annotateAgentTerminal.ts

@@ -1,14 +1,45 @@
-import type { AgentTerminalAgent } from "@plannotator/core/agent-terminal";
-import { storage } from "./storage";
+import type {
+  AgentTerminalAgent,
+  AnnotateAgentTerminalSide,
+} from "@plannotator/core/agent-terminal";
+import { configStore } from "../config";
 
-const DEFAULT_AGENT_KEY = "plannotator-annotate-agent-terminal-default";
+// The side/placement vocabulary lives in @plannotator/core so the settings
+// registry can reach it without importing this module (which would close a
+// cycle through ConfigStore). Re-exported here because this is the seam the
+// editor package imports from.
+export {
+  ANNOTATE_AGENT_TERMINAL_SIDES,
+  isAnnotateAgentTerminalSide,
+  resolveAnnotateAgentTerminalPlacement,
+  resolveAnnotateAgentTerminalSide,
+} from "@plannotator/core/agent-terminal";
+export type {
+  AnnotateAgentTerminalPlacement,
+  AnnotateAgentTerminalSide,
+} from "@plannotator/core/agent-terminal";
 
+/**
+ * Both Agent TUI preferences resolve through ConfigStore (server config file >
+ * cookie > default) rather than reading cookies directly. Annotate sessions run
+ * on a fresh random port every time, so a cookie is scoped to a single session;
+ * the server round-trip through ~/.plannotator/config.json is what makes these
+ * choices durable. Same seam identity.ts uses for `displayName`.
+ */
 export function getSavedAnnotateAgentId(): string | null {
-  return storage.getItem(DEFAULT_AGENT_KEY);
+  return configStore.get("agentTerminalDefaultAgent") || null;
 }
 
 export function saveAnnotateAgentId(agentId: string): void {
-  storage.setItem(DEFAULT_AGENT_KEY, agentId);
+  configStore.set("agentTerminalDefaultAgent", agentId);
+}
+
+export function getSavedAnnotateAgentTerminalSide(): AnnotateAgentTerminalSide {
+  return configStore.get("agentTerminalSide");
+}
+
+export function saveAnnotateAgentTerminalSide(side: AnnotateAgentTerminalSide): void {
+  configStore.set("agentTerminalSide", side);
 }
 
 export function resolveAnnotateAgentId(

package/utils/blockTargeting.ts

@@ -1,11 +1,12 @@
+import { getScrollViewportRect } from '../hooks/useScrollViewport';
+import { createTextRange } from './domSelection';
+
 /**
  * Semantic document targeting shared by pointer Pinpoint and Vim navigation.
  *
  * The graph is rebuilt from the live rendered document whenever a consumer
  * needs it. Callers persist stable keys, never DOM nodes, across renders.
  */
-import { createTextRange } from './domSelection';
-
 /** Elements that never participate in document targeting. */
 const SKIP_SELECTORS = [
   '.annotation-toolbar',
@@ -362,7 +363,9 @@ export function findInitialSemanticTarget(
   graph: SemanticTargetGraph,
   scrollViewport?: HTMLElement | null,
 ): SemanticTarget | null {
-  const viewportRect = (scrollViewport ?? graph.container).getBoundingClientRect();
+  const viewportRect = scrollViewport
+    ? getScrollViewportRect(scrollViewport)
+    : graph.container.getBoundingClientRect();
   const centerY = viewportRect.top + viewportRect.height / 2;
   return graph.blockKeys
     .map((key) => resolveSemanticTarget(graph, key))

package/utils/composerYield.ts

@@ -0,0 +1,45 @@
+/**
+ * Composer-yield state machine for shift-click multi-select.
+ *
+ * While Shift is held during a multi-target draft, the comment composer gets
+ * out of the pointer's way: it fades as the pointer approaches and becomes
+ * click-through when the pointer is over it. Restoration uses hysteresis so
+ * the composer does not flicker at its boundary.
+ */
+
+export type ComposerYieldState = 'none' | 'near' | 'over';
+
+/** Distance (px from the composer rect) at which the composer starts fading. */
+export const COMPOSER_YIELD_NEAR_ENTER_PX = 80;
+/** Distance the pointer must exceed before a faded composer fully restores. */
+export const COMPOSER_YIELD_NEAR_EXIT_PX = 96;
+/** Distance the pointer must clear a click-through composer by to restore. */
+export const COMPOSER_YIELD_OVER_EXIT_PX = 48;
+
+/** Shortest distance from a point to a rect's edge; <= 0 means inside. */
+export function distanceToRect(
+  x: number,
+  y: number,
+  rect: { left: number; top: number; right: number; bottom: number },
+): number {
+  const dx = Math.max(rect.left - x, 0, x - rect.right);
+  const dy = Math.max(rect.top - y, 0, y - rect.bottom);
+  if (dx === 0 && dy === 0) return 0;
+  return Math.hypot(dx, dy);
+}
+
+/** Next yield state for a pointer at `distance` px from the composer rect. */
+export function computeComposerYield(
+  previous: ComposerYieldState,
+  distance: number,
+): ComposerYieldState {
+  if (distance <= 0) return 'over';
+  if (previous === 'over') {
+    if (distance <= COMPOSER_YIELD_OVER_EXIT_PX) return 'over';
+    return distance <= COMPOSER_YIELD_NEAR_EXIT_PX ? 'near' : 'none';
+  }
+  if (previous === 'near') {
+    return distance <= COMPOSER_YIELD_NEAR_EXIT_PX ? 'near' : 'none';
+  }
+  return distance <= COMPOSER_YIELD_NEAR_ENTER_PX ? 'near' : 'none';
+}

package/utils/htmlChrome.ts

@@ -2,37 +2,41 @@ import { storage } from './storage';
 import { isStalePreference } from './preferenceTtl';
 
 /**
- * Cross-session chrome visibility for raw-HTML annotate sessions.
+ * Cross-session sidebar/panel state for raw-HTML annotate sessions.
  *
- * A raw-HTML session should open as close to "just the page" as possible, so
- * the default is minimal paint: tools hidden, sidebar closed, annotations
- * drawer closed. An explicit change the user makes (showing tools, opening the
- * drawer) persists for later HTML sessions, but only while they keep using
- * HTML annotate: state not refreshed within the staleness TTL (explicit
- * changes or annotation activity re-stamp it) expires back to the minimal
+ * A raw-HTML session opens with both side surfaces closed so the page gets
+ * the viewport; an explicit change the user makes (opening the sidebar or the
+ * annotations drawer) persists for later HTML sessions, but only while they
+ * keep using HTML annotate: state not refreshed within the staleness TTL
+ * (explicit changes or annotation activity re-stamp it) expires back to the
  * defaults. Persisted as a cookie (like every other cross-session UI pref;
  * hook servers run on random ports, and cookies are scoped by domain, not
  * port). Markdown sessions are untouched. A legacy record without a timestamp
- * has an unknowable age and is treated as expired, which one-time resets
- * everyone to the minimal defaults.
+ * has an unknowable age and is treated as expired.
+ *
+ * `toolsHidden` is the header "Hide tools" toggle: while true, ALL floating
+ * chrome over the page (sidebar tongue tabs + the comment/attachments
+ * cluster) is removed from the DOM. Restoring it hidden can never strand a
+ * user: the header button that flips it back is part of the header, not the
+ * hidden chrome.
  */
 
 const STORAGE_KEY = 'plannotator-html-chrome';
 
 export interface HtmlChromeState {
-  /** The header "Hide tools" toggle — true hides all annotation chrome. */
-  toolsHidden: boolean;
   /** Whether the left sidebar was open when the user last left. */
   sidebarOpen: boolean;
   /** Whether the right annotations drawer was open when the user last left. */
   panelOpen: boolean;
+  /** Whether ALL floating tools over the page were hidden when the user left. */
+  toolsHidden: boolean;
 }
 
-/** Default: minimal paint — everything hidden, both side surfaces closed. */
+/** Default: both side surfaces closed — the page gets the viewport. */
 export const DEFAULT_HTML_CHROME_STATE: HtmlChromeState = {
-  toolsHidden: true,
   sidebarOpen: false,
   panelOpen: false,
+  toolsHidden: false,
 };
 
 /** Pure resolution logic (exported for tests): raw cookie value → state. */
@@ -49,15 +53,15 @@ export function resolveHtmlChromeState(
     const record = parsed as Record<string, unknown>;
     if (isStalePreference(record.savedAt, now)) return DEFAULT_HTML_CHROME_STATE;
     return {
-      toolsHidden: typeof record.toolsHidden === 'boolean'
-        ? record.toolsHidden
-        : DEFAULT_HTML_CHROME_STATE.toolsHidden,
       sidebarOpen: typeof record.sidebarOpen === 'boolean'
         ? record.sidebarOpen
         : DEFAULT_HTML_CHROME_STATE.sidebarOpen,
       panelOpen: typeof record.panelOpen === 'boolean'
         ? record.panelOpen
         : DEFAULT_HTML_CHROME_STATE.panelOpen,
+      toolsHidden: typeof record.toolsHidden === 'boolean'
+        ? record.toolsHidden
+        : DEFAULT_HTML_CHROME_STATE.toolsHidden,
     };
   } catch {
     return DEFAULT_HTML_CHROME_STATE;

package/utils/lookAndFeelAnnouncement.ts

@@ -1,18 +1,22 @@
 /**
- * Tracks whether the user has seen the UI 2.0 "look & feel" refresh announcement.
- * Uses cookies so the dismissal survives Plannotator's random localhost ports.
+ * Tracks whether the user has explicitly resolved the Grid/Clean plan choice.
+ * This is separate from `gridEnabled`: ConfigStore seeds that preference with
+ * its default on first access, which is not evidence that the user chose it.
  */
 
 import { storage } from './storage';
 
-const STORAGE_KEY = 'plannotator-look-feel-announcement-seen';
-// v2: grid is the default again; the dialog became a grid-vs-clean image chooser.
-const CURRENT_VERSION = '2';
+const CHOICE_RESOLVED_KEY = 'plannotator-plan-look-choice-resolved';
+const LEGACY_ANNOUNCEMENT_KEY = 'plannotator-look-feel-announcement-seen';
 
 export function needsLookAndFeelAnnouncement(): boolean {
-  return storage.getItem(STORAGE_KEY) !== CURRENT_VERSION;
+  if (storage.getItem(CHOICE_RESOLVED_KEY) === 'true') return false;
+  // v2 was the old Grid/Clean chooser wrapped in the 0.20.0 announcement.
+  // A dismissal there resolved the same decision; migrate it without showing
+  // another dialog merely because the release framing was removed.
+  return storage.getItem(LEGACY_ANNOUNCEMENT_KEY) !== '2';
 }
 
-export function markLookAndFeelAnnouncementSeen(): void {
-  storage.setItem(STORAGE_KEY, CURRENT_VERSION);
+export function markLookAndFeelChoiceResolved(): void {
+  storage.setItem(CHOICE_RESOLVED_KEY, 'true');
 }

package/utils/markdownExtensions.ts

@@ -0,0 +1,57 @@
+/**
+ * Extra markdown extensions, renderer side (#1307).
+ *
+ * The server resolves `markdownExtensions` from `~/.plannotator/config.json`
+ * and ships the normalized list with the annotate payload. The renderer needs
+ * it for one job: deciding whether a relative link or a wiki-link target names
+ * a local document it should open in the linked-doc overlay (`/api/doc`) or a
+ * plain external link. Without it, `[notes](notes.livemd)` renders as a dead
+ * external link even though the server would happily serve it.
+ *
+ * Module-level registry seam, like `skillReferences.ts`: a host (or the app's
+ * own boot code) registers the list once, everything else reads it. Empty by
+ * default, so nothing changes for a user with no config.
+ *
+ * The built-in set here is deliberately NARROWER than the annotatable set on
+ * the server (`.md`/`.mdx`/`.txt`/`.html`/`.htm` only) — widening it is a
+ * separate decision. Extras are added on top of it.
+ */
+
+import { normalizeMarkdownExtensions } from "@plannotator/core/annotatable";
+
+/** Built-in extensions the renderer treats as openable local documents. */
+const BUILTIN_LINKED_DOC_REGEX = /\.(mdx?|txt|html?)$/i;
+
+let extraExtensions: string[] = [];
+
+/**
+ * Register the extra markdown extensions for this page. Values are normalized
+ * with the same rules the server applies (dot-led, lowercased, `.env` denied),
+ * so a hostile or malformed payload cannot inject regex or path fragments.
+ */
+export function setExtraMarkdownExtensions(value: unknown): void {
+	extraExtensions = normalizeMarkdownExtensions(value);
+}
+
+/** The registered extra extensions (normalized, possibly empty). */
+export function getExtraMarkdownExtensions(): string[] {
+	return extraExtensions;
+}
+
+/**
+ * Does this link target name a local document the linked-doc overlay can open?
+ *
+ * `allowFragment` mirrors the two call sites this replaced: markdown links
+ * accept a trailing `#fragment` (stripped by the caller before navigating),
+ * wiki-link targets do not.
+ */
+export function hasLinkedDocExtension(
+	target: string,
+	options?: { allowFragment?: boolean },
+): boolean {
+	const trimmed = target.trim();
+	const path = options?.allowFragment ? trimmed.replace(/#.*$/, "") : trimmed;
+	if (BUILTIN_LINKED_DOC_REGEX.test(path)) return true;
+	const lower = path.toLowerCase();
+	return extraExtensions.some((ext) => lower.endsWith(ext));
+}

package/utils/parser.ts

@@ -1178,8 +1178,43 @@ export const exportAnnotations = (
     output += `I've reviewed this ${subject} and have ${annotations.length} piece${annotations.length > 1 ? 's' : ''} of feedback:\n\n`;
   }
 
-  sortedAnns.forEach((ann, index) => {
-    output += `## ${index + 1}. `;
+  // Live app sessions stamp annotations with the page they were made on.
+  // When any exported annotation carries a pageUrl, entries are grouped under
+  // per-page `## Page:` headings in order of first appearance and every entry
+  // demotes to `###` so it nests BELOW its page header (a `### Page:` header
+  // over `##` entries would invert the hierarchy); annotations without a page
+  // (e.g. globals) come first under no heading, at the same `###` level so
+  // entries render uniformly. Numbers stay GLOBAL: each entry keeps the
+  // number of its position in the ungrouped order, matching the on-page
+  // marker numbering, so grouped sections may show non-contiguous numbers.
+  // With no pageUrl anywhere the output is byte-identical to the ungrouped
+  // export (`## N.` entries, no page headers).
+  const hasPageGroups = sortedAnns.some(
+    (a: any) => typeof a.pageUrl === 'string' && a.pageUrl.length > 0,
+  );
+  const annotationNumbers = new Map<any, number>(
+    sortedAnns.map((ann, index) => [ann, index + 1]),
+  );
+  let emitOrder = sortedAnns;
+  if (hasPageGroups) {
+    const unpaged = sortedAnns.filter((a: any) => !a.pageUrl);
+    const pageOrder: string[] = [];
+    for (const ann of sortedAnns) {
+      if (ann.pageUrl && !pageOrder.includes(ann.pageUrl)) pageOrder.push(ann.pageUrl);
+    }
+    emitOrder = [
+      ...unpaged,
+      ...pageOrder.flatMap((page) => sortedAnns.filter((a: any) => a.pageUrl === page)),
+    ];
+  }
+
+  let lastEmittedPage: string | null = null;
+  emitOrder.forEach((ann) => {
+    if (hasPageGroups && ann.pageUrl && ann.pageUrl !== lastEmittedPage) {
+      output += `## Page: ${ann.pageUrl}\n\n`;
+      lastEmittedPage = ann.pageUrl;
+    }
+    output += `${hasPageGroups ? '###' : '##'} ${annotationNumbers.get(ann)}. `;
 
     // Add diff context label if annotation was created in diff view
     if (ann.diffContext) {

package/utils/vimNavigation.ts

@@ -1,3 +1,4 @@
+import { getScrollViewportRect } from '../hooks/useScrollViewport';
 import { getAnnotatableTextNodes } from './domSelection';
 
 /** A durable cursor location measured within one rendered Markdown block. */
@@ -132,7 +133,9 @@ function getViewportCenterY(
   container: HTMLElement,
   scrollViewport?: HTMLElement | null,
 ): number {
-  const rect = (scrollViewport ?? container).getBoundingClientRect();
+  const rect = scrollViewport
+    ? getScrollViewportRect(scrollViewport)
+    : container.getBoundingClientRect();
   return rect.top + rect.height / 2;
 }