@volter/editor-core 0.5.57

package/src/active-project.ts

@@ -0,0 +1,155 @@
+/**
+ * THE ACTIVE PROJECT — the one store every surface reads the open project
+ * from, and nothing else. Split out of `project-manager.ts` so a host that
+ * only needs to know WHICH project is open (a bounded host, the
+ * contribution loader) does not carry the server boot path — the launcher,
+ * the server-project probe, the recent-projects list — and the server-SDK
+ * barrel those import. `project-manager.ts` re-exports everything here, so
+ * its importers are unchanged; a surface below the shell imports THIS file.
+ */
+
+import type { LearnMetadata } from '@volter/editor-project/manifest/schema';
+import type { HierarchyProjection } from './hierarchy-projection';
+
+/** One `run[]` declaration as the manifest carries it: the envelope plus the
+ *  kind's own fields (spelled here, not imported, so a bounded host's closure
+ *  stays free of the engine's kind registry). */
+export interface ConfigurationDeclaration {
+  readonly id: string;
+  readonly kind: string;
+  readonly [param: string]: unknown;
+}
+
+export interface ProjectConfig {
+  /** Project-file schema version. Kept distinct from game and engine versions. */
+  manifestVersion: 2;
+  name: string;
+  /** The authored game's own release version. */
+  version: string;
+  /** Exact engine identity the project is pinned to. */
+  engine: { version: string };
+  /** Editor-only organization. It never changes which runtime roots mount. */
+  authoring?: { hierarchy?: HierarchyProjection | undefined } | undefined;
+  resolution?: { width: number; height: number } | undefined;
+  appId?: string | undefined;
+  /**
+   * Multiplayer server config from the manifest (`server.room` — the Colyseus
+   * room this game registers), if declared. Carried here so edit-mode
+   * networking can answer "does this project declare a server" from the
+   * already-parsed manifest, NOT by re-reading `vgai.project.json` through the
+   * asset-scoped `StorageBackend.read` (which resolves under `public/` and so
+   * returns the SPA fallback for a root manifest — the bug that left the
+   * player-count picker hidden on the local dev server).
+   */
+  /** The manifest's run configurations (ARCHITECTURE-CORE §The project model). */
+  configurations?: readonly ConfigurationDeclaration[] | undefined;
+  /**
+   * Derived from the manifest roots. `false` means the editor must not
+   * fabricate its native Three scene document for this project. Optional
+   * only for legacy callers/tests; current project readers always provide it.
+   */
+  hasThreeRoot?: boolean | undefined;
+  /** How many roots the manifest declares — what MOUNTS. Zero is a real
+   *  shape (ARCHITECTURE-CORE §Roots): the chrome that only means something
+   *  for a running world (transport, instances, play state, analytics) is
+   *  derived from this, never from a project kind. */
+  rootCount?: number | undefined;
+  /**
+   * The project's default scene path, or `null` when the manifest's first
+   * world declares no scene (e.g. an `entry`-only world — §7.1-12). Always
+   * present when derived from the manifest (`readProjectView`, server-side).
+   * Consumers must NOT default a missing/null value to a guessed path: a
+   * guess resolves to a file nobody declared, and writing to it silently
+   * creates a placeholder the project never asked for.
+   */
+  defaultScene?: string | null | undefined;
+  /**
+   * FT-5 learner-facing metadata from the manifest's `learn` block. Carried
+   * for BUNDLED EXAMPLES opened read-only in the hosted editor so the shell
+   * can offer the example's Learn-site lesson ("This example has a lesson →",
+   * G6); absent everywhere else.
+   */
+  learn?: LearnMetadata | undefined;
+}
+
+export interface ActiveProject {
+  /** Absolute path to the project root (as passed via URL param / env). */
+  rootPath: string;
+  /** Parsed vgai.project.json project configuration plus derived editor fields. */
+  config: ProjectConfig;
+}
+
+let _activeProject: ActiveProject | null = null;
+const _listeners = new Set<() => void>();
+
+function _notify(): void {
+  for (const fn of _listeners) fn();
+}
+
+/**
+ * Set or clear the active project directly (project screen and bounded hosts).
+ *
+ * This is also where a project SESSION ends: switching to a different project
+ * without a page reload is a real path (the project screen's five open sites),
+ * and the editor's module-level session singletons do not reset themselves on
+ * it. Anything that must not outlive the previous project registers with
+ * {@link onProjectSessionEnd} — see `project-session-reset.ts`, the one
+ * subscriber, for the list.
+ */
+export function setActiveProject(project: ActiveProject | null): void {
+  const previous = _activeProject;
+  _activeProject = project;
+  // Only a genuine CHANGE of project ends a session: re-setting the same
+  // project (a config refresh after a manifest save) is not a switch, and
+  // resetting session state under it would drop a live mount for nothing.
+  if (previous && previous.rootPath !== project?.rootPath) {
+    for (const fn of _sessionEndListeners) fn();
+  }
+  _notify();
+}
+
+/**
+ * The boot/open path's own assignment: install the project just resolved
+ * WITHOUT the session-end notice — a session ends on a SWITCH
+ * ({@link setActiveProject}); resolving a project at boot or re-reading its
+ * manifest is not one. Same notify as the setter.
+ */
+export function assignActiveProject(project: ActiveProject): ActiveProject {
+  _activeProject = project;
+  _notify();
+  return project;
+}
+
+/** Get the currently open project, or null if none. */
+export function getCurrentProject(): ActiveProject | null {
+  return _activeProject;
+}
+
+/** Subscribe to project changes. Returns unsubscribe function. */
+export function onProjectChange(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => _listeners.delete(fn);
+}
+
+const _sessionEndListeners = new Set<() => void>();
+
+/**
+ * Subscribe to the END of a project session — fired by {@link setActiveProject}
+ * when a DIFFERENT project (or none) takes over.
+ *
+ * The sibling of {@link onProjectChange}, and deliberately not the same hook:
+ * `onProjectChange` means "re-derive against whatever project is open now" and
+ * fires for every notify, while this one means "the previous project's live
+ * state is over, drop it". Nothing but `project-session-reset.ts` subscribes;
+ * add a reset there rather than a second subscriber here.
+ */
+export function onProjectSessionEnd(fn: () => void): () => void {
+  _sessionEndListeners.add(fn);
+  return () => _sessionEndListeners.delete(fn);
+}
+
+/** The identity every per-project cache keys on: the open project's folder,
+ *  and a fixed unscoped key when no project is active. */
+export function activeProjectKey(): string {
+  return getCurrentProject()?.rootPath ?? '__unscoped__';
+}

package/src/adapter-editor-config.ts

@@ -0,0 +1,25 @@
+import type { AdapterEditorConfiguration } from '@volter/editor-project/adapter/adapter-module';
+import { activeProjectKey } from './active-project';
+
+// Published by the adapter loader; consumers need no dependency on its module graph.
+let configuration: AdapterEditorConfiguration = {};
+let owner: string | null = null;
+const EMPTY: AdapterEditorConfiguration = Object.freeze({});
+const listeners = new Set<() => void>();
+
+export function adapterEditorConfiguration(): AdapterEditorConfiguration {
+  return owner !== null && owner === activeProjectKey() ? configuration : EMPTY;
+}
+
+export function setAdapterEditorConfiguration(value: AdapterEditorConfiguration = {}): void {
+  owner = activeProjectKey();
+  configuration = value;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeAdapterEditorConfiguration(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}

package/src/adapter-observation.ts

@@ -0,0 +1,49 @@
+/**
+ * THE LOADED ADAPTER'S OBSERVATION DECLARATIONS, held host-side with their
+ * closures intact.
+ *
+ * Pushed rather than pulled, for exactly the reason `presentation-surface.ts`
+ * is: the reader is an ingest MOUNT, and having the mount import
+ * `project-adapter.ts` would drag the whole loader graph (the finder namespace,
+ * the manifest fetchers, the story registry) into the mount's module closure.
+ * `project-adapter.ts` stays the one place the table is decided; this is the
+ * one place the part that cannot travel over the wire is kept.
+ *
+ * "Cannot travel" is the whole reason this module exists separately from the
+ * `/__editor/state` facet. A declaration's `answer` is a CLOSURE evaluated
+ * against the mounted game, so the facet publishes only the statically readable
+ * half — id, kind, and whether an answer is bound — while the closures stay
+ * here, in the host realm, reachable by the mount that has a game to evaluate
+ * them against.
+ */
+
+import type {
+  AdapterInputBinding,
+  ObservationDeclaration,
+} from '@volter/editor-project/adapter/adapter-module';
+
+let _declarations: readonly ObservationDeclaration[] = [];
+let _input: AdapterInputBinding | null = null;
+
+/** Written by `project-adapter.ts` on every load — including with `[]`, so a
+ *  project switch cannot leave the previous game's closures reachable. */
+export function setAdapterObservations(declarations: readonly ObservationDeclaration[]): void {
+  _declarations = declarations;
+}
+
+/** What the loaded adapter declares. Empty before the first load, and for a
+ *  project whose adapter declares none — both are "nothing to project", which
+ *  is the only distinction a mount needs. */
+export function adapterObservations(): readonly ObservationDeclaration[] {
+  return _declarations;
+}
+
+/** The loaded adapter's app-owned input binding, or `null` when it declares none. */
+export function adapterInputBinding(): AdapterInputBinding | null {
+  return _input;
+}
+
+/** Written beside {@link setAdapterObservations} on every project load. */
+export function setAdapterInputBinding(binding: AdapterInputBinding | null): void {
+  _input = binding;
+}

package/src/animation/stage-transport.ts

@@ -0,0 +1,379 @@
+/**
+ * THE STAGE TRANSPORT — one position on a stage's facts, and the one holder
+ * of the content-time door (WORK.md §The stage transport and the animation
+ * door; owner ruling 2026-09-20).
+ *
+ * OWNERSHIP, STATED ONCE. The OWNER is the stage: `StageHost` constructs one
+ * transport beside the stage store it already owns, registers it under the
+ * document id, and disposes it when that document unmounts. The SHARERS are
+ * subjects (a world attaches what it can show at a time) and looks (the
+ * transport strip, Blender's Timeline) — both hold a handle and neither may
+ * end it. The ONE TEARDOWN PATH is the owning document's unmount; a subject
+ * detaching or a look unmounting never disposes the transport, because a
+ * stage outlives every look drawn over it. This is the rule the game-scoped
+ * clock destroyed by per-root teardown was missing.
+ *
+ * THE CONTENT-TIME POLICY IT INHERITS, quoted from `StageHost.tsx` where it
+ * was already written: on every stage PRESENTATION time (orbit, dressing,
+ * helpers) always advances, and CONTENT time advances ONLY through the one
+ * `advanceContent` door, and only while a human holds an explicit transport.
+ * This class IS that human's hand: `tick` returns the seconds it advanced and
+ * the host passes exactly that to `advanceContent`, so a stage with no
+ * transport demand still publishes a content clock that stood still
+ * (`coverage/design-time-surfaces.ts`).
+ *
+ * IT IS NOT THE SIM CLOCK. `core/sim-clock.ts` is the game's own time and
+ * this transport is INERT whenever it runs — `driver` reads the stage store's
+ * `playState`, and every write verb refuses by name while a world is driving.
+ *
+ * NO SECOND CLOCK, AND NO PRIVATE ONE. The time arithmetic is the engine's
+ * `AnimationClock` (ranges, loop laps, exact frame seeking); this class adds
+ * the subject registry, the driver gate and the settle debounce, and nothing
+ * else. `scripts/validate-import-bans.mjs`'s `private-clocks` row is the
+ * tripwire against a `requestAnimationFrame`/`performance.now` growing back
+ * in here or in a look.
+ */
+
+import type {
+  StageTransportSnapshot,
+  TransportPlaybackState,
+  TransportSubject,
+} from '@volter/editor-sdk/host';
+import { AnimationClock } from '@volter/editor-threejs/animation/animation-clock';
+import type { EditorShellStore } from '../editor-shell-store';
+
+/** The range a transport reports with nothing attached — a real, inert
+ *  domain, so a look never has to special-case `null` arithmetic. */
+const EMPTY_RANGE = { start: 0, end: 0, fps: 30, loop: false } as const;
+
+/** Scrub-end: the first quiet interval after a `seek` while not playing.
+ *  Long enough that a slider drag's frames coalesce into ONE settle, short
+ *  enough that releasing the mouse writes the bookmark without a visible wait. */
+const SETTLE_QUIET_MS = 150;
+
+export class StageTransport {
+  private readonly clock = new AnimationClock();
+  private readonly subjects: TransportSubject[] = [];
+  private activeId: string | null = null;
+  private readonly listeners = new Set<() => void>();
+  private readonly settleListeners = new Set<(seconds: number) => void>();
+  private settleTimer: ReturnType<typeof setTimeout> | null = null;
+  private disposed = false;
+  /**
+   * The last snapshot handed out, held until something changes.
+   * `useSyncExternalStore` compares snapshots by IDENTITY and re-renders
+   * forever if `getSnapshot` mints a fresh object each call, so the cache is
+   * not an optimization — it is what makes this class usable from React at
+   * all. `notify()` is the one invalidator, which is also the one place a
+   * change is announced, so the two cannot drift apart.
+   */
+  private cachedSnapshot: StageTransportSnapshot | null = null;
+
+  private readonly stopStoreWatch: () => void;
+
+  constructor(private readonly store: EditorShellStore) {
+    // `driver` reads the store, and the store changes WITHOUT any call on this
+    // class (entering Play is a store event). A snapshot cached across that
+    // would report `driver: 'editor'` while the world is already driving, so
+    // the strip would draw live controls over a running game. Invalidate here.
+    this.stopStoreWatch = store.subscribe(() => this.notify());
+  }
+
+  // ---------------------------------------------------------------- subjects
+
+  /**
+   * Attach a subject. The FIRST attach becomes active — a stage that just
+   * mounted one thing is immediately scrubbable with no further call. Returns
+   * the detach; detaching the active subject promotes whatever remains.
+   */
+  attach(subject: TransportSubject): () => void {
+    this.subjects.push(subject);
+    if (this.activeId === null) this.setActiveSubject(subject.id);
+    else this.notify();
+    return () => {
+      const at = this.subjects.indexOf(subject);
+      if (at < 0) return;
+      this.subjects.splice(at, 1);
+      if (this.activeId !== subject.id) {
+        this.notify();
+        return;
+      }
+      this.activeId = null;
+      const next = this.subjects[0];
+      if (next) this.setActiveSubject(next.id);
+      else {
+        this.clock.setRange({ start: EMPTY_RANGE.start, end: EMPTY_RANGE.end, loop: false });
+        this.notify();
+      }
+    };
+  }
+
+  /** Make `id` active: take ITS range, and clamp the current time into it —
+   *  switching subjects moves the playhead as little as the new domain allows. */
+  setActiveSubject(id: string): void {
+    const subject = this.subjects.find((s) => s.id === id);
+    if (!subject) return;
+    this.activeId = id;
+    const range = subject.range();
+    this.clock.setRange({ start: range.start, end: range.end });
+    // `setRange` only emits when it had to clamp, so re-assert the position
+    // unconditionally: every subject must be showing the transport's time,
+    // including the one that just became active inside an unchanged range.
+    this.applyTime(this.clock.time);
+    this.notify();
+  }
+
+  private get active(): TransportSubject | null {
+    return this.subjects.find((s) => s.id === this.activeId) ?? null;
+  }
+
+  private fps(): number {
+    return this.active?.range().fps ?? EMPTY_RANGE.fps;
+  }
+
+  // ------------------------------------------------------------------ driver
+
+  /**
+   * Who is advancing time. Reads the stage store this transport was built
+   * with and nothing else: for a Model document that store is always
+   * `'stopped'`, and for the Scene/Game document Play sets it.
+   */
+  private get driver(): 'editor' | 'world' {
+    return this.store.playState === 'stopped' ? 'editor' : 'world';
+  }
+
+  /** Refuse BY NAME, so a caller reads what to do rather than that it failed. */
+  private assertEditorDrives(): void {
+    if (this.driver === 'world') {
+      throw new Error('transport: the world is driving time (Play); pause the game to scrub');
+    }
+  }
+
+  // --------------------------------------------------------------- transport
+
+  play(direction: 'forward' | 'reverse' = 'forward'): void {
+    this.assertEditorDrives();
+    if (!this.active) return;
+    this.cancelSettle();
+    this.clock.play(direction);
+    this.notify();
+  }
+
+  pause(): void {
+    this.assertEditorDrives();
+    this.clock.pause();
+    this.cancelSettle();
+    this.settle();
+    this.notify();
+  }
+
+  /** `stop()` = `pause()` then home to the range's start. */
+  stop(): void {
+    this.assertEditorDrives();
+    this.clock.pause();
+    this.cancelSettle();
+    this.applyTime(this.clock.seek(this.clock.range.start).currentTime);
+    this.clock.stop();
+    this.settle();
+    this.notify();
+  }
+
+  seek(seconds: number): void {
+    this.assertEditorDrives();
+    this.applyTime(this.clock.seek(seconds).currentTime);
+    // A seek WHILE PLAYING never settles — only a scrub does, and a scrub is
+    // by definition not playback.
+    if (this.clock.playbackState !== 'playing') this.scheduleSettle();
+    this.notify();
+  }
+
+  /** Frames are the LOOK's unit, never the seam's: one conversion, here. */
+  seekFrame(frame: number): void {
+    this.seek(frame / this.fps());
+  }
+
+  setLoop(loop: boolean): void {
+    this.clock.setRange({ loop });
+    this.notify();
+  }
+
+  setTimeScale(scale: number): void {
+    this.clock.timeScale = scale;
+    this.notify();
+  }
+
+  /**
+   * Called by the stage host's frame callback with that frame's dt. Inert
+   * unless PLAYING and the editor drives. Returns the seconds advanced — the
+   * host adds exactly this to `host.contentSeconds` through `advanceContent`,
+   * which is what keeps the Edit-static vitals row honest.
+   */
+  tick(dt: number): number {
+    if (this.disposed || this.driver === 'world') return 0;
+    if (this.clock.playbackState !== 'playing') return 0;
+    const before = this.clock.time;
+    const crossing = this.clock.advance(dt);
+    if (!crossing) return 0;
+    this.applyTime(crossing.currentTime);
+    this.notify();
+    // Across a loop wrap `currentTime - before` is negative (and meaningless
+    // as an elapsed duration), so report the magnitude the clock was asked
+    // to move: that is what actually elapsed on this stage's content clock.
+    return crossing.looped ? Math.abs(dt) * this.clock.timeScale : crossing.currentTime - before;
+  }
+
+  /**
+   * Hand the crossing's time to EVERY attached subject, the active one first.
+   * Every subject, not just the active one: a stage showing two things at one
+   * position must not leave the inactive one frozen at whenever it was last
+   * looked at. The active one leads so the thing a person is watching is the
+   * first to update within a frame.
+   */
+  private applyTime(seconds: number): void {
+    const active = this.active;
+    if (active) active.seek(seconds);
+    for (const subject of this.subjects) {
+      if (subject !== active) subject.seek(seconds);
+    }
+  }
+
+  // ----------------------------------------------------------------- settled
+
+  onSettled(listener: (seconds: number) => void): () => void {
+    this.settleListeners.add(listener);
+    return () => {
+      this.settleListeners.delete(listener);
+    };
+  }
+
+  private scheduleSettle(): void {
+    this.cancelSettle();
+    this.settleTimer = setTimeout(() => {
+      this.settleTimer = null;
+      this.settle();
+    }, SETTLE_QUIET_MS);
+  }
+
+  private cancelSettle(): void {
+    if (this.settleTimer === null) return;
+    clearTimeout(this.settleTimer);
+    this.settleTimer = null;
+  }
+
+  private settle(): void {
+    if (this.disposed) return;
+    const at = this.clock.time;
+    for (const listener of [...this.settleListeners]) listener(at);
+  }
+
+  // ---------------------------------------------------------------- readback
+
+  snapshot(): StageTransportSnapshot {
+    const cached = this.cachedSnapshot;
+    if (cached) return cached;
+    const range = this.active?.range() ?? EMPTY_RANGE;
+    const next: StageTransportSnapshot = {
+      time: this.clock.time,
+      range: {
+        start: this.clock.range.start,
+        end: this.clock.range.end,
+        fps: range.fps,
+        loop: this.clock.range.loop,
+      },
+      playbackState: this.clock.playbackState as TransportPlaybackState,
+      timeScale: this.clock.timeScale,
+      activeSubject: this.activeId,
+      subjects: this.subjects.map((s) => ({ id: s.id, label: s.label })),
+      driver: this.driver,
+    };
+    this.cachedSnapshot = next;
+    return next;
+  }
+
+  /**
+   * The ACTIVE subject's clips, or `null` when it has none.
+   *
+   * Deliberately not on the snapshot: `StageTransportSnapshot` is the shape a
+   * CONTRIBUTION sees through the SDK, and a clip list is a three-world
+   * detail (Blender omits `clips` entirely — an action IS the subject there).
+   * The editor's own strip reaches it through the class it already imports.
+   */
+  activeClips(): readonly { id: string; label: string }[] | null {
+    const active = this.active;
+    const clips = active?.clips?.();
+    return clips && clips.length > 1 ? clips : null;
+  }
+
+  setActiveClip(id: string): void {
+    this.assertEditorDrives();
+    this.active?.setClip?.(id);
+    // The new clip's duration is a new range, and the playhead clamps into it.
+    const range = this.active?.range();
+    if (range) this.clock.setRange({ start: range.start, end: range.end });
+    this.applyTime(this.clock.time);
+    this.notify();
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  private notify(): void {
+    this.cachedSnapshot = null;
+    for (const listener of [...this.listeners]) listener();
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    this.stopStoreWatch();
+    this.cancelSettle();
+    this.clock.stop();
+    this.subjects.length = 0;
+    this.activeId = null;
+    this.listeners.clear();
+    this.settleListeners.clear();
+  }
+}
+
+/**
+ * WHICH TRANSPORT A STAGE RUNS ON — deliberately the same shape as
+ * `stage-store-registry.ts`, for the same objects and the same reason: a
+ * panel or contribution holding only a document id must be able to reach the
+ * stage's transport without the stage handing it down through props.
+ */
+const transports = new Map<string, StageTransport>();
+const registryListeners = new Set<() => void>();
+
+function notifyRegistry(): void {
+  for (const listener of [...registryListeners]) listener();
+}
+
+/** A mounted stage declares its transport. Re-registering the same document
+ *  replaces it; the returned unregister drops it. */
+export function registerStageTransport(documentId: string, transport: StageTransport): () => void {
+  transports.set(documentId, transport);
+  notifyRegistry();
+  return () => {
+    if (transports.get(documentId) !== transport) return;
+    transports.delete(documentId);
+    notifyRegistry();
+  };
+}
+
+/** That document's transport, or `null` for a document with no stage of its
+ *  own (a tool tab, a text document). */
+export function stageTransport(documentId: string | null): StageTransport | null {
+  return documentId === null ? null : (transports.get(documentId) ?? null);
+}
+
+/** `useSyncExternalStore` shape — a stage mounting or unmounting changes what
+ *  `stageTransport()` answers. */
+export function subscribeStageTransports(listener: () => void): () => void {
+  registryListeners.add(listener);
+  return () => {
+    registryListeners.delete(listener);
+  };
+}