@plannotator/ui 0.31.0 → 0.33.0

package/types.ts

@@ -80,6 +80,7 @@ export interface Annotation {
   }>; // math elements covered by a mixed text+formula selection
   prUrl?: string; // code-review PR mode: the PR this note belongs to, so it isn't shown/exported against another PR after an in-place switch
   pageUrl?: string; // set only by live app annotate sessions: the page (pathname + search) the annotation was made on; restore filters to the current page and export groups by page
+  inReplyTo?: string; // id of the annotation this one replies to; a reply inherits its parent's anchor, renders indented under it in the panel, and exports grouped under it. Additive: annotations without it render and export exactly as before.
   htmlAnchor?: HtmlElementAnchor; // raw-HTML pinpoint: serialized element anchor for reliable restoration
   htmlAdditionalTargets?: HtmlAnnotationTarget[]; // raw-HTML shift-click multi-select: extra elements this one comment covers (primary stays htmlAnchor/originalText)
   // web-highlighter metadata for cross-element selections

package/utils/generateIdentity.ts

@@ -1,12 +1,73 @@
 /**
- * Tater name generator — pure function, no storage dependencies.
+ * Tater name generator: pure function, no storage dependencies.
  *
  * Extracted to its own module to avoid circular imports:
  * settings.ts needs this for the default value, and identity.ts
  * needs configStore (which imports settings.ts).
+ *
+ * The full `unique-username-generator` dictionary is NOT imported here. It is
+ * registered into the slot below by `./identity-tater`, which every
+ * Plannotator entry imports eagerly, so Plannotator mints names from the
+ * full dictionary exactly as before. A host that provides its own
+ * `identityProvider` never calls the generator and, with the static import
+ * gone, no longer ships the word lists.
+ *
+ * The slot is SYNCHRONOUS on purpose: `configStore.ensureLoaded()` evaluates
+ * this default during the first settings read (a render-time read) and
+ * persists the result to the identity cookie at once, so a name that arrived
+ * later would be a visible identity change. The built-in fallback below keeps
+ * the same `{adjective}-{noun}-tater` shape from a small inline pool.
  */
 
-import { uniqueUsernameGenerator, adjectives, nouns } from 'unique-username-generator';
+export type IdentityGenerator = () => string;
+
+const FALLBACK_ADJECTIVES = [
+  'swift', 'gentle', 'brave', 'calm', 'clever', 'bright', 'quiet', 'bold',
+  'eager', 'kind', 'lucky', 'merry', 'nimble', 'proud', 'sunny', 'witty',
+] as const;
+
+const FALLBACK_NOUNS = [
+  'falcon', 'crystal', 'river', 'meadow', 'harbor', 'comet', 'maple', 'otter',
+  'summit', 'lantern', 'willow', 'ember', 'pebble', 'breeze', 'orchid', 'canyon',
+] as const;
+
+/** Pool words: exported for tests only. */
+export const FALLBACK_IDENTITY_POOL: {
+  readonly adjectives: readonly string[];
+  readonly nouns: readonly string[];
+} = {
+  adjectives: FALLBACK_ADJECTIVES,
+  nouns: FALLBACK_NOUNS,
+};
+
+function pick<T>(list: readonly T[]): T {
+  return list[Math.floor(Math.random() * list.length)]!;
+}
+
+/** Built-in generator: same shape as the dictionary one, from a 16 x 16 pool. */
+export const fallbackIdentityGenerator: IdentityGenerator = () =>
+  `${pick(FALLBACK_ADJECTIVES)}-${pick(FALLBACK_NOUNS)}-tater`;
+
+let generator: IdentityGenerator = fallbackIdentityGenerator;
+
+/**
+ * Register the generator `generateIdentity()` delegates to. Must return a
+ * string synchronously. `./identity-tater` registers the full dictionary;
+ * a host may register its own via `configurePlannotatorUI({ identityGenerator })`.
+ */
+export function setIdentityGenerator(next: IdentityGenerator): void {
+  generator = next;
+}
+
+/** The active generator. Exported so a test can assert which one is registered. */
+export function getIdentityGenerator(): IdentityGenerator {
+  return generator;
+}
+
+/** Reset to the built-in fallback pool. Mainly for tests. */
+export function resetIdentityGenerator(): void {
+  generator = fallbackIdentityGenerator;
+}
 
 /**
  * Generate a new random tater identity.
@@ -14,16 +75,5 @@ import { uniqueUsernameGenerator, adjectives, nouns } from 'unique-username-gene
  * Examples: "swift-falcon-tater", "gentle-crystal-tater"
  */
 export function generateIdentity(): string {
-  // Use a unique separator to split adjective from noun, avoiding issues
-  // with compound words that contain hyphens (e.g., "behind-the-scenes")
-  const generated = uniqueUsernameGenerator({
-    dictionaries: [adjectives, nouns],
-    separator: '|||',
-    style: 'lowerCase',
-    randomDigits: 0,
-    length: 50, // Prevent word truncation (default is too short)
-  });
-
-  const [adjective, noun] = generated.split('|||');
-  return `${adjective}-${noun}-tater`;
+  return generator();
 }

package/utils/identity-tater.ts

@@ -0,0 +1,36 @@
+/**
+ * Eager identity registration: installs the full `unique-username-generator`
+ * dictionary into the generator slot in `./generateIdentity` at module
+ * evaluation, before any settings read can mint a name.
+ *
+ * Every Plannotator entry (`packages/editor/App.tsx`, `packages/review-editor/App.tsx`)
+ * imports this module for its side effect, which keeps Plannotator's tater
+ * names byte-identical to before: same library, same config, same call. A host
+ * that wants the full dictionary without its own identity provider imports it
+ * too:
+ *
+ *   import '@plannotator/ui/utils/identity-tater';
+ *
+ * A host that provides `identityProvider` never calls the generator and should
+ * NOT import this, so the word lists stay out of its bundle.
+ */
+import { uniqueUsernameGenerator, adjectives, nouns } from 'unique-username-generator';
+import { setIdentityGenerator, type IdentityGenerator } from './generateIdentity';
+
+/** The dictionary generator Plannotator has always used. */
+export const generateTaterIdentity: IdentityGenerator = () => {
+  // Use a unique separator to split adjective from noun, avoiding issues
+  // with compound words that contain hyphens (e.g., "behind-the-scenes")
+  const generated = uniqueUsernameGenerator({
+    dictionaries: [adjectives, nouns],
+    separator: '|||',
+    style: 'lowerCase',
+    randomDigits: 0,
+    length: 50, // Prevent word truncation (default is too short)
+  });
+
+  const [adjective, noun] = generated.split('|||');
+  return `${adjective}-${noun}-tater`;
+};
+
+setIdentityGenerator(generateTaterIdentity);

package/utils/math-default-loader.ts

@@ -0,0 +1,24 @@
+/**
+ * The default math renderer loader: KaTeX's JS only, fetched lazily.
+ *
+ * This module is the ONLY place in `@plannotator/ui` that names `katex` at
+ * runtime (`./math-eager` names it too, but a host chooses to import that).
+ * `./math` calls `loadDefaultMathRenderer` only when no host loader is
+ * registered (`setMathRendererLoader` / `configurePlannotatorUI({
+ * mathRendererLoader })`), so a host that registers one never runs the
+ * `import('katex')` below and never requests the chunk it produces.
+ *
+ * Keeping the import in its own module is what lets a bundler drop the chunk
+ * entirely: chunk emission is static, so a host that registers a loader and
+ * wants no KaTeX chunk from the package at all points this module at a stub
+ * (see HANDOFF.md "Lazy renderers and eager entries", the alias recipe). The
+ * stylesheet is deliberately NOT imported here; CSS loading stays the host's
+ * job (HANDOFF.md "Math rendering"), and a host that already serves
+ * `katex.min.css` would otherwise load it twice.
+ */
+
+import type { MathRenderer } from './math';
+
+export function loadDefaultMathRenderer(): Promise<MathRenderer> {
+  return import('katex').then((m) => m.default);
+}

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,149 @@
+/**
+ * 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 `./math-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). That default is called only while no host loader is registered, and
+ * it lives in its own module so a host that registers a loader can alias it
+ * away and drop the chunk (see HANDOFF.md "Lazy renderers and eager entries").
+ */
+
+import type { KatexOptions } from 'katex';
+import { loadDefaultMathRenderer } from './math-default-loader';
+
+/** 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>;
+
+/**
+ * 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;
+/**
+ * The host loader, or `null` while none is registered. `null` is the only
+ * state in which `loadMathRenderer()` reaches `loadDefaultMathRenderer` and
+ * its `import('katex')`; a registered loader is never backfilled by the
+ * default, not even after it rejects.
+ */
+let loader: MathRendererLoader | null = null;
+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 ? loader() : loadDefaultMathRenderer()).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 = null;
+  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

@@ -1208,6 +1208,38 @@ export const exportAnnotations = (
     ];
   }
 
+  // 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) {
@@ -1268,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/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);
+}