@volter/editor-core 0.5.57

package/src/authoring/mounted-root-subjects.ts

@@ -0,0 +1,144 @@
+/**
+ * WHICH ROOTS THE ACTIVE AUTHORING SURFACE PRESENTS LIVE — the host's own
+ * answer to "what is mounted, and through which adapter".
+ *
+ * It lived in `coverage/root-coverage.ts` because the per-root coverage report
+ * was its first reader, and it stayed there long after a second one appeared.
+ * It is not a grade: the vitals' `presented three roots` invariant ("a scene
+ * has one root", `coverage/ontology-invariants.ts`) asks it, the Hierarchy and
+ * the gizmo work over exactly these subjects, and a host with no game skew
+ * loaded still has every one of them. So it is the authoring seam's, beside
+ * `active-adapter.ts` whose override it reads — and the coverage report that
+ * grades these subjects can leave the host without taking the question with
+ * it.
+ */
+
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+import type { AdapterSurface } from '@volter/editor-project/adapter/adapter-surface';
+import { liveSurface } from '../live-session-registry';
+import { projectAdapterFacet } from '../project-adapter';
+import {
+  activeWorkspaceDocument,
+  activeWorkspaceDocumentSelection,
+} from '../workspace-document-registry';
+import { getAuthoringOverride } from './active-adapter';
+import { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+
+/** One mounted root, as this module needs to see it. Structural on purpose: the
+ *  composite hands these over, and a test can build one by hand. */
+export interface MountedRootSubject {
+  readonly worldId: string;
+  readonly surface: AdapterSurface | null;
+  readonly adapter: AuthoringAdapter;
+}
+
+const SURFACE_KINDS: readonly string[] = ['three', 'canvas', 'dom'];
+
+/**
+ * A root that DECLARES it has no live editing surface here — the disclosure
+ * adapter (`AuthoringProvenance.source === 'boundary'`) a manifest-declared
+ * world wears while its real mount is still assembling, or after that mount was
+ * suspended or failed.
+ *
+ * It is NOT a coverage subject. Grading a disclosure against the provider
+ * contract prints "this root exposes no <provider> provider" fourteen times
+ * about a surface that does not exist yet — a snapshot that is false the moment
+ * it is taken and, because the console sync forwards warnings to the server's
+ * unresolved ledger, then stands there forever beside the real post-mount
+ * report.
+ *
+ * MEASURED on a canvas ingest: opening the project installs the edit-mode
+ * composite with a Boundary child for the ingest root
+ * (`authoring/edit-mode-authoring.ts`), and the mount then spends SECONDS
+ * awaiting the Game document, the capture window — a budget of VISIBLE time,
+ * 8s by default, which PARKS while the tab is hidden
+ * (`ingest/capture-wait-report.ts`) — and the stage settle, before
+ * `setActiveAuthoring` swaps the live adapter in
+ * (`ingest/mount-canvas-ingest-root.ts`). The vitals sampler runs every 5s
+ * (`coverage/session-vitals.ts`), so an ordinary reload lands inside that
+ * window and files "16 of 30 seams are MISSING" against a session that reports
+ * zero editor gaps seconds later.
+ *
+ * The stand-down is principled rather than timed: no debounce, no delay, no
+ * game id. Provenance is the adapter's OWN statement of what its rows project
+ * (rule zero — the shell reads the field, it never infers truth from adapter
+ * identity), and "declared world with no live editing surface here" is the
+ * adapter saying the mount has not attached. Coverage over an unattached mount
+ * is not a measurement.
+ *
+ * A root that mounted and honestly publishes nothing is the OPPOSITE case and
+ * stays a subject: `authoring/no-authoring-adapter.ts` declares no provenance
+ * at all, because "this root has no authoring surface" is a real, standing
+ * capability gap that the report exists to keep loud.
+ */
+function isBoundaryDisclosure(adapter: AuthoringAdapter): boolean {
+  return adapter.provenance?.source === 'boundary';
+}
+
+/** The composite's `kind` string as a surface, or `null` when it is not one of
+ *  the three the host hands out — in which case NOTHING is excused (see
+ *  `CapabilityCoverageFacts.surface`). */
+function asSurface(kind: string): AdapterSurface | null {
+  return SURFACE_KINDS.includes(kind) ? (kind as AdapterSurface) : null;
+}
+
+/**
+ * Every root the active authoring surface presents LIVE, or `[]` when nothing is
+ * mounted.
+ *
+ * A composite lists its children; a bare adapter IS the one root. `role:
+ * 'surface'` children are skipped: they are adapter-owned content INSIDE a
+ * root (a nested board, a scene-UI seam), not roots the manifest declared, and
+ * grading them against the full contract would invent gaps for things that were
+ * never meant to be roots. {@link isBoundaryDisclosure} children are skipped for
+ * the sibling reason: they are worlds the editor has DISCLOSED, not mounted.
+ */
+export function mountedRootSubjects(): readonly MountedRootSubject[] {
+  // An isolation document is a real Edit mount owned by one declared region,
+  // even though it deliberately does not replace the composition-wide active
+  // adapter. Its workspace binding is the same adapter Hierarchy, Inspector,
+  // and writes use; its descriptor carries the owning root. Measure that pair
+  // first so coverage describes the surface the author is actually editing.
+  const documentSelection = activeWorkspaceDocumentSelection();
+  const documentRootId = activeWorkspaceDocument()?.descriptor.provenance?.rootId;
+  const documentRegion = documentRootId
+    ? projectAdapterFacet()?.regions.find((region) => region.id === documentRootId)
+    : undefined;
+  const documentSubject =
+    documentSelection?.adapter && documentRootId && documentRegion
+      ? {
+          worldId: documentRootId,
+          surface: documentRegion.surface,
+          adapter: documentSelection.adapter,
+        }
+      : null;
+  const active = getAuthoringOverride();
+  if (!active) return documentSubject ? [documentSubject] : [];
+  if (active instanceof CompositeAuthoringAdapter) {
+    const subjects = active
+      .childAdapters()
+      .filter((child) => child.role === 'world' && !isBoundaryDisclosure(child.adapter))
+      .map((child) => ({
+        worldId: child.worldId,
+        surface: asSurface(child.kind),
+        adapter: child.adapter,
+      }));
+    if (!documentSubject) return subjects;
+    return [documentSubject, ...subjects.filter((subject) => subject.worldId !== documentRootId)];
+  }
+  if (isBoundaryDisclosure(active)) return documentSubject ? [documentSubject] : [];
+  // A bare (non-composite) active adapter still HAS a surface — a live ingest
+  // session states its render substrate outright, and `IngestKind` and
+  // `AdapterSurface` are the same three words by construction. Leaving this
+  // `null` reported the canvas N-A trio (assetSubject/text/colorSample) as
+  // gaps on every bare canvas mount, while the surface-aware ingest door
+  // called the same three rows `na` — two doors disagreeing about one mount.
+  // No live ingest ⇒ `null` stays, and nothing is excused (the deliberate
+  // cheap-direction-to-be-wrong).
+  const activeSubject = {
+    worldId: 'root',
+    surface: liveSurface(),
+    adapter: active,
+  };
+  return documentSubject ? [documentSubject, activeSubject] : [activeSubject];
+}

package/src/authoring/no-authoring-adapter.ts

@@ -0,0 +1,55 @@
+/**
+ * NoAuthoringAdapter — what the editor can honestly offer over a mounted root
+ * that exposes no authoring surface at all.
+ *
+ * A `{ module }` adapter is free to publish nothing authorable: it mounts, it
+ * draws, and the host has no tree to bind the hierarchy/inspector/gizmo to.
+ * Rather than hide that root, or fabricate a surface for it, this adapter
+ * advertises exactly what is true — one informational hierarchy node and all
+ * `capabilities` false — so the editor's generic panels render an honest
+ * nothing-to-author state instead of pretending to edit.
+ */
+
+import type {
+  AuthoringAdapter,
+  AuthoringCapabilities,
+  EditorNode,
+  HierarchyProvider,
+} from '@volter/editor-project/adapter';
+import type { EditorShellStore } from '../editor-shell-store';
+
+/** The one hierarchy row this adapter publishes. Exported because it is a
+ *  MESSAGE, not an entity: a surface that lists entities (the command palette)
+ *  has to be able to tell it apart from a thing a person can select. */
+export const NO_AUTHORING_ID = 'no-authoring:root';
+
+export function makeNoAuthoringAdapter(store: EditorShellStore, label: string): AuthoringAdapter {
+  const node: EditorNode = {
+    id: NO_AUTHORING_ID,
+    label,
+    secondaryLabel: 'No authoring surface',
+    role: 'boundary',
+    kind: 'object',
+    parentId: null,
+    childIds: [],
+  };
+  const hierarchy: HierarchyProvider = {
+    roots: () => [node],
+    node: (id) => (id === NO_AUTHORING_ID ? node : null),
+    // No `object3D`/`idForObject3D`: there is no reachable Object3D to offer.
+  };
+  const capabilities: AuthoringCapabilities = {
+    transform: false,
+    inspectorFields: false,
+    persist: false,
+  };
+  return {
+    capabilities,
+    hierarchy,
+    selection: {
+      get: () => [...store.selectedEntityIds],
+      set: (ids) => store.selectMultiple(ids),
+    },
+    subscribe: (listener) => store.subscribe(listener),
+  };
+}

package/src/authoring/null-inspection-subjects.tsx

@@ -0,0 +1,75 @@
+/**
+ * The shipped NO-SELECTION subjects (`inspection/null-subject.ts` is the
+ * seam; `main.tsx` imports this module for its import-time registration).
+ *
+ * With nothing selected, the inspector shows NOTHING (owner, 2026-08-07) —
+ * no box, no hint, no scene-global settings. A surface earns an empty-state
+ * subject only when its empty space IS a real thing: the one shipped case is
+ * an open Asset Lab document, where clicking empty space means "the
+ * document", and the box shows the document's own identity and sections.
+ * Every other surface's honest answer is `null`, which unmounts the box
+ * entirely (`inspection/null-subject.ts`'s no-provider contract).
+ *
+ * Scene-GLOBAL affordances do not ride the empty state: the navmesh
+ * bake/clear verbs live in the Debug menu (`components/ApplicationMenus.tsx`),
+ * dispatched through the same `navmesh-actions.ts` events as always.
+ */
+
+import { getActiveAssetEditorContext } from '../asset-editor-context';
+import { documentInspectionSubject } from '../inspection/document-subject';
+import { registerNullSubjectProvider } from '../inspection/null-subject';
+import { activeWorkspaceDocumentId } from '../workspace-document-registry';
+
+/**
+ * An open asset document's empty state: the DOCUMENT itself. Pick a part
+ * inside it and the ordinary selection path composes that part's subject
+ * through the document's own adapter; pick nothing and this is what the
+ * document says it is — its name, its kind, its provenance, and whatever
+ * sections it declared (`components/AssetEditorShell.tsx` publishes the
+ * description to `inspection/document-subject.ts`).
+ */
+registerNullSubjectProvider({
+  match: (ctx) => ctx.surface === 'asset-lab',
+  describe: () => {
+    const context = getActiveAssetEditorContext();
+    if (!context) return null;
+    const published = documentInspectionSubject();
+    // Only THIS document's subject. A stale publication from a document that
+    // has since been closed is not what the human is looking at — the honest
+    // fallback is the document's identity alone.
+    return published?.documentId === context.documentId
+      ? published.subject
+      : {
+          id: context.documentId,
+          title: context.title,
+          kindLabel: context.type,
+          sections: [],
+        };
+  },
+});
+
+/**
+ * ANY active document's own subject — the general case the Asset Lab provider
+ * above is the specialized one of.
+ *
+ * A document that stands behind no authoring adapter still has things to say
+ * about what you picked inside it, and `publishDocumentInspectionSubject` is
+ * where it says them. Until this existed the only READER was keyed on the
+ * `asset-lab` surface, so the 2D components board published a picked frame's
+ * identity into a holder nothing ever consulted and a human clicked frame
+ * after frame against an empty panel (runhuman pass 92). The match is
+ * document identity and nothing more, the same test
+ * `inspection/game-subject.ts` makes.
+ *
+ * Registered AFTER the Asset Lab provider so first-match-wins keeps that
+ * surface's fallback-to-document-identity behavior, which this deliberately
+ * does not have: a document that published nothing is describing no subject,
+ * and an empty inspector is the honest answer.
+ */
+registerNullSubjectProvider({
+  match: () => {
+    const published = documentInspectionSubject();
+    return published !== null && published.documentId === activeWorkspaceDocumentId();
+  },
+  describe: () => documentInspectionSubject()?.subject ?? null,
+});

package/src/authoring/object3d-document-persistence.ts

@@ -0,0 +1,106 @@
+/**
+ * Generic Asset Lab persistence. Project code serializes its own native
+ * document into ordinary files; this host-side bridge owns transaction
+ * ordering, checksum preflight, compensation, and canonical undo/redo.
+ */
+
+import type {
+  ToolObject3DDocumentPersistence,
+  ToolObject3DDocumentState,
+} from '@volter/editor-sdk/contributions';
+import type { HistoryService } from '../history/history-service';
+import {
+  getProjectFileHistory,
+  type HistoryFileBackend,
+  type ProjectFileMutation,
+  type ProjectFileMutationSession,
+} from '../history/project-file-history';
+import { getProjectResourceHistoryBackend } from '../history/project-root-history-backends';
+import { runWritePipe, type WriteAck, type WriteResolution } from './write-pipe';
+
+export interface OpenObject3DDocumentPersistenceOptions {
+  readonly binding: ToolObject3DDocumentPersistence;
+  readonly document: ToolObject3DDocumentState;
+  readonly history: HistoryService;
+  readonly backend?: HistoryFileBackend;
+}
+
+async function serializeObject3DDocument(
+  binding: ToolObject3DDocumentPersistence,
+  document: ToolObject3DDocumentState,
+): Promise<ProjectFileMutation[]> {
+  if (binding.resources.length === 0) {
+    throw new Error('An Object3D document persistence binding must own at least one resource.');
+  }
+  const changes: ProjectFileMutation[] = [];
+  for (const resource of binding.resources) {
+    changes.push({
+      path: resource.path,
+      data: await resource.serialize(document),
+      contentType: resource.contentType ?? 'application/octet-stream',
+    });
+  }
+  return changes;
+}
+
+export interface Object3DDocumentPersistenceSession {
+  /** Commit through the one persistence pipe, and answer for THIS commit.
+   *  `persisted: false` means the serializers produced the bytes already on
+   *  disk and nothing moved — a real outcome, not a failure (a failure throws). */
+  commit(document: ToolObject3DDocumentState, label?: string): Promise<WriteAck>;
+}
+
+/** Where an Asset Lab document's bytes go — the binding's own resource paths,
+ *  which is the finest-grained honest answer this lane has. */
+function destinationOf(binding: ToolObject3DDocumentPersistence): string {
+  return binding.resources.map((resource) => resource.path).join(' + ');
+}
+
+/**
+ * Establish the exact serialized bytes represented by a newly mounted native
+ * document. Every later commit is checked against that mount-time baseline,
+ * so a stale HMR module can never overwrite a newer sidecar on disk.
+ */
+export async function openObject3DDocumentPersistence(
+  options: OpenObject3DDocumentPersistenceOptions,
+): Promise<Object3DDocumentPersistenceSession> {
+  const { binding, document, history } = options;
+  const files = getProjectFileHistory(
+    history,
+    options.backend ?? getProjectResourceHistoryBackend(),
+    'asset-lab-document',
+  );
+  const session: ProjectFileMutationSession = await files.openMutationSession(
+    await serializeObject3DDocument(binding, document),
+  );
+  return {
+    // THE ONE PIPE, this lane's plug: resolve (a binding with resources is a
+    // real destination) → write (serialize + the file-mutation transaction) →
+    // record (that transaction IS the history entry, so nothing more).
+    commit: (nextDocument, requestedLabel) =>
+      runWritePipe({
+        resolve: (): WriteResolution => ({
+          reaches: 'writer',
+          // The document's own file is the anchor: no source literal addresses
+          // it, and project code serializes the record the editor edited.
+          anchorKind: 'data-record',
+          destination: destinationOf(binding),
+          write: async () => {
+            // Check the mount-time bytes BEFORE entering project code. HMR can
+            // invalidate a serializer's module-local state; a newer file must
+            // still receive the canonical content-conflict refusal, never that
+            // incidental serializer error and never an overwrite.
+            await session.assertUnchanged();
+            // Serialize before entering history: a failing project serializer
+            // writes nothing and cannot advance the open-document checksum
+            // baseline.
+            const changes = await serializeObject3DDocument(binding, nextDocument);
+            const label =
+              requestedLabel?.trim() || binding.label?.trim() || 'Edit Asset Lab Document';
+            return session.mutate(changes, { label });
+          },
+        }),
+        record: () => undefined,
+      }),
+  };
+}

package/src/authoring/object3d-document-session-registry.ts

@@ -0,0 +1,120 @@
+/**
+ * Lightweight registry for live Object3D document sessions.
+ *
+ * State/control readers only need to find a session that some document has
+ * already constructed. Keeping this map beside the implementation made every
+ * reader load the implementation's postprocessing, skeleton, outline and
+ * diagnostic-rendering graph during a plain Scene boot. The class remains the
+ * native session type; this module owns only its live identities.
+ */
+import type { Object3DDocumentSession } from './object3d-document-session';
+
+const sessions = new Map<string, Object3DDocumentSession>();
+const announcedStages = new Map<string, number>();
+const preparations = new Map<string, () => Promise<void>>();
+let registryVersion = 0;
+const registryListeners = new Set<() => void>();
+
+function notifyRegistry(): void {
+  registryVersion++;
+  for (const listener of registryListeners) listener();
+}
+
+export function registerObject3DDocumentSession(session: Object3DDocumentSession): () => void {
+  sessions.set(session.documentId, session);
+  notifyRegistry();
+  return () => {
+    if (sessions.get(session.documentId) !== session) return;
+    sessions.delete(session.documentId);
+    notifyRegistry();
+  };
+}
+
+export function object3DDocumentSession(documentId: string): Object3DDocumentSession | null {
+  return sessions.get(documentId) ?? null;
+}
+
+/** Async source-backed documents refresh their graph before a requested view
+ * is presented. The callback owns its build and failure semantics. */
+export function registerObject3DDocumentPreparation(
+  documentId: string,
+  prepare: () => Promise<void>,
+): () => void {
+  preparations.set(documentId, prepare);
+  return () => {
+    if (preparations.get(documentId) === prepare) preparations.delete(documentId);
+  };
+}
+
+export async function prepareObject3DDocument(documentId: string): Promise<void> {
+  await preparations.get(documentId)?.();
+}
+
+/**
+ * A DOCUMENT'S STAGE ANNOUNCES ITSELF AS IT RENDERS, before the session it
+ * will register exists — the fact an opener's `ready` needs and cannot get
+ * from anywhere else.
+ *
+ * MEASURED 2026-09-19 (phase 1 unit 16): whether a document mounts an Object3D
+ * session is a fact of its MOUNT, never of its address. Three `bird`/`humanoid`/
+ * `walking-castle` Builder documents open through the `tool` address and mount
+ * one (`catalog/project-source/src/contributions/builder-document.tsx:66`)
+ * while `data`, `asset-budget` and nine other `workspace.document`
+ * contributions at the same address do not; a `source` asset mounts one only
+ * when its module is a model builder (`asset-viewers/SourceAssetViewer.tsx:256`)
+ * and a `json` asset only when its content is a three.quarks system
+ * (`asset-viewers/JsonAssetDocument.tsx:64`). A host that waited by ADDRESS
+ * would hang the whole `DOCUMENT_REGISTRATION_TIMEOUT_MS` on every flat
+ * document at that address and then refuse a document that was never wrong —
+ * which is why the readiness rule the presenter held could not simply be
+ * copied kind-side. The announcement is made by the ONE host component every
+ * chromed stage goes through, so no lane is recognised by name.
+ *
+ * Announcing is idempotent and counted: several mounts for one document id
+ * (a revision swap keyed on `viewerKey`) overlap, and the last release is the
+ * one that clears it.
+ */
+export function announceObject3DDocumentStage(documentId: string): () => void {
+  announcedStages.set(documentId, (announcedStages.get(documentId) ?? 0) + 1);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const open = (announcedStages.get(documentId) ?? 0) - 1;
+    if (open > 0) announcedStages.set(documentId, open);
+    else announcedStages.delete(documentId);
+  };
+}
+
+/** Whether a stage for this document has begun mounting. The WAIT that reads
+ *  it is `document-context-registry.ts`'s, deliberately not here: this module
+ *  sits on `StageHost.tsx`'s own pinned closure, and a poll helper's import
+ *  edge grew that pin by one (measured). */
+export function object3DDocumentStageAnnounced(documentId: string): boolean {
+  return (announcedStages.get(documentId) ?? 0) > 0;
+}
+
+/** Every live CHROMED document session — the ones that own a toolbar, an
+ *  inspector context and a performance source. This is a presentation registry,
+ *  not the Edit-static one: whether a surface's CONTENT time is held is asked of
+ *  `coverage/design-time-surfaces.ts`, which every mount publishes into
+ *  (chromeless preview cards included). */
+export function allObject3DDocumentSessions(): readonly Object3DDocumentSession[] {
+  return [...sessions.values()];
+}
+
+export function subscribeObject3DDocumentSessions(listener: () => void): () => void {
+  registryListeners.add(listener);
+  return () => registryListeners.delete(listener);
+}
+
+export function object3DDocumentSessionsVersion(): number {
+  return registryVersion;
+}
+
+export function __resetObject3DDocumentSessionsForTest(): void {
+  sessions.clear();
+  preparations.clear();
+  announcedStages.clear();
+  notifyRegistry();
+}