@plannotator/ui 0.31.0 → 0.32.0

package/webmcp/changes.ts

@@ -0,0 +1,227 @@
+/**
+ * The change tracker behind "since your last read".
+ *
+ * WebMCP page tools receive no caller identity and the spec's model is one
+ * agent per tab, so the watermark is per tab, per page load, and any agent
+ * that wants its own passes `since` explicitly (every response returns
+ * `cursor`). Two agents on one tab share the implicit watermark; that is a
+ * documented limitation.
+ *
+ * Pure, no DOM, so it can move to `@plannotator/core` untouched.
+ */
+
+/** `source` stamped on every annotation a browser agent creates through the tools. */
+export const BROWSER_AGENT_SOURCE = 'browser-agent';
+
+/** The slice of an annotation the tracker hashes. */
+export interface TrackedAnnotation {
+  id: string;
+  text?: string;
+  originalText?: string;
+  source?: string;
+  inReplyTo?: string;
+  images?: ReadonlyArray<{ path: string }>;
+}
+
+export interface ChangeEntry {
+  seq: number;
+  hash: string;
+  agent: boolean;
+}
+
+export interface Tombstone {
+  id: string;
+  seq: number;
+  /** The removed annotation was agent-authored (its `source` was the agent stamp). */
+  agent: boolean;
+}
+
+export interface ObserveDelta {
+  added: string[];
+  changed: string[];
+  removed: Tombstone[];
+}
+
+export function isAgentAnnotation(annotation: { source?: string }): boolean {
+  return annotation.source === BROWSER_AGENT_SOURCE;
+}
+
+export function hashAnnotation(annotation: TrackedAnnotation): string {
+  return JSON.stringify([
+    annotation.text ?? '',
+    annotation.originalText ?? '',
+    annotation.inReplyTo ?? '',
+    annotation.images?.map((image) => image.path) ?? [],
+  ]);
+}
+
+const CURSOR_PREFIX = 'w:';
+
+export class AnnotationChangeTracker {
+  private readonly entries = new Map<string, ChangeEntry>();
+  private readonly tombstones = new Map<string, Tombstone>();
+  /** Hash the agent wrote for an id; the seq assigned to that exact state is never "new" to the agent. */
+  private readonly ownHashes = new Map<string, string>();
+  private readonly ownSeqs = new Map<string, number>();
+  /** Ids the agent removed itself; their tombstones are never reported back to it. */
+  private readonly agentRemoved = new Set<string>();
+  private counter = 0;
+  private mark = 0;
+  /** Wall-clock time of the last seq change (null until anything changes). */
+  lastActivity: number | null = null;
+
+  constructor(private readonly now: () => number = () => Date.now()) {}
+
+  /** Highest seq handed out so far. */
+  get seq(): number {
+    return this.counter;
+  }
+
+  /** The implicit per-tab watermark. */
+  get watermark(): number {
+    return this.mark;
+  }
+
+  cursor(): string {
+    return `${CURSOR_PREFIX}${this.counter}`;
+  }
+
+  /** Accepts a `cursor` string (`w:47`) or a bare number; anything else is null. */
+  static parseSince(value: unknown): number | null {
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0) return Math.floor(value);
+    if (typeof value === 'string') {
+      const digits = value.startsWith(CURSOR_PREFIX) ? value.slice(CURSOR_PREFIX.length) : value;
+      if (/^\d+$/.test(digits)) return Number(digits);
+    }
+    return null;
+  }
+
+  /** Advance the implicit watermark (default: to the current seq). */
+  advance(to: number = this.counter): void {
+    this.mark = Math.max(this.mark, Math.min(to, this.counter));
+  }
+
+  /**
+   * Claim an annotation state as the agent's own: when the tracker next sees
+   * this id with this exact hash, that seq is remembered so `newSince` skips
+   * it. A later human edit produces a different hash, a new seq, and IS new.
+   */
+  claimOwn(annotation: TrackedAnnotation): void {
+    this.ownHashes.set(annotation.id, hashAnnotation(annotation));
+    const entry = this.entries.get(annotation.id);
+    if (entry && entry.hash === this.ownHashes.get(annotation.id)) this.ownSeqs.set(annotation.id, entry.seq);
+  }
+
+  /**
+   * Record that the agent removed `id` itself, so the resulting tombstone
+   * is not attributed to the human (`removedSince` skips it).
+   */
+  claimRemoved(id: string): void {
+    this.agentRemoved.add(id);
+  }
+
+  /** One O(n) pass over the current list; assigns seqs and tombstones. */
+  observe(list: ReadonlyArray<TrackedAnnotation>): ObserveDelta {
+    const delta: ObserveDelta = { added: [], changed: [], removed: [] };
+    const seen = new Set<string>();
+    let touched = false;
+    for (const annotation of list) {
+      seen.add(annotation.id);
+      const hash = hashAnnotation(annotation);
+      const agent = isAgentAnnotation(annotation);
+      const existing = this.entries.get(annotation.id);
+      if (existing && existing.hash === hash) {
+        existing.agent = agent;
+        continue;
+      }
+      const seq = ++this.counter;
+      touched = true;
+      this.entries.set(annotation.id, { seq, hash, agent });
+      this.tombstones.delete(annotation.id);
+      if (existing) delta.changed.push(annotation.id);
+      else delta.added.push(annotation.id);
+      if (this.ownHashes.get(annotation.id) === hash) this.ownSeqs.set(annotation.id, seq);
+    }
+    for (const [id, entry] of this.entries) {
+      if (seen.has(id)) continue;
+      this.entries.delete(id);
+      const seq = ++this.counter;
+      touched = true;
+      const tombstone: Tombstone = { id, seq, agent: entry.agent || this.ownHashes.has(id) };
+      this.tombstones.set(id, tombstone);
+      delta.removed.push(tombstone);
+    }
+    // A re-added id is a fresh record: forget any agent-removal claim on it.
+    for (const id of seen) this.agentRemoved.delete(id);
+    if (touched) this.lastActivity = this.now();
+    return delta;
+  }
+
+  seqOf(id: string): number | undefined {
+    return this.entries.get(id)?.seq;
+  }
+
+  /** Whether `id` changed after `since` in a way the agent did not author. */
+  isNew(id: string, since: number = this.mark): boolean {
+    const entry = this.entries.get(id);
+    if (!entry || entry.seq <= since) return false;
+    return this.ownSeqs.get(id) !== entry.seq;
+  }
+
+  /** Ids added or edited after `since`, excluding states the agent wrote. */
+  newSince(since: number = this.mark): string[] {
+    const ids: string[] = [];
+    for (const [id] of this.entries) if (this.isNew(id, since)) ids.push(id);
+    return ids;
+  }
+
+  /** Tombstones written after `since`, excluding removals the agent made itself. */
+  removedSince(since: number = this.mark): Tombstone[] {
+    const removed: Tombstone[] = [];
+    for (const tombstone of this.tombstones.values()) {
+      if (tombstone.seq > since && !this.agentRemoved.has(tombstone.id)) removed.push(tombstone);
+    }
+    return removed;
+  }
+
+  /**
+   * Whether the agent claimed `id` in this page load. This is the ownership
+   * key for update/remove: a `source` stamp alone can be forged through the
+   * external-annotations API, a claim cannot.
+   */
+  isOwn(id: string): boolean {
+    return this.ownHashes.has(id);
+  }
+
+  /** Whether the tracker has ever seen `id` (live or removed). */
+  knows(id: string): boolean {
+    return this.entries.has(id) || this.tombstones.has(id);
+  }
+}
+
+/**
+ * Per-path trackers for folder and linked-doc sessions, each with its own
+ * read watermark so `newSinceLastRead` is per document.
+ */
+export class ChangeTrackerSet {
+  private readonly trackers = new Map<string, AnnotationChangeTracker>();
+
+  constructor(private readonly now: () => number = () => Date.now()) {}
+
+  forPath(path: string): AnnotationChangeTracker {
+    let tracker = this.trackers.get(path);
+    if (!tracker) {
+      tracker = new AnnotationChangeTracker(this.now);
+      this.trackers.set(path, tracker);
+    }
+    return tracker;
+  }
+
+  has(path: string): boolean {
+    return this.trackers.has(path);
+  }
+
+  paths(): string[] {
+    return [...this.trackers.keys()];
+  }
+}

package/webmcp/index.ts

@@ -0,0 +1,72 @@
+export {
+  MODEL_CONTEXT_PROPERTY,
+  TOOL_CHANGE_EVENT,
+  TOOL_NAME_PATTERN,
+  resolveModelContext,
+  type ModelContextLike,
+  type ModelContextToolAnnotations,
+  type ModelContextToolDescriptor,
+  type ModelContextRegisteredTool,
+  type ModelContextExecuteContext,
+} from './modelContext';
+export {
+  DEFAULT_WEBMCP_NAME_PREFIX,
+  getWebMcpPolicy,
+  resetWebMcpPolicy,
+  setWebMcpPolicy,
+  type WebMcpPolicy,
+  type ResolvedWebMcpPolicy,
+} from './policy';
+export { validateAgainstSchema, type JsonSchema } from './schema';
+export {
+  TOOL_DESCRIPTION_MAX_CHARS,
+  TOOL_PARAM_DESCRIPTION_MAX_CHARS,
+  createToolRegistry,
+  defineTool,
+  fail,
+  getRegistryFor,
+  ok,
+  runTool,
+  type Nudge,
+  type NudgeCode,
+  type ToolError,
+  type ToolErrorCode,
+  type ToolRegistry,
+  type ToolResponse,
+  type ToolResult,
+  type ToolSpec,
+  type ToolsetHooks,
+} from './toolset';
+export {
+  AnnotationChangeTracker,
+  BROWSER_AGENT_SOURCE,
+  ChangeTrackerSet,
+  hashAnnotation,
+  isAgentAnnotation,
+  type ObserveDelta,
+  type Tombstone,
+  type TrackedAnnotation,
+} from './changes';
+export {
+  MAX_OTHER_DOCUMENT_NUDGES,
+  buildNudges,
+  type DocumentSurface,
+  type NudgeSnapshot,
+  type OtherDocumentActivity,
+} from './nudges';
+export {
+  getWebMcpActivity,
+  recordToolCall,
+  resetWebMcpActivity,
+  subscribeWebMcpActivity,
+  useWebMcpActivity,
+  type WebMcpActivity,
+} from './activity';
+export { useToolset, type UseToolsetOptions, type UseToolsetResult } from './useToolset';
+export {
+  WEBMCP_TOOLS_COOKIE,
+  getWebMcpToolsEnabled,
+  setWebMcpToolsEnabled,
+  subscribeWebMcpToolsEnabled,
+  useWebMcpToolsEnabled,
+} from './preference';

package/webmcp/modelContext.ts

@@ -0,0 +1,103 @@
+/**
+ * The ONLY file in the repo that spells the WebMCP surface.
+ *
+ * Everything here mirrors the W3C WebML CG draft of WebMCP as of 2026-08-25
+ * (spec `index.bs`, entry point `document.modelContext`; the same shape
+ * `webmcp-types@0.1.5` publishes). The types are deliberately local and
+ * structural: no `declare global`, no dependency. `packages/ui/globals.d.ts`
+ * is a published ambient file and must not augment `Document` for every
+ * consumer, and the entry point has been renamed three times in a year, so a
+ * rename is a one-file change plus its test.
+ *
+ * Spec facts the engine relies on:
+ *   - `registerTool(tool, { signal })` returns a promise; unregistration is
+ *     ONLY via aborting the signal (the abort steps unregister synchronously).
+ *   - `execute(input, { signal })` runs in our realm; its return value is
+ *     JSON-serialized by the browser and a rejection or an unserializable value
+ *     surfaces to the caller as a bare `UnknownError` with no message, so tools
+ *     must always return a JSON value and report errors as data.
+ *   - Tool names are 1..128 chars of `[A-Za-z0-9_.-]`.
+ *   - `annotations` carries `readOnlyHint` and `untrustedContentHint`. The
+ *     dictionary ignores unknown members, which is why `destructiveHint` (an
+ *     MCP hint the WebMCP draft does not have yet, issue #176) can be set
+ *     honestly today at no cost.
+ */
+
+/** Property on `Document` that holds the per-document ModelContext. */
+export const MODEL_CONTEXT_PROPERTY = 'modelContext';
+
+/** Event fired at a document whenever its visible tool set changes. */
+export const TOOL_CHANGE_EVENT = 'toolchange';
+
+/** Spec name rule (`index.bs`: 1..128 chars of `[A-Za-z0-9_.-]`). */
+export const TOOL_NAME_PATTERN = /^[A-Za-z0-9_.-]{1,128}$/;
+
+export interface ModelContextToolAnnotations {
+  readOnlyHint?: boolean;
+  untrustedContentHint?: boolean;
+  /** Forward-compatible (MCP hint, WebMCP issue #176). Ignored by today's dictionary. */
+  destructiveHint?: boolean;
+}
+
+export interface ModelContextExecuteContext {
+  signal: AbortSignal;
+}
+
+export type ModelContextExecute = (
+  input: unknown,
+  context: ModelContextExecuteContext,
+) => unknown | Promise<unknown>;
+
+/** `ModelContextTool` dictionary, structural subset. */
+export interface ModelContextToolDescriptor {
+  name: string;
+  title?: string;
+  description: string;
+  inputSchema?: Record<string, unknown>;
+  execute: ModelContextExecute;
+  annotations?: ModelContextToolAnnotations;
+}
+
+export interface ModelContextRegisterOptions {
+  signal?: AbortSignal;
+}
+
+/** `RegisteredTool` dictionary, the part `getTools()` callers read. */
+export interface ModelContextRegisteredTool {
+  name: string;
+  title?: string;
+  description: string;
+  inputSchema?: Record<string, unknown>;
+  annotations?: ModelContextToolAnnotations;
+}
+
+/** The nine lines of the API the engine actually uses. */
+export interface ModelContextLike {
+  registerTool(tool: ModelContextToolDescriptor, options?: ModelContextRegisterOptions): Promise<unknown>;
+  getTools?(options?: Record<string, unknown>): Promise<ModelContextRegisteredTool[]>;
+  executeTool?(tool: ModelContextRegisteredTool, input?: object, options?: Record<string, unknown>): Promise<string>;
+  addEventListener?(type: string, listener: (event: Event) => void): void;
+  removeEventListener?(type: string, listener: (event: Event) => void): void;
+}
+
+/**
+ * Feature detection: the one `typeof` check the module contributes to a
+ * browser without WebMCP. `null` means "no provider", and every layer above
+ * treats `null` as "do nothing" (no effects, no DOM, no settings row).
+ *
+ * House pattern (`utils/clipboard.ts`): `typeof` for the environment, `?.`
+ * for the capability, `try/catch` for restricted contexts that throw on
+ * property access.
+ */
+export function resolveModelContext(doc?: Document | null): ModelContextLike | null {
+  try {
+    const target = doc ?? (typeof document === 'undefined' ? null : document);
+    if (!target) return null;
+    const ctx = (target as unknown as Record<string, unknown>)[MODEL_CONTEXT_PROPERTY];
+    if (!ctx || typeof ctx !== 'object') return null;
+    if (typeof (ctx as ModelContextLike).registerTool !== 'function') return null;
+    return ctx as ModelContextLike;
+  } catch {
+    return null;
+  }
+}

package/webmcp/nudges.ts

@@ -0,0 +1,174 @@
+/**
+ * Nudge computation: every response carries `nudges` computed synchronously
+ * from state the page already holds. No nudge needs a second call to
+ * discover, and every nudge names the ids/paths needed to act on it.
+ *
+ * Messages are static strings we own. Document text, heading titles and
+ * comment text are never concatenated into a message (prompt-injection
+ * hygiene); they travel as data in `ids`, `path` and `section`.
+ *
+ * Pure, no DOM.
+ */
+
+import type { AnnotationChangeTracker } from './changes';
+import type { Nudge } from './toolset';
+
+export type DocumentSurface = 'markdown' | 'html' | 'live-app';
+
+export interface OtherDocumentActivity {
+  path: string;
+  open: boolean;
+  annotations: number;
+  newSinceLastRead: number;
+  composerOpen: boolean;
+  /** The human opened this document since the last response. */
+  openedSinceLastRead: boolean;
+  /** Wall-clock ms of the last change, for ordering; null when never changed. */
+  lastActivity?: number | null;
+}
+
+export interface NudgeSnapshot {
+  surface: DocumentSurface;
+  composer: { open: boolean; section?: string };
+  sourceStale: boolean;
+  documentEdited: boolean;
+  /** Live app: the page the human is on now, and the one at the last response. */
+  pageUrl: string | null;
+  lastPageUrl: string | null;
+  annotationCount: number;
+  /** The human approved / sent feedback / closed. */
+  decided: boolean;
+  /** First response of the session (surface hints fire once). */
+  firstResponse: boolean;
+  /** Set by the response builder when text was windowed: the continuation call's arguments. */
+  truncated?: { nextOffset: number; args: Record<string, unknown> };
+  /** `inReplyTo` per live annotation id, for `replies_new`. */
+  annotations: ReadonlyArray<{ id: string; inReplyTo?: string; source?: string }>;
+  otherDocuments: OtherDocumentActivity[];
+  /** Watermark the novelty checks run against. */
+  since: number;
+}
+
+export const MAX_OTHER_DOCUMENT_NUDGES = 10;
+
+function plural(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+
+export function buildNudges(
+  snapshot: NudgeSnapshot,
+  tracker: AnnotationChangeTracker,
+  toolName: (bare: string) => string,
+): Nudge[] {
+  const nudges: Nudge[] = [];
+  const since = snapshot.since;
+  const agentIds = new Set(snapshot.annotations.filter((a) => a.source === 'browser-agent').map((a) => a.id));
+
+  const fresh = tracker.newSince(since);
+  const replies = fresh.filter((id) => {
+    const parent = snapshot.annotations.find((a) => a.id === id)?.inReplyTo;
+    return parent !== undefined && agentIds.has(parent);
+  });
+  const plain = fresh.filter((id) => !replies.includes(id));
+  if (plain.length > 0) {
+    nudges.push({
+      code: 'annotations_new',
+      message: `The human added or edited ${plural(plain.length, 'comment')} since your last read.`,
+      ids: plain,
+    });
+  }
+  if (replies.length > 0) {
+    nudges.push({
+      code: 'replies_new',
+      message: `The human replied to your comments (${replies.length} new ${replies.length === 1 ? 'reply' : 'replies'}).`,
+      ids: replies,
+    });
+  }
+
+  const removed = tracker.removedSince(since);
+  if (removed.length > 0) {
+    const own = removed.filter((t) => t.agent);
+    nudges.push({
+      code: 'annotations_removed',
+      message: own.length > 0
+        ? `The human removed ${own.length} of your comments; treat that as resolved and do not re-add them.`
+        : `${plural(removed.length, 'comment')} you had seen ${removed.length === 1 ? 'was' : 'were'} removed.`,
+      ids: removed.map((t) => t.id),
+    });
+  }
+
+  if (snapshot.composer.open) {
+    nudges.push({
+      code: 'composer_open',
+      message: 'The human is typing a comment right now; wait before commenting on the same passage.',
+      ...(snapshot.composer.section ? { section: snapshot.composer.section } : {}),
+    });
+  }
+
+  if (snapshot.sourceStale) {
+    nudges.push({
+      code: 'source_stale',
+      message: 'The annotated file changed on disk since it was loaded; the text you read may be behind the file.',
+    });
+  }
+
+  if (snapshot.documentEdited) {
+    nudges.push({
+      code: 'document_edited',
+      message: 'The human is editing the document text; the text reflects their buffer and quote anchors may drift.',
+    });
+  }
+
+  if (snapshot.firstResponse && snapshot.surface !== 'markdown') {
+    nudges.push({
+      code: 'comment_only_surface',
+      message: 'This surface is comment-only: comments anchor on an exact text quote or on the whole document, and nothing can be marked for deletion.',
+    });
+  }
+
+  if (snapshot.surface === 'live-app' && snapshot.lastPageUrl !== null && snapshot.pageUrl !== null && snapshot.pageUrl !== snapshot.lastPageUrl) {
+    nudges.push({
+      code: 'page_changed',
+      message: 'The human navigated to another page of the app since your last read; annotations are listed for the current page.',
+      path: snapshot.pageUrl,
+    });
+  }
+
+  const activeDocs = snapshot.otherDocuments
+    .filter((doc) => doc.newSinceLastRead > 0 || doc.composerOpen || doc.openedSinceLastRead)
+    .slice(0, MAX_OTHER_DOCUMENT_NUDGES);
+  for (const doc of activeDocs) {
+    nudges.push({
+      code: 'other_document_active',
+      message: doc.newSinceLastRead > 0
+        ? `The human is also annotating another document (${plural(doc.newSinceLastRead, 'new comment')}); read it by path.`
+        : doc.composerOpen
+          ? 'The human is typing a comment in another document; read it by path.'
+          : 'The human opened another document since your last read; read it by path.',
+      path: doc.path,
+      action: { tool: toolName('read_document'), args: { path: doc.path } },
+    });
+  }
+
+  if (snapshot.truncated) {
+    nudges.push({
+      code: 'truncated',
+      message: 'The text was windowed at a block boundary; continue from nextOffset to read the rest.',
+      action: { tool: toolName('read_document'), args: { ...snapshot.truncated.args, offset: snapshot.truncated.nextOffset } },
+    });
+  }
+
+  if (snapshot.decided) {
+    nudges.push({
+      code: 'session_decided',
+      message: 'The human has already decided this session; comment tools are no longer registered and nothing more can be added.',
+    });
+  } else if (snapshot.annotationCount > 0) {
+    nudges.push({
+      code: 'pending_unsent',
+      message: `${plural(snapshot.annotationCount, 'annotation')} ${snapshot.annotationCount === 1 ? 'is' : 'are'} pending; the human sends feedback and approves from the page, you do not.`,
+    });
+  }
+
+  return nudges;
+}

package/webmcp/policy.ts

@@ -0,0 +1,50 @@
+/**
+ * Host seam for the WebMCP provider, following the `utils/upload.ts` shape:
+ * a module-level default, `set`/`reset`/`get`, wired through
+ * `configurePlannotatorUI({ webmcp })`. Plannotator passes nothing and gets
+ * today's behavior: enabled (whenever `document.modelContext` exists) with the
+ * `plannotator.` name prefix.
+ */
+
+export interface WebMcpPolicy {
+  /**
+   * Master switch. Default `true`; the engine still registers nothing when
+   * the browser has no `document.modelContext` or the user turned the tools
+   * off in Settings.
+   */
+  enabled?: boolean;
+  /** Prefix applied to every bare tool name. Default `"plannotator."`; hosts namespace their own tools. */
+  namePrefix?: string;
+}
+
+export interface ResolvedWebMcpPolicy {
+  enabled: boolean;
+  namePrefix: string;
+}
+
+export const DEFAULT_WEBMCP_NAME_PREFIX = 'plannotator.';
+
+const defaultPolicy: ResolvedWebMcpPolicy = {
+  enabled: true,
+  namePrefix: DEFAULT_WEBMCP_NAME_PREFIX,
+};
+
+let policy: ResolvedWebMcpPolicy = defaultPolicy;
+
+/** Override the provider policy. Call once at app startup. */
+export function setWebMcpPolicy(next: WebMcpPolicy): void {
+  policy = {
+    enabled: next.enabled ?? defaultPolicy.enabled,
+    namePrefix: typeof next.namePrefix === 'string' ? next.namePrefix : defaultPolicy.namePrefix,
+  };
+}
+
+/** Reset to Plannotator's default policy. Mainly for tests. */
+export function resetWebMcpPolicy(): void {
+  policy = defaultPolicy;
+}
+
+/** Read the active policy at call time (so a late override is honored). */
+export function getWebMcpPolicy(): ResolvedWebMcpPolicy {
+  return policy;
+}

package/webmcp/preference.ts

@@ -0,0 +1,50 @@
+/**
+ * The user's WebMCP opt-out, kept OUT of the settings registry on purpose.
+ *
+ * `configStore.ensureLoaded` seeds every registry entry's default into a
+ * cookie on first settings access, which would write a cookie for every
+ * user of every surface (plan, annotate, code review, the guides.show
+ * viewer) whether or not their browser has `document.modelContext`. That is
+ * a footprint. This module is idle at its default: nothing is read or
+ * written until the Settings row (shown only when the API exists) is
+ * toggled, and turning the tools back on removes the cookie instead of
+ * writing `true`.
+ *
+ * Cookie: `plannotator-webmcp-tools=false` while opted out; absent otherwise.
+ */
+import { useSyncExternalStore } from 'react';
+import { storage } from '../utils/storage';
+
+export const WEBMCP_TOOLS_COOKIE = 'plannotator-webmcp-tools';
+
+const listeners = new Set<() => void>();
+/** Resolved lazily on first read; write-through afterwards so the snapshot is stable for useSyncExternalStore. */
+let cached: boolean | null = null;
+
+/** Whether the tools are enabled for this browser (default true; only an explicit opt-out disables). */
+export function getWebMcpToolsEnabled(): boolean {
+  if (cached === null) cached = storage.getItem(WEBMCP_TOOLS_COOKIE) !== 'false';
+  return cached;
+}
+
+/** Persist the opt-out. `true` removes the cookie so the default stays cookie-free. */
+export function setWebMcpToolsEnabled(enabled: boolean): void {
+  if (enabled) {
+    if (storage.getItem(WEBMCP_TOOLS_COOKIE) !== null) storage.removeItem(WEBMCP_TOOLS_COOKIE);
+  } else {
+    storage.setItem(WEBMCP_TOOLS_COOKIE, 'false');
+  }
+  cached = enabled;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeWebMcpToolsEnabled(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function useWebMcpToolsEnabled(): boolean {
+  return useSyncExternalStore(subscribeWebMcpToolsEnabled, getWebMcpToolsEnabled, getWebMcpToolsEnabled);
+}