@ai-matrx/rich-content 0.2.10 → 0.2.16

package/dist/rich-document/actions/provider.js

@@ -0,0 +1,245 @@
+import { holdDeliberateIntent } from "../../host/app-bindings.js";
+import {
+  computeEligibility,
+  createClickTarget
+} from "@ai-matrx/alchemy/actions";
+import { registerAlchemyIcon } from "../../utils/alchemy-icon-keys.js";
+import { MENU_STRUCTURE, menuStructureVersion } from "../variants/shared/menuStructure.js";
+import { resolveActionLabel } from "./labels.js";
+import { ensureRichDocumentRegistrations } from "../registrations.js";
+const RICH_DOCUMENT_PROVIDER_ID = "rich-document";
+const RICH_DOCUMENT_SOURCE_TARGET = "rich_document_source";
+const SOURCE_WRITE_TARGET = {
+  name: RICH_DOCUMENT_SOURCE_TARGET,
+  label: "This content",
+  description: "The record the content came from, changed through its source adapter.",
+  valueType: "document",
+  mode: "entity"
+};
+function store() {
+  const key = /* @__PURE__ */ Symbol.for("ai-matrx.rich-document.actions");
+  const g = globalThis;
+  let s = g[key];
+  if (!s) {
+    s = { actions: /* @__PURE__ */ new Map(), listeners: /* @__PURE__ */ new Set() };
+    g[key] = s;
+  }
+  return s;
+}
+function readStore() {
+  ensureRichDocumentRegistrations();
+  return store();
+}
+function registerAction(action) {
+  const { actions: ACTIONS, listeners } = store();
+  if (ACTIONS.has(action.id)) {
+    if (true) {
+      console.warn(
+        `[rich-document] action "${action.id}" re-registered (fast refresh) \u2014 replaced.`
+      );
+    } else {
+      throw new DuplicateActionError(action.id, RICH_DOCUMENT_PROVIDER_ID, RICH_DOCUMENT_PROVIDER_ID);
+    }
+  }
+  ACTIONS.set(action.id, action);
+  for (const l of [...listeners]) l();
+}
+function getAction(id) {
+  return readStore().actions.get(id);
+}
+function getAllActions() {
+  return Array.from(readStore().actions.values());
+}
+function richDocumentSectionId(label) {
+  return `rd:${label.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+}
+let placementCache = null;
+let placementVersion = -1;
+function placementOf(id) {
+  if (placementCache === null || placementVersion !== menuStructureVersion()) {
+    placementVersion = menuStructureVersion();
+    placementCache = buildPlacement();
+  }
+  return placementCache.get(id);
+}
+function buildPlacement() {
+  const map = /* @__PURE__ */ new Map();
+  MENU_STRUCTURE.forEach((section, sectionIndex) => {
+    section.actionIds.forEach((id, index) => {
+      const order = sectionIndex * 100 + index;
+      if (section.submenu === null || section.inline) {
+        map.set(id, { order });
+      } else {
+        const icon = section.icon ? registerAlchemyIcon(section.icon) : void 0;
+        map.set(id, {
+          order,
+          ...section.layoutCategory ? { category: section.layoutCategory } : {},
+          section: {
+            id: richDocumentSectionId(section.submenu),
+            label: section.submenu,
+            ...icon ? { icon } : {},
+            ...section.target ? { kind: "target" } : {}
+          }
+        });
+      }
+    });
+  });
+  return map;
+}
+const MENU_ALIASES = {
+  "regenerate-latest": "regenerate-response"
+};
+function hostOf(target) {
+  const host = target.host;
+  if (!host) return null;
+  if (host.kind === "rich-document") return host;
+  return host.richDocument?.kind === "rich-document" ? host.richDocument : null;
+}
+function richDocumentTargetHost(ctx, options = {}) {
+  return { kind: "rich-document", ctx, getCtx: options.getCtx ?? (() => ctx), extra: options.extra ?? [] };
+}
+function richDocumentClickTarget(ctx, options = {}) {
+  const readOnly = Boolean(ctx.source.readOnly);
+  const host = {
+    kind: "rich-document",
+    ctx,
+    getCtx: options.getCtx ?? (() => ctx),
+    extra: options.extra ?? []
+  };
+  return createClickTarget({
+    readOnly,
+    writable: readOnly ? [] : [SOURCE_WRITE_TARGET],
+    excludedActionIds: options.exclude ?? [],
+    organizationId: ctx.organizationId,
+    auth: { authenticated: ctx.isAuthenticated, admin: ctx.isAdmin, creator: ctx.isCreator },
+    payloadKinds: ["markdown"],
+    host
+  });
+}
+function eligibleFor(rd, target) {
+  const host = hostOf(target);
+  if (!host) return { status: "absent" };
+  const ctx = host.ctx;
+  if (rd.supportedSources !== "*" && !rd.supportedSources.includes(ctx.source.type)) {
+    return { status: "absent" };
+  }
+  if (rd.visible && !rd.visible(ctx)) return { status: "absent" };
+  const disabled = rd.disabled?.(ctx);
+  if (disabled === true || typeof disabled === "object" && disabled !== null) {
+    return { status: "absent" };
+  }
+  return { status: "available" };
+}
+const converted = /* @__PURE__ */ new WeakMap();
+function toAlchemyAction(rd) {
+  const cached = converted.get(rd);
+  if (cached) return cached;
+  const place = placementOf(rd.id);
+  const ctxOf = (t) => hostOf(t)?.ctx;
+  const action = {
+    id: rd.id,
+    provider: RICH_DOCUMENT_PROVIDER_ID,
+    label: (t) => {
+      const ctx = ctxOf(t);
+      return ctx ? resolveActionLabel(rd.label, ctx) : typeof rd.label === "string" ? rd.label : rd.id;
+    },
+    icon: registerAlchemyIcon(rd.icon),
+    ...rd.iconColor ? { iconTone: rd.iconColor } : {},
+    ...rd.stateIcon ? {
+      stateIcon: (t) => {
+        const ctx = ctxOf(t);
+        const live = ctx ? rd.stateIcon?.(ctx) : null;
+        return live ? { icon: registerAlchemyIcon(live.icon), ...live.spin ? { spin: true } : {} } : null;
+      }
+    } : {},
+    category: place?.category ?? rd.category,
+    order: place?.order ?? 1e4 + (rd.order ?? 0),
+    placement: rd.renderSlot ?? "overflow",
+    ...place?.section ? { section: place.section } : {},
+    ...rd.requiresAuth ? { requiresAuth: true } : {},
+    ...rd.writesSource ? { writes: [RICH_DOCUMENT_SOURCE_TARGET] } : {},
+    ...rd.preserveSelection ? { preserveSelection: true } : {},
+    ...rd.active ? {
+      pressed: (t) => {
+        const ctx = ctxOf(t);
+        return ctx ? Boolean(rd.active?.(ctx)) : false;
+      }
+    } : {},
+    ...rd.subscribe ? {
+      subscribe: (onChange, t) => {
+        const ctx = ctxOf(t);
+        if (!ctx || !rd.subscribe) return () => void 0;
+        let subscribing = true;
+        const off = rd.subscribe(() => {
+          if (!subscribing) onChange();
+        }, ctx);
+        subscribing = false;
+        return off;
+      }
+    } : {},
+    eligible: (t) => eligibleFor(rd, t),
+    run: async (t) => {
+      const host = hostOf(t);
+      if (!host) return;
+      await holdDeliberateIntent(() => rd.run(host.getCtx()));
+    }
+  };
+  converted.set(rd, action);
+  return action;
+}
+function candidates(target) {
+  const host = hostOf(target);
+  if (!host) return [];
+  const ACTIONS = readStore().actions;
+  const all = [...ACTIONS.values(), ...host.extra.filter((a) => !ACTIONS.has(a.id))];
+  const present = new Set(all.map((a) => a.id));
+  return all.filter((a) => {
+    const canonical = MENU_ALIASES[a.id];
+    return !(canonical && present.has(canonical));
+  });
+}
+const REGISTERED = /* @__PURE__ */ new WeakSet();
+function ensureRichDocumentProvider(registry) {
+  if (REGISTERED.has(registry)) return;
+  REGISTERED.add(registry);
+  registry.register(richDocumentActionProvider);
+}
+const richDocumentActionProvider = {
+  id: RICH_DOCUMENT_PROVIDER_ID,
+  tier: "T0",
+  declaredIds: () => [...readStore().actions.keys()],
+  actions: (target) => candidates(target).map(toAlchemyAction)
+};
+function subscribeRichDocumentActions(listener) {
+  const { listeners } = store();
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+function resolveActions(ctx, options) {
+  const target = richDocumentClickTarget(ctx, {
+    exclude: options?.exclude ?? [],
+    extra: options?.extra ?? []
+  });
+  return candidates(target).filter((rd) => computeEligibility(toAlchemyAction(rd), target, { authResumable: false }).status === "available").sort((a, b) => {
+    if (a.category !== b.category) return a.category.localeCompare(b.category);
+    return (a.order ?? 0) - (b.order ?? 0);
+  });
+}
+export {
+  RICH_DOCUMENT_PROVIDER_ID,
+  RICH_DOCUMENT_SOURCE_TARGET,
+  SOURCE_WRITE_TARGET,
+  ensureRichDocumentProvider,
+  getAction,
+  getAllActions,
+  registerAction,
+  resolveActions,
+  richDocumentActionProvider,
+  richDocumentClickTarget,
+  richDocumentSectionId,
+  richDocumentTargetHost,
+  subscribeRichDocumentActions,
+  toAlchemyAction
+};

package/dist/rich-document/actions/resumePendingAuthAction.d.ts

@@ -0,0 +1,3 @@
+import type { RichDocumentActionContext } from "../types.js";
+/** Replay a stashed action when the context's content matches. Never throws. */
+export declare function resumePendingAuthAction(ctx: RichDocumentActionContext): void;

package/dist/rich-document/actions/resumePendingAuthAction.js

@@ -0,0 +1,31 @@
+import { getAction } from "./provider.js";
+import { PENDING_ACTION_KEY } from "./labels.js";
+function resumePendingAuthAction(ctx) {
+  if (!ctx.isAuthenticated) return;
+  let pending = null;
+  try {
+    const raw = sessionStorage.getItem(PENDING_ACTION_KEY);
+    if (!raw) return;
+    pending = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (!pending || pending.savedContent !== ctx.content) return;
+  try {
+    sessionStorage.removeItem(PENDING_ACTION_KEY);
+  } catch {
+  }
+  const action = typeof pending.action === "string" ? getAction(pending.action) : void 0;
+  if (!action) {
+    console.error(
+      `[RichDocument] post-auth resume: no registered action "${String(pending.action)}" \u2014 the pending request was dropped.`
+    );
+    return;
+  }
+  void Promise.resolve(action.run(ctx)).catch((err) => {
+    console.error(`[RichDocument] post-auth resume of ${action.id} threw`, err);
+  });
+}
+export {
+  resumePendingAuthAction
+};

package/dist/rich-document/actions/sources/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ContentSourceType → ContentSourceAdapter. The engine ships `raw`; the host registers the rest
+ * (matrx-frontend: chat-message, note, prompt-result, artifact, scraper-result, working-document)
+ * through `registerSourceAdapter`, on import of its registration module.
+ */
+import type { ContentSourceAdapter, ContentSourceType } from "../../types.js";
+/** Register (or replace) the adapter for one source type. */
+export declare function registerSourceAdapter(sourceType: ContentSourceType, adapter: ContentSourceAdapter): void;
+export declare function getSourceAdapter(sourceType: ContentSourceType): ContentSourceAdapter;

package/dist/rich-document/actions/sources/index.js

@@ -0,0 +1,22 @@
+import { rawAdapter } from "./raw.js";
+import { ensureRichDocumentRegistrations } from "../../registrations.js";
+const KEY = /* @__PURE__ */ Symbol.for("ai-matrx.rich-content.rich-document.source-adapters");
+function adapters() {
+  const g = globalThis;
+  return g[KEY] ??= /* @__PURE__ */ new Map([["raw", rawAdapter]]);
+}
+function registerSourceAdapter(sourceType, adapter) {
+  adapters().set(sourceType, adapter);
+}
+function getSourceAdapter(sourceType) {
+  ensureRichDocumentRegistrations();
+  const adapter = adapters().get(sourceType);
+  if (!adapter) {
+    throw new Error(`No source adapter registered for type: ${sourceType}`);
+  }
+  return adapter;
+}
+export {
+  getSourceAdapter,
+  registerSourceAdapter
+};

package/dist/rich-document/actions/sources/raw.d.ts

@@ -0,0 +1,4 @@
+import type { ContentSourceAdapter } from "../../types.js";
+declare function shortHash(input: string): string;
+export declare const rawAdapter: ContentSourceAdapter;
+export { shortHash };

package/dist/rich-document/actions/sources/raw.js

@@ -0,0 +1,35 @@
+const LONG_INPUT = 4096;
+const recent = /* @__PURE__ */ new Map();
+function shortHash(input) {
+  if (input.length >= LONG_INPUT) {
+    const hit = recent.get(input);
+    if (hit !== void 0) return hit;
+    const computed = fnv1a(input);
+    if (recent.size >= 8) recent.delete(recent.keys().next().value);
+    recent.set(input, computed);
+    return computed;
+  }
+  return fnv1a(input);
+}
+function fnv1a(input) {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = hash * 16777619 >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+const rawAdapter = {
+  instanceKeyPrefix: (source) => {
+    if (source.type !== "raw") {
+      throw new Error(
+        `rawAdapter received non-raw source: ${source.type}`
+      );
+    }
+    return "raw";
+  }
+};
+export {
+  rawAdapter,
+  shortHash
+};

package/dist/rich-document/actions/useRichDocumentProvider.d.ts

@@ -0,0 +1 @@
+export declare function useRichDocumentProvider(): void;

package/dist/rich-document/actions/useRichDocumentProvider.js

@@ -0,0 +1,13 @@
+"use client";
+import * as React from "react";
+import { useAlchemyActions } from "@ai-matrx/alchemy/react/host";
+import { ensureRichDocumentProvider } from "./provider.js";
+function useRichDocumentProvider() {
+  const { registry } = useAlchemyActions();
+  React.useLayoutEffect(() => {
+    ensureRichDocumentProvider(registry);
+  }, [registry]);
+}
+export {
+  useRichDocumentProvider
+};

package/dist/rich-document/host-types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The host's own types the rich-document contract carries (its store's dispatch and state, its
+ * note record, its application scope). The host fills them in by augmentation — matrx-frontend:
+ *
+ *   declare module "@ai-matrx/rich-content/rich-document/host-types" {
+ *     interface RichDocumentHostTypes { dispatch: AppDispatch; state: RootState; note: Note; ... }
+ *   }
+ *
+ * Unaugmented, each is a structural default.
+ */
+export interface RichDocumentHostTypes {
+}
+type HostType<K extends string, Default> = RichDocumentHostTypes extends Record<K, infer T> ? T : Default;
+export type AppDispatch = HostType<"dispatch", (action: any) => any>;
+export type RootState = HostType<"state", Record<string, unknown>>;
+export type ApplicationScope = HostType<"applicationScope", Record<string, unknown>>;
+export type Note = HostType<"note", {
+    id: string;
+    content?: string | null;
+    label?: string | null;
+    [key: string]: unknown;
+}>;
+export type NoteSaveReceipt = HostType<"noteSaveReceipt", {
+    [key: string]: unknown;
+}>;
+/** The saved record a content source names (matrx-frontend: annotations/record-of-source). */
+export interface AnnotationRecord {
+    token: string;
+    id: string;
+    title?: string;
+    contentVersion?: number;
+    href?: string;
+    /** A chat answer's conversation. */
+    conversationId?: string;
+}
+/** The reading set's record + body (matrx-frontend: annotations/types `AnnotationSource`). */
+export interface AnnotationSource {
+    token: string;
+    id: string;
+    title: string;
+    body: string;
+    contentVersion: number;
+    href?: string;
+    conversationId?: string;
+}
+/** A server-processed block the full renderer accepts (matrx-frontend: EnhancedChatMarkdown). */
+export type ServerProcessedBlock = HostType<"serverProcessedBlock", {
+    type: string;
+    [key: string]: unknown;
+}>;
+export {};

package/dist/rich-document/registrations.d.ts

@@ -0,0 +1 @@
+export declare function ensureRichDocumentRegistrations(): void;

package/dist/rich-document/registrations.js

@@ -0,0 +1,13 @@
+import { hostCapability } from "../host/registry.js";
+const ENSURED = /* @__PURE__ */ Symbol.for("ai-matrx.rich-content.rich-document.registrations-ensured");
+function ensureRichDocumentRegistrations() {
+  const g = globalThis;
+  if (g[ENSURED]) return;
+  const ensure = hostCapability("ensureRichDocumentRegistrations");
+  if (!ensure) return;
+  g[ENSURED] = true;
+  ensure();
+}
+export {
+  ensureRichDocumentRegistrations
+};

package/dist/rich-document/review/applyTargets.d.ts

@@ -0,0 +1,16 @@
+import type { RichDocumentActionContext } from "../types.js";
+interface ApplyTarget {
+    ctx: RichDocumentActionContext;
+    /** What the source is called, for the action's label. */
+    label: string;
+}
+/** True when an answer about this text could be applied back to it. */
+export declare function canApplyBack(ctx: RichDocumentActionContext): boolean;
+export declare function registerApplyTarget(ctx: RichDocumentActionContext, label: string): string;
+export declare function bindConversationToApplyTarget(conversationId: string, targetId: string): void;
+export declare function applyTargetForConversation(conversationId: string | null | undefined): {
+    id: string;
+    label: string;
+} | null;
+export declare function getApplyTarget(id: string | null | undefined): ApplyTarget | null;
+export {};

package/dist/rich-document/review/applyTargets.js

@@ -0,0 +1,32 @@
+const targets = /* @__PURE__ */ new Map();
+const byConversation = /* @__PURE__ */ new Map();
+let seq = 0;
+const APPLYABLE_SOURCES = /* @__PURE__ */ new Set(["note", "chat-message", "working-document"]);
+function canApplyBack(ctx) {
+  return APPLYABLE_SOURCES.has(ctx.source.type) && ctx.source.readOnly !== true;
+}
+function registerApplyTarget(ctx, label) {
+  seq += 1;
+  const id = `apply-target-${seq}`;
+  targets.set(id, { ctx, label });
+  return id;
+}
+function bindConversationToApplyTarget(conversationId, targetId) {
+  if (targets.has(targetId)) byConversation.set(conversationId, targetId);
+}
+function applyTargetForConversation(conversationId) {
+  if (!conversationId) return null;
+  const id = byConversation.get(conversationId);
+  const target = id ? targets.get(id) : void 0;
+  return id && target ? { id, label: target.label } : null;
+}
+function getApplyTarget(id) {
+  return id ? targets.get(id) ?? null : null;
+}
+export {
+  applyTargetForConversation,
+  bindConversationToApplyTarget,
+  canApplyBack,
+  getApplyTarget,
+  registerApplyTarget
+};

package/dist/rich-document/review/proposedEdit.d.ts

@@ -0,0 +1,22 @@
+import { type SourceEdit, type SpliceResult } from "@ai-matrx/content-ir/source";
+export interface ProposedEdit {
+    /** The one block-aligned edit, or null when nothing differs. */
+    edit: SourceEdit | null;
+    /** Blocks of the original that stay byte-identical. */
+    keptBlocks: number;
+    /** Blocks of the original the edit replaces. */
+    replacedBlocks: number;
+}
+export declare function reduceToBlockEdit(original: string, proposed: string): ProposedEdit;
+/**
+ * The text to persist for a proposal: `original` with only the changed run
+ * spliced in. Throws `SourceSpliceError` when the splice would disturb an
+ * island it did not name — the caller surfaces that, never forces it.
+ */
+export declare function spliceProposal(original: string, proposed: string): SpliceResult | null;
+/**
+ * A splice refusal in words a person reads — never offsets or function names
+ * ("edit [0, 776) changes … island at [141, 233); islands change only through
+ * islandEdit()" was shown verbatim, verify-RC-B5 round 3 F7).
+ */
+export declare function explainSpliceRefusal(error: unknown): string;

package/dist/rich-document/review/proposedEdit.js

@@ -0,0 +1,48 @@
+import {
+  SourceSpliceError,
+  spliceSave,
+  tokenizeSource
+} from "@ai-matrx/content-ir/source";
+function reduceToBlockEdit(original, proposed) {
+  const a = tokenizeSource(original);
+  const b = tokenizeSource(proposed);
+  let head = 0;
+  while (head < a.length && head < b.length && a[head].raw === b[head].raw) {
+    head += 1;
+  }
+  if (head === a.length && head === b.length) {
+    return { edit: null, keptBlocks: a.length, replacedBlocks: 0 };
+  }
+  let tail = 0;
+  while (tail < a.length - head && tail < b.length - head && a[a.length - 1 - tail].raw === b[b.length - 1 - tail].raw) {
+    tail += 1;
+  }
+  const oldFirst = head;
+  const oldLast = a.length - 1 - tail;
+  const start = oldFirst < a.length ? a[oldFirst].start : original.length;
+  const end = oldLast >= oldFirst ? a[oldLast].end : start;
+  const newStart = head < b.length ? b[head].start : proposed.length;
+  const newEnd = b.length - 1 - tail >= head ? b[b.length - 1 - tail].end : newStart;
+  return {
+    edit: { start, end, text: proposed.slice(newStart, newEnd) },
+    keptBlocks: head + tail,
+    replacedBlocks: Math.max(0, oldLast - oldFirst + 1)
+  };
+}
+function spliceProposal(original, proposed) {
+  const { edit } = reduceToBlockEdit(original, proposed);
+  if (!edit) return null;
+  return spliceSave(original, [edit]);
+}
+function explainSpliceRefusal(error) {
+  const code = error instanceof SourceSpliceError ? error.code : null;
+  if (code === "island_edit" || code === "integrity") {
+    return "This change would alter protected content \u2014 code, math, a table, a section or hidden reasoning \u2014 which is only changed in its own editor.";
+  }
+  return "This change could not be placed exactly into the saved text.";
+}
+export {
+  explainSpliceRefusal,
+  reduceToBlockEdit,
+  spliceProposal
+};

package/dist/rich-document/review/protectedSpans.d.ts

@@ -0,0 +1,14 @@
+export interface MaskedText {
+    /** What the agent receives. */
+    text: string;
+    /** Original bytes of each span; marker `⟦Pn⟧` stands for spans[n-1]. */
+    spans: string[];
+}
+export declare function maskProtectedSpans(text: string): MaskedText;
+export type UnmaskResult = {
+    text: string;
+} | {
+    error: string;
+};
+/** Put every protected span back, byte-for-byte — or say which ones the agent broke. */
+export declare function unmaskProtectedSpans(result: string, spans: readonly string[]): UnmaskResult;

package/dist/rich-document/review/protectedSpans.js

@@ -0,0 +1,61 @@
+import { listIslands, tokenizeSource } from "@ai-matrx/content-ir/source";
+const ESCAPES = (
+  // eslint-disable-next-line no-control-regex
+  /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b[@-Z\\-_]|[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g
+);
+const MARKER = /⟦P(\d+)⟧/g;
+function maskProtectedSpans(text) {
+  if (MARKER.test(text)) {
+    MARKER.lastIndex = 0;
+    return { text, spans: [] };
+  }
+  MARKER.lastIndex = 0;
+  const ranges = [];
+  for (const m of text.matchAll(ESCAPES)) {
+    ranges.push({ start: m.index ?? 0, end: (m.index ?? 0) + m[0].length });
+  }
+  for (const island of listIslands(tokenizeSource(text))) {
+    if (island.inline || island.islandType === "json") {
+      ranges.push({ start: island.start, end: island.end });
+    }
+  }
+  ranges.sort((a, b) => a.start - b.start || b.end - a.end);
+  const kept = [];
+  for (const r of ranges) {
+    const last = kept[kept.length - 1];
+    if (last && r.start < last.end) continue;
+    kept.push(r);
+  }
+  if (kept.length === 0) return { text, spans: [] };
+  const spans = [];
+  let out = "";
+  let at = 0;
+  for (const r of kept) {
+    out += text.slice(at, r.start);
+    spans.push(text.slice(r.start, r.end));
+    out += `\u27E6P${spans.length}\u27E7`;
+    at = r.end;
+  }
+  out += text.slice(at);
+  return { text: out, spans };
+}
+function unmaskProtectedSpans(result, spans) {
+  if (spans.length === 0) return { text: result };
+  const seen = /* @__PURE__ */ new Map();
+  for (const m of result.matchAll(MARKER)) {
+    const n = Number(m[1]);
+    seen.set(n, (seen.get(n) ?? 0) + 1);
+  }
+  const broken = spans.map((_, i) => i + 1).filter((n) => seen.get(n) !== 1);
+  const invented = [...seen.keys()].filter((n) => n < 1 || n > spans.length);
+  if (broken.length > 0 || invented.length > 0) {
+    return {
+      error: "The agent's result dropped or changed protected text (terminal codes, variables or similar), so it cannot be applied. Run it again, or make the change in the editor."
+    };
+  }
+  return { text: result.replace(MARKER, (_, n) => spans[Number(n) - 1]) };
+}
+export {
+  maskProtectedSpans,
+  unmaskProtectedSpans
+};

package/dist/rich-document/runtime/actionSurfacesStore.d.ts

@@ -0,0 +1,30 @@
+import type { RichDocumentActionSpec, RichDocumentSurfaceRegistration } from "../types.js";
+export interface ActionSurfacesState {
+    /** surfaceId → ordered stack of providers (oldest first, newest at end). */
+    bySurfaceId: Record<string, RichDocumentSurfaceRegistration[]>;
+}
+/** Push a provider onto a surface's stack; a re-registration by providerId updates in place. */
+export declare function registerProvider(payload: {
+    surfaceId: string;
+    registration: RichDocumentSurfaceRegistration;
+}): void;
+/** Update the action-spec snapshot for an already-registered provider. */
+export declare function updateProviderSpecs(payload: {
+    surfaceId: string;
+    providerId: string;
+    computedActionSpecs: RichDocumentActionSpec[];
+    contentSourceId: string;
+}): void;
+/** Remove a provider by id; the remaining order is preserved. */
+export declare function unregisterProvider(payload: {
+    surfaceId: string;
+    providerId: string;
+}): void;
+/** Test/maintenance: clear everything. */
+export declare function clearAll(): void;
+export declare function getActionSurfacesState(): ActionSurfacesState;
+export declare function selectTopProvider(state: ActionSurfacesState, surfaceId: string): RichDocumentSurfaceRegistration | null;
+export declare function selectProviderStack(state: ActionSurfacesState, surfaceId: string): RichDocumentSurfaceRegistration[];
+export declare function selectSurfaceActionSpecs(state: ActionSurfacesState, surfaceId: string): RichDocumentActionSpec[];
+/** The top-of-stack provider for a surface, live. */
+export declare function useTopProvider(surfaceId: string): RichDocumentSurfaceRegistration | null;