@volter/editor-core 0.5.57

package/src/editor-runtime.tsx

@@ -0,0 +1,145 @@
+/**
+ * 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/editor-sdk/widgets';
+import { type ReactNode, Suspense, useContext, useMemo, useSyncExternalStore } from 'react';
+import type { EditorShellStore } from './editor-shell-store';
+import type { EditorSession } from './history/editor-session';
+import type { HistoryCommandSnapshot, HistoryCommands } from './history/history-commands';
+import type { HistoryService, HistorySnapshot } from './history/history-service';
+import { createHmrStableReactContext } from './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: EditorShellStore;
+  stats: EditorStats;
+  initPromise: Promise<void>;
+  session: EditorSession;
+}
+
+const EditorContext = createHmrStableReactContext<EditorRuntime | null>(
+  import.meta.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(): EditorShellStore {
+  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(): EditorShellStore | 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/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/editor-session-attribution.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 (`@vgai/collaboration` takes the guest flag,
+ * `@vgai/game` takes the write stamp), which by the rule `@vgai/dom` was
+ * landed on means it lives in neither. `WORK.md` §THE FINAL AUDIT.
+ */
+const participantKey = 'vgai.collaboration.participant.v1';
+const remoteShareKey = 'vgai.collaboration.remote-share.v1';
+const bootstrap = (
+  globalThis as typeof globalThis & {
+    __VGAI_EDITOR_PRESENCE_BOOTSTRAP__?: {
+      participantId?: string;
+      displayName?: string;
+    };
+  }
+).__VGAI_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';
+
+let revision = 0;
+
+export function setCollaborationRevision(value: number): void {
+  if (Number.isInteger(value) && value >= revision) revision = value;
+}
+
+export function sourceMutationAttribution(): {
+  participantId: string;
+  expectedRevision: number;
+} {
+  return { participantId: COLLABORATION_PARTICIPANT_ID, expectedRevision: revision };
+}

package/src/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 './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();
+}