@plannotator/ui 0.30.0 → 0.32.0

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/math-eager.ts

@@ -0,0 +1,25 @@
+/**
+ * Eager math registration: fills the renderer slot in `./math` with KaTeX at
+ * module evaluation, before any component renders.
+ *
+ * Every Plannotator entry (`packages/editor/App.tsx`, `packages/review-editor/App.tsx`;
+ * the hook, review, portal, OpenCode and Pi builds all flow from those two)
+ * imports this module for its side effect, which is what keeps math typeset
+ * on the first commit exactly as it was with a static `katex` import. A host
+ * that wants the same synchronous behavior imports it too:
+ *
+ *   import '@plannotator/ui/utils/math-eager';
+ *
+ * A host that does not import it gets lazy math: the TeX source in the same
+ * wrapper for one frame, then the typeset markup once the chunk lands.
+ *
+ * The source tag passed below doubles as a build marker: the literal only
+ * reaches a bundle when this module is evaluated in it, so a dropped or
+ * tree-shaken side-effect import is caught by the built-HTML check in
+ * tests/entry-assets.test.ts (KaTeX itself stays inlined either way through
+ * the loader's import(), so a KaTeX class name cannot prove registration).
+ */
+import katex from 'katex';
+import { setMathRenderer } from './math';
+
+setMathRenderer(katex, 'plannotator-math-eager');

package/utils/math.ts

@@ -0,0 +1,146 @@
+/**
+ * Math renderer slot.
+ *
+ * `MathBlock` and inline math read their renderer from this module instead of
+ * importing `katex` statically, so a host that bundles by route does not carry
+ * KaTeX in every document read. The slot is SYNCHRONOUS: when it is filled
+ * before the first render (which is what `./math-eager` does, and what every
+ * Plannotator entry imports) the typeset HTML is in the DOM on the first
+ * commit, exactly as it was when the import was static. When it is empty the
+ * components render the same wrapper element with the TeX source as text,
+ * call `loadMathRenderer()`, and re-render typeset once it resolves.
+ *
+ * This module deliberately has NO runtime import of `katex`: the only place
+ * the dependency is named is the default loader's `import('katex')`, which a
+ * chunking bundler turns into a lazy chunk and Plannotator's single-file
+ * builds inline (the eager entry keeps it in the entry either way).
+ */
+
+import type { KatexOptions } from 'katex';
+
+/** The subset of KaTeX's API the renderer needs. `katex` itself satisfies it. */
+export interface MathRenderer {
+  renderToString(tex: string, options?: KatexOptions): string;
+}
+
+export type MathRendererLoader = () => Promise<MathRenderer>;
+
+/**
+ * Default loader: KaTeX's JS only. The stylesheet is deliberately NOT imported
+ * here; CSS loading stays the host's job (see HANDOFF.md "Math rendering"),
+ * and a host that already serves `katex.min.css` would otherwise load it twice.
+ */
+const defaultMathRendererLoader: MathRendererLoader = () => import('katex').then((m) => m.default);
+
+/**
+ * Who filled the slot: the eager entry (`./math-eager`), the lazy loader, or a
+ * host calling `setMathRenderer` directly. Diagnostic for a host chasing a TeX
+ * flash, and the eager value is a build marker: it only reaches a bundle when
+ * `./math-eager` is evaluated, which is what `tests/entry-assets.test.ts`
+ * asserts on the built single-file HTML.
+ */
+export type MathRendererSource = 'plannotator-math-eager' | 'loader' | 'host';
+
+let renderer: MathRenderer | null = null;
+let rendererSource: MathRendererSource | null = null;
+let loader: MathRendererLoader = defaultMathRendererLoader;
+let pending: Promise<MathRenderer> | null = null;
+const listeners = new Set<() => void>();
+
+function notify(): void {
+  for (const listener of listeners) listener();
+}
+
+/** Current renderer, or `null` while none is registered. Safe to call during render. */
+export function getMathRenderer(): MathRenderer | null {
+  return renderer;
+}
+
+/** How the current renderer was registered, or `null` while the slot is empty. */
+export function getMathRendererSource(): MathRendererSource | null {
+  return rendererSource;
+}
+
+/** Register a renderer synchronously (what `./math-eager` does with `katex`). */
+export function setMathRenderer(next: MathRenderer, source: MathRendererSource = 'host'): void {
+  if (renderer === next) return;
+  renderer = next;
+  rendererSource = source;
+  notify();
+}
+
+/** Subscribe to slot changes. Shaped for `useSyncExternalStore`. */
+export function subscribeMathRenderer(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * Swap the loader `loadMathRenderer()` uses. Host seam
+ * (`configurePlannotatorUI({ mathRendererLoader })`): a host may return a
+ * module that imports katex AND its stylesheet in one chunk. A load already in
+ * flight keeps going; the new loader is used from the next `loadMathRenderer()`
+ * call that finds the slot empty.
+ */
+export function setMathRendererLoader(next: MathRendererLoader): void {
+  loader = next;
+  pending = null;
+}
+
+/**
+ * Load and register the renderer. Idempotent: a filled slot resolves at once,
+ * a load in flight is shared, and a rejected load is dropped so the next call
+ * retries instead of failing forever on a transient chunk error.
+ */
+export function loadMathRenderer(): Promise<MathRenderer> {
+  if (renderer) return Promise.resolve(renderer);
+  if (!pending) {
+    const attempt = loader().then(
+      (loaded) => {
+        setMathRenderer(loaded, 'loader');
+        return loaded;
+      },
+      (err: unknown) => {
+        if (pending === attempt) pending = null;
+        throw err;
+      },
+    );
+    pending = attempt;
+  }
+  return pending;
+}
+
+/** Test hook: clear the slot, the loader override and any pending load. */
+export function resetMathRenderer(): void {
+  renderer = null;
+  rendererSource = null;
+  loader = defaultMathRendererLoader;
+  pending = null;
+  notify();
+}
+
+export const normalizeMathTex = (tex: string): string => tex.trim();
+
+/**
+ * Render TeX with the pinned option set. `throwOnError: false` and
+ * `trust: false` are a deliberate security pin applied to EVERY renderer,
+ * including one a host registered: a registered module never widens what
+ * document-supplied TeX may do. Returns `null` while no renderer is
+ * registered so callers can fall back to the text placeholder.
+ */
+export function renderMathToHtml(
+  tex: string,
+  displayMode: boolean,
+  activeRenderer: MathRenderer | null = renderer,
+): string | null {
+  if (!activeRenderer) return null;
+  return activeRenderer.renderToString(tex, {
+    displayMode,
+    throwOnError: false,
+    strict: 'warn',
+    trust: false,
+    output: 'html',
+  });
+}

package/utils/mermaid-eager.ts

@@ -0,0 +1,28 @@
+/**
+ * Eager Mermaid registration: imports the runtime statically, initializes it
+ * at module evaluation (exactly where the old module-scope
+ * `mermaid.initialize` ran) and fills the slot in `./mermaid`.
+ *
+ * `packages/editor/App.tsx` imports this module for its side effect, by
+ * policy: Plannotator's own surfaces keep Mermaid in their entry chunk so it
+ * can never fail separately from the app (on the share portal this is what
+ * keeps `mermaid.core` out of a lazy chunk). The review editor does not import
+ * it because it never renders a Mermaid block; adding the runtime there would
+ * grow that bundle. A host that wants the same import adds:
+ *
+ *   import '@plannotator/ui/utils/mermaid-eager';
+ *
+ * A host that does not import it gets the lazy path in `./mermaid`.
+ *
+ * The source tag passed below doubles as a build marker: the literal only
+ * reaches a bundle when this module is evaluated in it, so a dropped or
+ * tree-shaken side-effect import is caught by the built-HTML check in
+ * tests/entry-assets.test.ts (the runtime itself stays inlined in a
+ * single-file build through the loader's import(), so a Mermaid diagram id
+ * cannot prove registration).
+ */
+import mermaid from 'mermaid';
+import { MERMAID_CONFIG, setMermaidRuntime } from './mermaid';
+
+mermaid.initialize(MERMAID_CONFIG);
+setMermaidRuntime(mermaid, 'plannotator-mermaid-eager');

package/utils/mermaid.ts

@@ -0,0 +1,132 @@
+/**
+ * Mermaid runtime slot.
+ *
+ * ONE code path feeds `MermaidBlock`: `loadMermaidRuntime()`. It resolves at
+ * once from a filled slot and otherwise imports the runtime lazily. Plannotator
+ * fills the slot at module evaluation through `./mermaid-eager` (imported by
+ * `packages/editor/App.tsx`), which keeps the runtime in its entry chunk on the
+ * share portal exactly as it was with the static import, so it cannot fail
+ * separately from the app. A host that does not import the eager entry gets
+ * the lazy path: the runtime is fetched on the first diagram, a failed import
+ * is dropped from the memo so the next call issues a fresh `import()`, and
+ * the block re-attempts once and offers Retry.
+ *
+ * This module has NO static import of `mermaid`; the only place the
+ * dependency is named at runtime is the default loader's `import('mermaid')`.
+ */
+import type { Mermaid, MermaidConfig } from 'mermaid';
+
+/**
+ * Hoisted verbatim from the former module-scope `mermaid.initialize(...)` in
+ * MermaidBlock. Nothing in it reads a CSS token or the resolved mode.
+ * `securityLevel: 'strict'` is a deliberate security pin (see MermaidBlock.test.ts).
+ */
+export const MERMAID_CONFIG: MermaidConfig = {
+  startOnLoad: false,
+  securityLevel: 'strict',
+  theme: 'dark',
+  themeVariables: {
+    primaryColor: '#3b82f6',
+    primaryTextColor: '#f8fafc',
+    primaryBorderColor: '#475569',
+    lineColor: '#64748b',
+    secondaryColor: '#1e293b',
+    tertiaryColor: '#0f172a',
+    background: '#1e293b',
+    mainBkg: '#1e293b',
+    nodeBorder: '#475569',
+    clusterBkg: '#1e293b',
+    clusterBorder: '#475569',
+    titleColor: '#f8fafc',
+    edgeLabelBackground: '#1e293b',
+  },
+  flowchart: {
+    htmlLabels: true,
+    curve: 'basis',
+  },
+};
+
+/**
+ * Who filled the slot. The eager value doubles as a build marker: the literal
+ * only reaches a bundle when `./mermaid-eager` is evaluated in it, which is
+ * what `tests/entry-assets.test.ts` asserts on the built HTML.
+ */
+export type MermaidRuntimeSource = 'plannotator-mermaid-eager' | 'loader' | 'host';
+
+export type MermaidRuntimeLoader = () => Promise<Mermaid>;
+
+/** Default lazy loader: import the runtime and initialize it once. */
+const defaultMermaidLoader: MermaidRuntimeLoader = () =>
+  import('mermaid').then(({ default: mermaid }) => {
+    mermaid.initialize(MERMAID_CONFIG);
+    return mermaid;
+  });
+
+let runtime: Mermaid | null = null;
+let runtimeSource: MermaidRuntimeSource | null = null;
+let loader: MermaidRuntimeLoader = defaultMermaidLoader;
+let pending: Promise<Mermaid> | null = null;
+
+/**
+ * Delay before the block's one automatic re-attempt after a failed lazy
+ * import. Only chunking hosts can fail here; a filled slot never loads.
+ */
+let retryDelayMs = 750;
+
+/** Current runtime, or `null` while the slot is empty. */
+export function getMermaidRuntime(): Mermaid | null {
+  return runtime;
+}
+
+/** How the current runtime was registered, or `null` while the slot is empty. */
+export function getMermaidRuntimeSource(): MermaidRuntimeSource | null {
+  return runtimeSource;
+}
+
+/** Register an already-initialized runtime (what `./mermaid-eager` does). */
+export function setMermaidRuntime(next: Mermaid, source: MermaidRuntimeSource = 'host'): void {
+  runtime = next;
+  runtimeSource = source;
+  pending = null;
+}
+
+/** The block's retry delay for the lazy path. */
+export function getMermaidRetryDelayMs(): number {
+  return retryDelayMs;
+}
+
+/**
+ * Resolve the runtime: at once from a filled slot, otherwise through the
+ * loader. A rejected load is dropped from the memo so the next call (the
+ * block's automatic re-attempt, a later mount, or the Retry button) issues a
+ * fresh `import()` instead of replaying the cached rejection.
+ */
+export function loadMermaidRuntime(): Promise<Mermaid> {
+  if (runtime) return Promise.resolve(runtime);
+  if (!pending) {
+    const attempt = loader().then(
+      (loaded) => {
+        setMermaidRuntime(loaded, 'loader');
+        return loaded;
+      },
+      (err: unknown) => {
+        if (pending === attempt) pending = null;
+        throw err;
+      },
+    );
+    pending = attempt;
+  }
+  return pending;
+}
+
+/** Test hook: empty the slot, stand in for the lazy import, shorten the retry delay. */
+export function __setMermaidRuntimeLoaderForTests(
+  next: MermaidRuntimeLoader | undefined,
+  options?: { retryDelayMs?: number },
+): void {
+  runtime = null;
+  runtimeSource = null;
+  pending = null;
+  loader = next ?? defaultMermaidLoader;
+  retryDelayMs = options?.retryDelayMs ?? 750;
+}

package/utils/parser.ts

@@ -1178,8 +1178,75 @@ 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)),
+    ];
+  }
+
+  // Threaded replies (`inReplyTo`): a reply is emitted as a nested exchange
+  // under its parent's entry rather than as its own numbered entry, so the
+  // coding agent reads the conversation in order. Replies whose parent is
+  // not in the export render as ordinary entries. With no `inReplyTo`
+  // anywhere the output is byte-identical to the ungrouped export.
+  const exportedIds = new Set(sortedAnns.map((a: any) => a.id));
+  const isReply = (a: any) => typeof a.inReplyTo === 'string' && a.inReplyTo !== a.id && exportedIds.has(a.inReplyTo);
+  const hasReplies = sortedAnns.some(isReply);
+  const repliesOf = (parent: any): any[] =>
+    hasReplies ? sortedAnns.filter((a: any) => isReply(a) && a.inReplyTo === parent.id).sort((a: any, b: any) => a.createdA - b.createdA) : [];
+  if (hasReplies) {
+    emitOrder = emitOrder.filter((a) => !isReply(a));
+    // Numbers stay consecutive over the entries that are actually emitted.
+    annotationNumbers.clear();
+    emitOrder.forEach((ann, index) => annotationNumbers.set(ann, index + 1));
+  }
+  const replyBlock = (parent: any, depth = 0): string => {
+    let block = '';
+    for (const reply of repliesOf(parent)) {
+      const who = reply.author ? `${reply.author}` : 'reply';
+      const indent = '  '.repeat(depth);
+      block += `${indent}- **Reply (${who}):** ${String(reply.text ?? '').replace(/\r?\n/g, `\n${indent}  `)}\n`;
+      if (reply.images && reply.images.length > 0) {
+        reply.images.forEach((img: ImageAttachment) => {
+          block += `${indent}  - [${img.name}] \`${img.path}\`\n`;
+        });
+      }
+      block += replyBlock(reply, depth + 1);
+    }
+    return block;
+  };
+
+  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) {
@@ -1233,6 +1300,12 @@ export const exportAnnotations = (
       });
     }
 
+    // Threaded replies nest under the entry they answer.
+    if (hasReplies) {
+      const thread = replyBlock(ann);
+      if (thread) output += `**Replies:**\n${thread}`;
+    }
+
     output += '\n';
   });
 

package/utils/quickLabels.ts

@@ -31,6 +31,19 @@ export const LABEL_COLOR_MAP: Record<string, { bg: string; text: string; darkTex
   amber:  { bg: 'rgba(180,83,9,0.15)',    text: '#b45309', darkText: '#fbbf24' },
 };
 
+/**
+ * The hardcoded one-click positive label behind the toolbar's 👍 button and
+ * the composer's "Looks good" action. Deliberately NOT part of the
+ * configurable set: it is the ONLY label comment-only surfaces (HTML /
+ * live-app) may emit — their restricted handlers filter on this id.
+ */
+export const THUMBS_UP_LABEL: QuickLabel = {
+  id: 'thumbs-up',
+  emoji: '👍',
+  text: 'Looks good',
+  color: 'green',
+};
+
 export const DEFAULT_QUICK_LABELS: QuickLabel[] = [
   { id: 'clarify-this',            emoji: '❓', text: 'Clarify this',            color: 'yellow' },
   { id: 'missing-overview',        emoji: '🗺️', text: 'Missing overview',        color: 'purple', tip: 'Provide a narrative overview of what is being built, why it is being built, and how it will be built. Add this before the implementation details.' },

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;
 }
 

package/utils/vimScroll.ts

@@ -1,3 +1,8 @@
+import {
+  getScrollViewportRect,
+  offsetScrollViewport,
+} from '../hooks/useScrollViewport';
+
 /**
  * Keep the Vim cursor clear of the HUD bands that hug the viewport edges.
  *
@@ -131,11 +136,11 @@ export function scrollVimTargetIntoView(
     return;
   }
 
-  const viewportRect = viewport.getBoundingClientRect();
+  const viewportRect = getScrollViewportRect(viewport);
   const targetRect = element.getBoundingClientRect();
   if (targetRect.height === 0 && targetRect.width === 0) return;
 
-  const margin = resolveVimScrollMargin(viewport.clientHeight);
+  const margin = resolveVimScrollMargin(viewportRect.height);
   const stickyBottom = viewport
     .querySelector<HTMLElement>('[data-sticky-actions]')
     ?.getBoundingClientRect().bottom;
@@ -153,10 +158,10 @@ export function scrollVimTargetIntoView(
     : margin;
 
   const delta = computeVimScrollDelta(
-    { top: viewportRect.top, height: viewport.clientHeight },
+    { top: viewportRect.top, height: viewportRect.height },
     { top: targetRect.top, bottom: targetRect.bottom },
     { topMargin, bottomMargin },
   );
   if (delta === 0) return;
-  viewport.scrollTop += delta;
+  offsetScrollViewport(viewport, delta);
 }

package/utils/wideMode.ts

@@ -1,4 +1,5 @@
 import type { SidebarTab } from '@plannotator/ui/hooks/useSidebar';
+import type { WideModeType } from '@plannotator/ui/types';
 export type { WideModeType } from '@plannotator/ui/types';
 
 export type WideModeLayoutSnapshot = {
@@ -26,6 +27,25 @@ export function canUseAnnotateWideMode(options: {
   return !options.archiveMode && !options.isPlanDiffActive;
 }
 
+/** What the focus-mode keyboard shortcut should do on this press. */
+export type FocusShortcutAction = 'enter-focus' | 'exit' | 'none';
+
+/**
+ * Decide the next step for the focus-mode keyboard shortcut.
+ *
+ * The shortcut is a single "hide the chrome / give it back" toggle, so ANY
+ * active panel-hiding view mode restores the remembered layout — including
+ * `wide`, which the toolbar control would instead swap for `focus`. A press
+ * that could only re-hide already-hidden panels would look like a dead key.
+ */
+export function resolveFocusShortcutAction(state: {
+  canUseWideMode: boolean;
+  wideModeType: WideModeType | null;
+}): FocusShortcutAction {
+  if (state.wideModeType !== null) return 'exit';
+  return state.canUseWideMode ? 'enter-focus' : 'none';
+}
+
 export function resolveWideModeExitLayout(
   snapshot: WideModeLayoutSnapshot | null,
   options?: WideModeExitOptions,

package/webmcp/activity.ts

@@ -0,0 +1,46 @@
+/**
+ * "An agent has acted" signal for the indicator policy: NOTHING visible may
+ * appear merely because `document.modelContext` exists. Only after the first
+ * successful tool call in a session does the header show its unobtrusive
+ * affordance, which subscribes here.
+ *
+ * Module-level and dependency-free; a browser without WebMCP never records a
+ * call, so subscribers render nothing and the store never changes.
+ */
+import { useSyncExternalStore } from 'react';
+
+export interface WebMcpActivity {
+  /** Successful tool calls in this page load. */
+  calls: number;
+  /** Prefixed name of the last successful tool call. */
+  lastTool: string | null;
+}
+
+let activity: WebMcpActivity = { calls: 0, lastTool: null };
+const listeners = new Set<() => void>();
+
+export function recordToolCall(tool: string): void {
+  activity = { calls: activity.calls + 1, lastTool: tool };
+  for (const listener of listeners) listener();
+}
+
+export function getWebMcpActivity(): WebMcpActivity {
+  return activity;
+}
+
+export function subscribeWebMcpActivity(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Mainly for tests. */
+export function resetWebMcpActivity(): void {
+  activity = { calls: 0, lastTool: null };
+  for (const listener of listeners) listener();
+}
+
+export function useWebMcpActivity(): WebMcpActivity {
+  return useSyncExternalStore(subscribeWebMcpActivity, getWebMcpActivity, getWebMcpActivity);
+}