@plannotator/ui 0.53.0 → 0.54.0

package/utils/scrollAnchor.ts

@@ -0,0 +1,82 @@
+/**
+ * Remember where a reader was in a rendered document, and put them back there.
+ *
+ * Raw pixels are a poor bookmark: images that finish loading, highlights that
+ * are re-applied, or a sidebar that changes the reading column's width all move
+ * the text under a fixed scrollTop. So the anchor is the first block
+ * (`data-block-id`) still visible at the top of the scroll viewport, plus how
+ * far its top sat from the viewport's top. Restoring scrolls that block back to
+ * the same offset; the raw scrollTop is only the fallback when the block is
+ * gone.
+ */
+
+import {
+  getScrollViewportRect,
+  getScrollViewportTop,
+  offsetScrollViewport,
+  scrollViewportTo,
+} from '../hooks/useScrollViewport';
+
+export interface ScrollAnchor {
+  /** The first block visible at the top of the viewport, null when none is. */
+  blockId: string | null;
+  /** That block's top minus the viewport's top, in CSS pixels (≤ 0 when the
+   *  block starts above the viewport). */
+  offset: number;
+  /** The viewport's scrollTop when captured — the fallback. */
+  scrollTop: number;
+}
+
+function blocksIn(viewport: HTMLElement): HTMLElement[] {
+  return Array.from(viewport.querySelectorAll<HTMLElement>('[data-block-id]'));
+}
+
+/** Capture where the reader is in `viewport`. */
+export function captureScrollAnchor(viewport: HTMLElement): ScrollAnchor {
+  const scrollTop = getScrollViewportTop(viewport);
+  const viewportTop = getScrollViewportRect(viewport).top;
+  for (const block of blocksIn(viewport)) {
+    const rect = block.getBoundingClientRect();
+    if (rect.height <= 0 && rect.width <= 0) continue;
+    if (rect.bottom > viewportTop + 1) {
+      return {
+        blockId: block.getAttribute('data-block-id'),
+        offset: rect.top - viewportTop,
+        scrollTop,
+      };
+    }
+  }
+  return { blockId: null, offset: 0, scrollTop };
+}
+
+function findBlock(viewport: HTMLElement, blockId: string): HTMLElement | null {
+  for (const block of blocksIn(viewport)) {
+    if (block.getAttribute('data-block-id') === blockId) return block;
+  }
+  return null;
+}
+
+/**
+ * Whether the anchor's block is in the viewport's DOM yet. A document that is
+ * still mounting has none of its blocks, so a caller can wait for this.
+ */
+export function scrollAnchorReady(viewport: HTMLElement, anchor: ScrollAnchor): boolean {
+  if (anchor.blockId === null) return blocksIn(viewport).length > 0 || anchor.scrollTop === 0;
+  return findBlock(viewport, anchor.blockId) !== null;
+}
+
+/**
+ * Put the reader back at `anchor`. Returns the viewport's scrollTop afterwards.
+ * When the anchor's block is gone, falls back to the captured scrollTop.
+ */
+export function restoreScrollAnchor(viewport: HTMLElement, anchor: ScrollAnchor): number {
+  const block = anchor.blockId === null ? null : findBlock(viewport, anchor.blockId);
+  if (block) {
+    const viewportTop = getScrollViewportRect(viewport).top;
+    const delta = block.getBoundingClientRect().top - viewportTop - anchor.offset;
+    if (Math.abs(delta) >= 1) offsetScrollViewport(viewport, delta);
+  } else if (Math.abs(getScrollViewportTop(viewport) - anchor.scrollTop) >= 1) {
+    scrollViewportTo(viewport, { top: anchor.scrollTop, behavior: 'auto' });
+  }
+  return getScrollViewportTop(viewport);
+}

package/utils/sectionRefs.ts

@@ -0,0 +1,123 @@
+/**
+ * `#Heading` references inside annotation text.
+ *
+ * Typing `#` followed by a heading's exact text links to that heading. Only
+ * headings in the current document resolve, so `#123`, `#fff` or a URL
+ * fragment stay plain text unless a heading is literally named that way.
+ */
+
+import { buildHeadingSlugMap } from './slugify';
+import { transformPlainText } from './inlineTransforms';
+
+export interface SectionRefSegment {
+  /** The heading text, shown as the link label. */
+  label: string;
+  /** The heading's anchor id in the rendered document. */
+  anchor: string;
+}
+
+export type SectionRefPart = string | SectionRefSegment;
+
+/** A heading's text without its inline markdown syntax. */
+function stripHeadingMarkdown(content: string): string {
+  return content
+    .replace(/\[\[([^\]]+)\]\]/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/[*_`~]/g, '');
+}
+
+/**
+ * Heading text → anchor id. Each heading is indexed under its markdown source
+ * (`**Don't** ship`), the text the page shows (`Don’t ship`), and that text as
+ * typed with straight quotes (`Don't ship`). A title that two different
+ * headings share is left out: it could mean either.
+ */
+export function buildSectionRefIndex(
+  blocks: Array<{ id: string; type: string; content: string }>,
+): Map<string, string> {
+  const slugs = buildHeadingSlugMap(blocks);
+  const index = new Map<string, string>();
+  const ambiguous = new Set<string>();
+
+  const register = (title: string, anchor: string) => {
+    const key = title.trim();
+    if (!key) return;
+    const existing = index.get(key);
+    if (existing === undefined) index.set(key, anchor);
+    else if (existing !== anchor) ambiguous.add(key);
+  };
+
+  for (const block of blocks) {
+    if (block.type !== 'heading') continue;
+    const anchor = slugs.get(block.id);
+    if (!anchor) continue;
+    const stripped = stripHeadingMarkdown(block.content);
+    register(block.content, anchor);
+    register(stripped, anchor);
+    register(transformPlainText(stripped), anchor);
+  }
+
+  for (const title of ambiguous) index.delete(title);
+  return index;
+}
+
+// A reference starts a word: at the start, after whitespace, or after an
+// opening bracket or quote. This keeps `C#`, `issue#4` and `page/#intro` plain.
+const REF_START = /[\s([{"'“‘「]/u;
+const SPACED_WORD = /[\p{Script=Latin}\p{Script=Cyrillic}\p{Script=Greek}\p{N}_]/u;
+
+function matchAt(text: string, hash: number, titles: string[]): string | null {
+  // `# Title` is a markdown heading, not a reference.
+  if (hash + 1 >= text.length || /\s/.test(text[hash + 1]!)) return null;
+  // Longest first, so `#3.1 Scope` beats a sibling heading named `3.1`.
+  for (const title of titles) {
+    if (!text.startsWith(title, hash + 1)) continue;
+    // `#Intro` must not link inside `#Introduction`. Only scripts that space
+    // their words need the boundary: elsewhere a suffix follows the title directly.
+    const end = hash + 1 + title.length;
+    const next = text.slice(end, end + 2).match(/^./su)?.[0];
+    const last = title.match(/.$/su)?.[0];
+    if (next && last && SPACED_WORD.test(next) && SPACED_WORD.test(last)) continue;
+    return title;
+  }
+  return null;
+}
+
+/**
+ * Split annotation text into plain runs and `#Heading` references. Returns
+ * `[text]` when nothing resolves. Text inside backticks is never linked.
+ */
+export function parseSectionRefs(text: string, index: Map<string, string>): SectionRefPart[] {
+  if (!text || index.size === 0 || !text.includes('#')) return [text];
+
+  const titles = [...index.keys()].sort((a, b) => b.length - a.length);
+  const parts: SectionRefPart[] = [];
+  let plain = '';
+  let i = 0;
+
+  while (i < text.length) {
+    const ch = text[i]!;
+    const close = ch === '`' ? text.indexOf('`', i + 1) : -1;
+    if (close !== -1) {
+      plain += text.slice(i, close + 1);
+      i = close + 1;
+      continue;
+    }
+    const title =
+      ch === '#' && (i === 0 || REF_START.test(text[i - 1]!))
+        ? matchAt(text, i, titles)
+        : null;
+    if (!title) {
+      plain += ch;
+      i += 1;
+      continue;
+    }
+    if (plain) parts.push(plain);
+    plain = '';
+    parts.push({ label: title, anchor: index.get(title)! });
+    i += 1 + title.length;
+  }
+
+  if (plain) parts.push(plain);
+  return parts.some((p) => typeof p !== 'string') ? parts : [text];
+}

package/utils/selectionBoundary.ts

@@ -0,0 +1,40 @@
+/**
+ * Boundary trimming for web-highlighter's `Render.SelectedNodes` hook.
+ *
+ * Lives in its own pure module so it can be unit-tested without a DOM:
+ * useAnnotationHighlighter imports @plannotator/web-highlighter, whose UMD
+ * bundle reads `window` at module-eval time.
+ */
+
+/**
+ * Minimal structural view of web-highlighter's `SelectedNode`: only the field
+ * the trim actually reads. Declared locally rather than imported from the
+ * package's `dist/`, which resolves today only because the fork ships no
+ * `exports` map; a republish that adds one would break consumers compiling
+ * @plannotator/ui from source.
+ */
+export interface SelectedNodeLike {
+  $node: { textContent: string | null };
+}
+
+/**
+ * Drop whitespace-only nodes from the leading and trailing ends of the node
+ * list web-highlighter is about to wrap. Whitespace-only nodes in the MIDDLE of
+ * a genuine multi-node selection are kept, so inter-node spacing stays
+ * highlighted.
+ */
+export const trimWhitespaceOnlyBoundaryNodes = (
+  selectedNodes: SelectedNodeLike[],
+): SelectedNodeLike[] => {
+  let start = 0;
+  while (start < selectedNodes.length && !/\S/.test(selectedNodes[start].$node.textContent ?? '')) {
+    start += 1;
+  }
+
+  let end = selectedNodes.length;
+  while (end > start && !/\S/.test(selectedNodes[end - 1].$node.textContent ?? '')) {
+    end -= 1;
+  }
+
+  return selectedNodes.slice(start, end);
+};

package/utils/sendFailure.ts

@@ -0,0 +1,85 @@
+/**
+ * Why a decision POST (send feedback, approve, deny) did not land (#1392).
+ *
+ * The review pages used to swallow these failures: a POST to a server that
+ * had stopped rejected with a network error, the catch only re-enabled the
+ * button, and the reviewer could not tell that nothing reached the agent.
+ * The handlers now tag the failure so the page can say which one happened
+ * (`SendFailureToast`).
+ */
+
+/** The `code` every plan, annotate and review server (Bun and Pi) puts on its
+ *  409 for a decision that arrives after the review was decided or closed
+ *  (also `packages/shared/host-control.ts`). */
+export const ALREADY_DECIDED_CODE = 'already_decided';
+
+/** The `code` of plan review's 409 for a decision on an older revision. */
+export const PLAN_REVISED_CODE = 'plan_revised';
+
+export type SendFailure =
+  /** fetch rejected: the server is gone (stopped, crashed) or unreachable. */
+  | { kind: 'unreachable' }
+  /** The server answered with a non-2xx status it has no dedicated UI for. */
+  | { kind: 'rejected'; status: number }
+  /** The review was decided already (another window sent it, or the session
+   *  that opened it ended). Sending again cannot work. */
+  | { kind: 'decided' }
+  /** Anything else thrown before the response settled. */
+  | { kind: 'unknown' };
+
+export class DecisionSendError extends Error {
+  readonly failure: SendFailure;
+  constructor(failure: SendFailure, options?: { cause?: unknown }) {
+    super(`Decision not sent (${failure.kind})`, options);
+    this.name = 'DecisionSendError';
+    this.failure = failure;
+  }
+}
+
+/** `.catch()` for a decision fetch: a rejected fetch means the server is unreachable. */
+export function throwUnreachable(cause: unknown): never {
+  throw new DecisionSendError({ kind: 'unreachable' }, { cause });
+}
+
+/** The `code` of a refusal body, when it has one. Never consumes `res`. */
+export async function refusalCode(res: Response): Promise<string | undefined> {
+  try {
+    const code = ((await res.clone().json()) as { code?: unknown } | null)?.code;
+    return typeof code === 'string' ? code : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Throws the failure for a response that is not ok: `decided` for the
+ *  servers' already-decided refusal, `rejected` with the status otherwise. */
+export async function assertSendOk(res: Response): Promise<void> {
+  if (res.ok) return;
+  if (res.status === 409 && (await refusalCode(res)) === ALREADY_DECIDED_CODE) {
+    throw new DecisionSendError({ kind: 'decided' });
+  }
+  throw new DecisionSendError({ kind: 'rejected', status: res.status });
+}
+
+export function sendFailureOf(error: unknown): SendFailure {
+  return error instanceof DecisionSendError ? error.failure : { kind: 'unknown' };
+}
+
+/** Whether sending the same decision again could work. */
+export function canRetrySend(failure: SendFailure): boolean {
+  return failure.kind !== 'decided';
+}
+
+/** The one sentence under the toast's title: why nothing reached the agent. */
+export function describeSendFailure(failure: SendFailure): string {
+  switch (failure.kind) {
+    case 'unreachable':
+      return "Plannotator isn't running or can't be reached.";
+    case 'rejected':
+      return `Plannotator answered with an error (${failure.status}).`;
+    case 'decided':
+      return 'This review was already decided, in another window or because its session ended.';
+    default:
+      return 'Something went wrong before it was sent.';
+  }
+}

package/utils/sharing.ts

@@ -29,7 +29,7 @@ export interface SharePayload {
   d?: (string | null)[];  // diffContext per annotation, parallel to `a`
   s?: (string | undefined)[];  // source per annotation (external tool identifier), parallel to `a`
   h?: string;  // raw HTML content (direct HTML rendering mode)
-  r?: 'html';  // render mode flag (omitted = markdown)
+  r?: 'html' | 'asciidoc';  // render mode flag (omitted = markdown)
 }
 
 /**
@@ -192,6 +192,7 @@ export async function generateShareUrl(
   globalAttachments?: ImageAttachment[],
   baseUrl: string = DEFAULT_SHARE_BASE,
   rawHtml?: string,
+  renderAs?: DocumentRenderAs,
 ): Promise<string | null> {
   // HTML content is too large for URL hashes — force paste service path
   if (rawHtml) return null;
@@ -203,6 +204,7 @@ export async function generateShareUrl(
     g: globalAttachments?.length ? toShareableImages(globalAttachments) : undefined,
     ...(diffContexts ? { d: diffContexts } : {}),
     ...(sources ? { s: sources } : {}),
+    ...(renderAs === 'asciidoc' ? { r: 'asciidoc' as const } : {}),
   };
 
   const hash = await compress(payload);
@@ -274,6 +276,7 @@ export async function createShortShareUrl(
     shareBaseUrl?: string;
   },
   rawHtml?: string,
+  renderAs?: DocumentRenderAs,
 ): Promise<{ shortUrl: string; id: string } | null> {
   const pasteApi = options?.pasteApiUrl ?? DEFAULT_PASTE_API;
   const shareBase = options?.shareBaseUrl ?? DEFAULT_SHARE_BASE;
@@ -287,7 +290,7 @@ export async function createShortShareUrl(
       g: globalAttachments?.length ? toShareableImages(globalAttachments) : undefined,
       ...(diffContexts ? { d: diffContexts } : {}),
       ...(sources ? { s: sources } : {}),
-      ...(rawHtml ? { h: rawHtml, r: 'html' as const } : {}),
+      ...(rawHtml ? { h: rawHtml, r: 'html' as const } : renderAs === 'asciidoc' ? { r: 'asciidoc' as const } : {}),
     };
 
     const compressed = await compress(payload);

package/utils/themeRegistry.ts

@@ -31,6 +31,16 @@ export const BUILT_IN_THEMES: ThemeInfo[] = [
       light: { primary: 'oklch(0.50 0.25 280)', secondary: 'oklch(0.50 0.18 180)', accent: 'oklch(0.60 0.22 50)', background: 'oklch(0.97 0.005 260)', foreground: 'oklch(0.18 0.02 260)' },
     },
   },
+  {
+    id: 'plannotator-graphite',
+    name: 'Plannotator Graphite',
+    builtIn: true,
+    modeSupport: 'both',
+    colors: {
+      dark: { primary: 'oklch(0.765 0.124 283)', secondary: 'oklch(0.740 0.123 180)', accent: 'oklch(0.765 0.156 60)', background: 'oklch(0.225 0.006 286)', foreground: 'oklch(0.945 0.003 286)' },
+      light: { primary: 'oklch(0.50 0.25 280)', secondary: 'oklch(0.50 0.18 180)', accent: 'oklch(0.60 0.22 50)', background: 'oklch(0.97 0.005 260)', foreground: 'oklch(0.18 0.02 260)' },
+    },
+  },
   {
     id: 'simple',
     name: 'Simple',

package/utils/themeTokens.ts

@@ -0,0 +1,74 @@
+/**
+ * Reading the live theme tokens off the document, for code that derives
+ * colours from the palette on screen (Mermaid's theme, the review sidebar's
+ * +/- counts). Browser-only, and free of any diagram code, so a bundle that
+ * only needs the tokens never pulls a diagram runtime in.
+ */
+import { parseCssColor } from './cssColor';
+
+/**
+ * Read the custom properties `names` off `el` (default: the document element,
+ * where `ThemeProvider` puts the `theme-*` / `light` classes). Colours the
+ * parser does not understand as written (`color-mix()`, a `var()` chain) are
+ * resolved through a throwaway probe element so the engine does the
+ * substitution; names in `raw` are returned as written (a font stack).
+ * Returns `undefined` outside a browser; a token that does not resolve is
+ * left out.
+ */
+export function readThemeTokenValues<N extends string>(
+  names: readonly N[],
+  el?: Element | null,
+  raw: readonly N[] = [],
+): Partial<Record<N, string>> | 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: Partial<Record<N, string>> = {};
+  let probe: HTMLElement | null = null;
+  try {
+    for (const name of names) {
+      let value = '';
+      try {
+        value = computed.getPropertyValue(`--${name}`).trim();
+      } catch {
+        value = '';
+      }
+      if (!value) continue;
+      if (raw.includes(name)) {
+        tokens[name] = value;
+        continue;
+      }
+      if (parseCssColor(value)) {
+        tokens[name] = value;
+        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();
+  }
+  return tokens;
+}

package/utils/updateNotice.ts

@@ -3,10 +3,10 @@
  * .product/approved/plannotator-updates/ §4.5, owner's answers 1 and 3).
  *
  * The server says whether a newer release exists (`updateAvailable` on
- * /api/plan and /api/diff, from the machine's once-a-day check): the browser
+ * /api/plan and /api/diff, from the machine's own check): the browser
  * never asks GitHub. This module parses that advert, decides whether the toast
- * may show now (once per version, and at most once every three days across
- * versions, remembered in a cookie that every localhost port shares), and
+ * may show now (once per version, and at most once a day across versions,
+ * remembered in a cookie that every localhost port shares), and
  * words the toast for the host that launched the session.
  */
 
@@ -25,8 +25,30 @@ export interface UpdateAdvert {
   publishedAt?: string;
 }
 
-/** The toast shows at most this often, across versions. */
-export const UPDATE_TOAST_INTERVAL_MS = 3 * 24 * 60 * 60 * 1000;
+/**
+ * Checking for updates has failed for hours on this machine
+ * (`updateCheckFailing` on /api/plan and /api/diff, never beside
+ * `updateAvailable`): the Options menu says so quietly, with the command that
+ * updates without the check. No toast, no dot.
+ */
+export interface UpdateCheckFailingAdvert {
+  since: string;
+  error: string;
+  command: string;
+}
+
+/** The server's failing record, validated (anything malformed is none). */
+export function parseUpdateCheckFailing(value: unknown): UpdateCheckFailingAdvert | null {
+  if (!value || typeof value !== 'object') return null;
+  const v = value as Record<string, unknown>;
+  if (typeof v.since !== 'string' || Number.isNaN(Date.parse(v.since))) return null;
+  if (typeof v.error !== 'string' || v.error.length > 200) return null;
+  if (typeof v.command !== 'string' || !v.command || v.command.length > 500) return null;
+  return { since: v.since, error: v.error, command: v.command };
+}
+
+/** The toast shows at most this often, across versions (owner's choice: once a day). */
+export const UPDATE_TOAST_INTERVAL_MS = 24 * 60 * 60 * 1000;
 
 const TOAST_KEY = 'plannotator-update-toast';
 const VERSION = /^\d{1,9}\.\d{1,9}\.\d{1,9}$/;
@@ -82,7 +104,7 @@ export function describeUpdateToast(advert: UpdateAdvert): { title: string; desc
     case 'script':
       return {
         title: `Plannotator ${advert.version} is available`,
-        description: `You have ${advert.current}. Update from the Inbox, or turn on automatic updates in Settings.`,
+        description: `You have ${advert.current}. Update installs it in the background; this review keeps working.`,
         primary: 'update',
       };
     case 'copy':
@@ -94,13 +116,13 @@ export function describeUpdateToast(advert: UpdateAdvert): { title: string; desc
     case 'pi':
       return {
         title: `Plannotator for Pi ${advert.version} is available`,
-        description: `Run ${advert.command}, then restart Pi.`,
+        description: `Run ${advert.command}, then type /reload in Pi.`,
         primary: 'copy',
       };
     case 'opencode':
       return {
         title: `Plannotator ${advert.version} is available`,
-        description: "Run the install script again, then restart OpenCode. It also clears OpenCode's cached plugin.",
+        description: "Run the install script again, then run opencode2 reload (OpenCode 1: restart it). It also clears OpenCode's cached plugin.",
         primary: 'copy',
       };
   }

package/utils/vscodePanel.ts

@@ -0,0 +1,9 @@
+/**
+ * True inside the VS Code extension's panel (its theme bridge sets
+ * `window.__PLANNOTATOR_VSCODE`). There the panel forwards keys to VS Code, so
+ * a page key that shadows a VS Code window key (⌘P is Quick Open there, not
+ * Print) should step aside.
+ */
+export function isVSCodePanel(): boolean {
+  return typeof window !== 'undefined' && (window as { __PLANNOTATOR_VSCODE?: unknown }).__PLANNOTATOR_VSCODE === true;
+}