@jxsuite/studio 8.0.1 → 9.0.0

package/src/tabs/transact.ts

@@ -1,7 +1,7 @@
 /// <reference lib="dom" />
 import { toRaw } from "../reactivity";
 import { jsonClone } from "../utils/studio-utils";
-import { childIndex, getNodeAtPath, parentElementPath, pathsEqual } from "../state";
+import { getNodeAtPath, pathsEqual } from "../state";
 import {
   cloneSelection,
   primarySelection,
@@ -10,6 +10,7 @@ import {
   structuralBatch,
 } from "./selection";
 import { applyDocOpToDoc, childArray, cloneValue, inverseOf } from "./doc-op-apply";
+import { insertionSlot, planMove, shiftPrefixedIndex } from "@jxsuite/schema/doc-ops";
 import {
   beginRecording,
   endRecording,
@@ -20,8 +21,9 @@ import {
 } from "./patch-ops";
 
 import type { JxDocOp, JxDocOpPair, TransactionRecord } from "./patch-ops";
+import type { SelectionEffect } from "@jxsuite/ai/jx-tools";
 
-import type { Tab } from "../tabs/tab";
+import type { HistorySnapshot, Tab } from "../tabs/tab";
 import type { JxPath } from "../state";
 
 import type { JsonValue } from "../types";
@@ -38,7 +40,6 @@ import {
   getNestedStyle,
   isEventBinding,
   isNonNullObject,
-  isNumber,
 } from "@jxsuite/schema/guards";
 
 const HISTORY_LIMIT = 100;
@@ -81,33 +82,6 @@ function setKeyPair(
   };
 }
 
-/**
- * Translate `path` into post-splice coordinates when it descends through `parentPath`'s children at
- * or beyond the spliced index: a removal (delta -1) at fromIndex shifts deeper paths down; an
- * insertion (delta +1, inclusive) shifts them up. Returns `path` unchanged when the splice doesn't
- * affect it. Used to express a move's inverse in post-mutation coordinates.
- */
-function shiftPrefixedIndex(
-  parentPath: JxPath,
-  path: JxPath,
-  spliceIndex: number,
-  delta: number,
-  inclusive: boolean,
-): JxPath {
-  const d = parentPath.length;
-  const isProperPrefix = d < path.length && parentPath.every((seg, i) => seg === path[i]);
-  const idx = path[d + 1];
-  if (!isProperPrefix || path[d] !== "children" || !isNumber(idx)) {
-    return path;
-  }
-  if (inclusive ? idx < spliceIndex : idx <= spliceIndex) {
-    return path;
-  }
-  const shifted = [...path];
-  shifted[d + 1] = idx + delta;
-  return shifted;
-}
-
 /** Any value that can sit at a document node key (undefined/null/"" deletes it). */
 export type JxNodeValue =
   | JsonValue
@@ -214,20 +188,21 @@ function rollbackFailedTransaction(
  * with no prompt. A refusal is not an exception (it is an ordinary, expected state of the room), so
  * it is a return value: `false` means the document is exactly as it was.
  *
+ * **AND IT SAYS WHO WROTE.** `actor` (else the scope {@link runAsActor} opened, else the person at
+ * the keyboard) decides where the step lands: an actor that owns an open {@link BatchLane} folds it
+ * into that lane's segment on this tab, and anyone else first closes whatever segment is open here,
+ * so their edit is never folded into someone else's step (specs/ai.md §3.3).
+ *
  * @param {Tab | null} tab
  * @param {(tab: Tab) => void} mutationFn
- * @param {{ skipHistory?: boolean; origin?: TransactOrigin }} [opts]
+ * @param {TransactOptions} [opts]
  * @returns {boolean} True when the mutation was applied; false when there was no tab, or the gate
  *   refused it.
  */
 export function transactDoc(
   tab: Tab | null,
   mutationFn: (tab: Tab) => void,
-  {
-    skipHistory = false,
-    origin = "user",
-    coalesceKey = null,
-  }: { skipHistory?: boolean; origin?: TransactOrigin; coalesceKey?: string | null } = {},
+  { skipHistory = false, origin = "user", coalesceKey = null, actor = null }: TransactOptions = {},
 ): boolean {
   if (!tab) {
     return false;
@@ -235,6 +210,12 @@ export function transactDoc(
   if (origin !== "remote" && _transactGate?.(tab, origin)) {
     return false;
   }
+  const writer = actor ?? _scopeActor;
+  /* A remote collaborator's ops are the room's, not a local writer's: they skip history and are
+     never published back, so they neither join a lane nor close one. */
+  if (origin !== "remote") {
+    closeForeignSegment(tab, writer);
+  }
   const selectionBefore = cloneSelection(tab.session.selection);
   const dirtyBefore = tab.doc.dirty;
   beginRecording();
@@ -287,8 +268,13 @@ export function transactDoc(
     }
   }
 
-  if (!skipHistory && !_batchTab) {
-    pushHistoryEntry(tab, raw, record, selectionBefore, coalesceKey);
+  if (!skipHistory) {
+    const lane = writer ? laneOwnedBy(writer) : null;
+    if (lane) {
+      joinSegment(lane, tab, record, selectionBefore);
+    } else {
+      pushHistoryEntry(tab, raw, record, selectionBefore, coalesceKey);
+    }
   }
 
   tab.doc.dirty = true;
@@ -404,7 +390,7 @@ function materializeState(
 export function transact(
   tab: Tab | null,
   fn: (doc: JxMutableNode) => void,
-  opts?: { skipHistory?: boolean; origin?: TransactOrigin },
+  opts?: TransactOptions,
 ): boolean {
   return transactDoc(tab, (t) => fn(t.doc.document), opts);
 }
@@ -431,6 +417,63 @@ export function applyExternalDocOps(tab: Tab, ops: JxDocOp[]) {
   );
 }
 
+/** What {@link applyDocOpsAsUser} did: wrote, had nothing to write, or was refused by the gate. */
+export type ApplyDocOpsResult = "applied" | "unchanged" | "refused";
+
+/**
+ * Apply ops a tool PRODUCED (rather than a mutator performing the edit itself) as one ordinary
+ * transaction: history, lanes, the gate, the canvas patch and the collab observer all see it as
+ * they see any edit. Each op's inverse is computed against the raw document just before that op
+ * lands, so a later op may address what an earlier one created, and the selection rule the producer
+ * named is applied inside the same transaction, so a rollback restores it too.
+ *
+ * Empty ops are no transaction at all: no new root, no history entry, nothing published
+ * (specs/ai.md §3.9). An op that cannot apply throws from `inverseOf` before it lands, and
+ * `transactDoc` rolls back the ones before it and rethrows.
+ *
+ * @param {Tab} tab
+ * @param {readonly JxDocOp[]} ops
+ * @param {{ actor?: ActorRef | null; selection?: SelectionEffect }} [options]
+ * @returns {ApplyDocOpsResult}
+ */
+export function applyDocOpsAsUser(
+  tab: Tab,
+  ops: readonly JxDocOp[],
+  {
+    actor = null,
+    selection = { kind: "keep" },
+  }: { actor?: ActorRef | null; selection?: SelectionEffect } = {},
+): ApplyDocOpsResult {
+  if (ops.length === 0) {
+    return "unchanged";
+  }
+  const applied = transactDoc(
+    tab,
+    (t) => {
+      for (const op of ops) {
+        applyDocOp(t, op, inverseOf(toRaw(t.doc.document), op));
+      }
+      applySelectionEffect(t, selection);
+    },
+    { actor },
+  );
+  return applied ? "applied" : "refused";
+}
+
+/** Carry the tab's selection across an edit, as the producer's {@link SelectionEffect} says. */
+function applySelectionEffect(tab: Tab, effect: SelectionEffect) {
+  if (effect.kind === "prune") {
+    for (const under of effect.under) {
+      tab.session.selection = pruneSelection(tab.session.selection, under);
+    }
+  } else if (
+    effect.kind === "follow" &&
+    pathsEqual(primarySelection(tab.session.selection), effect.from)
+  ) {
+    tab.session.selection = [[...effect.to]];
+  }
+}
+
 // ─── Document-op application ─────────────────────────────────────────────────
 
 /** Document-level keys whose changes require a full scope/panel rebuild on the canvas. */
@@ -442,8 +485,10 @@ const DOC_META_KEYS = new Set(["state", "$media", "$head", "$elements", "imports
  *
  * @param {Tab} tab
  * @param {JxDocOp} op
+ * @param {JxDocOp} inverse - The op that undoes this one: replay passes none (see below), a new
+ *   edit its real inverse
  */
-function applyDocOp(tab: Tab, op: JxDocOp) {
+function applyDocOp(tab: Tab, op: JxDocOp, inverse: JxDocOp = op) {
   let prev: JxDocumentValue | undefined | null = null;
   if (op.op === "set-key") {
     const node = getNodeAtPath(tab.doc.document, op.path);
@@ -456,10 +501,10 @@ function applyDocOp(tab: Tab, op: JxDocOp) {
   // Classified as applicable (suppressing the full render), and the canvas silently kept showing
   // The pre-undo content. Replaying an op IS a forward op — record it as one.
   //
-  // History never reads the inverse here: undo/redo run with `skipHistory`, and the entry they
+  // On replay history never reads the inverse: undo/redo run with `skipHistory`, and the entry they
   // Replay already holds the pair. `markNonInvertible` would be wrong (it forces a whole-document
-  // Checkpoint), so the op is paired with itself.
-  recordDocOp({ forward: op, inverse: op });
+  // Checkpoint), so a replayed op is paired with itself.
+  recordDocOp({ forward: op, inverse });
   switch (op.op) {
     case "set-key": {
       if (DOC_META_KEYS.has(op.key)) {
@@ -504,11 +549,78 @@ function applyDocOp(tab: Tab, op: JxDocOp) {
   }
 }
 
-// ─── Batch (group multiple mutations into one undo step) ────────────────────
+// ─── Batch lanes (one actor's run of writes, one undo step per document) ─────
+
+/**
+ * An actor that is not the person at the keyboard writing to a document. The assistant's
+ * `@jxsuite/ai` `Actor` is one: its `id` is `assistant:<sessionId|local>:<turnId>`.
+ */
+export interface ActorRef {
+  readonly kind: "user" | "assistant" | "remote";
+  readonly id: string;
+  readonly turnId?: string;
+}
+
+/** The options {@link transactDoc} takes. */
+export interface TransactOptions {
+  skipHistory?: boolean;
+  origin?: TransactOrigin;
+  coalesceKey?: string | null;
+  /** Who is writing; `null` (the default) is the person at the keyboard, or the open scope's. */
+  actor?: ActorRef | null;
+}
+
+/**
+ * One actor's run of writes that undoes as ONE step.
+ *
+ * A lane is open for a whole assistant turn. Each document it writes gets a **segment**, opened on
+ * the lane's first write there and closed when the lane flushes, or earlier when anyone else writes
+ * that document: the segment becomes one history entry and the other writer's edit becomes its own
+ * after it, so a person's edit is never folded into the assistant's step and the steps keep the
+ * order they happened in. A document the lane never wrote gets no entry at all.
+ */
+export interface BatchLane {
+  readonly owner: ActorRef;
+  /** Close every open segment now, one entry per document that recorded something. */
+  readonly flush: () => void;
+  /** Flush and retire the lane; returns where each of its entries landed, oldest first. */
+  readonly close: () => readonly BatchReceipt[];
+}
+
+/** Where one of a lane's segments landed in its tab's history. */
+export interface BatchReceipt {
+  readonly tab: Tab;
+  /**
+   * The history entry the segment became, compared by identity: its index moves when the history
+   * limit drops the oldest entry, the entry does not. Null on a tab whose undo a history delegate
+   * owns (a shared live document), where the step is the delegate's and no entry names it.
+   */
+  readonly entry: HistorySnapshot | null;
+  readonly turnId: string;
+}
+
+interface LaneState {
+  readonly owner: ActorRef;
+  readonly receipts: BatchReceipt[];
+}
+
+interface Segment {
+  readonly lane: LaneState;
+  readonly docOps: JxDocOpPair[];
+  readonly fmOps: TransactionRecord["fmOps"];
+  /** False once any write in it could not be inverted, or recorded no ops: the entry snapshots. */
+  invertible: boolean;
+  readonly selectionBefore: JxPath[];
+}
 
-let _batchTab: Tab | null = null;
+/** The open lanes, by owner id. */
+const _lanes = new Map<string, LaneState>();
+/** The open segment on each tab: at most one, since a second writer closes the first's. */
+const _segments = new Map<Tab, Segment>();
+/** The actor {@link runAsActor} is running as, for a writer that cannot pass one. */
+let _scopeActor: ActorRef | null = null;
 
-/** Module-level hook invoked when a batch closes (collab flushes its buffered ops as one step). */
+/** Module-level hook invoked when a segment closes (collab flushes its buffered ops as one step). */
 export type BatchEndNotifier = (tab: Tab) => void;
 
 let _batchEndNotifier: BatchEndNotifier | null = null;
@@ -517,48 +629,132 @@ export function setBatchEndNotifier(fn: BatchEndNotifier | null) {
   _batchEndNotifier = fn;
 }
 
-export function beginBatch(tab: Tab | null) {
-  _batchTab = tab;
+/**
+ * Open a lane for `owner`. Every transaction `owner` makes until {@link BatchLane.close} joins it;
+ * opening a second lane for the same owner replaces the first, after flushing it.
+ */
+export function openBatchLane(owner: ActorRef): BatchLane {
+  const previous = _lanes.get(owner.id);
+  if (previous) {
+    flushLane(previous);
+  }
+  const lane: LaneState = { owner, receipts: [] };
+  _lanes.set(owner.id, lane);
+  return {
+    owner,
+    flush: () => flushLane(lane),
+    close: () => {
+      flushLane(lane);
+      if (_lanes.get(owner.id) === lane) {
+        _lanes.delete(owner.id);
+      }
+      return [...lane.receipts];
+    },
+  };
 }
 
-export function endBatch() {
-  const tab = _batchTab;
-  // A history delegate owns undo grouping while registered; the snapshot push would be dead weight.
-  if (tab && !_historyDelegates.has(tab)) {
-    const raw = toRaw(tab.doc.document);
-    const snapshot = {
-      document: jsonClone(raw),
-      selection: cloneSelection(tab.session.selection),
-    };
-    const truncated = tab.history.snapshots.slice(0, tab.history.index + 1);
-    truncated.push(snapshot);
-    if (truncated.length > HISTORY_LIMIT) {
-      truncated.shift();
+/**
+ * Run `fn` with every transaction it makes attributed to `actor`.
+ *
+ * **Synchronous only.** The scope ends when `fn` returns, before any await inside it resumes, so a
+ * write made after an await is the person's again. That is deliberate: a scope that outlived its
+ * call would attribute whatever the person did in the meantime to the assistant. A writer that
+ * awaits before it writes passes `actor` to {@link transactDoc} instead.
+ */
+export function runAsActor<T>(actor: ActorRef, fn: () => T): T {
+  const previous = _scopeActor;
+  _scopeActor = actor;
+  try {
+    return fn();
+  } finally {
+    _scopeActor = previous;
+  }
+}
+
+/**
+ * Whether `tab` has an open segment: owned by `actor` when one is given, by anyone otherwise.
+ * Collab reads this to buffer the owner's ops until the segment closes.
+ */
+export function isBatched(tab: Tab, actor?: ActorRef | null): boolean {
+  const segment = _segments.get(tab);
+  return segment !== undefined && (!actor || segment.lane.owner.id === actor.id);
+}
+
+/** Close every open segment of every lane (a project is about to be replaced under them). */
+export function flushOpenBatches(): void {
+  for (const lane of _lanes.values()) {
+    flushLane(lane);
+  }
+}
+
+function laneOwnedBy(actor: ActorRef): LaneState | null {
+  return _lanes.get(actor.id) ?? null;
+}
+
+function flushLane(lane: LaneState): void {
+  // Deleting the entry being visited is safe: a Map iterator skips removed entries and goes on.
+  for (const [tab, segment] of _segments) {
+    if (segment.lane === lane) {
+      closeSegment(tab, segment);
     }
-    tab.history.snapshots = truncated;
-    tab.history.index = truncated.length - 1;
   }
-  _batchTab = null;
-  if (tab) {
-    _batchEndNotifier?.(tab);
+}
+
+/** Fold a lane owner's transaction into its segment on `tab`, opening the segment if needed. */
+function joinSegment(
+  lane: LaneState,
+  tab: Tab,
+  record: TransactionRecord,
+  selectionBefore: JxPath[],
+): void {
+  let segment = _segments.get(tab);
+  if (!segment) {
+    segment = { docOps: [], fmOps: [], invertible: true, lane, selectionBefore };
+    _segments.set(tab, segment);
+  }
+  segment.docOps.push(...record.docOps);
+  segment.fmOps.push(...record.fmOps);
+  /* An unrecorded mutation changed the document without saying how, so only a snapshot of the
+     result can undo the segment it is in. */
+  if (!record.invertible || (record.docOps.length === 0 && record.fmOps.length === 0)) {
+    segment.invertible = false;
   }
 }
 
-export function isBatching(): boolean {
-  return _batchTab !== null;
+/** A writer other than the segment's owner is about to write `tab`: close the segment first. */
+function closeForeignSegment(tab: Tab, writer: ActorRef | null): void {
+  const segment = _segments.get(tab);
+  if (segment && segment.lane.owner.id !== writer?.id) {
+    closeSegment(tab, segment);
+  }
 }
 
-/**
- * Which tab the open batch belongs to, or `null` when none is open.
- *
- * The agent loop needs this to keep a batch honest across a tab change. A batch is opened against
- * one tab and closed against the same one — {@link endBatch} pushes ITS history snapshot and fires
- * the collab notifier for IT — so a loop whose tools moved to a second document has to close the
- * first batch and open a second, or the second document's edits get neither a history entry nor a
- * collab publish. Reading the batched tab is how the loop can tell.
- */
-export function batchTab(): Tab | null {
-  return _batchTab;
+/** Push the segment as one history entry tagged with its owner, then let collab publish it. */
+function closeSegment(tab: Tab, segment: Segment): void {
+  _segments.delete(tab);
+  const { owner } = segment.lane;
+  const turnId = owner.turnId ?? "";
+  /* A history delegate owns undo grouping while registered; an entry here would be dead weight.
+     The receipt is still issued, with no entry, so Restore can tell a step it cannot check from a
+     document the turn never wrote. */
+  if (_historyDelegates.has(tab)) {
+    segment.lane.receipts.push({ entry: null, tab, turnId });
+  } else {
+    const record: TransactionRecord = {
+      docOps: segment.docOps,
+      fmOps: segment.fmOps,
+      invertible: segment.invertible,
+      ops: [],
+    };
+    pushHistoryEntry(tab, toRaw(tab.doc.document), record, segment.selectionBefore);
+    const entry = tab.history.snapshots[tab.history.index]!;
+    entry.actor = owner.id;
+    if (owner.turnId !== undefined) {
+      entry.turnId = owner.turnId;
+    }
+    segment.lane.receipts.push({ entry, tab, turnId });
+  }
+  _batchEndNotifier?.(tab);
 }
 
 // ─── Undo / Redo ─────────────────────────────────────────────────────────────
@@ -591,12 +787,17 @@ export function getHistoryDelegate(tab: Tab): HistoryDelegate | null {
 
 export function canUndo(tab: Tab): boolean {
   const delegate = _historyDelegates.get(tab);
-  return delegate ? delegate.canUndo(tab) : tab.history.index > 0;
+  // An open segment is a step that has not been pushed yet; undo closes it and then takes it back.
+  return delegate ? delegate.canUndo(tab) : tab.history.index > 0 || _segments.has(tab);
 }
 
 export function canRedo(tab: Tab): boolean {
   const delegate = _historyDelegates.get(tab);
-  return delegate ? delegate.canRedo(tab) : tab.history.index < tab.history.snapshots.length - 1;
+  /* An open segment has already changed the document past the redo stack, and closing it truncates
+     that stack, so there is nothing to redo while one is open. */
+  return delegate
+    ? delegate.canRedo(tab)
+    : !_segments.has(tab) && tab.history.index < tab.history.snapshots.length - 1;
 }
 
 /** Restore a materialized snapshot state (full-render path). */
@@ -627,6 +828,10 @@ function assertHistoryConsistency(tab: Tab, index: number) {
 
 /** @param {Tab} tab */
 export function undo(tab: Tab) {
+  /* Undo is the person's, so a segment open on this tab closes first and becomes the step undo
+     takes back. Without this, ⌘Z mid-turn would skip the assistant's pending edits and undo the
+     entry before them, leaving the segment's inverses pointing at a document they no longer fit. */
+  closeForeignSegment(tab, null);
   const delegate = _historyDelegates.get(tab);
   if (delegate) {
     delegate.undo(tab);
@@ -678,6 +883,8 @@ export function undo(tab: Tab) {
 
 /** @param {Tab} tab */
 export function redo(tab: Tab) {
+  // Same as {@link undo}: an open segment is history the redo stack is about to be measured against.
+  closeForeignSegment(tab, null);
   const delegate = _historyDelegates.get(tab);
   if (delegate) {
     delegate.redo(tab);
@@ -740,11 +947,16 @@ export function mutateInsertNode(
   if (!parent) {
     return;
   }
-  childArray(parent).splice(index, 0, structuredClone(nodeDef));
-  recordPatch({ index, op: "insert", parentPath });
+  const children = childArray(parent);
+  /* Recorded at the slot the node lands in, not the one asked for: `splice` appends past the end,
+     and an op naming index 9 of a two-child list replays wrongly anywhere that does not clamp (the
+     collab mirror throws on it) and undoes by removing nothing. */
+  const slot = insertionSlot(index, children.length);
+  children.splice(slot, 0, structuredClone(nodeDef));
+  recordPatch({ index: slot, op: "insert", parentPath });
   recordDocOp({
-    forward: { index, node: cloneValue(nodeDef), op: "insert-child", parentPath },
-    inverse: { index, op: "remove-child", parentPath },
+    forward: { index: slot, node: cloneValue(nodeDef), op: "insert-child", parentPath },
+    inverse: { index: slot, op: "remove-child", parentPath },
   });
 }
 
@@ -905,50 +1117,26 @@ export function mutateWrapNode(tab: Tab, path: JxPath, wrapperTag = "div") {
  */
 export function mutateMoveNode(tab: Tab, fromPath: JxPath, toParentPath: JxPath, toIndex: number) {
   const doc = tab.doc.document;
-  const fromParentPath = parentElementPath(fromPath);
-  const fromIdx = childIndex(fromPath);
-  if (!fromParentPath || !isNumber(fromIdx)) {
-    return;
-  }
-  const fromParent = getNodeAtPath(doc, fromParentPath);
-  const toParent = getNodeAtPath(doc, toParentPath);
-  if (!fromParent || !Array.isArray(fromParent.children) || !toParent) {
+  const move = planMove(doc, fromPath, toParentPath, toIndex);
+  if (!move) {
     return;
   }
-  if (fromParent.children[fromIdx] === undefined) {
-    return;
-  }
-  let adjustedIndex = toIndex;
-  if (fromParent === toParent && fromIdx < toIndex) {
-    adjustedIndex -= 1;
-  }
-  const forward: JxDocOp = {
-    fromIndex: fromIdx,
-    fromParentPath,
-    op: "move-child",
-    toIndex: adjustedIndex,
-    toParentPath,
-  };
-  /* Computed BEFORE the splice, against the document the move applies to. The inverse runs against
-     the post-move document, so `inverseOf` writes both of its parent paths in post-move
-     coordinates: the removal shifted paths under the source parent, the insertion paths under the
-     target. One implementation of that rule, shared with every other host that moves a node. */
-  const inverse = inverseOf(doc, forward);
-  const [node] = fromParent.children.splice(fromIdx, 1);
-  childArray(toParent).splice(adjustedIndex, 0, node!);
-  recordPatch({ fromPath, op: "move", toIndex: adjustedIndex, toParentPath });
+  const { forward, inverse } = move;
+  /* SAFETY: `planMove` resolved both parents as nodes, and the source's children as a static
+     array holding a child at `fromIndex`. */
+  const fromParent = getNodeAtPath(doc, forward.fromParentPath)!;
+  const toParent = getNodeAtPath(doc, toParentPath)!;
+  // SAFETY: as above, the source parent's children are a static array (`planMove` checked).
+  const [node] = (fromParent.children as (JxMutableNode | string)[]).splice(forward.fromIndex, 1);
+  childArray(toParent).splice(forward.toIndex, 0, node!);
+  recordPatch({ fromPath, op: "move", toIndex: forward.toIndex, toParentPath });
   recordDocOp({ forward, inverse });
 
+  /* The moved node's own post-move path is where its inverse picks it up. Writing the target path
+     as given would be wrong whenever the removal renumbered it: moving `children/0` into
+     `children/2` lands inside what is now `children/1`. */
   if (pathsEqual(primarySelection(tab.session.selection), fromPath)) {
-    let idx = toIndex;
-    if (
-      fromParentPath.length === toParentPath.length &&
-      fromParentPath.every((v, i) => v === toParentPath[i]) &&
-      fromIdx < toIndex
-    ) {
-      idx = toIndex - 1;
-    }
-    tab.session.selection = [[...toParentPath, "children", idx]];
+    tab.session.selection = [[...inverse.fromParentPath, "children", inverse.fromIndex]];
   }
 }
 
@@ -984,6 +1172,10 @@ export function mutateUpdateProperty(tab: Tab, path: JxPath, key: string, value?
     node[key] = value;
   }
   recordDocOp(setKeyPair(path, key, before, cloneValue(node[key])));
+  // Replacing the children replaces every node under them, so nothing selected there survives.
+  if (key === "children") {
+    tab.session.selection = pruneSelection(tab.session.selection, [...path, "children"]);
+  }
   if (key === "textContent") {
     recordPatch({ op: "set-text", path });
   } else if (key === "style") {

package/src/types.ts

@@ -361,16 +361,21 @@ export interface StudioPlatform {
    */
   assetCapabilities?: AssetCapabilities;
   activate: (root?: string) => Promise<void>;
-  openProject: () => Promise<{
+  /**
+   * Present a native project dialog and bind the chosen project to this window. Absent (the dev
+   * server, whose windows open a project from `?project=`), and with no `openProjectPicker` either,
+   * Studio offers no Open Project at all.
+   */
+  openProject?: () => Promise<{
     config: ProjectConfig;
     handle: { root: string; name: string; projectConfig: ProjectConfig };
   } | null>;
   /**
-   * How "Open Project" picks a project. Absent: `openProject()` owns picking (native dialog /
-   * showDirectoryPicker). `"repo-list"`: Studio shows its repository picker over `listRepos` +
-   * `importProject` (write-access repositories) and opens the choice through the recent-projects
-   * path — `openProject()` is never called. Cloud sets this: its sessions are URL-bound, so there
-   * is no backend dialog to delegate to.
+   * How "Open Project" picks a project. Absent: `openProject()` owns picking (the native dialog).
+   * `"repo-list"`: Studio shows its repository picker over `listRepos` + `importProject`
+   * (write-access repositories) and opens the choice through the recent-projects path —
+   * `openProject()` is never called. Cloud sets this: its sessions are URL-bound, so there is no
+   * backend dialog to delegate to.
    */
   openProjectPicker?: "repo-list";
   probeRootProject: () => Promise<{
@@ -677,8 +682,8 @@ export interface StudioPlatform {
   ) => Promise<{ root: string; config: ProjectConfig; result?: ImportSiteSummary }>;
   /**
    * Open a native directory picker and return the chosen absolute path. Backs the New Project
-   * modal's **Browse…** button on `createDestination: "path"` platforms: desktop (the system
-   * dialog), and the dev server in a browser that has `showDirectoryPicker` (Chromium-based).
+   * modal's **Browse…** button on `createDestination: "path"` platforms that have a native dialog
+   * (desktop). The dev server has none, so its Location field is typed.
    *
    * Resolves `null` only when the user cancels; rejects with a displayable Error otherwise. The
    * modal shows that message under the Location field, and typing a path clears it. A picker that