@volter/live 0.5.210 → 0.5.212

package/dist/installed-package.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The real directory of installed package `name` as Node finds it from `fromDir`: up the `node_modules` folders, or
+ * null when none holds it. It is found by its folder rather than by resolving `<name>/package.json`, which fails for a
+ * package whose `exports` does not list that file (`@volter/sdk`).
+ */
+export declare function installedPackageDir(fromDir: string, name: string): string | null;

package/dist/installed-package.js

@@ -0,0 +1,7 @@
+import {
+  installedPackageDir
+} from "./chunk-7WKVJGHZ.js";
+export {
+  installedPackageDir
+};
+//# sourceMappingURL=installed-package.js.map

package/dist/installed-package.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/lazy-proxy.d.ts

@@ -1,21 +1,21 @@
 /**
  * `lazyChainProxy` — turns an async "resolve the real object" function into
  * a synchronously-importable stand-in that supports the SAME call shape as
- * the real thing, including nested member access (`game.input.hold(...)`,
- * `editor.document.query(...)`), by recording the property-access PATH and only
+ * the real thing, including nested member access
+ * (`editor.document.query(...)`), by recording the property-access PATH and only
  * resolving + walking it down at the point of an actual function CALL.
  *
- * This is what makes `index.ts`'s top-level `export const editor = ...` /
- * `game` / `page` work as plain values a script can `import { editor, game,
- * page } from '@volter/live'` and call immediately — each call transparently
- * awaits the memoized `connect()` first.
+ * This is what makes `index.ts`'s top-level `export const editor = ...` work
+ * as a plain value a script can `import { editor } from '@volter/live'` and
+ * call immediately — each call transparently awaits the memoized `connect()`
+ * first.
  *
  * Limitation (by design, documented on `index.ts`'s exports too): only
- * FUNCTION-shaped access resolves through this proxy — `game.input.hold(x)`
- * works, but reading a plain data property (e.g. `game.fenceTick`) would
- * return another inert proxy, not the real number, since there is no
- * function CALL to trigger resolution. Every documented `editor`/`game`/
- * `page` member is a method, so this never bites the documented surface.
+ * FUNCTION-shaped access resolves through this proxy — `editor.document.query(s)`
+ * works, but reading a plain data property would return another inert proxy,
+ * not the real value, since there is no function CALL to trigger resolution.
+ * Every documented `editor` member is a method, so this never bites the
+ * documented surface.
  */
 /**
  * `resolveRoot` is called (and its result awaited) on every terminal

package/dist/member-hints.d.ts

@@ -2,13 +2,10 @@
  * NAMES AN AGENT REACHES FOR THAT THE FAÇADE DOES NOT HAVE, and where the
  * thing it wanted actually lives.
  *
- * Why this exists (measured 2026-10, an agent building an obby in the Model
- * Editor): it called `editor.setCamera(...)`, got the engine's bare
- * "editor.setCamera is not a function", searched for a camera verb, and in the
- * end improvised a pose from `frame()` and `orbit()`. The camera was reachable
- * the whole time — through `editor.present`'s `viewport.camera` — but the
- * failure said nothing about it. The refusal is the one moment the caller is
- * certainly reading, so that is where the pointer goes.
+ * A call to `editor.setCamera(...)` would otherwise fail with the engine's bare
+ * "editor.setCamera is not a function", though the camera is reachable through
+ * `editor.present`'s `viewport.camera`. The refusal is the one moment the
+ * caller is certainly reading, so that is where the pointer goes.
  *
  * TARGETED, NOT A CATCH-ALL. Only the names below are intercepted, each with
  * the door it was looking for. Every other missing member keeps JavaScript's
@@ -19,11 +16,11 @@
 export declare function editorMemberHint(member: PropertyKey): string | undefined;
 /**
  * `editor` as `eval` binds it: the same object, except that reading one of the
- * hinted names it does NOT have throws the hint, naming `binding.member`.
+ * hinted names it does NOT have throws the hint, naming `editor.member`.
  * Thrown on READ, not on call, so `editor.camera.position` is caught as well as
  * `editor.setCamera(...)`.
  *
  * Methods come back bound to the real object: `LiveEditor` keeps its client in
  * a `#`-private field, which a call whose `this` is the proxy cannot read.
  */
-export declare function withEditorMemberHints<T extends object>(target: T, binding?: string): T;
+export declare function withEditorMemberHints<T extends object>(target: T): T;

package/dist/product-create.d.ts

@@ -0,0 +1,29 @@
+/** Project creation is executable product code, shared by its CLI and the host. */
+export interface ProductCreateRequest {
+    name: string;
+    targetDir: string;
+    /** A starter the product offers (its `templates`), or none for its default. */
+    template?: string;
+    /** One of the product's example projects (its `examples`), in place of a template. */
+    example?: string;
+}
+export interface ProductCreateResult {
+    targetDir: string;
+    manifest: unknown;
+}
+/** A starter or an example a product creates, as a picker lists it. */
+interface ProductCreateChoice {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+}
+export interface ProductCreateDeclaration {
+    readonly product: string;
+    /** The starters a new project begins from. */
+    readonly templates: readonly ProductCreateChoice[];
+    /** Finished projects to learn from, each made whole (`create --example <id>`). */
+    readonly examples?: readonly ProductCreateChoice[];
+    create(request: ProductCreateRequest): Promise<ProductCreateResult>;
+}
+export declare function assertProductCreateDeclaration(value: unknown, source: string): ProductCreateDeclaration;
+export {};

package/dist/product-create.js

@@ -0,0 +1,13 @@
+// src/product-create.ts
+function assertProductCreateDeclaration(value, source) {
+  const declaration = value;
+  const choices = (list) => Array.isArray(list) && !list.some((t) => typeof t?.id !== "string" || typeof t?.name !== "string");
+  if (!declaration || typeof declaration.product !== "string" || typeof declaration.create !== "function" || !choices(declaration.templates) || declaration.examples !== void 0 && !choices(declaration.examples)) {
+    throw new Error(`${source}: expected a product, templates (and any examples) and create(request) function`);
+  }
+  return declaration;
+}
+export {
+  assertProductCreateDeclaration
+};
+//# sourceMappingURL=product-create.js.map

package/dist/product-create.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/product-create.ts"],
+  "sourcesContent": ["/** Project creation is executable product code, shared by its CLI and the host. */\nexport interface ProductCreateRequest {\n  name: string;\n  targetDir: string;\n  /** A starter the product offers (its `templates`), or none for its default. */\n  template?: string;\n  /** One of the product's example projects (its `examples`), in place of a template. */\n  example?: string;\n}\nexport interface ProductCreateResult {\n  targetDir: string;\n  manifest: unknown;\n}\n/** A starter or an example a product creates, as a picker lists it. */\ninterface ProductCreateChoice {\n  readonly id: string;\n  readonly name: string;\n  readonly description?: string;\n}\nexport interface ProductCreateDeclaration {\n  readonly product: string;\n  /** The starters a new project begins from. */\n  readonly templates: readonly ProductCreateChoice[];\n  /** Finished projects to learn from, each made whole (`create --example <id>`). */\n  readonly examples?: readonly ProductCreateChoice[];\n  create(request: ProductCreateRequest): Promise<ProductCreateResult>;\n}\nexport function assertProductCreateDeclaration(value: unknown, source: string): ProductCreateDeclaration {\n  const declaration = value as Partial<ProductCreateDeclaration> | null;\n  const choices = (list: unknown): boolean =>\n    Array.isArray(list) && !list.some(t => typeof t?.id !== 'string' || typeof t?.name !== 'string');\n  if (!declaration || typeof declaration.product !== 'string' ||\n      typeof declaration.create !== 'function' || !choices(declaration.templates) ||\n      (declaration.examples !== undefined && !choices(declaration.examples))) {\n    throw new Error(`${source}: expected a product, templates (and any examples) and create(request) function`);\n  }\n  return declaration as ProductCreateDeclaration;\n}\n"],
+  "mappings": ";AA2BO,SAAS,+BAA+B,OAAgB,QAA0C;AACvG,QAAM,cAAc;AACpB,QAAM,UAAU,CAAC,SACf,MAAM,QAAQ,IAAI,KAAK,CAAC,KAAK,KAAK,OAAK,OAAO,GAAG,OAAO,YAAY,OAAO,GAAG,SAAS,QAAQ;AACjG,MAAI,CAAC,eAAe,OAAO,YAAY,YAAY,YAC/C,OAAO,YAAY,WAAW,cAAc,CAAC,QAAQ,YAAY,SAAS,KACzE,YAAY,aAAa,UAAa,CAAC,QAAQ,YAAY,QAAQ,GAAI;AAC1E,UAAM,IAAI,MAAM,GAAG,MAAM,iFAAiF;AAAA,EAC5G;AACA,SAAO;AACT;",
+  "names": []
+}

package/dist/product-locator.d.ts

@@ -0,0 +1,100 @@
+import { type ProductDeclaration } from './volter-manifest';
+export declare const PRODUCT_DECLARATION_KEY = "contributes.volter.product";
+/** Light or dark — the two the workbench's own `ColorScheme` has plain names
+ *  for, and the only two a product needs to state (a high-contrast scheme is a
+ *  person's accessibility choice, never a product's declaration). */
+export type ProductColorTheme = 'dark' | 'light';
+export interface ProductWorkbench {
+    /** The GitHub Release tag on `volter-ai/code-oss`. */
+    readonly release: string;
+    /** The sha256 of that release's tarball asset, hex. */
+    readonly tarballSha256: string;
+}
+/** A product package, as everything outside it needs to know it. */
+export interface ProductIdentity {
+    readonly name: string;
+    /** Its version, reported beside the workbench by the editor's `status` command. */
+    readonly version: string;
+    readonly command: string;
+    /** The name a person sees — `contributes.volter.product.displayName`. */
+    readonly displayName: string;
+    /**
+     * `contributes.volter.product.upgrade: true` — its command has `upgrade [version]`
+     * (the product CLI's own), so a pinned-engine refusal
+     * may tell a person to run it. Optional: a product that says nothing has none.
+     */
+    readonly upgrade?: boolean;
+    /**
+     * `contributes.volter.product.adapterRequired: true` — a project this product opens must have its own
+     * adapter module (`editor/volter.adapter.ts`), because the product's layout and document
+     * finders are declared there and the native default shows none of them. Such a product refuses
+     * a project without one. Optional: a product that says nothing opens it on the native default.
+     */
+    readonly adapterRequired?: boolean;
+    /** Its package root, absolute. */
+    readonly dir: string;
+    /**
+     * Its ONE source entry, package-relative and POSIX (`./src/index.ts`). That
+     * entry IS the product's frame entry: it composes and re-exports `mountVolter`,
+     * which is the name the fork's contribution reads off the served module.
+     */
+    readonly entry: string;
+    /**
+     * The packages this product mounts, in order — `contributes.volter.product.composes`. The ONE statement of
+     * the composition: the build serves it to the entry as `volter:composition`, and the session
+     * reads it here for the catalog and the serving doors.
+     */
+    readonly composes: readonly string[];
+    readonly colorTheme: ProductColorTheme;
+    /** WHICH WORKBENCH THIS PRODUCT IS — see {@link ProductWorkbench}. */
+    readonly workbench: ProductWorkbench | null;
+    /**
+     * The ONE LINE that installs this product and starts a project in it —
+     * `contributes.volter.product.install` (`npx <name> create my-project`). A limited view quotes
+     * it wherever it cannot do what the local editor does (its agent answers with it, and every
+     * route it does not carry names it), so it is a declaration read without running the product.
+     * An undeclared one is `npx <name> create my-project`, which is what every product's `create`
+     * verb accepts.
+     */
+    readonly install: string;
+}
+/** What a project without a product is told to add: the declaration this module reads, naming no package. */
+export declare const PRODUCT_DECLARATION_HINT = "a product package as a dev dependency: one whose package.json declares `contributes.volter.product`";
+/**
+ * Read one product package's declaration, or `null` when the manifest is not a
+ * product's. Throws when it declares `contributes.volter.product` and the declaration is
+ * unusable — a half-written product must be named, never skipped.
+ */
+export declare function readProductManifest(packageDir: string): ProductIdentity | null;
+/** A product declaration's `composes`, checked: the packages it mounts, by name, in order. The
+ *  build's composition module and the session read it through this one check. */
+export declare function productComposes(manifestPath: string, declared: ProductDeclaration): string[];
+/**
+ * A product's SHORT id — `@<scope>/<name>` → `<name>`.
+ *
+ * It is the product's own `product({ id })`, the directory its workbench half
+ * lives in (`packages/<id>/workbench`), the `--product` flag the overlay and the
+ * release build take, and what a release records in `BUILD.json`. One derivation
+ * rather than four literals: the package name is the only place the product is
+ * NAMED, and everything else is that name's last segment.
+ */
+export declare function workbenchProductId(packageName: string): string;
+/** A product's entry as a path relative to `fromDir`, POSIX — the spelling a
+ *  Vite manifest key and a dev-server URL both use. */
+export declare function productEntryPath(product: ProductIdentity, fromDir: string): string;
+/**
+ * The packages `product` mounts that are installed and contribute: its `contributes.volter.product.composes`,
+ * each resolved from the product's own directory and kept when its manifest declares
+ * a `contributes.volter` object (its serving half, `contributes.volter.serving`, may be all a package contributes).
+ */
+export declare function productComposedPackages(product: ProductIdentity): string[];
+/** The products this project declares AND resolves, in declaration order. */
+export declare function declaredProducts(projectRoot: string): ProductIdentity[];
+/**
+ * THE product this project opens in, or a throw naming what is wrong.
+ *
+ * The refusals are the whole point: a project with none and a project with two
+ * are both states a person can be in, and neither has an answer this code may
+ * invent.
+ */
+export declare function resolveProductForProject(projectRoot: string): ProductIdentity;

package/dist/product-locator.js

@@ -0,0 +1,25 @@
+import {
+  PRODUCT_DECLARATION_HINT,
+  PRODUCT_DECLARATION_KEY,
+  declaredProducts,
+  productComposedPackages,
+  productComposes,
+  productEntryPath,
+  readProductManifest,
+  resolveProductForProject,
+  workbenchProductId
+} from "./chunk-SDIWRX5X.js";
+import "./chunk-7WKVJGHZ.js";
+import "./chunk-YPAOTPIF.js";
+export {
+  PRODUCT_DECLARATION_HINT,
+  PRODUCT_DECLARATION_KEY,
+  declaredProducts,
+  productComposedPackages,
+  productComposes,
+  productEntryPath,
+  readProductManifest,
+  resolveProductForProject,
+  workbenchProductId
+};
+//# sourceMappingURL=product-locator.js.map

package/dist/product-locator.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/registry-format.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared editor-session registry format: entry shape, guards, path,
+ * liveness-filtered reads, served-project parsing and pending launches.
+ * The server’s session-registry module owns writes to this format.
+ */
+/** One registry entry, exactly as the server's write half records it. */
+export interface EditorSessionEntry {
+    /** Canonical project root currently open, or null when none. */
+    project: string | null;
+    port: number;
+    /** PID of the dev-server process. */
+    pid: number;
+    /** ISO timestamp of server start. */
+    startedAt: string;
+    sessionId: string | null;
+    /** Private loopback control credential — never returned by an editor HTTP
+     *  route; exists only in this user-private registry. */
+    controlSecret?: string | null;
+    repositoryId: string | null;
+    worktreeId: string | null;
+    worktreeRoot: string | null;
+    projectRelativePath: string | null;
+    branch: string | null;
+    headCommit: string | null;
+    baseCommit: string | null;
+}
+export declare const EDITOR_SESSIONS_REGISTRY_FILE: string;
+export declare function isEditorSessionEntry(v: unknown): v is EditorSessionEntry;
+export declare function normalizeEditorSessionEntry(session: EditorSessionEntry): EditorSessionEntry;
+/** Whether pid exists. Signal 0's EPERM means it exists but this caller cannot signal it. */
+export declare function pidAlive(pid: number): boolean;
+/** The registry's live entries — shape-validated and PID-liveness-filtered. */
+export declare function readLiveRegisteredSessions(): EditorSessionEntry[];
+/** Announce a launch before the server can register. Each launcher owns its file. */
+export declare function announceEditorLaunch(project: string): () => void;
+/** Wait only for an observed live launcher, never for a missing editor. */
+export declare function waitForPendingEditorLaunch(project: string): Promise<void>;
+/** Read the project identity reported by /__editor/project. A serving path
+ * identifies an open project even when its manifest cannot be parsed or
+ * validated; project: null alone denotes no described project. */
+export declare function servedProjectAnswer(body: unknown): {
+    path: string | null;
+    manifestError: string | null;
+};

package/dist/registry-format.js

@@ -0,0 +1,21 @@
+import {
+  EDITOR_SESSIONS_REGISTRY_FILE,
+  announceEditorLaunch,
+  isEditorSessionEntry,
+  normalizeEditorSessionEntry,
+  pidAlive,
+  readLiveRegisteredSessions,
+  servedProjectAnswer,
+  waitForPendingEditorLaunch
+} from "./chunk-Y5W77HYT.js";
+export {
+  EDITOR_SESSIONS_REGISTRY_FILE,
+  announceEditorLaunch,
+  isEditorSessionEntry,
+  normalizeEditorSessionEntry,
+  pidAlive,
+  readLiveRegisteredSessions,
+  servedProjectAnswer,
+  waitForPendingEditorLaunch
+};
+//# sourceMappingURL=registry-format.js.map

package/dist/registry-format.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/session.d.ts

@@ -1,8 +1,7 @@
 /** Resolve an existing session for exactly one project.
  * Prefer the project's hint, verify it against the served canonical path,
- * then consult the shared registry. Never fall back to another project.
- * Storage identifiers move with the server in the coordinated migration. */
-import { type SessionListingTransport as SessionDiscoveryTransport } from '@volter/sdk/session/discovery';
+ * then consult the shared registry. Never fall back to another project. */
+import { type SessionListingTransport as SessionDiscoveryTransport } from './discovery.js';
 /** Nearest ancestor containing the project's canonical manifest. */
 export declare function findProjectRootFrom(dir: string): string | null;
 /** The minimal slice of `EditorTransport` `resolveSession` actually needs — narrower than the full interface so a test double only has to implement one method. */
@@ -32,4 +31,12 @@ export interface ProjectSessionHint {
 /** The code a refusal carries when the registry was read and no session opens the project: the
  *  one state in which "no editor is open here" is a fact, which `close` answers as done. */
 export declare const NO_SESSION_FOR_PROJECT = "VOLTER_NO_SESSION_FOR_PROJECT";
+/** The `code` of the refusal for this project's session whose manifest does not load; it carries `session`. */
+export declare const SESSION_MANIFEST_UNREADABLE = "VOLTER_SESSION_MANIFEST_UNREADABLE";
+/**
+ * Resolve `projectDir` (default `process.cwd()`) to its already-running editor
+ * session. Verify the project hint, then consult the shared registry, with
+ * each discovery probe bounded by `EDITOR_SESSION_DISCOVERY_TIMEOUT_MS`.
+ * Throw when no project manifest or matching live session is found.
+ */
 export declare function resolveSession(projectDir?: string, deps?: SessionResolutionDeps): Promise<ResolvedSession>;

package/dist/singleton.d.ts

@@ -1,18 +1,6 @@
-/**
- * A tiny memoized-async-factory primitive — the machinery behind
- * `index.ts`'s lazy top-level `editor`/`tools` singletons. Pulled into
- * its own module (rather than inlined) so it's independently unit-testable
- * with a fake factory, with no need to exercise a real `connect()` (session
- * discovery, network) just to prove "two accesses, one connect".
- *
- * Caches the in-flight PROMISE, not just the resolved value — two callers
- * racing `ensure()` before the first resolves still share the SAME
- * connection attempt, not two independent ones.
- */
+/** Memoized async connection. Concurrent ensure calls share the same in-flight promise. */
 export interface LazySession<T> {
     /** Returns the memoized promise, creating it via `factory()` on first call. */
     ensure(): Promise<T>;
-    /** Clears the memo — the NEXT `ensure()` calls `factory()` again. Exposed for tests (and for a caller that deliberately wants to reconnect); not needed in ordinary use. */
-    reset(): void;
 }
 export declare function createLazySession<T>(factory: () => Promise<T>): LazySession<T>;

package/dist/volter-manifest.d.ts

@@ -0,0 +1,55 @@
+/**
+ * THE NODE READER of a package's `package.json` as Volter reads it: its name, its dependency
+ * names and its `contributes.volter` declarations, which `@volter/sdk/volter-contributions` reads as the workbench and
+ * the page read them. The build's product plugin, the session's catalog and
+ * serving doors, the shared-React scope and the pre-bundle crawl all read a package here, so a
+ * declaration means one thing everywhere it is read.
+ *
+ * It parses and does no policy. What an unusable declaration costs is the caller's to say: a
+ * product build refuses it, the catalog reports it as a load error, a scope decision treats it
+ * as no declaration. {@link declaredContributions} is the one test of "this package contributes".
+ */
+export interface VolterManifest {
+    /** The `package.json`, absolute. */
+    readonly path: string;
+    /** Its package's directory. */
+    readonly dir: string;
+    readonly name: string | null;
+    readonly version: string | null;
+    readonly private: boolean;
+    readonly bin: unknown;
+    /** Every name in `dependencies`, `devDependencies` and `optionalDependencies`, in that order,
+     *  each once. */
+    readonly dependencyNames: readonly string[];
+    /** `package.json#contributes.volter`, unchecked: the package's contribution modules, an object
+     *  keyed by kind, and its declarations (`serving`, `viewRoutes`, `product`). It is where Code-OSS's extension
+     *  service reads them too, through the kit's `volter` extension point. */
+    readonly contributions: unknown;
+    /** `package.json#contributes.languageModelTools`, unchecked: the agent tools Code-OSS registers from it. */
+    readonly languageModelTools: unknown;
+    /** `package.json#contributes.volter.product`, a product's declaration, read and checked by `product-locator.ts`;
+     *  `undefined` when the package declares none or it is not an object. */
+    readonly product: ProductDeclaration | undefined;
+}
+/** `package.json#contributes.volter.product`, as declared and unchecked. */
+export interface ProductDeclaration {
+    readonly entry?: unknown;
+    readonly composes?: unknown;
+    readonly colorTheme?: unknown;
+    readonly workbench?: unknown;
+    readonly displayName?: unknown;
+    readonly install?: unknown;
+    readonly upgrade?: unknown;
+    readonly adapterRequired?: unknown;
+}
+/** `path`'s manifest, or `null` when there is no file there or it is not a JSON object. */
+export declare function readVolterManifest(path: string): VolterManifest | null;
+/**
+ * The package's declared modules, each contribution's and its page half's, with why any entry is refused; `null` when
+ * it declares none (an absent `contributes.volter`, or one that is not an object). A package with the object, even an
+ * empty one, is a contributing package: its modules are editor-tree code.
+ */
+export declare function declaredContributions(manifest: VolterManifest | null): {
+    readonly modules: readonly string[];
+    readonly errors: readonly string[];
+} | null;

package/dist/volter-manifest.js

@@ -0,0 +1,9 @@
+import {
+  declaredContributions,
+  readVolterManifest
+} from "./chunk-YPAOTPIF.js";
+export {
+  declaredContributions,
+  readVolterManifest
+};
+//# sourceMappingURL=volter-manifest.js.map

package/dist/volter-manifest.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/workbench-locator.d.ts

@@ -0,0 +1,84 @@
+import { type ProductIdentity } from './product-locator';
+/** Where a project declares its workbench, relative to the project root. */
+export declare const WORKBENCH_LOCATOR_PATH = ".volter/workbench.json";
+/** What the session reports about the workbench it is running. */
+export interface WorkbenchIdentity {
+    readonly kind: 'release' | 'sources';
+    /** The directory named by the declaration or the flag, resolved absolute. */
+    readonly dir: string;
+    /** The Code-OSS fork commit these bytes are. */
+    readonly commit: string;
+    readonly product: string;
+}
+/** Everything the session needs to run it, identity included. */
+export interface ResolvedWorkbench extends WorkbenchIdentity {
+    /** The executable to spawn, already known to exist. */
+    readonly serverBin: string;
+    /** Its working directory — the package root, or the checkout. */
+    readonly cwd: string;
+}
+/** The exact file to write, quoted in every refusal that wants one. */
+export declare function workbenchDeclarationExample(projectRoot: string): string;
+/**
+ * The workbench directory this project declares, or `null` when it declares
+ * none. Throws when the file exists and is not exactly `{ "workbench": <path> }`
+ * — unrecognized keys are refused.
+ */
+export declare function readWorkbenchDeclaration(projectRoot: string): string | null;
+/**
+ * WRITE THE DECLARATION — the one record of which workbench THIS machine opens
+ * this project in. Written by `<product> create --workbench <dir>`, and written
+ * by the fetch below, so the two paths cannot leave two different shapes of
+ * file behind.
+ */
+export declare function writeWorkbenchDeclaration(projectRoot: string, workbenchDir: string): void;
+/**
+ * The url the workbench answers on — the ONE url a person opens under the
+ * frame. Spelled here so the CLI's launch line and the session's tab bijection
+ * cannot disagree about it.
+ *
+ * `?project=<id>` is the one boot param the Volter editor carries; the session's
+ * one-origin proxy redirects it to the workbench's own `?folder=`, and
+ * `frame-proxy.ts` says why it must be a redirect.
+ */
+export declare function workbenchUrl(proxyPort: number, projectRoot: string): string;
+/** A project's stable key on this machine: its page's host, and its workbench extensions folder. */
+export declare function projectKey(projectRoot: string): string;
+/** The workbench at `dir`, refused where it is built for another product than `expectedProduct`; none named (a session
+ *  whose project's product cannot be resolved, which `/__editor/served-modules` explains) is not judged. */
+export declare function resolveWorkbench(dir: string, expectedProduct?: string): ResolvedWorkbench;
+/**
+ * WHERE FETCHED BYTES LIVE — one directory per release tag, per user (`~/.volter/workbenches`).
+ *
+ * Keyed by the TAG and nothing else, because that is what makes it a cache and
+ * not a decision: two projects on the same release share one directory,
+ * a second `create` consults no network, and a release is immutable, so a tag
+ * that is here is the tag that was published. Which workbench a project opens
+ * in is still recorded in the PROJECT (`.volter/workbench.json`, written the
+ * moment this resolves) — nothing ever searches this directory.
+ */
+export declare const WORKBENCH_CACHE_ROOT: string;
+/** Where the fetch talks. `log` is a line; `progress` is ONE line rewritten in
+ *  place (216 MB is a wait, and a wait with no number is a hang). */
+export interface WorkbenchFetchIO {
+    readonly log: (line: string) => void;
+    readonly progress?: (line: string) => void;
+}
+/**
+ * THE WORKBENCH THIS PROJECT OPENS IN, resolved in three steps:
+ *
+ *   1. `--workbench <dir>` — one launch, writes nothing.
+ *   2. `<project>/.volter/workbench.json` — this machine's record for this project.
+ *   3. the PRODUCT's declared release — fetched once, then written into (2).
+ *
+ * Step 3 is what makes the product's `create` open something
+ * on a machine that has never built anything, and it is why the CLI resolves
+ * the product BEFORE the workbench.
+ */
+export declare function resolveWorkbenchForProject(options: {
+    projectRoot: string;
+    product: ProductIdentity;
+    /** `--workbench <dir>`, when the person passed one. */
+    override?: string | undefined;
+    io: WorkbenchFetchIO;
+}): Promise<ResolvedWorkbench>;