@jxsuite/studio 8.1.0 → 10.0.0

package/src/services/project-adoption.ts

@@ -11,9 +11,8 @@
 
 import { initProjectRepo } from "../files/files";
 import { getPlatform, hasPlatform } from "../platform";
-import { beginBatch, endBatch, isBatching } from "../tabs/transact";
+import { flushOpenBatches } from "../tabs/transact";
 import { workspace } from "../workspace/workspace";
-import type { Tab } from "../tabs/tab";
 
 let _adopter: ((root: string) => Promise<void>) | null = null;
 
@@ -52,8 +51,6 @@ export interface AdoptOutcome {
 
 /** The seams {@link adoptCreatedProject} runs through, so each caller keeps the one it already had. */
 export interface AdoptCreatedOptions {
-  /** The active tab, read AFTER adoption to re-anchor the agent loop's undo batch. */
-  getTab: () => Tab | null;
   /** The project-open flow. Defaults to this module's late-bound {@link adoptProject}. */
   adopt?: (root: string) => Promise<void>;
   /** Version-control init. Defaults to `files/files.ts`'s `initProjectRepo`. */
@@ -76,9 +73,8 @@ export interface AdoptCreatedOptions {
  * - **Verifying.** `openRecentProject` swallows its failures into a status message, so a resolved
  *   promise is not proof of adoption. The caller must be told which of the two happened.
  *
- * The batch dance is the third: the agent loop may hold an undo batch on the pre-adoption tab, and
- * adoption replaces every tab in the workspace. Flush it, adopt, re-open one on whatever tab
- * adoption left active.
+ * The third is the undo batch: the agent loop's lane may hold segments on pre-adoption tabs, and
+ * adoption replaces every tab in the workspace, so they are closed first (specs/ai.md §3.3).
  *
  * @param {string} root - Absolute root of the project that was just created.
  * @param {AdoptCreatedOptions} opts
@@ -86,7 +82,7 @@ export interface AdoptCreatedOptions {
  */
 export async function adoptCreatedProject(
   root: string,
-  { getTab, adopt = adoptProject, initRepo = initProjectRepo }: AdoptCreatedOptions,
+  { adopt = adoptProject, initRepo = initProjectRepo }: AdoptCreatedOptions = {},
 ): Promise<AdoptOutcome> {
   // Never fails the create: a project that was written stays written (initProjectRepo notifies).
   await initRepo(root);
@@ -117,19 +113,15 @@ export async function adoptCreatedProject(
     }
   }
 
-  const wasBatching = isBatching();
-  if (wasBatching) {
-    endBatch();
-  }
+  /* The tabs an open lane has segments on are about to be replaced: close each now, against the
+     document it was written into. The lane stays open, so the turn's next write opens a segment on
+     whatever document it writes in the adopted project. */
+  flushOpenBatches();
   let adoptionError: string | null = null;
   try {
     await adopt(root);
   } catch (error) {
     adoptionError = error instanceof Error ? error.message : String(error);
   }
-  if (wasBatching) {
-    beginBatch(getTab());
-  }
-
   return { adopted: workspace.projectRoot === root, error: adoptionError, openedElsewhere };
 }

package/src/services/tool-executor.ts

@@ -9,17 +9,19 @@
  *   happen (`services/harness/chat-reducer.ts`), and each round's request is projected from it, as
  *   it always was, so the provider sees the conversation the panel shows, with whatever the send
  *   path trimmed or sealed before the turn began.
- * - **A batch belongs to the tab it edits** (§3.3). The undo batch opens on the active tab and is
- *   re-anchored after every call whose tools moved to another document, so a turn that edits two
- *   documents gives each its own history step and collab publish.
+ * - **The batch belongs to the assistant** (§3.3). The turn opens a batch lane owned by its actor,
+ *   and every write the turn's tools make joins it, one segment per document written: each document
+ *   gets one history step and one collab publish, whichever tab is active, and a person's edit
+ *   during the turn closes the segment on that document rather than being folded into it.
  * - **The ledger is filed under the last message the turn drew** (§3.2), in this module's `finally`,
  *   so the transcript draws the turn's changed-files summary under it.
  *
  * @license MIT
  */
 
+import type { InteractionStore } from "./harness/interaction-store";
 import type { createChatState } from "@jxsuite/ai/chat-state";
-import { DEFAULT_TURN_POLICY, runTurn } from "@jxsuite/ai/harness";
+import { DEFAULT_TURN_POLICY, assistantActorId, runTurn } from "@jxsuite/ai/harness";
 import type { TurnInput, TurnRun } from "@jxsuite/ai/harness";
 import { toChatMessages, toOpenAITools } from "@jxsuite/ai/messages";
 import type { StreamingClient } from "@jxsuite/ai/streaming-client";
@@ -27,7 +29,7 @@ import { createSessionFacts } from "@jxsuite/ai/tools";
 import type { SessionFacts, ToolRegistry } from "@jxsuite/ai/tools";
 
 import type { Tab } from "../tabs/tab";
-import { batchTab, beginBatch, endBatch } from "../tabs/transact";
+import { openBatchLane } from "../tabs/transact";
 import { estimatePromptTokens } from "./context-manager";
 import { fileTurn, openTurnLedger, turnAnchor } from "./ai-writes";
 import { applyHarnessEvent } from "./harness/chat-reducer";
@@ -48,6 +50,8 @@ interface RunAgentLoopOptions {
   getTab?: () => Tab | null;
   /** The conversation's facts, which every call's context carries; a fresh set when omitted. */
   session?: SessionFacts;
+  /** Where a call that needs the author waits on them. Without one, such a call is refused. */
+  interactions?: InteractionStore;
 }
 
 /**
@@ -62,26 +66,23 @@ export async function runAgentLoop({
   signal,
   getTab,
   session = createSessionFacts(),
+  interactions,
 }: RunAgentLoopOptions): Promise<void> {
   /* The ledger is filed under the turn's last DRAWN assistant message (see services/ai-writes), so
      the scan starts at the message this turn answers. */
   const turnUserId = chatState.messages.findLast((m) => m.role === "user")?.id;
   const ledger = openTurnLedger(`turn:${chatState.messages.length}`);
 
-  // Batch all tool-call mutations into a single undo step, anchored on the tab being edited.
-  if (getTab) {
-    beginBatch(getTab());
-  }
-  const reanchorBatch = () => {
-    if (!getTab) {
-      return;
-    }
-    const current = getTab();
-    if (current !== batchTab()) {
-      endBatch();
-      beginBatch(current);
-    }
-  };
+  /* One undo step per document the turn writes. A loop with no `getTab` has no document of its own
+     (the evals), so it gets no lane and each tool is its own entry. The owner's id is the one each
+     call's context will carry, so a tool's write joins the lane by naming `ctx.actor`. */
+  const lane = getTab
+    ? openBatchLane({
+        id: assistantActorId(session.sessionId, ledger.turnId),
+        kind: "assistant",
+        turnId: ledger.turnId,
+      })
+    : null;
 
   /* The placeholder `sendMessage` pushed is round one's message, so the turn answers into it; the
      conversation the turn continues is everything before it. */
@@ -124,7 +125,6 @@ export async function runAgentLoop({
           superseded = true;
           run?.cancel("superseded");
         },
-        reanchor: reanchorBatch,
       }),
       session,
       ledger,
@@ -137,13 +137,16 @@ export async function runAgentLoop({
     if (signal) {
       input.signal = signal;
     }
+    if (interactions) {
+      input.interactions = interactions.strategy;
+    }
     if (placeholder) {
       input.firstMessageId = placeholder.id;
     }
     run = runTurn(input);
     await run.outcome;
   } finally {
-    endBatch();
-    fileTurn(turnAnchor(chatState.messages, turnUserId) ?? "", ledger.writes);
+    const batches = lane?.close() ?? [];
+    fileTurn(turnAnchor(chatState.messages, turnUserId) ?? "", ledger.writes, batches);
   }
 }

package/src/settings/extension-commands.ts

@@ -135,7 +135,7 @@ export async function enableExtension(specifier: string): Promise<void> {
   let installed = false;
   notifySettingsDocument();
   try {
-    if (!row.installed && !row.bundled) {
+    if (!row.installed) {
       /*
        * `beginActivity`, not `showProgressModal`. `studio-ui-guidelines.md` §13.3 reserves blocking
        * for an operation that cannot proceed while the author edits, and this one can — the only

package/src/settings/extension-rows.ts

@@ -32,8 +32,6 @@ export interface ExtensionRow {
   origin: ExtensionOrigin;
   enabled: boolean;
   installed: boolean;
-  /** The host resolves it without a project install, so enabling is a config write alone. */
-  bundled: boolean;
   /** Why this backend cannot run it, as one sentence. Absent means it can. */
   unavailable?: string | undefined;
   /** Enabled but not installed — the state that fails the next build. */
@@ -69,11 +67,9 @@ export function buildRows(packages: PackageInfo[] | null = null): ExtensionRow[]
   for (const entry of getExtensionCatalog()) {
     const specifier = entry.specifier ?? entry.name;
     const here = entry.installed ?? installed.has(entry.name);
-    const bundled = entry.bundled ?? false;
     const info = resolved.get(entry.name);
     const row: ExtensionRow = {
-      broken: enabled.has(specifier) && !here && !bundled,
-      bundled,
+      broken: enabled.has(specifier) && !here,
       enabled: enabled.has(specifier),
       installed: here,
       name: entry.name,
@@ -102,7 +98,6 @@ export function buildRows(packages: PackageInfo[] | null = null): ExtensionRow[]
     const info = resolved.get(specifier);
     const row: ExtensionRow = {
       broken: !installed.has(specifier) && info === undefined,
-      bundled: false,
       enabled: true,
       installed: installed.has(specifier),
       name: specifier,

package/src/settings/extensions-section.ts

@@ -105,12 +105,9 @@ function noteFor(row: ExtensionRow): RowNote {
       noteTone: "warn",
     };
   }
-  if (!row.installed && !row.bundled) {
+  if (!row.installed) {
     return { note: "Not installed. Turning this on installs it first.", noteTone: "note" };
   }
-  if (row.bundled) {
-    return { note: "Ships with this backend, so it needs no install.", noteTone: "note" };
-  }
   return { note: "", noteTone: "none" };
 }
 
@@ -131,7 +128,7 @@ function blockedReason(row: ExtensionRow): string {
  * Refused while the extension is still enabled, and DISABLED with the reason rather than hidden
  * (`studio-ui-guidelines.md` §10): removing the package while `project.json` still names it
  * manufactures exactly the broken state this section exists to eliminate. It is absent only when
- * there is nothing to remove — a package the project never installed, or one the backend bundles.
+ * there is nothing to remove — a package the project never installed.
  */
 function removeFor(
   row: ExtensionRow,
@@ -140,7 +137,7 @@ function removeFor(
     ? `Turn ${row.title} off first. Removing the package while project.json still names it would fail the next build.`
     : "";
   return {
-    canRemove: row.installed && !row.bundled,
+    canRemove: row.installed,
     removeDisabled: refusal !== "" || extensionOpInFlight() !== null,
     removeHint: refusal === "" ? `Remove ${row.name}` : refusal,
     removeLabel: `Remove ${row.name}`,

package/src/state.ts

@@ -154,19 +154,9 @@ export function pathsEqual(a: JxPath | null, b: JxPath | null) {
   return a.every((v, i) => v === b[i]);
 }
 
-/**
- * Returns true if `path` is an ancestor of (or equal to) `descendant`.
- *
- * @param {JxPath} path
- * @param {JxPath} descendant
- * @returns {boolean}
- */
-export function isAncestor(path: JxPath, descendant: JxPath) {
-  if (path.length > descendant.length) {
-    return false;
-  }
-  return path.every((v, i) => v === descendant[i]);
-}
+/* Lives beside the doc-op vocabulary (`@jxsuite/schema/doc-ops`), with the other structural-path
+   helpers; re-exported for the many callers that import it from here. */
+export { isAncestor } from "@jxsuite/schema/doc-ops";
 
 // ─── Tree flattening (for layer panel) ────────────────────────────────────────
 

package/src/surfaces/block-action-bar.json

@@ -104,9 +104,7 @@
       "display": "contents"
     },
     "& [part=\"link\"]": {
-      "display": "flex",
-      "gap": "var(--jx-space-2)",
-      "alignItems": "center",
+      "$description": "No display here. A closed popover is hidden by the platform's own `[popover]:not(:popover-open)` rule, which the kit lets through with `display: revert-layer`; a `display` declared on the part beats it, and the closed panel stayed laid out at the viewport origin, invisible at opacity 0 and still taking every click and the text cursor meant for the workspace tabs beneath it.",
       "padding": "var(--jx-space-3)"
     },
     "& [part=\"link-field\"]": {

package/src/surfaces/files-panel.json

@@ -136,6 +136,18 @@
             }
           ]
         },
+        "address": {
+          "tagName": "div",
+          "attributes": {
+            "part": "empty"
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "textContent": "Add ?project= and a project folder's absolute path to this page's address to open it."
+            }
+          ]
+        },
         "welcome": {
           "tagName": "div",
           "attributes": {

package/src/surfaces/files-panel.ts

@@ -81,8 +81,11 @@ export interface FileRowView {
 
 /** Everything the document draws, as one value. */
 export interface FilesPanelValues {
-  /** Which of three things the panel is: no project, a monorepo root, or a tree. */
-  view: "none" | "welcome" | "tree";
+  /**
+   * Which of four things the panel is: no project, a monorepo root on a host that can open a
+   * project, the same root on one that opens from the address (`?project=`), or a tree.
+   */
+  view: "none" | "welcome" | "address" | "tree";
   headerState: "hidden" | "shown";
   projectName: string;
   query: string;

package/src/surfaces/media-library.json

@@ -1027,6 +1027,41 @@
                             }
                           ]
                         },
+                        "oncontextmenu": {
+                          "$prototype": "Function",
+                          "body": [
+                            {
+                              "$switch": {
+                                "$ref": "#/state/mode"
+                              },
+                              "cases": {
+                                "manage": [
+                                  {
+                                    "preventDefault": true
+                                  },
+                                  {
+                                    "operator": "call",
+                                    "target": {
+                                      "$ref": "#/state/contextMenu"
+                                    },
+                                    "value": [
+                                      {
+                                        "$ref": "$map/item/file"
+                                      },
+                                      {
+                                        "$ref": "event#/clientX"
+                                      },
+                                      {
+                                        "$ref": "event#/clientY"
+                                      }
+                                    ]
+                                  }
+                                ]
+                              }
+                            }
+                          ],
+                          "description": "Manage mode only: the detail pane's actions at the pointer. Pick mode's dialog is modal, and a menu in the popover layer outside it would be inert, so its right-click is left to the platform."
+                        },
                         "children": [
                           {
                             "tagName": "div",

package/src/surfaces/media-library.ts

@@ -118,6 +118,8 @@ export interface MediaLibraryActions {
   activate: (file: string) => void;
   /** Enter on the grid: the same, for the selected file. */
   activateSelected: () => void;
+  /** A right-click on a tile in manage mode: select it and open its actions at the pointer. */
+  contextMenu: (file: string, x: number, y: number) => void;
   key: (key: string, ctrl: boolean) => void;
   measure: (file: string, width: number, height: number) => void;
   copyRef: () => void;

package/src/surfaces/menu.ts

@@ -5,7 +5,8 @@
  * `menu.json` is the markup, ARIA and style, and this adapter is the decisions — which records,
  * what they print, where the panel opens, what runs on select. The kit owns the menu contract
  * (roving focus, typeahead, submenus, light dismissal, Escape) through the platform's own popover,
- * so nothing here binds a key or a document listener.
+ * so nothing here binds a key, and the one window listener is the record of which pointers are held
+ * ({@link pointersReleased}): a menu asked for mid-press is shown on the release.
  *
  * Every menu opens in a `getLayerSlot("popover", id)` slot, which is what carries the
  * `overlay.menu:<id>` region the screenshot pipeline addresses, and is torn down when the popover
@@ -309,6 +310,10 @@ export function openMenu(options: OpenMenuOptions): MenuHandle {
     if (aborted()) {
       return;
     }
+    await pointersReleased(controller.signal);
+    if (aborted()) {
+      return;
+    }
     const source =
       options.opener instanceof HTMLElement && options.opener !== document.body
         ? options.opener
@@ -368,6 +373,62 @@ export function openMenu(options: OpenMenuOptions): MenuHandle {
   return handle;
 }
 
+/**
+ * The pointers pressed in this document and not yet released, by `pointerId`.
+ *
+ * Read by {@link pointersReleased}. Window listeners in the capture phase, so the record is current
+ * before any handler in the document runs, a `contextmenu` handler included. A press in the canvas
+ * iframe is never seen here, and needs not be: that release lands in the iframe's document, which
+ * cannot light-dismiss a popover in this one. Bound at load, so the press that asks for the first
+ * menu is already recorded; not at all without a window, where the docs build imports this module
+ * for the command catalog and nothing is ever pressed.
+ */
+const pressedPointers = new Set<number>();
+if (typeof window !== "undefined") {
+  window.addEventListener("pointerdown", (event) => pressedPointers.add(event.pointerId), true);
+  window.addEventListener("pointerup", (event) => pressedPointers.delete(event.pointerId), true);
+  window.addEventListener(
+    "pointercancel",
+    (event) => pressedPointers.delete(event.pointerId),
+    true,
+  );
+  // A release outside a window that lost focus may never arrive.
+  window.addEventListener("blur", () => pressedPointers.clear());
+}
+
+/**
+ * Settle once no pointer is held down in this document, or when `signal` aborts.
+ *
+ * A menu shown while the button that asked for it is still down is light-dismissed by that button's
+ * release. On Linux and macOS `contextmenu` fires on the PRESS, so every right-click menu opened
+ * with the button held, and the release that followed is a `pointerup` outside the popover. The
+ * HTML light-dismiss algorithm hides every `auto` popover on it, before the event reaches any
+ * listener, so it cannot be cancelled. Chromium 156 exempts a non-primary button and Electron 43's
+ * Chromium does not: in the desktop app the menu flashed and vanished. Waiting for the release is
+ * what Windows does natively, where `contextmenu` fires on it; a menu opened by a click or a key
+ * has nothing held and is shown at once.
+ */
+function pointersReleased(signal: AbortSignal): Promise<void> {
+  if (pressedPointers.size === 0 || signal.aborted) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    const waiting = new AbortController();
+    const settle = (): void => {
+      if (pressedPointers.size === 0 || signal.aborted) {
+        waiting.abort();
+        resolve();
+      }
+    };
+    // Registered after the record's own listeners, so each sees the record already updated.
+    const options = { capture: true, signal: waiting.signal };
+    window.addEventListener("pointerup", settle, options);
+    window.addEventListener("pointercancel", settle, options);
+    window.addEventListener("blur", settle, { signal: waiting.signal });
+    signal.addEventListener("abort", settle, { signal: waiting.signal });
+  });
+}
+
 /**
  * Give the keyboard back to the opener BEFORE a chosen row runs, while the menu still holds it.
  *

package/src/surfaces/settings-packages.ts

@@ -73,7 +73,7 @@ export interface PackagesActions {
   /** Move every package that is behind one. */
   updateAll: () => void;
   remove: (name: string) => void;
-  /** Run `bun install` over the project as it stands. */
+  /** Install the project's dependencies as it stands. */
   reinstall: () => void;
 }
 

package/src/surfaces/welcome.ts

@@ -22,6 +22,7 @@
 import { getAccountStatus, getBannerNotices, needsAppInstall } from "../account-status";
 import { runOfferedAction } from "../account/action-flow";
 import { platformSupportsAddRepo } from "../new-project/add-repo-modal";
+import { canOpenProject, getPlatform } from "../platform";
 import { getProjectList } from "../project-list";
 import { reactive } from "../reactivity";
 import { MINUTE, now } from "../services/clock";
@@ -226,7 +227,9 @@ function project(): Omit<WelcomeScope, "run" | "open" | "remove" | "clear" | "no
     // One entry, not two: the starter gallery IS the first step of New Project now, so the
     // Separate "Start from an Example…" button it used to hide behind is gone.
     { icon: "plus", id: "new", title: "New Project…" },
-    { icon: "folder-open", id: "open", title: "Open Project…" },
+    ...(canOpenProject(getPlatform())
+      ? [{ icon: "folder-open", id: "open", title: "Open Project…" } as const]
+      : []),
     ...(platformSupportsClone()
       ? [{ icon: "download-simple", id: "clone", title: "Clone Git Repository…" } as const]
       : []),

package/src/tabs/selection.ts

@@ -42,10 +42,22 @@
  * standing between a mixed selection and a half-applied, unrecorded delete.
  */
 
-import { isNumber } from "@jxsuite/schema/guards";
+import { isAncestor } from "@jxsuite/schema/doc-ops";
 
 import type { JxPath } from "../state";
-import { isAncestor, pathsEqual } from "../state";
+import { pathsEqual } from "../state";
+
+/* The structural-path helpers live beside the doc-op vocabulary, so any host that edits a document
+   the way Studio does orders and filters a batch the same way. Re-exported here, where every
+   Studio caller already imports them. */
+export {
+  comparePaths,
+  isSpliceablePath,
+  spliceCoordinate,
+  structuralBatch,
+  topLevelSelection,
+} from "@jxsuite/schema/doc-ops";
+export type { SpliceCoordinate } from "@jxsuite/schema/doc-ops";
 
 /**
  * The path single-target surfaces address — the most recently added, or `null` when empty.
@@ -171,113 +183,6 @@ export function pruneSelection(selection: readonly JxPath[], removed: JxPath): J
   return clonePaths(selection.filter((p) => !isAncestor(removed, p)));
 }
 
-/**
- * Order two paths the way the document reads: parents before children, siblings by index.
- *
- * Segments are compared pairwise; numbers numerically (so `children/10` follows `children/9`), and
- * anything else by string order. A prefix sorts before what extends it.
- *
- * @param {JxPath} a
- * @param {JxPath} b
- * @returns {number}
- */
-export function comparePaths(a: JxPath, b: JxPath): number {
-  const len = Math.min(a.length, b.length);
-  for (let i = 0; i < len; i++) {
-    const x = a[i]!;
-    const y = b[i]!;
-    if (x === y) {
-      continue;
-    }
-    if (isNumber(x) && isNumber(y)) {
-      return x - y;
-    }
-    return String(x) < String(y) ? -1 : 1;
-  }
-  return a.length - b.length;
-}
-
-/**
- * Drop any path whose ancestor is also selected.
- *
- * Deleting a `<section>` and one of its own paragraphs is one deletion, not two: the paragraph goes
- * with its parent, and a second splice into coordinates that no longer exist is how a batch
- * corrupts a document.
- *
- * @param {readonly JxPath[]} selection
- * @returns {JxPath[]}
- */
-export function topLevelSelection(selection: readonly JxPath[]): JxPath[] {
-  return clonePaths(
-    selection.filter((p) => !selection.some((q) => !pathsEqual(q, p) && isAncestor(q, p))),
-  );
-}
-
-/**
- * Whether `path` names a position a structural verb can splice — a tail of `"children"` + index.
- *
- * Every structural mutator (`mutateRemoveNode`, `mutateDuplicateNode`, `mutateWrapNode`) reaches
- * its parent with `parentElementPath` — drop the last two segments — and its position with
- * `childIndex` — take the last. That produces a splice coordinate for exactly one path shape, and
- * the Outline emits three others as first-class rows: the document element (`[]`), a repeater's map
- * template (`[…, "children", 1, "map"]`) and a `$switch` case (`[…, "cases", "warn"]`). For the
- * template, `parentElementPath` resolves to the enclosing children ARRAY, whose `.children` is
- * `undefined`, so the splice throws mid-transaction; for a case it splices at `NaN` and takes the
- * wrong child.
- *
- * Selecting one of those beside an ordinary element is a single ctrl-click, so this is the
- * invariant that keeps a batch from mutating the document and then throwing before anything is
- * recorded.
- *
- * @param {JxPath} path
- * @returns {boolean}
- */
-export function isSpliceablePath(path: JxPath): boolean {
-  return spliceCoordinate(path) !== null;
-}
-
-/** Where a structural verb splices: the parent element's path and the index in its children. */
-export interface SpliceCoordinate {
-  parentPath: JxPath;
-  index: number;
-}
-
-/**
- * The splice coordinate `path` names, or `null` for no path and for every path
- * {@link isSpliceablePath} refuses.
- *
- * @param {JxPath | null | undefined} path
- * @returns {SpliceCoordinate | null}
- */
-export function spliceCoordinate(path: JxPath | null | undefined): SpliceCoordinate | null {
-  const index = path?.at(-1);
-  return path && path.at(-2) === "children" && isNumber(index)
-    ? { index, parentPath: path.slice(0, -2) }
-    : null;
-}
-
-/**
- * The order a structural batch must run in: contained paths dropped, unspliceable paths dropped,
- * then LAST node first.
- *
- * Descending document order is what makes a loop of splices safe. Removing or duplicating at index
- * `n` renumbers every sibling after `n`, so a batch that starts at the end never touches a
- * coordinate a later step still needs. It is also why duplicating a multi-selection inserts each
- * clone directly after its own original instead of walking the whole run forward.
- *
- * Containment is decided BEFORE spliceability, on the selection the user actually made: a selected
- * repeater template still shadows its own descendants, so selecting the template and something
- * inside it yields nothing rather than quietly deleting the child the user never pointed at.
- *
- * @param {readonly JxPath[]} selection
- * @returns {JxPath[]} Deepest/last first, every entry a splice coordinate.
- */
-export function structuralBatch(selection: readonly JxPath[]): JxPath[] {
-  return topLevelSelection(selection)
-    .filter((path) => isSpliceablePath(path))
-    .toSorted((a, b) => comparePaths(b, a));
-}
-
 /**
  * Deduplicate a list of paths, keeping the FIRST occurrence of each.
  *

package/src/tabs/tab.ts

@@ -132,7 +132,7 @@ export interface StoredLivePreview {
   error: string | null;
 }
 
-interface HistorySnapshot {
+export interface HistorySnapshot {
   /** Full document at this state (checkpoint), or null when the ops describe the transition. */
   document: JxMutableNode | null;
   /** Selection after this state's transaction — the whole set, so a batch undoes back to it. */
@@ -153,6 +153,13 @@ interface HistorySnapshot {
    * back through the prose one pause at a time instead of undoing the edit.
    */
   coalesceKey?: string | null;
+  /**
+   * Who made this step, when it is not the person at the keyboard: the id of the actor whose batch
+   * lane closed it (specs/ai.md §3.3). Absent on a person's own edits.
+   */
+  actor?: string;
+  /** The turn whose batch this step is, beside {@link HistorySnapshot.actor}. */
+  turnId?: string;
 }
 
 /**
@@ -186,6 +193,8 @@ export interface Tab {
   scope: {
     stop: () => void;
     run: <T>(fn: () => T) => T | undefined;
+    /** False once {@link disposeTab} stopped it: how a record that outlives the tab can tell. */
+    readonly active?: boolean;
   };
   doc: {
     document: JxMutableNode;