@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/editor-runtime.tsx

@@ -0,0 +1,147 @@
+/**
+ * THE EDITOR RUNTIME CONTEXT — the light half of what `EditorContext.tsx`
+ * used to be: the `EditorRuntime` shape (store, stats, init promise,
+ * session), the React context that carries it, `EditorRuntimeProvider`,
+ * and every `use*` hook that reads it. Nothing here starts a lifecycle:
+ * no project discovery, no command listener, no save wiring. That is the
+ * point of the split — a connected component's only dependency on the
+ * editor is this module (closure: the shell store, the history session and
+ * two context helpers), so a bounded host (a document mounted alone,
+ * Storybook, a component test) mounts the same components without the
+ * application's whole boot graph. `EditorContext.tsx` keeps the
+ * application-level `EditorProvider` that owns those lifecycles.
+ *
+ * Measured 2026-09-03 (`scripts/validate-editor-closure.mjs --rank`): the
+ * bounded entry's closure was 505 files, 500 of them through
+ * `EditorContext.tsx`'s lifecycle imports, and the web build put 6.5 MB of
+ * the editor into that page for one Provider. This module is the cut.
+ */
+
+import { type InteractiveEditScope, InteractiveEditScopeContext } from '@volter/sdk/widgets';
+import { type ReactNode, Suspense, useContext, useMemo, useSyncExternalStore } from 'react';
+import type { ShellStore } from '@volter/sdk/kit/shell-store';
+import type { EditorSession } from '@volter/sdk/kit/history/editor-session';
+import type { HistoryCommandSnapshot, HistoryCommands } from '@volter/sdk/kit/history/history-commands';
+import type { HistoryService, HistorySnapshot } from '@volter/sdk/kit/history/history-service';
+import { createHmrStableReactContext } from '@volter/sdk/kit/hmr-stable-react-context';
+
+export interface EditorStats {
+  fps: number;
+  frameTime: number;
+  drawCalls: number;
+  triangles: number;
+  cameraPosition: { x: number; y: number; z: number };
+  cameraTarget: { x: number; y: number; z: number };
+}
+
+export interface EditorRuntime {
+  store: ShellStore;
+  stats: EditorStats;
+  initPromise: Promise<void>;
+  session: EditorSession;
+}
+
+const EditorContext = createHmrStableReactContext<EditorRuntime | null>(
+  // Vite's HMR data when a dev server serves this module; the SDK carries no bundler types.
+  (import.meta as ImportMeta & { hot?: { data: Record<string, unknown> } }).hot?.data,
+  'EditorContext',
+  null,
+);
+
+/**
+ * Provide an already-constructed editor runtime without starting project
+ * discovery, filesystem initialization, command listeners, or global bridges.
+ *
+ * The application-level {@link EditorProvider} below owns those lifecycles.
+ * Bounded production hosts (Storybook, component tests, embedded tools) use
+ * this provider so they render the same connected components against explicit
+ * dependencies instead of cloning the UI or accidentally booting a project.
+ */
+export function EditorRuntimeProvider({
+  runtime,
+  children,
+}: {
+  readonly runtime: EditorRuntime;
+  readonly children: ReactNode;
+}) {
+  // The shell's interactive-edit scope is INERT by design: coalescing a drag
+  // into one undo entry is each adapter's own business, done next to the
+  // writes it owns, so nothing here needs to bracket them.
+  const editScope = useMemo<InteractiveEditScope>(() => ({ begin: () => {}, end: () => {} }), []);
+
+  return (
+    <EditorContext.Provider value={runtime}>
+      <InteractiveEditScopeContext.Provider value={editScope}>
+        <Suspense>{children}</Suspense>
+      </InteractiveEditScopeContext.Provider>
+    </EditorContext.Provider>
+  );
+}
+
+export function useEditorStore(): ShellStore {
+  const ctx = useContext(EditorContext);
+  if (!ctx) throw new Error('useEditorStore must be used within <EditorProvider>');
+  return ctx.store;
+}
+
+export function useEditorStats(): EditorStats {
+  const ctx = useContext(EditorContext);
+  if (!ctx) throw new Error('useEditorStats must be used within <EditorProvider>');
+  return ctx.stats;
+}
+
+export function useEditorInit(): Promise<void> {
+  const ctx = useContext(EditorContext);
+  if (!ctx) throw new Error('useEditorInit must be used within <EditorProvider>');
+  return ctx.initPromise;
+}
+
+export function useHistoryService(): HistoryService {
+  const ctx = useContext(EditorContext);
+  if (!ctx) throw new Error('useHistoryService must be used within <EditorProvider>');
+  return ctx.session.history;
+}
+
+/** History-aware panels may still be rendered in isolated component tests. */
+export function useOptionalHistoryService(): HistoryService | null {
+  return useContext(EditorContext)?.session.history ?? null;
+}
+
+/**
+ * The shell store WHEN THERE IS A SHELL — `null` in a bounded host.
+ *
+ * Same contract as {@link useOptionalHistoryService}, and it exists for the
+ * same reason: the surfaces `scripts/validate-editor-closure.mjs` pins are
+ * exactly the ones a bounded host mounts with no `EditorProvider` above them
+ * (`@volter/editor-blender`'s Model document mounts `ToolObject3DAuthoring` that way).
+ * A stage asking what the WORKSPACE is showing must be able to hear "there is
+ * no workspace" instead of throwing the host's own document off the screen.
+ */
+export function useOptionalEditorStore(): ShellStore | null {
+  return useContext(EditorContext)?.store ?? null;
+}
+
+/** The shell's frame/camera readout WHEN THERE IS A SHELL — same contract as
+ *  {@link useOptionalEditorStore}, for the stage host: the world root's stage
+ *  writes this every frame and the shell's own readouts (`CameraInfo`,
+ *  `StatsOverlay`) read it, while a bounded host has neither. */
+export function useOptionalEditorStats(): EditorStats | null {
+  return useContext(EditorContext)?.stats ?? null;
+}
+
+export function useHistoryCommands(): HistoryCommands {
+  const ctx = useContext(EditorContext);
+  if (!ctx) throw new Error('useHistoryCommands must be used within <EditorProvider>');
+  return ctx.session.historyCommands;
+}
+
+export function useHistoryCommandSnapshot(): HistoryCommandSnapshot {
+  const history = useHistoryCommands();
+  return useSyncExternalStore(history.subscribe, history.getSnapshot, history.getSnapshot);
+}
+
+export function useHistorySnapshot(): HistorySnapshot {
+  const history = useHistoryService();
+  return useSyncExternalStore(history.subscribe, history.getSnapshot, history.getSnapshot);
+}
+

package/src/kit/editor-server-response.ts

@@ -0,0 +1,86 @@
+/**
+ * One reader for "did the EDITOR SERVER answer this, and what did it say?"
+ *
+ * ## Why `response.ok` is not that question
+ *
+ * Every editor route lives under `/__editor/*` on the same origin as the
+ * editor page. When no editor server is in front of that origin — a static
+ * preview of `dist/`, a misconfigured deployment — the host still answers:
+ * with the SPA FALLBACK, which is `200 OK` and
+ * `text/html`. So `response.ok` is TRUE for a request nothing handled.
+ *
+ * That turned into two different fabrications, depending on what the caller did
+ * next:
+ *
+ *  - callers that PARSED died inside `res.json()` on `Unexpected token '<'`, an
+ *    error naming neither the route nor the cause, usually into a bare `catch`
+ *    that returned an empty value the UI then reported as a fact about the
+ *    project ("No project tools registered", "no portable CSF previews");
+ *  - callers that did NOT parse — a POST whose only interest is "did it work?"
+ *    — read the fallback as SUCCESS. Marking a generation job read, forgetting
+ *    one, reconciling providers: each reported done, having reached nothing.
+ *
+ * The second is the worse half, and it is invisible: there is no exception to
+ * catch, so the only symptom is state that never actually changed.
+ *
+ * ## The rule
+ *
+ * A response is from the editor server when its content type is JSON. Every
+ * `/__editor/*` route answers JSON — including its FAILURES, which carry
+ * `{ error }` — while the page fallback never does, so the check has no false
+ * negatives to trade against. Callers that already guard the REALM
+ * (`getEditorMode()`) still use this: the realm guard says "don't ask", this
+ * says "that answer isn't ours", and a deployment can put a page fallback in
+ * front of a mode the client believes is served.
+ *
+ * The header's question is really two, so there are two entry points:
+ *
+ *  - {@link assertEditorServerAnswered} — "did the editor server answer this?"
+ *    alone, for the many callers that then read the server's OWN `{ error }`
+ *    body on a non-OK status. Asserting `ok` for them would replace a real,
+ *    user-facing server message ("Insufficient credits") with a bare status
+ *    code, so they get the fallback check and keep their own status handling.
+ *  - {@link assertEditorServerResponse} / {@link editorServerJson} — answered
+ *    AND OK, for callers with no interest in the failure body.
+ */
+
+/** The single sentence a page-fallback answer gets, so the reader is sent to
+ *  the host rather than to their own project. */
+function fallbackMessage(what: string, contentType: string): string {
+  return (
+    `${what}: this origin answered with its page fallback (${contentType || 'no content-type'}) ` +
+    'rather than JSON, so no editor server handled the request.'
+  );
+}
+
+/**
+ * Throw unless `response` came from the editor server AT ALL — ignoring its
+ * status, which is the caller's own business.
+ *
+ * For callers that read the route's `{ error }` body on failure: run this
+ * BEFORE `response.json()`, so a page fallback reports itself instead of dying
+ * as `Unexpected token '<'` in the parse.
+ */
+export function assertEditorServerAnswered(response: Response, what: string): void {
+  const contentType = response.headers.get('content-type') ?? '';
+  if (!contentType.includes('application/json')) {
+    throw new Error(fallbackMessage(what, contentType));
+  }
+}
+
+/**
+ * Throw unless `response` really came from the editor server AND succeeded.
+ *
+ * For callers whose only question is whether the call took effect (POST/DELETE
+ * routes with no interesting body).
+ */
+export function assertEditorServerResponse(response: Response, what: string): void {
+  if (!response.ok) throw new Error(`${what} (${response.status}).`);
+  assertEditorServerAnswered(response, what);
+}
+
+/** {@link assertEditorServerResponse}, then the parsed body. */
+export async function editorServerJson<T>(response: Response, what: string): Promise<T> {
+  assertEditorServerResponse(response, what);
+  return (await response.json()) as T;
+}

package/src/kit/editor-session-attribution.ts

@@ -0,0 +1,85 @@
+/**
+ * WHO THIS EDITOR SESSION IS, AND WHAT REVISION IT LAST SAW — the stamp every
+ * host source write carries.
+ *
+ * Three facts, all of them the page's own:
+ *  - the PARTICIPANT ID this tab writes under, seeded by the server's
+ *    bootstrap global and otherwise persisted per browser. `editor-presence.ts`
+ *    re-exports it as `EDITOR_PARTICIPANT_ID`, which is the name the rest of
+ *    the host knows it by.
+ *  - the session's GUEST flag: this page reached the editor through a shared
+ *    tunnel, so three host surfaces disable what a guest may not do
+ *    (`account.ts`, `components/ProjectHeader.tsx`,
+ *    `components/WorktreeSwitcher.tsx`).
+ *  - the last source REVISION this page observed, which every write sends as
+ *    `expectedRevision` so the server can refuse a stale one. That is
+ *    optimistic concurrency on the storage seam, not a feature: the readers
+ *    are `storage/http-storage.ts`, `ui-source/source-write-backend.ts`,
+ *    `history/project-root-history-backends.ts`,
+ *    `authoring/edit-mode-authoring.ts` and `source-conflict.ts`.
+ *
+ * IT WAS CALLED `collaboration-attribution.ts` UNTIL THE FINAL AUDIT, and the
+ * name was the only thing that ever made it an opinion — two audits filed it
+ * under 'collaboration and presence' and named a door for it that the host
+ * does not need, because nothing here is a lane's: a page identifies itself
+ * and stamps its writes whether or not anyone else is connected. TWO sibling
+ * packages read it (the collaboration package takes the guest flag,
+ * `@volter/editor-game` takes the write stamp), which by the rule `@volter/editor-game` was
+ * landed on means it lives in neither. `WORK.md` §THE FINAL AUDIT.
+ */
+const participantKey = 'volter.collaboration.participant.v1';
+const remoteShareKey = 'volter.collaboration.remote-share.v1';
+const bootstrap = (
+  globalThis as typeof globalThis & {
+    __VOLTER_EDITOR_PRESENCE_BOOTSTRAP__?: {
+      participantId?: string;
+      displayName?: string;
+    };
+  }
+).__VOLTER_EDITOR_PRESENCE_BOOTSTRAP__;
+
+function storedParticipantId(): string {
+  if (bootstrap?.participantId) return bootstrap.participantId;
+  const generated = globalThis.crypto?.randomUUID?.() ?? `participant-${Date.now()}`;
+  try {
+    const stored = globalThis.localStorage?.getItem(participantKey);
+    if (stored) return stored;
+    globalThis.localStorage?.setItem(participantKey, generated);
+  } catch {
+    // Storage can be blocked; page-lifetime identity is still usable.
+  }
+  return generated;
+}
+
+export const COLLABORATION_PARTICIPANT_ID = storedParticipantId();
+export const COLLABORATION_REMOTE_SHARE = (() => {
+  try {
+    return globalThis.localStorage?.getItem(remoteShareKey) === '1';
+  } catch {
+    return false;
+  }
+})();
+export const COLLABORATION_PARTICIPANT_NAME = bootstrap?.displayName || 'Local editor';
+
+/**
+ * The source revision this page has seen, held on the PAGE, not in this module: the shell's
+ * bundled copy of this file and a declared package's source-served copy are two module instances
+ * on one page, and only the shell's collaboration client hears the revision stream. A module-local
+ * `let` left every other copy at 0, so a declared package's first write after anyone else's edit
+ * was refused as stale.
+ */
+const REVISION_SLOT = Symbol.for('volter.collaboration.revision');
+const revisionSlot = ((globalThis as unknown as Record<symbol, { value: number } | undefined>)[REVISION_SLOT] ??= {
+  value: 0,
+});
+
+export function setCollaborationRevision(value: number): void {
+  if (Number.isInteger(value) && value >= revisionSlot.value) revisionSlot.value = value;
+}
+
+export function sourceMutationAttribution(): {
+  participantId: string;
+  expectedRevision: number;
+} {
+  return { participantId: COLLABORATION_PARTICIPANT_ID, expectedRevision: revisionSlot.value };
+}

package/src/kit/editor-session-mode.ts

@@ -0,0 +1,54 @@
+/**
+ * WHICH MODE THE EDITOR IS IN — one predicate, in a leaf module.
+ *
+ * It lives here rather than beside its first reader because it has two kinds of
+ * reader now, and they must never drift: `coverage/session-vitals.ts` asks so
+ * the `edit-mode-static` invariant can judge the session, and the ingest mount
+ * paths ask so a freshly-loaded game can be HELD at design time
+ * (`ingest/ingest-play-control.ts`'s `ingestContentTimeForMode`). An instrument
+ * must not be an import of the thing it measures, so neither owns it.
+ *
+ * MODE IS A SESSION, NOT A LOOP — and reading it off the loops is the one
+ * mistake that would make the Edit-static check unable to fire.
+ *
+ * A first-party play, deferred-ingest play, module session, or explicit ingest
+ * ▶ exists because somebody asked the host to run content; that is the editor
+ * being in Play. An ingest loop merely TURNING is still not a mode — it is the
+ * condition "ingested games autoplay in Edit" describes. `ingestPlaying()` is
+ * safe to use here because it is NOT inferred from a moving loop: it is the
+ * host play-control latch, written only when that control releases or holds the
+ * required ingest pause surface. A game advancing behind the host's back cannot
+ * set it and therefore remains visible to the Edit-static invariant.
+ */
+
+import { anyLiveSessionPlaying } from '@volter/sdk/kit/live-session-registry';
+
+/** The editor is in Play when any registered lane is playing
+ *  (`live-session-registry.ts`): first-party Play, a deferred-ingest play, an
+ *  ingest ▶ held by the host play-control latch, a module session. */
+export function editorIsPlaying(): boolean {
+  return anyLiveSessionPlaying();
+}
+
+/**
+ * Whether a gesture closed RIGHT NOW is an AUTHORING edit — the question every
+ * source-write backend asks before it moves a byte
+ * (`authoring/source-persistence-backend.ts` and the two backends behind it).
+ *
+ * What an edit means is decided by the surface it is made on: a HELD world is
+ * being authored and the gesture belongs in the game's own source; a RUNNING
+ * one is being played, and a play-time edit is session-local.
+ * {@link editorIsPlaying} owns that whole answer, including the ingest play
+ * control, rather than making every caller remember a second condition. Play
+ * adoption normally hands its adapters no source backend at all, but not every
+ * world in a play session gets that treatment (`play-mode.ts` composes
+ * non-presented worlds with `structuralThree`, which carries one), so the
+ * mode is asked here rather than trusted to the composition.
+ *
+ * The converse case is what decides the shape: an ingest boot-mounted into the
+ * Game document and HELD on its title screen is being AUTHORED. So the test is
+ * the loop's state, never which document the mount happens to live in.
+ */
+export function editorIsAuthoring(): boolean {
+  return !editorIsPlaying();
+}

package/src/kit/editor-state-facets.ts

@@ -0,0 +1,74 @@
+/**
+ * THE STATE REPORT'S CONTRIBUTED FIELDS — what a lane adds to `collectState`
+ * (`command-listener.ts`: the editor's `status` command, the SDK's `editor.state`). The host
+ * reports the session; a lane reports what only it knows (its loop's time
+ * scale and liveness, its seed, whether a restart is required) through
+ * `@volter/sdk/host`'s `session.reportFacet`. Keys are spread in the
+ * order of registration; a lane never overrides a host key.
+ *
+ * ## A FACET MAY BE REUSABLE, and that is what let coverage leave the host
+ *
+ * `collectState` takes a previous full snapshot whose expensive facets it may
+ * COPY instead of re-deriving, and the list of copyable keys used to be a
+ * host constant (`command-listener.ts`'s `REUSABLE_DERIVED_FACETS`). That is
+ * the reason the four capability-GRADING families stayed host fields long
+ * after everything around them had left: their derivation costs 76ms–1.3s and
+ * a facet's collect ran on EVERY report, interaction path included, so
+ * registering them from a package would have put that cost back on the
+ * critical path this mechanism exists to keep it off.
+ *
+ * So a registration carries its own reusable key names, and the collect is
+ * handed the `reuse` snapshot. A reusing collect returns the copied values (or
+ * skips the work outright); {@link reusableFacetKeys} is what the host strips
+ * from an interaction PATCH by name. The choice stays the caller's — only
+ * `collectState`'s caller knows whether it is on a user's critical path — and
+ * a package never has to invent a cache of its own to approximate it.
+ */
+export interface EditorStateFacetOptions {
+  /**
+   * The keys this facet's collect may serve from `reuse` rather than
+   * re-deriving. They join the host's own reusable set: an interaction-path
+   * PATCH omits them (the server still holds the last full snapshot), and the
+   * deferred full collect that always follows makes them current again.
+   */
+  readonly reusableKeys?: readonly string[];
+}
+
+type FacetCollect = (reuse: Record<string, unknown> | null) => Record<string, unknown>;
+
+interface RegisteredFacet {
+  readonly collect: FacetCollect;
+  readonly reusableKeys: readonly string[];
+}
+
+const facets = new Set<RegisteredFacet>();
+
+export function registerEditorStateFacet(
+  collect: FacetCollect,
+  options?: EditorStateFacetOptions,
+): () => void {
+  const facet: RegisteredFacet = { collect, reusableKeys: options?.reusableKeys ?? [] };
+  facets.add(facet);
+  return () => {
+    facets.delete(facet);
+  };
+}
+
+export function collectEditorStateFacets(
+  /** A previous full snapshot a registered collect may copy its own reusable
+   *  keys from, or `null` for a full collect. */
+  reuse: Record<string, unknown> | null = null,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const facet of facets) Object.assign(out, facet.collect(reuse));
+  return out;
+}
+
+/** Every reusable key any registered facet declares — the contributed half of
+ *  the host's `REUSABLE_DERIVED_FACETS`, read fresh because a contribution
+ *  pass adds and removes facets while the session runs. */
+export function reusableFacetKeys(): readonly string[] {
+  const keys: string[] = [];
+  for (const facet of facets) keys.push(...facet.reusableKeys);
+  return keys;
+}