@volter/editor-core 0.5.57

package/src/session-tombstone.ts

@@ -0,0 +1,126 @@
+/**
+ * THE PAGE'S OWN DEATH CERTIFICATE — one latch, read by everything that would
+ * otherwise let a dead page keep impersonating a live editor.
+ *
+ * A vgai editor page is a client-side SPA. When its session ends — gracefully
+ * (`vgai close` pushes `tab-close`) or ungracefully (the process was killed, or
+ * a DIFFERENT server took the port) — the page keeps running: it keeps its
+ * control channel's reconnect loop, keeps POSTing state snapshots, and keeps
+ * executing relayed commands. Measured during a live debugging session: pages
+ * from earlier crashed/replaced sessions ("corpse pages") kept answering
+ * probes, so an attach or a `vgai status` read could land on a page whose
+ * server was gone or replaced, and nothing on that page said so.
+ *
+ * Both halves of the detection ALREADY existed and neither was wired to
+ * anything but a notice:
+ *  - graceful: `tab-lifecycle-client.ts` handles the server's `tab-close` push;
+ *  - ungraceful: `EditorLeaseGuard`/`editor-lease.ts` void the supervised lease
+ *    (`server-gone` / `taken-over`).
+ * This module is the ONE state both write to, and the one thing the command
+ * listener reads before it runs anything.
+ *
+ * ## Why a latch and not a per-caller check
+ *
+ * The bijection (`server/tab-lifecycle.ts`) is the server's account of which
+ * tab is real, and it is the mechanism the owner invariant names. A corpse page
+ * must therefore not merely stay quiet — it must LEAVE that account. So
+ * `markSessionEnded` is what the command listener subscribes to in order to
+ * report its listener DETACHED (`POST /__editor/command-listener`, the same
+ * fact `server/server-utils.ts`'s `commandListenerHealth` already prints per
+ * tab as `not attached`). The server's own tab table then names the page as
+ * unresponsive instead of blessing it — integrating with the bijection rather
+ * than growing a second notion of tab liveness beside it.
+ *
+ * ## Why it can be cleared
+ *
+ * Not every void is final. `editor-lease.ts`'s `decideLeaseRecovery` has a
+ * `resume` branch: the SAME process answers again, so it was never gone and the
+ * page is not stale. That branch calls {@link clearSessionEnded}. The two
+ * TERMINAL reasons (`taken-over`, and the server's own `tab-close`) never
+ * clear — a tab that yielded to a live window must never come back to fight it.
+ */
+
+/** Why this page's session is over, in the vocabulary its detector already
+ *  uses (`editor-lease.ts`'s `LeaseVoidReason`, plus the graceful push). */
+export type SessionEndReason = 'server-gone' | 'taken-over' | 'session-closed';
+
+export interface SessionEndedState {
+  readonly reason: SessionEndReason;
+  /** When this page decided it. Every refusal quotes the age, because "this
+   *  page is dead" without a time is the same unfalsifiable present-tense claim
+   *  the status age-stamp exists to kill. */
+  readonly at: number;
+}
+
+let ended: SessionEndedState | null = null;
+const listeners = new Set<(state: SessionEndedState | null) => void>();
+
+function publish(): void {
+  for (const listener of [...listeners]) listener(ended);
+}
+
+/** The state, or `null` while this page still believes it is live. */
+export function sessionEndedState(): SessionEndedState | null {
+  return ended;
+}
+
+/** Record the death. Idempotent per reason, and a TERMINAL reason is never
+ *  overwritten by a later recoverable one. */
+export function markSessionEnded(reason: SessionEndReason, at: number = Date.now()): void {
+  if (ended !== null && ended.reason !== 'server-gone') return;
+  if (ended !== null && ended.reason === reason) return;
+  ended = { reason, at };
+  publish();
+}
+
+/** The `resume` branch: the same process answered again, so nothing here is
+ *  stale. Only ever legitimate after a `server-gone` void. */
+export function clearSessionEnded(): void {
+  if (ended === null || ended.reason !== 'server-gone') return;
+  ended = null;
+  publish();
+}
+
+/** Subscribe to transitions. Returns an unsubscribe. */
+export function onSessionEndedChange(
+  listener: (state: SessionEndedState | null) => void,
+): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * The refusal a dead page answers control traffic with — a message that NAMES
+ * the state, its age, and the one thing that fixes it, so a caller never has to
+ * infer "corpse" from a plausible-looking answer.
+ *
+ * Pure over the state (no globals, no clock of its own) so the wording is
+ * testable without a browser.
+ */
+export function sessionEndedRefusal(
+  state: SessionEndedState,
+  commandType: string,
+  now: number = Date.now(),
+): string {
+  const age = `${Math.max(0, Math.round((now - state.at) / 1000))}s ago`;
+  const what =
+    state.reason === 'taken-over'
+      ? `a DIFFERENT editor session took this port ${age}; this page yielded to it`
+      : state.reason === 'session-closed'
+        ? `this page's editor session was closed ${age}`
+        : `this page's editor server stopped ${age}`;
+  return (
+    `refused "${commandType}": this editor page is a TOMBSTONE — ${what}. ` +
+    'Nothing it reports is live state and nothing it does is saved. ' +
+    'Run `volter-editor edit <project>` to open the session again; that reuses the live ' +
+    'server and its one tab.'
+  );
+}
+
+/** Test seam: forget everything this page decided. */
+export function resetSessionTombstone(): void {
+  ended = null;
+  listeners.clear();
+}

package/src/settings/settings-provider.ts

@@ -0,0 +1,82 @@
+/**
+ * WHERE THE SETTINGS ARE: `IConfigurationService`, through a provider the
+ * contribution installs here.
+ *
+ * Every setting is one dotted `vgai.*` name per LEAF of the settings document,
+ * and the prefix is part of the key everywhere — in `EditorHost.settings`, in
+ * `.vscode/settings.json`, in the Settings editor and in what a probe prints.
+ * The table is DERIVED, never written: `@volter/editor-project/settings/keys` walks the
+ * JSON Schema Zod itself produces, which is the same derivation
+ * `npm run generate-schema` commits.
+ *
+ * The ADAPTER layer — the one thing that service does not already have — is
+ * its own MEMORY target, which the platform merges ABOVE user; what puts the
+ * PROJECT back above the adapter is an INSPECT GATE, re-evaluated on every
+ * configuration change. See docs/CODE-OSS.md §The settings, under the frame.
+ *
+ * IT ARRIVES AFTER THE MOUNT, for the same reason the file provider does, and
+ * a reader falls back to the store's own layers until it lands — which is why
+ * a preference gesture made too early cannot write a `.vgai/settings.json` the
+ * workbench knows nothing about.
+ *
+ * A provider's own change stream is subscribed HERE rather than by each
+ * reader, so `subscribeSettingsProvider` is the one notification every consumer
+ * of the store already listens to.
+ */
+import type {
+  EditorHostSettingsInspection,
+  EditorHostSettingsProvider,
+} from '@volter/editor-sdk/host';
+
+export type SettingsProvider = EditorHostSettingsProvider;
+export type SettingsInspection = EditorHostSettingsInspection;
+
+let provider: SettingsProvider | null = null;
+const listeners = new Set<() => void>();
+let stopProvider: (() => void) | null = null;
+
+/**
+ * Is the provider installed? False until it lands — later than the mount,
+ * because a `ServicesAccessor` is valid only for a command's synchronous part,
+ * so the contribution hands the provider over after the editor is running. In
+ * that window a reader falls back to the store's own layers, which is why a
+ * preference gesture made too early does not write a settings file the
+ * workbench knows nothing about.
+ */
+export function settingsProviderInstalled(): boolean {
+  return provider !== null;
+}
+
+/** The installed provider, or `null` before it lands. */
+export function settingsProvider(): SettingsProvider | null {
+  return provider;
+}
+
+/**
+ * Install the configuration service the settings read and write through, or
+ * `null` to withdraw it — the service is the workbench's, and a workbench that
+ * went away takes it with it.
+ *
+ * A provider's own change stream is subscribed HERE rather than by each
+ * reader, so `subscribeSettingsProvider` is the one notification every consumer
+ * of the store already listens to — an adapter value clearing because a
+ * project value appeared reaches the palette the same way a settings file
+ * reload does.
+ */
+export function setSettingsProvider(next: SettingsProvider | null): void {
+  if (provider === next) return;
+  stopProvider?.();
+  stopProvider = null;
+  provider = next;
+  if (provider) stopProvider = provider.subscribe(() => announce());
+  announce();
+}
+
+function announce(): void {
+  for (const listener of listeners) listener();
+}
+
+export function subscribeSettingsProvider(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}

package/src/settings-store.ts

@@ -0,0 +1,345 @@
+/**
+ * THE SETTINGS STORE — the shared layers, loaded once and read
+ * synchronously everywhere (ARCHITECTURE-CORE §Editor chrome, "Settings have
+ * four layers with named homes"):
+ *
+ *   user     ~/.vgai/settings.json            every project, this person
+ *   adapter  <project>/vgai.adapter.ts        this project's own CODE
+ *   project  <project>/.vgai/settings.json    this project, everyone (committed)
+ *
+ * `effectiveSettings()` is project over adapter over user, key by key.
+ *
+ * THE ADAPTER LAYER is the project's look and bindings as the adapter
+ * DECLARES them — `editor: { style: blenderStyle, keymap: blenderKeymap }`,
+ * imported objects, not a file the host parses (ARCHITECTURE-CORE §Adapters
+ * and contributions are code, not configs). It sits above the USER layer
+ * because it is a fact about THIS project and the user layer is one person's
+ * cross-project default: a skew's Blender greys must not be undone by the
+ * graphite a game project left in `~/.vgai/settings.json`. It sits below the
+ * PROJECT layer because that file is this project's own explicit override, so
+ * an appearance gesture still lands somewhere that wins. Appearance and
+ * keymap choices write WHERE THE KEY IS DECLARED (`updatePreferenceSettings`):
+ * the user layer, or the project layer when the project's own file carries
+ * that key (a models scaffold declares its look, the way a repo's
+ * `.vscode/settings.json` does) — so the gesture edits the file that wins;
+ * the device preview frame is a project fact and writes the PROJECT layer. The other two layers — the project-LOCAL document
+ * (`project-local-state.ts`, git-ignored) and the built-in defaults every
+ * consumer carries — never pass through here.
+ *
+ * Boot awaits `preloadSettings()` before the first paint (`main.tsx`,
+ * before React mounts), so a consumer's first synchronous read already sees
+ * the person's palette; the project layer reloads whenever the active
+ * project changes. A file that does not parse is reported to the editor
+ * console by path — an unresolved condition, so `vgai console` carries it —
+ * and that layer reads as empty until it is fixed.
+ *
+ * ## UNDER THE CODE-OSS FRAME THIS MODULE IS THE FALLBACK, not the truth
+ *
+ * ARCHITECTURE-CORE §The core is Code-OSS, U7: the frame's
+ * `IConfigurationService` is the settings, and the same three layers are its
+ * USER target, its MEMORY target (the adapter's declaration, gated by
+ * `inspect` on the workspace value) and `.vscode/settings.json`. When
+ * `settings/settings-provider.ts` reports a frame provider, every one of the
+ * four layer views below is composed FROM IT, per key, through
+ * `@volter/editor-project/settings/keys`'s table — so nothing that reads this module
+ * changes shape, and `theme-preference.ts`, `workspace-regions.ts`,
+ * `keymap-presets.ts` and `device-preview.ts` go on reading a nested
+ * `EditorSettings` document exactly as they always did. The file layers are
+ * still loaded, because they are what answers in the window before the
+ * provider arrives and in every standalone session.
+ */
+
+import type { EditorHostSettingsInspection, EditorHostSettingsTarget } from '@volter/editor-sdk/host';
+import { flattenSettings, settingsFromEntries, settingsKeys } from '@volter/editor-project/settings/keys';
+import { type EditorSettings, mergeEditorSettings } from '@volter/editor-project/settings/schema';
+import { activeProjectKey, getCurrentProject, onProjectChange } from './active-project';
+import {
+  adapterEditorConfiguration,
+  subscribeAdapterEditorConfiguration,
+} from './adapter-editor-config';
+import { loadSettingsLayer, type SettingsLayer, saveSettingsLayer } from './api/settings';
+import { editorConsole } from './editor-console';
+import { settingsProvider, subscribeSettingsProvider } from './settings/settings-provider';
+
+type Listener = () => void;
+
+let user: EditorSettings = {};
+let project: EditorSettings = {};
+let adapter: EditorSettings = {};
+let effective: EditorSettings = {};
+let userLoaded = false;
+let projectLoadedFor: string | null = null;
+let userLoading: Promise<void> | null = null;
+let projectLoading: Promise<void> | null = null;
+const listeners = new Set<Listener>();
+
+function projectKey(): string {
+  return activeProjectKey();
+}
+
+/**
+ * The adapter's declared look and bindings, in the settings document's shape.
+ * The style object carries the ids the registries resolve; the objects
+ * themselves are registered by the package's own contributions, so a project
+ * that declares the look without the package simply resolves to the editor's
+ * defaults.
+ *
+ * This is the DECLARATION, read straight off the adapter, and it is what the
+ * frame's bridge hands the configuration service to write into its MEMORY
+ * target — so the frame never has a second notion of what the adapter said.
+ */
+export function declaredAdapterSettings(): EditorSettings {
+  const editor = adapterEditorConfiguration();
+  const style = editor.style;
+  const layer: Record<string, unknown> = {};
+  if (style) {
+    const appearance: Record<string, unknown> = {
+      palette: style.paletteId,
+      material: style.materialId,
+    };
+    const icons = style.iconSetId ?? style.icons?.id;
+    if (icons !== undefined) appearance['icons'] = icons;
+    if (style.regions !== undefined) appearance['regions'] = style.regions;
+    layer['appearance'] = appearance;
+  }
+  if (editor.keymap) layer['keymap'] = editor.keymap.id;
+  return layer as EditorSettings;
+}
+
+/** The adapter layer AS IT IS IN FORCE — the declaration standalone, the
+ *  configuration service's MEMORY target under the frame (where a project
+ *  value for a key has already cleared it). Standalone it is read LIVE rather
+ *  than from the cache below, so a reader that runs before the first
+ *  `recompute()` sees the adapter's declaration and not an empty layer. */
+export function adapterSettings(): EditorSettings {
+  return settingsProvider() ? adapter : declaredAdapterSettings();
+}
+
+/** The adapter's declaration as dotted `vgai.*` keys — what the frame writes
+ *  to the MEMORY target. */
+export function declaredAdapterSettingEntries(): ReadonlyMap<string, unknown> {
+  return flattenSettings(declaredAdapterSettings());
+}
+
+function recompute(): void {
+  const provider = settingsProvider();
+  if (provider) {
+    // THE FRAME'S LAYERS, one key at a time. `inspect` is the only door that
+    // separates them — the effective value alone cannot say whether a gesture
+    // on this key will stick, and `keymap-presets.ts` and `device-preview.ts`
+    // both ask exactly that.
+    const users: [string, unknown][] = [];
+    const adapters: [string, unknown][] = [];
+    const projects: [string, unknown][] = [];
+    const effectives: [string, unknown][] = [];
+    for (const { key } of settingsKeys()) {
+      const layered = provider.inspect(key);
+      users.push([key, layered.user]);
+      adapters.push([key, layered.adapter]);
+      projects.push([key, layered.project]);
+      effectives.push([key, layered.effective]);
+    }
+    user = settingsFromEntries(users);
+    adapter = settingsFromEntries(adapters);
+    project = settingsFromEntries(projects);
+    effective = settingsFromEntries(effectives);
+  } else {
+    adapter = {};
+    effective = mergeEditorSettings(mergeEditorSettings(user, declaredAdapterSettings()), project);
+  }
+  for (const listener of listeners) listener();
+}
+
+function report(layer: SettingsLayer, path: string | null, issues: readonly string[]): void {
+  if (issues.length === 0) return;
+  editorConsole.warn(
+    `${layer} settings ${path ?? ''} did not parse and is ignored — ${issues.join('; ')}`,
+    'settings',
+  );
+}
+
+function loadUser(): Promise<void> {
+  if (userLoaded) return Promise.resolve();
+  userLoading ??= loadSettingsLayer('user')
+    .then((read) => {
+      user = read.settings;
+      report('user', read.path, read.issues);
+    })
+    .catch(() => {
+      user = {};
+    })
+    .finally(() => {
+      userLoaded = true;
+      userLoading = null;
+    });
+  return userLoading;
+}
+
+function loadProject(): Promise<void> {
+  const key = projectKey();
+  if (projectLoadedFor === key) return Promise.resolve();
+  // In flight for another project: this one loads after it, never joins it.
+  if (projectLoading) return projectLoading.then(() => loadProject());
+  if (!getCurrentProject()) {
+    project = {};
+    projectLoadedFor = key;
+    return Promise.resolve();
+  }
+  projectLoading = loadSettingsLayer('project')
+    .then((read) => {
+      project = read.settings;
+      report('project', read.path, read.issues);
+    })
+    .catch(() => {
+      project = {};
+    })
+    .finally(() => {
+      projectLoadedFor = key;
+      projectLoading = null;
+    });
+  return projectLoading;
+}
+
+/** Load both layers (memoized per layer; the project layer per project) and
+ *  publish. Idempotent — every boot seam may await it. */
+export function preloadSettings(): Promise<void> {
+  return Promise.all([loadUser(), loadProject()]).then(recompute);
+}
+
+/** Project over adapter over user. */
+export function effectiveSettings(): EditorSettings {
+  return effective;
+}
+
+export function userSettings(): EditorSettings {
+  return user;
+}
+
+export function projectSettings(): EditorSettings {
+  return project;
+}
+
+/** Every layer's own value for one `vgai.*` key, plus the effective one —
+ *  the door's `inspect`, answered from whichever side owns the settings. */
+export function inspectSetting(key: string): EditorHostSettingsInspection {
+  const provider = settingsProvider();
+  if (provider) return provider.inspect(key);
+  const read = (document: EditorSettings): unknown => flattenSettings(document).get(key);
+  return {
+    // The standalone layers are FILES; nothing under them carries a built-in
+    // value, so answering anything here would be a fabricated layer.
+    default: undefined,
+    user: read(user),
+    adapter: read(adapterSettings()),
+    project: read(project),
+    effective: read(effective),
+  };
+}
+
+/** The effective value of one `vgai.*` key. */
+export function getSetting(key: string): unknown {
+  const provider = settingsProvider();
+  return provider ? provider.get(key) : flattenSettings(effective).get(key);
+}
+
+/**
+ * Which layer a gesture on this key must land in for it to stick: the project
+ * when this project's ADAPTER or its own settings already declare the key,
+ * the user layer otherwise.
+ *
+ * One rule, one implementation, both shapes — writing `appearance` to the
+ * user layer in a project whose adapter declares a style is a gesture that
+ * silently does nothing, and that is as true of the configuration service's
+ * MEMORY target as it is of `.vgai/settings.json`.
+ */
+function targetFor(key: string): EditorHostSettingsTarget {
+  if (!getCurrentProject()) return 'user';
+  const layered = inspectSetting(key);
+  return layered.adapter !== undefined || layered.project !== undefined ? 'project' : 'user';
+}
+
+/**
+ * Write a set of `vgai.*` keys, grouped so each LAYER is written once.
+ *
+ * The grouping is not a micro-optimisation: standalone, a layer write is a
+ * whole-document POST, so a two-key patch sent as two writes is two POSTs of
+ * two different documents racing each other on the server's side — the same
+ * "one document, one writer" reasoning `project-local-state.ts`'s header
+ * gives for its sections.
+ */
+function applySettings(
+  entries: Iterable<readonly [string, unknown]>,
+  forced?: EditorHostSettingsTarget,
+): void {
+  const toUser: (readonly [string, unknown])[] = [];
+  const toProject: (readonly [string, unknown])[] = [];
+  for (const entry of entries) {
+    const target = forced ?? targetFor(entry[0]);
+    (target === 'project' ? toProject : toUser).push(entry);
+  }
+  const provider = settingsProvider();
+  if (provider) {
+    for (const [key, value] of toUser) provider.set(key, value, 'user');
+    for (const [key, value] of toProject) provider.set(key, value, 'project');
+    return;
+  }
+  if (toUser.length > 0) writeUserLayer(settingsFromEntries(toUser));
+  if (toProject.length > 0) writeProjectLayer(settingsFromEntries(toProject));
+}
+
+/** Write one `vgai.*` key. With no target, {@link targetFor} picks the layer
+ *  that wins. */
+export function setSetting(key: string, value: unknown, target?: EditorHostSettingsTarget): void {
+  applySettings([[key, value]], target);
+}
+
+/** Merge `patch` into the USER layer and write `~/.vgai/settings.json`. */
+function writeUserLayer(patch: EditorSettings): void {
+  user = mergeEditorSettings(user, patch);
+  recompute();
+  void saveSettingsLayer('user', user).catch((cause: unknown) => {
+    editorConsole.error(`Could not save user settings: ${(cause as Error).message}`, 'settings');
+  });
+}
+
+/**
+ * Merge a PREFERENCE patch where each key lands WHERE IT WINS — see
+ * {@link targetFor}. The patch is a nested document because that is the shape
+ * every caller already holds; it is flattened to keys here, which is the one
+ * place the two spellings meet.
+ */
+export function updatePreferenceSettings(patch: EditorSettings): void {
+  applySettings(flattenSettings(patch));
+}
+
+/** Merge `patch` into the PROJECT layer. */
+export function updateProjectSettings(patch: EditorSettings): void {
+  if (!getCurrentProject()) return;
+  applySettings(flattenSettings(patch), 'project');
+}
+
+function writeProjectLayer(patch: EditorSettings): void {
+  if (!getCurrentProject()) return;
+  project = mergeEditorSettings(project, patch);
+  recompute();
+  void saveSettingsLayer('project', project).catch((cause: unknown) => {
+    editorConsole.error(`Could not save project settings: ${(cause as Error).message}`, 'settings');
+  });
+}
+
+export function subscribeSettings(listener: Listener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+onProjectChange(() => {
+  void loadProject().then(recompute);
+});
+
+// The adapter layer changes when a project's adapter module loads or unloads.
+subscribeAdapterEditorConfiguration(recompute);
+
+// And under the frame, when the configuration service says any layer moved —
+// including the MEMORY value the frame clears the instant a project value for
+// that key appears, which is what puts the project back above the adapter.
+subscribeSettingsProvider(recompute);

package/src/shared-view-restore.ts

@@ -0,0 +1,42 @@
+/**
+ * A SHARED VIEW LINK, restored once the session's own restore has settled.
+ *
+ * `editorViewFromUrl` reads the view a share link carries; presenting it has
+ * to wait for the workspace's documents, or the presentation lands on a
+ * document that is about to be replaced. It lives beside the editor rather
+ * than inside a layout because there is exactly ONE layout host now
+ * (`frame/bridge.tsx`) and a hook a layout owns is a hook one layout can
+ * forget: this is the session's behaviour, called from the one workspace that
+ * exists.
+ */
+
+import { editorViewFromUrl } from '@volter/editor-sdk';
+import { useEffect } from 'react';
+import { activeProjectKey } from './active-project';
+import { editorConsole } from './editor-console';
+import type { EditorShellStore } from './editor-shell-store';
+import { presentEditorView } from './editor-view-presentation';
+import { waitForWorkspaceStateRestore } from './workspace-state-persistence';
+
+export function useSharedViewRestore(store: EditorShellStore): void {
+  useEffect(() => {
+    const view = editorViewFromUrl(window.location.href);
+    if (!view) return;
+    let disposed = false;
+    const project = activeProjectKey();
+    const current = () => !disposed && activeProjectKey() === project;
+    void waitForWorkspaceStateRestore()
+      .then(() => {
+        if (current()) return presentEditorView(store, view, { updateUrl: false, origin: 'link' });
+      })
+      .catch((error) => {
+        editorConsole.error(
+          `Could not restore shared editor view: ${error instanceof Error ? error.message : String(error)}`,
+          'editor',
+        );
+      });
+    return () => {
+      disposed = true;
+    };
+  }, [store]);
+}

package/src/shell-store-door.ts

@@ -0,0 +1,45 @@
+/**
+ * THE ONE SHELL STORE, as the lanes that run something reach it. The store is
+ * created once per project session (`EditorContext.tsx`); the door is
+ * installed at boot before any store exists, and Play, ingest and the module
+ * lane bind themselves to the store on its ARRIVAL rather than being bound by
+ * the workspace panel that happens to mount first (until 2026-09-17 both
+ * `the world root's stage` and `NonThreeAuthoringBootstrap` named Play and ingest to
+ * hand them the store). A leaf module with no imports, so a lane may subscribe
+ * at its own module load without an import cycle.
+ */
+import type { EditorShellStore } from './editor-shell-store';
+
+let shellStore: EditorShellStore | null = null;
+const arrivals = new Set<(store: EditorShellStore) => void>();
+const changeListeners = new Set<() => void>();
+
+/** `EditorContext.tsx` registers the store it created. */
+export function registerShellStoreForHost(store: EditorShellStore): void {
+  shellStore = store;
+  for (const listener of arrivals) listener(store);
+  for (const listener of changeListeners) listener();
+}
+
+/** The current store, or null before a project session opens. */
+export function shellStoreForHost(): EditorShellStore | null {
+  return shellStore;
+}
+
+/** Runs on every store arrival — at once, when one is already registered. */
+export function onShellStore(listener: (store: EditorShellStore) => void): () => void {
+  arrivals.add(listener);
+  if (shellStore) listener(shellStore);
+  return () => {
+    arrivals.delete(listener);
+  };
+}
+
+/** Fires when the store is (re)registered; the door's `session.subscribe`
+ *  composes this with the store's own subscription. */
+export function onShellStoreChange(listener: () => void): () => void {
+  changeListeners.add(listener);
+  return () => {
+    changeListeners.delete(listener);
+  };
+}