@plannotator/ui 0.52.0 → 0.53.0

package/utils/planDiffEngine.ts

@@ -43,6 +43,17 @@ export interface PlanDiffBlock {
   inlineTokens?: InlineDiffToken[];
   /** Structural wrap metadata paired with inlineTokens. */
   inlineWrap?: InlineDiffWrap;
+  /**
+   * Source line range of this block in the OLD text: 1-based, inclusive,
+   * trimmed of leading and trailing blank lines. Absent when the block has
+   * no non-blank old line (added blocks, or an all-blank chunk). Filled by
+   * `computePlanDiff`; plan review ignores it.
+   */
+  oldStart?: number;
+  oldEnd?: number;
+  /** Same as `oldStart`/`oldEnd`, in the NEW text (absent on removed blocks). */
+  newStart?: number;
+  newEnd?: number;
 }
 
 export interface PlanDiffStats {
@@ -63,6 +74,35 @@ function countLines(text: string): number {
   return lines.length;
 }
 
+/**
+ * The trimmed line range a chunk occupies when its first line is `start`
+ * (1-based): leading and trailing blank lines are not counted. Empty when the
+ * chunk has no non-blank line.
+ */
+function trimmedLineRange(
+  value: string,
+  start: number
+): { start?: number; end?: number } {
+  const lines = value.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  let first = 0;
+  while (first < lines.length && lines[first].trim() === "") first++;
+  if (first >= lines.length) return {};
+  let last = lines.length - 1;
+  while (last > first && lines[last].trim() === "") last--;
+  return { start: start + first, end: start + last };
+}
+
+function oldRange(value: string, start: number): Pick<PlanDiffBlock, "oldStart" | "oldEnd"> {
+  const r = trimmedLineRange(value, start);
+  return r.start === undefined ? {} : { oldStart: r.start, oldEnd: r.end };
+}
+
+function newRange(value: string, start: number): Pick<PlanDiffBlock, "newStart" | "newEnd"> {
+  const r = trimmedLineRange(value, start);
+  return r.start === undefined ? {} : { newStart: r.start, newEnd: r.end };
+}
+
 const INLINE_DIFFABLE_TYPES = new Set<Block["type"]>([
   "paragraph",
   "heading",
@@ -213,6 +253,34 @@ function substituteFencedBlocks(
   });
 }
 
+// A quote (a run of `>` lines) that holds a code fence is one block in the
+// rendered plan, and each diff chunk renders as its own quote. Diffed line
+// by line, an edit inside the quoted fence split it into chunks holding half
+// a fence each, so one chunk opened a fence it never closed and rendered the
+// prose after it as code. The whole run is therefore one atomic unit, like
+// an unquoted fence. Quotes without a fence keep line-level diffing. Runs
+// after substituteFencedBlocks, so a `>` line inside an unquoted fence is
+// already behind its sentinel and never starts a run.
+const QUOTE_RUN_PATTERN = /^[ \t]*>[^\n]*(?:\n[ \t]*>[^\n]*)*/gm;
+const QUOTED_FENCE_LINE = /^[ \t]*(?:>[ \t]?)+[ \t]*`{3,}/m;
+
+function substituteQuotedFenceRuns(
+  text: string,
+  fenceMap: Map<string, string>,
+  fenceToId: Map<string, number>
+): string {
+  return text.replace(QUOTE_RUN_PATTERN, (match) => {
+    if (!QUOTED_FENCE_LINE.test(match)) return match;
+    let id = fenceToId.get(match);
+    if (id === undefined) {
+      id = fenceToId.size;
+      fenceMap.set(fenceSentinelFor(id), match);
+      fenceToId.set(match, id);
+    }
+    return fenceSentinelFor(id);
+  });
+}
+
 function restoreFencedBlocks(
   value: string,
   fenceMap: Map<string, string>
@@ -530,8 +598,16 @@ export function computePlanDiff(
   // FENCE_BLOCK_PATTERN for the failure this prevents.
   const fenceMap = new Map<string, string>();
   const fenceToId = new Map<string, number>();
-  const substOld = substituteFencedBlocks(oldText, fenceMap, fenceToId);
-  const substNew = substituteFencedBlocks(newText, fenceMap, fenceToId);
+  const substOld = substituteQuotedFenceRuns(
+    substituteFencedBlocks(oldText, fenceMap, fenceToId),
+    fenceMap,
+    fenceToId,
+  );
+  const substNew = substituteQuotedFenceRuns(
+    substituteFencedBlocks(newText, fenceMap, fenceToId),
+    fenceMap,
+    fenceToId,
+  );
 
   const rawChanges: Change[] = diffLines(substOld, substNew);
   // Restore the fenced-block content on each change value before the
@@ -544,6 +620,10 @@ export function computePlanDiff(
 
   const blocks: PlanDiffBlock[] = [];
   const stats: PlanDiffStats = { additions: 0, deletions: 0, modifications: 0 };
+  // First line (1-based) of the next chunk on each side; the restored chunk
+  // values hold the real source lines, so counting them keeps both in step.
+  let oldLine = 1;
+  let newLine = 1;
 
   for (let i = 0; i < changes.length; i++) {
     const change = changes[i];
@@ -558,7 +638,11 @@ export function computePlanDiff(
         oldContent: change.value,
         lines: countLines(next.value),
         ...(inline ? { inlineTokens: inline.tokens, inlineWrap: inline.wrap } : {}),
+        ...oldRange(change.value, oldLine),
+        ...newRange(next.value, newLine),
       });
+      oldLine += countLines(change.value);
+      newLine += countLines(next.value);
       stats.modifications++;
       stats.additions += countLines(next.value);
       stats.deletions += countLines(change.value);
@@ -568,23 +652,209 @@ export function computePlanDiff(
         type: "added",
         content: change.value,
         lines: countLines(change.value),
+        ...newRange(change.value, newLine),
       });
+      newLine += countLines(change.value);
       stats.additions += countLines(change.value);
     } else if (change.removed) {
       blocks.push({
         type: "removed",
         content: change.value,
         lines: countLines(change.value),
+        ...oldRange(change.value, oldLine),
       });
+      oldLine += countLines(change.value);
       stats.deletions += countLines(change.value);
     } else {
       blocks.push({
         type: "unchanged",
         content: change.value,
         lines: countLines(change.value),
+        ...oldRange(change.value, oldLine),
+        ...newRange(change.value, newLine),
       });
+      oldLine += countLines(change.value);
+      newLine += countLines(change.value);
     }
   }
 
   return { blocks, stats };
 }
+
+// --- Folding unchanged runs (code review's rendered Markdown diff) ---------
+
+/** A run of unchanged sections hidden behind one row. */
+export interface PlanDiffFold {
+  kind: "fold";
+  /** Stable for the same diff: `fold-<block index>-<first hidden piece>`. */
+  key: string;
+  /** The hidden sections, each an 'unchanged' block with its own ranges. */
+  pieces: PlanDiffBlock[];
+  /** How many sections are hidden (`pieces.length`). */
+  sectionCount: number;
+  /** Plain text of the hidden headings, at most three. */
+  headings: string[];
+  oldStart?: number;
+  oldEnd?: number;
+  newStart?: number;
+  newEnd?: number;
+}
+
+export type PlanDiffSegment =
+  | { kind: "block"; block: PlanDiffBlock; index: number }
+  | PlanDiffFold;
+
+const MAX_FOLD_HEADINGS = 3;
+
+/** Heading text without inline markdown markers. */
+function plainHeadingText(text: string): string {
+  return text
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/[*_`~]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+interface UnchangedPiece {
+  piece: PlanDiffBlock;
+  heading?: string;
+}
+
+/**
+ * Split an unchanged chunk into one piece per markdown block: each piece is
+ * the exact source text from its block's first line up to the next block's
+ * (blank lines stay with the piece before them; anything before the first
+ * block, such as frontmatter, stays with the first piece). Concatenating the
+ * pieces gives the chunk back byte for byte.
+ */
+function splitUnchangedChunk(block: PlanDiffBlock): UnchangedPiece[] {
+  const content = block.content;
+  const parsed = parseMarkdownToBlocks(content);
+  if (parsed.length <= 1) {
+    const only = parsed[0];
+    return [only?.type === "heading" ? { piece: block, heading: plainHeadingText(only.content) } : { piece: block }];
+  }
+
+  // Character offset of the start of each 1-based line.
+  const lineOffsets: number[] = [0];
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === "\n") lineOffsets.push(i + 1);
+  }
+  const lineCount = countLines(content);
+  const starts = Array.from(
+    new Set(parsed.map((b) => b.startLine).filter((line) => line >= 1 && line <= lineCount))
+  ).sort((a, b) => a - b);
+  if (starts.length === 0) return [{ piece: block }];
+  starts[0] = 1;
+
+  // The chunk's untrimmed first line on each side (its ranges are trimmed).
+  const contentLines = content.split("\n");
+  let leadingBlank = 0;
+  while (leadingBlank < contentLines.length && contentLines[leadingBlank].trim() === "") leadingBlank++;
+  const oldBase = block.oldStart !== undefined ? block.oldStart - leadingBlank : undefined;
+  const newBase = block.newStart !== undefined ? block.newStart - leadingBlank : undefined;
+
+  const headingByStart = new Map<number, string>();
+  for (const b of parsed) {
+    if (b.type === "heading" && !headingByStart.has(b.startLine)) {
+      headingByStart.set(b.startLine, plainHeadingText(b.content));
+    }
+  }
+
+  return starts.map((startLine, i) => {
+    const nextStart = starts[i + 1];
+    const from = lineOffsets[startLine - 1] ?? content.length;
+    const to = nextStart !== undefined ? lineOffsets[nextStart - 1] ?? content.length : content.length;
+    const pieceContent = content.slice(from, to);
+    const piece: PlanDiffBlock = {
+      type: "unchanged",
+      content: pieceContent,
+      lines: countLines(pieceContent),
+      ...(oldBase !== undefined ? oldRange(pieceContent, oldBase + startLine - 1) : {}),
+      ...(newBase !== undefined ? newRange(pieceContent, newBase + startLine - 1) : {}),
+    };
+    // A heading piece begins at the heading itself (i > 0), or the first
+    // piece's parsed block is the heading.
+    const heading = headingByStart.get(i === 0 ? parsed[0].startLine : startLine);
+    return heading !== undefined ? { piece, heading } : { piece };
+  });
+}
+
+/** The span of several pieces' ranges on each side. */
+function spanOf(pieces: PlanDiffBlock[]): Pick<PlanDiffBlock, "oldStart" | "oldEnd" | "newStart" | "newEnd"> {
+  const withOld = pieces.filter((p) => p.oldStart !== undefined);
+  const withNew = pieces.filter((p) => p.newStart !== undefined);
+  return {
+    ...(withOld.length > 0
+      ? { oldStart: withOld[0].oldStart, oldEnd: withOld[withOld.length - 1].oldEnd }
+      : {}),
+    ...(withNew.length > 0
+      ? { newStart: withNew[0].newStart, newEnd: withNew[withNew.length - 1].newEnd }
+      : {}),
+  };
+}
+
+/** Consecutive pieces as one unchanged block (kept together so list numbering stays continuous). */
+function joinPieces(pieces: PlanDiffBlock[]): PlanDiffBlock {
+  if (pieces.length === 1) return pieces[0];
+  const content = pieces.map((p) => p.content).join("");
+  return { type: "unchanged", content, lines: countLines(content), ...spanOf(pieces) };
+}
+
+/**
+ * Fold long runs of unchanged sections behind one row, the way a code diff
+ * folds unmodified lines. Changed blocks pass through. Each unchanged block
+ * keeps `context` sections next to each neighbouring change visible (none
+ * toward the start or end of the document) and folds the rest when at least
+ * `minHidden` would be hidden; otherwise it is shown whole, untouched.
+ *
+ * Pure: the same blocks always give the same segments and fold keys.
+ */
+export function foldUnchangedPlanDiff(
+  blocks: PlanDiffBlock[],
+  options: { context?: number; minHidden?: number } = {}
+): PlanDiffSegment[] {
+  const context = Math.max(0, options.context ?? 1);
+  const minHidden = Math.max(1, options.minHidden ?? 2);
+  const segments: PlanDiffSegment[] = [];
+
+  blocks.forEach((block, index) => {
+    if (block.type !== "unchanged") {
+      segments.push({ kind: "block", block, index });
+      return;
+    }
+    const pieces = splitUnchangedChunk(block);
+    const head = index > 0 ? Math.min(context, pieces.length) : 0;
+    const tail = index < blocks.length - 1 ? Math.min(context, pieces.length - head) : 0;
+    const hidden = pieces.length - head - tail;
+    if (hidden < minHidden) {
+      segments.push({ kind: "block", block, index });
+      return;
+    }
+    if (head > 0) {
+      segments.push({ kind: "block", block: joinPieces(pieces.slice(0, head).map((p) => p.piece)), index });
+    }
+    const folded = pieces.slice(head, head + hidden);
+    const foldPieces = folded.map((p) => p.piece);
+    segments.push({
+      kind: "fold",
+      key: `fold-${index}-${head}`,
+      pieces: foldPieces,
+      sectionCount: foldPieces.length,
+      headings: folded
+        .map((p) => p.heading)
+        .filter((h): h is string => !!h)
+        .slice(0, MAX_FOLD_HEADINGS),
+      ...spanOf(foldPieces),
+    });
+    if (tail > 0) {
+      segments.push({
+        kind: "block",
+        block: joinPieces(pieces.slice(head + hidden).map((p) => p.piece)),
+        index,
+      });
+    }
+  });
+
+  return segments;
+}

package/utils/skillCatalog.ts

@@ -81,6 +81,18 @@ async function requestCatalog(): Promise<SkillCatalogEntry[]> {
   }
 }
 
+// Whether a fetched catalog is registered for the per-comment feedback export
+// (skillReferenceExportBlock). Default on: Plannotator's exporters list each
+// comment's references. A host that composes ONE block per message itself
+// (the Plannotator Inbox) turns it off, so a comment's `$name` stays plain
+// text in its export instead of carrying a second "Skills referenced" list.
+let exportRegistration = true;
+
+export function setSkillCatalogExportRegistration(on: boolean): void {
+  exportRegistration = on;
+  if (!on) setSkillCatalogForExport([]);
+}
+
 let cached: { at: number; skills: SkillCatalogEntry[] } | null = null;
 let inflight: Promise<SkillCatalogEntry[]> | null = null;
 // Bumped by resetSkillCatalogCache. A request that resolves after a reset (or
@@ -111,7 +123,7 @@ export function fetchSkillCatalog(): Promise<SkillCatalogEntry[]> {
     } else {
       cached = { at: Date.now(), skills: cached.skills };
     }
-    setSkillCatalogForExport(cached.skills);
+    if (exportRegistration) setSkillCatalogForExport(cached.skills);
     return cached.skills;
   });
   inflight = promise;
@@ -176,7 +188,8 @@ export function resetSkillContentTransport(): void {
   contentTransport = defaultContentTransport;
 }
 
-function normalizeSkillContent(raw: unknown): SkillExportContent | null {
+/** A raw `{ content, truncated, dir, path }` record as an export content, or null when any part is missing. */
+export function normalizeSkillContent(raw: unknown): SkillExportContent | null {
   if (!raw || typeof raw !== 'object') return null;
   const { content, truncated, dir, path } = raw as Record<string, unknown>;
   if (typeof content !== 'string' || !content) return null;

package/utils/skillReferences.ts

@@ -14,6 +14,13 @@
  * pre-feature behavior byte-for-byte.
  */
 
+import {
+  REVIEWER_SKILL_AUDIENCE,
+  skillInstructionsIncludedNote,
+  skillsReferencedHeading,
+  type SkillBlockAudience,
+} from '@plannotator/core/skill-reference-block';
+
 export type SkillRootId = 'claude' | 'codex' | 'universal';
 
 export interface SkillCatalogEntry {
@@ -331,8 +338,8 @@ export function resetSkillContentsForExport(): void {
   exportContents.clear();
 }
 
-const HUMAN_ONLY_EXPORT_NOTE =
-  'human-invocation-only: you cannot invoke this skill; the reviewer included it as context';
+const humanOnlyExportNote = (audience: SkillBlockAudience): string =>
+  `human-invocation-only: you cannot invoke this skill; the ${audience.requester} included it as context`;
 
 /**
  * The structural forms the injection block itself uses: the BEGIN/END markers
@@ -392,9 +399,9 @@ export function neutralizeSkillMarkerLines(body: string): string {
  *  and labeled so it can never read as the reviewer's own words. Body lines
  *  that imitate the markers are neutralized (see neutralizeSkillMarkerLines)
  *  so the body cannot close the block early or forge a sibling block. */
-function injectedSkillSection(name: string, body: SkillExportContent): string {
+function injectedSkillSection(name: string, body: SkillExportContent, audience: SkillBlockAudience): string {
   let out = `--- BEGIN SKILL INSTRUCTIONS: ${name} ---\n`;
-  out += `This skill cannot be invoked by a model, so its instructions are included here at the reviewer's request. Follow them when acting on this feedback.\n`;
+  out += `This skill cannot be invoked by a model, so its instructions are included here at the ${audience.requester}'s request. Follow them when acting on this ${audience.subject}.\n`;
   out += `Skill directory: ${body.dir}\n`;
   out += `Resolve any relative paths in the instructions below (e.g. references/, scripts/, assets/) against that absolute directory; your working directory is not the skill directory.\n\n`;
   out += `${neutralizeSkillMarkerLines(body.content)}\n`;
@@ -438,38 +445,68 @@ export function skillReferenceExportBlock(
 ): string {
   if (!text) return '';
   const refs = extractSkillReferences(text, exportCatalog);
-  if (refs.length === 0) return '';
+  return renderSkillReferencesBlock(refs, {
+    contentOf: (name) => exportContents.get(name),
+    injectedNames,
+    external: options?.external,
+  });
+}
+
+/** What `renderSkillReferencesBlock` needs besides the references themselves. */
+export interface SkillReferencesBlockOptions {
+  /** The SKILL.md body of a human-only skill, when it is to be injected; undefined falls back to the name + directory line. */
+  contentOf?: (name: string) => SkillExportContent | undefined;
+  /** Per-export dedupe (see skillReferenceExportBlock). */
+  injectedNames?: Set<string>;
+  /** A comment that did not come from the person in this UI: never injects (see skillReferenceExportBlock). */
+  external?: boolean;
+  /** Who is asking, about what. Default: the reviewer, about this feedback (Plannotator's export). */
+  audience?: SkillBlockAudience;
+}
 
-  const external = options?.external === true;
+/**
+ * The block itself, for references a caller already resolved: the export
+ * above per comment, and a host that composes ONE block per message (the
+ * Plannotator Inbox, with `INBOX_REPLY_SKILL_AUDIENCE`). '' when `refs` is
+ * empty. Same rules and markers as skillReferenceExportBlock.
+ */
+export function renderSkillReferencesBlock(
+  refs: readonly SkillCatalogEntry[],
+  options: SkillReferencesBlockOptions = {},
+): string {
+  if (refs.length === 0) return '';
+  const { injectedNames } = options;
+  const audience = options.audience ?? REVIEWER_SKILL_AUDIENCE;
+  const external = options.external === true;
   const toInject: Array<{ name: string; body: SkillExportContent }> = [];
-  let out = `**Skills referenced** (the reviewer is asking you to invoke these skills when acting on this feedback):\n`;
+  let out = `${skillsReferencedHeading(audience)}\n`;
   for (const ref of refs) {
     if (!ref.humanOnly) {
       out += `- \`${ref.name}\`\n`;
       continue;
     }
-    const body = exportContents.get(ref.name);
+    const body = options.contentOf?.(ref.name);
     if (body && injectedNames?.has(ref.name)) {
       // Already injected earlier in this export (necessarily by a reviewer-
       // written comment) — true regardless of who references it now.
-      out += `- \`${ref.name}\` (cannot be invoked by a model; its instructions are included earlier in this feedback)\n`;
+      out += `- \`${ref.name}\` (cannot be invoked by a model; its instructions are included earlier in this ${audience.subject})\n`;
     } else if (external) {
       // Tool-submitted comment: name + directory, never verbatim injection.
       out += ref.dir
         ? `- \`${ref.name}\` (cannot be invoked by a model; this comment came from an external tool, so its instructions are not included — SKILL.md is in ${ref.dir})\n`
-        : `- \`${ref.name}\` (${HUMAN_ONLY_EXPORT_NOTE})\n`;
+        : `- \`${ref.name}\` (${humanOnlyExportNote(audience)})\n`;
     } else if (body) {
       injectedNames?.add(ref.name);
       toInject.push({ name: ref.name, body });
-      out += `- \`${ref.name}\` (cannot be invoked by a model; its instructions are included below at the reviewer's request)\n`;
+      out += `- \`${ref.name}\` (cannot be invoked by a model; ${skillInstructionsIncludedNote(audience)})\n`;
     } else if (ref.dir) {
       out += `- \`${ref.name}\` (cannot be invoked by a model; its instructions could not be included, read SKILL.md in ${ref.dir} and follow it)\n`;
     } else {
-      out += `- \`${ref.name}\` (${HUMAN_ONLY_EXPORT_NOTE})\n`;
+      out += `- \`${ref.name}\` (${humanOnlyExportNote(audience)})\n`;
     }
   }
   for (const { name, body } of toInject) {
-    out += `\n${injectedSkillSection(name, body)}`;
+    out += `\n${injectedSkillSection(name, body, audience)}`;
   }
   return out;
 }

package/utils/storage.ts

@@ -127,6 +127,11 @@ export function getLastOpenInApp(): string {
   return getItem(OPEN_IN_APP_KEY) ?? 'reveal';
 }
 
+/** The stored "Open in app" id, or null when nothing was ever picked (no 'reveal' default). */
+export function getStoredOpenInApp(): string | null {
+  return getItem(OPEN_IN_APP_KEY);
+}
+
 export function setLastOpenInApp(id: string): void {
   setItem(OPEN_IN_APP_KEY, id);
 }

package/utils/textCut.ts

@@ -0,0 +1,41 @@
+/**
+ * Is this element's text cut (its own overflow with "…", or a line clamp)?
+ * With `partSelector`, it also counts as cut when its first descendant
+ * matching it is (a name drawn in two parts, whose first part shrinks).
+ * Rounding can hide a cut of under a pixel (a chip
+ * measured a scrollWidth of 104 in a clientWidth of 103 with its ellipsis
+ * showing, and another 98 in 98 with the text 0.06 px wider than its box),
+ * so any whole pixel counts, and where layout can be read the text's own
+ * width (a Range over its contents) is compared with the box's content width.
+ */
+export function isTextCut(el: Element | null | undefined, partSelector?: string): boolean {
+  if (typeof HTMLElement === 'undefined' || !(el instanceof HTMLElement)) return false;
+  const part = partSelector ? el.querySelector<HTMLElement>(partSelector) : null;
+  if (part && overflows(part)) return true;
+  return overflows(el);
+}
+
+function overflows(el: HTMLElement): boolean {
+  if (el.scrollWidth > el.clientWidth || el.scrollHeight > el.clientHeight + 1) return true;
+  if (el.clientWidth === 0 || typeof document.createRange !== 'function') return false;
+  const range = document.createRange();
+  range.selectNodeContents(el);
+  const text = range.getBoundingClientRect?.().width ?? 0;
+  if (!(text > 0)) return false;
+  const style = getComputedStyle(el);
+  if (style.overflowX === 'visible') return false;
+  const box = el.getBoundingClientRect().width;
+  const inner = box - num(style.paddingLeft) - num(style.paddingRight) - num(style.borderLeftWidth) - num(style.borderRightWidth);
+  // Chrome draws the ellipsis for any overflow (a chip lost 0.06 px): a hundredth of a pixel counts.
+  return text > inner + 0.01;
+}
+
+function num(value: string): number {
+  const n = Number.parseFloat(value);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/** No hover on this device (a touch screen): a hover there is a first tap, so a tooltip should not open. */
+export function noHover(): boolean {
+  return typeof window !== 'undefined' && typeof window.matchMedia === 'function' && window.matchMedia('(hover: none)').matches;
+}

package/utils/updateNotice.ts

@@ -0,0 +1,120 @@
+/**
+ * Update notices in plan review, annotate and code review (design:
+ * .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
+ * 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
+ * words the toast for the host that launched the session.
+ */
+
+import { getItem, setItem } from './storage';
+import { noteServerSessionMismatch, withServerSession } from './serverSession';
+
+export type UpdateAction = 'script' | 'copy' | 'pi' | 'opencode';
+
+export interface UpdateAdvert {
+  version: string;
+  current: string;
+  releaseUrl: string;
+  action: UpdateAction;
+  /** What a person runs by hand, with the remembered install flags (`pi update --extensions` for Pi). */
+  command: string;
+  publishedAt?: string;
+}
+
+/** The toast shows at most this often, across versions. */
+export const UPDATE_TOAST_INTERVAL_MS = 3 * 24 * 60 * 60 * 1000;
+
+const TOAST_KEY = 'plannotator-update-toast';
+const VERSION = /^\d{1,9}\.\d{1,9}\.\d{1,9}$/;
+const ACTIONS: readonly UpdateAction[] = ['script', 'copy', 'pi', 'opencode'];
+
+/** The server's advert, validated (anything malformed is no advert). */
+export function parseUpdateAdvert(value: unknown): UpdateAdvert | null {
+  if (!value || typeof value !== 'object') return null;
+  const v = value as Record<string, unknown>;
+  if (typeof v.version !== 'string' || !VERSION.test(v.version)) return null;
+  if (typeof v.current !== 'string' || !VERSION.test(v.current)) return null;
+  if (typeof v.releaseUrl !== 'string' || !/^https:\/\/github\.com\//.test(v.releaseUrl)) return null;
+  if (typeof v.action !== 'string' || !ACTIONS.includes(v.action as UpdateAction)) return null;
+  if (typeof v.command !== 'string' || !v.command || v.command.length > 500) return null;
+  return {
+    version: v.version,
+    current: v.current,
+    releaseUrl: v.releaseUrl,
+    action: v.action as UpdateAction,
+    command: v.command,
+    ...(typeof v.publishedAt === 'string' && { publishedAt: v.publishedAt }),
+  };
+}
+
+function readToastRecord(): { version: string; at: number } | null {
+  const raw = getItem(TOAST_KEY);
+  if (!raw) return null;
+  const at = raw.lastIndexOf('@');
+  if (at <= 0) return null;
+  const time = Number(raw.slice(at + 1));
+  return Number.isFinite(time) ? { version: raw.slice(0, at), at: time } : null;
+}
+
+/** Whether the toast for `version` may show now (pure, for tests; `claimUpdateToast` records it). */
+export function updateToastDue(version: string, now: number, record = readToastRecord()): boolean {
+  if (!record) return true;
+  if (record.version === version) return false;
+  // A clock that moved backwards does not hold the toast back for good.
+  if (record.at > now) return true;
+  return now - record.at >= UPDATE_TOAST_INTERVAL_MS;
+}
+
+/** True the first time the toast may show for `version`; marks it shown. */
+export function claimUpdateToast(version: string, now: number): boolean {
+  if (!updateToastDue(version, now)) return false;
+  setItem(TOAST_KEY, `${version}@${now}`);
+  return true;
+}
+
+/** The toast's words and its primary action, per host. */
+export function describeUpdateToast(advert: UpdateAdvert): { title: string; description: string; primary: 'update' | 'copy' } {
+  switch (advert.action) {
+    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.`,
+        primary: 'update',
+      };
+    case 'copy':
+      return {
+        title: `Plannotator ${advert.version} is available`,
+        description: `You have ${advert.current}. This copy was not installed by the install script: run the install command to update.`,
+        primary: 'copy',
+      };
+    case 'pi':
+      return {
+        title: `Plannotator for Pi ${advert.version} is available`,
+        description: `Run ${advert.command}, then restart 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.",
+        primary: 'copy',
+      };
+  }
+}
+
+/** Ask the server to run the install script now (`script` only). */
+export async function requestUpdateNow(): Promise<{ ok: true; version: string } | { ok: false; error: string }> {
+  try {
+    const res = await fetch('/api/update', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(withServerSession({})) });
+    if (await noteServerSessionMismatch(res)) return { ok: false, error: 'This review was replaced by a newer Plannotator session. Reload the page.' };
+    const body = (await res.json().catch(() => ({}))) as { version?: string; error?: string };
+    if (res.ok && typeof body.version === 'string') return { ok: true, version: body.version };
+    return { ok: false, error: body.error ?? `The update could not start (HTTP ${res.status}).` };
+  } catch {
+    return { ok: false, error: 'The update could not start: the session is not reachable.' };
+  }
+}