@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/native-selection-style.ts

@@ -0,0 +1,497 @@
+/**
+ * Theme-backed renderer selection ink shared by the native Three and Pixi
+ * views. CSS can consume `var(--volter-accent)` directly; WebGL cannot, so this
+ * module resolves the inherited token to the integer both renderers speak.
+ */
+
+import { useMemo, useSyncExternalStore } from 'react';
+import { EDITOR_THEME_CLASS, graphiteDarkEditorTheme, STAGE_WORD_MODES } from '@volter/sdk/widgets';
+
+/** Import/SSR fallback: Graphite Dark's canonical blue accent. */
+export const DEFAULT_NATIVE_SELECTION_COLOR = 0x579eff;
+
+export interface NativeSelectionColors {
+  readonly visible: number;
+  readonly hidden: number;
+  /** The ACTIVE object's outline (`color.viewport.active`, Blender's lighter orange), or the
+   *  selection's own when the palette names none. */
+  readonly active?: { readonly visible: number; readonly hidden: number };
+  /** THE OUTLINE'S FORM (`stage.outlineStyle`, `outlineWidth`, `outlineHidden`):
+   *  `soft`, the editor's own blurred halo, or `crisp` at a width in device pixels; and whether
+   *  the parts other objects hide are drawn too. Absent is the editor's own. */
+  readonly outline?: { readonly style: 'soft' | 'crisp'; readonly width: number | null; readonly hidden: boolean };
+}
+
+function rgbHex(red: number, green: number, blue: number): number {
+  return (red << 16) | (green << 8) | blue;
+}
+
+function parseNormalizedColor(value: string): number | null {
+  const hex = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(value.trim())?.[1];
+  if (hex) {
+    const opaque = hex.length === 3 ? [...hex].map((digit) => `${digit}${digit}`).join('') : hex;
+    return Number.parseInt(opaque.slice(0, 6), 16);
+  }
+  const rgb =
+    /^rgba?\(\s*(\d+(?:\.\d+)?)\s*(?:,\s*|\s+)(\d+(?:\.\d+)?)\s*(?:,\s*|\s+)(\d+(?:\.\d+)?)/i.exec(
+      value.trim(),
+    );
+  if (!rgb) return null;
+  const channels = rgb.slice(1, 4).map((channel) => Math.round(Number(channel)));
+  if (channels.some((channel) => channel < 0 || channel > 255)) return null;
+  return rgbHex(channels[0]!, channels[1]!, channels[2]!);
+}
+
+/** Normalize any browser-valid CSS color (custom palettes may use HSL/names). */
+function parseCssColor(value: string): number | null {
+  const direct = parseNormalizedColor(value);
+  if (direct !== null || typeof document === 'undefined') return direct;
+  if (typeof CSS !== 'undefined' && !CSS.supports('color', value)) return null;
+  const context = document.createElement('canvas').getContext('2d');
+  if (!context) return null;
+  context.fillStyle = '#010203';
+  context.fillStyle = value;
+  return parseNormalizedColor(String(context.fillStyle));
+}
+
+function themeRoot(element?: Element | null): Element | null {
+  if (typeof document === 'undefined') return null;
+  return (
+    element?.closest(`.${EDITOR_THEME_CLASS}`) ?? document.querySelector(`.${EDITOR_THEME_CLASS}`)
+  );
+}
+
+function dimColor(color: number): number {
+  const red = Math.round(((color >> 16) & 0xff) * 0.42);
+  const green = Math.round(((color >> 8) & 0xff) * 0.42);
+  const blue = Math.round((color & 0xff) * 0.42);
+  return rgbHex(red, green, blue);
+}
+
+/** Current palette accent, with a same-hue dim variant for occluded 3D edges. */
+function themeToken(root: Element | null, name: string): string {
+  return root && typeof getComputedStyle !== 'undefined'
+    ? getComputedStyle(root).getPropertyValue(name).trim()
+    : '';
+}
+
+/**
+ * THE STAGE'S COLOURS ARE THE WORKBENCH'S FIRST. Under the Code-OSS frame each is a theme
+ * colour (`volter.viewport.*`, `volter.gizmo.*`, the frame's `volterColors.ts`) the look sets and a
+ * person's `workbench.colorCustomizations` override, emitted as `--vscode-<id>` with dots as
+ * dashes; the page's own token is what the look said, read where there is no workbench.
+ */
+const WORKBENCH_COLOR: Readonly<Record<string, string>> = {
+  '--volter-viewport-background': '--vscode-volter-viewport-background',
+  '--volter-viewport-grid': '--vscode-volter-viewport-grid',
+  '--volter-viewport-axis-x': '--vscode-volter-viewport-axisX',
+  '--volter-viewport-axis-y': '--vscode-volter-viewport-axisY',
+  '--volter-viewport-axis-z': '--vscode-volter-viewport-axisZ',
+  '--volter-viewport-selection': '--vscode-volter-viewport-selection',
+  '--volter-viewport-active': '--vscode-volter-viewport-active',
+  '--volter-viewport-wire': '--vscode-volter-viewport-wire',
+  '--volter-gizmo-x': '--vscode-volter-gizmo-x',
+  '--volter-gizmo-y': '--vscode-volter-gizmo-y',
+  '--volter-gizmo-z': '--vscode-volter-gizmo-z',
+  '--volter-gizmo-navigation-x': '--vscode-volter-gizmo-navigationX',
+  '--volter-gizmo-navigation-y': '--vscode-volter-gizmo-navigationY',
+  '--volter-gizmo-navigation-z': '--vscode-volter-gizmo-navigationZ',
+  '--volter-gizmo-hover': '--vscode-volter-gizmo-hover',
+  '--volter-gizmo-drag': '--vscode-volter-gizmo-drag',
+};
+
+function stageColorToken(root: Element | null, name: string): string {
+  const workbench = WORKBENCH_COLOR[name];
+  return (workbench ? themeToken(root, workbench) : '') || themeToken(root, name);
+}
+
+/** The palette's selection colour: its viewport group's when it carries one
+ *  (Blender's orange), the accent otherwise. */
+export function nativeSelectionColors(element?: Element | null): NativeSelectionColors {
+  const root = themeRoot(element);
+  const raw = stageColorToken(root, '--volter-viewport-selection') || themeToken(root, '--volter-accent');
+  const visible =
+    parseCssColor(raw || graphiteDarkEditorTheme.color.accent.default) ??
+    DEFAULT_NATIVE_SELECTION_COLOR;
+  const active = parseCssColor(stageColorToken(root, '--volter-viewport-active'));
+  const style = themeToken(root, '--volter-viewport-outline-style');
+  const width = Number.parseFloat(themeToken(root, '--volter-viewport-outline-width'));
+  const hidden = themeToken(root, '--volter-viewport-outline-hidden');
+  return {
+    visible,
+    hidden: dimColor(visible),
+    ...(active === null ? {} : { active: { visible: active, hidden: dimColor(active) } }),
+    ...(style === '' && hidden === '' && !Number.isFinite(width)
+      ? {}
+      : {
+          outline: {
+            style: style === 'crisp' ? 'crisp' : 'soft',
+            width: Number.isFinite(width) && width > 0 ? width : null,
+            hidden: hidden !== 'false',
+          },
+        }),
+  };
+}
+
+/** The palette's VIEWPORT GROUP (`EditorTheme.color.viewport`), each member
+ *  `null` when the palette carries none — the viewport keeps its own then. */
+export interface NativeViewportLook {
+  readonly background: number | null;
+  readonly grid: number | null;
+  readonly axisX: number | null;
+  readonly axisY: number | null;
+  readonly axisZ: number | null;
+  /** `stage.axisLineWidth`, device px, or `null` for the editor's own. */
+  readonly axisLineWidth: number | null;
+  readonly active: number | null;
+}
+
+/**
+ * Whether the ACTIVE LOOK declares a `color.viewport` group at all — the
+ * question "is the backdrop the look's, or the editor's own?"
+ * (ARCHITECTURE-CORE §A model is data: a data subject opens in an isolation
+ * scene whose story is the studio, and the studio's backdrop is the editor's;
+ * a look that paints the viewport itself — Blender's flat grey — has already
+ * answered, and the studio must not paint over it).
+ *
+ * `background` alone is the whole test because the group is ALL-OR-NOTHING:
+ * `EditorTheme.color.viewport` makes every member required, and a palette
+ * DOCUMENT that carries a partial group is rejected by name at parse
+ * (`theme-library.ts`'s viewport reconstruction). So the group is present
+ * exactly when this token paints.
+ */
+export function lookDeclaresViewportColors(element?: Element | null): boolean {
+  return nativeViewportLook(element).background !== null;
+}
+
+/** Whether the look paints its viewport LIGHT (relative luminance above one half). The ink that
+ *  reads over a declared viewport is the palette's `content.onAccent` on a dark one (Blender's
+ *  white over its grey) and its ordinary `content.primary` on a light one (ink over
+ *  paper), where the on-accent ink is the same colour as the ground. */
+export function lookPaintsLightViewport(element?: Element | null): boolean {
+  const background = nativeViewportLook(element).background;
+  if (background === null) return false;
+  const r = (background >> 16) & 0xff, g = (background >> 8) & 0xff, b = background & 0xff;
+  return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255 > 0.5;
+}
+
+export function nativeViewportLook(element?: Element | null): NativeViewportLook {
+  const root = themeRoot(element);
+  const read = (name: string): number | null => {
+    const raw = stageColorToken(root, name);
+    return raw ? parseCssColor(raw) : null;
+  };
+  return {
+    background: read('--volter-viewport-background'),
+    grid: read('--volter-viewport-grid'),
+    axisX: read('--volter-viewport-axis-x'),
+    axisY: read('--volter-viewport-axis-y'),
+    axisZ: read('--volter-viewport-axis-z'),
+    axisLineWidth: (() => {
+      const raw = themeToken(root, '--volter-viewport-axis-line-width');
+      const value = raw ? Number.parseFloat(raw) : Number.NaN;
+      return Number.isFinite(value) ? value : null;
+    })(),
+    active: read('--volter-viewport-active'),
+  };
+}
+
+/** THE LOOK'S GIZMO COLOURS AND HIGHLIGHT (`EditorTheme.color.gizmo`, and
+ *  `stage.gizmoOpacity`/`gizmoHighlightSaturation`/`gizmoHighlightValue`), each
+ *  `null` when the look names none — the viewport keeps its own then. `axes` are X, Y, Z. */
+export interface NativeGizmoLook {
+  readonly axes: readonly [number, number, number] | null;
+  /** The navigation gizmo's own X, Y, Z, or `null` to draw it in {@link axes}. */
+  readonly navigation: readonly [number, number, number] | null;
+  readonly hover: number | null;
+  readonly drag: number | null;
+  readonly opacity: number | null;
+  readonly arrowLength: number | null;
+  readonly arrowHead: number | null;
+  readonly ringWidth: number | null;
+  readonly navigationForm: 'balls' | 'godot' | 'cones' | 'triad';
+  /** The viewport's background, which the ball form mixes its colours toward by depth. */
+  readonly background: number | null;
+  readonly navigationSize: number | null;
+  readonly navigationCorner: 'top-right' | 'bottom-left';
+  readonly highlightSaturation: number | null;
+  readonly highlightValue: number | null;
+}
+
+export function nativeGizmoLook(element?: Element | null): NativeGizmoLook {
+  const root = themeRoot(element);
+  const color = (name: string): number | null => {
+    const raw = stageColorToken(root, name);
+    return raw ? parseCssColor(raw) : null;
+  };
+  const number = (name: string): number | null => {
+    const raw = themeToken(root, name);
+    if (!raw) return null;
+    const value = Number.parseFloat(raw);
+    return Number.isFinite(value) ? value : null;
+  };
+  const trio = (prefix: string): readonly [number, number, number] | null => {
+    const x = color(`${prefix}-x`);
+    const y = color(`${prefix}-y`);
+    const z = color(`${prefix}-z`);
+    return x !== null && y !== null && z !== null ? [x, y, z] : null;
+  };
+  return {
+    axes: trio('--volter-gizmo'),
+    navigation: trio('--volter-gizmo-navigation'),
+    hover: color('--volter-gizmo-hover'),
+    drag: color('--volter-gizmo-drag'),
+    opacity: number('--volter-viewport-gizmo-opacity'),
+    arrowLength: number('--volter-viewport-gizmo-arrow-length'),
+    arrowHead: number('--volter-viewport-gizmo-arrow-head'),
+    ringWidth: number('--volter-viewport-gizmo-ring-width'),
+    navigationSize: number('--volter-viewport-navigation-size'),
+    background: color('--volter-viewport-background'),
+    navigationForm: ((form) => (form === 'cones' || form === 'triad' || form === 'godot' ? form : 'balls'))(
+      themeToken(root, '--volter-viewport-navigation-gizmo'),
+    ),
+    navigationCorner:
+      themeToken(root, '--volter-viewport-navigation-corner') === 'bottom-left' ? 'bottom-left' : 'top-right',
+    highlightSaturation: number('--volter-viewport-gizmo-highlight-saturation'),
+    highlightValue: number('--volter-viewport-gizmo-highlight-value'),
+  };
+}
+
+/**
+ * THE LOOK'S TRANSFORM-GIZMO SIZE, in px per gizmo unit
+ * (`EditorTheme.stage.gizmoSize`), or `null` when the look names
+ * none — which is every look but Blender's, and means "keep three's own
+ * viewport-relative handle".
+ *
+ * Read off the emitted token for the same reason the colours above are: WebGL
+ * cannot consume a CSS variable, and the theme object reaching the viewport
+ * would be a second source for a value the stylesheet already carries.
+ * `editor-viewport.ts` is the one caller and it says what it does with the
+ * number; nothing here knows about three's units.
+ */
+export function nativeViewportGizmoSize(element?: Element | null): number | null {
+  const raw = themeToken(themeRoot(element), '--volter-viewport-gizmo-size');
+  if (!raw) return null;
+  const value = Number.parseFloat(raw);
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+
+/** THE BOX-SELECT OUTLINE'S DASH the look states (`EditorTheme.stage.marqueeDash`), in device
+ *  pixels, or `null` for the editor's own solid line. Its colours need no reader: the rectangle
+ *  is DOM, so it paints `themeVars.viewport.marquee*` directly. */
+export function nativeViewportMarqueeDash(element?: Element | null): number | null {
+  const value = Number.parseFloat(themeToken(themeRoot(element), '--volter-viewport-marquee-dash'));
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+
+/** THE FLOOR GRID'S LINES the look states (`EditorTheme.stage.gridLineWidth` and
+ *  its siblings), in device pixels, with the editor's own hairline floor for any it leaves out:
+ *  one level, one pixel, the major lines drawn like the minor. */
+export function nativeViewportGrid(element?: Element | null): {
+  readonly lineWidth: number;
+  readonly majorWidth: number;
+  readonly majorContrast: number;
+} {
+  const root = themeRoot(element);
+  const read = (name: string, fallback: number): number => {
+    const value = Number.parseFloat(themeToken(root, name) ?? '');
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+  };
+  const lineWidth = read('--volter-viewport-grid-line-width', 1);
+  return {
+    lineWidth,
+    majorWidth: read('--volter-viewport-grid-major-width', lineWidth),
+    majorContrast: read('--volter-viewport-grid-major-contrast', 1),
+  };
+}
+
+/** HOW THE LOOK DRAWS THE SELECTION BOX MARK (`stage.selectionBox` and its width),
+ *  with the editor's own corner brackets at 3 CSS px for what it leaves out. */
+/** The selection wire's look: the palette's `viewport.wire` and `stage.wireOpacity`,
+ *  each `null` for the editor's own (the selection colour at half opacity). */
+export function nativeViewportWire(element?: Element | null): {
+  readonly color: number | null;
+  readonly opacity: number | null;
+} {
+  const root = themeRoot(element);
+  const raw = stageColorToken(root, '--volter-viewport-wire');
+  const opacity = Number.parseFloat(themeToken(root, '--volter-viewport-wire-opacity'));
+  return {
+    color: raw ? parseCssColor(raw) : null,
+    opacity: Number.isFinite(opacity) ? opacity : null,
+  };
+}
+
+export function nativeViewportSelectionBox(element?: Element | null): {
+  readonly edges: boolean;
+  readonly lineWidth: number | null;
+  readonly frame: 'world' | 'object';
+} {
+  const root = themeRoot(element);
+  const width = Number.parseFloat(themeToken(root, '--volter-viewport-selection-box-width'));
+  return {
+    edges: themeToken(root, '--volter-viewport-selection-box') === 'edges',
+    frame: themeToken(root, '--volter-viewport-selection-box-frame') === 'object' ? 'object' : 'world',
+    lineWidth: Number.isFinite(width) && width > 0 ? width : null,
+  };
+}
+
+/** THE STAGE'S OWN CHROME as the look places it (`StageContribution.chrome`), each member
+ *  resolved to the editor's own arrangement where the look states none. */
+export interface NativeViewportChrome {
+  readonly bar: 'none' | 'strip' | 'pills';
+  readonly viewName: 'text' | 'menu' | 'gizmo' | 'bar';
+  readonly tools: 'shelf' | 'bar-start' | 'bar-end';
+  readonly display: 'corner' | 'bar-start' | 'bar-end';
+  readonly transformControls: 'header' | 'bar';
+}
+
+/** The chrome's members as one string, a stable snapshot for `useSyncExternalStore`
+ *  ({@link viewportChromeFromKey} reads it back). */
+export function nativeViewportChromeKey(element?: Element | null): string {
+  const root = themeRoot(element);
+  return [
+    '--volter-viewport-chrome-bar',
+    '--volter-viewport-chrome-view-name',
+    '--volter-viewport-chrome-tools',
+    '--volter-viewport-chrome-display',
+    '--volter-viewport-chrome-transform-controls',
+  ]
+    .map((name) => themeToken(root, name))
+    .join('|');
+}
+
+export function viewportChromeFromKey(key: string): NativeViewportChrome {
+  const [bar, viewName, tools, display, transformControls] = key.split('|');
+  const bars = ['strip', 'pills'] as const;
+  const names = ['menu', 'gizmo', 'bar'] as const;
+  const places = ['bar-start', 'bar-end'] as const;
+  const pick = <T extends string>(value: string | undefined, members: readonly T[], fallback: T): T =>
+    members.includes(value as T) ? (value as T) : fallback;
+  return {
+    bar: pick(bar, bars, 'none'),
+    viewName: pick(viewName, names, 'text'),
+    tools: pick(tools, places, 'shelf'),
+    display: pick(display, places, 'corner'),
+    transformControls: transformControls === 'bar' ? 'bar' : 'header',
+  };
+}
+
+export function nativeViewportChrome(element?: Element | null): NativeViewportChrome {
+  return viewportChromeFromKey(nativeViewportChromeKey(element));
+}
+
+/** The key, read from the theme only when the theme changes: a stage's furniture re-renders on
+ *  every camera move, and the tokens are computed style. */
+let chromeKey: string | null = null;
+function subscribeViewportChrome(listener: () => void): () => void {
+  return subscribeNativeSelectionTheme(null, () => {
+    chromeKey = nativeViewportChromeKey();
+    listener();
+  });
+}
+function viewportChromeSnapshot(): string {
+  chromeKey ??= nativeViewportChromeKey();
+  return chromeKey;
+}
+
+/** THE STAGE'S CONTROLS IN THE TARGET'S WORDS (`StageContribution.words`): a mode's name, or
+ *  the helpers menu's, where the look names it; `undefined` keeps the editor's own. */
+export interface NativeViewportWords {
+  readonly shading: Readonly<Partial<Record<string, string>>>;
+  readonly helpers: string | undefined;
+}
+let wordsKey: string | null = null;
+function viewportWordsKeyNow(): string {
+  const root = themeRoot();
+  return JSON.stringify([
+    STAGE_WORD_MODES.map((mode) => themeToken(root, `--volter-viewport-word-${mode}`)),
+    themeToken(root, '--volter-viewport-word-helpers'),
+  ]);
+}
+function subscribeViewportWords(listener: () => void): () => void {
+  return subscribeNativeSelectionTheme(null, () => {
+    wordsKey = viewportWordsKeyNow();
+    listener();
+  });
+}
+function viewportWordsSnapshot(): string {
+  wordsKey ??= viewportWordsKeyNow();
+  return wordsKey;
+}
+/** The look's words for the stage's controls, following a change of look. */
+export function useViewportWords(): NativeViewportWords {
+  const key = useSyncExternalStore(subscribeViewportWords, viewportWordsSnapshot, viewportWordsSnapshot);
+  return useMemo(() => {
+    const [modes, helpers] = JSON.parse(key) as [string[], string];
+    const shading: Record<string, string> = {};
+    STAGE_WORD_MODES.forEach((mode, index) => {
+      if (modes[index]) shading[mode] = modes[index];
+    });
+    return { shading, helpers: helpers || undefined };
+  }, [key]);
+}
+
+/** The look's stage chrome, following a change of look. */
+export function useViewportChrome(): NativeViewportChrome {
+  const key = useSyncExternalStore(subscribeViewportChrome, viewportChromeSnapshot, viewportChromeSnapshot);
+  return useMemo(() => viewportChromeFromKey(key), [key]);
+}
+
+/**
+ * Observe the one theme root's inline token update. This includes saved theme
+ * changes and unsaved Theme Manager previews; neither renderer has to poll
+ * `getComputedStyle` on every frame.
+ */
+export function subscribeNativeSelectionTheme(
+  element: Element | null | undefined,
+  listener: () => void,
+): () => void {
+  listener();
+  const root = themeRoot(element);
+  if (!root || typeof MutationObserver === 'undefined') return () => {};
+  const observer = new MutationObserver(listener);
+  observer.observe(root, { attributes: true, attributeFilter: ['style'] });
+  // AND THE WORKBENCH'S COLOURS, which the frame applies after the look's own tokens land and a
+  // person's customizations change without touching this root (`subscribeWorkbenchStageColors`).
+  const stopWorkbench = subscribeWorkbenchStageColors(root, listener);
+  return () => {
+    observer.disconnect();
+    stopWorkbench();
+  };
+}
+
+/**
+ * THE WORKBENCH'S STAGE COLOURS, watched once for every subscriber: Code-OSS writes them into a
+ * stylesheet in the document head, which changes for many other reasons (every stylesheet a
+ * module loads), so one observer reads the stage's colours once per change and wakes the
+ * subscribers only when they moved.
+ */
+const workbenchListeners = new Set<() => void>();
+let workbenchObserver: MutationObserver | null = null;
+let workbenchSeen = '';
+
+function subscribeWorkbenchStageColors(root: Element, listener: () => void): () => void {
+  const signature = () =>
+    Object.values(WORKBENCH_COLOR)
+      .map((name) => themeToken(root, name))
+      .join('|');
+  workbenchListeners.add(listener);
+  if (!workbenchObserver && typeof document !== 'undefined' && document.head) {
+    workbenchSeen = signature();
+    workbenchObserver = new MutationObserver(() => {
+      const next = signature();
+      if (next === workbenchSeen) return;
+      workbenchSeen = next;
+      for (const each of [...workbenchListeners]) each();
+    });
+    workbenchObserver.observe(document.head, { childList: true, subtree: true, characterData: true });
+  }
+  return () => {
+    workbenchListeners.delete(listener);
+    if (workbenchListeners.size === 0 && workbenchObserver) {
+      workbenchObserver.disconnect();
+      workbenchObserver = null;
+    }
+  };
+}

package/src/kit/object3d-document-write-policy.ts

@@ -0,0 +1,137 @@
+/**
+ * WHAT THE ASSET LAB 3D DOCUMENT ASKS THE SHELL — the one collaborator
+ * `StageHost.tsx` (with its toolbar) declares and the shell
+ * installs at boot.
+ *
+ * ARCHITECTURE-CORE §Editor chrome, "The viewport stack is separable": a
+ * surface below the shell never imports the shell's transport, a world
+ * authoring adapter, or project discovery. The 3D document was importing four
+ * modules to answer three questions —
+ *
+ *   · where do this document's own bytes go? (`object3d-document-persistence`
+ *     → project file history → the resource history backend)
+ *   · how do I replace a whole SOURCE file? (`ui-source/tier-source-write-backend`
+ *     for the tier's recorder + `history/source-history-backend` to run it)
+ *   · where does a thumbnail framing get recorded? (`asset-workflow/thumbnail-system`
+ *     to read `.volter/thumbnails.json` + `components/asset-editor-persistence`
+ *     to write it, which reaches `editor-api.ts`)
+ *
+ * — and every one of those is TRANSPORT. Measured, those edges were 72 of the
+ * document's 213 files, all of them behind the server SDK barrel; the document
+ * itself only ever needed "hand these bytes to the project and tell me whether
+ * one moved".
+ *
+ * ## The default is the NO-SHELL answer, and it is deliberate
+ *
+ * {@link DEFAULT_OBJECT3D_DOCUMENT_WRITE_POLICY} is what a document mounted
+ * with no shell above it (a bounded host; a fixture) gets: there is no
+ * project to write to, so each member REFUSES by name rather than
+ * half-answering. Every call site here already renders a refusal — the
+ * document's error state, the toolbar's error banner — because the same
+ * refusal is what a read-only tier produced before this seam existed
+ * ("This editor tier cannot write project source").
+ *
+ * In the editor the shell policy is installed once by `EditorProvider`
+ * (`EditorContext.tsx`), beside the viewport policy and before any document
+ * mounts, so today's behaviour is unchanged.
+ */
+
+import type {
+  Object3DDocumentPersistenceSession,
+  OpenObject3DDocumentPersistenceOptions,
+} from './authoring/object3d-document-persistence';
+import type { HistoryService } from '@volter/sdk/kit/history/history-service';
+
+/** Re-exported from its declaration site so a consumer of this seam does not
+ *  import the persistence module (which reaches project file history) for a
+ *  type. `import type` is erased, so this costs the closure nothing. */
+export type { Object3DDocumentPersistenceSession } from './authoring/object3d-document-persistence';
+
+/** A whole-file SOURCE replacement — the document's animation binding and its
+ *  single-module documents both write this way. */
+export interface Object3DDocumentSourceReplacement {
+  readonly file: string;
+  readonly source: string;
+  readonly label: string;
+}
+
+/** The camera framing `.volter/thumbnails.json` records for one asset.
+ *  `undefined` is the RESET — remove this asset's framing. */
+export interface Object3DDocumentThumbnailFraming {
+  readonly position: [number, number, number];
+  readonly target: [number, number, number];
+  readonly fov?: number;
+}
+
+export interface Object3DDocumentWritePolicy {
+  /**
+   * Open the persistence baseline for a document that declares a binding.
+   * The session owns transaction ordering, checksum preflight and canonical
+   * undo/redo; the document only calls `commit`.
+   */
+  openPersistence<TDocument>(
+    options: OpenObject3DDocumentPersistenceOptions<TDocument>,
+  ): Promise<Object3DDocumentPersistenceSession<TDocument>>;
+  /**
+   * Replace a whole source file through the tier's recorder, in `history`.
+   * Resolves to whether a byte actually moved. The HISTORY lookup stays with
+   * the document (it holds the session's service already, and its two call
+   * sites word an absent one differently); what the shell owns here is the
+   * WRITE BACKEND — the thing a read-only tier does not have.
+   */
+  replaceSource(
+    history: HistoryService,
+    request: Object3DDocumentSourceReplacement,
+  ): Promise<boolean>;
+  /**
+   * Record (or clear, with `undefined`) this asset's thumbnail framing in the
+   * project's thumbnail manifest. Refuses loudly rather than rebuilding a
+   * manifest it could not read.
+   */
+  saveThumbnailFraming(
+    assetPath: string,
+    framing: Object3DDocumentThumbnailFraming | undefined,
+  ): Promise<void>;
+}
+
+/** The one refusal, worded for the member that raised it. Rejected rather than
+ *  thrown so every member answers the same way; each call site is already
+ *  inside the `await` of a try/catch that renders the message. */
+function refuse<T>(what: string): Promise<T> {
+  return Promise.reject(new Error(`This editor tier cannot ${what}.`));
+}
+
+export const DEFAULT_OBJECT3D_DOCUMENT_WRITE_POLICY: Object3DDocumentWritePolicy = {
+  openPersistence: () => refuse('persist Asset Lab documents'),
+  // The exact wording a read-only tier produced when the document asked the
+  // tier recorder for a source-write backend and got none.
+  replaceSource: () => refuse('write project source'),
+  saveThumbnailFraming: () => refuse('write project thumbnail framing'),
+};
+
+let _policy: Object3DDocumentWritePolicy = DEFAULT_OBJECT3D_DOCUMENT_WRITE_POLICY;
+
+/**
+ * Install the shell's composition. One owner, same rule as
+ * `installViewportAuthoringPolicy` and the store's `attachHistory`:
+ * re-installing the SAME policy is a no-op (React strict-mode double-invokes
+ * the provider body), a DIFFERENT one throws rather than letting two shells
+ * disagree about where a document's bytes go.
+ */
+export function installObject3DDocumentWritePolicy(policy: Object3DDocumentWritePolicy): void {
+  if (_policy === policy) return;
+  if (_policy !== DEFAULT_OBJECT3D_DOCUMENT_WRITE_POLICY) {
+    throw new Error('An Object3D document write policy is already installed.');
+  }
+  _policy = policy;
+}
+
+/** The installed policy, or the no-shell default. */
+export function object3DDocumentWritePolicy(): Object3DDocumentWritePolicy {
+  return _policy;
+}
+
+/** Test seam: drop the installed policy. */
+export function __resetObject3DDocumentWritePolicyForTest(): void {
+  _policy = DEFAULT_OBJECT3D_DOCUMENT_WRITE_POLICY;
+}