@agent-native/core 0.37.3 → 0.39.0

package/dist/client/rich-markdown-editor/useCollabReconcile.js

@@ -0,0 +1,375 @@
+import { useEffect, useRef, useState } from "react";
+import { isChangeOrigin } from "@tiptap/extension-collaboration";
+import { isReconcileLeadClient } from "../../collab/client.js";
+import { AGENT_CLIENT_ID } from "../../collab/agent-identity.js";
+/** Reads the current markdown out of the tiptap-markdown storage. */
+export function getEditorMarkdown(editor) {
+    const markdownStorage = editor.storage;
+    return markdownStorage.markdown?.getMarkdown?.() ?? "";
+}
+/**
+ * Push a value onto the bounded ring of recently-emitted markdown (most recent
+ * last, deduped, capped). The reconcile uses this to recognize a stale-but-recent
+ * echo of OUR OWN edits: a debounced autosave can persist a PARTIAL burst, and
+ * the next poll re-supplies that partial value with a newer timestamp — applying
+ * it would clobber the freshly-typed tail. An external change (agent/peer) never
+ * byte-matches one of our own recent emissions, and if it somehow did the content
+ * is identical, so skipping it is safe by construction.
+ */
+const EMITTED_RING_MAX = 16;
+function pushEmittedRing(ring, value) {
+    if (!value)
+        return;
+    if (ring[ring.length - 1] === value)
+        return;
+    const dupe = ring.indexOf(value);
+    if (dupe !== -1)
+        ring.splice(dupe, 1);
+    ring.push(value);
+    if (ring.length > EMITTED_RING_MAX)
+        ring.shift();
+}
+/**
+ * The subtle seed / reconcile / lead-client logic for the shared markdown
+ * editor, extracted once so it can never be duplicated across embedders.
+ *
+ * Responsibilities (reproducing the Plan editor's behavior exactly):
+ *  - Track whether THIS client is the reconcile lead (sole client always leads;
+ *    otherwise elected via {@link isReconcileLeadClient}) and how many other
+ *    visible human peers are present.
+ *  - Seed an empty shared Y.Doc once from `value` — lead client only — so two
+ *    clients opening a brand-new block don't both insert the content.
+ *  - Reconcile authoritative external markdown (agent edit, source patch, peer
+ *    edit mirrored to SQL) into the editor: in collab mode only the lead client
+ *    applies it through `setContent` and Yjs propagates; in non-collab mode this
+ *    is the original controlled-value reconcile.
+ *  - Provide the `onUpdate` guards (`shouldIgnoreUpdate`, `registerEmitted`) so
+ *    the component never persists remote-origin or pre-seed empty content.
+ */
+/** Default seed predicate: seed only when the shared doc is genuinely empty. */
+function defaultShouldSeed({ currentMarkdown, fragmentLength, }) {
+    return fragmentLength === 0 || !currentMarkdown.trim();
+}
+/**
+ * Default content writer: hand the raw markdown string to `setContent`, which
+ * tiptap-markdown overrides to parse the markdown into a ProseMirror doc.
+ *
+ * IMPORTANT: do NOT pass `parseOptions: { preserveWhitespace: "full" }` here.
+ * In tiptap v3 the core `setContent` command routes `preserveWhitespace: "full"`
+ * through `insertContentAt`, which tiptap-markdown ALSO overrides to re-run its
+ * markdown parser. That double-parse stringifies the already-parsed PM doc and
+ * re-parses it as HTML, so a clean heading/list/code block comes back as the
+ * escaped, non-idempotent `<h1>…` — which then escalates every reconcile
+ * cycle (`<p>` → `&lt;p&gt;` → `&amp;lt;p&amp;gt;` …). Letting the markdown
+ * override parse the string directly (no `parseOptions`) round-trips byte-stably
+ * for the GFM corpus, including code-block and empty-line whitespace. Content's
+ * NFM path supplies its own `setContent` (it passes a pre-parsed PM doc) and is
+ * unaffected by this default.
+ */
+function defaultSetContent(editor, value, options) {
+    if (options.addToHistory === false) {
+        editor
+            .chain()
+            .command(({ tr }) => {
+            // addToHistory:false so cmd+z (or Yjs undo) doesn't erase
+            // externally-loaded content.
+            tr.setMeta("addToHistory", false);
+            return true;
+        })
+            .setContent(value, { emitUpdate: options.emitUpdate })
+            .run();
+        return;
+    }
+    editor.commands.setContent(value);
+}
+export function useCollabReconcile({ editor, ydoc = null, awareness = null, value, contentUpdatedAt, editable, getMarkdown = getEditorMarkdown, setContent = defaultSetContent, normalizeValue = (v) => v, shouldSeed = defaultShouldSeed, initialAppliedUpdatedAt, }) {
+    const collab = !!ydoc;
+    const isSettingContentRef = useRef(false);
+    const lastEmittedRef = useRef("");
+    // Ring of recent local emissions (see pushEmittedRing). Lets the reconcile
+    // recognize a stale-but-recent echo of our OWN (possibly partial, debounced)
+    // save so a lagging poll never clobbers freshly-typed text.
+    const recentEmittedRef = useRef([]);
+    const lastTypedAtRef = useRef(0);
+    // The raw authoritative `value` string the reconcile last applied. When the
+    // SAME raw string is re-fetched (a lagging poll, or a source-sync that keeps
+    // re-supplying the same stored markdown), applying it again would only
+    // reproduce the doc we already hold — and if `value` is NON-idempotent
+    // (serialize(parse(value)) !== value) re-applying compounds the divergence
+    // every cycle (`<p>` → `&lt;p&gt;` → `&amp;lt;p&amp;gt;` …). Tracked so the
+    // identical re-fetch is recognized and skipped.
+    const lastAppliedValueRef = useRef(null);
+    // The editor's SERIALIZED output captured right AFTER the last reconcile/seed
+    // apply (`getMarkdown(editor)` once the content settled). For non-idempotent
+    // input this is what autosave actually persists, so the NEXT poll hands it
+    // back as the new `value`. Comparing the incoming value against this lets the
+    // reconcile recognize its own echo even when the raw string changed once, so
+    // it never re-parses content the editor already represents. This is the
+    // doc-equivalence guard that breaks the escalation loop.
+    const lastAppliedSerializedRef = useRef(null);
+    const lastAppliedUpdatedAtRef = useRef(initialAppliedUpdatedAt !== undefined
+        ? initialAppliedUpdatedAt
+        : (contentUpdatedAt ?? null));
+    // Whether THIS client is the one that seeds the empty shared doc / applies an
+    // authoritative external snapshot into it. Exactly one client does, so the
+    // content isn't inserted once per open editor. A sole client always leads.
+    const [isLeadClient, setIsLeadClient] = useState(true);
+    // Count of OTHER visible human collaborators. When >0, a peer's edit also
+    // arrives via Yjs, so external markdown reconcile must defer (avoid applying
+    // the same change through both Yjs and setContent).
+    const peerCountRef = useRef(0);
+    useEffect(() => {
+        if (!collab || !awareness || !ydoc) {
+            setIsLeadClient(true);
+            peerCountRef.current = 0;
+            return;
+        }
+        const update = () => {
+            setIsLeadClient(isReconcileLeadClient(awareness, ydoc.clientID));
+            let peers = 0;
+            awareness.getStates().forEach((state, clientId) => {
+                if (clientId === ydoc.clientID)
+                    return; // self
+                if (clientId === AGENT_CLIENT_ID)
+                    return; // agent isn't a Yjs editor
+                const s = state;
+                if (s && s.user && s.visible !== false)
+                    peers += 1;
+            });
+            peerCountRef.current = peers;
+        };
+        update();
+        awareness.on("change", update);
+        document.addEventListener("visibilitychange", update);
+        return () => {
+            awareness.off("change", update);
+            document.removeEventListener("visibilitychange", update);
+        };
+    }, [collab, awareness, ydoc]);
+    // Collab seed: populate an empty shared Y.Doc from the markdown `value` once.
+    // The Collaboration extension does NOT auto-seed; only the lead client does,
+    // so two clients opening a brand-new block at once don't both seed (which
+    // would duplicate the content via concurrent inserts at the same position).
+    const seededRef = useRef(false);
+    useEffect(() => {
+        if (!collab || !editor || editor.isDestroyed || !ydoc)
+            return;
+        if (seededRef.current)
+            return;
+        if (!isLeadClient)
+            return;
+        if (!value.trim())
+            return;
+        const fragment = ydoc.getXmlFragment("default");
+        const currentMarkdown = getMarkdown(editor);
+        // Seed only when the shared doc is genuinely empty — either the fragment has
+        // no nodes yet, or it holds no semantic markdown (an empty paragraph, or an
+        // app's sentinel-empty filler via a custom `shouldSeed`).
+        if (shouldSeed({ value, currentMarkdown, fragmentLength: fragment.length })) {
+            isSettingContentRef.current = true;
+            setContent(editor, value, {});
+            isSettingContentRef.current = false;
+            const serialized = getMarkdown(editor);
+            lastEmittedRef.current = serialized;
+            pushEmittedRing(recentEmittedRef.current, serialized);
+            lastAppliedValueRef.current = value;
+            lastAppliedSerializedRef.current = serialized;
+            if (contentUpdatedAt)
+                lastAppliedUpdatedAtRef.current = contentUpdatedAt;
+        }
+        seededRef.current = true;
+    }, [
+        collab,
+        editor,
+        ydoc,
+        value,
+        isLeadClient,
+        contentUpdatedAt,
+        getMarkdown,
+        setContent,
+        shouldSeed,
+    ]);
+    // Reconcile authoritative external markdown (agent edit, source patch, or a
+    // peer edit mirrored to SQL) into the live editor. In collab mode only the
+    // lead client applies it through setContent; Yjs propagates the result to
+    // every other client. In non-collab mode this is the original controlled-value
+    // reconcile, unchanged.
+    useEffect(() => {
+        if (!editor || editor.isDestroyed)
+            return;
+        let cancelled = false;
+        let retry = null;
+        // With peers present, a peer's edit also arrives via Yjs. Defer one poll
+        // cycle (+margin) and re-check before applying via setContent so the same
+        // change isn't inserted twice (Yjs + setContent → duplicated region).
+        const PEER_SETTLE_MS = 2500;
+        const apply = (deferred = false) => {
+            if (cancelled || editor.isDestroyed)
+                return;
+            // In collab mode, defer all reconcile until the shared doc is seeded so we
+            // never setContent over an unseeded fragment.
+            if (collab && !seededRef.current) {
+                retry = setTimeout(() => apply(deferred), 300);
+                return;
+            }
+            const currentMarkdown = getMarkdown(editor);
+            // Compare against the canonical form the editor would emit so a serializer
+            // that re-normalizes (Content's NFM) still recognizes "already in sync".
+            const normalizedValue = normalizeValue(value);
+            // Whether the editor still holds exactly what THIS hook last applied (the
+            // user hasn't edited since). Only then are the round-trip echo guards
+            // below safe: if the user has since edited away from the applied content,
+            // an external snapshot equal to a previously-applied value is a real
+            // revert and must NOT be swallowed as an echo.
+            const editorUnchangedSinceApply = lastAppliedSerializedRef.current !== null &&
+                currentMarkdown === lastAppliedSerializedRef.current;
+            // Doc-equivalence skip. Never re-apply content the editor already
+            // represents — comparing by DOC EQUIVALENCE, not raw strings/timestamps:
+            //   1. `currentMarkdown === normalizedValue` — the editor's CURRENT
+            //      serialized doc already equals the (normalized) incoming value.
+            //   2. `value === lastEmittedRef.current` — the incoming value is our own
+            //      just-emitted markdown echoing back.
+            //   3. `value === lastAppliedValueRef.current` — the SAME raw value we
+            //      already applied is being re-supplied (a lagging poll or a
+            //      source-sync re-handing the same stored markdown). Applying it again
+            //      would only reproduce the doc we hold; for NON-idempotent input it
+            //      would compound divergence. Guarded by `editorUnchangedSinceApply`
+            //      so a deliberate revert-to-previous after a local edit still lands.
+            //   4. `normalizedValue === lastAppliedSerializedRef.current` — the
+            //      incoming value round-trips to the serialized output we last
+            //      produced (our own autosaved echo coming back from SQL). For
+            //      non-idempotent input the raw string differs from what we were
+            //      handed, but it is doc-equivalent to what the editor already shows,
+            //      so re-parsing it must be skipped. This is the guard that stops the
+            //      `<p>` → `&lt;p&gt;` → `&amp;lt;p&amp;gt;` escalation.
+            if (currentMarkdown === normalizedValue ||
+                value === lastEmittedRef.current ||
+                // A stale-but-recent echo of our own (possibly partial) save — applying
+                // it would clobber the freshly-typed tail. External edits never match.
+                recentEmittedRef.current.includes(value) ||
+                recentEmittedRef.current.includes(normalizedValue) ||
+                (editorUnchangedSinceApply &&
+                    (value === lastAppliedValueRef.current ||
+                        normalizedValue === lastAppliedSerializedRef.current))) {
+                if (contentUpdatedAt) {
+                    lastAppliedUpdatedAtRef.current = contentUpdatedAt;
+                }
+                return;
+            }
+            const externalNewer = !lastAppliedUpdatedAtRef.current ||
+                !contentUpdatedAt ||
+                contentUpdatedAt > lastAppliedUpdatedAtRef.current;
+            // Only the lead client applies an authoritative snapshot into the shared
+            // Y.Doc; peers receive it through Yjs sync.
+            if (collab && !isLeadClient) {
+                if (contentUpdatedAt && !externalNewer) {
+                    lastAppliedUpdatedAtRef.current = contentUpdatedAt;
+                }
+                return;
+            }
+            // Never clobber an in-progress edit. While the user is actively typing
+            // (focused and a keystroke landed within the window) defer and re-check —
+            // applying external content now would yank text out from under them and,
+            // for non-idempotent input, fight every keystroke. Newer external content
+            // retries so it still lands once they pause; older-or-equal content is a
+            // stale poll and is dropped outright while focused.
+            const typingRecently = editor.isFocused && Date.now() - lastTypedAtRef.current < 1500;
+            if (typingRecently) {
+                if (externalNewer) {
+                    retry = setTimeout(() => apply(deferred), 700);
+                }
+                return;
+            }
+            if (!externalNewer && editor.isFocused)
+                return;
+            // Race guard: with peers present, let Yjs deliver a peer's edit first.
+            // Defer once and re-check — a peer edit makes the equality check above
+            // no-op next pass; an agent/source edit still differs and applies.
+            if (collab && externalNewer && !deferred && peerCountRef.current > 0) {
+                retry = setTimeout(() => apply(true), PEER_SETTLE_MS);
+                return;
+            }
+            queueMicrotask(() => {
+                if (cancelled || editor.isDestroyed)
+                    return;
+                // Re-check doc-equivalence at apply time. Between the decision above and
+                // this microtask a peer/Yjs edit (or our own prior apply) may have made
+                // the editor already represent this value — re-applying would be a
+                // wasted setContent that, for non-idempotent input, re-triggers the
+                // loop. Skip when the editor's current serialization already matches the
+                // normalized value, or the value round-trips to what we last produced.
+                const beforeMarkdown = getMarkdown(editor);
+                const normalized = normalizeValue(value);
+                const unchangedSinceApply = lastAppliedSerializedRef.current !== null &&
+                    beforeMarkdown === lastAppliedSerializedRef.current;
+                if (beforeMarkdown === normalized ||
+                    (unchangedSinceApply &&
+                        normalized === lastAppliedSerializedRef.current)) {
+                    lastAppliedValueRef.current = value;
+                    if (contentUpdatedAt) {
+                        lastAppliedUpdatedAtRef.current = contentUpdatedAt;
+                    }
+                    return;
+                }
+                isSettingContentRef.current = true;
+                setContent(editor, value, { emitUpdate: false, addToHistory: false });
+                isSettingContentRef.current = false;
+                // Capture the SERIALIZED result, not the raw value. For non-idempotent
+                // input these differ; recording the serialized output is what lets the
+                // next poll (which returns this serialized form) be recognized as our
+                // own echo and skipped — stabilizing the doc after exactly one apply.
+                const serialized = getMarkdown(editor);
+                lastEmittedRef.current = serialized;
+                pushEmittedRing(recentEmittedRef.current, serialized);
+                lastAppliedValueRef.current = value;
+                lastAppliedSerializedRef.current = serialized;
+                if (contentUpdatedAt) {
+                    lastAppliedUpdatedAtRef.current = contentUpdatedAt;
+                }
+            });
+        };
+        apply();
+        return () => {
+            cancelled = true;
+            if (retry)
+                clearTimeout(retry);
+        };
+    }, [
+        contentUpdatedAt,
+        editor,
+        value,
+        collab,
+        isLeadClient,
+        getMarkdown,
+        setContent,
+        normalizeValue,
+    ]);
+    const shouldIgnoreUpdate = (transaction) => {
+        if (!editable || isSettingContentRef.current)
+            return true;
+        // In collab mode, never persist remote-originated changes (the initial Yjs
+        // state load or a peer's edit arriving via sync). Each client saves only its
+        // OWN local edits; a peer's edit is saved by that peer. Without this, a
+        // lagging Y.Doc load would write stale markdown over newer SQL.
+        if (collab && transaction && isChangeOrigin(transaction))
+            return true;
+        lastTypedAtRef.current = Date.now();
+        return false;
+    };
+    const registerEmitted = (markdown) => {
+        // Don't persist an empty doc before Collaboration has seeded — that would
+        // clobber the saved block content with an empty string.
+        if (collab && !markdown.trim())
+            return false;
+        lastEmittedRef.current = markdown;
+        pushEmittedRing(recentEmittedRef.current, markdown);
+        return true;
+    };
+    return {
+        collab,
+        isSettingContentRef,
+        shouldIgnoreUpdate,
+        registerEmitted,
+    };
+}
+//# sourceMappingURL=useCollabReconcile.js.map

package/dist/client/rich-markdown-editor/useCollabReconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCollabReconcile.js","sourceRoot":"","sources":["../../../src/client/rich-markdown-editor/useCollabReconcile.ts"],"names":[],"mappings":"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","sourcesContent":["import { useEffect, useRef, useState, type MutableRefObject } from \"react\";\nimport type { Editor } from \"@tiptap/react\";\nimport type { Transaction } from \"@tiptap/pm/state\";\nimport { isChangeOrigin } from \"@tiptap/extension-collaboration\";\nimport type { Doc as YDoc } from \"yjs\";\nimport type { Awareness } from \"y-protocols/awareness\";\nimport { isReconcileLeadClient } from \"../../collab/client.js\";\nimport { AGENT_CLIENT_ID } from \"../../collab/agent-identity.js\";\n\n/** Reads the current markdown out of the tiptap-markdown storage. */\nexport function getEditorMarkdown(editor: Editor): string {\n  const markdownStorage = editor.storage as unknown as {\n    markdown?: { getMarkdown?: () => string };\n  };\n  return markdownStorage.markdown?.getMarkdown?.() ?? \"\";\n}\n\n/**\n * Push a value onto the bounded ring of recently-emitted markdown (most recent\n * last, deduped, capped). The reconcile uses this to recognize a stale-but-recent\n * echo of OUR OWN edits: a debounced autosave can persist a PARTIAL burst, and\n * the next poll re-supplies that partial value with a newer timestamp — applying\n * it would clobber the freshly-typed tail. An external change (agent/peer) never\n * byte-matches one of our own recent emissions, and if it somehow did the content\n * is identical, so skipping it is safe by construction.\n */\nconst EMITTED_RING_MAX = 16;\nfunction pushEmittedRing(ring: string[], value: string): void {\n  if (!value) return;\n  if (ring[ring.length - 1] === value) return;\n  const dupe = ring.indexOf(value);\n  if (dupe !== -1) ring.splice(dupe, 1);\n  ring.push(value);\n  if (ring.length > EMITTED_RING_MAX) ring.shift();\n}\n\nexport interface UseCollabReconcileOptions {\n  /** The live editor, or null until it mounts. */\n  editor: Editor | null;\n  /** Shared Y.Doc when collaborating; null disables all collab paths. */\n  ydoc?: YDoc | null;\n  /** Shared awareness; null keeps the sole-client lead path. */\n  awareness?: Awareness | null;\n  /** Authoritative markdown value (SQL source of truth). */\n  value: string;\n  /** Timestamp of the authoritative value; gates newer-than reconcile. */\n  contentUpdatedAt?: string | null;\n  /** Whether the editor accepts edits. Reconcile/seed only run for the live editor. */\n  editable: boolean;\n  /**\n   * Reads the current markdown from the editor. Injected so a dialect could\n   * swap serializers; defaults to the tiptap-markdown storage reader. For an app\n   * with a custom serializer (e.g. Content's `docToNfm(editor.getJSON())`), pass\n   * it here so the seed/reconcile equality checks compare like-for-like.\n   */\n  getMarkdown?: (editor: Editor) => string;\n  /**\n   * Applies the authoritative `value` into the editor. Defaults to passing the\n   * raw markdown string to `editor.commands.setContent`. Apps whose serializer\n   * is NOT tiptap-markdown (Content parses `nfmToDoc(value)` into a PM doc)\n   * override this so seed + reconcile write the correct content shape. The\n   * supplied `options` carry the history/whitespace flags the default path uses;\n   * a custom implementation should forward them when relevant.\n   */\n  setContent?: (\n    editor: Editor,\n    value: string,\n    options: { emitUpdate?: boolean; addToHistory?: boolean },\n  ) => void;\n  /**\n   * Normalizes the authoritative `value` to the canonical markdown the editor\n   * would emit, so the \"already in sync / our own echo\" equality checks match a\n   * serializer that re-canonicalizes (Content's `canonicalizeNfm`). Defaults to\n   * identity (GFM already round-trips byte-stably).\n   */\n  normalizeValue?: (value: string) => string;\n  /**\n   * Decides whether the empty-doc seed should run for the current shared\n   * fragment. Defaults to \"fragment has no nodes, or the editor holds no\n   * semantic markdown\". Apps with sentinel-empty content (Content's\n   * `<empty-block/>` filler) override this. Receives the live fragment length\n   * and the editor's current markdown.\n   */\n  shouldSeed?: (info: {\n    value: string;\n    currentMarkdown: string;\n    fragmentLength: number;\n  }) => boolean;\n  /**\n   * The initial \"applied\" watermark. Default mirrors `contentUpdatedAt`, so a\n   * fresh mount whose Y.Doc already matches SQL doesn't re-apply. Pass `null`\n   * to force the first reconcile pass to adopt authoritative SQL even at the\n   * same timestamp — Content does this so a stale persisted Y.Doc (an agent that\n   * edited the CLOSED doc) is corrected on open. The editor is keyed per\n   * document upstream, so this only affects the first mount of each doc.\n   */\n  initialAppliedUpdatedAt?: string | null;\n}\n\nexport interface UseCollabReconcileResult {\n  /** True when a Y.Doc is bound (collaborative editing active). */\n  collab: boolean;\n  /**\n   * Set true around any programmatic `setContent` so the editor's `onUpdate`\n   * can ignore the resulting transaction (it isn't a user edit).\n   */\n  isSettingContentRef: MutableRefObject<boolean>;\n  /**\n   * Call from `onUpdate` BEFORE serializing. Returns true when the update must\n   * be ignored: editor not editable, mid-programmatic-setContent, or (in collab\n   * mode) a remote-origin transaction. Also records the local typing time.\n   */\n  shouldIgnoreUpdate: (transaction: Transaction) => boolean;\n  /**\n   * Call from `onUpdate` AFTER computing the markdown to emit. Returns false\n   * when the value must NOT be persisted yet (an empty collab doc before the\n   * seed has run); records it as the last-emitted value otherwise.\n   */\n  registerEmitted: (markdown: string) => boolean;\n}\n\n/**\n * The subtle seed / reconcile / lead-client logic for the shared markdown\n * editor, extracted once so it can never be duplicated across embedders.\n *\n * Responsibilities (reproducing the Plan editor's behavior exactly):\n *  - Track whether THIS client is the reconcile lead (sole client always leads;\n *    otherwise elected via {@link isReconcileLeadClient}) and how many other\n *    visible human peers are present.\n *  - Seed an empty shared Y.Doc once from `value` — lead client only — so two\n *    clients opening a brand-new block don't both insert the content.\n *  - Reconcile authoritative external markdown (agent edit, source patch, peer\n *    edit mirrored to SQL) into the editor: in collab mode only the lead client\n *    applies it through `setContent` and Yjs propagates; in non-collab mode this\n *    is the original controlled-value reconcile.\n *  - Provide the `onUpdate` guards (`shouldIgnoreUpdate`, `registerEmitted`) so\n *    the component never persists remote-origin or pre-seed empty content.\n */\n/** Default seed predicate: seed only when the shared doc is genuinely empty. */\nfunction defaultShouldSeed({\n  currentMarkdown,\n  fragmentLength,\n}: {\n  value: string;\n  currentMarkdown: string;\n  fragmentLength: number;\n}): boolean {\n  return fragmentLength === 0 || !currentMarkdown.trim();\n}\n\n/**\n * Default content writer: hand the raw markdown string to `setContent`, which\n * tiptap-markdown overrides to parse the markdown into a ProseMirror doc.\n *\n * IMPORTANT: do NOT pass `parseOptions: { preserveWhitespace: \"full\" }` here.\n * In tiptap v3 the core `setContent` command routes `preserveWhitespace: \"full\"`\n * through `insertContentAt`, which tiptap-markdown ALSO overrides to re-run its\n * markdown parser. That double-parse stringifies the already-parsed PM doc and\n * re-parses it as HTML, so a clean heading/list/code block comes back as the\n * escaped, non-idempotent `&lt;h1&gt;…` — which then escalates every reconcile\n * cycle (`<p>` → `&lt;p&gt;` → `&amp;lt;p&amp;gt;` …). Letting the markdown\n * override parse the string directly (no `parseOptions`) round-trips byte-stably\n * for the GFM corpus, including code-block and empty-line whitespace. Content's\n * NFM path supplies its own `setContent` (it passes a pre-parsed PM doc) and is\n * unaffected by this default.\n */\nfunction defaultSetContent(\n  editor: Editor,\n  value: string,\n  options: { emitUpdate?: boolean; addToHistory?: boolean },\n): void {\n  if (options.addToHistory === false) {\n    editor\n      .chain()\n      .command(({ tr }) => {\n        // addToHistory:false so cmd+z (or Yjs undo) doesn't erase\n        // externally-loaded content.\n        tr.setMeta(\"addToHistory\", false);\n        return true;\n      })\n      .setContent(value, { emitUpdate: options.emitUpdate })\n      .run();\n    return;\n  }\n  editor.commands.setContent(value);\n}\n\nexport function useCollabReconcile({\n  editor,\n  ydoc = null,\n  awareness = null,\n  value,\n  contentUpdatedAt,\n  editable,\n  getMarkdown = getEditorMarkdown,\n  setContent = defaultSetContent,\n  normalizeValue = (v) => v,\n  shouldSeed = defaultShouldSeed,\n  initialAppliedUpdatedAt,\n}: UseCollabReconcileOptions): UseCollabReconcileResult {\n  const collab = !!ydoc;\n  const isSettingContentRef = useRef(false);\n  const lastEmittedRef = useRef(\"\");\n  // Ring of recent local emissions (see pushEmittedRing). Lets the reconcile\n  // recognize a stale-but-recent echo of our OWN (possibly partial, debounced)\n  // save so a lagging poll never clobbers freshly-typed text.\n  const recentEmittedRef = useRef<string[]>([]);\n  const lastTypedAtRef = useRef(0);\n  // The raw authoritative `value` string the reconcile last applied. When the\n  // SAME raw string is re-fetched (a lagging poll, or a source-sync that keeps\n  // re-supplying the same stored markdown), applying it again would only\n  // reproduce the doc we already hold — and if `value` is NON-idempotent\n  // (serialize(parse(value)) !== value) re-applying compounds the divergence\n  // every cycle (`<p>` → `&lt;p&gt;` → `&amp;lt;p&amp;gt;` …). Tracked so the\n  // identical re-fetch is recognized and skipped.\n  const lastAppliedValueRef = useRef<string | null>(null);\n  // The editor's SERIALIZED output captured right AFTER the last reconcile/seed\n  // apply (`getMarkdown(editor)` once the content settled). For non-idempotent\n  // input this is what autosave actually persists, so the NEXT poll hands it\n  // back as the new `value`. Comparing the incoming value against this lets the\n  // reconcile recognize its own echo even when the raw string changed once, so\n  // it never re-parses content the editor already represents. This is the\n  // doc-equivalence guard that breaks the escalation loop.\n  const lastAppliedSerializedRef = useRef<string | null>(null);\n  const lastAppliedUpdatedAtRef = useRef<string | null>(\n    initialAppliedUpdatedAt !== undefined\n      ? initialAppliedUpdatedAt\n      : (contentUpdatedAt ?? null),\n  );\n\n  // Whether THIS client is the one that seeds the empty shared doc / applies an\n  // authoritative external snapshot into it. Exactly one client does, so the\n  // content isn't inserted once per open editor. A sole client always leads.\n  const [isLeadClient, setIsLeadClient] = useState(true);\n  // Count of OTHER visible human collaborators. When >0, a peer's edit also\n  // arrives via Yjs, so external markdown reconcile must defer (avoid applying\n  // the same change through both Yjs and setContent).\n  const peerCountRef = useRef(0);\n  useEffect(() => {\n    if (!collab || !awareness || !ydoc) {\n      setIsLeadClient(true);\n      peerCountRef.current = 0;\n      return;\n    }\n    const update = () => {\n      setIsLeadClient(isReconcileLeadClient(awareness, ydoc.clientID));\n      let peers = 0;\n      awareness.getStates().forEach((state, clientId) => {\n        if (clientId === ydoc.clientID) return; // self\n        if (clientId === AGENT_CLIENT_ID) return; // agent isn't a Yjs editor\n        const s = state as { user?: unknown; visible?: boolean };\n        if (s && s.user && s.visible !== false) peers += 1;\n      });\n      peerCountRef.current = peers;\n    };\n    update();\n    awareness.on(\"change\", update);\n    document.addEventListener(\"visibilitychange\", update);\n    return () => {\n      awareness.off(\"change\", update);\n      document.removeEventListener(\"visibilitychange\", update);\n    };\n  }, [collab, awareness, ydoc]);\n\n  // Collab seed: populate an empty shared Y.Doc from the markdown `value` once.\n  // The Collaboration extension does NOT auto-seed; only the lead client does,\n  // so two clients opening a brand-new block at once don't both seed (which\n  // would duplicate the content via concurrent inserts at the same position).\n  const seededRef = useRef(false);\n  useEffect(() => {\n    if (!collab || !editor || editor.isDestroyed || !ydoc) return;\n    if (seededRef.current) return;\n    if (!isLeadClient) return;\n    if (!value.trim()) return;\n    const fragment = ydoc.getXmlFragment(\"default\");\n    const currentMarkdown = getMarkdown(editor);\n    // Seed only when the shared doc is genuinely empty — either the fragment has\n    // no nodes yet, or it holds no semantic markdown (an empty paragraph, or an\n    // app's sentinel-empty filler via a custom `shouldSeed`).\n    if (\n      shouldSeed({ value, currentMarkdown, fragmentLength: fragment.length })\n    ) {\n      isSettingContentRef.current = true;\n      setContent(editor, value, {});\n      isSettingContentRef.current = false;\n      const serialized = getMarkdown(editor);\n      lastEmittedRef.current = serialized;\n      pushEmittedRing(recentEmittedRef.current, serialized);\n      lastAppliedValueRef.current = value;\n      lastAppliedSerializedRef.current = serialized;\n      if (contentUpdatedAt) lastAppliedUpdatedAtRef.current = contentUpdatedAt;\n    }\n    seededRef.current = true;\n  }, [\n    collab,\n    editor,\n    ydoc,\n    value,\n    isLeadClient,\n    contentUpdatedAt,\n    getMarkdown,\n    setContent,\n    shouldSeed,\n  ]);\n\n  // Reconcile authoritative external markdown (agent edit, source patch, or a\n  // peer edit mirrored to SQL) into the live editor. In collab mode only the\n  // lead client applies it through setContent; Yjs propagates the result to\n  // every other client. In non-collab mode this is the original controlled-value\n  // reconcile, unchanged.\n  useEffect(() => {\n    if (!editor || editor.isDestroyed) return;\n\n    let cancelled = false;\n    let retry: ReturnType<typeof setTimeout> | null = null;\n    // With peers present, a peer's edit also arrives via Yjs. Defer one poll\n    // cycle (+margin) and re-check before applying via setContent so the same\n    // change isn't inserted twice (Yjs + setContent → duplicated region).\n    const PEER_SETTLE_MS = 2500;\n\n    const apply = (deferred = false) => {\n      if (cancelled || editor.isDestroyed) return;\n      // In collab mode, defer all reconcile until the shared doc is seeded so we\n      // never setContent over an unseeded fragment.\n      if (collab && !seededRef.current) {\n        retry = setTimeout(() => apply(deferred), 300);\n        return;\n      }\n      const currentMarkdown = getMarkdown(editor);\n      // Compare against the canonical form the editor would emit so a serializer\n      // that re-normalizes (Content's NFM) still recognizes \"already in sync\".\n      const normalizedValue = normalizeValue(value);\n      // Whether the editor still holds exactly what THIS hook last applied (the\n      // user hasn't edited since). Only then are the round-trip echo guards\n      // below safe: if the user has since edited away from the applied content,\n      // an external snapshot equal to a previously-applied value is a real\n      // revert and must NOT be swallowed as an echo.\n      const editorUnchangedSinceApply =\n        lastAppliedSerializedRef.current !== null &&\n        currentMarkdown === lastAppliedSerializedRef.current;\n\n      // Doc-equivalence skip. Never re-apply content the editor already\n      // represents — comparing by DOC EQUIVALENCE, not raw strings/timestamps:\n      //   1. `currentMarkdown === normalizedValue` — the editor's CURRENT\n      //      serialized doc already equals the (normalized) incoming value.\n      //   2. `value === lastEmittedRef.current` — the incoming value is our own\n      //      just-emitted markdown echoing back.\n      //   3. `value === lastAppliedValueRef.current` — the SAME raw value we\n      //      already applied is being re-supplied (a lagging poll or a\n      //      source-sync re-handing the same stored markdown). Applying it again\n      //      would only reproduce the doc we hold; for NON-idempotent input it\n      //      would compound divergence. Guarded by `editorUnchangedSinceApply`\n      //      so a deliberate revert-to-previous after a local edit still lands.\n      //   4. `normalizedValue === lastAppliedSerializedRef.current` — the\n      //      incoming value round-trips to the serialized output we last\n      //      produced (our own autosaved echo coming back from SQL). For\n      //      non-idempotent input the raw string differs from what we were\n      //      handed, but it is doc-equivalent to what the editor already shows,\n      //      so re-parsing it must be skipped. This is the guard that stops the\n      //      `<p>` → `&lt;p&gt;` → `&amp;lt;p&amp;gt;` escalation.\n      if (\n        currentMarkdown === normalizedValue ||\n        value === lastEmittedRef.current ||\n        // A stale-but-recent echo of our own (possibly partial) save — applying\n        // it would clobber the freshly-typed tail. External edits never match.\n        recentEmittedRef.current.includes(value) ||\n        recentEmittedRef.current.includes(normalizedValue) ||\n        (editorUnchangedSinceApply &&\n          (value === lastAppliedValueRef.current ||\n            normalizedValue === lastAppliedSerializedRef.current))\n      ) {\n        if (contentUpdatedAt) {\n          lastAppliedUpdatedAtRef.current = contentUpdatedAt;\n        }\n        return;\n      }\n\n      const externalNewer =\n        !lastAppliedUpdatedAtRef.current ||\n        !contentUpdatedAt ||\n        contentUpdatedAt > lastAppliedUpdatedAtRef.current;\n\n      // Only the lead client applies an authoritative snapshot into the shared\n      // Y.Doc; peers receive it through Yjs sync.\n      if (collab && !isLeadClient) {\n        if (contentUpdatedAt && !externalNewer) {\n          lastAppliedUpdatedAtRef.current = contentUpdatedAt;\n        }\n        return;\n      }\n\n      // Never clobber an in-progress edit. While the user is actively typing\n      // (focused and a keystroke landed within the window) defer and re-check —\n      // applying external content now would yank text out from under them and,\n      // for non-idempotent input, fight every keystroke. Newer external content\n      // retries so it still lands once they pause; older-or-equal content is a\n      // stale poll and is dropped outright while focused.\n      const typingRecently =\n        editor.isFocused && Date.now() - lastTypedAtRef.current < 1500;\n      if (typingRecently) {\n        if (externalNewer) {\n          retry = setTimeout(() => apply(deferred), 700);\n        }\n        return;\n      }\n      if (!externalNewer && editor.isFocused) return;\n\n      // Race guard: with peers present, let Yjs deliver a peer's edit first.\n      // Defer once and re-check — a peer edit makes the equality check above\n      // no-op next pass; an agent/source edit still differs and applies.\n      if (collab && externalNewer && !deferred && peerCountRef.current > 0) {\n        retry = setTimeout(() => apply(true), PEER_SETTLE_MS);\n        return;\n      }\n\n      queueMicrotask(() => {\n        if (cancelled || editor.isDestroyed) return;\n        // Re-check doc-equivalence at apply time. Between the decision above and\n        // this microtask a peer/Yjs edit (or our own prior apply) may have made\n        // the editor already represent this value — re-applying would be a\n        // wasted setContent that, for non-idempotent input, re-triggers the\n        // loop. Skip when the editor's current serialization already matches the\n        // normalized value, or the value round-trips to what we last produced.\n        const beforeMarkdown = getMarkdown(editor);\n        const normalized = normalizeValue(value);\n        const unchangedSinceApply =\n          lastAppliedSerializedRef.current !== null &&\n          beforeMarkdown === lastAppliedSerializedRef.current;\n        if (\n          beforeMarkdown === normalized ||\n          (unchangedSinceApply &&\n            normalized === lastAppliedSerializedRef.current)\n        ) {\n          lastAppliedValueRef.current = value;\n          if (contentUpdatedAt) {\n            lastAppliedUpdatedAtRef.current = contentUpdatedAt;\n          }\n          return;\n        }\n        isSettingContentRef.current = true;\n        setContent(editor, value, { emitUpdate: false, addToHistory: false });\n        isSettingContentRef.current = false;\n        // Capture the SERIALIZED result, not the raw value. For non-idempotent\n        // input these differ; recording the serialized output is what lets the\n        // next poll (which returns this serialized form) be recognized as our\n        // own echo and skipped — stabilizing the doc after exactly one apply.\n        const serialized = getMarkdown(editor);\n        lastEmittedRef.current = serialized;\n        pushEmittedRing(recentEmittedRef.current, serialized);\n        lastAppliedValueRef.current = value;\n        lastAppliedSerializedRef.current = serialized;\n        if (contentUpdatedAt) {\n          lastAppliedUpdatedAtRef.current = contentUpdatedAt;\n        }\n      });\n    };\n\n    apply();\n    return () => {\n      cancelled = true;\n      if (retry) clearTimeout(retry);\n    };\n  }, [\n    contentUpdatedAt,\n    editor,\n    value,\n    collab,\n    isLeadClient,\n    getMarkdown,\n    setContent,\n    normalizeValue,\n  ]);\n\n  const shouldIgnoreUpdate = (transaction: Transaction): boolean => {\n    if (!editable || isSettingContentRef.current) return true;\n    // In collab mode, never persist remote-originated changes (the initial Yjs\n    // state load or a peer's edit arriving via sync). Each client saves only its\n    // OWN local edits; a peer's edit is saved by that peer. Without this, a\n    // lagging Y.Doc load would write stale markdown over newer SQL.\n    if (collab && transaction && isChangeOrigin(transaction)) return true;\n    lastTypedAtRef.current = Date.now();\n    return false;\n  };\n\n  const registerEmitted = (markdown: string): boolean => {\n    // Don't persist an empty doc before Collaboration has seeded — that would\n    // clobber the saved block content with an empty string.\n    if (collab && !markdown.trim()) return false;\n    lastEmittedRef.current = markdown;\n    pushEmittedRing(recentEmittedRef.current, markdown);\n    return true;\n  };\n\n  return {\n    collab,\n    isSettingContentRef,\n    shouldIgnoreUpdate,\n    registerEmitted,\n  };\n}\n"]}

package/dist/client/track.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Fire an analytics event from browser/app code. This is the client-side twin
+ * of the server `track()` from `@agent-native/core/tracking`: it POSTs to the
+ * `/_agent-native/track` framework route, which forwards the event to the SAME
+ * registered server-side providers (PostHog, Mixpanel, Amplitude, webhook,
+ * etc.). The event is attributed server-side to the signed-in user (and active
+ * org) — callers do not pass an identity.
+ *
+ * ```ts
+ * import { track } from "@agent-native/core/client";
+ *
+ * track("checkout.completed", { total: 49.99, items: 3 });
+ * ```
+ *
+ * Fire-and-forget by design: it never blocks the UI, never throws, and
+ * swallows network errors. The returned promise resolves once the request
+ * settles (useful in tests) but does not reject.
+ *
+ * This is intentionally distinct from the framework's internal browser
+ * analytics (`trackEvent` / pageview tracking in `analytics.ts`), which feeds
+ * Agent Native's own product telemetry. Use `track()` for your app's own
+ * analytics events.
+ */
+export declare function track(name: string, properties?: Record<string, unknown>): Promise<void>;
+//# sourceMappingURL=track.d.ts.map

package/dist/client/track.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track.d.ts","sourceRoot":"","sources":["../../src/client/track.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,KAAK,CACnB,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,OAAO,CAAC,IAAI,CAAC,CA4Bf"}

package/dist/client/track.js

@@ -0,0 +1,53 @@
+import { agentNativePath } from "./api-path.js";
+/**
+ * Fire an analytics event from browser/app code. This is the client-side twin
+ * of the server `track()` from `@agent-native/core/tracking`: it POSTs to the
+ * `/_agent-native/track` framework route, which forwards the event to the SAME
+ * registered server-side providers (PostHog, Mixpanel, Amplitude, webhook,
+ * etc.). The event is attributed server-side to the signed-in user (and active
+ * org) — callers do not pass an identity.
+ *
+ * ```ts
+ * import { track } from "@agent-native/core/client";
+ *
+ * track("checkout.completed", { total: 49.99, items: 3 });
+ * ```
+ *
+ * Fire-and-forget by design: it never blocks the UI, never throws, and
+ * swallows network errors. The returned promise resolves once the request
+ * settles (useful in tests) but does not reject.
+ *
+ * This is intentionally distinct from the framework's internal browser
+ * analytics (`trackEvent` / pageview tracking in `analytics.ts`), which feeds
+ * Agent Native's own product telemetry. Use `track()` for your app's own
+ * analytics events.
+ */
+export function track(name, properties) {
+    if (typeof fetch !== "function")
+        return Promise.resolve();
+    if (typeof name !== "string" || !name.trim())
+        return Promise.resolve();
+    let body;
+    try {
+        body = JSON.stringify(properties === undefined ? { name } : { name, properties });
+    }
+    catch {
+        // Non-serializable properties — drop rather than throw into the caller.
+        return Promise.resolve();
+    }
+    return fetch(agentNativePath("/_agent-native/track"), {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            // Custom header forces a preflight cross-origin; the framework CSRF
+            // middleware trusts it as a first-party marker. Matches the convention
+            // used by other client writes (application-state, guided-questions).
+            "X-Agent-Native-CSRF": "1",
+        },
+        body,
+        keepalive: true,
+    })
+        .then(() => undefined)
+        .catch(() => undefined);
+}
+//# sourceMappingURL=track.js.map

package/dist/client/track.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track.js","sourceRoot":"","sources":["../../src/client/track.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,KAAK,CACnB,IAAY,EACZ,UAAoC;IAEpC,IAAI,OAAO,KAAK,KAAK,UAAU;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC1D,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAEvE,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,SAAS,CACnB,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAC3D,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;QACxE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,OAAO,KAAK,CAAC,eAAe,CAAC,sBAAsB,CAAC,EAAE;QACpD,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,oEAAoE;YACpE,uEAAuE;YACvE,qEAAqE;YACrE,qBAAqB,EAAE,GAAG;SAC3B;QACD,IAAI;QACJ,SAAS,EAAE,IAAI;KAChB,CAAC;SACC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;SACrB,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;AAC5B,CAAC","sourcesContent":["import { agentNativePath } from \"./api-path.js\";\n\n/**\n * Fire an analytics event from browser/app code. This is the client-side twin\n * of the server `track()` from `@agent-native/core/tracking`: it POSTs to the\n * `/_agent-native/track` framework route, which forwards the event to the SAME\n * registered server-side providers (PostHog, Mixpanel, Amplitude, webhook,\n * etc.). The event is attributed server-side to the signed-in user (and active\n * org) — callers do not pass an identity.\n *\n * ```ts\n * import { track } from \"@agent-native/core/client\";\n *\n * track(\"checkout.completed\", { total: 49.99, items: 3 });\n * ```\n *\n * Fire-and-forget by design: it never blocks the UI, never throws, and\n * swallows network errors. The returned promise resolves once the request\n * settles (useful in tests) but does not reject.\n *\n * This is intentionally distinct from the framework's internal browser\n * analytics (`trackEvent` / pageview tracking in `analytics.ts`), which feeds\n * Agent Native's own product telemetry. Use `track()` for your app's own\n * analytics events.\n */\nexport function track(\n  name: string,\n  properties?: Record<string, unknown>,\n): Promise<void> {\n  if (typeof fetch !== \"function\") return Promise.resolve();\n  if (typeof name !== \"string\" || !name.trim()) return Promise.resolve();\n\n  let body: string;\n  try {\n    body = JSON.stringify(\n      properties === undefined ? { name } : { name, properties },\n    );\n  } catch {\n    // Non-serializable properties — drop rather than throw into the caller.\n    return Promise.resolve();\n  }\n\n  return fetch(agentNativePath(\"/_agent-native/track\"), {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n      // Custom header forces a preflight cross-origin; the framework CSRF\n      // middleware trusts it as a first-party marker. Matches the convention\n      // used by other client writes (application-state, guided-questions).\n      \"X-Agent-Native-CSRF\": \"1\",\n    },\n    body,\n    keepalive: true,\n  })\n    .then(() => undefined)\n    .catch(() => undefined);\n}\n"]}

package/dist/client/use-action.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-action.d.ts","sourceRoot":"","sources":["../../src/client/use-action.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EACnB,MAAM,uBAAuB,CAAC;AA4B/B;;;;;GAKG;AACH,MAAM,WAAW,cAAc;CAAG;AAElC,2FAA2F;AAC3F,KAAK,UAAU,GAAG,MAAM,cAAc,SAAS,KAAK,GAChD,MAAM,GACN,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEpD,8EAA8E;AAC9E,KAAK,YAAY,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,cAAc,GAChE,cAAc,CAAC,CAAC,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC3C,CAAC,GACD,GAAG,GACL,GAAG,CAAC;AAER,iGAAiG;AACjG,KAAK,YAAY,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,cAAc,GAChE,cAAc,CAAC,CAAC,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC3C,CAAC,GACD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACrB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAExB,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEnE,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,kBAAkB,CAAC;CAC7B;AAmBD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,MAAM,CAMR;AAgID;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,OAAO,GAAG,SAAS,EACnB,KAAK,SAAS,UAAU,GAAG,UAAU,EAErC,UAAU,EAAE,KAAK,EACjB,MAAM,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,EAC5B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,OAAO,SAAS,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAGpE;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,OAAO,GAAG,SAAS,EACnB,KAAK,SAAS,UAAU,GAAG,UAAU,EAErC,UAAU,EAAE,KAAK,EACjB,MAAM,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,EAC5B,OAAO,CAAC,EAAE,IAAI,CACZ,eAAe,CAAC,OAAO,SAAS,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,EAC1E,UAAU,GAAG,SAAS,CACvB,6JASF;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,GAAG,SAAS,EACjB,UAAU,GAAG,SAAS,EACtB,KAAK,SAAS,UAAU,GAAG,UAAU,EAErC,UAAU,EAAE,KAAK,EACjB,OAAO,CAAC,EAAE,IAAI,CACZ,kBAAkB,CAChB,KAAK,SAAS,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,KAAK,EACrD,KAAK,EACL,UAAU,SAAS,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,UAAU,CAChE,EACD,YAAY,CACb,GAAG;IACF,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;CACpC,6LAuBF"}
+{"version":3,"file":"use-action.d.ts","sourceRoot":"","sources":["../../src/client/use-action.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EACnB,MAAM,uBAAuB,CAAC;AA4B/B;;;;;GAKG;AACH,MAAM,WAAW,cAAc;CAAG;AAElC,2FAA2F;AAC3F,KAAK,UAAU,GAAG,MAAM,cAAc,SAAS,KAAK,GAChD,MAAM,GACN,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEpD,8EAA8E;AAC9E,KAAK,YAAY,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,cAAc,GAChE,cAAc,CAAC,CAAC,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC3C,CAAC,GACD,GAAG,GACL,GAAG,CAAC;AAER,iGAAiG;AACjG,KAAK,YAAY,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,cAAc,GAChE,cAAc,CAAC,CAAC,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC3C,CAAC,GACD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACrB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAExB,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEnE,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,kBAAkB,CAAC;CAC7B;AAmBD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,MAAM,CAMR;AAsID;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,OAAO,GAAG,SAAS,EACnB,KAAK,SAAS,UAAU,GAAG,UAAU,EAErC,UAAU,EAAE,KAAK,EACjB,MAAM,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,EAC5B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,OAAO,SAAS,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAGpE;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,OAAO,GAAG,SAAS,EACnB,KAAK,SAAS,UAAU,GAAG,UAAU,EAErC,UAAU,EAAE,KAAK,EACjB,MAAM,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,EAC5B,OAAO,CAAC,EAAE,IAAI,CACZ,eAAe,CAAC,OAAO,SAAS,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,EAC1E,UAAU,GAAG,SAAS,CACvB,6JASF;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,GAAG,SAAS,EACjB,UAAU,GAAG,SAAS,EACtB,KAAK,SAAS,UAAU,GAAG,UAAU,EAErC,UAAU,EAAE,KAAK,EACjB,OAAO,CAAC,EAAE,IAAI,CACZ,kBAAkB,CAChB,KAAK,SAAS,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,KAAK,EACrD,KAAK,EACL,UAAU,SAAS,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,UAAU,CAChE,EACD,YAAY,CACb,GAAG;IACF,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;CACpC,6LAuBF"}

package/dist/client/use-action.js

@@ -78,6 +78,12 @@ async function actionFetch(name, method, params) {
     let url = `${ACTION_PREFIX}/${name}`;
     const headers = {
         "Content-Type": "application/json",
+        // Tag browser-originated action calls so the server can set
+        // `ctx.caller = "frontend"` (vs a bare programmatic `"http"` POST).
+        // Mirrors the X-Agent-Native-Tool-Bridge: 1 convention. The header is
+        // safe to expose: CORS allows it (see action-routes.ts) and it carries
+        // no auth weight — it only narrows the caller tag.
+        "X-Agent-Native-Frontend": "1",
     };
     const tz = resolveUserTimezone();
     if (tz)