@agent-native/core 0.85.6 → 0.86.0

package/corpus/templates/plan/app/components/editor/usePlanUndoStack.ts

@@ -24,14 +24,38 @@ import { useRef, type MutableRefObject } from "react";
 /* text, structure, and options identically — they are all just "blocks[] was */
 /* X, now it's Y". External/agent updates enter via the content-prop effect    */
 /* (setBlocks, NOT commit) so they never enter the user's stack.              */
+/*                                                                            */
+/* External/agent edits DO NOT wipe the stack. Blowing the whole history away  */
+/* on every agent patch was hostile — one agent tweak stranded every unrelated */
+/* user edit. Instead each entry stores the tree it was recorded against        */
+/* (`fromBlocks`) and is validated at APPLY time:                               */
+/*   1. Full match — the live tree still equals the baseline: restore the full  */
+/*      snapshot (the pre-external-edit fast path).                             */
+/*   2. Scoped match — for single-block `text` entries, an external/agent edit  */
+/*      elsewhere must not strand the user's undo (Google-Docs behavior): as    */
+/*      long as THAT block is unchanged since the entry was recorded, undo/redo */
+/*      swaps just that block's state into the live tree, preserving everyone   */
+/*      else's edits.                                                           */
+/*   3. Otherwise the entry is dropped and the walk continues — a stale entry   */
+/*      can't dead-end undo, and a full-tree restore can never clobber newer    */
+/*      concurrent state. `reset()` is kept only for a real doc/plan switch.    */
 /* -------------------------------------------------------------------------- */
 
 /** Kind of change a commit represents — drives coalescing boundaries. */
 type ChangeKind = "text" | "data" | "structural";
 
 interface Snapshot {
-  /** The blocks[] tree to restore when this entry is popped. */
+  /** The blocks[] tree to restore when this entry is applied. */
   blocks: PlanBlock[];
+  /**
+   * The tree this entry expects to be applied AGAINST — the post-edit tree for a
+   * past (undo) entry, or the pre-restore tree for a future (redo) entry. Apply
+   * time compares the live tree to this: they match when no external/agent edit
+   * has intervened, so restoring `blocks` is clean; a mismatch means an external
+   * edit changed the baseline and applying the full snapshot would clobber it, so
+   * the entry is skipped instead of the old blanket reset of the whole stack.
+   */
+  fromBlocks: PlanBlock[];
   kind: ChangeKind;
   /** For `text` entries: the single rich-text block whose markdown changed. */
   changedBlockId: string | null;
@@ -104,6 +128,53 @@ function structuralSignature(blocks: PlanBlock[]): string {
   return parts.join("|");
 }
 
+/** Find a leaf block by id anywhere in the tree (recursing into columns/tabs). */
+function findLeafBlock(blocks: PlanBlock[], id: string): PlanBlock | null {
+  for (const block of blocks) {
+    if (block.type === "columns") {
+      for (const column of block.data.columns) {
+        const found = findLeafBlock(column.blocks, id);
+        if (found) return found;
+      }
+    } else if (block.type === "tabs") {
+      for (const tab of block.data.tabs) {
+        const found = findLeafBlock(tab.blocks, id);
+        if (found) return found;
+      }
+    } else if (block.id === id) {
+      return block;
+    }
+  }
+  return null;
+}
+
+/**
+ * Replace a leaf block by id anywhere in the tree, in place. Returns whether
+ * the block was found and replaced.
+ */
+function replaceLeafBlock(
+  blocks: PlanBlock[],
+  id: string,
+  replacement: PlanBlock,
+): boolean {
+  for (let i = 0; i < blocks.length; i++) {
+    const block = blocks[i];
+    if (block.type === "columns") {
+      for (const column of block.data.columns) {
+        if (replaceLeafBlock(column.blocks, id, replacement)) return true;
+      }
+    } else if (block.type === "tabs") {
+      for (const tab of block.data.tabs) {
+        if (replaceLeafBlock(tab.blocks, id, replacement)) return true;
+      }
+    } else if (block.id === id) {
+      blocks[i] = replacement;
+      return true;
+    }
+  }
+  return false;
+}
+
 /** Map every LEAF block (everything except columns/tabs containers) → serialized data + type. */
 function leafDataById(
   blocks: PlanBlock[],
@@ -187,40 +258,111 @@ export function createPlanUndoStack({
 
     if (coalesce && top) {
       // Keep `top.blocks` (the state from BEFORE the typing burst began) so a
-      // single undo reverts the whole burst; just extend the window.
+      // single undo reverts the whole burst; advance `fromBlocks` to the newest
+      // post-edit tree so apply-time matching tracks the current baseline.
+      top.fromBlocks = clone(next);
       top.t = ts;
     } else {
-      past.push({ blocks: clone(prev), kind, changedBlockId, t: ts });
+      past.push({
+        blocks: clone(prev),
+        fromBlocks: clone(next),
+        kind,
+        changedBlockId,
+        t: ts,
+      });
       if (past.length > limit) past.shift();
     }
     // Any new user edit invalidates the redo branch.
     future.length = 0;
   };
 
+  /**
+   * An entry applies cleanly only when the live tree still equals the tree it was
+   * recorded against (`fromBlocks`). If they differ, an external/agent edit moved
+   * the baseline and restoring the full snapshot would clobber that change — so
+   * the entry falls through to the scoped path. Deep structural equality over the
+   * normalized JSON.
+   */
+  const matchesBaseline = (entry: Snapshot, target: PlanBlock[]): boolean =>
+    JSON.stringify(entry.fromBlocks) === JSON.stringify(target);
+
+  /**
+   * Scoped application for single-block `text` entries whose full-tree baseline
+   * no longer matches (an external/agent edit landed elsewhere). If the entry's
+   * target block is untouched since the entry was recorded — even if it moved
+   * position — swap just that block's recorded state into the live tree. Returns
+   * the new tree, or null when the block itself changed/vanished (entry must be
+   * dropped).
+   */
+  const applyScopedText = (
+    entry: Snapshot,
+    current: PlanBlock[],
+  ): PlanBlock[] | null => {
+    if (entry.kind !== "text" || !entry.changedBlockId) return null;
+    const id = entry.changedBlockId;
+    const liveBlock = findLeafBlock(current, id);
+    const baselineBlock = findLeafBlock(entry.fromBlocks, id);
+    const restoredBlock = findLeafBlock(entry.blocks, id);
+    if (!liveBlock || !baselineBlock || !restoredBlock) return null;
+    // Someone else edited THIS block since the entry was recorded — applying
+    // would clobber their change, so the entry is invalid.
+    if (JSON.stringify(liveBlock) !== JSON.stringify(baselineBlock)) {
+      return null;
+    }
+    const next = clone(current);
+    return replaceLeafBlock(next, id, clone([restoredBlock])[0]) ? next : null;
+  };
+
+  const applyEntry = (
+    entry: Snapshot,
+    current: PlanBlock[],
+  ): PlanBlock[] | null => {
+    if (matchesBaseline(entry, current)) return entry.blocks;
+    return applyScopedText(entry, current);
+  };
+
   const undo = () => {
-    if (past.length === 0) return false;
-    const entry = past.pop() as Snapshot;
-    future.push({
-      blocks: clone(getCurrentBlocks()),
-      kind: entry.kind,
-      changedBlockId: entry.changedBlockId,
-      t: now(),
-    });
-    restore(entry.blocks);
-    return true;
+    // Walk from the top and apply the first entry that still applies — fully
+    // when the baseline matches, scoped to its block for text entries when an
+    // external/agent edit landed elsewhere. Entries invalidated entirely are
+    // dropped as we pass them, so a stale entry can't dead-end undo — the next
+    // still-valid user edit is undone instead. This replaces the old blanket
+    // reset that wiped ALL history the moment any external edit landed.
+    while (past.length > 0) {
+      const entry = past.pop() as Snapshot;
+      const current = getCurrentBlocks();
+      const restored = applyEntry(entry, current);
+      if (!restored) continue;
+      future.push({
+        blocks: clone(current),
+        fromBlocks: clone(restored),
+        kind: entry.kind,
+        changedBlockId: entry.changedBlockId,
+        t: now(),
+      });
+      restore(restored);
+      return true;
+    }
+    return false;
   };
 
   const redo = () => {
-    if (future.length === 0) return false;
-    const entry = future.pop() as Snapshot;
-    past.push({
-      blocks: clone(getCurrentBlocks()),
-      kind: entry.kind,
-      changedBlockId: entry.changedBlockId,
-      t: now(),
-    });
-    restore(entry.blocks);
-    return true;
+    while (future.length > 0) {
+      const entry = future.pop() as Snapshot;
+      const current = getCurrentBlocks();
+      const restored = applyEntry(entry, current);
+      if (!restored) continue;
+      past.push({
+        blocks: clone(current),
+        fromBlocks: clone(restored),
+        kind: entry.kind,
+        changedBlockId: entry.changedBlockId,
+        t: now(),
+      });
+      restore(restored);
+      return true;
+    }
+    return false;
   };
 
   const reset = () => {

package/corpus/templates/plan/app/components/plan/PlanContentRenderer.tsx

@@ -2,7 +2,14 @@ import {
   BlockRegistryProvider,
   type BlockRenderContext,
 } from "@agent-native/core/blocks";
-import { useT, type RichMarkdownCollabUser } from "@agent-native/core/client";
+import {
+  PresenceBar,
+  RecentEditHighlights,
+  useT,
+  type AttributedRecentEdit,
+  type CollabUser,
+  type RichMarkdownCollabUser,
+} from "@agent-native/core/client";
 import type { PlanFileTreeBlock } from "@shared/plan-content";
 import type {
   PlanAnnotation,
@@ -12,6 +19,7 @@ import type {
 } from "@shared/plan-content";
 import { IconBrandGithub } from "@tabler/icons-react";
 import {
+  useCallback,
   useEffect,
   lazy,
   useMemo,
@@ -26,6 +34,7 @@ import {
 } from "react";
 
 import { Button } from "@/components/ui/button";
+import { usePlanPresence } from "@/hooks/use-plan-presence";
 import { cn } from "@/lib/utils";
 
 import {
@@ -190,6 +199,57 @@ export function PlanContentRenderer({
   const t = useT();
   // Deep-link scroll on load/reload/back-forward (TOC clicks aside).
   usePlanHashScroll(content.blocks);
+
+  // ─── Plan-level presence + agent visibility ─────────────────────────────────
+  //
+  // A content-free `plan:<planId>` collab doc carries only awareness: which
+  // humans are viewing/editing, plus the agent's presence + recent-edit
+  // attribution published by the patch actions (`agentTouchDocument`). We render
+  // a PresenceBar in the header and paint a lingering highlight over any block
+  // the agent just patched. Disabled for recaps / non-persisted surfaces (no
+  // planId) and while editing is fully disabled.
+  const presenceUser = useMemo<CollabUser | undefined>(
+    () =>
+      collabUser?.email
+        ? {
+            name: collabUser.name,
+            email: collabUser.email,
+            color: collabUser.color,
+          }
+        : undefined,
+    [collabUser?.email, collabUser?.name, collabUser?.color],
+  );
+  const { activeUsers, agentPresent, agentActive, recentEdits } =
+    usePlanPresence({
+      planId,
+      enabled: !!planId && !isRecap,
+      user: presenceUser,
+    });
+  const documentRegionRef = useRef<HTMLDivElement>(null);
+  const resolvePlanEditRect = useCallback(
+    (edit: AttributedRecentEdit): DOMRect | null => {
+      const container = documentRegionRef.current;
+      if (!container || edit.descriptor.kind !== "paths") return null;
+      const paths = edit.descriptor.paths;
+      if (!Array.isArray(paths) || paths.length === 0) return null;
+      // Each path is a block id; resolve the first one that maps to a live block
+      // node (the core registry NodeView + the read-only view both stamp
+      // `data-block-id` on the block wrapper).
+      for (const blockId of paths) {
+        if (typeof blockId !== "string" || !blockId) continue;
+        const escaped =
+          typeof CSS !== "undefined" && CSS.escape
+            ? CSS.escape(blockId)
+            : blockId.replace(/["\\]/g, "\\$&");
+        const el = container.querySelector<HTMLElement>(
+          `[data-block-id="${escaped}"]`,
+        );
+        if (el) return el.getBoundingClientRect();
+      }
+      return null;
+    },
+    [],
+  );
   const planLabel = isRecap
     ? "Visual Recap"
     : content.prototype
@@ -721,10 +781,16 @@ export function PlanContentRenderer({
           // (not canvas) so its containment can't disturb fixed canvas chrome.
           <div className="plan-document-region">
             <div
+              ref={documentRegionRef}
               className="plan-document-shell relative mx-auto w-full max-w-[1040px] px-6 pb-12 pt-16 sm:px-10 sm:py-12 lg:py-14"
               data-plan-direction={documentDirection}
               dir={documentDirection}
             >
+              <RecentEditHighlights
+                edits={recentEdits}
+                resolveRect={resolvePlanEditRect}
+                containerRef={documentRegionRef}
+              />
               {/* Grid wrapper (header/flow/rails). `data-has-*` picks the tracks;
                   see global.css. */}
               <div
@@ -733,9 +799,19 @@ export function PlanContentRenderer({
               >
                 <header className="border-b border-plan-line pb-8">
                   {!hideRecapChrome && (
-                    <p className="mb-4 text-xs font-bold uppercase tracking-[0.16em] text-plan-muted">
-                      {planLabel}
-                    </p>
+                    <div className="mb-4 flex items-center justify-between gap-3">
+                      <p className="text-xs font-bold uppercase tracking-[0.16em] text-plan-muted">
+                        {planLabel}
+                      </p>
+                      {planId && !isRecap ? (
+                        <PresenceBar
+                          activeUsers={activeUsers}
+                          agentPresent={agentPresent}
+                          agentActive={agentActive}
+                          currentUserEmail={collabUser?.email}
+                        />
+                      ) : null}
+                    </div>
                   )}
                   <EditableHeaderText
                     as="h1"

package/corpus/templates/plan/app/global.css

@@ -1,8 +1,9 @@
-@import url("https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap");
-/* Vazirmatn — open-source (OFL) Persian/Arabic face, scoped to RTL plan content
- * below via `[data-plan-direction="rtl"]`. @fontsource/vazirmatn is not in the
- * workspace, so this matches the Inter CDN @import pattern above. */
-@import url("https://fonts.googleapis.com/css2?family=Vazirmatn:wght@300;400;500;600;700&display=swap");
+/* Self-hosted via @fontsource-variable/inter and @fontsource-variable/vazirmatn
+ * — no render-blocking Google Fonts request. Vazirmatn is an open-source (OFL)
+ * Persian/Arabic face, scoped to RTL plan content below via
+ * `[data-plan-direction="rtl"]`. */
+@import "@fontsource-variable/inter";
+@import "@fontsource-variable/vazirmatn";
 
 @import "tailwindcss";
 @import "@agent-native/core/styles/agent-native.css";
@@ -111,7 +112,7 @@
 @layer base {
   body {
     @apply bg-background text-foreground;
-    font-family: "Inter", sans-serif;
+    font-family: "Inter Variable", "Inter", sans-serif;
     font-feature-settings: "cv02", "cv03", "cv04", "cv11";
   }
 }
@@ -124,7 +125,8 @@
  * face — code never renders in Vazirmatn (code-like blocks are also pinned to
  * dir="ltr"). */
 [data-plan-direction="rtl"] {
-  font-family: "Vazirmatn", "Inter", sans-serif;
+  font-family:
+    "Vazirmatn Variable", "Vazirmatn", "Inter Variable", "Inter", sans-serif;
 }
 
 @layer utilities {
@@ -1711,7 +1713,7 @@
 .plan-template-group-title > span:last-child,
 .plan-template-meter-copy > span {
   color: var(--plan-muted);
-  font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+  font-family: "Inter Variable", Inter, ui-sans-serif, system-ui, sans-serif;
   font-size: 11px;
   font-weight: 700;
 }
@@ -1732,7 +1734,7 @@
 .plan-template-header-meta,
 .plan-template-popover-header > span {
   color: var(--plan-muted);
-  font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+  font-family: "Inter Variable", Inter, ui-sans-serif, system-ui, sans-serif;
   font-size: 11px;
   font-weight: 700;
 }

package/corpus/templates/plan/app/hooks/use-navigation-state.ts

@@ -106,7 +106,16 @@ export function useNavigationState() {
     const path = planNavigateCommandPath(cmd);
     void prewarmPlanRoutePath(path);
     if (path !== "/") markAgentChatHomeHandoff("plans");
-    navigate(path, { replace: true, flushSync: true });
+    const commitNavigation = () =>
+      navigate(path, { replace: true, flushSync: true });
+    if (
+      typeof window !== "undefined" &&
+      typeof window.queueMicrotask === "function"
+    ) {
+      window.queueMicrotask(commitNavigation);
+    } else {
+      window.setTimeout(commitNavigation, 0);
+    }
     qc.setQueryData(["navigate-command"], null);
   }, [navCommand, navigate, qc]);
 }

package/corpus/templates/plan/app/hooks/use-plan-presence.ts

@@ -0,0 +1,66 @@
+import {
+  useCollaborativeDoc,
+  usePresence,
+  useRecentEdits,
+  generateTabId,
+  type AttributedRecentEdit,
+  type CollabUser,
+} from "@agent-native/core/client";
+
+/** One tab id per browser tab, shared by every plan presence hook instance. */
+const TAB_ID = generateTabId();
+
+export interface UsePlanPresenceResult {
+  /** Remote human collaborators (excludes self and the agent slot). */
+  activeUsers: CollabUser[];
+  /** True while the AI agent holds a durable presence entry on this plan. */
+  agentPresent: boolean;
+  /** True briefly right after the agent edits (for the "AI editing" pulse). */
+  agentActive: boolean;
+  /** Non-expired recent edits from remote participants (human + agent). */
+  recentEdits: AttributedRecentEdit[];
+}
+
+/**
+ * Plan-level presence + recent-edit attribution over a lightweight, content-free
+ * collab doc `plan:<planId>` — the single-doc content collab is intentionally
+ * OFF (see PlanDocumentEditor), so this doc carries ONLY awareness (who is here,
+ * where the agent is working) and never any Y.XmlFragment content.
+ *
+ * Mirrors templates/slides `use-deck-presence`: open the doc for awareness, and
+ * publish the local user identity so peers see the current user's avatar. The
+ * agent's presence + `{ kind: "paths", paths }` recent-edit descriptors arrive
+ * on the same doc from `agentTouchDocument("plan:<planId>", …)` in the patch
+ * actions, so no client publish is needed for the agent.
+ */
+export function usePlanPresence(options: {
+  planId: string | null | undefined;
+  enabled?: boolean;
+  user?: CollabUser;
+}): UsePlanPresenceResult {
+  const { planId, enabled = true, user } = options;
+  const docId = enabled && planId ? `plan:${planId}` : null;
+
+  const { ydoc, awareness, activeUsers, agentPresent, agentActive } =
+    useCollaborativeDoc({
+      docId,
+      user,
+      requestSource: TAB_ID,
+      // Presence is low-stakes; a relaxed poll keeps it cheap.
+      pollInterval: 3000,
+    });
+
+  const localClientId = ydoc?.clientID ?? null;
+  const { others } = usePresence(awareness, localClientId);
+  const recentEdits = useRecentEdits(others);
+
+  return {
+    // `activeUsers` from useCollaborativeDoc already excludes the agent slot and
+    // dedupes by email; PresenceBar filters out the current user via its
+    // `currentUserEmail` prop.
+    activeUsers,
+    agentPresent,
+    agentActive,
+    recentEdits,
+  };
+}