@volter/editor-core 0.5.57

package/src/native-selection-style.ts

@@ -0,0 +1,202 @@
+/**
+ * Theme-backed renderer selection ink shared by the native Three and Pixi
+ * views. CSS can consume `var(--vgai-accent)` directly; WebGL cannot, so this
+ * module resolves the inherited token to the integer both renderers speak.
+ */
+
+import { EDITOR_THEME_CLASS, graphiteDarkEditorTheme } from '@volter/editor-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;
+}
+
+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 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 = themeToken(root, '--vgai-viewport-selection') || themeToken(root, '--vgai-accent');
+  const visible =
+    parseCssColor(raw || graphiteDarkEditorTheme.color.accent.default) ??
+    DEFAULT_NATIVE_SELECTION_COLOR;
+  return { visible, hidden: dimColor(visible) };
+}
+
+/** 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 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;
+}
+
+export function nativeViewportLook(element?: Element | null): NativeViewportLook {
+  const root = themeRoot(element);
+  const read = (name: string): number | null => {
+    const raw = themeToken(root, name);
+    return raw ? parseCssColor(raw) : null;
+  };
+  return {
+    background: read('--vgai-viewport-background'),
+    grid: read('--vgai-viewport-grid'),
+    axisX: read('--vgai-viewport-axis-x'),
+    axisY: read('--vgai-viewport-axis-y'),
+    active: read('--vgai-viewport-active'),
+  };
+}
+
+/**
+ * THE LOOK'S TRANSFORM-GIZMO SIZE, in px per gizmo unit
+ * (`EditorTheme.density.viewport.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), '--vgai-viewport-gizmo-size');
+  if (!raw) return null;
+  const value = Number.parseFloat(raw);
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+
+/**
+ * WHICH TOOL THE LOOK'S SHELF OPENS ON
+ * (`EditorTheme.density.viewport.shelfTool`), or `null` when the look names
+ * none — which is every look but Blender's, and means the editor's own
+ * combined gizmo.
+ *
+ * It rides the THEME rather than the chrome regions, and that is measured
+ * rather than stylistic: a region crosses the Code-OSS frame's configuration
+ * service, which knows only the key list its generated contribution carries
+ * and drops anything newer until the next release is cut
+ * (`workspace-regions.ts`'s own note). A theme token is installed on the theme
+ * root by the page, so a look can add a value and use it in the same session.
+ */
+export function nativeViewportShelfTool(element?: Element | null): 'select' | 'transform' | null {
+  const raw = themeToken(themeRoot(element), '--vgai-viewport-shelf-tool');
+  return raw === 'select' || raw === 'transform' ? raw : null;
+}
+
+/**
+ * WHICH AXIS THE LOOK SAYS IS UP in the world its stage presents
+ * (`EditorTheme.density.viewport.upAxis`), or `null` when it names none —
+ * which is every look but Blender's, and means three's own frame.
+ *
+ * Read off the emitted token for the same reason the two above are: WebGL
+ * consumes no CSS variable, and a second path from the theme object into the
+ * viewport would be a second source for one value. What `'z'` means in three's
+ * units — which handle carries which axis's colour, which side its arm is
+ * drawn on, and what the six navigation balls are called — is
+ * `editor-viewport.ts`'s to know, and it says so there.
+ */
+export function nativeViewportUpAxis(element?: Element | null): 'y' | 'z' | null {
+  const raw = themeToken(themeRoot(element), '--vgai-viewport-up-axis');
+  return raw === 'y' || raw === 'z' ? raw : null;
+}
+
+/** WHAT A BOX SELECT MEANS in the look's stage
+ *  (`EditorTheme.density.viewport.boxSelect`), or `null` for the editor's own
+ *  `contain`. Blender's Select Box is `touch`; see the field's own note for
+ *  why neither can be the other's default. */
+export function nativeViewportBoxSelect(element?: Element | null): 'contain' | 'touch' | null {
+  const raw = themeToken(themeRoot(element), '--vgai-viewport-box-select');
+  return raw === 'contain' || raw === 'touch' ? raw : null;
+}
+
+/**
+ * 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'] });
+  return () => observer.disconnect();
+}

package/src/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 `.vgai/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 './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 `.vgai/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(
+    options: OpenObject3DDocumentPersistenceOptions,
+  ): Promise<Object3DDocumentPersistenceSession>;
+  /**
+   * 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;
+}

package/src/packaged-runtime.ts

@@ -0,0 +1,108 @@
+/**
+ * Runtime detection of the PACKAGED editor server (`packages/editor/server/
+ * packaged.ts` — a `@vgai/editor` npm package with NO monorepo checkout on
+ * disk) from editor CLIENT code. Needed because a react world's mount
+ * (`react-mount-runtime.ts`'s `resolveReactRootMountRuntime`) must resolve its
+ * `react`/`react-dom/client`/`WorldProvider`-fallback wrapper from the
+ * PROJECT's own module graph ONLY under this runtime — see that function's
+ * doc comment, and `packaged.ts`'s header doc comment ("React-world OID
+ * authoring parity"), for the dual-React-instance bug this closes. Under
+ * dev, this must resolve `false` so the existing static-import path
+ * stays byte-unchanged (one shared Vite instance already collapses both
+ * react copies via `resolve.dedupe`).
+ *
+ * Reads the server's own `packaged` flag off `/__editor/project`'s response
+ * (computed server-side via `isMonorepoScaffoldRoot`, `server-utils.ts`)
+ * rather than probing a URL that only resolves in packaged mode: an
+ * unconditional dynamic `import()` probe would 404 (and log an
+ * unsuppressible browser console error) on EVERY react-world mount under
+ * dev — the exact reasoning `binding-resolver.ts`'s
+ * `loadProjectUIRegistry` doc comment already recorded for `hasUiRegistry`
+ * ("the client must not probe /@fs for it").
+ *
+ * A plain inline `fetch()`, not `editor-api.ts`'s `getCurrentServerProject`
+ * — same reasoning `loadProjectUIRegistry` documents: this module (via
+ * `binding-resolver.ts`) must stay importable by headless Node/vitest
+ * suites, and `editor-api.ts`'s module top level pulls in `./storage`.
+ *
+ * A HOST THAT SERVES NO `/__editor/project` is answered locally rather than by
+ * a doomed fetch: it is never the packaged runtime, because "packaged" names a
+ * Node host serving a project's own module graph, and a 404's console error is
+ * unsuppressible on every doorway of every mount. Same guard, same reason, as
+ * `ui-source/tier-source-write-backend.ts`'s `serverSourceWriteRoutes`.
+ *
+ * ## What is memoized, and what a FAILED probe does
+ *
+ * An ANSWER is memoized for the page — the runtime a server process runs
+ * under cannot change without a restart, so a settled answer is settled. A
+ * probe that never got an answer is NOT memoized, and does NOT resolve: it
+ * drops the memo and REJECTS, so the next caller asks again.
+ *
+ * Both halves were bought by one measured failure. A `.catch(() => false)`
+ * latch turned a single unreachable fetch — a mount landing in the window
+ * while `vgai edit` restarts its dev server, which it does on any
+ * server-file change — into a page where EVERY doorway
+ * (`three-ingest-runtime`, `canvas-entry-runtime`, `r3f-entry-runtime`,
+ * the two story runtimes, `binding-resolver`'s react
+ * mount) silently resolved the SHELL's namespace for the rest of the
+ * session. Under the packaged runtime that is the wrong graph, and the cost
+ * lands 10–15 seconds later as a mount failure whose message blames the
+ * GAME ("bundles its own (un-shared) copy of three") for a defect in this
+ * host — the exact mis-attribution `three-ingest-runtime.ts`'s own
+ * loud-throw comment already refuses to make for the sibling case.
+ *
+ * So "I don't know" is never spent as "dev". Every doorway reads this with
+ * `await isPackagedRuntime()` and does nothing else with the answer, so the
+ * rejection propagates to the mount site unchanged: nothing mounts on a
+ * guessed graph, the message names this host, and because the memo is
+ * dropped the remedy it states — retry the mount — is a real one rather
+ * than advice.
+ */
+
+import { editorServerJson } from './editor-server-response';
+
+let cachedIsPackaged: Promise<boolean> | null = null;
+
+export function isPackagedRuntime(): Promise<boolean> {
+  if (!cachedIsPackaged) {
+    // The `fetch` call is INSIDE the chain so that a synchronous throw from it
+    // is a rejected probe like any other, rather than an exception thrown at
+    // whoever happened to ask first.
+    const probe: Promise<boolean> = Promise.resolve()
+      .then(() => fetch('/__editor/project'))
+      .then((res) =>
+        editorServerJson<{ project?: { packaged?: boolean } | null }>(
+          res,
+          '`/__editor/project` did not answer',
+        ),
+      )
+      .then((data) => Boolean(data.project?.packaged))
+      .catch((err: unknown) => {
+        if (cachedIsPackaged === probe) cachedIsPackaged = null;
+        throw new Error(
+          "This editor session's runtime is unknown — `/__editor/project` did not answer, so " +
+            'which module graph a world mounts in (this shell’s, or the project’s) cannot be ' +
+            'decided and nothing was mounted on a guess. This is a fault in the editor host, ' +
+            'not in the game. The answer is not latched: retry the mount (reopen the project) ' +
+            `and the question is asked again. (${err instanceof Error ? err.message : String(err)})`,
+          { cause: err },
+        );
+      });
+    cachedIsPackaged = probe;
+  }
+  return cachedIsPackaged;
+}
+
+/** Test-only: reset the memoized result between tests (mirrors
+ *  `setCachedProjectUIRegistry`'s test-seam shape). */
+export function resetPackagedRuntimeCacheForTest(): void {
+  cachedIsPackaged = null;
+}
+
+/** Test-only: pre-seed the probe's answer. jsdom has no `/__editor/project` to
+ *  ask (vitest's MODE is not `web`, so the browser short-circuit does not
+ *  apply), and the loud unknown-runtime refusal — correct in a live session —
+ *  is pure noise in a suite that mounts portable stories. */
+export function setPackagedRuntimeForTest(packaged: boolean): void {
+  cachedIsPackaged = Promise.resolve(packaged);
+}

package/src/palettes/maya.palette.json

@@ -0,0 +1,57 @@
+{
+  "schemaVersion": 3,
+  "name": "Maya",
+  "theme": {
+    "id": "maya",
+    "color": {
+      "surface": {
+        "shell": "#2b2b2b",
+        "panel": "#444444",
+        "chrome": "#373737",
+        "raised": "#4b4b4b",
+        "inset": "#333333",
+        "overlay": "rgba(55,55,55,0.94)"
+      },
+      "boundary": {
+        "default": "#2b2b2b",
+        "strong": "#5a5a5a"
+      },
+      "content": {
+        "primary": "#cccccc",
+        "muted": "#a8a8a8",
+        "dim": "#858585",
+        "onAccent": "#ffffff",
+        "onBright": {
+          "primary": "#1c1c1c",
+          "muted": "rgba(28,28,28,0.82)",
+          "dim": "rgba(28,28,28,0.7)"
+        }
+      },
+      "accent": {
+        "default": "#5285a6",
+        "muted": "rgba(82,133,166,0.34)"
+      },
+      "semantic": {
+        "danger": "#d9534f",
+        "dangerMuted": "rgba(217,83,79,0.28)",
+        "dangerFaint": "rgba(217,83,79,0.12)",
+        "warning": "#e0a030",
+        "warningMuted": "rgba(224,160,48,0.28)",
+        "success": "#4fd85b",
+        "successMuted": "rgba(79,216,91,0.28)",
+        "dynamic": "#e6a6ff",
+        "dynamicMuted": "rgba(230,166,255,0.18)",
+        "instance": "#4fd85b"
+      },
+      "neutralOverlay": {
+        "hover": "rgba(255,255,255,0.07)",
+        "active": "rgba(255,255,255,0.12)"
+      },
+      "scrim": "rgba(0,0,0,0.55)"
+    },
+    "typography": {
+      "sans": "'Helvetica Neue', Arial, system-ui, sans-serif",
+      "mono": "Menlo, Consolas, monospace"
+    }
+  }
+}

package/src/palettes/substance.palette.json

@@ -0,0 +1,57 @@
+{
+  "schemaVersion": 3,
+  "name": "Substance",
+  "theme": {
+    "id": "substance",
+    "color": {
+      "surface": {
+        "shell": "#1e1e1e",
+        "panel": "#252525",
+        "chrome": "#2a2a2a",
+        "raised": "#2d2d2d",
+        "inset": "#1a1a1a",
+        "overlay": "rgba(37,37,37,0.94)"
+      },
+      "boundary": {
+        "default": "#3a3a3a",
+        "strong": "#4a4a4a"
+      },
+      "content": {
+        "primary": "#d9d9d9",
+        "muted": "#a6a6a6",
+        "dim": "#7f7f7f",
+        "onAccent": "#ffffff",
+        "onBright": {
+          "primary": "#1e1e1e",
+          "muted": "rgba(30,30,30,0.82)",
+          "dim": "rgba(30,30,30,0.7)"
+        }
+      },
+      "accent": {
+        "default": "#4aa3df",
+        "muted": "rgba(74,163,223,0.3)"
+      },
+      "semantic": {
+        "danger": "#e5534b",
+        "dangerMuted": "rgba(229,83,75,0.28)",
+        "dangerFaint": "rgba(229,83,75,0.12)",
+        "warning": "#e3a52f",
+        "warningMuted": "rgba(227,165,47,0.28)",
+        "success": "#5cc27a",
+        "successMuted": "rgba(92,194,122,0.28)",
+        "dynamic": "#4aa3df",
+        "dynamicMuted": "rgba(74,163,223,0.18)",
+        "instance": "#e98b3a"
+      },
+      "neutralOverlay": {
+        "hover": "rgba(255,255,255,0.06)",
+        "active": "rgba(255,255,255,0.11)"
+      },
+      "scrim": "rgba(0,0,0,0.62)"
+    },
+    "typography": {
+      "sans": "'Source Sans 3', 'Segoe UI', system-ui, sans-serif",
+      "mono": "'Source Code Pro', Menlo, monospace"
+    }
+  }
+}

package/src/pasteboard-module.ts

@@ -0,0 +1,81 @@
+/**
+ * Structural detection of a PASTEBOARD MODULE — an ordinary project `.tsx`
+ * whose default export renders the pasteboard capability's `Pasteboard`
+ * helper at its root (`src/lib/pasteboard/pasteboard.tsx` in the project,
+ * marker `data-vgai-pasteboard`). Same doctrine as `LiveModuleDocument`'s
+ * Object3D probe and the quarks JSON probe: detection is structural, never a
+ * filename convention, so a project's freely edited copy of the helper keeps
+ * working.
+ *
+ * The probe is a BARE UNWRAP, not a render: the default export is invoked as
+ * a plain function and the returned element chain is followed by invoking
+ * each function `type` until a host element appears, whose props either carry
+ * the marker or do not. This keeps the probe free of react-dom and of the
+ * two-React-copies trap (the editor's react-dom driving a project component
+ * would crash on the project React's own hook dispatcher). The CONTRACT that
+ * buys: the chain from the default export down to `<Pasteboard>` is hook-free
+ * static composition — which a pasteboard is by design. Children BELOW the
+ * Pasteboard root may do anything; the probe never descends past the first
+ * host element. A chain that throws (hooks, wrong shape) is simply not a
+ * pasteboard: the module falls back to the ordinary source viewer.
+ */
+
+import { liveModuleImportUrl } from '@volter/editor-sdk/session/project-module-url';
+
+const PASTEBOARD_MARKER = 'data-vgai-pasteboard';
+
+/** Follow a React element's function-component chain to its first host
+ *  element and answer whether that element carries the pasteboard marker. */
+export function isPasteboardElementTree(value: unknown): boolean {
+  let current = value;
+  for (let depth = 0; depth < 12; depth++) {
+    if (!current || typeof current !== 'object') return false;
+    const element = current as { type?: unknown; props?: Record<string, unknown> | null };
+    if (typeof element.type === 'string') {
+      return element.props?.[PASTEBOARD_MARKER] === 'true';
+    }
+    if (typeof element.type === 'function') {
+      try {
+        current = (element.type as (props: unknown) => unknown)(element.props ?? {});
+      } catch {
+        return false;
+      }
+      continue;
+    }
+    // memo/forwardRef/fragment wrappers are outside the static-composition
+    // contract; an author who wants one keeps it below the Pasteboard root.
+    return false;
+  }
+  return false;
+}
+
+/**
+ * Import the module (same revisioned url the live-module probe uses, so the
+ * two probes share one fetch) and answer whether its DEFAULT export is a
+ * pasteboard component. Named exports are deliberately not considered — the
+ * pasteboard contract is "the file IS the canvas", and a file whose canvas is
+ * a side export has no one subject.
+ */
+export async function probePasteboardModule(
+  projectRoot: string,
+  modulePath: string,
+  revision: number,
+): Promise<boolean> {
+  let namespace: Record<string, unknown>;
+  try {
+    namespace = (await import(
+      /* @vite-ignore */ liveModuleImportUrl(projectRoot, modulePath, revision)
+    )) as Record<string, unknown>;
+  } catch {
+    return false;
+  }
+  const candidate = namespace['default'];
+  if (typeof candidate !== 'function') return false;
+  let element: unknown;
+  try {
+    element = (candidate as (props: Record<string, unknown>) => unknown)({});
+  } catch {
+    return false;
+  }
+  return isPasteboardElementTree(element);
+}