@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/components/asset-viewers/shader-source.ts

@@ -0,0 +1,144 @@
+/** Native GLSL document helpers. GLSL remains the artifact; these functions
+ * only describe it for Asset Lab and never serialize a Volter shader shape. */
+
+export type ShaderStage = 'vertex' | 'fragment';
+
+export interface ShaderUniformDescriptor {
+  readonly name: string;
+  readonly type: string;
+  readonly arraySize?: number | undefined;
+  readonly stages: readonly ShaderStage[];
+}
+
+export interface ShaderDiagnostic {
+  readonly stage: ShaderStage | 'program';
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+  readonly line?: number | undefined;
+  readonly column?: number | undefined;
+}
+
+const VERTEX_SUFFIXES = ['.vert', '.vert.glsl'] as const;
+const FRAGMENT_SUFFIXES = ['.frag', '.frag.glsl'] as const;
+
+function cleanPath(path: string): string {
+  return path.split(/[?#]/, 1)[0]!.toLowerCase();
+}
+
+export function shaderStageFromPath(path: string, source = ''): ShaderStage {
+  const clean = cleanPath(path);
+  if (VERTEX_SUFFIXES.some((suffix) => clean.endsWith(suffix))) return 'vertex';
+  if (FRAGMENT_SUFFIXES.some((suffix) => clean.endsWith(suffix))) return 'fragment';
+  return /\bgl_Position\b/.test(source) ? 'vertex' : 'fragment';
+}
+
+/** Conventional sibling only. A standalone `.glsl` file stays standalone. */
+export function shaderCompanionPath(path: string): string | null {
+  const clean = path.split(/[?#]/, 1)[0]!;
+  if (/\.vert\.glsl$/i.test(clean)) return clean.replace(/\.vert\.glsl$/i, '.frag.glsl');
+  if (/\.frag\.glsl$/i.test(clean)) return clean.replace(/\.frag\.glsl$/i, '.vert.glsl');
+  if (/\.vert$/i.test(clean)) return clean.replace(/\.vert$/i, '.frag');
+  if (/\.frag$/i.test(clean)) return clean.replace(/\.frag$/i, '.vert');
+  return null;
+}
+
+function withoutComments(source: string): string {
+  // Preserve newlines so reflection never perturbs source-line diagnostics.
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, (comment) => comment.replace(/[^\n]/g, ' '))
+    .replace(/\/\/[^\n]*/g, '');
+}
+
+function declarations(source: string, stage: ShaderStage): ShaderUniformDescriptor[] {
+  const result: ShaderUniformDescriptor[] = [];
+  const pattern =
+    /\buniform\s+(?:(?:lowp|mediump|highp)\s+)?([A-Za-z_]\w*)\s+([A-Za-z_]\w*)\s*(?:\[\s*(\d+)\s*\])?\s*;/g;
+  for (const match of withoutComments(source).matchAll(pattern)) {
+    const type = match[1];
+    const name = match[2];
+    if (!type || !name) continue;
+    const arraySize = match[3] ? Number.parseInt(match[3], 10) : undefined;
+    result.push({ name, type, ...(arraySize ? { arraySize } : {}), stages: [stage] });
+  }
+  return result;
+}
+
+export function reflectShaderUniforms(
+  vertexSource: string,
+  fragmentSource: string,
+): ShaderUniformDescriptor[] {
+  const reflected = new Map<string, ShaderUniformDescriptor>();
+  for (const uniform of [
+    ...declarations(vertexSource, 'vertex'),
+    ...declarations(fragmentSource, 'fragment'),
+  ]) {
+    const current = reflected.get(uniform.name);
+    if (!current) {
+      reflected.set(uniform.name, uniform);
+      continue;
+    }
+    reflected.set(uniform.name, {
+      ...current,
+      stages: [...new Set([...current.stages, ...uniform.stages])],
+    });
+  }
+  return [...reflected.values()];
+}
+
+export function parseShaderDiagnostics(
+  log: string,
+  stage: ShaderDiagnostic['stage'],
+): ShaderDiagnostic[] {
+  const diagnostics = log
+    .split('\n')
+    .map((line) => parseDiagnosticLine(line.trim(), stage))
+    .filter((diagnostic): diagnostic is ShaderDiagnostic => diagnostic !== null);
+  if (diagnostics.length === 0 && log.trim()) {
+    diagnostics.push({ stage, severity: 'error', message: log.trim() });
+  }
+  return diagnostics;
+}
+
+function parseDiagnosticLine(
+  text: string,
+  stage: ShaderDiagnostic['stage'],
+): ShaderDiagnostic | null {
+  if (!text) return null;
+  const colon = text.match(/^(ERROR|WARNING):\s*\d+:(\d+)(?::|\((\d+)\):)\s*(.*)$/i);
+  if (colon) {
+    return {
+      stage,
+      severity: colon[1]!.toLowerCase() === 'warning' ? 'warning' : 'error',
+      line: Number.parseInt(colon[2]!, 10),
+      ...(colon[3] ? { column: Number.parseInt(colon[3], 10) } : {}),
+      message: colon[4] || text,
+    };
+  }
+  const paren = text.match(/^\d+:(\d+)\((\d+)\):\s*(?:(error|warning)\s*:?)?\s*(.*)$/i);
+  if (!paren) return null;
+  return {
+    stage,
+    severity: paren[3]?.toLowerCase() === 'warning' ? 'warning' : 'error',
+    line: Number.parseInt(paren[1]!, 10),
+    column: Number.parseInt(paren[2]!, 10),
+    message: paren[4] || text,
+  };
+}
+
+/** Reset driver-reported lines after Three's injected ShaderMaterial prefix. */
+export function previewShaderSource(source: string): string {
+  return `#line 1\n${source}`;
+}
+
+export const FALLBACK_VERTEX_SHADER = `varying vec2 vUv;
+
+void main() {
+  vUv = uv;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}`;
+
+export const FALLBACK_FRAGMENT_SHADER = `varying vec2 vUv;
+
+void main() {
+  gl_FragColor = vec4(vUv, 0.55, 1.0);
+}`;

package/src/kit/components/board-guides.ts

@@ -0,0 +1,150 @@
+/**
+ * PERSISTENT BOARD GUIDES (design ledger: snapping/guides — "persistent
+ * guides do not ship"). User-placed ruler guides on the DOM component board,
+ * in BOARD coordinates (the same space the frames are laid out in, so a
+ * guide stays put under pan/zoom).
+ *
+ * Persistence: per-project, per-document localStorage — the
+ * `device-preview.ts` idiom (keyed by `getCurrentProject().rootPath`; UI
+ * convenience, never project truth). A guide is a design AID: it has no
+ * rendered meaning in the game, so it must never be written into game
+ * source — the same reasoning that keeps the workspace layout and the device
+ * preset out of the project.
+ *
+ * The snap seam: `RootSelectionOverlay`'s gestures snap in HOST-relative
+ * space (a per-world frame inside the board), so the board registers its
+ * live transform here ({@link registerBoardGuideTransform}) and the overlay
+ * asks for guide edges in CLIENT space ({@link guideClientEdges}) to convert
+ * against its own host origin.
+ */
+
+import { getCurrentProject } from '../project-manager';
+
+export interface BoardGuide {
+  readonly id: string;
+  /** 'x' = vertical guide at a board X; 'y' = horizontal guide at a board Y. */
+  readonly axis: 'x' | 'y';
+  /** Board-space coordinate. */
+  readonly value: number;
+}
+
+const STORAGE_KEY = 'volter:board-guides:v1';
+
+type Stored = Record<string, Record<string, BoardGuide[]>>;
+
+function storage(): Storage | null {
+  return typeof window === 'undefined' ? null : window.localStorage;
+}
+
+function projectKey(): string {
+  try {
+    return getCurrentProject()?.rootPath ?? '(no-project)';
+  } catch {
+    return '(no-project)';
+  }
+}
+
+function readAll(): Stored {
+  try {
+    return JSON.parse(storage()?.getItem(STORAGE_KEY) ?? '{}') as Stored;
+  } catch {
+    return {};
+  }
+}
+
+function writeAll(all: Stored): void {
+  try {
+    storage()?.setItem(STORAGE_KEY, JSON.stringify(all));
+  } catch {
+    // Quota/denied — guides silently stay session-only; the next write retries.
+  }
+}
+
+const listeners = new Set<() => void>();
+let cache: Record<string, BoardGuide[]> | null = null;
+let nextId = Date.now() % 1_000_000;
+
+function docs(): Record<string, BoardGuide[]> {
+  if (!cache) cache = readAll()[projectKey()] ?? {};
+  return cache;
+}
+
+function persist(): void {
+  const all = readAll();
+  all[projectKey()] = docs();
+  writeAll(all);
+  for (const listener of listeners) listener();
+}
+
+const EMPTY_GUIDES: readonly BoardGuide[] = [];
+
+export function boardGuides(docId: string): readonly BoardGuide[] {
+  // Referentially stable for a guide-less document: this is a
+  // `useSyncExternalStore` snapshot, and a fresh `[]` per call is an
+  // infinite re-render (measured: it crashed the whole editor surface with
+  // "Maximum update depth exceeded" on first mount).
+  return docs()[docId] ?? EMPTY_GUIDES;
+}
+
+export function subscribeBoardGuides(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function addBoardGuide(docId: string, axis: BoardGuide['axis'], value: number): string {
+  nextId += 1;
+  const id = `guide-${nextId}`;
+  docs()[docId] = [...boardGuides(docId), { id, axis, value }];
+  persist();
+  return id;
+}
+
+export function moveBoardGuide(docId: string, id: string, value: number): void {
+  docs()[docId] = boardGuides(docId).map((g) => (g.id === id ? { ...g, value } : g));
+  persist();
+}
+
+export function removeBoardGuide(docId: string, id: string): void {
+  docs()[docId] = boardGuides(docId).filter((g) => g.id !== id);
+  persist();
+}
+
+// --- The live board transform, for the overlay's snap conversion ---
+
+export interface BoardGuideTransform {
+  /** The board container's client origin. */
+  readonly originX: number;
+  readonly originY: number;
+  /** The board pan/zoom (client = origin + pan + value * zoom). */
+  readonly panX: number;
+  readonly panY: number;
+  readonly zoom: number;
+}
+
+let activeTransform: { docId: string; transform: BoardGuideTransform } | null = null;
+
+/** The mounted board registers its transform (and clears it on unmount) so
+ *  guide coordinates can be answered in client space. One DOM board is
+ *  active at a time; a second registration simply replaces the first. */
+export function registerBoardGuideTransform(
+  docId: string,
+  transform: BoardGuideTransform | null,
+): void {
+  activeTransform = transform ? { docId, transform } : null;
+}
+
+/** Every guide of the registered board, as CLIENT-space edge coordinates —
+ *  what a gesture overlay converts against its own host origin. Empty when
+ *  no board is registered (nothing to snap to, honestly). */
+export function guideClientEdges(): { x: number[]; y: number[] } {
+  if (!activeTransform) return { x: [], y: [] };
+  const { docId, transform } = activeTransform;
+  const x: number[] = [];
+  const y: number[] = [];
+  for (const guide of boardGuides(docId)) {
+    if (guide.axis === 'x')
+      x.push(transform.originX + transform.panX + guide.value * transform.zoom);
+    else y.push(transform.originY + transform.panY + guide.value * transform.zoom);
+  }
+  return { x, y };
+}

package/src/kit/components/canvas-scene-hotkeys.ts

@@ -0,0 +1,37 @@
+/**
+ * A 2D view's keys, from the active keymap, while it is the active one: its transform tools (the
+ * three viewport binds the same actions for its own store, `viewport-hotkeys.ts`) and Godot's
+ * Pan and Ruler modes. Kept apart from the view so the workbench keymap generator, which reads
+ * every `bindActions([...])` call, hashes this small file rather than the whole view.
+ */
+
+import { editorHost } from '@volter/sdk/host';
+import type { ShellStore } from '@volter/sdk/kit/shell-store';
+import { requestTransformMode } from '@volter/sdk/kit/transform-mode-request';
+
+export type CanvasSceneKeyMode = 'pan' | 'ruler';
+
+export function bindCanvasSceneKeys(
+  store: ShellStore,
+  /** Leave any canvas mode (a transform tool's key leaves List Select, Pivot, Pan and Ruler, even
+   *  when its tool was the one already armed under them). */
+  clearMode: () => void,
+  /** Switch a canvas mode on, or off when it is the one on. */
+  toggleMode: (mode: CanvasSceneKeyMode) => void,
+  /** View › Grid › Toggle Grid. */
+  toggleGrid: () => void,
+): () => void {
+  const arm = (mode: 'select' | 'translate' | 'rotate' | 'scale') => () => {
+    clearMode();
+    requestTransformMode(store, mode);
+  };
+  return editorHost().keyboard.bindActions([
+    { id: 'transform.select', scope: 'stage', run: arm('select') },
+    { id: 'transform.translate', scope: 'stage', run: arm('translate') },
+    { id: 'transform.rotate', scope: 'stage', run: arm('rotate') },
+    { id: 'transform.scale', scope: 'stage', run: arm('scale') },
+    { id: 'canvas.panMode', scope: 'stage', run: () => toggleMode('pan') },
+    { id: 'canvas.rulerMode', scope: 'stage', run: () => toggleMode('ruler') },
+    { id: 'canvas.toggleGrid', scope: 'stage', run: toggleGrid },
+  ]);
+}

package/src/kit/components/canvas-temporary-pivot.ts

@@ -0,0 +1,34 @@
+/**
+ * Godot's TEMPORARY PIVOT on a 2D view: a point, in the view's world frame, that rotation turns
+ * the selection around without changing any node's own pivot. Pivot mode sets it with Shift+click
+ * (and Shift+click on the Pivot button puts it at the selection's centre); Escape in Pivot mode,
+ * or a new selection, clears it. One per view.
+ */
+
+import type { RootViewController } from '@volter/sdk/kit/world-pan-state';
+
+type Point = { readonly x: number; readonly y: number };
+
+const pivots = new WeakMap<RootViewController, Point>();
+const listeners = new Set<() => void>();
+let version = 0;
+
+export function temporaryPivot(view: RootViewController): Point | null {
+  return pivots.get(view) ?? null;
+}
+
+export function setTemporaryPivot(view: RootViewController, point: Point | null): void {
+  if (point) pivots.set(view, point);
+  else pivots.delete(view);
+  version += 1;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeTemporaryPivot(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function temporaryPivotVersion(): number {
+  return version;
+}

package/src/kit/components/core-utilities.tsx

@@ -0,0 +1,94 @@
+/**
+ * The editor's built-in DRAWER utilities, registered through the same
+ * W0 workspace-utility registry every other utility uses, so the utility
+ * region is registry-driven end to end:
+ *
+ *  - **Console** (B3): always available; its error/warn count becomes the
+ *    registry `badge()` in the open tab, plus the three standard level counts
+ *    in the status line while the drawer is hidden.
+ *    Ordinary log traffic never auto-opens the region; only actionable
+ *    failures reveal it automatically (today: a world that failed to mount —
+ *    `workspace-utility-commands.ts`).
+ * Animation and state machines are deliberately absent: each is an authored
+ * center document (animation inside its owning Asset Lab; an XState machine as
+ * its own Machine document), not a global debugger drawer instrument.
+ * The Profiler bench and State Watch are deliberately absent: both moved to
+ * `@volter/editor-game` as the `profiler.utility` / `state-watch.utility`
+ * contributions (WORKBENCH.md §The invariants — the host imports no package).
+ * GENERATIONS is absent for the same reason: the paid-provider lane's gallery
+ * is `@volter/editor-game`'s `generation.service.ts`, which registers the tab (badge and
+ * all) through this same registry.
+ * *
+ * PROBLEMS (§4.1 mock's `Problems` tab) is deliberately NOT registered —
+ * the W4 decision, recorded in the inventory: no truthful problem SOURCE
+ * exists today (there is no in-editor typecheck surface; scene-validation
+ * and mount failures already surface as console errors plus their own
+ * status-bar items), and
+ * §4.3's spirit forbids fabricating a surface with nothing real to feed it.
+ * The status bar's console counters (`status-contributions.tsx`) read the
+ * same real source — the truthful signal that does exist. A real Problems
+ * utility lands when a real diagnostics source does.
+ *
+ * Idempotent-ensure idiom mirrors `build-documents.tsx`'s
+ * `ensureBuildContributionsRegistered`.
+ */
+
+import { editorConsole } from '@volter/sdk/kit/editor-console';
+import { createHmrRegistrationGroup, type HmrRegistrationContext } from '@volter/sdk/kit/hmr-registration-group';
+import { CORE_WORKSPACE_UTILITIES } from '@volter/sdk/kit/workspace-core-utilities';
+import {
+  registerWorkspaceUtility,
+  type WorkspaceUtilityBadge,
+} from '@volter/sdk/kit/workspace-utility-registry';
+import { ConsolePanel } from './ConsolePanel';
+import { LightExplorerPanel } from './LightExplorerPanel';
+
+const registrationGroup = createHmrRegistrationGroup(
+  // Vite's HMR context when a dev server serves this module; the SDK carries no bundler types.
+  (import.meta as ImportMeta & { hot?: HmrRegistrationContext }).hot,
+  'core-utilities',
+);
+
+/** The Console tab's attention badge: error count (error severity) else
+ *  warn count (warn severity) else none. Exported for tests. */
+export function consoleUtilityBadge(): WorkspaceUtilityBadge | null {
+  const { error, warn } = editorConsole.counts;
+  if (error > 0) return { count: error + warn, severity: 'error' };
+  if (warn > 0) return { count: warn, severity: 'warn' };
+  return null;
+}
+
+/** Idempotent one-time registration of the built-in workspace utilities. */
+export function ensureCoreUtilitiesRegistered(): void {
+  registrationGroup.ensure((track) => {
+    track(
+      registerWorkspaceUtility({
+        ...CORE_WORKSPACE_UTILITIES.console,
+        order: -100, // first utility tab, matching the §4.1 mock's tab order
+        Content: ConsolePanel,
+        badge: consoleUtilityBadge,
+        subscribeBadge: editorConsole.subscribe,
+        badgeSnapshot: editorConsole.getSnapshot,
+        visibleByDefault: false,
+        closeable: true,
+      }),
+    );
+    track(
+      // Scene-wide light inventory over the active authoring adapter's real
+      // hierarchy + inspector fields. Closed by default and opened from the
+      // viewport display toolbar or Window menu; no parallel light registry.
+      registerWorkspaceUtility({
+        ...CORE_WORKSPACE_UTILITIES.lightExplorer,
+        order: 21,
+        Content: LightExplorerPanel,
+        visibleByDefault: false,
+        closeable: true,
+      }),
+    );
+  });
+}
+
+/** Test-only: allow re-registration after a registry reset. */
+export function __resetCoreUtilitiesForTest(): void {
+  registrationGroup.reset();
+}

package/src/kit/components/inspector-preview-section.tsx

@@ -0,0 +1,223 @@
+/**
+ * The PREVIEW section's body — a live square view of whatever the subject is,
+ * with the subject's `preview`-placed verbs sitting in the box over it.
+ *
+ * It lives in its own light module for one reason: `inspection/compose.ts`
+ * builds the preview section, and the preview drags the whole render stack
+ * (three.quarks, realism-effects) behind it. The heavy component stays behind
+ * `lazy()` here, so a headless composer — every unit test of the model, and
+ * `editor.inspect`, which never renders — pays nothing for it.
+ *
+ * `render` fills its host at any size, which is what lets the section body and
+ * the minimized card's round thumb be the SAME function off the SAME subject
+ * (`components/CompactInspectorCard.tsx`) rather than two derivations of what
+ * the thing looks like. What differs between those hosts is CHROME, not the
+ * picture — see {@link InspectionPreviewMode}.
+ */
+
+import { Button } from '@volter/sdk/widgets';
+import { lazy, type ReactNode, Suspense } from 'react';
+import type { ContentEntry, ContentEntrySource } from '../content-entry-source-registry';
+import type { InspectionAction, InspectionPreviewMode } from '@volter/sdk/kit/inspection-model';
+import { useAfterPaint } from './use-after-paint';
+
+const InspectorCanvasPreview = lazy(() =>
+  import('./InspectorCanvasPreview').then((m) => ({ default: m.InspectorCanvasPreview })),
+);
+
+export function InspectorPreviewBody({
+  picture,
+  previewKey,
+  actions,
+  mode = 'section',
+}: {
+  /** The subject's live picture, drawn by the medium that renders it (a three.js
+   *  object's isolated view). The composer only builds a preview section when
+   *  there IS one, so this never renders a fabricated stand-in. */
+  readonly picture: () => ReactNode;
+  /** Stable identity for the isolated preview document (the subject's node
+   *  id) — remounts when the subject changes, not on every compose. */
+  readonly previewKey: string;
+  readonly actions: readonly InspectionAction[];
+  /** Which host this is rendering into. Default `section` — the full box. */
+  readonly mode?: InspectionPreviewMode;
+}) {
+  // A thumbnail host is a small clipped shape that owns its own single press,
+  // so the body gives it the PICTURE and nothing else: it fills the host
+  // exactly, and the verbs stay in the section, which is where they are
+  // reachable and readable.
+  const thumbnail = mode === 'thumbnail';
+  // The picture arrives a frame after the box does: mounting it is scene and GL
+  // work, and doing it in the selection's own commit is what used to make the
+  // whole inspector wait on it (`components/use-after-paint.ts`).
+  const showPicture = useAfterPaint(previewKey);
+  return (
+    <div
+      data-testid={thumbnail ? 'inspection-preview-thumbnail' : 'inspection-preview'}
+      style={
+        thumbnail
+          ? { position: 'absolute', inset: 0, overflow: 'hidden' }
+          : {
+              position: 'relative',
+              width: 'calc(100% - 24px)',
+              aspectRatio: '1 / 1',
+              flexShrink: 0,
+              margin: 12,
+              overflow: 'hidden',
+              border: '1px solid var(--volter-structural-divider)',
+              borderRadius: 'var(--dv-group-border-radius, 8px)',
+            }
+      }
+    >
+      {showPicture && <Suspense fallback={null}>{picture()}</Suspense>}
+      {!thumbnail &&
+        actions.map((action) => (
+          <Button
+            key={action.id}
+            data-testid={action.id}
+            size="compact"
+            disabled={action.disabled}
+            title={action.title}
+            onClick={action.run}
+            style={{ position: 'absolute', right: 8, bottom: 8 }}
+          >
+            {action.label}
+          </Button>
+        ))}
+    </div>
+  );
+}
+
+/** The same Preview-section chrome around a COMPONENT's own picture, painted by
+ * whichever content source admits it (`content-entry-source-registry.ts`).
+ * Canvas entities are Pixi display objects rather than Object3Ds, so the
+ * picture Content already shows is the honest preview authority here too; the
+ * shell never substitutes the Transform icon for a picture, and never knows
+ * what the picture IS. */
+export function InspectorComponentPreviewBody({
+  source,
+  entry,
+  previewKey,
+  actions,
+  mode = 'section',
+}: {
+  readonly source: ContentEntrySource;
+  readonly entry: ContentEntry;
+  readonly previewKey: string;
+  readonly actions: readonly InspectionAction[];
+  readonly mode?: InspectionPreviewMode;
+}) {
+  const thumbnail = mode === 'thumbnail';
+  const showPicture = useAfterPaint(previewKey);
+  return (
+    <div
+      data-testid={thumbnail ? 'inspection-preview-thumbnail' : 'inspection-preview'}
+      style={
+        thumbnail
+          ? { position: 'absolute', inset: 0, overflow: 'hidden' }
+          : {
+              position: 'relative',
+              width: 'calc(100% - 24px)',
+              aspectRatio: '1 / 1',
+              flexShrink: 0,
+              margin: 12,
+              overflow: 'hidden',
+              border: '1px solid var(--volter-structural-divider)',
+              borderRadius: 'var(--dv-group-border-radius, 8px)',
+            }
+      }
+    >
+      {showPicture && (
+        <div
+          style={{
+            position: 'absolute',
+            inset: 0,
+            overflow: 'hidden',
+            background: 'var(--volter-bg-inset)',
+          }}
+        >
+          <source.Thumbnail
+            entry={entry}
+            previewRevision={0}
+            width={thumbnail ? 96 : 256}
+            height={thumbnail ? 96 : 256}
+          />
+        </div>
+      )}
+      {!thumbnail &&
+        actions.map((action) => (
+          <Button
+            key={action.id}
+            data-testid={action.id}
+            size="compact"
+            disabled={action.disabled}
+            title={action.title}
+            onClick={action.run}
+            style={{ position: 'absolute', right: 8, bottom: 8 }}
+          >
+            {action.label}
+          </Button>
+        ))}
+    </div>
+  );
+}
+
+/** The selected live Canvas subtree in the same Preview-section shell used by
+ * Three and by story fallbacks. */
+export function InspectorCanvasPreviewBody({
+  capture,
+  previewKey,
+  actions,
+  mode = 'section',
+}: {
+  readonly capture: (size: number) => Promise<string | null>;
+  readonly previewKey: string;
+  readonly actions: readonly InspectionAction[];
+  readonly mode?: InspectionPreviewMode;
+}) {
+  const thumbnail = mode === 'thumbnail';
+  const showPicture = useAfterPaint(previewKey);
+  return (
+    <div
+      data-testid={thumbnail ? 'inspection-preview-thumbnail' : 'inspection-preview'}
+      style={
+        thumbnail
+          ? { position: 'absolute', inset: 0, overflow: 'hidden' }
+          : {
+              position: 'relative',
+              width: 'calc(100% - 24px)',
+              aspectRatio: '1 / 1',
+              flexShrink: 0,
+              margin: 12,
+              overflow: 'hidden',
+              border: '1px solid var(--volter-structural-divider)',
+              borderRadius: 'var(--dv-group-border-radius, 8px)',
+            }
+      }
+    >
+      {showPicture && (
+        <Suspense fallback={null}>
+          <InspectorCanvasPreview
+            capture={capture}
+            previewKey={previewKey}
+            size={thumbnail ? 96 : 256}
+          />
+        </Suspense>
+      )}
+      {!thumbnail &&
+        actions.map((action) => (
+          <Button
+            key={action.id}
+            data-testid={action.id}
+            size="compact"
+            disabled={action.disabled}
+            title={action.title}
+            onClick={action.run}
+            style={{ position: 'absolute', right: 8, bottom: 8 }}
+          >
+            {action.label}
+          </Button>
+        ))}
+    </div>
+  );
+}