@jxsuite/studio 2.0.1 → 2.1.0

package/src/tabs/transact.ts

@@ -1,7 +1,14 @@
 /// <reference lib="dom" />
 import { toRaw } from "../reactivity";
 import { jsonClone } from "../utils/studio-utils";
-import { childIndex, getNodeAtPath, isAncestor, parentElementPath, pathsEqual } from "../state";
+import { childIndex, getNodeAtPath, parentElementPath, pathsEqual } from "../state";
+import {
+  cloneSelection,
+  isSpliceablePath,
+  primarySelection,
+  pruneSelection,
+  structuralBatch,
+} from "./selection";
 import { applyDocOpToDoc, childArray, cloneValue } from "./doc-op-apply";
 import {
   beginRecording,
@@ -125,13 +132,68 @@ export function setTransactGate(fn: TransactGate | null) {
   _transactGate = fn;
 }
 
+/**
+ * Undo a transaction that threw part-way through, using the pairs it managed to record.
+ *
+ * **Why the inverses are enough.** Every mutator records its op AFTER its splice or assignment
+ * succeeds, so `record.docOps` describes exactly the changes that landed — no more, no less.
+ * Replaying their inverses in reverse is the same replay `undo` performs on a committed entry, run
+ * against a document that never got a history entry. A mutator that changed the document WITHOUT
+ * recording is already broken for undo; this is no weaker a guarantee than the one history gives.
+ *
+ * The document root reference is replaced so every effect re-reads, and nothing is marked consumed
+ * — the canvas takes the full-render path, because the patch ops recorded for the half-applied
+ * state describe changes that no longer exist.
+ */
+function rollbackFailedTransaction(
+  tab: Tab,
+  record: TransactionRecord,
+  selectionBefore: JxPath[],
+  dirtyBefore: boolean,
+) {
+  for (let i = record.docOps.length - 1; i >= 0; i--) {
+    applyDocOpToDoc(tab.doc.document, toRaw(record.docOps[i]!.inverse) as JxDocOp);
+  }
+  for (let i = record.fmOps.length - 1; i >= 0; i--) {
+    const op = record.fmOps[i]!;
+    applyFmState(tab, op.field, op.before);
+  }
+  tab.doc.document = { ...toRaw(tab.doc.document) };
+  // Mutators repair the selection as they go (`pruneSelection`, "select the clone"); rolling their
+  // Edits back and leaving the selection pointing at coordinates that no longer exist would be its
+  // Own corruption.
+  tab.session.selection = selectionBefore;
+  // `mutateUpdateFrontmatter` marks the tab dirty itself, mid-mutation. Rolling its write back and
+  // Leaving the mark standing would report unsaved changes that no longer exist; restoring the
+  // Captured value is right in both directions, since nothing but this transaction could have
+  // Moved it.
+  tab.doc.dirty = dirtyBefore;
+}
+
 /**
  * Apply a document mutation transactionally: push to history and mark dirty. The mutationFn
  * receives the tab and should mutate tab.doc.document in place.
  *
+ * **All of it or none of it.** A mutationFn that throws part-way — a batch whose third splice hits
+ * a coordinate that is not one — used to leave the earlier splices standing in the live reactive
+ * tree while the throw skipped the new document reference, the history entry, the dirty mark and
+ * the collab observer: the document was changed on screen, unreachable by undo, and invisible to
+ * Save. The exception now rolls the applied ops back ({@link rollbackFailedTransaction}) and only
+ * then rethrows, so a failed transaction is indistinguishable from one that never ran.
+ *
+ * **AND IT SAYS WHETHER IT WROTE**, because {@link setTransactGate} made "returned normally" and
+ * "changed the document" two different facts and nothing downstream could tell them apart. Under
+ * the source-canonical freeze the dock's body commit is refused here — and its caller went on to
+ * mark the buffer settled, so `tabBufferUnsaved`, `shouldWarnOnClose` and `hasUnsavedTabs` all
+ * reported "nothing to lose" about text that only existed in the buffer. Every close then took it
+ * 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.
+ *
  * @param {Tab | null} tab
  * @param {(tab: Tab) => void} mutationFn
  * @param {{ skipHistory?: boolean; origin?: TransactOrigin }} [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,
@@ -141,21 +203,31 @@ export function transactDoc(
     origin = "user",
     coalesceKey = null,
   }: { skipHistory?: boolean; origin?: TransactOrigin; coalesceKey?: string | null } = {},
-) {
+): boolean {
   if (!tab) {
-    return;
+    return false;
   }
   if (origin !== "remote" && _transactGate?.(tab, origin)) {
-    return;
+    return false;
   }
-  const selectionBefore = tab.session.selection ? [...tab.session.selection] : null;
+  const selectionBefore = cloneSelection(tab.session.selection);
+  const dirtyBefore = tab.doc.dirty;
   beginRecording();
   let record: TransactionRecord;
+  let failure: { error: unknown } | null = null;
   try {
     mutationFn(tab);
+  } catch (error) {
+    // Boxed rather than tested for truthiness: a mutation is free to throw a falsy value, and
+    // "did it throw" must not become "was what it threw interesting".
+    failure = { error };
   } finally {
     record = endRecording();
   }
+  if (failure) {
+    rollbackFailedTransaction(tab, record, selectionBefore, dirtyBefore);
+    throw failure.error;
+  }
 
   // Replace the document root reference so effects tracking tab.doc.document re-trigger.
   // Nested objects are shared — the mutation already modified them in place.
@@ -174,7 +246,7 @@ export function transactDoc(
         ? { patchable: false, reason: "unrecorded-mutation" }
         : consumer.classify(tab, record.ops);
   if (verdict.patchable) {
-    consumer!.markConsumed(newRef);
+    consumer!.markConsumed(newRef, tab);
   }
 
   tab.doc.document = newRef;
@@ -185,6 +257,7 @@ export function transactDoc(
     } catch (error) {
       consumer!.escalate(
         `patch-apply-failed: ${error instanceof Error ? error.message : String(error)}`,
+        tab,
       );
     }
   }
@@ -196,6 +269,7 @@ export function transactDoc(
   tab.doc.dirty = true;
 
   _transactObserver?.(tab, record, origin);
+  return true;
 }
 
 /**
@@ -207,13 +281,13 @@ export function transactDoc(
  * @param {Tab} tab
  * @param {JxMutableNode} raw Post-mutation raw document
  * @param {TransactionRecord} record
- * @param {JxPath | null} selectionBefore
+ * @param {JxPath[]} selectionBefore
  */
 function pushHistoryEntry(
   tab: Tab,
   raw: JxMutableNode,
   record: TransactionRecord,
-  selectionBefore: JxPath | null,
+  selectionBefore: JxPath[],
   coalesceKey: string | null = null,
 ) {
   const truncated = tab.history.snapshots.slice(0, tab.history.index + 1);
@@ -234,7 +308,7 @@ function pushHistoryEntry(
     // Leaving the node holding both keys at once. Undo replays inverses in reverse order, so
     // Appending yields "undo the last commit, then the one before it, …".
     prev.inverseOps = [...prev.inverseOps, ...record.docOps.map((pair) => pair.inverse)];
-    prev.selection = tab.session.selection ? [...tab.session.selection] : null;
+    prev.selection = cloneSelection(tab.session.selection);
     if (prev.document) {
       prev.document = jsonClone(raw);
     }
@@ -250,7 +324,7 @@ function pushHistoryEntry(
     forwardOps: useOps ? record.docOps.map((p) => p.forward) : null,
     inverseOps: useOps ? record.docOps.map((p) => p.inverse) : null,
     coalesceKey,
-    selection: tab.session.selection ? [...tab.session.selection] : null,
+    selection: cloneSelection(tab.session.selection),
     selectionBefore,
   });
   if (truncated.length > HISTORY_LIMIT) {
@@ -299,13 +373,14 @@ function materializeState(
  * @param {Tab | null} tab
  * @param {(doc: JxMutableNode) => void} fn
  * @param {{ skipHistory?: boolean; origin?: TransactOrigin }} [opts]
+ * @returns {boolean} Whatever {@link transactDoc} answered — whether the mutation was applied.
  */
 export function transact(
   tab: Tab | null,
   fn: (doc: JxMutableNode) => void,
   opts?: { skipHistory?: boolean; origin?: TransactOrigin },
-) {
-  transactDoc(tab, (t) => fn(t.doc.document), opts);
+): boolean {
+  return transactDoc(tab, (t) => fn(t.doc.document), opts);
 }
 
 /**
@@ -424,7 +499,7 @@ export function endBatch() {
     const raw = toRaw(tab.doc.document);
     const snapshot = {
       document: jsonClone(raw),
-      selection: tab.session.selection ? [...tab.session.selection] : null,
+      selection: cloneSelection(tab.session.selection),
     };
     const truncated = tab.history.snapshots.slice(0, tab.history.index + 1);
     truncated.push(snapshot);
@@ -444,6 +519,19 @@ export function isBatching(): boolean {
   return _batchTab !== null;
 }
 
+/**
+ * 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;
+}
+
 // ─── Undo / Redo ─────────────────────────────────────────────────────────────
 
 /**
@@ -487,7 +575,7 @@ function restoreState(tab: Tab, index: number) {
   const { snapshots } = tab.history;
   tab.doc.document = materializeState(snapshots, index);
   const snap = snapshots[index]!;
-  tab.session.selection = snap.selection ? [...toRaw(snap.selection)] : null;
+  tab.session.selection = cloneSelection(toRaw(snap.selection));
 }
 
 /** Debug-flag assertion: ops-based undo/redo must land on the same state replay produces. */
@@ -524,7 +612,7 @@ export function undo(tab: Tab) {
   if ((inverseOps && inverseOps.length > 0) || (fmOps && fmOps.length > 0)) {
     // Surgical path: apply inverse ops through the normal transaction pipeline (the canvas
     // Patches in place when it can), in reverse recording order.
-    transactDoc(
+    const applied = transactDoc(
       tab,
       (t) => {
         if (inverseOps) {
@@ -541,7 +629,15 @@ export function undo(tab: Tab) {
       },
       { origin: "history", skipHistory: true },
     );
-    tab.session.selection = entry.selectionBefore ? [...toRaw(entry.selectionBefore)] : null;
+    /* A REFUSED REPLAY IS NOT A STEP TAKEN. `"history"` is not `"remote"`, so the gate refuses this
+       exactly as it refuses a direct edit — and everything below assumed the ops landed. Moving the
+       index over a document that did not change desynchronises the log from the tree: the next redo
+       replays a forward op onto a state it was never the inverse of, and `doc.dirty` claims an edit
+       nobody made. Undo that cannot run is undo that does nothing, which is the honest answer. */
+    if (!applied) {
+      return;
+    }
+    tab.session.selection = cloneSelection(toRaw(entry.selectionBefore ?? []));
     tab.history.index -= 1;
     assertHistoryConsistency(tab, tab.history.index);
   } else {
@@ -565,7 +661,7 @@ export function redo(tab: Tab) {
   const forwardOps = patchHistoryEnabled() ? entry.forwardOps : null;
   const fmOps = patchHistoryEnabled() ? entry.fmOps : null;
   if ((forwardOps && forwardOps.length > 0) || (fmOps && fmOps.length > 0)) {
-    transactDoc(
+    const applied = transactDoc(
       tab,
       (t) => {
         if (forwardOps) {
@@ -582,7 +678,12 @@ export function redo(tab: Tab) {
       },
       { origin: "history", skipHistory: true },
     );
-    tab.session.selection = entry.selection ? [...toRaw(entry.selection)] : null;
+    // Same as {@link undo}: a refused replay leaves the document alone, so the index must stay
+    // Where it is or the log stops describing the tree.
+    if (!applied) {
+      return;
+    }
+    tab.session.selection = cloneSelection(toRaw(entry.selection));
     tab.history.index += 1;
     assertHistoryConsistency(tab, tab.history.index);
   } else {
@@ -619,11 +720,18 @@ export function mutateInsertNode(
 }
 
 /**
+ * Remove the node at `path` from its parent's children array.
+ *
+ * The guard is {@link isSpliceablePath}, not `path.length < 2`: the shorter test admits the
+ * Outline's map-template and `$switch`-case rows, whose `parentElementPath` is a children ARRAY
+ * rather than a node — `.children.splice` on it throws, and the throw is what left a batch's
+ * earlier removals applied and unrecorded.
+ *
  * @param {Tab} tab
  * @param {JxPath} path
  */
 export function mutateRemoveNode(tab: Tab, path: JxPath) {
-  if (!path || path.length < 2) {
+  if (!path || !isSpliceablePath(path)) {
     return;
   }
   const elemPath = parentElementPath(path) as JxPath;
@@ -637,9 +745,7 @@ export function mutateRemoveNode(tab: Tab, path: JxPath) {
     forward: { index: idx, op: "remove-child", parentPath: elemPath },
     inverse: { index: idx, node: cloneValue(removed), op: "insert-child", parentPath: elemPath },
   });
-  if (tab.session.selection && isAncestor(path, tab.session.selection)) {
-    tab.session.selection = null;
-  }
+  tab.session.selection = pruneSelection(tab.session.selection, path);
 }
 
 /**
@@ -647,7 +753,7 @@ export function mutateRemoveNode(tab: Tab, path: JxPath) {
  * @param {JxPath} path
  */
 export function mutateDuplicateNode(tab: Tab, path: JxPath) {
-  if (!path || path.length < 2) {
+  if (!path || !isSpliceablePath(path)) {
     return;
   }
   const node = getNodeAtPath(tab.doc.document, path);
@@ -663,7 +769,66 @@ export function mutateDuplicateNode(tab: Tab, path: JxPath) {
     forward: { index: idx + 1, node: cloneValue(clone), op: "insert-child", parentPath: elemPath },
     inverse: { index: idx + 1, op: "remove-child", parentPath: elemPath },
   });
-  tab.session.selection = [...elemPath, "children", idx + 1];
+  tab.session.selection = [[...elemPath, "children", idx + 1]];
+}
+
+/**
+ * Remove every selected node, in ONE transaction and therefore ONE undo step (§6.5).
+ *
+ * Three things make a batch different from a loop. `structuralBatch` drops paths contained by
+ * another selected path — deleting a `<section>` and a paragraph inside it is one deletion — drops
+ * paths that name no splice coordinate at all (the document element, a repeater's map template, a
+ * `$switch` case, each of which the Outline offers as a ctrl-clickable row), and orders what
+ * survives LAST-node-first, so each splice happens above coordinates no later step depends on. A
+ * forward loop would delete `children/0` and then `children/1`, which by then is the node that used
+ * to be `children/2`.
+ *
+ * Selection repair is `mutateRemoveNode`'s, applied once per removal: a path is dropped when the
+ * node it addresses has gone. With a single path in, that is exactly the old behaviour — the
+ * selection ends up empty.
+ *
+ * @param {Tab} tab
+ * @param {readonly JxPath[]} paths
+ */
+export function mutateRemoveNodes(tab: Tab, paths: readonly JxPath[]) {
+  for (const path of structuralBatch(paths)) {
+    mutateRemoveNode(tab, path);
+  }
+}
+
+/**
+ * Duplicate every selected node in one transaction, selecting the clones.
+ *
+ * Same descending order, for the same reason: inserting a clone at `idx + 1` renumbers every later
+ * sibling, so the batch starts at the last. The resulting selection is the clones in document
+ * order, which means a duplicate-then-duplicate-again walks down the page the way repeating the
+ * single-node command always did.
+ *
+ * @param {Tab} tab
+ * @param {readonly JxPath[]} paths
+ */
+export function mutateDuplicateNodes(tab: Tab, paths: readonly JxPath[]) {
+  let clones: JxPath[] = [];
+  for (const path of structuralBatch(paths)) {
+    const before = tab.session.selection;
+    mutateDuplicateNode(tab, path);
+    const made = primarySelection(tab.session.selection);
+    // `mutateDuplicateNode` refuses a path that addresses nothing and leaves the selection alone;
+    // Only a real insertion contributes a clone.
+    if (!made || tab.session.selection === before) {
+      continue;
+    }
+    // Descending order keeps the ORIGINALS valid, but not the clones already made: this insertion
+    // Sits before them, so every one of their coordinates moved up by one. Translating them here
+    // Is the difference between "the copies are selected" and "two of the originals are".
+    const parentPath = parentElementPath(made) as JxPath;
+    const spliceIndex = childIndex(made) as number;
+    clones = clones.map((clone) => shiftPrefixedIndex(parentPath, clone, spliceIndex, 1, true));
+    clones.unshift(made);
+  }
+  if (clones.length > 0) {
+    tab.session.selection = clones;
+  }
 }
 
 /**
@@ -672,7 +837,7 @@ export function mutateDuplicateNode(tab: Tab, path: JxPath) {
  * @param {string} wrapperTag
  */
 export function mutateWrapNode(tab: Tab, path: JxPath, wrapperTag = "div") {
-  if (!path || path.length < 2) {
+  if (!path || !isSpliceablePath(path)) {
     return;
   }
   const node = getNodeAtPath(tab.doc.document, path);
@@ -692,7 +857,7 @@ export function mutateWrapNode(tab: Tab, path: JxPath, wrapperTag = "div") {
     forward: { index: idx, node: cloneValue(wrapper), op: "set-child", parentPath: elemPath },
     inverse: { index: idx, node: original, op: "set-child", parentPath: elemPath },
   });
-  tab.session.selection = [...elemPath, "children", idx];
+  tab.session.selection = [[...elemPath, "children", idx]];
 }
 
 /**
@@ -743,7 +908,7 @@ export function mutateMoveNode(tab: Tab, fromPath: JxPath, toParentPath: JxPath,
     },
   });
 
-  if (pathsEqual(tab.session.selection, fromPath)) {
+  if (pathsEqual(primarySelection(tab.session.selection), fromPath)) {
     let idx = toIndex;
     if (
       fromParentPath.length === toParentPath.length &&
@@ -752,11 +917,24 @@ export function mutateMoveNode(tab: Tab, fromPath: JxPath, toParentPath: JxPath,
     ) {
       idx = toIndex - 1;
     }
-    tab.session.selection = [...toParentPath, "children", idx];
+    tab.session.selection = [[...toParentPath, "children", idx]];
   }
 }
 
 /**
+ * Set (or, for an empty value, delete) one property on the node `path` names.
+ *
+ * **A path that no longer resolves is a no-op, not a throw.** `getNodeAtPath` answers `undefined`
+ * for a coordinate that has been deleted, and `node[key]` on that is `undefined is not an object` —
+ * an exception thrown from inside a mutation, which {@link transactDoc} correctly rolls back and
+ * rethrows into whatever asked for the edit. For a panel that is one stale click; for the dock's
+ * debounced body commit it escaped through `commitBufferWrites` and out of the dock's
+ * `afterRender`, aborting the repaint with the editor undisposed and its 500ms timer still armed.
+ * Deletions arrive from collaborators and from the author's own undo while an editor is open, so a
+ * stale path is an ordinary state of the document rather than a programming error, and the ordinary
+ * answer is to change nothing. Callers that must distinguish "wrote" from "nothing to write to"
+ * resolve the node themselves first — `panels/editors.ts`'s `bodyWriter` does exactly that.
+ *
  * @param {Tab} tab
  * @param {JxPath} path
  * @param {string} key
@@ -764,6 +942,9 @@ export function mutateMoveNode(tab: Tab, fromPath: JxPath, toParentPath: JxPath,
  */
 export function mutateUpdateProperty(tab: Tab, path: JxPath, key: string, value?: JxNodeValue) {
   const node = getNodeAtPath(tab.doc.document, path);
+  if (!node) {
+    return;
+  }
   const prev = node[key];
   const before = cloneValue(prev);
   if (value === undefined || value === null || value === "") {

package/src/types.ts

@@ -38,6 +38,7 @@ import type {
   ProjectListEntry,
   ProjectSchemasResponse,
   RecentProjectEntry,
+  ReferencesResult,
   RenameResult,
   SecretsSetRequest,
   SecretsSetResponse,
@@ -85,6 +86,9 @@ export type {
   ProjectSchemasResponse,
   PullRequestInfo,
   RecentProjectEntry,
+  ReferenceFile,
+  ReferenceHit,
+  ReferencesResult,
   RenameResult,
   SecretsListResponse,
   SecretsSetRequest,
@@ -130,6 +134,28 @@ export type CreateProjectDestination =
   | { kind: "path"; parent: string }
   | { kind: "repo"; owner: string; repo: string; private: boolean };
 
+/**
+ * What a site build reports back.
+ *
+ * `errors` is a list rather than a thrown exception because a partial build still produced pages:
+ * the author is better served by opening the page they asked for with the failures named beside it
+ * than by a refusal that says only that something went wrong.
+ */
+export interface SiteBuildResult {
+  routes: number;
+  files: number;
+  errors: string[];
+  /**
+   * Origin the built site is browsable at, e.g. `http://127.0.0.1:41234`.
+   *
+   * The backend names it because only the backend knows it: the built site is served on a port of
+   * its own, not on the editor's, since the editor's paths mean the project's SOURCES and a built
+   * page means its own output by the very same paths. Absent when the backend serves no preview,
+   * and `View: Open in Browser` then says so rather than guessing an origin.
+   */
+  url?: string;
+}
+
 export interface StudioPlatform {
   id: string;
   projectRoot: string;
@@ -167,6 +193,20 @@ export interface StudioPlatform {
   uploadFile: (path: string, data: string | File | Blob | ArrayBuffer) => Promise<unknown>;
   deleteFile: (path: string) => Promise<void>;
   renameFile: (from: string, to: string) => Promise<RenameResult>;
+  /**
+   * Where a file or a component tag is used across the project — the read side of the same walker
+   * `renameFile` writes through. Backs `capability.findReferences`, and with it the inspector's
+   * "Used on N pages", `Selection: Find Usages`, and the reference count inside every delete and
+   * rename confirmation.
+   *
+   * Optional so a backend without the route hides those three renderings rather than reporting a
+   * confident zero — the one answer a destructive dialog must never invent. Every shipped host
+   * implements it: the walker lives in `@jxsuite/server`, which desktop and cloud both run.
+   *
+   * At least one of `path` / `tagName` must be given. A `path` naming a component document
+   * contributes its own root tag, so one call answers "as a file AND as an element" together.
+   */
+  findReferences?: (target: { path?: string; tagName?: string }) => Promise<ReferencesResult>;
   createDirectory: (path: string) => Promise<void>;
   /**
    * Subscribe to backend filesystem change events for the active project. Returns an unsubscribe
@@ -266,6 +306,15 @@ export interface StudioPlatform {
   gitDiscard: (files: string[]) => Promise<void>;
   gitClone?: (url: string) => Promise<{ ok: boolean; root: string }>;
   gitInit: () => Promise<void>;
+  /**
+   * Build the site to its output directory, so a reader opens what the author is looking at.
+   *
+   * `View: Open in Browser` runs this first and reports what it says. Optional because it is a
+   * capability, not an assumption: a backend that cannot build (a read-only cloud viewer) simply
+   * does not declare it, and the command says so rather than opening whatever stale output the last
+   * build happened to leave — which for most projects is nothing at all.
+   */
+  buildSite?: () => Promise<SiteBuildResult>;
   gitAddRemote: (name: string, url: string) => Promise<void>;
   /**
    * How the New Project modal collects a destination, and which `CreateProjectDestination` variant
@@ -321,8 +370,23 @@ export interface StudioPlatform {
   /** Stack B AI assistant: URL of the OpenAI-compatible SSE chat proxy (`/__studio/ai/chat`). */
   aiChatUrl: () => string | Promise<string>;
   // ─── Multi-window (desktop only; undefined on dev-server) ───────────────────
-  /** Open a project in a new window, focusing an existing window if it is already open. */
-  openProjectInNewWindow?: (root: string) => Promise<void>;
+  /**
+   * Open a project in a new window, focusing an existing window if it is already open.
+   *
+   * `focused` says which of the two happened, so the caller reports the outcome instead of
+   * announcing the intent — "opened in a new window" is a lie when the project was already open
+   * somewhere and that window merely came to the front.
+   */
+  openProjectInNewWindow?: (root: string) => Promise<{ focused: boolean }>;
+  /**
+   * Pick a project WITHOUT binding this window to it — the answer to "which project", separated
+   * from the act of opening it here. Backs the New Window branch of Open Project: `openProject()`
+   * re-roots this window's backend as a side effect of picking, so it cannot ask a question whose
+   * answer is "not in this window". Resolves null when the user cancels the picker.
+   *
+   * Desktop only. Without it Studio does not offer the choice, because it could not honour it.
+   */
+  pickProject?: () => Promise<{ root: string; name: string } | null>;
   /** Open a fresh welcome window. */
   newWindow?: () => Promise<void>;
   /**
@@ -444,15 +508,6 @@ export interface CanvasPanel {
   renderScope: { stop: () => void; run: <T>(fn: () => T) => T | undefined } | null;
 }
 
-export interface DocumentStackEntry {
-  document: JxMutableNode;
-  documentPath: string | null;
-  selection: JxPath | null;
-  dirty?: boolean;
-  mode?: string;
-  sourceFormat?: string | null;
-}
-
 export interface FunctionEditDef {
   type: string;
   defName?: string;
@@ -464,8 +519,8 @@ export interface FunctionEditDef {
 }
 
 /**
- * Identifies which document position's `$expression` the full-screen formula workspace is editing:
- * a state entry (`type: "def"` + defName) or an element event binding (`type: "event"` + path +
+ * Identifies which document position's `$expression` the Bottom dock's Logic tab is editing: a
+ * state entry (`type: "def"` + defName) or an element event binding (`type: "event"` + path +
  * eventKey). Mirrors FunctionEditDef, the Monaco function editor's target shape.
  */
 export interface FormulaEditDef {