@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/world-adoption.ts

@@ -0,0 +1,115 @@
+/**
+ * WORLD-ADOPTION AMBIGUITY — the reader for what the capture trap decided, and
+ * for every world it saw afterwards and did not adopt.
+ *
+ * `@volter/editor-threejs/adapter/ingest/scene-capture` adopts a self-booting game's world on
+ * the first non-host render. That is a sound MEASURED default and a permanent,
+ * silent commitment: a splash scene, a shadow pre-pass or a render-to-texture
+ * warm-up that happens to draw first is adopted as the game forever, and the
+ * real world drawing one frame later reached nobody.
+ *
+ * This module does not change the decision (ARCHITECTURE-CORE §The editor
+ * protocol: a diagnostic diagnoses; it does not silently re-pick). It records
+ * the adoption's PROVENANCE — `declared` when the game's contract named the
+ * scene, `measured` when first-render-wins ran — and every distinct
+ * (scene, camera) pair seen after it, and publishes both as the `worldAdoption`
+ * facet of `/__editor/state`.
+ *
+ * Alternates are INFORMATION, not an error: a post-processing chain renders
+ * several pairs per frame by design. The facet says how many and which, and the
+ * `ambiguity` sentence exists so a reader chasing "the editor is showing the
+ * wrong scene" has one place that already knows there was a choice.
+ */
+
+import type { WorldAdoptionEvent } from '@volter/sdk/kit/world-adoption-event';
+
+export interface WorldAdoptionAlternate {
+  readonly sceneId: string;
+  readonly cameraId: string;
+  /** `false` ⇒ a SECOND renderer is drawing — the stronger signal that the
+   *  adopted world may not be the one on screen. */
+  readonly sameRenderer: boolean;
+  readonly drawCount: number;
+}
+
+export interface WorldAdoption {
+  readonly rootId: string;
+  /** `declared` = the game's contract named this scene; `measured` = the trap's
+   *  first-non-host-render default decided. */
+  readonly source: 'declared' | 'measured';
+  readonly sceneId: string;
+  readonly cameraId: string;
+  /** Distinct worlds seen AFTER the adopted one, capped by the trap's own
+   *  `MAX_RECORDED_ALTERNATES`. */
+  readonly alternates: readonly WorldAdoptionAlternate[];
+  /** Present iff `alternates` is non-empty — the one sentence, spelled once. */
+  readonly ambiguity?: string;
+}
+
+/** RESOURCE OWNERSHIP: one entry per self-booting root, written through
+ *  {@link worldAdoptionRecorder} by the mount that installed the capture trap,
+ *  and dropped by that mount's teardown ({@link clearWorldAdoption}). */
+const _adoptions = new Map<
+  string,
+  {
+    source: 'declared' | 'measured';
+    sceneId: string;
+    cameraId: string;
+    alternates: WorldAdoptionAlternate[];
+  }
+>();
+
+/**
+ * The `onWorldAdoption` handler a mount hands to `installSceneCapture`, bound
+ * to one root id. One door: the mount passes this straight through, so nothing
+ * in the editor transcribes the engine's event shape a second time.
+ */
+export function worldAdoptionRecorder(rootId: string): (event: WorldAdoptionEvent) => void {
+  return (event) => {
+    if (event.phase === 'adopted') {
+      _adoptions.set(rootId, {
+        source: event.source,
+        sceneId: event.sceneId,
+        cameraId: event.cameraId,
+        alternates: [],
+      });
+      return;
+    }
+    // An alternate before an adoption cannot happen (the trap only reports one
+    // after it has committed), so a missing entry here means this root's
+    // adoption was already torn down — drop it rather than resurrect the root.
+    const entry = _adoptions.get(rootId);
+    if (!entry) return;
+    entry.alternates.push({
+      sceneId: event.sceneId,
+      cameraId: event.cameraId,
+      sameRenderer: event.sameRenderer,
+      drawCount: event.drawCount,
+    });
+  };
+}
+
+export function clearWorldAdoption(rootId: string): void {
+  _adoptions.delete(rootId);
+}
+
+export function worldAdoptionFacet(): readonly WorldAdoption[] {
+  return [..._adoptions].map(([rootId, entry]) => ({
+    rootId,
+    source: entry.source,
+    sceneId: entry.sceneId,
+    cameraId: entry.cameraId,
+    alternates: [...entry.alternates],
+    ...(entry.alternates.length > 0
+      ? {
+          ambiguity:
+            `"${rootId}" rendered ${entry.alternates.length} other world(s) after the one the ` +
+            `editor adopted (${entry.source}: ${entry.sceneId}). The adopted world is unchanged; ` +
+            'if the editor is showing the wrong scene, one of these is it: ' +
+            entry.alternates
+              .map((alt) => `${alt.sceneId}${alt.sameRenderer ? '' : ' (a SECOND renderer)'}`)
+              .join(', '),
+        }
+      : {}),
+  }));
+}

package/src/kit/world-canvas-viewport-state.ts

@@ -0,0 +1,35 @@
+/** Session-only responsive canvas size for DOM-backed authoring roots. */
+export interface RootCanvasViewport {
+  readonly width: number | null;
+  readonly height: number | null;
+}
+
+const FILL_VIEWPORT: RootCanvasViewport = { width: null, height: null };
+let viewport: RootCanvasViewport = FILL_VIEWPORT;
+const listeners = new Set<() => void>();
+
+export function getRootCanvasViewport(): RootCanvasViewport {
+  return viewport;
+}
+
+export function setRootCanvasViewport(width: number | null, height: number | null): void {
+  const nextWidth = width === null ? null : Math.max(1, Math.round(width));
+  const nextHeight = height === null ? null : Math.max(1, Math.round(height));
+  if (viewport.width === nextWidth && viewport.height === nextHeight) return;
+  viewport = { width: nextWidth, height: nextHeight };
+  for (const listener of listeners) listener();
+}
+
+export function resetRootCanvasViewport(): void {
+  setRootCanvasViewport(null, null);
+}
+
+export function subscribeRootCanvasViewport(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function _resetRootCanvasViewportForTest(): void {
+  viewport = FILL_VIEWPORT;
+  listeners.clear();
+}

package/src/kit/world-document-routing.ts

@@ -0,0 +1,104 @@
+import {
+  availableWorkspaceDocuments,
+  openAvailableWorkspaceDocument,
+} from '@volter/sdk/kit/workspace-available-documents';
+import { activateWorkspaceDocument } from '@volter/sdk/kit/workspace-document-registry';
+
+const _documentIdByRoot = new Map<string, string>();
+
+export function registerRootDocumentRoute(worldId: string, documentId: string): () => void {
+  _documentIdByRoot.set(worldId, documentId);
+  return () => {
+    if (_documentIdByRoot.get(worldId) === documentId) _documentIdByRoot.delete(worldId);
+  };
+}
+
+/** The edit-time document that owns a manifest world, or `null` when the
+ *  session installed none. Read by the Edit tab row, whose `root-mount` scene
+ *  entries NAME a standing document rather than adding one
+ *  (`components/scene-documents.tsx`). */
+export function rootDocumentId(worldId: string): string | null {
+  return (
+    _documentIdByRoot.get(worldId) ??
+    availableWorkspaceDocuments().find((document) => document.rootId === worldId)?.descriptor.id ??
+    null
+  );
+}
+
+/** Activate the edit-time document that owns a manifest world. */
+export function activateRootDocument(worldId: string): boolean {
+  const documentId = rootDocumentId(worldId);
+  return documentId
+    ? openAvailableWorkspaceDocument(documentId) || activateWorkspaceDocument(documentId)
+    : false;
+}
+
+const _gapByRoot = new Map<string, () => string | null>();
+
+/**
+ * Register the reason a root has NO document to activate — the DECIDED half of
+ * {@link activateRootDocument}'s `false`.
+ *
+ * A root's document is installed asynchronously, so `false` from
+ * `activateRootDocument` means one of two opposite things: "not yet" (boot in
+ * flight) or "never" (this session has settled that this root has no design
+ * surface of its own). Callers cannot tell them apart, so every caller waits
+ * out the full registration window even for an answer that was decided in the
+ * first second — long enough that the asking side has usually given up before
+ * the refusal is spoken.
+ *
+ * The `reason` is a THUNK, evaluated live at each ask, precisely so it can keep
+ * answering `null` while the document may still arrive and only speak once the
+ * question is settled. It is registered by whoever OWNS the decision — the
+ * presenter must never infer why a document is absent.
+ */
+export function registerRootDocumentGap(worldId: string, reason: () => string | null): () => void {
+  _gapByRoot.set(worldId, reason);
+  return () => {
+    if (_gapByRoot.get(worldId) === reason) _gapByRoot.delete(worldId);
+  };
+}
+
+/** Why this root has no document to activate, when that is decided; `null`
+ *  while one may still arrive. */
+export function rootDocumentGap(worldId: string): string | null {
+  return _gapByRoot.get(worldId)?.() ?? null;
+}
+
+const _workspaceGaps = new Set<(documentId: string) => string | null>();
+
+/**
+ * The same DECIDED half, for a workspace document asked for by id.
+ *
+ * `activateWorkspaceDocument` returns `false` with the identical ambiguity
+ * {@link registerRootDocumentGap} describes — "not yet" and "never" are one
+ * answer — and a workspace document has the further case a root cannot have:
+ * the id may name nothing at all. Both are the same question ("why is this
+ * document not here?"), so they share this mechanism rather than growing a
+ * second one; the arms differ only in their KEY, because a root is asked for
+ * by manifest id and a workspace document by document id.
+ *
+ * The resolver takes the requested id rather than being registered per id,
+ * because the ids that will never exist cannot be enumerated in advance — the
+ * owner answers for the whole namespace it installs into. Same thunk contract:
+ * `null` means "no verdict" (boot in flight, or not this owner's question),
+ * and the first owner to speak wins.
+ */
+export function registerWorkspaceDocumentGap(
+  reason: (documentId: string) => string | null,
+): () => void {
+  _workspaceGaps.add(reason);
+  return () => {
+    _workspaceGaps.delete(reason);
+  };
+}
+
+/** Why this workspace document is not here, when that is decided; `null` while
+ *  one may still arrive. */
+export function workspaceDocumentGap(documentId: string): string | null {
+  for (const reason of _workspaceGaps) {
+    const answer = reason(documentId);
+    if (answer !== null) return answer;
+  }
+  return null;
+}

package/src/kit/world-pan-state.ts

@@ -0,0 +1,198 @@
+/**
+ * Shared DOM-world canvas transform (spec27 §8 "space-pan" row, D4 rebuild) — a
+ * module-level subscribable singleton (mirrors `eyedropper-session.ts`'s "bare
+ * singleton + own listener set" shape) holding the CURRENT SHARED pan + zoom
+ * applied, in LOCKSTEP, to both every design-time world-layer host
+ * (`design-time-layers.ts`'s `createLayerElement`-produced react/pixi layers)
+ * and `RootSelectionOverlay`'s visual-chrome wrapper. Its independent input
+ * sibling deliberately remains untransformed and covers the full viewport.
+ *
+ * SOUNDNESS (why lockstep preserves the "zero-correction" host-relative rect
+ * invariant `RootSelectionOverlay.tsx`'s own doc comment establishes):
+ * `RectProvider.rect(id)` is computed as `el.getBoundingClientRect()` MINUS
+ * the owning world's own root/host `getBoundingClientRect()`
+ * (`react-world-authoring-adapter.ts`'s `toHostRelative`/`hostRect` — `this
+ * .root` IS the exact layer div `createLayerElement` produces). A CSS
+ * `transform: translate()` applied directly to that host element shifts the
+ * host's OWN rendered rect AND every descendant's rendered rect by the
+ * IDENTICAL `(x, y)` delta — a rigid subtree translation — so the
+ * subtraction is invariant under pan: `rect(id)` returns the SAME
+ * host-relative numbers at any pan offset, unmodified, with no pan-awareness
+ * needed in `inspect.ts`'s geometry math or the overlay chrome consumers.
+ * Zoom scales both measured rectangles; `toHostRelative` divides their
+ * offsets and dimensions by the shared zoom before exposing authored-space
+ * geometry, while `RootSelectionOverlay.toHostLocal` performs the inverse
+ * for pointer gestures. `PickProvider.pick` needs no changes — it
+ * hit-tests real rendered rects against the real client cursor position,
+ * both of which already reflect the applied transform natively.
+ *
+ * Applying the exact SAME transform to `RootSelectionOverlay`'s own visual-
+ * chrome wrapper (a SIBLING of every world-layer host inside the SAME
+ * `the world root's stage` containerRef parent — see that file's own mount-site doc
+ * comment) shifts and scales the overlay by the identical transform — so
+ * drawing a chrome element at `rect(id)`'s authored coordinates lands it at the
+ * SAME screen position as the panned live element it describes. This is the
+ * entire "lockstep" contract: every consumer on both sides of the pan reads
+ * ONE shared value (`getRootPan()`) and applies it through the ONE shared
+ * pure helper (`panTransformValue`) — never two independently-computed
+ * transforms that could drift.
+ */
+
+export interface RootPan {
+  readonly x: number;
+  readonly y: number;
+  readonly zoom: number;
+}
+
+const ZERO_PAN: RootPan = { x: 0, y: 0, zoom: 1 };
+
+/**
+ * One document camera over a 2D authoring plane.
+ *
+ * DOM component boards still use the historical shared instance exported
+ * below. A native canvas Scene creates its own instance, because a scene
+ * camera and a component-board camera are different documents and must not
+ * inherit one another's pose merely because both happen to be 2D.
+ */
+export interface RootViewController {
+  get(): RootPan;
+  setView(x: number, y: number, zoom: number): void;
+  setPan(x: number, y: number): void;
+  setZoom(zoom: number): void;
+  reset(): void;
+  subscribe(listener: () => void): () => void;
+}
+
+export function createRootViewController(initial: RootPan = ZERO_PAN): RootViewController {
+  let current: RootPan = initial;
+  const subscribers = new Set<() => void>();
+  const notifySubscribers = (): void => {
+    for (const listener of subscribers) listener();
+  };
+  return {
+    get: () => current,
+    setView: (x, y, zoom) => {
+      const nextZoom = Math.min(4, Math.max(0.1, zoom));
+      if (current.x === x && current.y === y && current.zoom === nextZoom) return;
+      current = { x, y, zoom: nextZoom };
+      notifySubscribers();
+    },
+    setPan: (x, y) => {
+      const nextZoom = current.zoom;
+      if (current.x === x && current.y === y) return;
+      current = { x, y, zoom: nextZoom };
+      notifySubscribers();
+    },
+    setZoom: (zoom) => {
+      const nextZoom = Math.min(4, Math.max(0.1, zoom));
+      if (current.zoom === nextZoom) return;
+      current = { x: current.x, y: current.y, zoom: nextZoom };
+      notifySubscribers();
+    },
+    reset: () => {
+      if (current.x === 0 && current.y === 0 && current.zoom === 1) return;
+      current = ZERO_PAN;
+      notifySubscribers();
+    },
+    subscribe: (listener) => {
+      subscribers.add(listener);
+      return () => subscribers.delete(listener);
+    },
+  };
+}
+
+let _pan: RootPan = ZERO_PAN;
+const listeners = new Set<() => void>();
+
+/** The historical DOM-board camera, exposed as a controller for generic
+ * navigation/overlay code. Existing function exports below remain the
+ * compatibility surface for board-specific callers. */
+export const sharedRootViewController: RootViewController = {
+  get: () => getRootPan(),
+  setView: (x, y, zoom) => setRootView(x, y, zoom),
+  setPan: (x, y) => setRootPan(x, y),
+  setZoom: (zoom) => setRootZoom(zoom),
+  reset: () => resetRootPan(),
+  subscribe: (listener) => subscribeRootPan(listener),
+};
+
+function notify(): void {
+  for (const l of listeners) l();
+}
+
+/** The current shared canvas transform; x/y are CSS px and zoom is unitless. */
+export function getRootPan(): RootPan {
+  return _pan;
+}
+
+/** Set the complete shared canvas transform in one subscriber notification. */
+export function setRootView(x: number, y: number, zoom: number): void {
+  const nextZoom = Math.min(4, Math.max(0.1, zoom));
+  if (_pan.x === x && _pan.y === y && _pan.zoom === nextZoom) return;
+  _pan = { x, y, zoom: nextZoom };
+  notify();
+}
+
+/** Set the shared pan translate to an absolute `(x, y)`. */
+export function setRootPan(x: number, y: number): void {
+  setRootView(x, y, _pan.zoom);
+}
+
+/** Set the shared canvas zoom while preserving its current pan. */
+export function setRootZoom(zoom: number): void {
+  setRootView(_pan.x, _pan.y, zoom);
+}
+
+/** Set the shared pan translate by a RELATIVE `(dx, dy)` — a convenience
+ *  wrapper over `setRootPan` (not used by `RootSelectionOverlay`'s own
+ *  space-drag, which composes onto a captured drag-start snapshot instead —
+ *  see its own doc comment — but kept here as the natural pure counterpart
+ *  for any future incremental caller, e.g. a nudge-pan keybinding). */
+export function panRootBy(dx: number, dy: number): void {
+  setRootPan(_pan.x + dx, _pan.y + dy);
+}
+
+/** Reset pan to `(0, 0)` and zoom to 100% — called on a world-layer remount (`design-time-
+ *  layers.ts`'s `mountDesignTimeLayers`, invoked on initial edit-mode install
+ *  AND every acknowledged edit-mode rebuild), so switching/reloading the active
+ *  world set never leaves a stale pan offset applied over a DIFFERENT layer
+ *  stack. A no-op (no `notify()`) when already at rest, so a fresh session
+ *  never fires a spurious subscriber tick. */
+export function resetRootPan(): void {
+  if (_pan.x === 0 && _pan.y === 0 && _pan.zoom === 1) return;
+  _pan = ZERO_PAN;
+  notify();
+}
+
+/** Subscribe to canvas-transform changes — both `design-time-layers.ts` (imperative DOM
+ *  style writes) and `RootSelectionOverlay` (`useSyncExternalStore`) bind
+ *  this so every lockstep mount point re-applies the SAME new value the
+ *  instant it changes. */
+export function subscribeRootPan(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/**
+ * The ONE shared CSS `transform` value both visual lockstep mount points apply —
+ * pure, so a unit test can assert the world-layer host and the overlay
+ * wrapper are handed byte-identical strings for any given pan (the actual
+ * "lockstep" proof). `undefined` at rest `(0, 0)` so neither mount point ever
+ * carries a no-op `transform: translate(0px, 0px)` — keeps every pre-pan
+ * pixel-position snapshot (the full 27x suite, pinned at pan=0) byte-identical
+ * to its pre-this-feature output.
+ */
+export function panTransformValue(pan: RootPan): string | undefined {
+  if (pan.x === 0 && pan.y === 0 && pan.zoom === 1) return undefined;
+  if (pan.zoom === 1) return `translate(${pan.x}px, ${pan.y}px)`;
+  if (pan.x === 0 && pan.y === 0) return `scale(${pan.zoom})`;
+  return `translate(${pan.x}px, ${pan.y}px) scale(${pan.zoom})`;
+}
+
+/** Test-only reset (mirrors `eyedropper-session.ts`'s/`world-session-
+ *  state.ts`'s identical helpers) — drops pan + every subscriber so unit
+ *  tests don't leak state across cases. */
+export function _resetRootPanStateForTest(): void {
+  _pan = ZERO_PAN;
+  listeners.clear();
+}

package/src/kit/write-pipe.ts

@@ -0,0 +1,173 @@
+/**
+ * THE ONE PERSISTENCE PIPE — `resolve(anchor) → write(dialect) → record(recorder)`.
+ *
+ * Every authored write, from every lane, runs through {@link runWritePipe}.
+ * The lanes that used to be parallel stacks are now this pipe's PLUG POINTS:
+ * a lane supplies a resolution (which anchor this edit lands at), a dialect
+ * writer (the bytes), and a recorder (history), and the pipe supplies the
+ * ordering, the awaiting, and the ack.
+ *
+ * ## The three defects it exists for, all measured on the vendored racing game
+ *
+ * 1. **The ack was the ADAPTER'S blanket answer, not this edit's.** The
+ *    composite joined only its persist-CAPABLE children, so a three-root edit
+ *    acked the DOM root's destination with `persisted: true`. Here the ack is
+ *    produced by the component that performed the write, about that write, and
+ *    there is nowhere else for a caller to get one.
+ * 2. **The classifier and the writer were different components.** A subject the
+ *    adapter classified `live-only` still wrote a real prop into the game's
+ *    source, because the code answering `TruthProvider.resolve` was not
+ *    the code performing the write. Here the anchor is resolved ONCE, and a
+ *    `live-only` resolution has no `write` member at all — reaching a dialect
+ *    writer from it is a type error, not a discipline.
+ * 3. **The write was fired un-awaited, so the ack raced the byte.** Here the
+ *    pipe awaits the dialect writer and the recorder before it acks.
+ *
+ * ## Why `live-only` is a destination and not a failure
+ *
+ * `live-only` (and its play-mode sibling, ephemeral) is a real
+ * {@link WriteAnchorKind}: the edit lands on the running object for the session
+ * and nothing else, and the contract of that kind is that the surface SAYS SO.
+ * So the pipe's live-only branch still applies the edit — the caller has
+ * already done that, synchronously, which is what keeps an `endEdit(); undo()`
+ * sequence working — and answers `persisted: false` with the reason reported
+ * where a user can read it. What the pipe forbids is the inverse: naming a
+ * destination no byte reached.
+ */
+
+import type { WriteAck, WriteAnchorKind } from '@volter/project/adapter';
+
+export type { WriteAck } from '@volter/project/adapter';
+
+/** What a surface reports when nothing this session does reaches a file. */
+export const LIVE_ONLY_DESTINATION = 'live-only (not saved)';
+
+/** What a play-mode adoption reports: edits are real, and die with the session. */
+export const EPHEMERAL_DESTINATION = 'ephemeral (discarded on stop)';
+
+/** What `CompositeAuthoringAdapter.persistence` reports when no child of the
+ *  composition can persist at all. That provider answers the SAVE-status
+ *  question ("where do this surface's saves go"), never the per-edit one — the
+ *  pipe's ack is the only answer to that. */
+export const NO_PERSISTABLE_CHILD_DESTINATION = '(no persistable child)';
+
+/** The honest floor, as a value: no write was performed, and saying so is the
+ *  whole point. Frozen because it is shared by every lane that has no write. */
+export const LIVE_ONLY_ACK: WriteAck = Object.freeze({
+  destination: LIVE_ONLY_DESTINATION,
+  persisted: false,
+});
+
+/**
+ * A CLIPBOARD gesture reports itself by its WRITE, never by the clipboard half
+ * that already succeeded.
+ *
+ * `StructuralClipboardOutcome` (`@volter/project/adapter`) keeps `false` as the refusal
+ * channel and reserves the {@link WriteAck} for a SUCCESSFUL cut/paste. A cut
+ * whose removal reached no byte is a COPY: handing its `persisted: false` ack
+ * straight back is truthy, so every caller — `consumer-actions.ts`'s
+ * `clipboardStructureWrite`, which only shortcuts on `=== false`, and the
+ * composite's `cut`, which claims clipboard ownership on anything else — reads
+ * a refusal as a landed edit.
+ *
+ * ONE owner, because the four lanes each said this inline and one commit
+ * deleted all four collapses together while widening the return type.
+ */
+export function clipboardOutcome(ack: WriteAck): false | WriteAck {
+  return ack.persisted ? ack : false;
+}
+
+/** An anchor kind that has somewhere to land. `live-only` is excluded BY THE
+ *  TYPE, which is what makes "a live-only resolution cannot reach a writer" a
+ *  compile-time fact rather than a convention. */
+export type AnchoredWriteKind = Exclude<WriteAnchorKind, 'live-only'>;
+
+/**
+ * Step 1's product: what THIS edit's anchor resolved to.
+ *
+ * The two arms are not "success" and "failure" — they are the two honest
+ * outcomes of asking where an edit lands. Only the `writer` arm carries a
+ * `write`, so a lane cannot accidentally write through a resolution that said
+ * there was nowhere to write.
+ */
+export type WriteResolution =
+  | {
+      readonly reaches: 'writer';
+      /** Which lane carries it — the SAME fact `TruthProvider.resolve`
+       *  must report for this subject, because both read this resolution. */
+      readonly anchorKind: AnchoredWriteKind;
+      /** Where the bytes go, in the dialect writer's own words. */
+      readonly destination: string;
+      /** Step 2 — the dialect writer, already bound to this edit. `true` ⇒ the
+       *  bytes landed and the writer's own transaction carries both halves. */
+      readonly write: () => Promise<boolean>;
+    }
+  | {
+      readonly reaches: 'live-only';
+      /** {@link LIVE_ONLY_DESTINATION} or {@link EPHEMERAL_DESTINATION}. */
+      readonly destination: string;
+      /** Why there is nowhere to write — reported to the user by the lane's
+       *  own reporter, never swallowed. */
+      readonly reason: string;
+    };
+
+/** One edit, offered to the pipe. */
+export interface PipedWrite {
+  /**
+   * Step 1 — resolve THIS edit's anchor. Called EXACTLY ONCE by the pipe, so
+   * the classification a caller reads and the route the write takes are the
+   * same object rather than two evaluations that can disagree.
+   */
+  resolve(): WriteResolution;
+  /**
+   * Step 3 — the recorder. Called exactly once, after the write step settled,
+   * with what actually happened. `persisted: true` ⇒ the dialect writer's own
+   * transaction already carries both the file and the live half, so the
+   * recorder skips its session journal rather than adding a second entry.
+   *
+   * This is where undo/redo integrates, and it is the ONLY place: a lane that
+   * journals outside the pipe forks history, which is what the pipe replaced.
+   */
+  record(persisted: boolean): void;
+  /**
+   * Show a live-only reason where the user can read it. Called only for the
+   * `live-only` arm, and only when the lane wants it said (an unarmed backend
+   * refusing on every frame of a game somebody is playing is noise, so lanes
+   * gate this themselves).
+   */
+  report?(reason: string): void;
+}
+
+/**
+ * RUN ONE EDIT THROUGH THE PIPE, and answer for it.
+ *
+ * The ordering is the contract: resolve, then write (awaited), then record
+ * (before the ack). A caller that awaits this ack has awaited the byte.
+ *
+ * A dialect writer that comes back `false` has already reported its own reason
+ * (that is its contract — every refusal names its gate), and the edit degrades
+ * to the live-only floor: the value is on the running object, the recorder
+ * journals it so it can be undone, and the ack says no byte moved.
+ */
+export async function runWritePipe(edit: PipedWrite): Promise<WriteAck> {
+  const resolution = edit.resolve();
+  if (resolution.reaches === 'live-only') {
+    edit.report?.(resolution.reason);
+    edit.record(false);
+    return { destination: resolution.destination, persisted: false };
+  }
+  const persisted = await resolution.write();
+  edit.record(persisted);
+  return persisted
+    ? { destination: resolution.destination, persisted: true }
+    : { destination: LIVE_ONLY_DESTINATION, persisted: false };
+}
+
+/** Spell a live-only resolution — the one form, so no lane invents a second
+ *  phrasing of "there is nowhere to write". */
+export function resolvesLiveOnly(
+  reason: string,
+  destination: string = LIVE_ONLY_DESTINATION,
+): WriteResolution {
+  return { reaches: 'live-only', destination, reason };
+}

package/src/layout-arrangements.ts

@@ -0,0 +1,5 @@
+import type { WorkspaceArrangement } from '@volter/project/adapter/workspace-arrangement';
+export type { WorkspaceArrangement, WorkspaceAreaContribution } from '@volter/project/adapter/workspace-arrangement';
+
+export const GameArrangement: WorkspaceArrangement = { id: 'game', title: 'Game' };
+export const DesignArrangement: WorkspaceArrangement = { id: 'design', title: 'Design' };