@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/workspace-style.ts

@@ -0,0 +1,226 @@
+/**
+ * Workspace STYLE BUNDLES (Glass-UI spike, Unit 3, "New named style using
+ * existing axes" row).
+ *
+ * Named one-shot presets over PALETTE + MATERIAL + ICONS: how things are DRAWN, and nothing
+ * else (ARCHITECTURE.md rule 7). The axes stay independently selectable; choosing a named style
+ * intentionally restores its canonical complete appearance. In particular, Classic must restore
+ * the original Graphite contract rather than inheriting a Glass palette. Which chrome regions
+ * exist is function — a workspace's (`workspace-regions.ts`), never a style's.
+ *
+ * Bundles are ONE-SHOT PRESETS, not a fifth stored axis: applying a bundle
+ * just calls the four existing axis setters, and this module keeps no store
+ * or persistence of its own. "Which bundle is active" is always DERIVED
+ * from their current values (`activeWorkspaceStyleId`) and can never
+ * disagree with them — e.g. after a user independently changes just the
+ * material, the derived id correctly falls back to `null` (a "custom" mix)
+ * rather than going stale.
+ */
+
+import type { StyleContribution } from '@volter/sdk/looks';
+import type { EditorMaterialId, EditorPalette } from '@volter/sdk/widgets';
+import {
+  DEFAULT_ICON_SET_ID,
+  registerContributedIconSet,
+  registerContributedMaterial,
+} from '@volter/sdk/widgets';
+import { activeProduct, subscribeActiveProduct } from './active-product';
+import { registerContributedPalette } from './theme-library';
+import {
+  editorIconSetSnapshot,
+  editorMaterialSnapshot,
+  editorPaletteSnapshot,
+  setDefaultEditorAppearance,
+  setEditorIconSetPreference,
+  setEditorMaterialPreference,
+  setEditorPalettePreference,
+} from './theme-preference';
+
+export interface WorkspaceStyleBundle {
+  readonly id: string;
+  readonly title: string;
+  readonly paletteId: EditorPalette['id'];
+  readonly materialId: EditorMaterialId;
+  /** `icon-set-registry.ts`; `default` is the editor's own glyphs. */
+  readonly iconSetId: string;
+}
+
+/** Frozen built-in list — the switch surface (command palette / View menu)
+ *  enumerates this directly. */
+const BUILT_IN_STYLES: readonly WorkspaceStyleBundle[] = Object.freeze([
+  {
+    id: 'classic',
+    title: 'Classic',
+    paletteId: 'graphite-dark',
+    materialId: 'classic',
+    iconSetId: DEFAULT_ICON_SET_ID,
+  },
+  {
+    id: 'glass',
+    title: 'Glass',
+    paletteId: 'graphite-neutral',
+    materialId: 'glass',
+    iconSetId: DEFAULT_ICON_SET_ID,
+  },
+  {
+    id: 'maya',
+    title: 'Maya',
+    paletteId: 'maya',
+    materialId: 'classic',
+    iconSetId: DEFAULT_ICON_SET_ID,
+  },
+  {
+    id: 'substance',
+    title: 'Substance',
+    paletteId: 'substance',
+    materialId: 'classic',
+    iconSetId: DEFAULT_ICON_SET_ID,
+  },
+]);
+
+interface ContributedStyle {
+  readonly bundle: WorkspaceStyleBundle;
+  readonly unregisterPalette: (() => void) | null;
+  readonly unregisterMaterial: (() => void) | null;
+  readonly unregisterIconSet: (() => void) | null;
+}
+const contributedStyles = new Map<string, ContributedStyle>();
+let registryVersion = 0;
+const registryListeners = new Set<() => void>();
+
+/** Built-ins first, then contributions in registration order — the switch
+ *  surfaces (View menu, palette) enumerate this. */
+export function workspaceStyles(): readonly WorkspaceStyleBundle[] {
+  return [...BUILT_IN_STYLES, ...[...contributedStyles.values()].map((entry) => entry.bundle)];
+}
+
+export function workspaceStylesVersion(): number {
+  return registryVersion;
+}
+
+export function subscribeWorkspaceStyles(listener: () => void): () => void {
+  registryListeners.add(listener);
+  return () => registryListeners.delete(listener);
+}
+
+/**
+ * Register a package's style bundle (`workspace.style` contribution), with
+ * the palette document and the material it carries registered first — the
+ * bundle names their ids, and an id must exist before the bundle can be
+ * applied. Returns the unregister. A duplicate id throws.
+ */
+export function registerContributedStyle(contribution: StyleContribution): () => void {
+  if (
+    BUILT_IN_STYLES.some((entry) => entry.id === contribution.id) ||
+    contributedStyles.has(contribution.id)
+  )
+    throw new Error(`registerContributedStyle: style "${contribution.id}" is already registered.`);
+  const unregisterPalette =
+    contribution.palette === undefined ? null : registerContributedPalette(contribution.palette);
+  const unregisterMaterial =
+    contribution.material === undefined ? null : registerContributedMaterial(contribution.material);
+  const unregisterIconSet =
+    contribution.icons === undefined ? null : registerContributedIconSet(contribution.icons);
+  const entry: ContributedStyle = {
+    bundle: {
+      id: contribution.id,
+      title: contribution.title,
+      paletteId: contribution.paletteId,
+      materialId: contribution.materialId,
+      iconSetId: contribution.iconSetId ?? contribution.icons?.id ?? DEFAULT_ICON_SET_ID,
+    },
+    unregisterPalette,
+    unregisterMaterial,
+    unregisterIconSet,
+  };
+  contributedStyles.set(contribution.id, entry);
+  registryVersion++;
+  for (const listener of registryListeners) listener();
+  // The product's look is usually one of these (the Blender look ships inside
+  // `@volter/editor-blender`), so the id it named only becomes resolvable here.
+  publishProductLook();
+  return () => {
+    if (contributedStyles.get(contribution.id) !== entry) return;
+    contributedStyles.delete(contribution.id);
+    entry.unregisterPalette?.();
+    entry.unregisterMaterial?.();
+    entry.unregisterIconSet?.();
+    registryVersion++;
+    for (const listener of registryListeners) listener();
+    publishProductLook();
+  };
+}
+
+/**
+ * THE PRODUCT'S LOOK, RESOLVED TO ITS AXES — the one thing this module does for
+ * a composition rather than for a gesture.
+ *
+ * A product names a style bundle id (`frame/product.ts`'s `look`); this is the
+ * module that knows what a bundle IS, so it resolves the id and pushes the
+ * palette/material/icons behind `theme-preference.ts`'s defaults. It runs on
+ * every registry change because a product's own look usually arrives as one of
+ * its packages' `workspace.style` contributions, which register a moment into
+ * the session — the Blender look is the worked case.
+ *
+ * It applies nothing and persists nothing: a bundle a person CHOOSES goes
+ * through {@link applyWorkspaceStyle}, which writes the preference. This is the
+ * floor under that.
+ */
+function publishProductLook(): void {
+  const declared = activeProduct()?.look;
+  if (declared === undefined) {
+    setDefaultEditorAppearance(null);
+    return;
+  }
+  const bundle = workspaceStyles().find((entry) => entry.id === declared);
+  if (!bundle) return;
+  setDefaultEditorAppearance({
+    palette: bundle.paletteId,
+    material: bundle.materialId,
+    icons: bundle.iconSetId,
+  });
+}
+
+subscribeActiveProduct(publishProductLook);
+publishProductLook();
+
+/** Apply the three axes of the named bundle. Unknown ids are a silent no-op —
+ *  callers (menu/command palette) only ever offer ids from {@link workspaceStyles}. */
+export function applyWorkspaceStyle(id: string): void {
+  const bundle = workspaceStyles().find((entry) => entry.id === id);
+  if (!bundle) return;
+  setEditorPalettePreference(bundle.paletteId);
+  setEditorMaterialPreference(bundle.materialId);
+  setEditorIconSetPreference(bundle.iconSetId);
+}
+
+/** Each axis on which the chrome's current value differs from the bundle `id`'s, as
+ *  `axis: wearing <value>, bundle <value>` — what a caller told "custom mix" needs to act on. */
+export function workspaceStyleDifferences(id: string): string[] {
+  const bundle = workspaceStyles().find((entry) => entry.id === id);
+  if (!bundle) return [`no style bundle "${id}"`];
+  const rows: Array<[string, string, string]> = [
+    ['palette', editorPaletteSnapshot(), bundle.paletteId],
+    ['material', editorMaterialSnapshot(), bundle.materialId],
+    ['icons', editorIconSetSnapshot(), bundle.iconSetId],
+  ];
+  return rows
+    .filter(([, wearing, wanted]) => wearing !== wanted)
+    .map(([axis, wearing, wanted]) => `${axis}: wearing ${wearing}, bundle ${wanted}`);
+}
+
+/** The bundle id whose palette, material and icon set all match the
+ *  current axis values, or `null` if the current combination isn't any
+ *  registered bundle (a "custom" mix — always derived, never a separate
+ *  stored state). */
+export function activeWorkspaceStyleId(): string | null {
+  const paletteId = editorPaletteSnapshot();
+  const materialId = editorMaterialSnapshot();
+  const bundle = workspaceStyles().find(
+    (entry) =>
+      entry.paletteId === paletteId &&
+      entry.materialId === materialId &&
+      entry.iconSetId === editorIconSetSnapshot()
+  );
+  return bundle?.id ?? null;
+}

package/src/kit/workspace-utility-commands.ts

@@ -0,0 +1,74 @@
+/** Semantic commands and failure auto-open policy for workspace utilities. */
+
+import { getMountFailureReports, subscribeToMountFailures } from '@volter/sdk/kit/mount-failure-report';
+import { editorConsole } from '@volter/sdk/kit/editor-console';
+import type { HistoryService } from '@volter/sdk/kit/history/history-service';
+import { showWorkspaceUtility, toggleWorkspaceUtility } from '@volter/sdk/kit/workspace-host-commands';
+import { activeChromeRegions } from '@volter/sdk/kit/workspace-regions';
+
+export const CONSOLE_UTILITY_ID = 'console';
+
+/**
+ * Only actionable failures open a utility automatically.
+ *
+ * A world that did not mount is the most actionable failure the editor has —
+ * the project is showing something that is not the game — and revealing the
+ * Console (where every mount route already wrote its full line) is what keeps
+ * it LOUD without a second error surface. This replaced a top-of-shell red
+ * banner: the reveal, not the banner, is the answer to "the Console is not
+ * the default bottom tab". Fires on the empty→failing EDGE only, so a second
+ * failing world in the same attempt does not yank the region back.
+ *
+ * Source persistence failures arrive through the project history that guarded
+ * and rolled back the write. Watch its failure EDGE directly: this keeps the
+ * Console reveal format-neutral and avoids a second adapter-specific event.
+ *
+ * A workspace whose regions HIDE the drawer (Blender's modeling workspace has
+ * no strip below the viewport) is never yanked open by this policy: the
+ * status bar's error count stays the loud surface there, and a person's own
+ * gesture (a failure item, View → Console) still reveals it.
+ */
+export function installUtilityAutoOpen(history: HistoryService): () => void {
+  let hadMountFailure = getMountFailureReports().length > 0;
+  const stopMountFailures = subscribeToMountFailures(() => {
+    const failing = getMountFailureReports().length > 0;
+    if (failing && !hadMountFailure && activeChromeRegions().drawer !== 'hidden')
+      showWorkspaceUtility(CONSOLE_UTILITY_ID);
+    hadMountFailure = failing;
+  });
+
+  let hadSourceFailure = history.getSnapshot().lastError !== null;
+  const stopHistory = history.subscribe(() => {
+    const error = history.getSnapshot().lastError;
+    const failing = error !== null;
+    if (failing && !hadSourceFailure) {
+      // The one place every rolled-back write is named for the DOOR: the
+      // screen narrates it (a toast, the document's own message), and
+      // the editor's `console` command must say the same — measured silent before this line.
+      editorConsole.error(`Source write rolled back: ${error.message} (${error.code})`, 'history');
+      if (activeChromeRegions().drawer !== 'hidden') showWorkspaceUtility(CONSOLE_UTILITY_ID);
+    }
+    hadSourceFailure = failing;
+  });
+
+  return () => {
+    stopMountFailures();
+    stopHistory();
+  };
+}
+
+/** Toggle the Console utility — the semantic command every menu/hotkey/
+ *  control-API caller invokes directly. It used to be reached through a
+ *  `window` CustomEvent (`editor:toggle-console`) installed by
+ *  `installUtilityEvents`; that indirection was a shell-era relay with no
+ *  remaining second implementation, so it was deleted. */
+export function toggleConsoleUtility(): void {
+  toggleWorkspaceUtility(CONSOLE_UTILITY_ID);
+}
+
+/** REVEAL the Console — what a failure item clicks through to. Distinct from
+ *  {@link toggleConsoleUtility} on purpose: a user acting on a reported error
+ *  must never have that click HIDE the panel holding the error's trace. */
+export function showConsoleUtility(): void {
+  showWorkspaceUtility(CONSOLE_UTILITY_ID);
+}

package/src/kit/workspace-utility-registry.ts

@@ -0,0 +1,263 @@
+/**
+ * Workspace UTILITY registry (W0 — the shell-contract slice of §9 W0).
+ * Utilities are the TRANSIENT output/debug surfaces of §1.4/§5: Console,
+ * Problems, Build Output, Dev, and story-scoped addon results. They live in
+ * the on-demand bottom utility region — never substantial editors, which are
+ * documents (`workspace-document-registry.ts`).
+ *
+ * On-demand is about the TAB: a registration with no materialized tab has no
+ * presence at all. Once a tab EXISTS — pre-registered here, contributed by
+ * the open project, or introduced by background activity through
+ * `ensureWorkspaceUtility` — the region stays on screen COLLAPSED to its own
+ * tab strip, so the tab and its badge are discoverable while the body stays
+ * closed until the tab is clicked (the layout host owns that presentation).
+ *
+ * The layout host pre-registers default-visible tabs in a
+ * zero-footprint hidden host. Semantic commands and actionable failures reveal
+ * that host directly. Other registrations
+ * are created on demand (built-ins register via
+ * `components/core-utilities.tsx`; migration map).
+ *
+ * Registrations declare a `section` (`core` | `project`, default `core`) —
+ * the editor's own instruments versus the open game's plane. It is the OUTER
+ * sort key, so the drawer's tab strip renders the two as visually separated
+ * clusters (`utilitySectionBoundaryId` names the divider's position). It is
+ * presentation within the one bottom group; it is not a second dock.
+ *
+ * Idioms mirror `inspector-section-registry.ts`: module-scope state,
+ * `useSyncExternalStore`-shaped subscribe + monotonic version,
+ * `__resetForTest`, pure-logic headless tests (`Content` is never rendered
+ * here). Unlike that registry, utility ids KEY tabs (test ids, persisted
+ * drawer state), so duplicate registration is a programming error and
+ * throws.
+ */
+
+import type { ComponentType } from 'react';
+
+/** Attention badge a utility surfaces when its host is open; persistent
+ *  signals such as Console errors are also projected into the status bar. */
+export interface WorkspaceUtilityBadge {
+  readonly count: number;
+  readonly severity: 'info' | 'warn' | 'error';
+}
+
+/**
+ * Which audience a utility belongs to, and therefore which cluster of the
+ * drawer's tab strip it sits in.
+ *
+ *  - `core` — the EDITOR's own instruments (Console, Animation, Profiler,
+ *    Network, Audio…). Present in every project.
+ *  - `project` — the GAME's own plane: one tab per `workspace.utility` tool
+ *    contribution the open project ships (`tool-loader.ts` registers them
+ *    under `tool:<contributionId>`). Which tabs exist depends entirely on the
+ *    open game, so this cluster is empty for a project that contributes none.
+ */
+export type WorkspaceUtilitySection = 'core' | 'project';
+
+const SECTION_RANK: Record<WorkspaceUtilitySection, number> = { core: 0, project: 1 };
+
+/** The §7 utility contribution contract. */
+export interface WorkspaceUtilityRegistration {
+  /** Stable id — keys the drawer tab (`data-testid`, persisted layout). */
+  readonly id: string;
+  /** Tab label (§8 naming: `Build Output`, not `Build`). */
+  readonly title: string;
+  /** Tab-strip cluster. Default `'core'` — a contribution that says nothing
+   *  is one of the editor's own instruments. */
+  readonly section?: WorkspaceUtilitySection;
+  /** React content host. Never rendered by the registry itself. */
+  readonly Content: ComponentType;
+  /** Tab order among registered utilities (ascending; ties keep
+   *  registration order). Default `0`. */
+  readonly order?: number;
+  /** Session-scoped availability — e.g. Network exists only while a live
+   *  session exposes the owning adapter (§5 "play-only bottom utility").
+   *  Default: always available. */
+  readonly available?: () => boolean;
+  /** Optional attention badge for the tab (may return `null` for none). */
+  readonly badge?: () => WorkspaceUtilityBadge | null;
+  /** Subscribe to the source read by `badge()`. Dynamic badges must provide
+   * this together with `badgeSnapshot` so a dock tab updates while its panel
+   * is collapsed. */
+  readonly subscribeBadge?: (listener: () => void) => () => void;
+  /** Stable `useSyncExternalStore` snapshot for `subscribeBadge`. */
+  readonly badgeSnapshot?: () => number;
+  /** Whether the tab is pre-registered in the clean layout's hidden utility
+   * host. Defaults to `true`; this does not make the host itself visible.
+   * Event/output surfaces can remain discoverable while creating their tab
+   * only after an explicit command or relevant activity. */
+  readonly visibleByDefault?: boolean;
+  /** Whether a revealed utility tab may be closed. Defaults to `false`. */
+  readonly closeable?: boolean;
+}
+
+// --- Module-scope state (mirrors inspector-section-registry.ts) -----------
+
+interface StoredUtility {
+  readonly registration: WorkspaceUtilityRegistration;
+  readonly seq: number;
+}
+
+let _utilities: StoredUtility[] = [];
+let _seq = 0;
+let _version = 0;
+const _listeners = new Set<() => void>();
+
+function notifyChanged(): void {
+  _version++;
+  for (const fn of _listeners) fn();
+}
+
+/** Subscribe to (un)registrations. Returns an unsubscribe function. */
+export function subscribeWorkspaceUtilities(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => {
+    _listeners.delete(fn);
+  };
+}
+
+/** Monotonic change counter — the `getSnapshot` for `useSyncExternalStore`. */
+export function workspaceUtilityRegistryVersion(): number {
+  return _version;
+}
+
+/**
+ * Register a utility contribution. Returns an unregister function.
+ * Throws on a duplicate id — utility ids key tabs and persisted layout, so
+ * two live registrations sharing one id is always a bug (re-registration
+ * flows, e.g. project-tool HMR, unregister first — tool-loader's own
+ * discipline).
+ */
+export function registerWorkspaceUtility(registration: WorkspaceUtilityRegistration): () => void {
+  if (_utilities.some((u) => u.registration.id === registration.id)) {
+    throw new Error(
+      `registerWorkspaceUtility: id "${registration.id}" is already registered — ` +
+        'utility ids key drawer tabs and persisted layout, so they must be unique; ' +
+        'unregister the previous contribution first.',
+    );
+  }
+  const stored: StoredUtility = { registration, seq: _seq++ };
+  _utilities = [..._utilities, stored];
+  notifyChanged();
+  return () => {
+    if (!_utilities.includes(stored)) return;
+    _utilities = _utilities.filter((u) => u !== stored);
+    notifyChanged();
+  };
+}
+
+/** A registration's cluster, defaulting to the editor's own instruments. */
+export function workspaceUtilitySection(
+  registration: WorkspaceUtilityRegistration,
+): WorkspaceUtilitySection {
+  return registration.section ?? 'core';
+}
+
+function sorted(): WorkspaceUtilityRegistration[] {
+  return [..._utilities]
+    .sort(
+      (a, b) =>
+        // Section is the OUTER key: the two clusters never interleave, so the
+        // tab strip's divider is a single boundary rather than a repeated one.
+        SECTION_RANK[workspaceUtilitySection(a.registration)] -
+          SECTION_RANK[workspaceUtilitySection(b.registration)] ||
+        (a.registration.order ?? 0) - (b.registration.order ?? 0) ||
+        a.seq - b.seq,
+    )
+    .map((u) => u.registration);
+}
+
+/**
+ * The id of the tab the `project` cluster STARTS at, for a given rendered tab
+ * order — i.e. the first project-section utility that some core-section
+ * utility precedes. `null` when the order has no such boundary (one cluster
+ * only, or the project cluster leads). Pure: the caller passes the list it is
+ * actually rendering, which after a user tab-drag need not be registry order.
+ */
+export function utilitySectionBoundaryId(
+  utilities: readonly WorkspaceUtilityRegistration[],
+): string | null {
+  let sawCore = false;
+  for (const utility of utilities) {
+    if (workspaceUtilitySection(utility) === 'core') {
+      sawCore = true;
+      continue;
+    }
+    if (sawCore) return utility.id;
+  }
+  return null;
+}
+
+/**
+ * Where a NEWLY ADDED utility tab belongs among the tabs already in the
+ * drawer, per registry order — the count of existing tabs that sort at or
+ * before it. Registrations arrive at different times (core utilities at
+ * module init, project-tool contributions after the async tool load), so
+ * appending would interleave the clusters by arrival order; inserting at
+ * this index makes any arrival order converge to registry order. Ids the
+ * registry no longer knows (a stale persisted tab) sort AFTER every known
+ * one, and an unknown `id` appends. Pure: the caller passes the tab ids it
+ * is actually hosting, which after a user drag need not be registry order —
+ * rank-counting still yields a stable, in-bounds index there.
+ */
+export function utilityInsertionIndex(
+  existingIds: readonly string[],
+  id: string,
+): number | undefined {
+  const rank = new Map(availableWorkspaceUtilities().map((utility, index) => [utility.id, index]));
+  const target = rank.get(id);
+  if (target === undefined) return undefined;
+  let index = 0;
+  for (const existing of existingIds) {
+    const existingRank = rank.get(existing);
+    if (existingRank !== undefined && existingRank <= target) index += 1;
+  }
+  return index;
+}
+
+/** Every registered utility, in (order, registration-sequence) order. */
+export function registeredWorkspaceUtilities(): WorkspaceUtilityRegistration[] {
+  return sorted();
+}
+
+/** The registered utilities whose `available()` currently returns true
+ *  (guarded: a THROWING `available` counts as unavailable — a broken
+ *  contribution must not take the drawer down; same failure physics as
+ *  tool-loader's match guard). */
+export function availableWorkspaceUtilities(): WorkspaceUtilityRegistration[] {
+  return sorted().filter((u) => {
+    if (!u.available) return true;
+    try {
+      return u.available();
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** Order-preserving fingerprint of the available utility ids — a stable
+ *  STRING, so `useAvailabilitySelector` consumers (the dock's reconciler)
+ *  re-render only when the available SET changes, not on every 250ms tick. */
+export function availableUtilityFingerprint(): string {
+  return availableWorkspaceUtilities()
+    .map((u) => u.id)
+    .join('\n');
+}
+
+/** A utility's current badge (guarded: a throwing `badge` yields `null`). */
+export function workspaceUtilityBadge(id: string): WorkspaceUtilityBadge | null {
+  const found = _utilities.find((u) => u.registration.id === id);
+  if (!found?.registration.badge) return null;
+  try {
+    return found.registration.badge();
+  } catch {
+    return null;
+  }
+}
+
+/** Test-only reset (mirrors `__resetInspectorSectionRegistryForTest`). */
+export function __resetWorkspaceUtilityRegistryForTest(): void {
+  _utilities = [];
+  _seq = 0;
+  notifyChanged();
+}

package/src/kit/world-adoption-event.ts

@@ -0,0 +1,23 @@
+/**
+ * One world-adoption fact. `adopted` fires exactly once, when the trap commits
+ * to a (scene, camera, renderer) triple; `alternate` fires for each DISTINCT
+ * triple seen afterwards, up to the capture trap's `MAX_RECORDED_ALTERNATES`.
+ */
+export type WorldAdoptionEvent =
+  | {
+      readonly phase: 'adopted';
+      /** `declared` = the contract named this scene; `measured` = first render won. */
+      readonly source: 'declared' | 'measured';
+      readonly sceneId: string;
+      readonly cameraId: string;
+    }
+  | {
+      readonly phase: 'alternate';
+      readonly sceneId: string;
+      readonly cameraId: string;
+      /** `false` ⇒ a SECOND renderer is drawing, which is the stronger signal. */
+      readonly sameRenderer: boolean;
+      /** Draws observed when this alternate first appeared — how far past the
+       *  adoption it is, without a wall clock. */
+      readonly drawCount: number;
+    };