@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/authoring/panel-authoring.ts

@@ -0,0 +1,121 @@
+/**
+ * ONE resolver for "which authoring adapter do the shared panels drive?" —
+ * the Hierarchy and the Inspector must never disagree, and before this module
+ * they each open-coded the same expression.
+ *
+ * ## The defect this exists for (audit A1/A3, 2026-08-01) — and its MEASURED cause
+ *
+ * Symptom: every pixi ingest (the in-tree canvas fixtures, and
+ * the synthetic `ingest-pixi` manifest fixtures) mounted, captured and drew,
+ * `getAuthoringOverride()` held a healthy `PixiAuthoringAdapter` with
+ * `{transform, inspectorFields, persist}` all true — and the Hierarchy still
+ * rendered "No authoring adapter" while the Inspector took its
+ * nothing-to-show branch. The three route (the `games-fps` fixture) bound fine in the same session
+ * shape.
+ *
+ * The audit's hypothesis was adapter RESOLUTION: that the active workspace
+ * document's adapter shadowed the ingest override at `Inspector.tsx`'s
+ * `documentSelection?.adapter ?? getActiveAuthoring(store)`. Reproduced live on
+ * a single-`ingest-pixi`-root project and measured: `activeWorkspaceDocument
+ * Selection()` is `null`, the only open document is `workspace:game`, and the
+ * override is already correct at the moment the panels are showing the wrong
+ * thing. Resolution was never wrong. **It was a stale render**: the override
+ * slot is module state with no change notification, and the panels only
+ * re-rendered because ingest entry ALSO moves workspace focus, which in
+ * a Three-rooted project activates a different center document and the
+ * workspace registry's `notifyChanged()` re-rendered them incidentally. With no
+ * Three root there is one center document, that activation is a no-op, and the
+ * incidental notification never happens.
+ *
+ * The fix is therefore in `active-adapter.ts` (the slot notifies) plus the
+ * subscription the panels take out beside this resolver. This module exists so
+ * the two panels share ONE expression and one subscription set instead of two
+ * copies that can drift apart again.
+ *
+ * ## Why the resolution ORDER is unchanged
+ *
+ * An earlier revision of this fix also made an ingest override outrank a
+ * document-published adapter — the audit's hypothesis, kept "just in case". It
+ * is deliberately NOT here: it was never observed (measured null document
+ * selection in the reproduction above), and reaching `isIngestActive` from a
+ * module both shared panels import drags `ingest/mount-ingest-root.ts`'s whole transitive
+ * graph — the pixi stack and the engine renderer setup — into the
+ * Hierarchy's module graph, which broke six unit suites outright on a
+ * `URL.createObjectURL` that does not exist in the node test environment. A
+ * behavior change nobody could demonstrate is not worth a dependency edge that
+ * heavy. If document shadowing is ever actually observed, it should be fixed
+ * where the document's provider is registered (`world-documents.tsx`), which
+ * is the layer that knows a foreign session is live.
+ */
+
+import type { AdapterSurface, AuthoringAdapter } from '@volter/project/adapter';
+import type { ShellDocumentState } from '@volter/sdk/kit/shell-document-state';
+import {
+  activeWorkspaceDocument,
+  activeWorkspaceDocumentSelection,
+  type WorkspaceDocumentSelection,
+} from '@volter/sdk/kit/workspace-document-registry';
+import { getActiveAuthoring } from './active-adapter';
+import { CompositeAuthoringAdapter } from '@volter/sdk/kit/authoring/composite-authoring-adapter';
+
+export interface PanelAuthoringBinding {
+  /** The adapter the Hierarchy/Inspector must drive. */
+  readonly adapter: AuthoringAdapter;
+  /** Render substrate owned by the active authored document. `null` for
+   * composition/reference documents that do not focus one root surface. */
+  readonly surface: AdapterSurface | null;
+  /** The active document's selection context, when it publishes one. */
+  readonly documentSelection: WorkspaceDocumentSelection | null;
+}
+
+/**
+ * An authored root document projects only the root it is showing. The Game
+ * document intentionally falls through to the full composite: composition is
+ * its subject, while a Scene/world document's subject is one root.
+ *
+ * `world` documents carry their manifest root id as provenance. The pinned
+ * Three Scene document predates per-root document ids, so its focused child is
+ * the one live Three adapter that honestly reports transform authoring.
+ */
+function adapterSurface(kind: string): AdapterSurface | null {
+  return kind === 'three' || kind === 'canvas' || kind === 'dom' ? kind : null;
+}
+
+function rootDocumentBinding(
+  active: AuthoringAdapter,
+): { adapter: AuthoringAdapter; surface: AdapterSurface } | null {
+  if (!(active instanceof CompositeAuthoringAdapter)) return null;
+  const document = activeWorkspaceDocument()?.descriptor;
+  if (!document) return null;
+
+  const children = active.childAdapters();
+  if (document.kind === 'world') {
+    const rootId = document.provenance?.rootId;
+    const child = rootId ? children.find((candidate) => candidate.worldId === rootId) : undefined;
+    const surface = child ? adapterSurface(child.kind) : null;
+    return child && surface ? { adapter: child.adapter, surface } : null;
+  }
+  if (document.kind === 'scene') {
+    const child = children.find(
+      (candidate) => candidate.kind === 'three' && candidate.adapter.capabilities.transform,
+    );
+    if (!child) return null;
+    return {
+      adapter: active.projectedDocumentAdapter(child.worldId) ?? child.adapter,
+      surface: 'three',
+    };
+  }
+  return null;
+}
+
+export function resolvePanelAuthoring(store: ShellDocumentState): PanelAuthoringBinding {
+  const documentSelection = activeWorkspaceDocumentSelection();
+  const active = getActiveAuthoring(store);
+  const rootBinding = rootDocumentBinding(active);
+  const documentKind = activeWorkspaceDocument()?.descriptor.kind;
+  return {
+    adapter: documentSelection?.adapter ?? rootBinding?.adapter ?? active,
+    surface: documentKind === 'story' ? 'dom' : (rootBinding?.surface ?? null),
+    documentSelection,
+  };
+}

package/src/kit/authoring/project-authoring-session.ts

@@ -0,0 +1,105 @@
+/** The project owns its authoring session. Scene tabs attach renderers to it;
+ * closing a viewport must not remove the other scenes or component canvases. */
+import { runProjectReady } from '../project-ready';
+import {
+  availableWorkspaceDocuments,
+  requestAvailableWorkspaceDocument,
+} from '@volter/sdk/kit/workspace-available-documents';
+import { activeWorkspaceDocumentId, openWorkspaceDocuments } from '@volter/sdk/kit/workspace-document-registry';
+import type { CompositeAuthoringAdapter } from '@volter/sdk/kit/authoring/composite-authoring-adapter';
+import {
+  bindEditModeRebuildOwner,
+  exitEditModeAuthoring,
+  installEditModeAuthoringForProject,
+} from '@volter/sdk/kit/authoring/edit-mode-authoring';
+import type { ShellStore } from '@volter/sdk/kit/shell-store';
+
+type Stage = (composite: CompositeAuthoringAdapter) => Promise<void>;
+class ProjectAuthoringSession {
+  private references = 0;
+  private disposed = false;
+  private composite: CompositeAuthoringAdapter | undefined;
+  private disposeDocuments: (() => void) | undefined;
+  private stages = new Set<Stage>();
+  private tail: Promise<void> = Promise.resolve();
+  private unbind: () => void;
+  readonly ready: Promise<void>;
+
+  constructor(private readonly store: ShellStore) {
+    this.unbind = bindEditModeRebuildOwner(() => this.rebuild());
+    this.ready = this.rebuild();
+  }
+  retain(): () => void {
+    this.references++;
+    return () => {
+      if (--this.references > 0) return;
+      this.disposed = true;
+      this.unbind();
+      this.disposeDocuments?.();
+      exitEditModeAuthoring(this.composite);
+      sessions.delete(this.store);
+    };
+  }
+  attach(stage: Stage): { ready: Promise<void>; dispose: () => void } {
+    const release = this.retain();
+    this.stages.add(stage);
+    // A stage attached during a rebuild is mounted by that rebuild. A later
+    // stage attaches to the already installed project without reinstalling it.
+    const ready = this.composite ? stage(this.composite) : this.tail;
+    return {
+      ready,
+      dispose: () => {
+        this.stages.delete(stage);
+        release();
+      },
+    };
+  }
+  private rebuild(): Promise<void> {
+    const run = this.tail.then(async () => {
+      if (this.disposed) return;
+      const active = activeWorkspaceDocumentId();
+      const available = new Set(availableWorkspaceDocuments().map((entry) => entry.descriptor.id));
+      const reopen = this.composite
+        ? openWorkspaceDocuments()
+            .map((document) => document.descriptor.id)
+            .filter((id) => available.has(id))
+        : [];
+      this.disposeDocuments?.();
+      this.disposeDocuments = undefined;
+      exitEditModeAuthoring(this.composite);
+      this.composite = undefined;
+      const composite = await installEditModeAuthoringForProject(this.store);
+      if (this.disposed) {
+        exitEditModeAuthoring(composite);
+        return;
+      }
+      const { installRootDocuments } = await import('../components/world-documents');
+      if (this.disposed) {
+        exitEditModeAuthoring(composite);
+        return;
+      }
+      this.composite = composite;
+      this.disposeDocuments = installRootDocuments(this.store, composite);
+      for (const id of reopen) requestAvailableWorkspaceDocument(id, id === active);
+      await Promise.all([...this.stages].map((stage) => stage(composite)));
+    });
+    this.tail = run.catch(() => undefined);
+    return run;
+  }
+}
+const sessions = new Map<ShellStore, ProjectAuthoringSession>();
+function sessionFor(store: ShellStore): ProjectAuthoringSession {
+  let session = sessions.get(store);
+  if (!session) {
+    session = new ProjectAuthoringSession(store);
+    sessions.set(store, session);
+  }
+  return session;
+}
+export function retainProjectAuthoringSession(store: ShellStore) {
+  const session = sessionFor(store);
+  return { ready: session.ready.then(() => runProjectReady()), dispose: session.retain() };
+}
+export function attachProjectAuthoringStage(store: ShellStore, stage: Stage) {
+  return sessionFor(store).attach(stage);
+}

package/src/kit/authoring/provenance.ts

@@ -0,0 +1,99 @@
+/**
+ * Seam-level provenance resolution (spec 29 §5): which {@link
+ * AuthoringProvenance} governs a given hierarchy node. Provenance is declared
+ * once per adapter and rendered at the seam (world group row / panel header);
+ * affordance code also reads it for the REASON string on a disabled operation
+ * ("the subject is present but the operation isn't" — the complement of spec
+ * 28's hide-when-absent rule).
+ *
+ * Rule zero: roots are resolved by ASKING the composite (`groupNodeId` /
+ * `ownerOf`), never by decoding adapter-minted id strings here.
+ */
+import type { AuthoringAdapter, AuthoringProvenance } from '@volter/project/adapter';
+import { CompositeAuthoringAdapter } from '@volter/sdk/kit/authoring/composite-authoring-adapter';
+
+/** Resolve the concrete adapter that owns a real hierarchy node. Synthetic
+ * composite rows and unknown ids have no owner. */
+export function authoringAdapterForNode(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): AuthoringAdapter | null {
+  if (!(adapter instanceof CompositeAuthoringAdapter)) return adapter;
+  const worldId = adapter.ownerOf(nodeId);
+  if (worldId === null) return null;
+  return adapter.childAdapters().find((child) => child.worldId === worldId)?.adapter ?? null;
+}
+
+/**
+ * The adapter GOVERNING `nodeId` under the ACTIVE adapter — the one entitled to
+ * answer questions *about that node*: the owning child inside a composite, the
+ * world's own child for a `world:<id>` GROUP row, the adapter itself when it
+ * isn't a composite. `null` when the composite recognizes no owner (a synthetic
+ * organization row, an unknown id).
+ *
+ * Use this — not the active adapter — for any PER-NODE capability check inside
+ * a composite. `CompositeAuthoringAdapter`'s provider fields are unconditional
+ * routing objects: reading presence off the composite is `true` for every node
+ * in every multi-root project, including nodes whose owner exposes no such
+ * provider at all and nodes nobody owns (where `route()` falls back to the
+ * FIRST child). That has the editor assert a capability claim on a child's
+ * behalf — exactly the fabrication the anti-shim rule forbids. Ask the
+ * governing adapter instead, and treat "no governing adapter" as "nobody
+ * declared anything".
+ *
+ * Distinct from {@link authoringAdapterForNode}, which resolves REAL hierarchy
+ * nodes only and is deliberately `null` for a group row.
+ */
+export function governingAdapterForNode(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): AuthoringAdapter | null {
+  if (!(adapter instanceof CompositeAuthoringAdapter)) return adapter;
+  for (const child of adapter.childAdapters()) {
+    if (adapter.groupNodeId(child.worldId) === nodeId) return child.adapter;
+  }
+  return authoringAdapterForNode(adapter, nodeId);
+}
+
+/**
+ * The provenance governing `nodeId` under the ACTIVE adapter: the owning
+ * child's declaration inside a composite (a `world:<id>` group row resolves
+ * to that world's own child), the adapter's own declaration otherwise.
+ * `null` when nothing was declared (the shell shows no badge and falls back
+ * to a generic reason — never fabricates a claim).
+ */
+export function provenanceForNode(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): AuthoringProvenance | null {
+  return governingAdapterForNode(adapter, nodeId)?.provenance ?? null;
+}
+
+/** The reason string for an affordance that is present but unavailable —
+ *  the adapter's own explanation when it declared one, a plain honest
+ *  fallback when it didn't. */
+export function unavailableReason(provenance: AuthoringProvenance | null): string {
+  return provenance?.detail ?? "Not supported by this world's adapter.";
+}
+/**
+ * WHERE this adapter's truth is written, as one human-readable string.
+ *
+ * One owner, because two surfaces read it and they must agree: the Hierarchy
+ * panel publishes it as its scene name (`components/GameHierarchy.tsx`), and
+ * the Inspector's identity row PRINTS it as the datablock line
+ * (`inspection/model.ts`'s `InspectionDocumentLine`) now that the tree's own
+ * breadcrumb row is gone. When the two were computed separately the
+ * Inspector's half silently showed nothing for every adapter that answers
+ * through its document root instead of a persistence provider — which is the
+ * ordinary three-source case.
+ *
+ * `null` for a session with no single destination (a composite, whose worlds'
+ * destinations differ) — the same silence its `provenance` keeps.
+ */
+export function authoringDestination(adapter: AuthoringAdapter): string | null {
+  const persisted = adapter.persistence?.destination;
+  if (persisted) return persisted;
+  const roots = adapter.hierarchy.roots();
+  const documentRoot = roots.length === 1 && roots[0]?.role === 'document' ? roots[0] : null;
+  return documentRoot?.secondaryLabel ?? documentRoot?.label ?? null;
+}

package/src/kit/authoring/react-canvas-navigation.ts

@@ -0,0 +1,259 @@
+import { type RootPan, type RootViewController, sharedRootViewController } from '@volter/sdk/kit/world-pan-state';
+
+const MIN_ZOOM = 0.1;
+const MAX_ZOOM = 4;
+/** A 2D scene zooms further both ways than a board: a pixel-art sprite is read at many times its
+ *  size, and a level wider than the screen is laid out from far above it. */
+export const SCENE_MIN_ZOOM = 0.02;
+export const SCENE_MAX_ZOOM = 32;
+const ZOOM_SENSITIVITY = 0.002;
+const SECONDARY_DRAG_THRESHOLD_PX = 4;
+
+export interface ReactCanvasWheelInput {
+  readonly clientX: number;
+  readonly clientY: number;
+  readonly deltaX: number;
+  readonly deltaY: number;
+  readonly deltaMode: number;
+  readonly ctrlKey: boolean;
+  readonly metaKey: boolean;
+  readonly shiftKey: boolean;
+  readonly bounds: Pick<DOMRect, 'left' | 'top' | 'width' | 'height'>;
+}
+
+function deltaPixels(delta: number, mode: number, pageSize: number): number {
+  if (mode === 1) return delta * 16; // WheelEvent.DOM_DELTA_LINE
+  if (mode === 2) return delta * pageSize; // WheelEvent.DOM_DELTA_PAGE
+  return delta;
+}
+
+/** Resolve one component-board wheel gesture without touching global state. */
+export function resolveReactCanvasWheel(view: RootPan, input: ReactCanvasWheelInput): RootPan {
+  let deltaX = deltaPixels(input.deltaX, input.deltaMode, input.bounds.width);
+  let deltaY = deltaPixels(input.deltaY, input.deltaMode, input.bounds.height);
+
+  if (input.ctrlKey || input.metaKey) {
+    const zoom = Math.min(
+      MAX_ZOOM,
+      Math.max(MIN_ZOOM, view.zoom * Math.exp(-deltaY * ZOOM_SENSITIVITY)),
+    );
+    const pointerX = input.clientX - input.bounds.left;
+    const pointerY = input.clientY - input.bounds.top;
+    const worldX = (pointerX - view.x) / view.zoom;
+    const worldY = (pointerY - view.y) / view.zoom;
+    return {
+      x: pointerX - worldX * zoom,
+      y: pointerY - worldY * zoom,
+      zoom,
+    };
+  }
+
+  // Figma treats a shifted vertical mouse wheel as horizontal movement.
+  // Trackpads already provide deltaX, so preserve that richer input.
+  if (input.shiftKey && deltaX === 0) {
+    deltaX = deltaY;
+    deltaY = 0;
+  }
+  return { x: view.x - deltaX, y: view.y - deltaY, zoom: view.zoom };
+}
+
+/** Resolve the wheel gesture for a native 2D Scene. Like the Three Scene and
+ * Godot's 2D workspace, the wheel changes the spatial camera's zoom around
+ * the cursor; panning belongs to middle-drag, right-drag, or Space-drag. This is
+ * intentionally different from the component board above, where a wheel pans
+ * the layout and a modifier-wheel zooms it. */
+export function resolveCanvasSceneWheel(view: RootPan, input: ReactCanvasWheelInput): RootPan {
+  const deltaY = deltaPixels(input.deltaY, input.deltaMode, input.bounds.height);
+  const zoom = Math.min(
+    SCENE_MAX_ZOOM,
+    Math.max(SCENE_MIN_ZOOM, view.zoom * Math.exp(-deltaY * ZOOM_SENSITIVITY)),
+  );
+  const pointerX = input.clientX - input.bounds.left;
+  const pointerY = input.clientY - input.bounds.top;
+  const worldX = (pointerX - view.x) / view.zoom;
+  const worldY = (pointerY - view.y) / view.zoom;
+  return {
+    x: pointerX - worldX * zoom,
+    y: pointerY - worldY * zoom,
+    zoom,
+  };
+}
+
+function isNavigationChrome(target: EventTarget | null): boolean {
+  return (
+    target instanceof Element &&
+    target.closest('[data-volter-canvas-navigation-ignore="true"]') !== null
+  );
+}
+
+/**
+ * Install viewport-sized navigation for a React design canvas. This stays on
+ * the untransformed document container, unlike authoring chrome that follows
+ * the world transform, so navigation remains available after fit/zoom.
+ */
+function installCanvasNavigation(
+  container: HTMLElement,
+  view: RootViewController,
+  resolveWheel: (view: RootPan, input: ReactCanvasWheelInput) => RootPan,
+  options: { readonly rightDragPans?: boolean } = {},
+): () => void {
+  let drag: {
+    readonly pointerId: number;
+    readonly button: 1 | 2;
+    readonly startClientX: number;
+    readonly startClientY: number;
+    readonly startPan: RootPan;
+    moved: boolean;
+  } | null = null;
+  let suppressNextContextMenu = false;
+  let previousInteractionCursor = '';
+
+  const interactionLayer = (): HTMLElement | null =>
+    container.querySelector<HTMLElement>('[data-testid="world-selection-overlay-interaction"]');
+
+  const setDraggingAppearance = (dragging: boolean): void => {
+    container.dataset['canvasPanning'] = dragging ? 'true' : 'false';
+    container.style.cursor = dragging ? 'grabbing' : '';
+    const interaction = interactionLayer();
+    if (!interaction) return;
+    if (dragging) {
+      previousInteractionCursor = interaction.style.cursor;
+      interaction.style.cursor = 'grabbing';
+    } else {
+      interaction.style.cursor = previousInteractionCursor;
+    }
+  };
+
+  const onPointerMove = (event: PointerEvent): void => {
+    if (!drag || event.pointerId !== drag.pointerId) return;
+    // PointerEvent's button mask is platform-independent: 4 is middle, 2 is
+    // secondary/right. Windows can drop pointerup around native auto-scroll
+    // or a window boundary, so stop as soon as the active bit disappears.
+    const pressedButtonMask = drag.button === 1 ? 4 : 2;
+    if ((event.buttons & pressedButtonMask) === 0) {
+      endDrag(event);
+      return;
+    }
+    const deltaX = event.clientX - drag.startClientX;
+    const deltaY = event.clientY - drag.startClientY;
+    if (!drag.moved) {
+      if (Math.hypot(deltaX, deltaY) <= SECONDARY_DRAG_THRESHOLD_PX) return;
+      drag.moved = true;
+      setDraggingAppearance(true);
+    }
+    view.setPan(drag.startPan.x + deltaX, drag.startPan.y + deltaY);
+  };
+
+  const endDrag = (event: PointerEvent): void => {
+    if (!drag || event.pointerId !== drag.pointerId) return;
+    const pointerId = drag.pointerId;
+    if (drag.button === 2 && drag.moved) suppressNextContextMenu = true;
+    drag = null;
+    setDraggingAppearance(false);
+    if (container.hasPointerCapture?.(pointerId)) container.releasePointerCapture(pointerId);
+    window.removeEventListener('pointermove', onPointerMove);
+    window.removeEventListener('pointerup', endDrag);
+    window.removeEventListener('pointercancel', endDrag);
+  };
+
+  const onPointerDown = (event: PointerEvent): void => {
+    const isMiddleButton = event.button === 1;
+    const isRightButton = options.rightDragPans === true && event.button === 2;
+    if ((!isMiddleButton && !isRightButton) || isNavigationChrome(event.target)) return;
+    if (isRightButton) suppressNextContextMenu = false;
+    event.preventDefault();
+    // A secondary press is shared with the selection overlay: navigation owns
+    // movement, while the overlay owns the stationary overlap menu. Let that
+    // one event continue so both can measure the same press; middle drag is
+    // unambiguous and remains navigation-only.
+    if (isMiddleButton) event.stopPropagation();
+    drag = {
+      pointerId: event.pointerId,
+      button: event.button as 1 | 2,
+      startClientX: event.clientX,
+      startClientY: event.clientY,
+      startPan: view.get(),
+      // Middle-drag is unambiguous and retains its immediate response. A
+      // secondary press waits for movement so a stationary secondary click
+      // remains the viewport's overlap/context menu.
+      moved: isMiddleButton,
+    };
+    // Pointer capture is the mouse-equivalent of a trackpad's uninterrupted
+    // gesture stream: middle-drag keeps panning across child frames and past
+    // the viewport edge, including on Windows where window-level move/up
+    // delivery is otherwise inconsistent around native auto-scroll.
+    container.setPointerCapture?.(event.pointerId);
+    setDraggingAppearance(isMiddleButton);
+    window.addEventListener('pointermove', onPointerMove);
+    window.addEventListener('pointerup', endDrag);
+    window.addEventListener('pointercancel', endDrag);
+  };
+
+  const onMouseDown = (event: MouseEvent): void => {
+    // Prevent Chromium's native middle-button auto-scroll glyph.
+    if (event.button === 1 && !isNavigationChrome(event.target)) event.preventDefault();
+  };
+
+  const onContextMenu = (event: MouseEvent): void => {
+    if (options.rightDragPans !== true) return;
+    const activeRightDrag = drag?.button === 2 && drag.moved;
+    if (!activeRightDrag && !suppressNextContextMenu) return;
+    suppressNextContextMenu = false;
+    event.preventDefault();
+    event.stopPropagation();
+  };
+
+  const onWheel = (event: WheelEvent): void => {
+    if (isNavigationChrome(event.target)) return;
+    event.preventDefault();
+    event.stopPropagation();
+    const next = resolveWheel(view.get(), {
+      clientX: event.clientX,
+      clientY: event.clientY,
+      deltaX: event.deltaX,
+      deltaY: event.deltaY,
+      deltaMode: event.deltaMode,
+      ctrlKey: event.ctrlKey,
+      metaKey: event.metaKey,
+      shiftKey: event.shiftKey,
+      bounds: container.getBoundingClientRect(),
+    });
+    view.setView(next.x, next.y, next.zoom);
+  };
+
+  container.addEventListener('pointerdown', onPointerDown, true);
+  container.addEventListener('lostpointercapture', endDrag, true);
+  container.addEventListener('mousedown', onMouseDown, true);
+  container.addEventListener('contextmenu', onContextMenu, true);
+  container.addEventListener('wheel', onWheel, { capture: true, passive: false });
+  return () => {
+    drag = null;
+    setDraggingAppearance(false);
+    container.removeEventListener('pointerdown', onPointerDown, true);
+    container.removeEventListener('lostpointercapture', endDrag, true);
+    container.removeEventListener('mousedown', onMouseDown, true);
+    container.removeEventListener('contextmenu', onContextMenu, true);
+    container.removeEventListener('wheel', onWheel, true);
+    window.removeEventListener('pointermove', onPointerMove);
+    window.removeEventListener('pointerup', endDrag);
+    window.removeEventListener('pointercancel', endDrag);
+  };
+}
+
+/** Component-board navigation: wheel pans; modifier-wheel zooms. */
+export function installReactCanvasNavigation(
+  container: HTMLElement,
+  view: RootViewController = sharedRootViewController,
+): () => void {
+  return installCanvasNavigation(container, view, resolveReactCanvasWheel);
+}
+
+/** Native 2D Scene navigation: wheel zooms; middle/right/Space drag pans. */
+export function installCanvasSceneNavigation(
+  container: HTMLElement,
+  view: RootViewController,
+): () => void {
+  return installCanvasNavigation(container, view, resolveCanvasSceneWheel, {
+    rightDragPans: true,
+  });
+}

package/src/kit/authoring/react-design-canvas-style.ts

@@ -0,0 +1,20 @@
+/**
+ * React design documents deliberately use an opaque, theme-independent canvas.
+ * Glass theme surface tokens are translucent and would let the chrome's
+ * backdrop frost turn the fine dot grid into a pale blur. These literals describe the
+ * semantic preview media itself, like an alpha checkerboard, rather than editor
+ * chrome colors.
+ */
+export const REACT_DESIGN_CANVAS_COLOR = '#191c22';
+export const REACT_DESIGN_CANVAS_DOT = 'rgba(255, 255, 255, 0.2)';
+export const REACT_STORY_TRANSPARENCY_BASE = '#20242a';
+export const REACT_STORY_TRANSPARENCY_TILE = '#2d323a';
+
+export function reactStoryTransparencyBackground(): string {
+  return (
+    `linear-gradient(45deg, ${REACT_STORY_TRANSPARENCY_TILE} 25%, transparent 25%, ` +
+    `transparent 75%, ${REACT_STORY_TRANSPARENCY_TILE} 75%), ` +
+    `linear-gradient(45deg, ${REACT_STORY_TRANSPARENCY_TILE} 25%, transparent 25%, ` +
+    `transparent 75%, ${REACT_STORY_TRANSPARENCY_TILE} 75%)`
+  );
+}