@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/readiness.ts

@@ -0,0 +1,113 @@
+/**
+ * DECLARED READINESS, per root — the facet that makes "is this game ready?" an
+ * answer with a stated PROVENANCE instead of a host-side guess nobody can see.
+ *
+ * ARCHITECTURE-CORE §The editor protocol, "Zero inference". The question has
+ * exactly three answerers, and this module is where each one's answer lands:
+ *
+ *   · `host-mount` — a HOST-MOUNTED (exported-composition) root. The host runs
+ *     the mount, so mount completion IS readiness; no game code is needed and
+ *     the answer is `declared` for every first-party project by construction.
+ *   · `contract-ready` — a SELF-BOOTING game that declares
+ *     `window.volterGame.ready` (`@volter/project/adapter/ingest/game-contract`). Also
+ *     `declared`: the game stated it.
+ *   · `measured-wait` — a self-booting game that declares nothing. The measured
+ *     waits remain (they are the documented fallback), and this is the whole
+ *     point of the facet: that root reports `source: 'measured'`, so "nobody
+ *     stated this" is a visible fact rather than silence.
+ *
+ * Published as the `readiness` facet of `/__editor/state`
+ * (`command-listener.ts`'s `collectState`), which is what the editor's `status` command reads.
+ */
+
+import type {
+  MountFailureKind,
+  ReadinessSource,
+} from '@volter/project/adapter/ingest/mount-readiness';
+
+/** How a root's readiness is answered. See this module's header for each. */
+export type ReadinessMechanism = 'host-mount' | 'contract-ready' | 'measured-wait';
+
+export interface RootReadiness {
+  /** The manifest root id, as every other per-root facet names it. */
+  readonly rootId: string;
+  readonly mechanism: ReadinessMechanism;
+  /** `declared` for `host-mount`/`contract-ready`, `measured` otherwise — the
+   *  one field that makes a fallback legible as a fallback. */
+  readonly source: ReadinessSource;
+  /** `waiting` is a real state, not a missing answer: a self-booting game on a
+   *  hidden tab parks there indefinitely and nothing is wrong. */
+  readonly state: 'waiting' | 'ready' | 'failed';
+  /** Which of M29's three blockers, for a `failed` root. */
+  readonly failure?: MountFailureKind;
+}
+
+/**
+ * RESOURCE OWNERSHIP: one entry per root, written by the mount path that owns
+ * that root's lifecycle (`play-mode.ts` for host-mounted roots,
+ * `authoring/ingest-root-adapter.ts` for self-booting ones) and cleared by that
+ * same path's teardown. `clearRootReadiness` is per-root for the reason
+ * `clearMountFailureReport` is: a composite manifest mounts roots
+ * independently, and a blanket clear on one root's teardown would erase a
+ * sibling's still-true answer.
+ */
+const _readiness = new Map<string, RootReadiness>();
+let _snapshot: readonly RootReadiness[] = [];
+const _listeners = new Set<() => void>();
+
+function publish(): void {
+  _snapshot = [..._readiness.values()];
+  for (const listener of _listeners) listener();
+}
+
+/** `useSyncExternalStore`-compatible subscription for viewport explanations. */
+export function subscribeRootReadiness(listener: () => void): () => void {
+  _listeners.add(listener);
+  return () => _listeners.delete(listener);
+}
+
+export function recordRootReadiness(entry: RootReadiness): void {
+  _readiness.set(entry.rootId, entry);
+  publish();
+}
+
+export function clearRootReadiness(rootId: string): void {
+  if (!_readiness.delete(rootId)) return;
+  publish();
+}
+
+/** Test seam. Every production teardown clears PER ROOT (see the ownership note
+ *  above), so nothing but a test has the whole map's lifetime to drop. */
+export function clearAllRootReadiness(): void {
+  if (_readiness.size === 0) return;
+  _readiness.clear();
+  publish();
+}
+
+/**
+ * Every root's readiness, in the order they were recorded. `[]` means nothing
+ * has mounted — deliberately NOT the same as "nothing is ready", which is what
+ * a bare boolean would have said.
+ */
+export function readinessFacet(): readonly RootReadiness[] {
+  return _snapshot;
+}
+
+/**
+ * The one sentence a reader gets when a project's readiness is entirely
+ * measured — i.e. no root stated it and every answer here is a host-side wait.
+ * `null` when there is nothing to say (nothing mounted, or at least one root
+ * declared), because a warning that fires on healthy projects is a warning
+ * people learn to skip.
+ */
+export function measuredReadinessWarning(): string | null {
+  const entries = readinessFacet();
+  if (entries.length === 0) return null;
+  const measured = entries.filter((entry) => entry.source === 'measured');
+  if (measured.length === 0) return null;
+  return (
+    `${measured.length} of ${entries.length} root(s) have NO readiness declaration ` +
+    `(${measured.map((entry) => entry.rootId).join(', ')}) — the host is measuring instead. ` +
+    'A self-booting game states it with `window.volterGame.ready`.'
+  );
+}

package/src/kit/renderer-resource-counts.ts

@@ -0,0 +1,27 @@
+/**
+ * Renderer resource counts a media integration reports for the session's diagnostics
+ * (`status.rendererResources`): the Three viewport's interactive renderers, for one. The kit
+ * reads what is registered and imports no renderer.
+ */
+export interface RendererResourceCount {
+  readonly active: number;
+  readonly idle: number;
+}
+
+const providers = new Map<string, () => RendererResourceCount | number>();
+
+/** Report counts under `key`. Returns the teardown. */
+export function registerRendererResourceCounts(
+  key: string,
+  read: () => RendererResourceCount | number,
+): () => void {
+  providers.set(key, read);
+  return () => {
+    if (providers.get(key) === read) providers.delete(key);
+  };
+}
+
+/** Every registered provider's counts, read now. */
+export function rendererResourceCounts(): Record<string, RendererResourceCount | number> {
+  return Object.fromEntries([...providers].map(([key, read]) => [key, read()]));
+}

package/src/kit/reported-play-state.ts

@@ -0,0 +1,90 @@
+/**
+ * Honest play-state reporting for the control API (the editor's `status` command) — the
+ * derivation half of the SimCity ledger's S-1 "false-alive ingest status".
+ *
+ * ## The defect this closes
+ *
+ * `EditorShellStore.playState` is EDITOR UI STATE. Every lane that mounts
+ * something writes `'playing'` into it, but only play mode's write is
+ * accompanied by a live `play-mode.ts` `_session`, which is the predicate the
+ * whole debug seam gates on (`isPlayModeActive()`, `command-listener.ts`'s
+ * `notPlayingResult`). `collectState` reported the store flag verbatim, so a
+ * mounted lane printed `playState: "playing"` while every `game.state()` /
+ * `game.command()` call refused with "not in play mode" — the two predicates
+ * disagreeing in the same breath.
+ *
+ * Worse, a lane sets `'playing'` BEFORE the mount is attempted (it is what
+ * swaps the viewport onto the live scene). A mount that then threw left the
+ * flag behind, so a DEAD game reported itself alive.
+ *
+ * ## The rule
+ *
+ * A reported play state is a claim about something that is actually running,
+ * so it is derived from the LIVE-SESSION REGISTRY (`live-session-registry.ts`)
+ * — the host's one question about what runs — never from the UI flag alone,
+ * and it names no lane:
+ *
+ *  - nothing mounted is `stopped`, whatever the stale flag says;
+ *  - a mount whose lane was not asked to run is `paused` — a freshly mounted,
+ *    still-cold session is `paused`, not `playing`;
+ *  - otherwise the store flag, which for a running lane is written in lockstep.
+ *
+ * Pure and injectable so the whole decision is unit-testable with no browser
+ * (`packages/editor/test/ingest-status.test.ts`).
+ *
+ * ## Why this is not folded back into the store's getter
+ *
+ * Because the two answer different questions, and the store's is the one the
+ * editor itself needs. `isPlayModeActive()` is `_instance.session !== null`,
+ * assigned only after the mount resolves — so a derived `store.playState` would
+ * read `'stopped'` for the whole play boot (manifest fetch, entry resolution,
+ * the mount itself), and the structural-edit block, the design session's
+ * suspend, the Play bar and the viewport-tab predicates would all act as though
+ * nothing were starting. The store's flag stays the editor's MODE; this stays
+ * the report.
+ */
+
+import type { MountFailureReport } from '@volter/sdk/kit/mount-failure-report';
+
+/** The vocabulary `EditorShellStore.playState` and the SDK's status both use. */
+export type ReportedPlayState = 'stopped' | 'playing' | 'paused';
+
+/** Everything the derivation reads. Assembled by the caller from the live
+ *  module singletons so this module itself imports no session state. */
+export interface LiveSurfaceFacts {
+  /** `EditorShellStore.playState` — the UI flag, used only where it is backed. */
+  readonly storePlayState: ReportedPlayState;
+  /** `live-session-registry.ts`: some lane owns a canvas right now. */
+  readonly liveMounted: boolean;
+  /** `live-session-registry.ts`: some lane was asked to RUN content. */
+  readonly livePlaying: boolean;
+  /** Recorded mount failures (`authoring/mount-failure-report.ts`). */
+  readonly mountFailures: readonly MountFailureReport[];
+}
+
+/**
+ * The reported play state — derived from what is actually running, asked of
+ * the live-session registry so no lane is named: a held mount (a mounted game
+ * whose loop is stopped) is `paused`; a running one reports the store's
+ * playing/paused; nothing mounted is `stopped` whatever the store says.
+ */
+export function deriveReportedPlayState(facts: LiveSurfaceFacts): ReportedPlayState {
+  if (!facts.liveMounted) {
+    // Nothing is running. A leftover `'playing'`/`'paused'` here is exactly
+    // the false-alive report S-1 is about — a mount that threw after setting
+    // the flag.
+    return 'stopped';
+  }
+  if (!facts.livePlaying) return 'paused';
+  return facts.storePlayState === 'paused' ? 'paused' : 'playing';
+}
+
+/**
+ * True when the editor is reporting a world that FAILED to mount and has no
+ * live session to replace it. Consumers surface this as the "dead game" signal
+ * (the editor's `status` command's `mountFailures`, the status bar's mount-failure item)
+ * rather than making a reader diff two other fields to notice.
+ */
+export function hasDeadMount(facts: LiveSurfaceFacts): boolean {
+  return facts.mountFailures.length > 0 && !facts.liveMounted;
+}

package/src/kit/resolve-contributed-command.ts

@@ -0,0 +1,14 @@
+import type { CommandSpec } from '@volter/sdk/commands';
+import { isRelayCommandType } from '@volter/sdk/session/command-table';
+import { contributedCommand } from '@volter/sdk/kit/command-registry';
+
+/** A listener can attach before the presentation-deferred contribution pass.
+ * A requested package command needs that pass now; absence is only meaningful
+ * after the current project's contributions have finished installing. */
+export async function resolveContributedCommand(type: unknown): Promise<CommandSpec | null> {
+  const found = contributedCommand(type);
+  if (found || typeof type !== 'string' || isRelayCommandType(type)) return found;
+  await (await import('@volter/sdk/kit/initial-project')).projectBootstrapSettled();
+  await (await import('@volter/sdk/kit/tool-loader')).refreshProjectToolContributions();
+  return contributedCommand(type);
+}

package/src/kit/resolve-relative-specifier.ts

@@ -0,0 +1,33 @@
+/**
+ * Resolve a RELATIVE import specifier against an index of known project
+ * paths — the extensionless-import answer (`./x` → `x.tsx`/`x.ts`/index
+ * variants) answered from a REAL index, never by guessing an extension onto
+ * a path. `null` when the specifier is not relative or nothing in the index
+ * matches. The one algorithm behind both the component index and the
+ * project adapter's module resolver; two copies of the candidate list is
+ * how play and the finders disagree about which module a specifier names.
+ */
+export function resolveRelativeSpecifier(
+  specifier: string,
+  fromPath: string,
+  paths: ReadonlySet<string>,
+): string | null {
+  if (!specifier.startsWith('.')) return null;
+  const dir = fromPath.replaceAll('\\', '/').split('/').slice(0, -1);
+  for (const segment of specifier.split('/')) {
+    if (segment === '.' || segment === '') continue;
+    if (segment === '..') dir.pop();
+    else dir.push(segment);
+  }
+  const base = dir.join('/');
+  for (const candidate of [
+    base,
+    `${base}.tsx`,
+    `${base}.ts`,
+    `${base}/index.tsx`,
+    `${base}/index.ts`,
+  ]) {
+    if (paths.has(candidate)) return candidate;
+  }
+  return null;
+}

package/src/kit/retained-document-states.ts

@@ -0,0 +1,91 @@
+interface DisposableSource {
+  dispose(): void;
+}
+
+export interface RetainedDocumentState {
+  readonly documentId: string;
+  inUse: boolean;
+  source: DisposableSource | null;
+}
+
+/** CPU state belongs to an open document, not to the lifetime of its last pane. */
+export class RetainedDocumentStates<T extends RetainedDocumentState> {
+  private readonly states = new Map<string, T[]>();
+  private readonly generations = new WeakMap<T, number>();
+  private unsubscribe: (() => void) | null = null;
+
+  constructor(
+    private readonly create: (documentId: string) => T,
+    private readonly isOpen: (documentId: string) => boolean,
+    private readonly subscribe: (changed: () => void) => () => void,
+  ) {}
+
+  claim(documentId: string): T {
+    const states = this.states.get(documentId) ?? [];
+    let state = states.find(candidate => !candidate.inUse);
+    if (!state) {
+      state = this.create(documentId);
+      states.push(state);
+      this.states.set(documentId, states);
+    }
+    state.inUse = true;
+    this.generations.set(state, this.generation(state) + 1);
+    this.unsubscribe ??= this.subscribe(() => this.discardClosed());
+    return state;
+  }
+
+  generation(state: T): number {
+    return this.generations.get(state) ?? 0;
+  }
+
+  release(state: T, generation = this.generation(state)): void {
+    if (this.generation(state) !== generation) return;
+    state.inUse = false;
+    // React cleanup may precede the registry's close notification. The
+    // subscription also handles closing a pane that was already unmounted.
+    queueMicrotask(() => this.discardClosed());
+  }
+
+  /** A gesture may finish releasing its source after its document has closed
+   * or its state slot has been claimed by a replacement pane. */
+  retain(state: T, source: NonNullable<T['source']>, generation: number): void {
+    if (
+      !this.isOpen(state.documentId) ||
+      !this.states.get(state.documentId)?.includes(state) ||
+      this.generation(state) !== generation
+    ) {
+      source.dispose();
+      return;
+    }
+    const previous = state.source;
+    state.source = source;
+    if (previous !== source) previous?.dispose();
+  }
+
+  private discardClosed(): void {
+    const discarded: T[] = [];
+    for (const [documentId, states] of this.states) {
+      if (this.isOpen(documentId)) continue;
+      const remaining = states.filter(state => state.inUse);
+      discarded.push(...states.filter(state => !state.inUse));
+      if (remaining.length) this.states.set(documentId, remaining);
+      else this.states.delete(documentId);
+    }
+    if (this.states.size === 0) {
+      this.unsubscribe?.();
+      this.unsubscribe = null;
+    }
+    // Remove ownership first, even if a disposer throws or publishes a change.
+    const failures: unknown[] = [];
+    for (const state of discarded) {
+      const source = state.source;
+      state.source = null;
+      try {
+        source?.dispose();
+      } catch (error) {
+        failures.push(error);
+      }
+    }
+    if (failures.length) throw new AggregateError(failures, 'Retained document cleanup failed');
+  }
+}