@volter/editor-core 0.5.57

package/src/stage-context.ts

@@ -0,0 +1,341 @@
+/**
+ * WHAT A STAGE IS SHOWING — the ONE derived answer every stage capability asks.
+ *
+ * ARCHITECTURE-CORE §One stage: there is one 3D stage host, and a capability is
+ * present on a stage wherever its CONDITION holds — never by the origin or kind
+ * of the document that happens to have opened it. Before this, four gates spelled
+ * that question four ways in three places (`threeSurfaceToolsApply` for the shelf
+ * rail, `showThreejsTools` in the scene panel, `studioStage`/`hasShell` in the
+ * document host), which is why a prefab's stage and the world root's stage could
+ * not be the same code.
+ *
+ * It is a FUNCTION over the stores the panels already subscribe to, not a store
+ * of its own — the method transcribed from `inspection/active-surface.ts`, whose
+ * docblock states the rule: the surface is derived, never held. Callers keep
+ * their existing `useSyncExternalStore` subscriptions (shell store, active
+ * authoring, the session registry); this module only reads.
+ */
+
+import { stageTransformDoor } from '@volter/editor-sdk/contributions';
+import { getActiveAuthoring } from './authoring/active-adapter';
+import { CompositeAuthoringAdapter } from './authoring/composite-authoring-adapter';
+import { object3DDocumentSession } from './authoring/object3d-document-session-registry';
+import {
+  isViewportToolContextVisible,
+  resolveViewportToolContext,
+} from './authoring/viewport-tool-context';
+import { isThreejsSurfaceVisible } from './authoring/world-hidden-viewport';
+import type { EditorShellStore } from './editor-shell-store';
+import { stageStore } from './stage-store-registry';
+import { activeWorkspaceDocumentId, openWorkspaceDocuments } from './workspace-document-registry';
+
+export type StageSurface = 'three' | 'canvas' | 'dom';
+
+/** What the stage's document IS — the document's own `presentation()` kind
+ *  (`WorkspaceDocumentDescriptor.presentation`), folded to the subjects a
+ *  stage distinguishes. `unknown` when the descriptor declares none. */
+export type StageSubject =
+  | { readonly kind: 'composition' } // presentation 'scene' | 'world' (a scene, a manifest root)
+  | { readonly kind: 'story' } // 'story' — a piece in isolation with its parameters
+  | { readonly kind: 'artifact' } // 'asset' — an ecosystem artifact (glTF, particles, a model)
+  | { readonly kind: 'data' } // 'document' — an adapter-table document (a model, a page)
+  | { readonly kind: 'unknown' };
+
+export interface StageSelection {
+  readonly count: number;
+  /** The surface that owns the whole selection; null when empty or mixed. */
+  readonly surface: StageSurface | null;
+  /** Whether that owner is painted on this stage (hidden roots are not). */
+  readonly visible: boolean;
+}
+
+/**
+ * Whether the stage has chrome of its own, or is EMBEDDED in another surface
+ * with none (the inspector's object preview). It is a genuine condition OF THE
+ * STAGE — the same kind of fact as `surface`, `selection` and `play` — never
+ * the origin or kind of a document; and the HOST is the only thing that knows
+ * it, because an embedded preview has no workspace document at all (which is
+ * exactly why `subjectOf` answers `unknown` for one). So the host supplies it
+ * and nothing is inferred (decided 2026-09-18, an application of
+ * ARCHITECTURE-CORE §One stage's own rule).
+ */
+export type StageChrome = 'document' | 'embedded';
+
+export interface StageContext {
+  readonly documentId: string | null;
+  readonly chrome: StageChrome;
+  readonly subject: StageSubject;
+  /** The surface the stage paints; null when nothing is showing. */
+  readonly surface: StageSurface | null;
+  readonly selection: StageSelection;
+  readonly play: 'stopped' | 'playing' | 'paused';
+}
+
+const EMPTY_SELECTION: StageSelection = { count: 0, surface: null, visible: false };
+
+function stageSurfaceOf(kind: string | undefined): StageSurface | null {
+  return kind === 'three' || kind === 'canvas' || kind === 'dom' ? kind : null;
+}
+
+function subjectFromKind(kind: string | undefined): StageSubject {
+  switch (kind) {
+    case 'scene':
+    case 'world':
+      return { kind: 'composition' };
+    case 'story':
+      return { kind: 'story' };
+    case 'asset':
+      return { kind: 'artifact' };
+    case 'document':
+      return { kind: 'data' };
+    default:
+      return { kind: 'unknown' };
+  }
+}
+
+function subjectOf(documentId: string | null): StageSubject {
+  if (documentId === null) return { kind: 'unknown' };
+  const open = openWorkspaceDocuments().find((doc) => doc.descriptor.id === documentId);
+  if (!open) return { kind: 'unknown' };
+  const presentation = open.descriptor.presentation?.() ?? null;
+  const projected = subjectFromKind(presentation?.kind);
+  if (projected.kind !== 'unknown') return projected;
+  // The document's own declared KIND is the fallback, and it is a real answer
+  // rather than a guess: `presentation()` is the ADDRESSABLE projection of a
+  // document, and a document can legitimately have none while still being an
+  // artifact — `asset-documents.tsx:258` returns null for an ONLINE asset and
+  // for one with no project path, and reading only the projection took the
+  // studio stage off exactly those (measured 2026-09-18, which is why the
+  // `documentKind` prop could not simply be deleted without this).
+  return subjectFromKind(open.descriptor.kind);
+}
+
+/**
+ * Whether this adapter PAINTS a three surface at all, selection or not — the
+ * no-selection branch of what `threeSurfaceToolsApply` asked before this module
+ * existed, transcribed verbatim. A composite paints three when some child does;
+ * a single adapter paints three when it is not rect-capable and can hand back an
+ * `Object3D` for a node.
+ */
+function adapterPaintsThree(adapter: ReturnType<typeof getActiveAuthoring>): boolean {
+  if (adapter instanceof CompositeAuthoringAdapter)
+    return adapter.childAdapters().some((child) => child.kind === 'three');
+  return !adapter.rects && typeof adapter.hierarchy.object3D === 'function';
+}
+
+function worldStageContext(
+  store: EditorShellStore,
+  documentId: string | null,
+  subject: StageSubject,
+  chrome: StageChrome,
+): StageContext {
+  const adapter = getActiveAuthoring(store);
+  const surface: StageSurface | null =
+    isThreejsSurfaceVisible(store) && adapterPaintsThree(adapter) ? 'three' : null;
+  const play = store.playState;
+  const count = store.selectedEntityIds.size;
+  if (count === 0)
+    return { documentId, chrome, subject, surface, selection: EMPTY_SELECTION, play };
+  const context = resolveViewportToolContext(adapter, store.selectedEntityIds);
+  return {
+    documentId,
+    chrome,
+    subject,
+    surface,
+    selection: {
+      count,
+      surface: stageSurfaceOf(context?.kind),
+      visible: isViewportToolContextVisible(store, context),
+    },
+    play,
+  };
+}
+
+/**
+ * The stage a given document is showing.
+ *
+ * Two shapes answer this, and which one applies is a FACT about the document —
+ * not a kind it declares: a DOCUMENT stage has registered an
+ * `Object3DDocumentSession` (a model, a prefab story, an isolation scene) and
+ * its selection is its session's own; everything else is the WORLD stage — the
+ * manifest's roots under the shell store, whose selection is the shell's and
+ * whose surface is subject to the world-hidden eye.
+ */
+export function documentStageContext(
+  store: EditorShellStore,
+  documentId: string,
+  chrome: StageChrome = 'document',
+): StageContext {
+  const subject = subjectOf(documentId);
+  const session = object3DDocumentSession(documentId);
+  if (session === null) return worldStageContext(store, documentId, subject, chrome);
+  // A document stage's own selection: the session reads it straight off its
+  // authoring adapter, and its stage is the only thing painting it, so an owner
+  // it reports is by construction three-owned and visible here.
+  const count = session.selection().length;
+  return {
+    documentId,
+    chrome,
+    subject,
+    surface: 'three',
+    selection: { count, surface: count > 0 ? 'three' : null, visible: true },
+    play: store.playState,
+  };
+}
+
+/** The stage the FOCUSED document is showing; the world stage when no document
+ *  is active (the shell with nothing focused still paints the world root). */
+export function focusedStageContext(store: EditorShellStore): StageContext {
+  const documentId = activeWorkspaceDocumentId();
+  if (documentId !== null) return documentStageContext(store, documentId);
+  return worldStageContext(store, null, { kind: 'unknown' }, 'document');
+}
+
+/**
+ * THE STORE THE FOCUSED STAGE RUNS ON — where a shared panel reads per-stage
+ * state (selection, scene/objectMap, camera pose, orbit target, tool state,
+ * view options like `showStats`/shading).
+ *
+ * `shell` is the answer for a focused document with no stage of its own — a
+ * tool tab, a text document, the Game tab. That is not a fallback in name
+ * only: the world root's stage runs on the session store (see
+ * `StageHost.tsx`'s world-root install), so a panel asked while focus sits
+ * off every stage keeps reporting the world, exactly as it did before §One
+ * stage unit 4.
+ *
+ * It is a FUNCTION, like the rest of this module: the caller keeps its own
+ * subscriptions, and a panel that reads this subscribes to
+ * `subscribeStageStores` and `subscribeWorkspaceDocuments` so a mount or a
+ * tab switch re-renders it against the new answer.
+ */
+export function focusedStageStore(shell: EditorShellStore): EditorShellStore {
+  return stageStore(activeWorkspaceDocumentId()) ?? shell;
+}
+
+/** The host transform strip on a stage's shelf (Blender's persistent rail),
+ *  where the editor viewport's own gizmo is what it drives. This is the
+ *  `gizmo` arm of {@link stageTransformDriver} and nothing else asks it. */
+export function transformToolsApply(ctx: StageContext): boolean {
+  if (ctx.surface !== 'three') return false;
+  if (ctx.selection.count === 0) return true;
+  return ctx.selection.surface === 'three' && ctx.selection.visible;
+}
+
+/**
+ * WHAT THE HOST'S TRANSFORM TOOLS DRIVE ON THIS STAGE — one answer the shelf's
+ * strip and the header's transform wells both ask.
+ *
+ * `gizmo`  `EditorViewport`'s `TransformControls`, through the stage's own
+ *          `EditorShellStore.transformMode` (`stage-store-registry.ts` — NOT
+ *          the shell's; see `ToolStrip`'s note for the measurement that
+ *          separates them). The header's four wells configure that same gizmo,
+ *          so they are drawn with it.
+ * `modal`  the stage transforms MODALLY instead and declared how
+ *          (`registerStageTransform`): a mesh module's `G`/`R`/`S`. The three
+ *          single-channel tools arm it; the all-handles tool and the header
+ *          wells are NOT DRAWN, because a modal transform is no gizmo and has
+ *          nothing for a well to configure.
+ * `none`   not a three stage, or the selection belongs to another surface —
+ *          `transformToolsApply`'s own condition, unchanged.
+ *
+ * A DOCUMENT STAGE IS NOT AUTOMATICALLY THE MODAL CASE, and assuming it was is
+ * the error this docblock replaces: measured 2026-09-19 on a prefab story, a
+ * session-painted stage DOES draw the host's gizmo on its selection. Only a
+ * stage that declares a door takes the modal arm.
+ */
+export type StageTransformDriver = 'gizmo' | 'modal' | 'none';
+
+export function stageTransformDriver(ctx: StageContext): StageTransformDriver {
+  if (!transformToolsApply(ctx)) return 'none';
+  return stageTransformDoor(ctx.documentId) === null ? 'gizmo' : 'modal';
+}
+
+/** The three tools that need a selection (ViewportOverlay, CameraInfo). */
+export function threeSelectionToolsApply(ctx: StageContext): boolean {
+  return (
+    ctx.surface === 'three' &&
+    ctx.selection.count > 0 &&
+    ctx.selection.surface === 'three' &&
+    ctx.selection.visible
+  );
+}
+
+/**
+ * THE ARTIFACT-FLAVOURED SUBJECT — a piece shown IN ISOLATION that is not the
+ * project's own live composition: an artifact (a glTF, a particle system, a
+ * model asset), a story (a prefab mounted with its parameters), or a stage
+ * EMBEDDED in another surface with no workspace document at all (the
+ * inspector's object preview, which is why nothing can infer this one and the
+ * host supplies `chrome`).
+ *
+ * This is the question `documentKind: 'source' | 'asset'` asked as a PROP the
+ * caller chose, and it is the base the two conditions below are written
+ * against, so they cannot drift apart: it drives the source adapter's
+ * `documentKind` (its "derived asset" provenance line and its `model-asset`
+ * hierarchy kind) and the `asset` performance-source kind.
+ *
+ * DATA is deliberately not here. A mesh module is the project's own CODE — it
+ * opens in an isolation scene (§A model is data) but nothing about it is a
+ * derived asset, and saying so is what the `documentKind` prop did by
+ * accident once the studio grew a data arm.
+ */
+export function assetSubjectApplies(ctx: StageContext): boolean {
+  return (
+    ctx.chrome === 'embedded' || ctx.subject.kind === 'story' || ctx.subject.kind === 'artifact'
+  );
+}
+
+/**
+ * THE STUDIO PRESENTATION — the alpha clear and the editor's own backdrop
+ * behind a piece in isolation.
+ *
+ * ARCHITECTURE-CORE §A model is data: "opening data opens an ISOLATION SCENE
+ * around it … whose story is the STUDIO". So the studio is every
+ * artifact-flavoured subject PLUS data — a mesh module, a page, anything the
+ * adapter's table calls a document.
+ *
+ * The one condition on the data arm is the LOOK, and it is a condition rather
+ * than a kind: the studio's backdrop is the EDITOR'S (the alpha canvas over the
+ * `.vgai-object3d-studio-stage` bloom), and a look that declares its own
+ * `color.viewport` group has already said what the 3D viewport is painted —
+ * Blender's flat #3f3f3f — so painting the studio over it would be the editor
+ * overruling the skew.
+ *
+ * `lookPaintsViewport` is that group's presence, and it is a PARAMETER rather
+ * than a read inside here for two reasons: this module is derived-never-held
+ * and the look is not one of the stores its callers already subscribe to (the
+ * host subscribes to the theme root itself, `StageHost.tsx`); and importing
+ * the renderer's token reader here put `native-selection-style.ts` into
+ * `main.tsx`'s pinned closure for a layout predicate, which is the erosion the
+ * closure gate exists to stop (measured 2026-09-18: +1 file on `main.tsx` and
+ * on both builds). `native-selection-style.ts`'s `lookDeclaresViewportColors`
+ * is the one reader of that token, so the stage and the renderer cannot
+ * disagree about what is on screen.
+ */
+export function studioStageApplies(ctx: StageContext, lookPaintsViewport: boolean): boolean {
+  if (assetSubjectApplies(ctx)) return true;
+  return ctx.subject.kind === 'data' && !lookPaintsViewport;
+}
+
+/**
+ * THE IDENTITY-ROW FRAME — the Asset Lab shell around the stage: the row that
+ * names the thing, its type and its path, and the one registrar of the
+ * document's own workspace selection (the host registers it wherever this
+ * shell is absent, and exactly one of the two must).
+ *
+ * ARCHITECTURE-CORE §One stage: "the identity row when the subject is an
+ * ARTIFACT rather than source". It was the studio presentation's own answer
+ * until the studio gained a data arm, and it must not follow it there: a mesh
+ * module is the project's CODE, so an Asset-Lab row naming it a type and a
+ * file path, wrapped around the mesh editor's own header, would say the
+ * opposite of what the document is.
+ *
+ * An EMBEDDED stage never takes it — it has no chrome of its own by
+ * definition. Whether a STORY should keep it is the ruling's own open reading
+ * (a prefab's truth is source too); no frame of a story document has been
+ * read against that sentence, so this stays exactly what
+ * `assetSubjectApplies` says and nothing is re-decided blind.
+ */
+export function identityRowApplies(ctx: StageContext): boolean {
+  return ctx.chrome === 'document' && assetSubjectApplies(ctx);
+}

package/src/stage-store-registry.ts

@@ -0,0 +1,63 @@
+/**
+ * WHICH STORE A STAGE RUNS ON — the live identities behind
+ * `focusedStageStore()` (`stage-context.ts`).
+ *
+ * ARCHITECTURE-CORE §One stage: no stage is on "the" store by birthright.
+ * Every mounted stage owns an `EditorShellStore` holding its own per-stage
+ * state — selection, scene/objectMap, camera pose, orbit target, tool state
+ * and view options — and the shared panels read whichever one the FOCUSED
+ * document's stage runs on. Before this, only one stage's store was reachable
+ * (the shell's), so a control mounted over a model or a prefab drove a
+ * different stage's state: the grid button toggled the world's grid, and the
+ * camera readout reported a camera nobody was looking through.
+ *
+ * A registry of live identities, deliberately shaped like
+ * `authoring/object3d-document-session-registry.ts` — the same job for the
+ * same objects, and the reason it is not merged into that module is that a
+ * stage has a store BEFORE it has a session (the world root's stage has no
+ * `Object3DDocumentSession` at all, measured 2026-09-18). A leaf module with
+ * no imports beyond the store's type, so any lane may read it without an
+ * import cycle.
+ */
+import type { EditorShellStore } from './editor-shell-store';
+
+const stores = new Map<string, { store: EditorShellStore }>();
+let registryVersion = 0;
+const listeners = new Set<() => void>();
+
+function notify(): void {
+  registryVersion++;
+  for (const listener of [...listeners]) listener();
+}
+
+/** A mounted stage declares the store it runs on. Re-registering the same
+ *  document replaces it; the returned unregister drops it. */
+export function registerStageStore(documentId: string, store: EditorShellStore): () => void {
+  const registration = { store };
+  stores.set(documentId, registration);
+  notify();
+  return () => {
+    if (stores.get(documentId) !== registration) return;
+    stores.delete(documentId);
+    notify();
+  };
+}
+
+/** The store that document's stage runs on, or `null` for a document with no
+ *  stage of its own (a tool tab, a text document, the Game tab). */
+export function stageStore(documentId: string | null): EditorShellStore | null {
+  return documentId === null ? null : (stores.get(documentId)?.store ?? null);
+}
+
+/** `useSyncExternalStore` shape — a stage mounting or unmounting changes what
+ *  `focusedStageStore()` answers, so a panel that reads it subscribes here. */
+export function subscribeStageStores(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function stageStoresVersion(): number {
+  return registryVersion;
+}

package/src/stale-chunk-recovery.ts

@@ -0,0 +1,34 @@
+/**
+ * A LAZY CHUNK THAT NO LONGER EXISTS RELOADS THE PAGE ONCE.
+ *
+ * The hosted editor is deployed as hashed chunks and a promotion replaces
+ * every one of them: a tab that loaded the previous build keeps working until
+ * it lazily imports a chunk it has not touched yet — the first Play of a
+ * session, an Inspector preview — and gets a 404 for a hash the host no
+ * longer serves. Vite surfaces that as `vite:preloadError` on `window`, and
+ * the editor showed it as a crash whose Retry could never succeed ("Failed to
+ * fetch dynamically imported module … InspectorObjectPreview-…js", runhuman
+ * pass 146, a session that straddled a promotion). One ordinary reload picks
+ * up the current build; the guard keeps a genuinely broken host from looping.
+ */
+const RELOAD_GUARD_KEY = 'vgai:stale-chunk-reload';
+
+export function installStaleChunkRecovery(): void {
+  if (typeof window === 'undefined') return;
+  window.addEventListener('vite:preloadError', (event) => {
+    let last = 0;
+    try {
+      last = Number(sessionStorage.getItem(RELOAD_GUARD_KEY) ?? 0);
+    } catch {
+      // storage unavailable — reload once regardless
+    }
+    if (Date.now() - last < 60_000) return; // already reloaded for this; let the crash surface show
+    try {
+      sessionStorage.setItem(RELOAD_GUARD_KEY, String(Date.now()));
+    } catch {
+      // storage unavailable
+    }
+    event.preventDefault();
+    window.location.reload();
+  });
+}

package/src/state-report-deferral.ts

@@ -0,0 +1,73 @@
+/**
+ * Keeping the editor's status snapshot off the interaction critical path.
+ *
+ * `collectState` (command-listener.ts) is not a read — it RE-DERIVES the whole
+ * status surface. Two families dominate, and both scale with the size of the
+ * project rather than with the size of the change:
+ *
+ *   - the hierarchy walk behind `entities`/`entityCount`, and
+ *   - the capability GRADING facets (`rootCoverage`, `systemCoverage`,
+ *     `projectCoverage`, `authoringCoverage`, `ontologyInvariants`), each
+ *     documented as re-derived on read; `rootCoverage`'s conformance probe
+ *     walks the hierarchy AGAIN, once per mounted root, allocating a receipt
+ *     object and a formatted sentence per node.
+ *
+ * Measured 2026-08-19 through the session journal on `examples/first-person`
+ * in play mode, 251 hierarchy nodes:
+ *
+ *     collectState total 76ms  =  rootCoverage 30ms
+ *                              +  2 x hierarchy walk 23ms
+ *     JSON.stringify of the 41KB result: 0.0ms.  Sending it: 0.1ms.
+ *
+ * So none of the cost is serialization or transport; all of it is derivation,
+ * and it is superlinear in node count (56 nodes: 1.5ms per walk; 251 nodes:
+ * 23ms). On a game-heavy project the same function measured 1.2-1.3s of
+ * main-thread block.
+ *
+ * That would be survivable if it ran rarely. It does not: `reportLatestState`
+ * is wired to the store's own change notification, to restart-required, to the
+ * ingest capture wait, to the adapter load, to every command completion, and
+ * to focus/blur/visibilitychange. So the whole derivation ran on every
+ * selection click and several times over during a mount — which is why the
+ * defect reads as "the editor is slow to touch" while an idle tab is fine.
+ *
+ * The fix is not to derive less truth, it is to derive it OFF the critical
+ * path: an interaction reports immediately with the cheap fields fresh and the
+ * derived families reused from the last full snapshot, and schedules ONE
+ * deferred full collect that makes them current again. `vgai status` readers
+ * are never handed a snapshot older than that deferral, and the snapshot
+ * already carries its own age.
+ */
+
+/**
+ * How long the deferred full collect may wait for an idle moment before the
+ * browser runs it anyway. Short enough that "current shortly after the change"
+ * stays true for a `vgai status` reader; long enough that the interaction that
+ * triggered it paints first, which is the entire point.
+ */
+export const DEFERRED_FULL_REPORT_TIMEOUT_MS = 500;
+
+interface IdleCallbackHost {
+  requestIdleCallback?: (callback: () => void, options?: { timeout?: number }) => number;
+  cancelIdleCallback?: (handle: number) => void;
+}
+
+/**
+ * Run `report` off the critical path — at the next idle moment, or when
+ * {@link DEFERRED_FULL_REPORT_TIMEOUT_MS} expires, whichever comes first.
+ * Returns the canceller the caller's teardown must run.
+ *
+ * Falls back to a task (`setTimeout`) where `requestIdleCallback` is missing
+ * (Safari before 17, and jsdom): still off the triggering handler's own frame,
+ * which is what makes the interaction cheap.
+ */
+export function scheduleDeferredFullReport(report: () => void): () => void {
+  const host = globalThis as IdleCallbackHost;
+  const idle = host.requestIdleCallback;
+  if (typeof idle === 'function') {
+    const handle = idle.call(globalThis, report, { timeout: DEFERRED_FULL_REPORT_TIMEOUT_MS });
+    return () => host.cancelIdleCallback?.call(globalThis, handle);
+  }
+  const handle = setTimeout(report, 0);
+  return () => clearTimeout(handle);
+}

package/src/storage/host-files-storage.ts

@@ -0,0 +1,97 @@
+/**
+ * `StorageBackend`, answered by the WORKBENCH'S OWN FILE SERVICE (U5).
+ *
+ * ARCHITECTURE-CORE §The core is Code-OSS: *"the storage backends → file
+ * system providers, the dev server as one provider"*. What that turned out to
+ * mean, measured: both product shapes already have a real file service over
+ * the project folder (desktop's disk provider, the REH's `vscode-remote://`),
+ * so there is nothing to PROVIDE — the door CALLS what exists
+ * (`files/project-files.ts` states the decision and the reason).
+ *
+ * This class is how the existing `StorageBackend` callers — forty-odd of
+ * them, from the asset browser to the provenance ledger — reach that file
+ * service without one of them changing. It is a DECORATOR, not a fourth
+ * backend: it overrides exactly the three operations where "is this the
+ * workbench's own write?" is a question that has an answer (`read`,
+ * `readBytes`, `write`) and delegates everything else to the tier's real
+ * backend. `remove`, `mkdir`, `stat`, `list` and `watch` are the session's
+ * still, because the file door deliberately carries no remove/mkdir — a
+ * member nobody reads is cut, and nothing in the frame needs them yet.
+ *
+ * THE ROOT DIFFERENCE IS THE WHOLE JOB. `StorageBackend`'s paths on the server
+ * tier are rooted at `<project>/public/` (`http-storage.ts`'s header) while
+ * the file door's are PROJECT-RELATIVE, because that is the spelling the frame
+ * can resolve against its workspace folder. This class is the `public/` view:
+ * one prefix, in one place, instead of forty callers learning a second
+ * spelling.
+ */
+
+import { projectFiles } from '../files/project-files';
+import type { DirEntry, Stat, StorageBackend, WatchCallback } from './types';
+
+export class HostFilesStorage implements StorageBackend {
+  readonly id: string;
+
+  /**
+   * @param inner the tier's own backend, which still owns every operation the
+   *   file door does not carry — and which is also the FALLBACK while the
+   *   frame has taken ownership but not yet installed its provider (the mount
+   *   window `files/file-provider.ts` describes).
+   * @param root the project-relative prefix these paths live under. Always
+   *   `public` today; named rather than hardcoded so the prefix is visible at
+   *   the call site that chose it.
+   */
+  constructor(
+    private readonly inner: StorageBackend,
+    private readonly root = 'public',
+  ) {
+    this.id = `frame:${inner.id}`;
+  }
+
+  private resolve(path: string): string {
+    const key = path.replace(/\\/g, '/').replace(/^\/+/, '');
+    return key ? `${this.root}/${key}` : this.root;
+  }
+
+  read(path: string): Promise<string> {
+    return projectFiles.read(this.resolve(path));
+  }
+
+  readBytes(path: string): Promise<Uint8Array> {
+    return projectFiles.readBytes(this.resolve(path));
+  }
+
+  write(path: string, data: string | Uint8Array): Promise<void> {
+    return projectFiles.write(this.resolve(path), data);
+  }
+
+  async writeIfAbsent(path: string, data: string | Uint8Array): Promise<boolean> {
+    if (await this.exists(path)) return false;
+    await this.write(path, data);
+    return true;
+  }
+
+  list(dir: string): Promise<DirEntry[]> {
+    return this.inner.list(dir);
+  }
+
+  stat(path: string): Promise<Stat | null> {
+    return this.inner.stat(path);
+  }
+
+  exists(path: string): Promise<boolean> {
+    return projectFiles.exists(this.resolve(path));
+  }
+
+  mkdir(path: string): Promise<void> {
+    return this.inner.mkdir(path);
+  }
+
+  remove(path: string): Promise<void> {
+    return this.inner.remove(path);
+  }
+
+  watch(callback: WatchCallback): () => void {
+    return this.inner.watch(callback);
+  }
+}