@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/authoring/instance-source-menu.ts

@@ -0,0 +1,135 @@
+/**
+ * H3 wiring — the instance row's two source actions, registered through the
+ * hierarchy contribution seam.
+ *
+ * This is the "adapter-module registration" half of the split
+ * `hierarchy-menu-registry.ts` describes: `GameHierarchy` stays contract-only
+ * and never learns that an R3F world has a callsite; THIS module is the one
+ * allowed to resolve the owning child adapter and probe it for source
+ * accessors. The sentences and the applicability rule are pure and live in
+ * `../instance-source-actions.ts`.
+ *
+ * ISOLATE IS DELIBERATELY ABSENT — see {@link enterInstanceRow}. The design
+ * record's "double-click = Isolate, reusing the catalog nodes' existing Isolate
+ * mount" is not reachable from a scene instance row, and faking it was
+ * explicitly out of scope.
+ */
+
+import type { AuthoringAdapter } from '@volter/project/adapter';
+import type { ShellStore } from '@volter/sdk/kit/shell-store';
+import { registerHierarchyMenuItems } from '@volter/sdk/kit/hierarchy-menu-registry';
+import {
+  INSTANCE_SOURCE_LABELS,
+  type InstanceSourceLocator,
+  type InstanceSourceTarget,
+  instanceSourceTargets,
+  runInstanceSourceAction,
+} from '@volter/sdk/kit/instance-source-actions';
+import { showTransientHint } from '@volter/sdk/kit/transient-hint';
+import { getActiveAuthoring } from '@volter/sdk/kit/authoring/active-adapter';
+import { CompositeAuthoringAdapter } from '@volter/sdk/kit/authoring/composite-authoring-adapter';
+import { enterSelectionScope } from '@volter/sdk/kit/authoring/selection-scope';
+
+/**
+ * The adapter whose source accessors answer for `nodeId`. Ownership is asked
+ * of the composite (`ownerOf`/`childAdapters`, the same public T0 query
+ * `GameHierarchy`'s own gates use) rather than decoded from the id — a
+ * composite's routers would otherwise answer for a row their owning child
+ * knows nothing about.
+ */
+export function instanceSourceLocatorFor(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): InstanceSourceLocator | null {
+  const owner =
+    adapter instanceof CompositeAuthoringAdapter
+      ? (adapter.childAdapters().find((c) => c.worldId === adapter.ownerOf(nodeId))?.adapter ??
+        adapter)
+      : adapter;
+  const locator = owner as unknown as InstanceSourceLocator;
+  return typeof locator.sourceLocation === 'function' ||
+    typeof locator.definitionLocation === 'function'
+    ? locator
+    : null;
+}
+
+/** Run one target and SAY what happened — every path returns a sentence
+ *  (copied / not in the index / clipboard refused), so no click is silent. */
+function runAndReport(
+  locator: InstanceSourceLocator | null,
+  nodeId: string,
+  target: InstanceSourceTarget,
+): void {
+  void runInstanceSourceAction(locator, nodeId, target).then(showTransientHint);
+}
+
+/**
+ * Double-click on an instance row.
+ *
+ * An instance row is already the native authoring subject; portable CSF
+ * selects complete design-time states and does not provide a second subtree
+ * isolation protocol. Double-click therefore ENTERS the instance's scope and
+ * falls back to its callsite when the row cannot be entered.
+ *
+ * That fallback is the COMMON case, not the corner one: `projectedChildren`
+ * collapses everything an instance rendered itself (same `authoringInstance`),
+ * so an instance row has children only when it contains a NESTED instance.
+ * Every other instance row is a hierarchy leaf, `enterSelectionScope` refuses
+ * it for having no children, and until now that double-click did nothing at
+ * all — the silent no-op this whole decision exists to kill.
+ *
+ * Rename is NOT in conflict: `Row`'s `onDoubleClick` already routes every
+ * `component`/`instance`/`boundary` row here BEFORE its rename branch, so an
+ * instance row has never started a rename on double-click; rename stays
+ * reachable on the context menu, where it is always offered for a non-group row.
+ */
+export function enterInstanceRow(adapter: AuthoringAdapter, nodeId: string): void {
+  if (enterSelectionScope(adapter, nodeId)) return;
+  runCallsite(adapter, nodeId);
+}
+
+function runCallsite(adapter: AuthoringAdapter, nodeId: string): void {
+  const node = adapter.hierarchy.node(nodeId);
+  const locator = instanceSourceLocatorFor(adapter, nodeId);
+  // Only a row that ADVERTISES a callsite falls through to the source action —
+  // a boundary/placeholder row with nothing to open keeps double-clicking to
+  // nothing, exactly as before, rather than raising a hint the user did not ask
+  // for by picking a source verb.
+  if (!instanceSourceTargets(node, locator, nodeId).includes('callsite')) return;
+  runAndReport(locator, nodeId, 'callsite');
+}
+
+let unregister: (() => void) | null = null;
+
+/** Idempotent install of the two H3 items (see the register module). */
+export function ensureInstanceSourceMenuRegistered(): void {
+  if (unregister) return;
+  unregister = registerHierarchyMenuItems(
+    ({ nodeId, store }) => targetsFor(store, nodeId).length > 0,
+    ({ nodeId, store }) => {
+      const adapter = getActiveAuthoring(store);
+      const locator = instanceSourceLocatorFor(adapter, nodeId);
+      return targetsFor(store, nodeId).map((target) => ({
+        label: INSTANCE_SOURCE_LABELS[target],
+        action: () => {
+          runAndReport(locator, nodeId, target);
+        },
+      }));
+    },
+  );
+}
+
+function targetsFor(store: ShellStore, nodeId: string): InstanceSourceTarget[] {
+  const adapter = getActiveAuthoring(store);
+  return instanceSourceTargets(
+    adapter.hierarchy.node(nodeId),
+    instanceSourceLocatorFor(adapter, nodeId),
+    nodeId,
+  );
+}
+
+/** Test-only: drop the registration so a suite can reset the shared registry. */
+export function __unregisterInstanceSourceMenuForTest(): void {
+  unregister?.();
+  unregister = null;
+}

package/src/kit/authoring/layered-pick.ts

@@ -0,0 +1,185 @@
+/**
+ * Layered viewport picking (B4, D12) — "click anything you can see; topmost
+ * visible layer wins." Shell POLICY over the composite's public seams, kept a
+ * separate module (rather than living inline in `editor-viewport.ts`) so it
+ * stays lean AND unit-testable with plain fake adapters — no real DOM/canvas
+ * needed.
+ *
+ * This module speaks ONLY the public contract: `CompositeAuthoringAdapter
+ * .childAdapters()` (T0), the `AuthoringAdapter.pickable` provider (D12,
+ * `@volter/project/adapter`), and `world-session-state.ts`'s session toggles. It never
+ * reaches into any one child adapter's own private, format-specific model (no
+ * concrete-world-shape vocabulary of any kind here) — `instanceof
+ * CompositeAuthoringAdapter` is the ONE sanctioned type check (that class's
+ * own doc comment blesses exactly this use, mirroring
+ * `authoring/first-party-inspector/is-first-party-selection.ts`'s identical
+ * precedent).
+ *
+ * Walk order: the composite's NON-threejs children (react/pixi design-time
+ * layers), topmost-first by (install-time) manifest zOrder — `stackOrder`
+ * sorts bottom-to-top, so `.reverse()` gives topmost-first while preserving
+ * its own tie-break rule. The Three world is appended LAST
+ * (canvas-bottom) regardless of its manifest zOrder — it always renders
+ * beneath every positioned design-time layer (`design-time-layers.ts`'s own
+ * doc comment: "the three canvas keeps its existing slot"), so it is
+ * correct for it to lose every pick to a layer that also claims the point.
+ *
+ * A layer that is eye-hidden or pick-locked (`world-session-state.ts`, B1) is
+ * skipped ENTIRELY — its `pickable.pick` is never even called. This is a
+ * SEPARATE mechanism from a layer's `interactive` toggle: an interactive
+ * layer's DOM has `pointer-events: auto`, so a real pointer event lands on the
+ * layer's own element and this walk (triggered only by the CANVAS's own
+ * `pointerup` listener) never runs at all for that event — mutually exclusive
+ * by construction, no code needed here for it.
+ *
+ * When the active adapter is NOT a composite (single-world project, or a
+ * non-composite override), this degrades to that one adapter's own
+ * `pickable.pick` (or `null` if it doesn't have one) — today's single-world
+ * behavior, unchanged.
+ */
+
+import type { AuthoringAdapter } from '@volter/project/adapter';
+import { stackOrder } from '@volter/project/adapter/root-stacking';
+import type { ShellStore } from '@volter/sdk/kit/shell-store';
+import { SCENE_DOCUMENT_ID } from '@volter/sdk/kit/workspace-document-ids';
+import { activeWorkspaceDocumentId } from '@volter/sdk/kit/workspace-document-registry';
+import { getActiveAuthoring } from './active-adapter';
+import { CompositeAuthoringAdapter } from '@volter/sdk/kit/authoring/composite-authoring-adapter';
+import { currentSelectionScopeId } from '@volter/sdk/kit/authoring/selection-scope';
+import { isRootHidden, isRootPickLocked } from '@volter/sdk/kit/authoring/world-session-state';
+
+export function resolveAdapterPick(
+  adapter: AuthoringAdapter,
+  clientX: number,
+  clientY: number,
+  intent: 'normal' | 'deep',
+): string | null {
+  const raw = adapter.pickable?.pick(clientX, clientY) ?? null;
+  if (!raw) return null;
+  return (
+    adapter.selection?.resolve?.(raw, {
+      intent,
+      scopeId: currentSelectionScopeId(),
+    })?.id ?? raw
+  );
+}
+
+function resolveAdapterCandidates(
+  adapter: AuthoringAdapter,
+  clientX: number,
+  clientY: number,
+  intent: 'normal' | 'deep',
+  includeLocked = false,
+): string[] {
+  const raw = adapter.pickable?.candidates?.(clientX, clientY, includeLocked ? { includeLocked } : undefined) ?? [];
+  const resolved: string[] = [];
+  const seen = new Set<string>();
+  for (const id of raw) {
+    const candidate =
+      adapter.selection?.resolve?.(id, {
+        intent,
+        scopeId: currentSelectionScopeId(),
+      })?.id ?? id;
+    if (!seen.has(candidate)) {
+      seen.add(candidate);
+      resolved.push(candidate);
+    }
+  }
+  return resolved;
+}
+
+/** Topmost-first pick across every visible, pick-unlocked layer of the active
+ *  (possibly composite) authoring adapter. Returns the winning node id, or
+ *  `null` when nothing under `(clientX, clientY)` claims the point. */
+export function pickTopmost(
+  store: ShellStore,
+  clientX: number,
+  clientY: number,
+  options: { intent?: 'normal' | 'deep' } = {},
+): string | null {
+  const intent = options.intent ?? 'normal';
+  const active = getActiveAuthoring(store);
+  if (!(active instanceof CompositeAuthoringAdapter)) {
+    return resolveAdapterPick(active, clientX, clientY, intent);
+  }
+
+  const children = active.childAdapters();
+  // The Game document stays mounted warm while Scene is active. Its DOM rects
+  // therefore still exist even though it is not painted. Document ownership,
+  // not mount lifetime, decides which layers may claim the pointer.
+  const sceneDocumentActive = activeWorkspaceDocumentId() === SCENE_DOCUMENT_ID;
+  const layered = sceneDocumentActive ? [] : children.filter((c) => c.kind !== 'three');
+  const three = children.filter((c) => c.kind === 'three');
+
+  // `stackOrder` wants `{id, zOrder}` (`ClaimEntry`) — reuse `worldId` as its
+  // `id` (this walk has no separate id vocabulary of its own).
+  const layeredClaims = layered.map((c) => ({
+    id: c.worldId,
+    zOrder: c.zOrder,
+    worldId: c.worldId,
+    adapter: c.adapter,
+  }));
+
+  // Topmost-first: `stackOrder` is bottom-to-top (ascending zOrder, ties by
+  // original array order) — `.reverse()` flips it without disturbing its own
+  // tie-break rule (a later-declared same-zOrder layer still wins the tie,
+  // now by being checked FIRST instead of sorting last).
+  const order: Array<{ worldId: string; adapter: AuthoringAdapter }> = [
+    ...stackOrder(layeredClaims).reverse(),
+    // The Three world paints/picks LAST — canvas-bottom, regardless
+    // of its own manifest zOrder (see module doc comment).
+    ...three,
+  ];
+
+  for (const { worldId, adapter } of order) {
+    if (isRootHidden(worldId) || isRootPickLocked(worldId)) continue;
+    const hit = resolveAdapterPick(adapter, clientX, clientY, intent);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/** Ordered overlap stack across the same visible layers as {@link pickTopmost}. */
+export function pickCandidates(
+  store: ShellStore,
+  clientX: number,
+  clientY: number,
+  options: { intent?: 'normal' | 'deep'; adapter?: AuthoringAdapter; includeLocked?: boolean } = {},
+): string[] {
+  const intent = options.intent ?? 'normal';
+  const includeLocked = options.includeLocked === true;
+  const active = options.adapter ?? getActiveAuthoring(store);
+  if (!(active instanceof CompositeAuthoringAdapter)) {
+    const candidates = resolveAdapterCandidates(active, clientX, clientY, intent, includeLocked);
+    const fallback = resolveAdapterPick(active, clientX, clientY, intent);
+    return candidates.length > 0 ? candidates : fallback ? [fallback] : [];
+  }
+
+  const children = active.childAdapters();
+  const sceneDocumentActive = activeWorkspaceDocumentId() === SCENE_DOCUMENT_ID;
+  const layered = sceneDocumentActive ? [] : children.filter((child) => child.kind !== 'three');
+  const three = children.filter((child) => child.kind === 'three');
+  const layeredClaims = layered.map((child) => ({
+    id: child.worldId,
+    zOrder: child.zOrder,
+    worldId: child.worldId,
+    adapter: child.adapter,
+  }));
+  const order: Array<{ worldId: string; adapter: AuthoringAdapter }> = [
+    ...stackOrder(layeredClaims).reverse(),
+    ...three,
+  ];
+  const result: string[] = [];
+  const seen = new Set<string>();
+  for (const { worldId, adapter } of order) {
+    if (isRootHidden(worldId) || isRootPickLocked(worldId)) continue;
+    const candidates = resolveAdapterCandidates(adapter, clientX, clientY, intent, includeLocked);
+    const fallback = resolveAdapterPick(adapter, clientX, clientY, intent);
+    for (const id of candidates.length > 0 ? candidates : fallback ? [fallback] : []) {
+      if (seen.has(id)) continue;
+      seen.add(id);
+      result.push(id);
+    }
+  }
+  return result;
+}

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

@@ -0,0 +1,146 @@
+/**
+ * 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/project/adapter';
+import type { AdapterSurface } from '@volter/project/adapter/adapter-surface';
+import { liveSurface } from '@volter/sdk/kit/live-session-registry';
+import { projectAdapterFacet } from '../project-adapter';
+import {
+  activeWorkspaceDocument,
+  activeWorkspaceDocumentSelection,
+} from '@volter/sdk/kit/workspace-document-registry';
+import { getAuthoringOverride } from '@volter/sdk/kit/authoring/active-adapter';
+import { CompositeAuthoringAdapter } from '@volter/sdk/kit/authoring/composite-authoring-adapter';
+import { emptyProjectAuthoring } from '@volter/sdk/kit/authoring/empty-project-authoring';
+
+/** 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)];
+  }
+  // A project that declares no roots wears a placeholder that says so; nothing is mounted.
+  if (isBoundaryDisclosure(active) || active === emptyProjectAuthoring()) 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/kit/authoring/no-authoring-adapter.ts

@@ -0,0 +1,59 @@
+/**
+ * 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/project/adapter';
+import type { ShellDocumentState } from '@volter/sdk/kit/shell-document-state';
+
+/** 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: ShellDocumentState,
+  label: string,
+  secondaryLabel = 'No authoring surface',
+): AuthoringAdapter {
+  const node: EditorNode = {
+    id: NO_AUTHORING_ID,
+    label,
+    secondaryLabel,
+    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/kit/authoring/object3d-document-persistence.ts

@@ -0,0 +1,122 @@
+/**
+ * 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 { HistoryService } from '@volter/sdk/kit/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 '@volter/sdk/kit/write-pipe';
+
+/** One project-owned artifact participating in an Asset Lab commit. The document is whatever the
+ *  medium hands its serializers (Three's is `ToolObject3DDocumentState`). */
+export interface DocumentPersistenceResource<TDocument> {
+  /** Project-root-relative destination. */
+  readonly path: string;
+  /** MIME type recorded in canonical history. */
+  readonly contentType?: string;
+  /** `null` removes the file in the same atomic transaction. */
+  readonly serialize: (
+    document: TDocument,
+  ) => string | Uint8Array | null | Promise<string | Uint8Array | null>;
+}
+
+export interface DocumentPersistenceBinding<TDocument> {
+  /** Default undo/redo label. A completed gesture may supply a narrower one. */
+  readonly label?: string;
+  /** Non-empty, path-unique set of files owned by this document. */
+  readonly resources: readonly DocumentPersistenceResource<TDocument>[];
+}
+
+export interface OpenObject3DDocumentPersistenceOptions<TDocument = unknown> {
+  readonly binding: DocumentPersistenceBinding<TDocument>;
+  readonly document: TDocument;
+  readonly history: HistoryService;
+  readonly backend?: HistoryFileBackend;
+}
+
+async function serializeObject3DDocument<TDocument>(
+  binding: DocumentPersistenceBinding<TDocument>,
+  document: TDocument,
+): 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<TDocument = unknown> {
+  /** 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: TDocument, 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<TDocument>(binding: DocumentPersistenceBinding<TDocument>): 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<TDocument>(
+  options: OpenObject3DDocumentPersistenceOptions<TDocument>,
+): Promise<Object3DDocumentPersistenceSession<TDocument>> {
+  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,
+      }),
+  };
+}