@agent-native/core 0.85.6 → 0.86.0

package/corpus/core/src/client/index.ts

@@ -163,6 +163,20 @@ export {
   useFileWatcher,
   useScreenRefreshKey,
 } from "./use-db-sync.js";
+export {
+  VisualControlRow,
+  VisualInspectorPanel,
+  VisualInspectorSection,
+  VisualScrubInput,
+  VisualSegmentedControl,
+  VisualSliderControl,
+  VisualSwatchControl,
+  VisualToggleControl,
+  VisualTweakControl,
+  type VisualControlOption,
+  type VisualControlValue,
+  type VisualTweakDefinition,
+} from "./visual-style-controls.js";
 export {
   useChangeVersion,
   useChangeVersions,
@@ -660,6 +674,7 @@ export {
   DevDatabaseLink,
   type DevDatabaseLinkProps,
 } from "./db-admin/DevDatabaseLink.js";
+export { DbAdminPage } from "./db-admin/DbAdminPage.js";
 export { ErrorBoundary } from "./ErrorBoundary.js";
 export {
   installRouteChunkRecovery,
@@ -853,7 +868,40 @@ export {
 export {
   RemoteSelectionRings,
   type RemoteSelectionRingsProps,
+  type SelectionDescriptor,
 } from "./components/RemoteSelectionRings.js";
+export {
+  RecentEditHighlights,
+  type RecentEditHighlightsProps,
+} from "./components/RecentEditHighlights.js";
+// Recent-edit attribution (lingering highlights)
+export {
+  appendRecentEdit,
+  collectRecentEdits,
+  publishRecentEdit,
+  useRecentEdits,
+  RECENT_EDITS_MAX,
+  RECENT_EDIT_TTL_MS,
+  type RecentEdit,
+  type RecentEditDescriptor,
+  type AttributedRecentEdit,
+  type UseRecentEditsOptions,
+} from "../collab/recent-edits.js";
+// Per-user undo/redo
+export {
+  useCollabUndo,
+  useLocalOpUndo,
+  createLocalOpUndoController,
+  type UseCollabUndoOptions,
+  type UseCollabUndoResult,
+  type CollabUndoScope,
+  type UseLocalOpUndoOptions,
+  type UseLocalOpUndoResult,
+  type LocalOpUndoEntry,
+  type LocalOpUndoController,
+  type CreateLocalOpUndoOptions,
+  type UndoKeyboardOptions,
+} from "../collab/undo.js";
 // Structured data collaboration hooks
 export {
   useCollaborativeMap,

package/corpus/core/src/client/org/OrgSwitcher.tsx

@@ -13,7 +13,6 @@ import {
   IconChevronRight,
   IconClipboardList,
   IconCode,
-  IconContract,
   IconFileText,
   IconLayoutBoard,
   IconLoader2,
@@ -34,7 +33,6 @@ import {
   IconUser,
   IconUserPlus,
   IconUsers,
-  IconVideo,
   IconWorld,
 } from "@tabler/icons-react";
 import { useState } from "react";
@@ -109,12 +107,10 @@ const APP_ICON_MAP: Record<string, typeof IconApps> = {
   LayoutBoard: IconLayoutBoard,
   BarChart2: IconChartBar,
   GalleryHorizontal: IconPresentation,
-  Video: IconVideo,
   BrandJira: IconBrandJira,
   ClipboardList: IconClipboardList,
   Users: IconUsers,
   Code: IconCode,
-  Contract: IconContract,
   MessageCircle: IconMessageCircle,
   Route: IconRoute,
   ScreenShare: IconScreenShare,

package/corpus/core/src/client/rich-markdown-editor/SharedRichEditor.tsx

@@ -19,6 +19,7 @@ import {
   useCollabReconcile,
   getEditorMarkdown,
   type UseCollabReconcileResult,
+  type UseCollabReconcileOptions,
 } from "./useCollabReconcile.js";
 
 export interface SharedRichEditorProps {
@@ -86,6 +87,12 @@ export interface SharedRichEditorProps {
     value: string,
     options: { emitUpdate?: boolean; addToHistory?: boolean },
   ) => void;
+  /**
+   * Optional parser for surgical reconcile. Custom value formats that already
+   * handle surgical writes inside `setContent` can pass `false` so the default
+   * markdown parser never treats their source bytes as literal markdown.
+   */
+  parseValue?: UseCollabReconcileOptions["parseValue"];
   /** Canonicalize `value` for the echo / already-in-sync equality checks. */
   normalizeValue?: (value: string) => string;
   /** Override the empty-doc seed predicate (see {@link useCollabReconcile}). */
@@ -142,6 +149,7 @@ export function SharedRichEditor({
   buildBubbleItems,
   getMarkdown,
   setContent,
+  parseValue,
   normalizeValue,
   shouldSeed,
   initialAppliedUpdatedAt,
@@ -196,40 +204,48 @@ export function SharedRichEditor({
   // holds the real guards.
   const guardsRef = useRef<UseCollabReconcileResult | null>(null);
 
-  const editor = useEditor({
-    extensions,
-    // With Collaboration active the prose is owned by the shared Y.XmlFragment.
-    // Seeding `content` here too would make the editor initialize from BOTH the
-    // prop and the Y.Doc, firing a spurious initial update that could autosave a
-    // stale value over newer SQL. The lead-client seed effect populates an empty
-    // doc instead. Non-collab editors keep initializing from `value`.
-    // With Collaboration the Y.Doc owns the prose (seeded by the lead client).
-    // With a custom `setContent` the reconcile seeds the editor too (the raw
-    // `value` is not directly settable content — e.g. the plan's blocks JSON),
-    // so only the plain markdown path seeds from `value` here.
-    content: collab || setContent ? null : value,
-    editable,
-    editorProps: {
-      attributes: {
-        class: cn("an-rich-md-prose", editorClassName),
-        ...(ariaLabel ? { role: "textbox", "aria-label": ariaLabel } : {}),
+  const editor = useEditor(
+    {
+      extensions,
+      // With Collaboration active the prose is owned by the shared Y.XmlFragment.
+      // Seeding `content` here too would make the editor initialize from BOTH the
+      // prop and the Y.Doc, firing a spurious initial update that could autosave a
+      // stale value over newer SQL. The lead-client seed effect populates an empty
+      // doc instead. Non-collab editors keep initializing from `value`.
+      // With Collaboration the Y.Doc owns the prose (seeded by the lead client).
+      // With a custom `setContent` the reconcile seeds the editor too (the raw
+      // `value` is not directly settable content — e.g. the plan's blocks JSON),
+      // so only the plain markdown path seeds from `value` here.
+      content: collab || setContent ? null : value,
+      editable,
+      editorProps: {
+        attributes: {
+          class: cn("an-rich-md-prose", editorClassName),
+          ...(ariaLabel ? { role: "textbox", "aria-label": ariaLabel } : {}),
+        },
       },
+      onUpdate: ({ editor, transaction }) => {
+        const guards = guardsRef.current;
+        if (!guards || guards.shouldIgnoreUpdate(transaction)) return;
+        try {
+          const markdown = readMarkdown(editor);
+          if (!guards.registerEmitted(markdown)) return;
+          queueMicrotask(() => onChangeRef.current(markdown));
+        } catch (error) {
+          console.error("Markdown serialization error:", error);
+        }
+      },
+      onBlur: () => {
+        onBlurRef.current?.();
+      },
+      // Recreate the editor when the shared Y.Doc identity changes — including
+      // null → doc. Extensions are baked in at creation, so a ydoc that arrives
+      // AFTER the first mount (fresh page load: the session/user resolves after
+      // the editor mounts) would otherwise never bind Collaboration: the editor
+      // looks fine but produces no Yjs updates and never receives peers' edits.
     },
-    onUpdate: ({ editor, transaction }) => {
-      const guards = guardsRef.current;
-      if (!guards || guards.shouldIgnoreUpdate(transaction)) return;
-      try {
-        const markdown = readMarkdown(editor);
-        if (!guards.registerEmitted(markdown)) return;
-        queueMicrotask(() => onChangeRef.current(markdown));
-      } catch (error) {
-        console.error("Markdown serialization error:", error);
-      }
-    },
-    onBlur: () => {
-      onBlurRef.current?.();
-    },
-  });
+    [ydoc],
+  );
 
   const collabState = useCollabReconcile({
     editor,
@@ -240,6 +256,7 @@ export function SharedRichEditor({
     editable,
     getMarkdown: readMarkdown,
     setContent,
+    parseValue,
     normalizeValue,
     shouldSeed,
     initialAppliedUpdatedAt,

package/corpus/core/src/client/rich-markdown-editor/index.ts

@@ -15,6 +15,12 @@ export {
   type UseCollabReconcileOptions,
   type UseCollabReconcileResult,
 } from "./useCollabReconcile.js";
+export {
+  applyDocSurgically,
+  defaultParseValue,
+  diffTopLevel,
+  type TopLevelDiff,
+} from "./surgical-apply.js";
 export {
   SlashCommandMenu,
   DEFAULT_SLASH_COMMANDS,

package/corpus/core/src/client/rich-markdown-editor/surgical-apply.ts

@@ -0,0 +1,192 @@
+/**
+ * Surgical reconcile — apply an authoritative external document into the live
+ * editor by replacing only the changed top-level node run, instead of a
+ * whole-document `setContent`.
+ *
+ * Why: under the Collaboration extension, `setContent` routes through
+ * y-prosemirror and rewrites the ENTIRE `Y.XmlFragment`. Every block-level
+ * NodeView is torn down and recreated (each `ReactRenderer` constructor calls
+ * `flushSync`, firing inside a React lifecycle), remote carets jump, and the
+ * CRDT sees a delete-all + insert-all instead of a small edit. Diffing the
+ * top-level children and dispatching one `tr.replaceWith(from, to, changed)`
+ * leaves unchanged NodeViews untouched and produces minimal Yjs ops.
+ *
+ * This is the core mechanism behind re-enabling single-doc collab in the plan
+ * editor (see templates/plan/shared/plan-doc.collab-stability.spec.ts, "Option
+ * B") and removing agent-edit NodeView churn in content.
+ */
+
+import { createNodeFromContent } from "@tiptap/core";
+import type { Fragment, Node as ProseMirrorNode } from "@tiptap/pm/model";
+import type { Editor } from "@tiptap/react";
+
+/**
+ * Transaction meta marking programmatic (non-user) rich-markdown transactions.
+ * Declared here (not in useCollabReconcile) so the module dependency stays
+ * one-directional; useCollabReconcile re-exports it for consumers.
+ */
+export const RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION =
+  "an-rich-md-programmatic-transaction";
+
+export interface TopLevelDiff {
+  /** Index of the first differing top-level child. */
+  fromIndex: number;
+  /** Exclusive end index of the differing run in the OLD doc. */
+  oldToIndex: number;
+  /** Exclusive end index of the differing run in the NEW doc. */
+  newToIndex: number;
+  /** Document position where the differing run starts. */
+  fromPos: number;
+  /** Document position where the differing run ends in the OLD doc. */
+  toPos: number;
+}
+
+/**
+ * Diff two documents at top-level-node granularity: trim the common prefix and
+ * suffix (node equality via ProseMirror's `Node.eq`, which is deep) and return
+ * the remaining changed run. Returns null when the documents are equal.
+ */
+export function diffTopLevel(
+  oldDoc: ProseMirrorNode,
+  newDoc: ProseMirrorNode,
+): TopLevelDiff | null {
+  const oldCount = oldDoc.childCount;
+  const newCount = newDoc.childCount;
+
+  let prefix = 0;
+  const maxPrefix = Math.min(oldCount, newCount);
+  while (prefix < maxPrefix && oldDoc.child(prefix).eq(newDoc.child(prefix))) {
+    prefix++;
+  }
+
+  if (prefix === oldCount && prefix === newCount) return null; // identical
+
+  let suffix = 0;
+  const maxSuffix = Math.min(oldCount, newCount) - prefix;
+  while (
+    suffix < maxSuffix &&
+    oldDoc.child(oldCount - 1 - suffix).eq(newDoc.child(newCount - 1 - suffix))
+  ) {
+    suffix++;
+  }
+
+  const fromIndex = prefix;
+  const oldToIndex = oldCount - suffix;
+  const newToIndex = newCount - suffix;
+
+  // Positions: sum nodeSize of the preserved prefix, then of the changed run.
+  let fromPos = 0;
+  for (let i = 0; i < fromIndex; i++) fromPos += oldDoc.child(i).nodeSize;
+  let toPos = fromPos;
+  for (let i = fromIndex; i < oldToIndex; i++) {
+    toPos += oldDoc.child(i).nodeSize;
+  }
+
+  return { fromIndex, oldToIndex, newToIndex, fromPos, toPos };
+}
+
+function changedFragment(
+  newDoc: ProseMirrorNode,
+  diff: TopLevelDiff,
+): Fragment {
+  return newDoc.content.cut(
+    positionOfChild(newDoc, diff.fromIndex),
+    positionOfChild(newDoc, diff.newToIndex),
+  );
+}
+
+function positionOfChild(doc: ProseMirrorNode, index: number): number {
+  let pos = 0;
+  for (let i = 0; i < index; i++) pos += doc.child(i).nodeSize;
+  return pos;
+}
+
+function isEmptyParagraph(node: ProseMirrorNode | null): boolean {
+  return !!node && node.type.name === "paragraph" && node.content.size === 0;
+}
+
+/**
+ * Markdown can't represent a trailing empty paragraph (the cursor line users
+ * keep below a list/code block), so a parsed authoritative value never has
+ * one — but the live doc often does, and the legacy `setContent` path
+ * preserves it. Without this, every surgical reconcile whose old doc ends
+ * with an empty paragraph would DELETE the user's trailing cursor line.
+ */
+function withPreservedTrailingParagraph(
+  oldDoc: ProseMirrorNode,
+  newDoc: ProseMirrorNode,
+): ProseMirrorNode {
+  const oldLast =
+    oldDoc.childCount > 0 ? oldDoc.child(oldDoc.childCount - 1) : null;
+  if (!isEmptyParagraph(oldLast)) return newDoc;
+  const newLast =
+    newDoc.childCount > 0 ? newDoc.child(newDoc.childCount - 1) : null;
+  if (isEmptyParagraph(newLast)) return newDoc;
+  return newDoc.copy(newDoc.content.addToEnd(oldLast!.type.create()));
+}
+
+/**
+ * Replace only the changed top-level run of the live document with the
+ * corresponding run from `newDoc`, in one programmatic, history-free
+ * transaction. Returns:
+ *  - "applied"   — a targeted replacement was dispatched
+ *  - "noop"      — the documents were already equal (nothing dispatched)
+ *  - "failed"    — the diff/transaction could not be applied (schema mismatch,
+ *                  invalid content, …); caller should fall back to setContent.
+ */
+export function applyDocSurgically(
+  editor: Editor,
+  newDoc: ProseMirrorNode,
+): "applied" | "noop" | "failed" {
+  try {
+    const oldDoc = editor.state.doc;
+    // The parsed doc MUST come from this editor's schema — NodeType identity
+    // is per-Schema-instance, so a foreign-schema doc can never diff or apply.
+    if (newDoc.type.schema !== editor.schema || newDoc.type !== oldDoc.type) {
+      return "failed";
+    }
+
+    const target = withPreservedTrailingParagraph(oldDoc, newDoc);
+    const diff = diffTopLevel(oldDoc, target);
+    if (!diff) return "noop";
+
+    const fragment = changedFragment(target, diff);
+    const tr = editor.state.tr;
+    tr.replaceWith(diff.fromPos, diff.toPos, fragment);
+    tr.setMeta("addToHistory", false);
+    tr.setMeta(RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION, true);
+    editor.view.dispatch(tr);
+    return "applied";
+  } catch {
+    return "failed";
+  }
+}
+
+/**
+ * Best-effort default parser for the surgical path: use the tiptap-markdown
+ * storage parser (present when the shared editor's `features.markdown` is on)
+ * to turn the authoritative markdown into a ProseMirror document. Returns null
+ * when unavailable or when parsing fails — the caller falls back to the full
+ * `setContent` path.
+ *
+ * Apps with their own serializers (Content's NFM, Plan's blocks[] doc) should
+ * pass an explicit `parseValue` producing the exact doc their `setContent`
+ * would have written.
+ */
+export function defaultParseValue(
+  editor: Editor,
+  value: string,
+): ProseMirrorNode | null {
+  try {
+    const storage = (editor.storage as Record<string, any>).markdown;
+    const parsed = storage?.parser?.parse?.(value, { inline: false });
+    if (typeof parsed !== "string" || !parsed) return null;
+    const node = createNodeFromContent(parsed, editor.schema, {
+      slice: false,
+    });
+    // createNodeFromContent with slice:false returns a Node (the doc).
+    return (node as ProseMirrorNode) ?? null;
+  } catch {
+    return null;
+  }
+}

package/corpus/core/src/client/rich-markdown-editor/useCollabReconcile.ts

@@ -1,4 +1,5 @@
 import { isChangeOrigin } from "@tiptap/extension-collaboration";
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
 import type { Transaction } from "@tiptap/pm/state";
 import type { Editor } from "@tiptap/react";
 import { useEffect, useRef, useState, type MutableRefObject } from "react";
@@ -7,9 +8,13 @@ import type { Doc as YDoc } from "yjs";
 
 import { AGENT_CLIENT_ID } from "../../collab/agent-identity.js";
 import { isReconcileLeadClient } from "../../collab/client.js";
+import {
+  RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION,
+  applyDocSurgically,
+  defaultParseValue,
+} from "./surgical-apply.js";
 
-export const RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION =
-  "an-rich-md-programmatic-transaction";
+export { RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION };
 
 /** Reads the current markdown out of the tiptap-markdown storage. */
 export function getEditorMarkdown(editor: Editor): string {
@@ -71,6 +76,22 @@ export interface UseCollabReconcileOptions {
     value: string,
     options: { emitUpdate?: boolean; addToHistory?: boolean },
   ) => void;
+  /**
+   * Parses the authoritative `value` into a full ProseMirror document for the
+   * SURGICAL reconcile path: instead of a whole-document `setContent` (which
+   * under Collaboration rewrites the entire Y.XmlFragment and tears down every
+   * block NodeView), the reconcile diffs the parsed doc against the live doc
+   * and replaces only the changed top-level run. Return null to skip the
+   * surgical path for a given value (falls back to `setContent`).
+   *
+   * Defaults to a best-effort tiptap-markdown parse; apps with their own
+   * serializers (Content's NFM, Plan's blocks[] doc) should supply the exact
+   * doc their `setContent` would write. Pass `false` to disable surgical
+   * application entirely.
+   */
+  parseValue?:
+    | ((editor: Editor, value: string) => ProseMirrorNode | null)
+    | false;
   /**
    * Normalizes the authoritative `value` to the canonical markdown the editor
    * would emit, so the "already in sync / our own echo" equality checks match a
@@ -198,6 +219,7 @@ export function useCollabReconcile({
   editable,
   getMarkdown = getEditorMarkdown,
   setContent = defaultSetContent,
+  parseValue,
   normalizeValue = (v) => v,
   shouldSeed = defaultShouldSeed,
   initialAppliedUpdatedAt,
@@ -281,20 +303,32 @@ export function useCollabReconcile({
     // 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`).
+    seededRef.current = true;
     if (
-      shouldSeed({ value, currentMarkdown, fragmentLength: fragment.length })
+      !shouldSeed({ value, currentMarkdown, fragmentLength: fragment.length })
     ) {
+      return;
+    }
+
+    let cancelled = false;
+    queueMicrotask(() => {
+      if (cancelled || editor.isDestroyed) return;
       isSettingContentRef.current = true;
-      setContent(editor, value, {});
-      isSettingContentRef.current = false;
+      try {
+        setContent(editor, value, {});
+      } finally {
+        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;
+    });
+    return () => {
+      cancelled = true;
+    };
   }, [
     collab,
     editor,
@@ -452,7 +486,23 @@ export function useCollabReconcile({
           return;
         }
         isSettingContentRef.current = true;
-        setContent(editor, value, { emitUpdate: false, addToHistory: false });
+        // Surgical path first: replace only the changed top-level run so
+        // unchanged block NodeViews are never torn down and (under
+        // Collaboration) Yjs sees a minimal edit instead of a full-fragment
+        // rewrite. Falls back to the classic whole-document setContent when no
+        // parser is available or the targeted transaction cannot be applied.
+        let appliedSurgically = false;
+        if (parseValue !== false) {
+          const parse = parseValue ?? defaultParseValue;
+          const parsedDoc = parse(editor, value);
+          if (parsedDoc) {
+            const result = applyDocSurgically(editor, parsedDoc);
+            appliedSurgically = result === "applied" || result === "noop";
+          }
+        }
+        if (!appliedSurgically) {
+          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
@@ -482,6 +532,7 @@ export function useCollabReconcile({
     isLeadClient,
     getMarkdown,
     setContent,
+    parseValue,
     normalizeValue,
   ]);