@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/creation-site-registry.ts

@@ -0,0 +1,160 @@
+/**
+ * The creation-site registry — the host-side half of the index whose
+ * source half is `server/creation-site-transform.ts`.
+ *
+ * ANTI-SHIM: the record NEVER touches the object. A `WeakMap` keyed by the
+ * constructed object is the whole storage, so an ingested game cannot see that
+ * it is being indexed — no new property, no symbol, no `userData` key, nothing
+ * enumerable, nothing a `for…in`/`Object.keys`/JSON round-trip can pick up.
+ * (This is the same rule the ingest adapter follows for its structural ids'
+ * sole exception, `userData.entityId`, which is a deliberate, documented
+ * identity tag; a provenance record has no such justification.)
+ *
+ * RESOURCE OWNERSHIP (brief-rule 4).
+ *  - THE MAP is owned by this module and scoped to the editor page's realm.
+ *    Every same-realm mount in the page shares it, which is correct: the
+ *    stamped modules are ordinary modules in that one realm and their `new`
+ *    expressions have exactly one place to report to.
+ *  - IT IS NEVER CLEARED, deliberately. A `WeakMap` holds no strong reference,
+ *    so a record dies with the object it describes — a game teardown that
+ *    dropped its scene has already emptied the registry of everything that
+ *    mattered. An explicit `clear()` on teardown would be a no-op dressed as
+ *    cleanup, and it would be WRONG for the upgrade path, where a late-captured
+ *    mount reuses objects constructed before the capture.
+ *  - THE INSTALLED GLOBAL is the ownable resource, and it has one owner:
+ *    `installGatedGameGlobals` (`gated-globals.ts`) installs it alongside the
+ *    other `__volter*` game-realm globals, once, at the same point in the
+ *    lifecycle. {@link installCreationSiteRecorder} returns an uninstall for
+ *    tests, which is the only caller that needs to take it back down.
+ */
+
+/** A source location a stamped `new` expression reported. */
+export interface CreationSite {
+  /** Project-root-RELATIVE path, POSIX separators (e.g. `src/scripts/sim/city.js`). */
+  file: string;
+  /** 1-based. */
+  line: number;
+  /** 0-based character offset. */
+  col: number;
+}
+
+/**
+ * What the read surfaces show for one object: either the anchor, or a NAMED
+ * reason there is none. There is no third, blank state — an unanchored object
+ * says why (the honest-floor rule).
+ */
+export type CreationSiteAnchor =
+  | ({ anchored: true; kind: 'source'; display: string } & CreationSite)
+  | { anchored: false; reason: string };
+
+/** The reason for an object that exists but was not constructed by a `new`
+ *  expression in a served project module — a three.js internal, a GLTF
+ *  loader's mesh, anything from a bundled dependency. The anchoring does not
+ *  reach these, so this is what the surfaces say, verbatim. */
+export const UNANCHORED_REASON =
+  'constructed outside project source (library internals or loader output)';
+
+/** The reason for a selection with no live object behind it at all. */
+export const NO_OBJECT_REASON = 'no live object for this selection';
+
+const sites = new WeakMap<object, CreationSite>();
+
+/**
+ * How many objects each anchor has constructed — the MULTIPLICITY signal.
+ *
+ * SimCity builds all 256 tiles from one line (`const tile = new Tile(x, y)`,
+ * `src/scripts/sim/city.js:59`), so "can this edit be written at its creation
+ * site?" has a second answer beyond "is there a literal there": writing that
+ * line would move every tile, and writing it for one tile is a lie about what
+ * the source says. Nothing else in the system knows the count — the WeakMap
+ * above is deliberately un-enumerable — so it is counted here, at the one place
+ * every construction reports to.
+ *
+ * A PLAIN `Map`, not a WeakMap, and never decremented: the count is over
+ * CONSTRUCTIONS, not live objects. That is the conservative direction — a site
+ * that built and dropped a hundred objects still refuses, which costs a refusal
+ * the user can read, where a count that forgot its history would eventually let
+ * a shared site be written as if it were unique. It is keyed by the site string,
+ * so it holds no reference to anything the game owns and cannot leak an object.
+ */
+const instances = new Map<string, number>();
+
+function siteKey(site: CreationSite): string {
+  return `${site.file}:${site.line}:${site.col}`;
+}
+
+/** The global name the served prelude calls through (must match
+ *  `CREATION_SITE_GLOBAL` in `server/creation-site-transform.ts`; the pairing is
+ *  asserted by `creation-site-registry.test.ts`). */
+export const CREATION_SITE_GLOBAL = '__volterRecordCreationSite';
+
+type Recorder = (o: unknown, file: string, line: number, col: number) => void;
+
+/**
+ * Record one construction. FIRST WRITE WINS: a constructor that returns an
+ * already-registered object (a cache, a singleton, an interned value) must not
+ * have its true creation site overwritten by the call site that merely asked
+ * for it again.
+ */
+export function recordCreationSite(o: unknown, file: string, line: number, col: number): void {
+  if (o === null || (typeof o !== 'object' && typeof o !== 'function')) return;
+  if (sites.has(o as object)) return;
+  const site: CreationSite = { file, line, col };
+  sites.set(o as object, site);
+  const key = siteKey(site);
+  instances.set(key, (instances.get(key) ?? 0) + 1);
+}
+
+/**
+ * How many objects this anchor has constructed. `0` for a site nothing was ever
+ * recorded at. Only `1` may be written by a single-object edit; a deliberate
+ * creation-site-default edit may address the full count after naming it — see
+ * `creation-site-edit.ts`'s `CreationSiteWriteScope`.
+ */
+export function instancesAtSite(site: CreationSite): number {
+  return instances.get(siteKey(site)) ?? 0;
+}
+
+/** Test-only: forget every recorded construction count. The WeakMap needs no
+ *  equivalent (it is collected with its keys) and deliberately has none. */
+export function resetCreationSiteCountsForTest(): void {
+  instances.clear();
+}
+
+/** The raw record for an object, or `null`. */
+export function creationSiteOf(o: unknown): CreationSite | null {
+  if (o === null || (typeof o !== 'object' && typeof o !== 'function')) return null;
+  return sites.get(o as object) ?? null;
+}
+
+/** `src/scripts/sim/city.js:59` — the text the inspector shows and the editor's `eval` command reads. */
+export function formatCreationSite(site: CreationSite): string {
+  return `${site.file}:${site.line}`;
+}
+
+/**
+ * The read-surface answer for one object: the anchor, or the named reason there
+ * isn't one. `null`/a non-object means the caller had no live object to ask
+ * about, which is a DIFFERENT honest answer from "the library built it".
+ */
+export function creationSiteAnchor(o: unknown): CreationSiteAnchor {
+  if (o === null || o === undefined) return { anchored: false, reason: NO_OBJECT_REASON };
+  const site = creationSiteOf(o);
+  if (!site) return { anchored: false, reason: UNANCHORED_REASON };
+  return { anchored: true, kind: 'source', ...site, display: formatCreationSite(site) };
+}
+
+/**
+ * Publish {@link recordCreationSite} on `globalThis` for the served prelude.
+ * Idempotent. Returns an uninstall — see the module header for who owns this.
+ */
+export function installCreationSiteRecorder(): () => void {
+  const g = globalThis as unknown as Record<string, unknown>;
+  const existing = g[CREATION_SITE_GLOBAL];
+  if (typeof existing === 'function') return () => {};
+  const recorder: Recorder = recordCreationSite;
+  g[CREATION_SITE_GLOBAL] = recorder;
+  return () => {
+    if (g[CREATION_SITE_GLOBAL] === recorder) delete g[CREATION_SITE_GLOBAL];
+  };
+}

package/src/kit/delegate-harness-registry.ts

@@ -0,0 +1,134 @@
+/**
+ * WHICH CODING HARNESSES CAN BE DELEGATED TO — the eleventh registry in the
+ * family of `workspace-document-restore.ts` (a kind owns its persisted state),
+ * `document-open-registry.ts` (a kind owns how it opens), `chrome-slot-registry
+ * .ts` (the host owns the place, a package owns what sits there),
+ * `content-entry-source-registry.ts` (the host owns the Content scope, a
+ * package owns why a component is content) and the seven since. Here: the host
+ * owns the DELEGATE FORM — the task text, the isolation choice, the branch
+ * name, the button, the notice line and `delegateEditorTask` itself — and a
+ * package owns WHICH AGENTS EXIST.
+ *
+ * WHY IT EXISTS. `components/WorktreeSwitcher.tsx`'s Delegate form was the
+ * single edge holding `api/agents.ts` and its three wire modules in the
+ * editor's eager import closure (WORK.md §The open-source launch, the four
+ * that remained of the harness bucket): it called `getHarnessChatSnapshot()`
+ * to list which harnesses are installed, and it named two of them by hand
+ * (`claude`, `codex`). A base library for making IDEs should not know the
+ * name of a coding agent.
+ *
+ * THE DOOR THE RECORD NAMED WAS A BIGGER ONE, AND THE CODE DID NOT WANT IT.
+ * Unit 21 specified "a chrome slot that can hand its filler a dismiss/refresh
+ * callback", i.e. the whole form becoming `@volter/agents`' surface. Measured
+ * against the form: of its ~120 lines, everything but the harness `<Select>`
+ * is the worktree board's own vocabulary — the branch slug, the two
+ * isolations, the copy about sibling checkouts, and
+ * `delegateEditorTask` (`api/worktrees.ts`, a `keep`-bucket module whose wire
+ * already takes a `harness` string). Moving it would have put the board's
+ * delegation UI inside the agents package AND changed `ChromeSlotFiller` —
+ * whose whole claim is that a slot is a PLACE, rendered `<filler.Content />`
+ * with no props — for every existing filler. What the host actually cannot
+ * answer is one question, so one question is what it asks.
+ *
+ * ASKED PER ISOLATION, so a source whose answer depends on where the task runs
+ * can say so; the host passes the isolation and reads a list.
+ *
+ * THE KIT ANSWERS FIRST. `WorktreeSwitcher.tsx` registers the harnesses supercode
+ * reports able to start (`/__editor/worktrees/harnesses`); a package may add more.
+ */
+
+/** How a delegated task is isolated from the caller's checkout — the board's
+ *  own vocabulary, passed to a source as the question's context. */
+export type DelegateIsolation = 'worktree' | 'current';
+
+export interface DelegateHarness {
+  /** The value `delegateEditorTask({ harness })` takes. */
+  readonly id: string;
+  /** What the picker shows. */
+  readonly label: string;
+}
+
+export interface DelegateHarnessSource {
+  /** Which module registered it. Re-registering the same owner REPLACES, so
+   *  an HMR re-evaluation leaves one source, not two. */
+  readonly owner: string;
+  /** Ascending; ties keep registration order. */
+  readonly order?: number;
+  /** Asking is a fetch, so this is async; the form re-asks whenever the
+   *  isolation or the registry version changes. */
+  readonly harnesses: (isolation: DelegateIsolation) => Promise<readonly DelegateHarness[]>;
+}
+
+const _sources: DelegateHarnessSource[] = [];
+const listeners = new Set<() => void>();
+let version = 0;
+
+function publish(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+/** Install a source. Returns the teardown. */
+export function registerDelegateHarnessSource(source: DelegateHarnessSource): () => void {
+  const stale = _sources.findIndex((item) => item.owner === source.owner);
+  if (stale >= 0) _sources.splice(stale, 1);
+  _sources.push(source);
+  _sources.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  publish();
+  return () => {
+    const at = _sources.indexOf(source);
+    if (at < 0) return;
+    _sources.splice(at, 1);
+    publish();
+  };
+}
+
+/**
+ * THE HOST'S ONE QUESTION. Every source's answer, in registration order, with
+ * the first claim on an id winning — two packages offering the same harness is
+ * one harness, and the one that registered earlier named it.
+ *
+ * A source that throws is skipped rather than taking the form down with it:
+ * the picker degrades to the harnesses that did answer, which is the same
+ * shape as no source at all.
+ */
+export async function delegateHarnesses(
+  isolation: DelegateIsolation,
+): Promise<readonly DelegateHarness[]> {
+  const seen = new Set<string>();
+  const out: DelegateHarness[] = [];
+  for (const source of _sources) {
+    let answered: readonly DelegateHarness[];
+    try {
+      answered = await source.harnesses(isolation);
+    } catch {
+      continue;
+    }
+    for (const harness of answered) {
+      if (seen.has(harness.id)) continue;
+      seen.add(harness.id);
+      out.push(harness);
+    }
+  }
+  return out;
+}
+
+/** The form's `useSyncExternalStore` subscription: a source arriving with a
+ *  contribution pass re-asks the question. */
+export function subscribeDelegateHarnessSources(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function delegateHarnessRegistryVersion(): number {
+  return version;
+}
+
+/** Test-only reset (mirrors the restore, open, chrome-slot and content-entry
+ *  registries'). */
+export function __resetDelegateHarnessSourcesForTest(): void {
+  _sources.length = 0;
+  publish();
+}

package/src/kit/document-areas.ts

@@ -0,0 +1,70 @@
+/**
+ * A DOCUMENT'S SECOND AREA, and the host chrome it borrows.
+ *
+ * The host draws one header strip over a document (the document's own header, then the stage's
+ * controls) and one tool shelf at its leading edge. A document that divides its body into two
+ * AREAS side by side (Blender's split 3D viewport) needs that chrome divided the same way,
+ * because each of Blender's areas carries its own header over itself and its own tool shelf. So
+ * the document declares its second area ({@link setDocumentSecondArea}):
+ *
+ *  - `headerWidth`: the host reserves that width at the strip's trailing edge, after its own
+ *    controls, which then end where the first area ends, and hands the region's element back
+ *    ({@link documentSecondAreaHeader}) for the document to draw the second area's header in;
+ *  - `shelf`: an element inside the second area, which the host fills with the same tool strip
+ *    its own shelf carries (the tools are the workspace's, not an area's).
+ *
+ * With no second area declared, the host draws its chrome as it always does.
+ */
+export interface DocumentSecondArea {
+  readonly headerWidth: number;
+  readonly shelf: HTMLElement | null;
+}
+
+const areas = new Map<string, DocumentSecondArea>();
+const headers = new Map<string, HTMLElement>();
+const listeners = new Set<() => void>();
+let version = 0;
+
+function changed(): void {
+  version++;
+  for (const listener of [...listeners]) listener();
+}
+
+/** Declare `documentId`'s second area, or remove it with null. */
+export function setDocumentSecondArea(documentId: string, area: DocumentSecondArea | null): void {
+  const current = areas.get(documentId);
+  const width = area === null ? null : Math.max(0, Math.round(area.headerWidth));
+  if (area === null ? current === undefined : current?.headerWidth === width && current.shelf === area.shelf) return;
+  if (area === null || width === null) areas.delete(documentId);
+  else areas.set(documentId, { headerWidth: width, shelf: area.shelf });
+  changed();
+}
+
+/** `documentId`'s second area, or null. */
+export function documentSecondArea(documentId: string): DocumentSecondArea | null {
+  return areas.get(documentId) ?? null;
+}
+
+/** The host's header region for the second area, once drawn; null before and after. */
+export function documentSecondAreaHeader(documentId: string): HTMLElement | null {
+  return headers.get(documentId) ?? null;
+}
+
+/** Called by the host as it draws and removes the second area's header region. */
+export function bindDocumentSecondAreaHeader(documentId: string, element: HTMLElement | null): void {
+  if ((headers.get(documentId) ?? null) === element) return;
+  if (element === null) headers.delete(documentId);
+  else headers.set(documentId, element);
+  changed();
+}
+
+export function subscribeDocumentAreas(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function documentAreasVersion(): number {
+  return version;
+}

package/src/kit/document-context-registry.ts

@@ -0,0 +1,193 @@
+import { documentStageAnnounced, documentViewport } from '@volter/sdk/kit/document-viewports';
+import { DOCUMENT_REGISTRATION_TIMEOUT_MS, waitUntil } from './wait-until';
+
+/**
+ * THE OPEN DOCUMENT'S OWN CONTEXT, published for the REPL door.
+ *
+ * A tool document (`workspace.document`) may hand the host ONE object — the
+ * live session it edits through — and `editor.document.run(ctx => …)`
+ * (the editor's `eval` command) runs a wire-carried step against it, in Edit mode, without
+ * play. This is the "explore in the REPL, commit as source" half of the
+ * parity program's one spine (docs/BLENDER-PARITY.md §Execution model): the
+ * mesh document publishes its `MeshEditSession`, whose `ctx` is the
+ * bpy-shaped edit context, so an agent phrases a modeling step the way the
+ * corpus does — context + selection + op — and reads the result back.
+ *
+ * Keyed by workspace document id; the door resolves the ACTIVE document and
+ * refuses by name when it published nothing (a data sheet, a story). A
+ * document re-publishes whenever its session object changes (a reload swaps
+ * it); publishing returns the unpublish.
+ *
+ * ITS SIBLING FACT, and the reason they share a module: whether a contributed
+ * document has MOUNTED AT ALL. Both are things a contribution's own React root
+ * tells the host about itself, and both exist because `ToolHost.tsx` renders
+ * that contribution into a SEPARATE root (`createEditorRoot(...).render(...)`),
+ * which React schedules — so nothing in the host's own commit can say whether
+ * the contribution has rendered yet. Every door that must not read a document
+ * "before it decided what it is" waits on one of these two.
+ */
+
+const _contexts = new Map<string, unknown>();
+const _contextOwners = new Map<string, symbol>();
+const _listeners = new Set<() => void>();
+const _mounted = new Set<string>();
+const _mountListeners = new Set<() => void>();
+
+let _version = 0;
+let _notificationPending = false;
+
+function _notifyContexts(): void {
+  // Contributions publish from their own React roots' effects. A host store
+  // update here can synchronously re-enter a pending host commit when React
+  // flushes passive effects. Publish the React snapshot after that stack has
+  // unwound; direct context readers still see the new handle immediately.
+  if (_notificationPending) return;
+  _notificationPending = true;
+  queueMicrotask(() => {
+    _notificationPending = false;
+    _version += 1;
+    for (const listener of [..._listeners]) listener();
+  });
+}
+
+export function publishDocumentContext(documentId: string, context: unknown): () => void {
+  // Remounted panes can publish the same long-lived view object. Cleanup
+  // belongs to this registration, not to the identity of that shared view.
+  const owner = Symbol(documentId);
+  _contextOwners.set(documentId, owner);
+  _contexts.set(documentId, context);
+  _notifyContexts();
+  return () => {
+    if (_contextOwners.get(documentId) !== owner) return;
+    _contextOwners.delete(documentId);
+    _contexts.delete(documentId);
+    _notifyContexts();
+  };
+}
+
+/**
+ * THE PUBLISHED CONTEXT HAS MOVED — said by the package that DRIVES the
+ * document, not by the one that published it.
+ *
+ * The context object is a live handle, so a package can change what it answers
+ * without ever republishing: `@volter/editor-blender` reads the engine through its RNA
+ * door and the answer decides which Properties TABS exist for the selected
+ * datablock (an armature has a Bone tab, a cube does not). Nothing in the
+ * host's own stores moves when that answer arrives, so before this existed the
+ * inspector had no reason to re-compose and the rail stayed at whatever the
+ * first render could see.
+ *
+ * `use-active-inspection.ts` subscribes to {@link documentContextVersion}, so
+ * this makes the whole inspection re-derive — matches included.
+ */
+export function notifyDocumentContextChanged(documentId: string): void {
+  if (!_contexts.has(documentId)) return;
+  _notifyContexts();
+}
+
+export function subscribeDocumentContexts(listener: () => void): () => void {
+  _listeners.add(listener);
+  return () => {
+    _listeners.delete(listener);
+  };
+}
+
+export function documentContextVersion(): number {
+  return _version;
+}
+
+export function documentContextFor(documentId: string): unknown {
+  return _contexts.get(documentId);
+}
+
+/** Opening a document activates its tab before an async model import can
+ * publish its context. The REPL waits for that publication; it never executes
+ * against a placeholder or mistakes a loading document for an unsupported one. */
+export function waitForDocumentContext(documentId: string, timeoutMs = 10_000): Promise<unknown> {
+  const current = documentContextFor(documentId);
+  if (current !== undefined) return Promise.resolve(current);
+  return new Promise((resolve) => {
+    const onPublish = () => {
+      const context = documentContextFor(documentId);
+      if (context === undefined) return;
+      clearTimeout(timeout);
+      _listeners.delete(onPublish);
+      resolve(context);
+    };
+    const timeout = setTimeout(() => {
+      _listeners.delete(onPublish);
+      resolve(undefined);
+    }, timeoutMs);
+    _listeners.add(onPublish);
+  });
+}
+
+export function __resetDocumentContextsForTest(): void {
+  _contexts.clear();
+  _contextOwners.clear();
+  _mounted.clear();
+}
+
+/**
+ * A CONTRIBUTED DOCUMENT'S REACT ROOT HAS COMMITTED — published by the host's
+ * own wrapper INSIDE that root (`ToolHost.tsx`), so every child effect has run
+ * by the time it fires. That ordering is the whole point: it is what lets an
+ * opener's `ready` read an absent stage announcement as "this document has no
+ * stage" rather than "the stage has not rendered yet"
+ * (`authoring/object3d-document-session-registry.ts`).
+ */
+export function markContributedDocumentMounted(documentId: string): () => void {
+  _mounted.add(documentId);
+  for (const listener of [..._mountListeners]) listener();
+  return () => {
+    _mounted.delete(documentId);
+  };
+}
+
+/** Resolves once this document's contribution has committed, `false` if the
+ *  bounded window elapses first — the same shape and reason as
+ *  {@link waitForDocumentContext} above. */
+export function waitForContributedDocumentMount(
+  documentId: string,
+  timeoutMs = 10_000,
+): Promise<boolean> {
+  if (_mounted.has(documentId)) return Promise.resolve(true);
+  return new Promise((resolve) => {
+    const onMount = () => {
+      if (!_mounted.has(documentId)) return;
+      clearTimeout(timeout);
+      _mountListeners.delete(onMount);
+      resolve(true);
+    };
+    const timeout = setTimeout(() => {
+      _mountListeners.delete(onMount);
+      resolve(false);
+    }, timeoutMs);
+    _mountListeners.add(onMount);
+  });
+}
+
+/**
+ * THE SHARED HALF OF EVERY OPENER'S `ready` (`document-open-registry.ts`): a
+ * document whose stage announced itself
+ * (`authoring/object3d-document-session-registry.ts`) is not ready to be
+ * driven until that stage has registered its session, and one that announced
+ * nothing is ready already. Each caller has already waited for its own MOUNT
+ * to settle — the asset family for its Inspector, a contributed document for
+ * the React root above — which is what makes an absent announcement mean
+ * "this document has no stage" rather than "the stage has not rendered yet".
+ *
+ * The refusal sentence is the one `editor-view-presentation.ts` used to throw,
+ * moved to the kinds' own side unchanged.
+ */
+export async function awaitAnnouncedObject3DDocumentSession(documentId: string): Promise<void> {
+  if (!documentStageAnnounced(documentId)) return;
+  if (
+    await waitUntil(
+      () => documentViewport(documentId) !== null,
+      DOCUMENT_REGISTRATION_TIMEOUT_MS,
+    )
+  )
+    return;
+  throw new Error(`The requested Object3D view did not mount for document: ${documentId}`);
+}