@dsh-electron/dsh-plugin-multi-root-workspace 0.1.14 → 0.1.16

package/lib/skills-utyuvmwr.js

@@ -0,0 +1,104 @@
+import { n as isPackageInstalled } from "./agent-instructions-BXuKhOzr.js";
+//#region \0@oxc-project+runtime@0.149.0/helpers/esm/usingCtx.js
+function _usingCtx() {
+	var r = "function" == typeof SuppressedError ? SuppressedError : function(r, e) {
+		var n = Error();
+		return n.name = "SuppressedError", n.error = r, n.suppressed = e, n;
+	}, e = {}, n = [];
+	function using(r, e) {
+		if (null != e) {
+			if (Object(e) !== e) throw new TypeError("using declarations can only be used with objects, functions, null, or undefined.");
+			if (r) var o = e[Symbol.asyncDispose || Symbol["for"]("Symbol.asyncDispose")];
+			if (void 0 === o && (o = e[Symbol.dispose || Symbol["for"]("Symbol.dispose")], r)) var t = o;
+			if ("function" != typeof o) throw new TypeError("Object is not disposable.");
+			t && (o = function o() {
+				try {
+					t.call(e);
+				} catch (r) {
+					return Promise.reject(r);
+				}
+			}), n.push({
+				v: e,
+				d: o,
+				a: r
+			});
+		} else r && n.push({
+			d: e,
+			a: r
+		});
+		return e;
+	}
+	return {
+		e,
+		u: using.bind(null, !1),
+		a: using.bind(null, !0),
+		d: function d() {
+			var o, t = this.e, s = 0;
+			function next() {
+				for (; o = n.pop();) try {
+					if (!o.a && 1 === s) return s = 0, n.push(o), Promise.resolve().then(next);
+					if (o.d) {
+						var r = o.d.call(o.v);
+						if (o.a) return s |= 2, Promise.resolve(r).then(next, err);
+					} else s |= 1;
+				} catch (r) {
+					return err(r);
+				}
+				if (1 === s) return t !== e ? Promise.reject(t) : Promise.resolve();
+				if (t !== e) throw t;
+			}
+			function err(n) {
+				return t = t !== e ? new r(n, t) : n, next();
+			}
+			return next();
+		}
+	};
+}
+//#endregion
+//#region src/compat/skills.ts
+/** Never infer authority from cwd, a preset key, or a lookalike Agent. */
+function skillAgent(ctx, options) {
+	const scope = options.scope;
+	if (typeof scope !== "object" || scope === null || !("id" in scope) || typeof scope.id !== "string") return void 0;
+	const agent = ctx.get("agents")?.get(scope.id);
+	return agent === scope ? agent : void 0;
+}
+function skillOrigin(ctx, options) {
+	const cwd = skillAgent(ctx, options)?.session.header.cwd;
+	return typeof cwd === "string" && cwd !== "" ? cwd : void 0;
+}
+/** Absence is optional; a present but broken module must fail visibly. */
+async function filesystemSkillsApi() {
+	if (!isPackageInstalled("@deepseek-ai/dsh-skill-filesystem")) return void 0;
+	const api = await import("@deepseek-ai/dsh-skill-filesystem");
+	if (typeof api.FileSystemSkillProvider !== "function") throw new Error("multi-root skills: FileSystemSkillProvider is unavailable");
+	return api;
+}
+function volatileField(schema) {
+	const method = schema.volatile;
+	return typeof method === "function" ? method.call(schema) : schema;
+}
+function configValue(value) {
+	if (typeof value === "object" && value !== null && Symbol.for("cosmokit.volatile.write") in value) {
+		const get = value.get;
+		if (typeof get === "function") return get.call(value);
+	}
+	return value;
+}
+/** Cold Browser Catalog supplies a Session header, never a fabricated Agent. */
+async function observedSkillOrigin(ctx, sessionId) {
+	try {
+		var _usingCtx$1 = _usingCtx();
+		const query = ctx.get("sessionQuery");
+		if (query === void 0) throw new Error("multi-root skills: SessionQuery is unavailable");
+		const cwd = _usingCtx$1.u(await query.observeSession(sessionId)).header.cwd;
+		if (typeof cwd !== "string" || cwd === "") throw new Error("multi-root skills: Session has no origin");
+		return cwd;
+	} catch (_) {
+		_usingCtx$1.e = _;
+	} finally {
+		_usingCtx$1.d();
+	}
+}
+//#endregion
+export { skillOrigin as a, skillAgent as i, filesystemSkillsApi as n, volatileField as o, observedSkillOrigin as r, configValue as t };

package/lib/skills.js

@@ -1,7 +1,8 @@
-import { t as wrapMethod } from "./method-wrapper-CFY3p3j2.js";
-import { c as withRegistryRead } from "./registry-operation-C2ZV3Jhw.js";
-import { r as isPackageInstalled, t as createInstructionMessage } from "./llm-message-fYORacvh.js";
-import { n as skillsMetadataValid } from "./metadata-DgqSdVX_.js";
+import { t as wrapMethod } from "./method-wrapper-D4oUCsEF.js";
+import { l as withRegistryRead } from "./registry-operation-CIlmt6_c.js";
+import { t as createInstructionMessage } from "./llm-message-CepyzEBQ.js";
+import { n as skillsMetadataValid } from "./metadata-99jgViHQ.js";
+import { a as skillOrigin, i as skillAgent, n as filesystemSkillsApi, o as volatileField, r as observedSkillOrigin, t as configValue } from "./skills-utyuvmwr.js";
 import { constants, statSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -10,108 +11,6 @@ import { canonicalPath } from "@deepseek-ai/dsh-sandbox";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { lstat, open, readdir, stat } from "node:fs/promises";
 import z from "@deepseek-ai/schemastery";
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/usingCtx.js
-function _usingCtx() {
-	var r = "function" == typeof SuppressedError ? SuppressedError : function(r, e) {
-		var n = Error();
-		return n.name = "SuppressedError", n.error = r, n.suppressed = e, n;
-	}, e = {}, n = [];
-	function using(r, e) {
-		if (null != e) {
-			if (Object(e) !== e) throw new TypeError("using declarations can only be used with objects, functions, null, or undefined.");
-			if (r) var o = e[Symbol.asyncDispose || Symbol["for"]("Symbol.asyncDispose")];
-			if (void 0 === o && (o = e[Symbol.dispose || Symbol["for"]("Symbol.dispose")], r)) var t = o;
-			if ("function" != typeof o) throw new TypeError("Object is not disposable.");
-			t && (o = function o() {
-				try {
-					t.call(e);
-				} catch (r) {
-					return Promise.reject(r);
-				}
-			}), n.push({
-				v: e,
-				d: o,
-				a: r
-			});
-		} else r && n.push({
-			d: e,
-			a: r
-		});
-		return e;
-	}
-	return {
-		e,
-		u: using.bind(null, !1),
-		a: using.bind(null, !0),
-		d: function d() {
-			var o, t = this.e, s = 0;
-			function next() {
-				for (; o = n.pop();) try {
-					if (!o.a && 1 === s) return s = 0, n.push(o), Promise.resolve().then(next);
-					if (o.d) {
-						var r = o.d.call(o.v);
-						if (o.a) return s |= 2, Promise.resolve(r).then(next, err);
-					} else s |= 1;
-				} catch (r) {
-					return err(r);
-				}
-				if (1 === s) return t !== e ? Promise.reject(t) : Promise.resolve();
-				if (t !== e) throw t;
-			}
-			function err(n) {
-				return t = t !== e ? new r(n, t) : n, next();
-			}
-			return next();
-		}
-	};
-}
-//#endregion
-//#region src/compat/skills.ts
-/** Never infer authority from cwd, a preset key, or a lookalike Agent. */
-function skillAgent(ctx, options) {
-	const scope = options.scope;
-	if (typeof scope !== "object" || scope === null || !("id" in scope) || typeof scope.id !== "string") return void 0;
-	const agent = ctx.get("agents")?.get(scope.id);
-	return agent === scope ? agent : void 0;
-}
-function skillOrigin(ctx, options) {
-	const cwd = skillAgent(ctx, options)?.session.header.cwd;
-	return typeof cwd === "string" && cwd !== "" ? canonicalPath(cwd) : void 0;
-}
-/** Absence is optional; a present but broken module must fail visibly. */
-async function filesystemSkillsApi() {
-	if (!isPackageInstalled("@deepseek-ai/dsh-skill-filesystem")) return void 0;
-	const api = await import("@deepseek-ai/dsh-skill-filesystem");
-	if (typeof api.FileSystemSkillProvider !== "function") throw new Error("multi-root skills: FileSystemSkillProvider is unavailable");
-	return api;
-}
-function volatileField(schema) {
-	const method = schema.volatile;
-	return typeof method === "function" ? method.call(schema) : schema;
-}
-function configValue(value) {
-	if (typeof value === "object" && value !== null && Symbol.for("cosmokit.volatile.write") in value) {
-		const get = value.get;
-		if (typeof get === "function") return get.call(value);
-	}
-	return value;
-}
-/** Cold Browser Catalog supplies a Session header, never a fabricated Agent. */
-async function observedSkillOrigin(ctx, sessionId) {
-	try {
-		var _usingCtx$1 = _usingCtx();
-		const query = ctx.get("sessionQuery");
-		if (query === void 0) throw new Error("multi-root skills: SessionQuery is unavailable");
-		const cwd = _usingCtx$1.u(await query.observeSession(sessionId)).header.cwd;
-		if (typeof cwd !== "string" || cwd === "") throw new Error("multi-root skills: Session has no origin");
-		return canonicalPath(cwd);
-	} catch (_) {
-		_usingCtx$1.e = _;
-	} finally {
-		_usingCtx$1.d();
-	}
-}
-//#endregion
 //#region src/skills/reader.ts
 /** Constrain the native parser before discovery can read a candidate's body. */
 function containsPath(root, target) {

package/lib/{tool-context-CpgIFcCB.js → tool-context-CCeY3mrK.js}

@@ -1,6 +1,6 @@
 //#region src/compat/tool-context.ts
 function aroundTool(ctx, listener) {
-	ctx.on.call(ctx, "tools/execute", listener);
+	ctx.on.call(ctx, "tools/execute", listener, { global: true });
 }
 //#endregion
 export { aroundTool as t };

package/lib/types/authority/protocol.d.ts

@@ -29,7 +29,11 @@ export declare const snapshotSchema: z.ZodObject<{
             invalid: "invalid";
         }>;
         detail: z.ZodOptional<z.ZodString>;
-        invalidReason: z.ZodOptional<z.ZodLiteral<"membership-conflict">>;
+        invalidReason: z.ZodOptional<z.ZodEnum<{
+            "membership-conflict": "membership-conflict";
+            "protected-path": "protected-path";
+            "primary-overlap": "primary-overlap";
+        }>>;
     }, z.core.$strict>>;
     available: z.ZodBoolean;
 }, z.core.$strict>;

package/lib/types/client/files-tree/FilesTree.d.ts

@@ -9,23 +9,66 @@ import type { FilesInjected } from './face.ts';
 import type { createFilesStore } from './store.ts';
 /**
  * The fork's props: the store/locale shares verbatim from upstream's
- * composed props, `start`/`toggle` from the injected face, and the four
- * seams upstream binds inside `FilesBody` — tab id, lifetime, root, and the
- * resource-opening callback — supplied by the adapter instead.
+ * composed props, `hold`/`release`/`toggle` from the injected face, and the
+ * four seams upstream binds inside `FilesBody` — tab id, lifetime, root, and
+ * the resource-opening callback — supplied by the adapter instead.
  */
-export type FilesTreeProps = PropsStore<ReturnType<typeof createFilesStore>> & Pick<FilesInjected, 'start' | 'toggle'> & PropsLocale<'sidebarFiles'> & {
+export type FilesTreeProps = PropsStore<ReturnType<typeof createFilesStore>> & Pick<FilesInjected, 'hold' | 'release' | 'toggle'> & PropsLocale<'sidebarFiles'> & {
     /** The store bucket this tree reads and writes — the pane's own dockkit tab id. */
     readonly tabId: TabId;
     /** Session the listing and the resource addresses belong to. */
     readonly sessionId: SessionId;
     /** Absolute path of the root this tree lists (the selected additional root). */
     readonly root: string;
-    /** Takeover lifetime: aborting forgets the bucket and closes the watch tree. */
+    /**
+     * The owner's record lifetime: aborting it forgets the bucket and closes
+     * the tree. A body unmount alone only ends the hold — the bucket, its
+     * listed levels, and its expansion stay for the next mount to resume.
+     */
     readonly signal: AbortSignal;
     /** Open one `dsh-resource://file` address (the adapter's sidebarRight route). */
     readonly onOpen: (address: string) => void;
     /** Optional host-controlled tree Factory, available on the newer Files page. */
     readonly nativeTree?: NativeTreeRenderer | undefined;
+    /**
+     * The owner's live scroll mirror — upstream's `scrolled` writing
+     * `pane.scrollTop`: fired on every scroll and once more at unmount with
+     * the body's final offset (the adapter refuses the write when the owner
+     * is already dead, so a normal close keeps its last position while a
+     * killed one cannot resurrect). The fork's own store still hears the
+     * offset only at unmount through `actions.scrolled`, as upstream.
+     */
+    readonly onScrollOffset?: ((offset: number) => void) | undefined;
+    /**
+     * The preview navigator's locate-current-file request: expand the file's
+     * ancestors, mark its row current, and scroll it into view — what the
+     * native navigator's `revealing`/`step()`/`revealed` does with
+     * `pane.current` and `scrollToCurrent`. `revealed` is the owner's memory
+     * of the last completed walk: a path equal to it suppresses stepping —
+     * exactly upstream's `revealing = revealed === address ? undefined :
+     * address` on a body mount — while `onSettled` reports each completed
+     * walk (found, unreachable, or canceled) so the owner can record it.
+     * Absent on the Files page, which has no current file.
+     */
+    readonly reveal?: {
+        readonly path: string;
+        readonly revealed?: string | undefined;
+        readonly onSettled?: ((path: string) => void) | undefined;
+    } | undefined;
+    /**
+     * Expansion, scroll offset, and reveal memory saved while this tree's
+     * owner was closed — the pane record's surviving `expanded`/`scrollTop`/
+     * `revealed` upstream. `expanded` is replayed through `toggle` (the
+     * verbatim face's own restore-preferences channel) right after `start`,
+     * so every remembered directory re-expands as its level lands; the
+     * scroll offset is deferred until the body overflows, and `revealed`
+     * seeds the reveal's suppression.
+     */
+    readonly saved?: {
+        readonly expanded?: readonly string[];
+        readonly scrollTop?: number;
+        readonly revealed?: string;
+    } | undefined;
 };
 /**
  * Order one level's entries for display: directories first, then everything
@@ -47,4 +90,4 @@ export declare function failureLine(t: TranslateNS<'sidebarFiles'>, failure: Rem
  * has opened under it — the upstream body's scroll, seed, and render logic
  * verbatim, with the root arriving as a prop instead of `useSessions(cwd)`.
  */
-export declare function FilesTree({ tabId, sessionId, root, signal, useStore, actions, start, toggle, onOpen, t, nativeTree, }: FilesTreeProps): ReactNode;
+export declare function FilesTree({ tabId, sessionId, root, signal, useStore, actions, hold, release, toggle, onOpen, t, nativeTree, reveal, saved, onScrollOffset, }: FilesTreeProps): ReactNode;

package/lib/types/client/files-tree/adapter.d.ts

@@ -47,26 +47,67 @@ export type TreeSelection = Readonly<Record<string, RootView>>;
  * native tree across a body remount (opening a file deactivates this tab,
  * unmounting its body without ending the record).
  */
+/**
+ * The tree-view memory one closed owner keeps for its next open — the
+ * fork's spelling of upstream's pane record: `expanded`/`scrollTop` survive
+ * the hold's end, and `revealed` is the last previewed file the reveal
+ * walk completed (upstream's `pane.revealed`). Entries live per
+ * (key, root), so one pane previewing files of different roots keeps each
+ * root's memory apart.
+ */
+export interface FilesTreeSaved {
+    /** The root this snapshot belongs to; a stale snapshot never crosses roots. */
+    readonly root: string;
+    /** Expansion preferences at the moment the owner closed. */
+    readonly expanded?: readonly string[];
+    /** The body's scroll offset at the moment it closed. */
+    readonly scrollTop?: number;
+    /** The last previewed file whose reveal completed — suppresses re-stepping. */
+    readonly revealed?: string;
+}
 export interface FilesTreeTakeover {
     /**
-     * The live signal for (tabId, root); reuses the live entry so a remounted
-     * body finds its bucket and watches intact. A different root — or an entry
-     * already aborted — ends the previous controller before minting the next.
-     * @param tabId - the pane's dockkit tab id.
+     * The record signal for (key, root); reuses the live entry so a remounted
+     * body finds its tree bucket and resumes it. Only the record's end — the
+     * owner dying, or a different root superseding it — aborts the controller;
+     * a navigator closing is a hold ending and leaves this signal live.
+     * @param key - the owner's dockkit identity: the Files pane's tab id, or
+     *   the preview navigator's pane id.
      * @param root - absolute path of the root being browsed.
-     * @param section - the dockkit tabHost section the caller mounted under; a
-     *   live entry keeps an observer on it that ends the takeover whenever the
-     *   section leaves the document — the record's real end — including when the
-     *   body that mounted it has long been unmounted itself.
+     * @param section - how the owner's survival is checked: an Element (kept
+     *   while `isConnected`) or a predicate (kept while it returns true —
+     *   the preview navigator's "some connected element still carries this
+     *   pane id" query, since a dockkit pane has no stable element across a
+     *   `replaceTab`). The watch lives at this scope and outlives `end()`:
+     *   ending the hold never disarms it, so the owner's real death drops
+     *   the saved memory even after the body that mounted it is gone.
      * @returns the signal the forked tree lives under.
      */
-    readonly signal: (tabId: TabId, root: string, section?: Element) => AbortSignal;
+    readonly signal: (key: TabId, root: string, section?: Element | (() => boolean)) => AbortSignal;
     /**
-     * Abort and drop one tab's takeover: the reader deselected or switched
-     * roots, or the tab record itself went away.
-     * @param tabId - the pane's dockkit tab id.
+     * Abort and drop one owner's record: the owner died, the selection moved to
+     * another root, or a body with no pane carrier closed. A normal navigator
+     * close is not a record end — the body release keeps the bucket. The saved
+     * memory survives here because the death watch owns the only real drop;
+     * this method only guarantees a superseded record stops writing.
+     * @param key - the owner's dockkit identity.
      */
-    readonly end: (tabId: TabId) => void;
+    readonly end: (key: TabId) => void;
+    /**
+     * The tree-view memory kept for (key, root) — `undefined` before the
+     * first close or after the owner's section died.
+     * @param key - the owner's dockkit identity.
+     * @param root - absolute path of the root the memory belongs to.
+     */
+    readonly saved: (key: TabId, root: string) => FilesTreeSaved | undefined;
+    /**
+     * Merge memory for (key, snapshot.root): fields present in the snapshot
+     * overwrite, fields absent keep what was saved before — so a settle-time
+     * `revealed` write survives the close-time `expanded`/`scrollTop` write.
+     * @param key - the owner's dockkit identity.
+     * @param snapshot - the memory fields to record.
+     */
+    readonly save: (key: TabId, snapshot: FilesTreeSaved) => void;
 }
 /** The inject face the registration composes onto the occupant's props. */
 export interface FilesTreeInjected {
@@ -74,6 +115,14 @@ export interface FilesTreeInjected {
     readonly face: FilesInjected;
     /** Open one `dsh-resource://file` address in the host viewer. */
     readonly openFile: (address: string) => void;
+    /**
+     * Open one `dsh-resource://file` address replacing the given tab — the
+     * document-preview navigator's open route, where the native navigator's
+     * `onOpen` is `tab.actions.openResource(address, { replaceTab: true })`.
+     * @param tabId - the preview tab the opened file replaces.
+     * @param address - the file's `dsh-resource://file` address.
+     */
+    readonly openFileIn: (tabId: TabId, address: string) => void;
     /**
      * The reserved inject compartment: the slot renderer binds each source to a
      * `use<Name>` selector hook, so `treeSelection` reaches the component as
@@ -99,6 +148,8 @@ export interface FilesTreeSurface {
     readonly actions: FilesTreeProps['actions'];
     readonly face: FilesInjected;
     readonly openFile: (address: string) => void;
+    /** The preview navigator's replace-tab open route; see {@link FilesTreeInjected.openFileIn}. */
+    readonly openFileIn: FilesTreeInjected['openFileIn'];
     readonly t: FilesTreeProps['t'];
     /** Selector hook over this session's per-tab root selections. */
     readonly useTreeSelection: SnapshotSelectorHook<TreeSelection>;
@@ -123,9 +174,10 @@ export declare function lazyFilesRemote(ctx: ClientContext): ClientRemote;
 /**
  * The registration's `store`/`inject` declarations, built once in `apply`.
  *
- * The inject face nests the verbatim files face under `face` and adds the
- * session-bound `openFile` — keeping `FilesInjected` untouched means the
- * fork's call sites and the sync diff stay upstream-shaped.
+ * The inject face nests the files face under `face` and adds the
+ * session-bound `openFile`; the fork's call sites stay upstream-shaped, the
+ * one lifecycle delta being the hold/release pair the preview navigator needs
+ * (see FORK.md).
  * @param ctx - the client root context (the remote/sidebarRight lookups).
  * @returns the store handle and the inject factory for `register`.
  */
@@ -148,6 +200,7 @@ export declare function createFilesTreeSurface(props: {
     readonly actions: FilesTreeSurface['actions'];
     readonly face: FilesInjected | undefined;
     readonly openFile: ((address: string) => void) | undefined;
+    readonly openFileIn: FilesTreeInjected['openFileIn'] | undefined;
     readonly useTreeSelection: FilesTreeSurface['useTreeSelection'] | undefined;
     readonly selectRoot: FilesTreeSurface['selectRoot'] | undefined;
     readonly takeover: FilesTreeSurface['takeover'] | undefined;

package/lib/types/client/files-tree/face.d.ts

@@ -1,7 +1,7 @@
 /**
  * The tree's asynchronous half: listing directories into the store.
  *
- * The component never awaits anything. It calls `start` / `refresh` / `toggle`, and
+ * The component never awaits anything. It calls `hold` / `release` / `refresh` / `toggle`, and
  * this face performs the listing and writes the outcome through the store's own
  * actions — the Slot-standard `inject` shape, so the session id is resolved by
  * the framework and the write set stays the store's.
@@ -17,6 +17,12 @@
  * `signal`: a request is not made for a record that already ended, and when the
  * record goes away the bucket and the tab's listing bookkeeping are forgotten,
  * so no later settlement writes to it.
+ *
+ * A hold can end without its record ending: `release` closes the hold's
+ * directory node and watches but keeps the listed levels and expansion, and
+ * the next `hold` reopens them. That is upstream's `hold(paneId, cwd)` —
+ * closing a navigator is not closing its pane, so reopening draws the kept
+ * rows instead of falling back to a loading row.
  */
 import type { ClientRemote, RemoteResult } from '@deepseek-ai/dsh-api-remotes/client';
 import type { BoundActions } from '@deepseek-ai/dsh-client-store';
@@ -75,12 +81,35 @@ export interface FilesInjected {
     /** Control automatic rereads without closing watches. @param tabId - owning tab. @param enabled - automatic-refresh setting. */
     readonly setAutoRefresh: (tabId: TabId, enabled: boolean) => void;
     /**
-     * Seed this tab's tree and list its root.
+     * Seed this tab's tree and list its root. This is the record's first open:
+     * it always reseeds the store at `root`, so use {@link hold} for later holds.
      * @param tabId - the tab being drawn.
      * @param root - absolute path of the workspace root.
      * @param signal - the tab record's lifetime.
      */
     readonly start: (tabId: TabId, root: string, signal: AbortSignal) => void;
+    /**
+     * Open one hold on this tab's tree and list its root.
+     *
+     * The store bucket is reused when it already belongs to `root`; its listed
+     * levels stay drawn while the reopened node's listings settle, so a navigator
+     * closed and reopened by the reader never flashes a loading row over rows it
+     * already had. A different root reseeds the bucket, exactly like `start`.
+     * @param tabId - the tab being drawn.
+     * @param root - absolute path of the workspace root.
+     * @param signal - the tab record's lifetime; aborting it still forgets the
+     *   bucket and closes the node.
+     * @param restore - expanded directories to reopen as their parent listing
+     *   returns (the kept tree's expansion preferences).
+     */
+    readonly hold: (tabId: TabId, root: string, signal: AbortSignal, restore?: readonly string[]) => void;
+    /**
+     * End one hold: close its directory node and watches while keeping the store
+     * bucket and expansion for the next `hold`. The record's `signal` still owns
+     * the bucket; aborting it forgets the tree.
+     * @param tabId - the tab whose hold ends.
+     */
+    readonly release: (tabId: TabId) => void;
     /**
      * List one directory into the store.
      * @param tabId - the tab being drawn.

package/lib/types/client/files-tree/locate.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Path-location mechanics for the preview navigator's takeover and reveal,
+ * ported from upstream's `ui-sidebar-files` navigator internals
+ * (`0.2.2-alpha.3`; the package build is byte-identical at `0.2.2-rc.1`):
+ * the same `windowsRoot`, `underRoot`, and `locateFile` the native
+ * FileNavigator runs against its pane tree, spelled against this fork's
+ * `FilesTabState` — the store shape is the same (`root`, `levels` keyed by
+ * absolute path, `expanded`), only the `refreshing` flag is absent, so a
+ * stale level reports `pending: false` exactly like a settled native one.
+ *
+ * Everything here is a port or plugin-owned logic on top of it; nothing in
+ * this file needs upstream sync beyond the documented provenance.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/client/files-tree/locate
+ */
+import type { RootView, RootsView } from '../../contract.ts';
+import type { FilesTabState } from './store.ts';
+/**
+ * Whether a root is a Windows drive or UNC path, in either separator
+ * spelling, where names compare regardless of case.
+ * @param root - the tree's root, or a prefix built from it.
+ * @returns `true` for a drive letter followed by a separator, or a leading
+ *   double separator.
+ */
+export declare function windowsRoot(root: string): boolean;
+/**
+ * An absolute `/`-separated path relative to a tree's root.
+ * @param path - the absolute path, in either separator spelling.
+ * @param root - the tree's root, in either separator spelling.
+ * @returns the path under the root, or `undefined` outside it.
+ */
+export declare function underRoot(path: string, root: string): string | undefined;
+/**
+ * The workspace-relative path of a file under a tree's root, validated the
+ * way upstream's `relativeFileOf` tail validates it: nothing absolute, and
+ * no empty or dot segments.
+ * @param path - the file's absolute path, in either separator spelling.
+ * @param root - the root it must sit under.
+ * @returns the `/`-separated relative path, or `undefined` outside the root.
+ */
+export declare function relativeUnderRoot(path: string, root: string): string | undefined;
+/**
+ * The additional root that owns one absolute file path: available roots
+ * only, the longest matching root path winning when registrations nest.
+ * @param view - the session's registry view.
+ * @param path - the file's absolute path, in either separator spelling.
+ * @returns the owning root, or `undefined` when the file is outside every
+ *   available additional root (the primary root included).
+ */
+export declare function rootForPath(view: RootsView, path: string): RootView | undefined;
+/** What walking the listed levels toward a workspace-relative file found. */
+export interface FileLocation {
+    /** The directories verified so far, each named by its listing's spelling. */
+    readonly ancestors: readonly {
+        readonly parent: string;
+        readonly path: string;
+    }[];
+    /** The file's tree key once its row exists, `undefined` until or unless it does. */
+    readonly current: string | undefined;
+    /** Whether a level on the way is still pending its listing. */
+    readonly pending: boolean;
+}
+/**
+ * Walk the listed levels to a workspace-relative file, keeping the listing's
+ * spelling of each name; a Windows root also matches names regardless of
+ * case. A verbatim port of upstream's navigator helper — the fork's
+ * `LevelState` carries no `refreshing` flag, so a stale level reports
+ * `pending: false` like a settled native one.
+ * @param tree - the tab's tree.
+ * @param relativePath - the file's path under the tree's root, `/`-separated.
+ * @returns the ancestors found so far, the file's tree key, and whether a
+ *   level is pending.
+ */
+export declare function locateFile(tree: Pick<FilesTabState, 'root' | 'levels'>, relativePath: string): FileLocation;