@plannotator/ui 0.53.1 → 0.54.0

package/utils/documentFont.ts

@@ -0,0 +1,68 @@
+/**
+ * The document's font in plan review and annotate (Settings → Display →
+ * Document font, #1657): the family the document's text is drawn in. Empty by
+ * default, which keeps the theme's font (the document as it has always been
+ * drawn).
+ *
+ * The value is one of the generic presets below or the family name of a font
+ * installed on the machine, as for the code font (#851). A name always goes
+ * through `quoteFontFamily`, and the theme's sans font follows it, so a name
+ * that is not installed falls back to today's look.
+ *
+ * The app puts it on the document element (`applyDocumentFont`, through
+ * `hooks/useDocumentFont`) and packages/ui/theme.css hands it to the blocks of
+ * a document container (`data-doc-text-root`), the same scope as Text size.
+ * Code (inline code, code blocks, the raw diff) keeps the monospace font, and
+ * diagrams and the table / diagram popouts are left out.
+ */
+
+import { normalizeFontFamilyName, quoteFontFamily } from './cssFontFamily';
+
+/** Generic stacks Settings offers by name. Every one always resolves. */
+export const DOCUMENT_FONT_PRESETS = {
+  serif: 'ui-serif, Georgia, Cambria, "Times New Roman", Times, serif',
+  'sans-serif': 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+  monospace: 'var(--font-mono), ui-monospace, monospace',
+} as const;
+
+/** The options of the Settings select, Theme Default first. */
+export const DOCUMENT_FONT_OPTIONS = [
+  { value: '', label: 'Theme Default' },
+  { value: 'serif', label: 'Serif' },
+  { value: 'sans-serif', label: 'Sans Serif' },
+  { value: 'monospace', label: 'Monospace' },
+] as const;
+
+/** The attribute theme.css keys on; present only away from the default. */
+export const DOCUMENT_FONT_ATTRIBUTE = 'data-doc-font';
+
+/** The `font-family` value theme.css hands to the document's blocks. */
+export const DOCUMENT_FONT_PROPERTY = '--doc-font-family';
+
+/**
+ * The `font-family` value for a stored setting: a preset's stack, or the
+ * quoted name followed by the theme's sans font. Empty for the default.
+ */
+export function documentFontStack(value: string | undefined): string {
+  const name = value ? normalizeFontFamilyName(value) : '';
+  if (!name) return '';
+  if (Object.hasOwn(DOCUMENT_FONT_PRESETS, name)) {
+    return DOCUMENT_FONT_PRESETS[name as keyof typeof DOCUMENT_FONT_PRESETS];
+  }
+  return `${quoteFontFamily(name)}, var(--font-sans), sans-serif`;
+}
+
+/**
+ * Put `value` on `root` (the document element). At the default both the
+ * attribute and the property are removed, so nothing in theme.css applies.
+ */
+export function applyDocumentFont(root: HTMLElement, value: string | undefined): void {
+  const stack = documentFontStack(value);
+  if (!stack) {
+    root.removeAttribute(DOCUMENT_FONT_ATTRIBUTE);
+    root.style.removeProperty(DOCUMENT_FONT_PROPERTY);
+    return;
+  }
+  root.setAttribute(DOCUMENT_FONT_ATTRIBUTE, '');
+  root.style.setProperty(DOCUMENT_FONT_PROPERTY, stack);
+}

package/utils/documentTextSize.ts

@@ -0,0 +1,54 @@
+/**
+ * The document's text size in plan review and annotate (Settings → Display →
+ * Text size, #2066): the body text size in px, 15 by default (the document as
+ * it has always been drawn). Headings, lists, code, tables and question cards
+ * keep their proportions to it.
+ *
+ * The app puts it on the document element (`applyDocumentTextSize`, through
+ * `hooks/useDocumentTextSize`) and packages/ui/theme.css scales the blocks of
+ * a document container (`data-doc-text-root`) from `--doc-text-scale`. At the
+ * default nothing is set, so the page is exactly today's. Only the document's
+ * blocks scale: the header, panels, badges, menus and popouts keep their size.
+ * Raw HTML pages and diagrams draw themselves and do not follow it.
+ *
+ * Deliberately free of imports so the settings registry can read it on every
+ * surface (the guides.show viewer included).
+ */
+
+/** The steps Settings offers, in px of body text. */
+export const DOCUMENT_TEXT_SIZE_OPTIONS = [13, 15, 17, 19, 21] as const;
+
+export type DocumentTextSize = (typeof DOCUMENT_TEXT_SIZE_OPTIONS)[number];
+
+/** Today's body text size: paragraphs are `text-[15px]`. */
+export const DEFAULT_DOCUMENT_TEXT_SIZE: DocumentTextSize = 15;
+
+/** The attribute index.css keys on; present only away from the default. */
+export const DOCUMENT_TEXT_SIZE_ATTRIBUTE = 'data-doc-text-size';
+
+/** The multiplier index.css scales by (size / 15). */
+export const DOCUMENT_TEXT_SCALE_PROPERTY = '--doc-text-scale';
+
+/** Only an offered step is a size; anything else reads as the default. */
+export function isDocumentTextSize(value: unknown): value is DocumentTextSize {
+  return (DOCUMENT_TEXT_SIZE_OPTIONS as readonly unknown[]).includes(value);
+}
+
+/** The scale a size draws the document at, relative to today's. */
+export function documentTextScale(size: DocumentTextSize): number {
+  return size / DEFAULT_DOCUMENT_TEXT_SIZE;
+}
+
+/**
+ * Put `size` on `root` (the document element). At the default both the
+ * attribute and the property are removed, so nothing in index.css applies.
+ */
+export function applyDocumentTextSize(root: HTMLElement, size: number): void {
+  if (!isDocumentTextSize(size) || size === DEFAULT_DOCUMENT_TEXT_SIZE) {
+    root.removeAttribute(DOCUMENT_TEXT_SIZE_ATTRIBUTE);
+    root.style.removeProperty(DOCUMENT_TEXT_SCALE_PROPERTY);
+    return;
+  }
+  root.setAttribute(DOCUMENT_TEXT_SIZE_ATTRIBUTE, String(size));
+  root.style.setProperty(DOCUMENT_TEXT_SCALE_PROPERTY, String(documentTextScale(size)));
+}

package/utils/fontDetect.ts

@@ -0,0 +1,63 @@
+/**
+ * Local font detection via width measurement.
+ *
+ * Renders a glyph-diverse sample string with the candidate family in front of
+ * each generic fallback (monospace, serif, sans-serif) and compares measured
+ * widths against the fallback alone. If any pair differs, the browser resolved
+ * the candidate font — it is installed (or already loaded as a webfont).
+ *
+ * This observes actual rendering rather than querying font-availability APIs,
+ * so it is deterministic for a given machine + browser + installed-font set.
+ * `document.fonts.check()` is NOT used: its spec answers "would this render
+ * without a font load," which browsers answer inconsistently for families the
+ * page never registered.
+ *
+ * Known limits:
+ * - The name must be the family name as the OS reports it ("Iosevka Custom",
+ *   not a file name).
+ * - A font installed mid-session is picked up on the next call (no event).
+ */
+
+import { quoteFontFamily } from "./cssFontFamily";
+
+const SAMPLE = "mmmmmmmmmmlli0O1Il@#WQ";
+const SIZE = "72px";
+const GENERICS = ["monospace", "serif", "sans-serif"] as const;
+
+let ctx: CanvasRenderingContext2D | null | undefined;
+
+function getContext(): CanvasRenderingContext2D | null {
+  if (ctx !== undefined) return ctx;
+  try {
+    ctx = document.createElement("canvas").getContext("2d");
+  } catch {
+    ctx = null;
+  }
+  return ctx;
+}
+
+/**
+ * Check whether a font family resolves on this machine.
+ *
+ * Returns `true` / `false` from width measurement, or `null` when measurement
+ * is unavailable (no canvas) — callers should treat `null` as "unknown" and
+ * skip any installed/missing hint.
+ */
+export function isFontInstalled(
+  family: string,
+  context: Pick<CanvasRenderingContext2D, "font" | "measureText"> | null = getContext(),
+): boolean | null {
+  const quoted = quoteFontFamily(family);
+  if (!quoted) return false;
+
+  const c = context;
+  if (!c) return null;
+
+  for (const generic of GENERICS) {
+    c.font = `${SIZE} ${generic}`;
+    const base = c.measureText(SAMPLE).width;
+    c.font = `${SIZE} ${quoted}, ${generic}`;
+    if (c.measureText(SAMPLE).width !== base) return true;
+  }
+  return false;
+}

package/utils/inboxAnnouncement.ts

@@ -0,0 +1,78 @@
+/**
+ * One-time gate for the Plannotator Inbox announcement. Cookie-backed like the
+ * other announcement gates, so a dismissal survives Plannotator's random
+ * localhost ports, and shared by the plan editor, the annotate surfaces and
+ * the code review editor: dismissing it anywhere retires it everywhere.
+ *
+ * A plain storage key rather than a settings-registry entry for the same reason
+ * as terminalToolsAnnouncement.ts: configStore seeds every registry default
+ * into a cookie on first access, so a registry flag could not tell "never seen"
+ * from "seeded default".
+ */
+
+import { storage } from './storage';
+
+const STORAGE_KEY = 'plannotator-announce-inbox-seen';
+// Bump to re-announce after a meaningful revision.
+const CURRENT_VERSION = '1';
+
+export function needsInboxAnnouncement(): boolean {
+  return storage.getItem(STORAGE_KEY) !== CURRENT_VERSION;
+}
+
+export function markInboxAnnouncementSeen(): void {
+  storage.setItem(STORAGE_KEY, CURRENT_VERSION);
+}
+
+/**
+ * The page runs inside the VS Code extension's webview, whose theme bridge sets
+ * `window.__PLANNOTATOR_VSCODE` before the app script runs (the same flag
+ * useEditorAnnotations reads). Read per call, not at module load, so a test can
+ * set it.
+ */
+export function isVSCodeWebview(): boolean {
+  return typeof window !== 'undefined'
+    && (window as { __PLANNOTATOR_VSCODE?: unknown }).__PLANNOTATOR_VSCODE === true;
+}
+
+export interface InboxAnnouncementGateState {
+  /** Latched at mount from needsInboxAnnouncement(). */
+  readonly announcementPending: boolean;
+  /** The app has not finished loading its initial payload. */
+  readonly isLoading: boolean;
+  /**
+   * Archive browsing, a read-only shared plan, or no Plannotator server (the
+   * share portal and its demo). Deferred, not consumed.
+   */
+  readonly readOnlySession: boolean;
+  /** Inside the VS Code extension's webview (isVSCodeWebview). Deferred, not consumed. */
+  readonly vscodeWebview: boolean;
+  /** Any other first-run dialog is on screen. The chain dialogs never stack. */
+  readonly otherFirstRunDialogVisible: boolean;
+  /**
+   * The terminal-tools announcement takes this load: it is pending and can
+   * show on this surface, or it was shown on this load. Then this one waits
+   * for the next load, so a reader never gets two announcements in a row.
+   */
+  readonly earlierAnnouncementTakesThisLoad: boolean;
+}
+
+/**
+ * Whether the Inbox announcement may open now. After the terminal-tools
+ * announcement (never on the same load) and before "Ask this session" and the
+ * agent-tool offer, which wait while this one takes the load. Unlike its
+ * siblings it is not deferred on the compact touch shell: the panel is a video
+ * and one link, and the Inbox is read on a phone too. The Apps pass this
+ * through useFirstRunAnnouncementWindow, so it only opens before the reader
+ * has started working.
+ */
+export function inboxAnnouncementEligible(state: InboxAnnouncementGateState): boolean {
+  return (
+    state.announcementPending &&
+    !state.isLoading &&
+    !state.readOnlySession &&
+    !state.vscodeWebview &&
+    !state.otherFirstRunDialogVisible &&
+    !state.earlierAnnouncementTakesThisLoad
+  );
+}

package/utils/lookAndFeelAnnouncement.ts

@@ -2,21 +2,98 @@
  * 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.
+ * So `gridEnabled` trusts its stored value only once this decision is resolved
+ * (see `config/settings.ts`); before that, everyone gets the default, Clean.
+ *
+ * Two generations of marker:
+ *  - v1: `plannotator-plan-look-choice-resolved=true`, or the 0.20.0 chooser's
+ *    `plannotator-look-feel-announcement-seen=2`. Both choosers opened with
+ *    Grid preselected, so a v1 marker next to a stored Grid does not tell a
+ *    real Grid choice from a Continue on the preselected default.
+ *  - v2: `plannotator-plan-look-v2` = `resolved` (a choice made since Clean
+ *    became the default: the chooser's Continue or Escape, or the Settings
+ *    switch) or `notice` (moved to Clean once, the notice not yet seen).
+ *
+ * The owner's decision (2026-10-27): everyone holding only a v1 marker with
+ * Grid stored moves to Clean once and sees a one-time notice (the chooser,
+ * Clean preselected); Clean users are marked v2 silently. v2 lives under its
+ * own key, and resolving still writes the v1 key, so an older Plannotator
+ * build sharing the cookie jar never re-asks and can never write a v1 marker
+ * over a v2 choice (which would move that person again).
  */
 
 import { storage } from './storage';
 
 const CHOICE_RESOLVED_KEY = 'plannotator-plan-look-choice-resolved';
 const LEGACY_ANNOUNCEMENT_KEY = 'plannotator-look-feel-announcement-seen';
+const V2_KEY = 'plannotator-plan-look-v2';
+const GRID_KEY = 'plannotator-grid-enabled';
+
+/** Which plan-look dialog this person needs: the first-run chooser, the one-time "moved to Clean" notice, or none. */
+export type PlanLookPrompt = 'first-run' | 'moved' | null;
+
+function hasV1Marker(): boolean {
+  return storage.getItem(CHOICE_RESOLVED_KEY) === 'true'
+    || storage.getItem(LEGACY_ANNOUNCEMENT_KEY) === '2';
+}
+
+/**
+ * Upgrade a v1 marker to v2, once. Grid stored → Clean, notice pending;
+ * anything else → resolved, silently. Idempotent: does nothing once v2 is set
+ * or when there is no marker at all (a first run).
+ */
+export function migratePlanLookChoice(): void {
+  if (storage.getItem(V2_KEY) !== null) return;
+  if (!hasV1Marker()) return;
+  if (storage.getItem(GRID_KEY) === 'true') {
+    storage.setItem(GRID_KEY, 'false');
+    storage.setItem(V2_KEY, 'notice');
+  } else {
+    storage.setItem(V2_KEY, 'resolved');
+  }
+}
+
+/**
+ * The v2 marker after migration. A `resolved` read is written again: cookies
+ * last a year from their last write, and an older build can keep the v1
+ * marker and a stored Grid alive. If v2 expired first, the next load would
+ * move the person to Clean a second time.
+ */
+function readV2(): string | null {
+  migratePlanLookChoice();
+  const v2 = storage.getItem(V2_KEY);
+  if (v2 === 'resolved') storage.setItem(V2_KEY, 'resolved');
+  return v2;
+}
+
+/** True once the person picked Grid or Clean under the Clean default (chooser, notice or Settings). */
+export function isLookChoiceResolved(): boolean {
+  return readV2() === 'resolved';
+}
+
+export function planLookPrompt(): PlanLookPrompt {
+  const v2 = readV2();
+  if (v2 === 'resolved') return null;
+  return v2 === 'notice' ? 'moved' : 'first-run';
+}
+
+/**
+ * The look another tab already chose, or null while the choice is still open.
+ * Two open tabs both show the chooser or notice; when one is answered, the
+ * other must adopt that answer, not write its own preselected Clean over a
+ * Grid picked in the first tab.
+ */
+export function planLookAnsweredElsewhere(): boolean | null {
+  if (storage.getItem(V2_KEY) !== 'resolved') return null;
+  return storage.getItem(GRID_KEY) === 'true';
+}
 
 export function needsLookAndFeelAnnouncement(): boolean {
-  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';
+  return planLookPrompt() !== null;
 }
 
 export function markLookAndFeelChoiceResolved(): void {
+  storage.setItem(V2_KEY, 'resolved');
+  // Older builds read only this key; without it they would ask again.
   storage.setItem(CHOICE_RESOLVED_KEY, 'true');
 }

package/utils/markdownExtensions.ts

@@ -13,14 +13,14 @@
  * 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
+ * the server (`.md`/`.mdx`/`.txt`/`.adoc`/`.asciidoc`/`.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;
+const BUILTIN_LINKED_DOC_REGEX = /\.(mdx?|txt|adoc|asciidoc|html?)$/i;
 
 let extraExtensions: string[] = [];
 

package/utils/mermaid.ts

@@ -11,9 +11,8 @@
  * the lazy path IS Plannotator's own path: `packages/editor/App.tsx` no longer
  * imports `./mermaid-eager`, so a plan with no diagram never downloads the
  * runtime in a chunked build (the share portal, any host that bundles by
- * route). The single-file builds inline the `import('mermaid')` target through
- * `inlineDynamicImports`, so there the lazy import resolves from the bundle
- * itself and nothing is fetched. A host that wants the runtime registered at
+ * route), nor in the single-file builds, which carry it as a packed chunk
+ * their server serves on request (build/pack-app.ts). A host that wants the runtime registered at
  * startup imports `./mermaid-eager`, which fills the slot at module
  * evaluation; the slot then short-circuits this loader.
  *
@@ -22,6 +21,16 @@
  */
 import type { Mermaid, MermaidConfig } from 'mermaid';
 
+/**
+ * Width in px at which node labels wrap (#2064). Mermaid 12 lowered the
+ * default from 200 to 120, and at Plannotator's 16 px label text that wraps
+ * after about eight CJK characters and splits short Latin labels. 140 is the
+ * owner-approved middle: long labels still wrap, short ones stay on one line.
+ * The themed path (`buildMermaidConfig`) spreads this config, so both the
+ * themed and the host-fallback `initialize` carry it.
+ */
+export const MERMAID_LABEL_WRAP_WIDTH = 140;
+
 /**
  * Hoisted verbatim from the former module-scope `mermaid.initialize(...)` in
  * MermaidBlock. Nothing in it reads a CSS token or the resolved mode.
@@ -61,6 +70,14 @@ export const MERMAID_CONFIG: MermaidConfig = {
   flowchart: {
     htmlLabels: true,
     curve: 'basis',
+    wrappingWidth: MERMAID_LABEL_WRAP_WIDTH,
+  },
+  /**
+   * Mermaid 11 drew state labels with the flowchart width; Mermaid 12 gives
+   * state diagrams their own `wrappingWidth`, also 120, so it is pinned too.
+   */
+  state: {
+    wrappingWidth: MERMAID_LABEL_WRAP_WIDTH,
   },
 };
 

package/utils/mermaidTheme.ts

@@ -70,6 +70,7 @@
  */
 import type { Mermaid, MermaidConfig } from 'mermaid';
 import { MERMAID_CONFIG } from './mermaid';
+import { readThemeTokenValues } from './themeTokens';
 import {
   compositeOver,
   contrastRatio,
@@ -183,57 +184,8 @@ const CANVAS_MUTED_ALPHA = 0.3;
  * is the signal to keep the static config.
  */
 export function readThemeTokens(el?: Element | null): MermaidThemeTokens | undefined {
-  if (typeof document === 'undefined' || typeof getComputedStyle !== 'function') return undefined;
-  const target = el ?? document.documentElement;
-  if (!target) return undefined;
-  let computed: CSSStyleDeclaration;
-  try {
-    computed = getComputedStyle(target);
-  } catch {
-    return undefined;
-  }
-  const tokens: MermaidThemeTokens = {};
-  let probe: HTMLElement | null = null;
-  try {
-    for (const name of MERMAID_THEME_TOKEN_NAMES) {
-      let raw = '';
-      try {
-        raw = computed.getPropertyValue(`--${name}`).trim();
-      } catch {
-        raw = '';
-      }
-      if (!raw) continue;
-      if (name === 'font-sans') {
-        tokens[name] = raw;
-        continue;
-      }
-      if (parseCssColor(raw)) {
-        tokens[name] = raw;
-        continue;
-      }
-      // Unparsable as written: let the engine resolve it to a colour.
-      try {
-        if (!probe) {
-          probe = document.createElement('span');
-          probe.setAttribute('aria-hidden', 'true');
-          probe.style.position = 'absolute';
-          probe.style.width = '0';
-          probe.style.height = '0';
-          probe.style.overflow = 'hidden';
-          probe.style.pointerEvents = 'none';
-          target.appendChild(probe);
-        }
-        probe.style.color = `var(--${name})`;
-        const resolved = getComputedStyle(probe).color.trim();
-        if (resolved && parseCssColor(resolved)) tokens[name] = resolved;
-      } catch {
-        // leave the token absent
-      }
-    }
-  } finally {
-    probe?.remove();
-  }
-  if (!tokens.background || !tokens.foreground) return undefined;
+  const tokens: MermaidThemeTokens | undefined = readThemeTokenValues(MERMAID_THEME_TOKEN_NAMES, el, ['font-sans']);
+  if (!tokens?.background || !tokens.foreground) return undefined;
   return tokens;
 }
 

package/utils/notion.ts

@@ -0,0 +1,58 @@
+import { storage } from './storage';
+
+const STORAGE_KEY_ENABLED = 'plannotator-notion-enabled';
+const STORAGE_KEY_PARENT_PAGE_ID = 'plannotator-notion-parent-page-id';
+const STORAGE_KEY_AUTOSAVE = 'plannotator-notion-autosave';
+
+export interface NotionSettings {
+  enabled: boolean;
+  parentPageId: string;
+  autoSave: boolean;
+}
+
+/**
+ * Whether this server offers Notion (`notion: true` from /api/plan): it has
+ * NOTION_TOKEN and the session is only on this computer. Off until the app
+ * hears otherwise, so the option stays hidden everywhere else.
+ */
+let available = false;
+
+export function setNotionAvailable(value: boolean): void {
+  available = value;
+}
+
+export function isNotionAvailable(): boolean {
+  return available;
+}
+
+/** Extract and normalize a Notion page UUID from either an ID or a page URL. */
+export function normalizeNotionPageId(value: string): string | null {
+  const match = value.trim().match(/[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}/i);
+  if (!match) return null;
+  const compact = match[0].replace(/-/g, '').toLowerCase();
+  return `${compact.slice(0, 8)}-${compact.slice(8, 12)}-${compact.slice(12, 16)}-${compact.slice(16, 20)}-${compact.slice(20)}`;
+}
+
+export function getNotionSettings(): NotionSettings {
+  return {
+    enabled: storage.getItem(STORAGE_KEY_ENABLED) === 'true',
+    parentPageId: storage.getItem(STORAGE_KEY_PARENT_PAGE_ID) ?? '',
+    autoSave: storage.getItem(STORAGE_KEY_AUTOSAVE) === 'true',
+  };
+}
+
+export function saveNotionSettings(settings: NotionSettings): void {
+  storage.setItem(STORAGE_KEY_ENABLED, String(settings.enabled));
+  storage.setItem(STORAGE_KEY_PARENT_PAGE_ID, settings.parentPageId);
+  storage.setItem(STORAGE_KEY_AUTOSAVE, String(settings.autoSave));
+}
+
+/** The parent page to save under, or null when Notion is not offered, off, or has no valid page. */
+export function getNotionParentPageId(settings: NotionSettings = getNotionSettings()): string | null {
+  if (!available || !settings.enabled) return null;
+  return normalizeNotionPageId(settings.parentPageId);
+}
+
+export function isNotionConfigured(): boolean {
+  return getNotionParentPageId() !== null;
+}

package/utils/parser.ts

@@ -2,6 +2,7 @@ import type { Block, Annotation, CodeAnnotation, EditorAnnotation, ImageAttachme
 import { planDenyFeedback } from '@plannotator/core/feedback-templates';
 import { resolveReplyParents } from '@plannotator/core/annotation-threads';
 import { diagramAnchorLocationLine, parseDiagramAnchor } from '@plannotator/core/diagram-anchor';
+import { imageRegionLocationLines, parseImageRegion, type ImageRegion } from '@plannotator/core/image-region';
 import {
   formatQuestionAnswerLines,
   formatQuestionAnswerText,
@@ -779,6 +780,8 @@ const isElementPlaceholderQuote = (text: unknown): boolean =>
  *  element instead (`Feedback on the <nav> element — "Primary"`); every other
  *  annotation keeps the quote line exactly as before. */
 const commentHeadingLine = (ann: any): string => {
+  const region = imageRegionOf(ann);
+  if (region) return `Feedback on a region of the image ${safeInline(region.src, 600)}`;
   const element = elementSubject(ann);
   return element ? `Feedback on ${element}` : `Feedback on: "${ann.originalText}"`;
 };
@@ -1001,6 +1004,8 @@ export const exportAnnotationEntry = (ann: any, opts: ElementContextExportOption
     default:
       if (ann?.isQuickLabel) {
         output += `[${ann.text}] ${commentHeadingLine(ann)}\n`;
+        const region = imageRegionOf(ann);
+        if (region) output += imageRegionExportLines(region);
         if (ann.quickLabelTip) output += `> ${ann.quickLabelTip}\n`;
       } else {
         output += `${commentHeadingLine(ann)}\n${diagramLocationExportLine(ann)}> ${ann?.text ?? ''}\n`;
@@ -1021,12 +1026,28 @@ export const exportAnnotationEntry = (ann: any, opts: ElementContextExportOption
   return output;
 };
 
+/** The validated region of a comment on part of an image (#2100), or null
+ *  for every other annotation and for a malformed one (an older or foreign
+ *  writer), which then exports as the ordinary comment it also is. */
+const imageRegionOf = (ann: any): ImageRegion | null =>
+  ann?.imageRegion == null ? null : parseImageRegion(ann.imageRegion);
+
+/** The two location lines under a region comment (the approved prototype):
+ *  `Image: figures/status-colors.png (line 63)` then
+ *  `Region: x=1820 y=380 w=420 h=160 (of 3664×1453)` — the image as written,
+ *  its line, and the box in the image's own pixels. The src is collapsed to
+ *  one line and defused like every page-controlled string. */
+const imageRegionExportLines = (region: ImageRegion): string =>
+  `${imageRegionLocationLines({ ...region, src: safeInline(region.src, 600) })}\n`;
+
 /** The location line under a comment made on a rendered diagram part:
  *  `Diagram node Approve? (D), line 4` — the part's own id (what the agent
  *  greps the fence for) and the DOCUMENT line that declares it. Emits
  *  nothing for every other annotation, keeping their output byte-identical;
  *  a malformed anchor (an older or foreign writer) is skipped, never thrown. */
 const diagramLocationExportLine = (ann: any): string => {
+  const region = imageRegionOf(ann);
+  if (region) return imageRegionExportLines(region);
   const anchor = ann?.diagramAnchor === undefined ? null : parseDiagramAnchor(ann.diagramAnchor);
   if (anchor !== null) return `${safeInline(diagramAnchorLocationLine(anchor), 600)}\n`;
   return hostLocationExportLine(ann);
@@ -1043,6 +1064,9 @@ const hostLocationExportLine = (ann: any): string => {
 
 const lineLabelForAnnotation = (blocks: Block[], ann: any): string | null => {
   if (!ann.blockId || ann.type === 'GLOBAL_COMMENT') return null;
+  // A region names the line its image is written on, not its block's span.
+  const region = imageRegionOf(ann);
+  if (region?.sourceLine != null) return `line ${region.sourceLine}`;
   if (typeof ann.blockId === 'string' && ann.blockId.startsWith('diff-block-')) return null;
   const block = blocks.find(b => b.id === ann.blockId);
   if (!block || typeof block.startLine !== 'number') return null;
@@ -1615,7 +1639,10 @@ export const formatDraftAnnotationsForAsk = (input: DraftAnnotationsForAsk): str
     } else {
       const subject = elementSubject(ann) ?? quote(ann.originalText);
       const anchor = ann.diagramAnchor === undefined ? null : parseDiagramAnchor(ann.diagramAnchor);
-      const target = anchor ? `${subject} [${safeInline(diagramAnchorLocationLine(anchor), 300)}]` : subject;
+      const region = imageRegionOf(ann);
+      const target = region
+        ? `a region of the image ${quote(region.src)} [${safeInline(imageRegionLocationLines(region).replace('\n', '; '), 300)}]`
+        : anchor ? `${subject} [${safeInline(diagramAnchorLocationLine(anchor), 300)}]` : subject;
       body = ann.isQuickLabel
         ? `label ${quote(ann.text)} on ${target}`
         : `comment on ${target} — ${text(ann.text)}`;