@agent-native/core 0.85.7 → 0.86.0

package/dist/collab/recent-edits.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Recent-edit attribution for collaborative documents.
+ *
+ * Every participant (human or agent) may publish a short ring of recent edits
+ * in its awareness state under the `recentEdits` key. Clients render these as
+ * lingering, fading highlights ("Google Docs / Figma collaborator just edited
+ * this") for a few seconds after the edit lands, with the editor's name and
+ * color next to the highlighted region.
+ *
+ * The descriptor is intentionally open-ended — each app publishes whatever its
+ * surfaces can resolve back to a DOM rect:
+ *   - `{ kind: "text", quote }`         rich-text apps resolve by text search
+ *   - `{ kind: "selector", selector }`  canvas/DOM apps resolve by querySelector
+ *   - `{ kind: "paths", paths }`        structured apps resolve JSON paths
+ *     (e.g. `slides.3.content`) to their rendered element
+ *   - `{ kind: "doc" }`                 whole-document change (no region)
+ */
+import type { OtherPresence } from "./presence.js";
+export type RecentEditDescriptor = {
+    kind: "text";
+    quote: string;
+} | {
+    kind: "selector";
+    selector: string;
+} | {
+    kind: "paths";
+    paths: string[];
+} | {
+    kind: "doc";
+} | {
+    kind: string;
+    [key: string]: unknown;
+};
+export interface RecentEdit {
+    descriptor: RecentEditDescriptor;
+    /** Short human-readable label, e.g. "Rewrote intro" or "Slide 3". */
+    label?: string;
+    /** Epoch ms when the edit landed. */
+    at: number;
+}
+/** A recent edit attributed to the participant who made it. */
+export interface AttributedRecentEdit extends RecentEdit {
+    clientId: number;
+    user: OtherPresence["user"];
+    isAgent: boolean;
+}
+/** Max entries kept in a participant's recentEdits ring. */
+export declare const RECENT_EDITS_MAX = 5;
+/**
+ * Default time a recent-edit highlight stays visible, measured from the
+ * edit's `at` timestamp. Awareness delivery adds up to ~3s (poll cadence),
+ * and some actions do post-write work before a viewer looks, so this is
+ * deliberately generous — the fade consumes the final 40% of the window.
+ */
+export declare const RECENT_EDIT_TTL_MS = 10000;
+/**
+ * Append an edit to a recentEdits ring, keeping the newest
+ * {@link RECENT_EDITS_MAX} entries. Pure — returns a new array.
+ */
+export declare function appendRecentEdit(existing: RecentEdit[] | undefined, edit: RecentEdit): RecentEdit[];
+/**
+ * Flatten non-expired recent edits from remote participants, newest last.
+ * Pure — exported for tests and non-React consumers.
+ */
+export declare function collectRecentEdits(others: OtherPresence[], ttlMs: number, now: number): AttributedRecentEdit[];
+export interface UseRecentEditsOptions {
+    /** How long a highlight lingers after the edit. Default 6000ms. */
+    ttlMs?: number;
+}
+/**
+ * Reactive list of remote participants' recent edits that haven't expired.
+ * Ticks internally (~500ms) while any highlight is visible so consumers can
+ * render a smooth fade-out without wiring their own timers.
+ */
+export declare function useRecentEdits(others: OtherPresence[], options?: UseRecentEditsOptions): AttributedRecentEdit[];
+/**
+ * Publish a local edit into this client's awareness ring so peers render a
+ * lingering highlight for it. Call from app mutation paths (throttled by the
+ * ring size + TTL; safe to call per committed edit, not per keystroke).
+ */
+export declare function publishRecentEdit(awareness: {
+    getLocalState: () => Record<string, unknown> | null;
+    setLocalStateField: (field: string, value: unknown) => void;
+}, edit: Omit<RecentEdit, "at"> & {
+    at?: number;
+}): void;
+//# sourceMappingURL=recent-edits.d.ts.map

package/dist/collab/recent-edits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recent-edits.d.ts","sourceRoot":"","sources":["../../src/collab/recent-edits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAE7C,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,oBAAoB,CAAC;IACjC,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,+DAA+D;AAC/D,MAAM,WAAW,oBAAqB,SAAQ,UAAU;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,UAAU,EAAE,GAAG,SAAS,EAClC,IAAI,EAAE,UAAU,GACf,UAAU,EAAE,CAOd;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EAAE,EACvB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV,oBAAoB,EAAE,CAmBxB;AAED,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EAAE,EACvB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,oBAAoB,EAAE,CA0BxB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE;IACT,aAAa,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACpD,kBAAkB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7D,EACD,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,IAAI,CAON"}

package/dist/collab/recent-edits.js

@@ -0,0 +1,116 @@
+/**
+ * Recent-edit attribution for collaborative documents.
+ *
+ * Every participant (human or agent) may publish a short ring of recent edits
+ * in its awareness state under the `recentEdits` key. Clients render these as
+ * lingering, fading highlights ("Google Docs / Figma collaborator just edited
+ * this") for a few seconds after the edit lands, with the editor's name and
+ * color next to the highlighted region.
+ *
+ * The descriptor is intentionally open-ended — each app publishes whatever its
+ * surfaces can resolve back to a DOM rect:
+ *   - `{ kind: "text", quote }`         rich-text apps resolve by text search
+ *   - `{ kind: "selector", selector }`  canvas/DOM apps resolve by querySelector
+ *   - `{ kind: "paths", paths }`        structured apps resolve JSON paths
+ *     (e.g. `slides.3.content`) to their rendered element
+ *   - `{ kind: "doc" }`                 whole-document change (no region)
+ */
+import { useEffect, useRef, useState } from "react";
+/** Max entries kept in a participant's recentEdits ring. */
+export const RECENT_EDITS_MAX = 5;
+/**
+ * Default time a recent-edit highlight stays visible, measured from the
+ * edit's `at` timestamp. Awareness delivery adds up to ~3s (poll cadence),
+ * and some actions do post-write work before a viewer looks, so this is
+ * deliberately generous — the fade consumes the final 40% of the window.
+ */
+export const RECENT_EDIT_TTL_MS = 10_000;
+/**
+ * Append an edit to a recentEdits ring, keeping the newest
+ * {@link RECENT_EDITS_MAX} entries. Pure — returns a new array.
+ */
+export function appendRecentEdit(existing, edit) {
+    const ring = Array.isArray(existing) ? existing.slice() : [];
+    ring.push(edit);
+    if (ring.length > RECENT_EDITS_MAX) {
+        ring.splice(0, ring.length - RECENT_EDITS_MAX);
+    }
+    return ring;
+}
+/**
+ * Flatten non-expired recent edits from remote participants, newest last.
+ * Pure — exported for tests and non-React consumers.
+ */
+export function collectRecentEdits(others, ttlMs, now) {
+    const result = [];
+    for (const other of others) {
+        const ring = other.presence["recentEdits"];
+        if (!Array.isArray(ring))
+            continue;
+        for (const raw of ring) {
+            const edit = raw;
+            if (!edit || typeof edit.at !== "number" || !edit.descriptor)
+                continue;
+            if (now - edit.at > ttlMs)
+                continue;
+            result.push({
+                ...edit,
+                clientId: other.clientId,
+                user: other.user,
+                isAgent: other.isAgent,
+            });
+        }
+    }
+    result.sort((a, b) => a.at - b.at);
+    return result;
+}
+/**
+ * Reactive list of remote participants' recent edits that haven't expired.
+ * Ticks internally (~500ms) while any highlight is visible so consumers can
+ * render a smooth fade-out without wiring their own timers.
+ */
+export function useRecentEdits(others, options) {
+    const ttlMs = options?.ttlMs ?? RECENT_EDIT_TTL_MS;
+    const [edits, setEdits] = useState([]);
+    const othersRef = useRef(others);
+    othersRef.current = others;
+    useEffect(() => {
+        let timer = null;
+        function tick() {
+            const next = collectRecentEdits(othersRef.current, ttlMs, Date.now());
+            setEdits((prev) => (recentEditsEqual(prev, next) ? prev : next));
+            if (next.length > 0) {
+                timer = setTimeout(tick, 500);
+            }
+            else {
+                timer = null;
+            }
+        }
+        tick();
+        return () => {
+            if (timer)
+                clearTimeout(timer);
+        };
+    }, [others, ttlMs]);
+    return edits;
+}
+/**
+ * Publish a local edit into this client's awareness ring so peers render a
+ * lingering highlight for it. Call from app mutation paths (throttled by the
+ * ring size + TTL; safe to call per committed edit, not per keystroke).
+ */
+export function publishRecentEdit(awareness, edit) {
+    const local = awareness.getLocalState();
+    const existing = local?.["recentEdits"];
+    awareness.setLocalStateField("recentEdits", appendRecentEdit(existing, { ...edit, at: edit.at ?? Date.now() }));
+}
+function recentEditsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i].clientId !== b[i].clientId || a[i].at !== b[i].at)
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=recent-edits.js.map

package/dist/collab/recent-edits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recent-edits.js","sourceRoot":"","sources":["../../src/collab/recent-edits.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Recent-edit attribution for collaborative documents.\n *\n * Every participant (human or agent) may publish a short ring of recent edits\n * in its awareness state under the `recentEdits` key. Clients render these as\n * lingering, fading highlights (\"Google Docs / Figma collaborator just edited\n * this\") for a few seconds after the edit lands, with the editor's name and\n * color next to the highlighted region.\n *\n * The descriptor is intentionally open-ended — each app publishes whatever its\n * surfaces can resolve back to a DOM rect:\n *   - `{ kind: \"text\", quote }`         rich-text apps resolve by text search\n *   - `{ kind: \"selector\", selector }`  canvas/DOM apps resolve by querySelector\n *   - `{ kind: \"paths\", paths }`        structured apps resolve JSON paths\n *     (e.g. `slides.3.content`) to their rendered element\n *   - `{ kind: \"doc\" }`                 whole-document change (no region)\n */\n\nimport { useEffect, useRef, useState } from \"react\";\n\nimport type { OtherPresence } from \"./presence.js\";\n\nexport type RecentEditDescriptor =\n  | { kind: \"text\"; quote: string }\n  | { kind: \"selector\"; selector: string }\n  | { kind: \"paths\"; paths: string[] }\n  | { kind: \"doc\" }\n  | { kind: string; [key: string]: unknown };\n\nexport interface RecentEdit {\n  descriptor: RecentEditDescriptor;\n  /** Short human-readable label, e.g. \"Rewrote intro\" or \"Slide 3\". */\n  label?: string;\n  /** Epoch ms when the edit landed. */\n  at: number;\n}\n\n/** A recent edit attributed to the participant who made it. */\nexport interface AttributedRecentEdit extends RecentEdit {\n  clientId: number;\n  user: OtherPresence[\"user\"];\n  isAgent: boolean;\n}\n\n/** Max entries kept in a participant's recentEdits ring. */\nexport const RECENT_EDITS_MAX = 5;\n\n/**\n * Default time a recent-edit highlight stays visible, measured from the\n * edit's `at` timestamp. Awareness delivery adds up to ~3s (poll cadence),\n * and some actions do post-write work before a viewer looks, so this is\n * deliberately generous — the fade consumes the final 40% of the window.\n */\nexport const RECENT_EDIT_TTL_MS = 10_000;\n\n/**\n * Append an edit to a recentEdits ring, keeping the newest\n * {@link RECENT_EDITS_MAX} entries. Pure — returns a new array.\n */\nexport function appendRecentEdit(\n  existing: RecentEdit[] | undefined,\n  edit: RecentEdit,\n): RecentEdit[] {\n  const ring = Array.isArray(existing) ? existing.slice() : [];\n  ring.push(edit);\n  if (ring.length > RECENT_EDITS_MAX) {\n    ring.splice(0, ring.length - RECENT_EDITS_MAX);\n  }\n  return ring;\n}\n\n/**\n * Flatten non-expired recent edits from remote participants, newest last.\n * Pure — exported for tests and non-React consumers.\n */\nexport function collectRecentEdits(\n  others: OtherPresence[],\n  ttlMs: number,\n  now: number,\n): AttributedRecentEdit[] {\n  const result: AttributedRecentEdit[] = [];\n  for (const other of others) {\n    const ring = other.presence[\"recentEdits\"];\n    if (!Array.isArray(ring)) continue;\n    for (const raw of ring) {\n      const edit = raw as RecentEdit;\n      if (!edit || typeof edit.at !== \"number\" || !edit.descriptor) continue;\n      if (now - edit.at > ttlMs) continue;\n      result.push({\n        ...edit,\n        clientId: other.clientId,\n        user: other.user,\n        isAgent: other.isAgent,\n      });\n    }\n  }\n  result.sort((a, b) => a.at - b.at);\n  return result;\n}\n\nexport interface UseRecentEditsOptions {\n  /** How long a highlight lingers after the edit. Default 6000ms. */\n  ttlMs?: number;\n}\n\n/**\n * Reactive list of remote participants' recent edits that haven't expired.\n * Ticks internally (~500ms) while any highlight is visible so consumers can\n * render a smooth fade-out without wiring their own timers.\n */\nexport function useRecentEdits(\n  others: OtherPresence[],\n  options?: UseRecentEditsOptions,\n): AttributedRecentEdit[] {\n  const ttlMs = options?.ttlMs ?? RECENT_EDIT_TTL_MS;\n  const [edits, setEdits] = useState<AttributedRecentEdit[]>([]);\n  const othersRef = useRef(others);\n  othersRef.current = others;\n\n  useEffect(() => {\n    let timer: ReturnType<typeof setTimeout> | null = null;\n\n    function tick() {\n      const next = collectRecentEdits(othersRef.current, ttlMs, Date.now());\n      setEdits((prev) => (recentEditsEqual(prev, next) ? prev : next));\n      if (next.length > 0) {\n        timer = setTimeout(tick, 500);\n      } else {\n        timer = null;\n      }\n    }\n\n    tick();\n    return () => {\n      if (timer) clearTimeout(timer);\n    };\n  }, [others, ttlMs]);\n\n  return edits;\n}\n\n/**\n * Publish a local edit into this client's awareness ring so peers render a\n * lingering highlight for it. Call from app mutation paths (throttled by the\n * ring size + TTL; safe to call per committed edit, not per keystroke).\n */\nexport function publishRecentEdit(\n  awareness: {\n    getLocalState: () => Record<string, unknown> | null;\n    setLocalStateField: (field: string, value: unknown) => void;\n  },\n  edit: Omit<RecentEdit, \"at\"> & { at?: number },\n): void {\n  const local = awareness.getLocalState();\n  const existing = local?.[\"recentEdits\"] as RecentEdit[] | undefined;\n  awareness.setLocalStateField(\n    \"recentEdits\",\n    appendRecentEdit(existing, { ...edit, at: edit.at ?? Date.now() }),\n  );\n}\n\nfunction recentEditsEqual(\n  a: AttributedRecentEdit[],\n  b: AttributedRecentEdit[],\n): boolean {\n  if (a.length !== b.length) return false;\n  for (let i = 0; i < a.length; i++) {\n    if (a[i].clientId !== b[i].clientId || a[i].at !== b[i].at) return false;\n  }\n  return true;\n}\n"]}

package/dist/collab/routes.d.ts

@@ -26,8 +26,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
  * Body: { update: string (base64), requestSource?: string }
  */
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;
@@ -41,9 +41,9 @@ export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import
  * Body: { text: string, fieldName?: string, requestSource?: string }
  */
 export declare const postCollabText: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    text?: undefined;
     ok?: undefined;
     error: string;
+    text?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/collab/struct-routes.d.ts

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

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":"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"}

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