@ai-matrx/rich-content 0.2.9 → 0.2.15

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;

package/dist/rich-document/runtime/actionSurfacesStore.js

@@ -0,0 +1,79 @@
+import { useSyncExternalStore } from "react";
+const KEY = /* @__PURE__ */ Symbol.for("ai-matrx.rich-content.rich-document.action-surfaces");
+function store() {
+  const g = globalThis;
+  return g[KEY] ??= { state: { bySurfaceId: {} }, listeners: /* @__PURE__ */ new Set() };
+}
+function commit(next) {
+  const s = store();
+  s.state = { bySurfaceId: next };
+  for (const listener of s.listeners) listener();
+}
+function registerProvider(payload) {
+  const { surfaceId, registration } = payload;
+  const stack = [...store().state.bySurfaceId[surfaceId] ?? []];
+  const idx = stack.findIndex((entry) => entry.providerId === registration.providerId);
+  if (idx >= 0) stack[idx] = registration;
+  else stack.push(registration);
+  commit({ ...store().state.bySurfaceId, [surfaceId]: stack });
+}
+function updateProviderSpecs(payload) {
+  const { surfaceId, providerId, computedActionSpecs, contentSourceId } = payload;
+  const stack = store().state.bySurfaceId[surfaceId];
+  if (!stack) return;
+  const idx = stack.findIndex((entry) => entry.providerId === providerId);
+  if (idx < 0) return;
+  const next = [...stack];
+  next[idx] = { ...stack[idx], computedActionSpecs, contentSourceId };
+  commit({ ...store().state.bySurfaceId, [surfaceId]: next });
+}
+function unregisterProvider(payload) {
+  const { surfaceId, providerId } = payload;
+  const stack = store().state.bySurfaceId[surfaceId];
+  if (!stack) return;
+  const next = stack.filter((entry) => entry.providerId !== providerId);
+  const all = { ...store().state.bySurfaceId };
+  if (next.length === 0) delete all[surfaceId];
+  else all[surfaceId] = next;
+  commit(all);
+}
+function clearAll() {
+  commit({});
+}
+function getActionSurfacesState() {
+  return store().state;
+}
+function subscribe(listener) {
+  store().listeners.add(listener);
+  return () => store().listeners.delete(listener);
+}
+const EMPTY_PROVIDER_STACK = [];
+const EMPTY_ACTION_SPECS = [];
+function selectTopProvider(state, surfaceId) {
+  const stack = state.bySurfaceId[surfaceId];
+  return stack && stack.length > 0 ? stack[stack.length - 1] : null;
+}
+function selectProviderStack(state, surfaceId) {
+  return state.bySurfaceId[surfaceId] ?? EMPTY_PROVIDER_STACK;
+}
+function selectSurfaceActionSpecs(state, surfaceId) {
+  return selectTopProvider(state, surfaceId)?.computedActionSpecs ?? EMPTY_ACTION_SPECS;
+}
+function useTopProvider(surfaceId) {
+  return useSyncExternalStore(
+    subscribe,
+    () => selectTopProvider(store().state, surfaceId),
+    () => null
+  );
+}
+export {
+  clearAll,
+  getActionSurfacesState,
+  registerProvider,
+  selectProviderStack,
+  selectSurfaceActionSpecs,
+  selectTopProvider,
+  unregisterProvider,
+  updateProviderSpecs,
+  useTopProvider
+};

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

@@ -0,0 +1,6 @@
+import type { RichDocumentAction, RichDocumentActionId, RichDocumentActionsVariant } from "../types.js";
+export type ContextMenuOption = boolean | {
+    extra?: RichDocumentAction[];
+    exclude?: (RichDocumentActionId | string)[];
+};
+export declare function contextMenuFor(prop: ContextMenuOption | undefined, variant: RichDocumentActionsVariant): ContextMenuOption | false;

package/dist/rich-document/runtime/contextMenuFor.js

@@ -0,0 +1,7 @@
+function contextMenuFor(prop, variant) {
+  if (prop !== void 0) return prop;
+  return variant === "bar" || variant === "mini-bar" || variant === "menu" || variant === "icon-only";
+}
+export {
+  contextMenuFor
+};

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

@@ -0,0 +1,20 @@
+import type { ClickTarget } from "@ai-matrx/alchemy/actions";
+import type { RichDocumentAction, RichDocumentActionContext } from "../types.js";
+export interface ProviderBridge {
+    /** Builds a fresh action context from the host's live state/refs. */
+    getCtx: () => RichDocumentActionContext;
+    /** The actions visible for this provider (already filtered + sorted). */
+    resolvedActions: RichDocumentAction[];
+    /** The Alchemy click target the package layouts resolve against (ALC-15). */
+    target: ClickTarget;
+}
+export declare function registerBridge(providerId: string, bridge: ProviderBridge): void;
+/**
+ * Refresh an existing bridge (no semantic difference from register today,
+ * but kept separate so call sites are self-documenting).
+ */
+export declare function updateBridge(providerId: string, bridge: ProviderBridge): void;
+export declare function unregisterBridge(providerId: string): void;
+export declare function getBridge(providerId: string): ProviderBridge | undefined;
+/** Diagnostics only. */
+export declare function _getAllBridges(): ReadonlyMap<string, ProviderBridge>;

package/dist/rich-document/runtime/providerBridge.js

@@ -0,0 +1,23 @@
+const BRIDGES = /* @__PURE__ */ new Map();
+function registerBridge(providerId, bridge) {
+  BRIDGES.set(providerId, bridge);
+}
+function updateBridge(providerId, bridge) {
+  BRIDGES.set(providerId, bridge);
+}
+function unregisterBridge(providerId) {
+  BRIDGES.delete(providerId);
+}
+function getBridge(providerId) {
+  return BRIDGES.get(providerId);
+}
+function _getAllBridges() {
+  return BRIDGES;
+}
+export {
+  _getAllBridges,
+  getBridge,
+  registerBridge,
+  unregisterBridge,
+  updateBridge
+};

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

@@ -0,0 +1,33 @@
+import type { ClickTarget } from "@ai-matrx/alchemy/actions";
+import type { ContentSource, RichDocumentAction, RichDocumentActionContext, RichDocumentActionsProp, RichDocumentActionsVariant } from "../types.js";
+export interface UseActionSurfaceProviderArgs {
+    content: string | undefined;
+    source: ContentSource;
+    actions?: RichDocumentActionsProp;
+    /** Only "remote" registers to the Redux surface; all variants register the bridge. */
+    actionsVariant: RichDocumentActionsVariant;
+    /** Required when actionsVariant === "remote". */
+    actionsSurfaceId?: string;
+}
+export interface UseActionSurfaceProviderResult {
+    /** Render-time context (from props). Safe to read during render — used to
+     * resolve auxiliary action sets (e.g. context-menu actions). */
+    ctx: RichDocumentActionContext;
+    /** Ref-based context factory. Read inside event handlers only. */
+    getCtx: () => RichDocumentActionContext;
+    /** The actions visible for this source + this consumer's exclude/extra. */
+    resolvedActions: RichDocumentAction[];
+    /**
+     * The Alchemy click target for this content (ALC-15): what the package's
+     * layouts (bar, ⋯, sheet) resolve the one registry against. Stable until
+     * something that changes eligibility changes (content, source, auth, org,
+     * exclude/extra).
+     */
+    target: ClickTarget;
+}
+/**
+ * Register a RichDocument action provider (specs + bridge) for a surface and
+ * expose the live context + resolved action list. See the file header for the
+ * no-functions-in-Redux invariant.
+ */
+export declare function useActionSurfaceProvider(args: UseActionSurfaceProviderArgs): UseActionSurfaceProviderResult;