@agent-native/core 0.85.7 → 0.86.1

package/dist/collab/undo.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Shared per-user undo/redo for collaborative surfaces.
+ *
+ * Two primitives, one rule: undo NEVER reverts another participant's (human
+ * or agent) work, and never restores whole-document snapshots that would
+ * clobber concurrent edits.
+ *
+ * - `useCollabUndo` — Y.UndoManager lifecycle wrapper for Yjs-backed surfaces.
+ *   Tracks only transactions tagged with the local origin, coalesces rapid
+ *   edits, and is recreated/destroyed when the document changes (stale
+ *   managers hold Y.Doc references and grow unboundedly).
+ *
+ * - `useLocalOpUndo` / `createLocalOpUndoController` — inverse-operation undo
+ *   for op-based apps (slides decks, forms). Each local mutation registers
+ *   the granular ops that redo and undo it; Cmd+Z replays the inverse ops
+ *   through the app's normal granular mutation path, so concurrent edits by
+ *   other participants to OTHER items are never touched.
+ */
+import * as Y from "yjs";
+export interface UndoKeyboardOptions {
+    /** Bind Mod+Z / Shift+Mod+Z / Mod+Y on window while mounted. */
+    enableKeyboardShortcuts?: boolean;
+    /**
+     * Skip the shortcut when the event target is an input, textarea, or
+     * contentEditable (those own their own undo). Default true.
+     */
+    ignoreInputTargets?: boolean;
+}
+export type CollabUndoScope = Y.AbstractType<any> | Y.AbstractType<any>[] | ((doc: Y.Doc) => Y.AbstractType<any> | Y.AbstractType<any>[]);
+export interface UseCollabUndoOptions extends UndoKeyboardOptions {
+    /** The collaborative document. Null/undefined while loading. */
+    ydoc: Y.Doc | null | undefined;
+    /**
+     * Shared type(s) to track, or a factory receiving the doc (evaluated when
+     * the doc changes) — e.g. `(doc) => doc.getText("content")`.
+     */
+    scope: CollabUndoScope;
+    /**
+     * Origins captured as undoable. Defaults to the hook's own `localOrigin`.
+     * Transactions from remote peers ("remote") and the agent ("agent"/
+     * "server") are never captured.
+     */
+    trackedOrigins?: unknown[];
+    /** Coalesce rapid edits into one undo step. Default 500ms. */
+    captureTimeout?: number;
+}
+export interface UseCollabUndoResult {
+    /** Undo the local user's most recent edit. Returns true if applied. */
+    undo: () => boolean;
+    /** Redo the local user's most recently undone edit. */
+    redo: () => boolean;
+    canUndo: boolean;
+    canRedo: boolean;
+    /**
+     * Tag local transactions with this origin so they're captured:
+     * `ydoc.transact(() => { ... }, localOrigin)` — or use `transactLocal`.
+     */
+    localOrigin: unknown;
+    /** Run a mutation in a transaction tagged with the local origin. */
+    transactLocal: <T>(fn: () => T) => T;
+    /** The underlying manager (null while the doc is loading). */
+    undoManager: Y.UndoManager | null;
+}
+export declare function useCollabUndo(options: UseCollabUndoOptions): UseCollabUndoResult;
+export interface LocalOpUndoEntry<TOp> {
+    /** Granular ops that reverse the mutation. */
+    undo: TOp[];
+    /** Granular ops that re-apply the mutation. */
+    redo: TOp[];
+    /** Optional label for UI ("Delete slide 3"). */
+    label?: string;
+    /**
+     * Coalescing key: consecutive pushes with the same non-empty key within
+     * `coalesceMs` merge into one entry (keeps the FIRST undo ops and the
+     * LATEST redo ops) — e.g. per-keystroke text patches on one field.
+     */
+    coalesceKey?: string;
+}
+export interface LocalOpUndoController<TOp> {
+    /** Record a local mutation. Clears the redo stack. */
+    push(entry: LocalOpUndoEntry<TOp>): void;
+    /** Apply the inverse ops of the most recent entry. */
+    undo(): Promise<boolean>;
+    /** Re-apply the most recently undone entry. */
+    redo(): Promise<boolean>;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    clear(): void;
+    /** Peek labels for UI (undo tooltip). */
+    peekUndoLabel(): string | undefined;
+    peekRedoLabel(): string | undefined;
+}
+export interface CreateLocalOpUndoOptions<TOp> {
+    /**
+     * Apply granular ops through the app's normal mutation path. MUST NOT
+     * push back into this controller (re-entrant pushes are ignored).
+     */
+    apply: (ops: TOp[], direction: "undo" | "redo", entry: LocalOpUndoEntry<TOp>) => void | Promise<void>;
+    /** Max retained entries. Default 200. */
+    maxDepth?: number;
+    /** Window for coalescing same-key pushes. Default 800ms. */
+    coalesceMs?: number;
+    /** Called after any stack change (for canUndo/canRedo UI updates). */
+    onChange?: () => void;
+    /** Clock override for tests. */
+    now?: () => number;
+}
+export declare function createLocalOpUndoController<TOp>(options: CreateLocalOpUndoOptions<TOp>): LocalOpUndoController<TOp>;
+export interface UseLocalOpUndoOptions<TOp> extends Omit<CreateLocalOpUndoOptions<TOp>, "onChange">, UndoKeyboardOptions {
+}
+export interface UseLocalOpUndoResult<TOp> {
+    push: (entry: LocalOpUndoEntry<TOp>) => void;
+    undo: () => Promise<boolean>;
+    redo: () => Promise<boolean>;
+    canUndo: boolean;
+    canRedo: boolean;
+    clear: () => void;
+    controller: LocalOpUndoController<TOp>;
+}
+export declare function useLocalOpUndo<TOp>(options: UseLocalOpUndoOptions<TOp>): UseLocalOpUndoResult<TOp>;
+//# sourceMappingURL=undo.d.ts.map

package/dist/collab/undo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undo.d.ts","sourceRoot":"","sources":["../../src/collab/undo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAMzB,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAgDD,MAAM,MAAM,eAAe,GACvB,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,GACnB,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,GACrB,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAElE,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAC/D,gEAAgE;IAChE,IAAI,EAAE,CAAC,CAAC,GAAG,GAAG,IAAI,GAAG,SAAS,CAAC;IAC/B;;;OAGG;IACH,KAAK,EAAE,eAAe,CAAC;IACvB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,EAAE,CAAC;IAC3B,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,IAAI,EAAE,MAAM,OAAO,CAAC;IACpB,uDAAuD;IACvD,IAAI,EAAE,MAAM,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,oEAAoE;IACpE,aAAa,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IACrC,8DAA8D;IAC9D,WAAW,EAAE,CAAC,CAAC,WAAW,GAAG,IAAI,CAAC;CACnC;AAED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,oBAAoB,GAC5B,mBAAmB,CAmGrB;AAMD,MAAM,WAAW,gBAAgB,CAAC,GAAG;IACnC,8CAA8C;IAC9C,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,+CAA+C;IAC/C,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB,CAAC,GAAG;IACxC,sDAAsD;IACtD,IAAI,CAAC,KAAK,EAAE,gBAAgB,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IACzC,sDAAsD;IACtD,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,+CAA+C;IAC/C,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,OAAO,IAAI,OAAO,CAAC;IACnB,OAAO,IAAI,OAAO,CAAC;IACnB,KAAK,IAAI,IAAI,CAAC;IACd,yCAAyC;IACzC,aAAa,IAAI,MAAM,GAAG,SAAS,CAAC;IACpC,aAAa,IAAI,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,MAAM,WAAW,wBAAwB,CAAC,GAAG;IAC3C;;;OAGG;IACH,KAAK,EAAE,CACL,GAAG,EAAE,GAAG,EAAE,EACV,SAAS,EAAE,MAAM,GAAG,MAAM,EAC1B,KAAK,EAAE,gBAAgB,CAAC,GAAG,CAAC,KACzB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAMD,wBAAgB,2BAA2B,CAAC,GAAG,EAC7C,OAAO,EAAE,wBAAwB,CAAC,GAAG,CAAC,GACrC,qBAAqB,CAAC,GAAG,CAAC,CAoF5B;AAED,MAAM,WAAW,qBAAqB,CAAC,GAAG,CACxC,SACE,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC,EAC/C,mBAAmB;CAAG;AAE1B,MAAM,WAAW,oBAAoB,CAAC,GAAG;IACvC,IAAI,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;IAC7C,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,UAAU,EAAE,qBAAqB,CAAC,GAAG,CAAC,CAAC;CACxC;AAED,wBAAgB,cAAc,CAAC,GAAG,EAChC,OAAO,EAAE,qBAAqB,CAAC,GAAG,CAAC,GAClC,oBAAoB,CAAC,GAAG,CAAC,CA0C3B"}

package/dist/collab/undo.js

@@ -0,0 +1,244 @@
+/**
+ * Shared per-user undo/redo for collaborative surfaces.
+ *
+ * Two primitives, one rule: undo NEVER reverts another participant's (human
+ * or agent) work, and never restores whole-document snapshots that would
+ * clobber concurrent edits.
+ *
+ * - `useCollabUndo` — Y.UndoManager lifecycle wrapper for Yjs-backed surfaces.
+ *   Tracks only transactions tagged with the local origin, coalesces rapid
+ *   edits, and is recreated/destroyed when the document changes (stale
+ *   managers hold Y.Doc references and grow unboundedly).
+ *
+ * - `useLocalOpUndo` / `createLocalOpUndoController` — inverse-operation undo
+ *   for op-based apps (slides decks, forms). Each local mutation registers
+ *   the granular ops that redo and undo it; Cmd+Z replays the inverse ops
+ *   through the app's normal granular mutation path, so concurrent edits by
+ *   other participants to OTHER items are never touched.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import * as Y from "yjs";
+function isEditableTarget(target) {
+    const el = target;
+    if (!el)
+        return false;
+    const tag = el.tagName;
+    return (tag === "INPUT" ||
+        tag === "TEXTAREA" ||
+        tag === "SELECT" ||
+        !!el.isContentEditable);
+}
+function useUndoKeyboard(undo, redo, options) {
+    const enabled = options?.enableKeyboardShortcuts ?? false;
+    const ignoreInputs = options?.ignoreInputTargets ?? true;
+    useEffect(() => {
+        if (!enabled || typeof window === "undefined")
+            return;
+        function onKeyDown(e) {
+            if (!(e.metaKey || e.ctrlKey))
+                return;
+            if (ignoreInputs && isEditableTarget(e.target))
+                return;
+            const key = e.key.toLowerCase();
+            if (key === "z") {
+                e.preventDefault();
+                if (e.shiftKey)
+                    redo();
+                else
+                    undo();
+            }
+            else if (key === "y") {
+                e.preventDefault();
+                redo();
+            }
+        }
+        window.addEventListener("keydown", onKeyDown);
+        return () => window.removeEventListener("keydown", onKeyDown);
+    }, [enabled, ignoreInputs, undo, redo]);
+}
+export function useCollabUndo(options) {
+    const { ydoc, scope, trackedOrigins, captureTimeout = 500 } = options;
+    // Stable per-hook local origin (an object identity — never collides).
+    const localOrigin = useMemo(() => ({ collabUndoLocalOrigin: true }), []);
+    const managerRef = useRef(null);
+    const [canUndo, setCanUndo] = useState(false);
+    const [canRedo, setCanRedo] = useState(false);
+    // Keep latest scope/origins in refs so the effect only re-runs on doc change.
+    const scopeRef = useRef(scope);
+    scopeRef.current = scope;
+    const trackedRef = useRef(trackedOrigins);
+    trackedRef.current = trackedOrigins;
+    useEffect(() => {
+        if (!ydoc) {
+            managerRef.current = null;
+            setCanUndo(false);
+            setCanRedo(false);
+            return;
+        }
+        const rawScope = scopeRef.current;
+        const resolved = typeof rawScope === "function" ? rawScope(ydoc) : rawScope;
+        const scopes = Array.isArray(resolved) ? resolved : [resolved];
+        const origins = new Set(trackedRef.current ?? [localOrigin]);
+        const manager = new Y.UndoManager(scopes, {
+            trackedOrigins: origins,
+            captureTimeout,
+        });
+        // The manager applies undo/redo transactions with itself as origin;
+        // track it so redo of an undone step is capturable.
+        origins.add(manager);
+        managerRef.current = manager;
+        function refresh() {
+            setCanUndo(manager.undoStack.length > 0);
+            setCanRedo(manager.redoStack.length > 0);
+        }
+        refresh();
+        manager.on("stack-item-added", refresh);
+        manager.on("stack-item-popped", refresh);
+        manager.on("stack-cleared", refresh);
+        return () => {
+            manager.off("stack-item-added", refresh);
+            manager.off("stack-item-popped", refresh);
+            manager.off("stack-cleared", refresh);
+            manager.destroy();
+            if (managerRef.current === manager) {
+                managerRef.current = null;
+            }
+        };
+    }, [ydoc, captureTimeout, localOrigin]);
+    const undo = useCallback(() => {
+        const m = managerRef.current;
+        if (!m || m.undoStack.length === 0)
+            return false;
+        m.undo();
+        return true;
+    }, []);
+    const redo = useCallback(() => {
+        const m = managerRef.current;
+        if (!m || m.redoStack.length === 0)
+            return false;
+        m.redo();
+        return true;
+    }, []);
+    const transactLocal = useCallback((fn) => {
+        if (!ydoc)
+            return fn();
+        let result;
+        ydoc.transact(() => {
+            result = fn();
+        }, localOrigin);
+        return result;
+    }, [ydoc, localOrigin]);
+    useUndoKeyboard(undo, redo, options);
+    return {
+        undo,
+        redo,
+        canUndo,
+        canRedo,
+        localOrigin,
+        transactLocal,
+        undoManager: managerRef.current,
+    };
+}
+export function createLocalOpUndoController(options) {
+    const { apply, maxDepth = 200, coalesceMs = 800, onChange, now = () => Date.now(), } = options;
+    const undoStack = [];
+    const redoStack = [];
+    let applying = false;
+    function notify() {
+        onChange?.();
+    }
+    return {
+        push(entry) {
+            // Ignore pushes triggered by our own undo/redo application.
+            if (applying)
+                return;
+            const at = now();
+            const top = undoStack[undoStack.length - 1];
+            if (top &&
+                entry.coalesceKey &&
+                top.coalesceKey === entry.coalesceKey &&
+                at - top.at <= coalesceMs) {
+                // Merge: first undo wins (restores the pre-burst state), latest redo
+                // wins (re-applies the final state).
+                top.redo = entry.redo;
+                top.at = at;
+            }
+            else {
+                undoStack.push({ ...entry, at });
+                if (undoStack.length > maxDepth) {
+                    undoStack.splice(0, undoStack.length - maxDepth);
+                }
+            }
+            redoStack.length = 0;
+            notify();
+        },
+        async undo() {
+            const entry = undoStack.pop();
+            if (!entry)
+                return false;
+            redoStack.push(entry);
+            notify();
+            applying = true;
+            try {
+                await apply(entry.undo, "undo", entry);
+            }
+            finally {
+                applying = false;
+            }
+            return true;
+        },
+        async redo() {
+            const entry = redoStack.pop();
+            if (!entry)
+                return false;
+            undoStack.push(entry);
+            notify();
+            applying = true;
+            try {
+                await apply(entry.redo, "redo", entry);
+            }
+            finally {
+                applying = false;
+            }
+            return true;
+        },
+        canUndo: () => undoStack.length > 0,
+        canRedo: () => redoStack.length > 0,
+        clear() {
+            undoStack.length = 0;
+            redoStack.length = 0;
+            notify();
+        },
+        peekUndoLabel: () => undoStack[undoStack.length - 1]?.label,
+        peekRedoLabel: () => redoStack[redoStack.length - 1]?.label,
+    };
+}
+export function useLocalOpUndo(options) {
+    const [, setTick] = useState(0);
+    const applyRef = useRef(options.apply);
+    applyRef.current = options.apply;
+    const controller = useMemo(() => createLocalOpUndoController({
+        apply: (ops, direction, entry) => applyRef.current(ops, direction, entry),
+        maxDepth: options.maxDepth,
+        coalesceMs: options.coalesceMs,
+        now: options.now,
+        onChange: () => setTick((n) => n + 1),
+    }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []);
+    const undo = useCallback(() => controller.undo(), [controller]);
+    const redo = useCallback(() => controller.redo(), [controller]);
+    const push = useCallback((entry) => controller.push(entry), [controller]);
+    const clear = useCallback(() => controller.clear(), [controller]);
+    useUndoKeyboard(() => void controller.undo(), () => void controller.redo(), options);
+    return {
+        push,
+        undo,
+        redo,
+        canUndo: controller.canUndo(),
+        canRedo: controller.canRedo(),
+        clear,
+        controller,
+    };
+}
+//# sourceMappingURL=undo.js.map

package/dist/collab/undo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"undo.js","sourceRoot":"","sources":["../../src/collab/undo.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared per-user undo/redo for collaborative surfaces.\n *\n * Two primitives, one rule: undo NEVER reverts another participant's (human\n * or agent) work, and never restores whole-document snapshots that would\n * clobber concurrent edits.\n *\n * - `useCollabUndo` — Y.UndoManager lifecycle wrapper for Yjs-backed surfaces.\n *   Tracks only transactions tagged with the local origin, coalesces rapid\n *   edits, and is recreated/destroyed when the document changes (stale\n *   managers hold Y.Doc references and grow unboundedly).\n *\n * - `useLocalOpUndo` / `createLocalOpUndoController` — inverse-operation undo\n *   for op-based apps (slides decks, forms). Each local mutation registers\n *   the granular ops that redo and undo it; Cmd+Z replays the inverse ops\n *   through the app's normal granular mutation path, so concurrent edits by\n *   other participants to OTHER items are never touched.\n */\n\nimport { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport * as Y from \"yjs\";\n\n// ---------------------------------------------------------------------------\n// Keyboard shortcut helper (shared by both hooks)\n// ---------------------------------------------------------------------------\n\nexport interface UndoKeyboardOptions {\n  /** Bind Mod+Z / Shift+Mod+Z / Mod+Y on window while mounted. */\n  enableKeyboardShortcuts?: boolean;\n  /**\n   * Skip the shortcut when the event target is an input, textarea, or\n   * contentEditable (those own their own undo). Default true.\n   */\n  ignoreInputTargets?: boolean;\n}\n\nfunction isEditableTarget(target: EventTarget | null): boolean {\n  const el = target as HTMLElement | null;\n  if (!el) return false;\n  const tag = el.tagName;\n  return (\n    tag === \"INPUT\" ||\n    tag === \"TEXTAREA\" ||\n    tag === \"SELECT\" ||\n    !!el.isContentEditable\n  );\n}\n\nfunction useUndoKeyboard(\n  undo: () => void,\n  redo: () => void,\n  options: UndoKeyboardOptions | undefined,\n): void {\n  const enabled = options?.enableKeyboardShortcuts ?? false;\n  const ignoreInputs = options?.ignoreInputTargets ?? true;\n\n  useEffect(() => {\n    if (!enabled || typeof window === \"undefined\") return;\n\n    function onKeyDown(e: KeyboardEvent) {\n      if (!(e.metaKey || e.ctrlKey)) return;\n      if (ignoreInputs && isEditableTarget(e.target)) return;\n      const key = e.key.toLowerCase();\n      if (key === \"z\") {\n        e.preventDefault();\n        if (e.shiftKey) redo();\n        else undo();\n      } else if (key === \"y\") {\n        e.preventDefault();\n        redo();\n      }\n    }\n\n    window.addEventListener(\"keydown\", onKeyDown);\n    return () => window.removeEventListener(\"keydown\", onKeyDown);\n  }, [enabled, ignoreInputs, undo, redo]);\n}\n\n// ---------------------------------------------------------------------------\n// Yjs-backed undo — useCollabUndo\n// ---------------------------------------------------------------------------\n\nexport type CollabUndoScope =\n  | Y.AbstractType<any>\n  | Y.AbstractType<any>[]\n  | ((doc: Y.Doc) => Y.AbstractType<any> | Y.AbstractType<any>[]);\n\nexport interface UseCollabUndoOptions extends UndoKeyboardOptions {\n  /** The collaborative document. Null/undefined while loading. */\n  ydoc: Y.Doc | null | undefined;\n  /**\n   * Shared type(s) to track, or a factory receiving the doc (evaluated when\n   * the doc changes) — e.g. `(doc) => doc.getText(\"content\")`.\n   */\n  scope: CollabUndoScope;\n  /**\n   * Origins captured as undoable. Defaults to the hook's own `localOrigin`.\n   * Transactions from remote peers (\"remote\") and the agent (\"agent\"/\n   * \"server\") are never captured.\n   */\n  trackedOrigins?: unknown[];\n  /** Coalesce rapid edits into one undo step. Default 500ms. */\n  captureTimeout?: number;\n}\n\nexport interface UseCollabUndoResult {\n  /** Undo the local user's most recent edit. Returns true if applied. */\n  undo: () => boolean;\n  /** Redo the local user's most recently undone edit. */\n  redo: () => boolean;\n  canUndo: boolean;\n  canRedo: boolean;\n  /**\n   * Tag local transactions with this origin so they're captured:\n   * `ydoc.transact(() => { ... }, localOrigin)` — or use `transactLocal`.\n   */\n  localOrigin: unknown;\n  /** Run a mutation in a transaction tagged with the local origin. */\n  transactLocal: <T>(fn: () => T) => T;\n  /** The underlying manager (null while the doc is loading). */\n  undoManager: Y.UndoManager | null;\n}\n\nexport function useCollabUndo(\n  options: UseCollabUndoOptions,\n): UseCollabUndoResult {\n  const { ydoc, scope, trackedOrigins, captureTimeout = 500 } = options;\n\n  // Stable per-hook local origin (an object identity — never collides).\n  const localOrigin = useMemo<unknown>(\n    () => ({ collabUndoLocalOrigin: true }),\n    [],\n  );\n\n  const managerRef = useRef<Y.UndoManager | null>(null);\n  const [canUndo, setCanUndo] = useState(false);\n  const [canRedo, setCanRedo] = useState(false);\n\n  // Keep latest scope/origins in refs so the effect only re-runs on doc change.\n  const scopeRef = useRef(scope);\n  scopeRef.current = scope;\n  const trackedRef = useRef(trackedOrigins);\n  trackedRef.current = trackedOrigins;\n\n  useEffect(() => {\n    if (!ydoc) {\n      managerRef.current = null;\n      setCanUndo(false);\n      setCanRedo(false);\n      return;\n    }\n\n    const rawScope = scopeRef.current;\n    const resolved = typeof rawScope === \"function\" ? rawScope(ydoc) : rawScope;\n    const scopes = Array.isArray(resolved) ? resolved : [resolved];\n\n    const origins = new Set<unknown>(trackedRef.current ?? [localOrigin]);\n    const manager = new Y.UndoManager(scopes, {\n      trackedOrigins: origins,\n      captureTimeout,\n    });\n    // The manager applies undo/redo transactions with itself as origin;\n    // track it so redo of an undone step is capturable.\n    origins.add(manager);\n    managerRef.current = manager;\n\n    function refresh() {\n      setCanUndo(manager.undoStack.length > 0);\n      setCanRedo(manager.redoStack.length > 0);\n    }\n    refresh();\n\n    manager.on(\"stack-item-added\", refresh);\n    manager.on(\"stack-item-popped\", refresh);\n    manager.on(\"stack-cleared\", refresh);\n\n    return () => {\n      manager.off(\"stack-item-added\", refresh);\n      manager.off(\"stack-item-popped\", refresh);\n      manager.off(\"stack-cleared\", refresh);\n      manager.destroy();\n      if (managerRef.current === manager) {\n        managerRef.current = null;\n      }\n    };\n  }, [ydoc, captureTimeout, localOrigin]);\n\n  const undo = useCallback((): boolean => {\n    const m = managerRef.current;\n    if (!m || m.undoStack.length === 0) return false;\n    m.undo();\n    return true;\n  }, []);\n\n  const redo = useCallback((): boolean => {\n    const m = managerRef.current;\n    if (!m || m.redoStack.length === 0) return false;\n    m.redo();\n    return true;\n  }, []);\n\n  const transactLocal = useCallback(\n    <T>(fn: () => T): T => {\n      if (!ydoc) return fn();\n      let result!: T;\n      ydoc.transact(() => {\n        result = fn();\n      }, localOrigin);\n      return result;\n    },\n    [ydoc, localOrigin],\n  );\n\n  useUndoKeyboard(undo, redo, options);\n\n  return {\n    undo,\n    redo,\n    canUndo,\n    canRedo,\n    localOrigin,\n    transactLocal,\n    undoManager: managerRef.current,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Inverse-op undo — createLocalOpUndoController / useLocalOpUndo\n// ---------------------------------------------------------------------------\n\nexport interface LocalOpUndoEntry<TOp> {\n  /** Granular ops that reverse the mutation. */\n  undo: TOp[];\n  /** Granular ops that re-apply the mutation. */\n  redo: TOp[];\n  /** Optional label for UI (\"Delete slide 3\"). */\n  label?: string;\n  /**\n   * Coalescing key: consecutive pushes with the same non-empty key within\n   * `coalesceMs` merge into one entry (keeps the FIRST undo ops and the\n   * LATEST redo ops) — e.g. per-keystroke text patches on one field.\n   */\n  coalesceKey?: string;\n}\n\nexport interface LocalOpUndoController<TOp> {\n  /** Record a local mutation. Clears the redo stack. */\n  push(entry: LocalOpUndoEntry<TOp>): void;\n  /** Apply the inverse ops of the most recent entry. */\n  undo(): Promise<boolean>;\n  /** Re-apply the most recently undone entry. */\n  redo(): Promise<boolean>;\n  canUndo(): boolean;\n  canRedo(): boolean;\n  clear(): void;\n  /** Peek labels for UI (undo tooltip). */\n  peekUndoLabel(): string | undefined;\n  peekRedoLabel(): string | undefined;\n}\n\nexport interface CreateLocalOpUndoOptions<TOp> {\n  /**\n   * Apply granular ops through the app's normal mutation path. MUST NOT\n   * push back into this controller (re-entrant pushes are ignored).\n   */\n  apply: (\n    ops: TOp[],\n    direction: \"undo\" | \"redo\",\n    entry: LocalOpUndoEntry<TOp>,\n  ) => void | Promise<void>;\n  /** Max retained entries. Default 200. */\n  maxDepth?: number;\n  /** Window for coalescing same-key pushes. Default 800ms. */\n  coalesceMs?: number;\n  /** Called after any stack change (for canUndo/canRedo UI updates). */\n  onChange?: () => void;\n  /** Clock override for tests. */\n  now?: () => number;\n}\n\ninterface StampedEntry<TOp> extends LocalOpUndoEntry<TOp> {\n  at: number;\n}\n\nexport function createLocalOpUndoController<TOp>(\n  options: CreateLocalOpUndoOptions<TOp>,\n): LocalOpUndoController<TOp> {\n  const {\n    apply,\n    maxDepth = 200,\n    coalesceMs = 800,\n    onChange,\n    now = () => Date.now(),\n  } = options;\n\n  const undoStack: StampedEntry<TOp>[] = [];\n  const redoStack: StampedEntry<TOp>[] = [];\n  let applying = false;\n\n  function notify() {\n    onChange?.();\n  }\n\n  return {\n    push(entry) {\n      // Ignore pushes triggered by our own undo/redo application.\n      if (applying) return;\n\n      const at = now();\n      const top = undoStack[undoStack.length - 1];\n      if (\n        top &&\n        entry.coalesceKey &&\n        top.coalesceKey === entry.coalesceKey &&\n        at - top.at <= coalesceMs\n      ) {\n        // Merge: first undo wins (restores the pre-burst state), latest redo\n        // wins (re-applies the final state).\n        top.redo = entry.redo;\n        top.at = at;\n      } else {\n        undoStack.push({ ...entry, at });\n        if (undoStack.length > maxDepth) {\n          undoStack.splice(0, undoStack.length - maxDepth);\n        }\n      }\n      redoStack.length = 0;\n      notify();\n    },\n\n    async undo() {\n      const entry = undoStack.pop();\n      if (!entry) return false;\n      redoStack.push(entry);\n      notify();\n      applying = true;\n      try {\n        await apply(entry.undo, \"undo\", entry);\n      } finally {\n        applying = false;\n      }\n      return true;\n    },\n\n    async redo() {\n      const entry = redoStack.pop();\n      if (!entry) return false;\n      undoStack.push(entry);\n      notify();\n      applying = true;\n      try {\n        await apply(entry.redo, \"redo\", entry);\n      } finally {\n        applying = false;\n      }\n      return true;\n    },\n\n    canUndo: () => undoStack.length > 0,\n    canRedo: () => redoStack.length > 0,\n\n    clear() {\n      undoStack.length = 0;\n      redoStack.length = 0;\n      notify();\n    },\n\n    peekUndoLabel: () => undoStack[undoStack.length - 1]?.label,\n    peekRedoLabel: () => redoStack[redoStack.length - 1]?.label,\n  };\n}\n\nexport interface UseLocalOpUndoOptions<TOp>\n  extends\n    Omit<CreateLocalOpUndoOptions<TOp>, \"onChange\">,\n    UndoKeyboardOptions {}\n\nexport interface UseLocalOpUndoResult<TOp> {\n  push: (entry: LocalOpUndoEntry<TOp>) => void;\n  undo: () => Promise<boolean>;\n  redo: () => Promise<boolean>;\n  canUndo: boolean;\n  canRedo: boolean;\n  clear: () => void;\n  controller: LocalOpUndoController<TOp>;\n}\n\nexport function useLocalOpUndo<TOp>(\n  options: UseLocalOpUndoOptions<TOp>,\n): UseLocalOpUndoResult<TOp> {\n  const [, setTick] = useState(0);\n  const applyRef = useRef(options.apply);\n  applyRef.current = options.apply;\n\n  const controller = useMemo(\n    () =>\n      createLocalOpUndoController<TOp>({\n        apply: (ops, direction, entry) =>\n          applyRef.current(ops, direction, entry),\n        maxDepth: options.maxDepth,\n        coalesceMs: options.coalesceMs,\n        now: options.now,\n        onChange: () => setTick((n) => n + 1),\n      }),\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [],\n  );\n\n  const undo = useCallback(() => controller.undo(), [controller]);\n  const redo = useCallback(() => controller.redo(), [controller]);\n  const push = useCallback(\n    (entry: LocalOpUndoEntry<TOp>) => controller.push(entry),\n    [controller],\n  );\n  const clear = useCallback(() => controller.clear(), [controller]);\n\n  useUndoKeyboard(\n    () => void controller.undo(),\n    () => void controller.redo(),\n    options,\n  );\n\n  return {\n    push,\n    undo,\n    redo,\n    canUndo: controller.canUndo(),\n    canRedo: controller.canRedo(),\n    clear,\n    controller,\n  };\n}\n"]}

package/dist/collab/ydoc-manager.d.ts

@@ -16,6 +16,16 @@
  */
 import * as Y from "yjs";
 import { type PatchOp } from "./json-to-yjs.js";
+/**
+ * Compute a small "what changed" descriptor from a text diff by trimming the
+ * common prefix/suffix. Used for lingering edit highlights client-side.
+ */
+export declare function computeTextEditDescriptor(oldText: string, newText: string): {
+    kind: "text";
+    quote: string;
+} | {
+    kind: "doc";
+};
 /**
  * Get or load a Yjs document by ID. Creates a new empty doc if none exists.
  */

package/dist/collab/ydoc-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ydoc-manager.d.ts","sourceRoot":"","sources":["../../src/collab/ydoc-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAGzB,OAAO,EAKL,KAAK,OAAO,EACb,MAAM,kBAAkB,CAAC;AAmI1B;;GAEG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAoC1D;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,UAAU,EAClB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,MAAsB,EACjC,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,MAAM,CAAC,CAgBjB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC,CA4BjD;AAED;;GAEG;AACH,wBAAsB,OAAO,CAC3B,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,MAAsB,GAChC,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAGjE;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,iBAAiB,EAAE,UAAU,GAC5B,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAAsB,GAChC,OAAO,CAAC,IAAI,CAAC,CAYf;AAID;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,GAAG,EACZ,SAAS,GAAE,MAAe,EAC1B,KAAK,GAAE,KAAK,GAAG,OAAe,EAC9B,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,OAAO,EAAE,EACd,SAAS,GAAE,MAAe,EAC1B,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;GAEG;AACH,wBAAsB,OAAO,CAC3B,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,MAAe,GACzB,OAAO,CAAC,GAAG,CAAC,CAGd;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,GAAG,EACT,SAAS,GAAE,MAAe,EAC1B,IAAI,GAAE,KAAK,GAAG,OAAe,GAC5B,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAM9C"}
+{"version":3,"file":"ydoc-manager.d.ts","sourceRoot":"","sources":["../../src/collab/ydoc-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAGzB,OAAO,EAKL,KAAK,OAAO,EACb,MAAM,kBAAkB,CAAC;AAmC1B;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,CAqBnD;AAuHD;;GAEG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAoC1D;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,UAAU,EAClB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,MAAsB,EACjC,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,MAAM,CAAC,CAoBjB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC,CAkCjD;AAED;;GAEG;AACH,wBAAsB,OAAO,CAC3B,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,MAAsB,GAChC,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAGjE;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,iBAAiB,EAAE,UAAU,GAC5B,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAAsB,GAChC,OAAO,CAAC,IAAI,CAAC,CAYf;AAID;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,GAAG,EACZ,SAAS,GAAE,MAAe,EAC1B,KAAK,GAAE,KAAK,GAAG,OAAe,EAC9B,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,OAAO,EAAE,EACd,SAAS,GAAE,MAAe,EAC1B,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;GAEG;AACH,wBAAsB,OAAO,CAC3B,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,MAAe,GACzB,OAAO,CAAC,GAAG,CAAC,CAGd;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,GAAG,EACT,SAAS,GAAE,MAAe,EAC1B,IAAI,GAAE,KAAK,GAAG,OAAe,GAC5B,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAM9C"}

package/dist/collab/ydoc-manager.js

@@ -23,6 +23,46 @@ import { applyTextToYDoc, initYDocWithText } from "./text-to-yjs.js";
 import { searchAndReplaceInYXml, extractTextFromYXml } from "./xml-ops.js";
 const DEFAULT_FIELD = "content";
 const MAX_CACHE = 50;
+/**
+ * Auto-presence: any agent-sourced write produces visible presence and
+ * lingering edit attribution without the calling action having to wire
+ * agentEnterDocument/agentLeaveDocument itself. Dynamic import avoids a
+ * static cycle (agent-presence.ts imports searchAndReplace from this module).
+ */
+function touchAgentPresence(docId, requestSource, edit) {
+    if (requestSource !== "agent")
+        return;
+    import("./agent-presence.js")
+        .then((mod) => {
+        mod.agentTouchDocument(docId, edit ? { edit: edit } : undefined);
+    })
+        .catch(() => {
+        // Presence is best-effort; never fail the write for it.
+    });
+}
+/**
+ * Compute a small "what changed" descriptor from a text diff by trimming the
+ * common prefix/suffix. Used for lingering edit highlights client-side.
+ */
+export function computeTextEditDescriptor(oldText, newText) {
+    let start = 0;
+    const maxStart = Math.min(oldText.length, newText.length);
+    while (start < maxStart && oldText[start] === newText[start])
+        start++;
+    let endOld = oldText.length;
+    let endNew = newText.length;
+    while (endOld > start &&
+        endNew > start &&
+        oldText[endOld - 1] === newText[endNew - 1]) {
+        endOld--;
+        endNew--;
+    }
+    const inserted = newText.slice(start, endNew).trim();
+    if (inserted.length > 0) {
+        return { kind: "text", quote: inserted.slice(0, 120) };
+    }
+    return { kind: "doc" };
+}
 /**
  * Compaction ratio threshold. When the stored state byte count exceeds
  * COMPACTION_RATIO × the freshly encoded state, write the compact form
@@ -176,12 +216,16 @@ export async function applyUpdate(docId, update, requestSource) {
 export async function applyText(docId, newText, fieldName = DEFAULT_FIELD, requestSource) {
     return withDocWriteLock(docId, async () => {
         const doc = await getDoc(docId);
+        const oldText = doc.getText(fieldName).toString();
         const update = applyTextToYDoc(doc, fieldName, newText, "server");
         if (update.length === 0) {
             return doc.getText(fieldName).toString();
         }
         await persistMergedState(docId, doc, () => doc.getText(fieldName).toString());
         emitCollabUpdate(docId, uint8ArrayToBase64(update), requestSource);
+        touchAgentPresence(docId, requestSource, {
+            descriptor: computeTextEditDescriptor(oldText, newText),
+        });
         return doc.getText(fieldName).toString();
     });
 }
@@ -211,6 +255,12 @@ export async function searchAndReplace(docId, find, replace, requestSource) {
         }
         await persistMergedState(docId, doc, () => extractTextFromYXml(fragment));
         emitCollabUpdate(docId, uint8ArrayToBase64(update), requestSource);
+        touchAgentPresence(docId, requestSource, {
+            descriptor: {
+                kind: "text",
+                quote: (replace || find).slice(0, 120),
+            },
+        });
         return { found: true, update };
     });
 }
@@ -267,6 +317,7 @@ export async function applyJson(docId, newJson, fieldName = "data", _type = "map
         // concurrent writes, so `newJson` can be stale. Matches applyPatchOps.
         await persistMergedState(docId, doc, () => JSON.stringify(yDocToJson(doc, fieldName)));
         emitCollabUpdate(docId, uint8ArrayToBase64(update), requestSource);
+        touchAgentPresence(docId, requestSource, { descriptor: { kind: "doc" } });
     });
 }
 /**
@@ -280,6 +331,12 @@ export async function applyPatchOps(docId, ops, fieldName = "data", requestSourc
             return;
         await persistMergedState(docId, doc, () => JSON.stringify(yDocToJson(doc, fieldName)));
         emitCollabUpdate(docId, uint8ArrayToBase64(update), requestSource);
+        touchAgentPresence(docId, requestSource, {
+            descriptor: {
+                kind: "paths",
+                paths: ops.slice(0, 5).map((op) => op.path),
+            },
+        });
     });
 }
 /**