@volter/editor-core 0.5.57

package/src/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/workspace-viewport-rect.ts

@@ -0,0 +1,97 @@
+/**
+ * The CENTER (viewport) group's live rect in dock-root-local coordinates.
+ * The workspace host is the sole writer because the frame owns this geometry —
+ * Consumers are
+ * overlays that belong to the VIEWPORT rather than the whole workspace
+ * (the compact inspector card clamps itself inside this rect), without
+ * measuring the layout themselves.
+ */
+
+export interface WorkspaceViewportRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+let rect: WorkspaceViewportRect | null = null;
+let version = 0;
+const listeners = new Set<() => void>();
+
+export function workspaceViewportRect(): WorkspaceViewportRect | null {
+  return rect;
+}
+
+export function workspaceViewportRectVersion(): number {
+  return version;
+}
+
+export function subscribeWorkspaceViewportRect(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function setWorkspaceViewportRect(next: WorkspaceViewportRect | null): void {
+  const same =
+    rect === next ||
+    (rect !== null &&
+      next !== null &&
+      rect.x === next.x &&
+      rect.y === next.y &&
+      rect.width === next.width &&
+      rect.height === next.height);
+  if (same) return;
+  rect = next;
+  version += 1;
+  for (const listener of listeners) listener();
+}
+
+// ---- Viewport-owned overlay placement (pure — headlessly testable) --------
+
+/** Offsets of an overlay's bottom-right corner from the VIEWPORT's
+ *  bottom-right corner. Bottom-right anchoring keeps a corner-hugging
+ *  overlay hugging its corner under viewport resizes, wherever it was
+ *  dragged. */
+export interface ViewportOverlayAnchor {
+  readonly right: number;
+  readonly bottom: number;
+}
+
+export interface ViewportOverlaySizing {
+  readonly maxWidth: number;
+  readonly maxHeight: number;
+  /** Floor when the viewport is too small for the full size. */
+  readonly minSize: number;
+  /** Breathing room kept between the overlay and every viewport edge. */
+  readonly margin: number;
+}
+
+/** The overlay's size and top-left for a given anchor, clamped fully inside
+ *  the viewport (pinned toward the top-left edge when the viewport is
+ *  smaller than the overlay + margins). */
+export function resolveViewportOverlayPlacement(
+  viewport: WorkspaceViewportRect,
+  sizing: ViewportOverlaySizing,
+  anchor: ViewportOverlayAnchor,
+): { left: number; top: number; width: number; height: number } {
+  const width = Math.min(
+    sizing.maxWidth,
+    Math.max(sizing.minSize, viewport.width - sizing.margin * 2),
+  );
+  const height = Math.min(
+    sizing.maxHeight,
+    Math.max(sizing.minSize, viewport.height - sizing.margin * 2),
+  );
+  const minLeft = viewport.x + sizing.margin;
+  const maxLeft = viewport.x + viewport.width - width - sizing.margin;
+  const minTop = viewport.y + sizing.margin;
+  const maxTop = viewport.y + viewport.height - height - sizing.margin;
+  const left = viewport.x + viewport.width - anchor.right - width;
+  const top = viewport.y + viewport.height - anchor.bottom - height;
+  return {
+    width,
+    height,
+    left: Math.min(Math.max(left, minLeft), Math.max(maxLeft, minLeft)),
+    top: Math.min(Math.max(top, minTop), Math.max(maxTop, minTop)),
+  };
+}

package/src/world-adoption.ts

@@ -0,0 +1,115 @@
+/**
+ * WORLD-ADOPTION AMBIGUITY — the reader for what the capture trap decided, and
+ * for every world it saw afterwards and did not adopt.
+ *
+ * `@volter/editor-threejs/adapter/ingest/scene-capture` adopts a self-booting game's world on
+ * the first non-host render. That is a sound MEASURED default and a permanent,
+ * silent commitment: a splash scene, a shadow pre-pass or a render-to-texture
+ * warm-up that happens to draw first is adopted as the game forever, and the
+ * real world drawing one frame later reached nobody.
+ *
+ * This module does not change the decision (ARCHITECTURE-CORE §The editor
+ * protocol: a diagnostic diagnoses; it does not silently re-pick). It records
+ * the adoption's PROVENANCE — `declared` when the game's contract named the
+ * scene, `measured` when first-render-wins ran — and every distinct
+ * (scene, camera) pair seen after it, and publishes both as the `worldAdoption`
+ * facet of `/__editor/state`.
+ *
+ * Alternates are INFORMATION, not an error: a post-processing chain renders
+ * several pairs per frame by design. The facet says how many and which, and the
+ * `ambiguity` sentence exists so a reader chasing "the editor is showing the
+ * wrong scene" has one place that already knows there was a choice.
+ */
+
+import type { WorldAdoptionEvent } from '@volter/editor-threejs/adapter/ingest/scene-capture';
+
+export interface WorldAdoptionAlternate {
+  readonly sceneId: string;
+  readonly cameraId: string;
+  /** `false` ⇒ a SECOND renderer is drawing — the stronger signal that the
+   *  adopted world may not be the one on screen. */
+  readonly sameRenderer: boolean;
+  readonly drawCount: number;
+}
+
+export interface WorldAdoption {
+  readonly rootId: string;
+  /** `declared` = the game's contract named this scene; `measured` = the trap's
+   *  first-non-host-render default decided. */
+  readonly source: 'declared' | 'measured';
+  readonly sceneId: string;
+  readonly cameraId: string;
+  /** Distinct worlds seen AFTER the adopted one, capped by the trap's own
+   *  `MAX_RECORDED_ALTERNATES`. */
+  readonly alternates: readonly WorldAdoptionAlternate[];
+  /** Present iff `alternates` is non-empty — the one sentence, spelled once. */
+  readonly ambiguity?: string;
+}
+
+/** RESOURCE OWNERSHIP: one entry per self-booting root, written through
+ *  {@link worldAdoptionRecorder} by the mount that installed the capture trap,
+ *  and dropped by that mount's teardown ({@link clearWorldAdoption}). */
+const _adoptions = new Map<
+  string,
+  {
+    source: 'declared' | 'measured';
+    sceneId: string;
+    cameraId: string;
+    alternates: WorldAdoptionAlternate[];
+  }
+>();
+
+/**
+ * The `onWorldAdoption` handler a mount hands to `installSceneCapture`, bound
+ * to one root id. One door: the mount passes this straight through, so nothing
+ * in the editor transcribes the engine's event shape a second time.
+ */
+export function worldAdoptionRecorder(rootId: string): (event: WorldAdoptionEvent) => void {
+  return (event) => {
+    if (event.phase === 'adopted') {
+      _adoptions.set(rootId, {
+        source: event.source,
+        sceneId: event.sceneId,
+        cameraId: event.cameraId,
+        alternates: [],
+      });
+      return;
+    }
+    // An alternate before an adoption cannot happen (the trap only reports one
+    // after it has committed), so a missing entry here means this root's
+    // adoption was already torn down — drop it rather than resurrect the root.
+    const entry = _adoptions.get(rootId);
+    if (!entry) return;
+    entry.alternates.push({
+      sceneId: event.sceneId,
+      cameraId: event.cameraId,
+      sameRenderer: event.sameRenderer,
+      drawCount: event.drawCount,
+    });
+  };
+}
+
+export function clearWorldAdoption(rootId: string): void {
+  _adoptions.delete(rootId);
+}
+
+export function worldAdoptionFacet(): readonly WorldAdoption[] {
+  return [..._adoptions].map(([rootId, entry]) => ({
+    rootId,
+    source: entry.source,
+    sceneId: entry.sceneId,
+    cameraId: entry.cameraId,
+    alternates: [...entry.alternates],
+    ...(entry.alternates.length > 0
+      ? {
+          ambiguity:
+            `"${rootId}" rendered ${entry.alternates.length} other world(s) after the one the ` +
+            `editor adopted (${entry.source}: ${entry.sceneId}). The adopted world is unchanged; ` +
+            'if the editor is showing the wrong scene, one of these is it: ' +
+            entry.alternates
+              .map((alt) => `${alt.sceneId}${alt.sameRenderer ? '' : ' (a SECOND renderer)'}`)
+              .join(', '),
+        }
+      : {}),
+  }));
+}

package/src/world-document-routing.ts

@@ -0,0 +1,104 @@
+import {
+  availableWorkspaceDocuments,
+  openAvailableWorkspaceDocument,
+} from './workspace-available-documents';
+import { activateWorkspaceDocument } from './workspace-document-registry';
+
+const _documentIdByRoot = new Map<string, string>();
+
+export function registerRootDocumentRoute(worldId: string, documentId: string): () => void {
+  _documentIdByRoot.set(worldId, documentId);
+  return () => {
+    if (_documentIdByRoot.get(worldId) === documentId) _documentIdByRoot.delete(worldId);
+  };
+}
+
+/** The edit-time document that owns a manifest world, or `null` when the
+ *  session installed none. Read by the Edit tab row, whose `root-mount` scene
+ *  entries NAME a standing document rather than adding one
+ *  (`components/scene-documents.tsx`). */
+export function rootDocumentId(worldId: string): string | null {
+  return (
+    _documentIdByRoot.get(worldId) ??
+    availableWorkspaceDocuments().find((document) => document.rootId === worldId)?.descriptor.id ??
+    null
+  );
+}
+
+/** Activate the edit-time document that owns a manifest world. */
+export function activateRootDocument(worldId: string): boolean {
+  const documentId = rootDocumentId(worldId);
+  return documentId
+    ? openAvailableWorkspaceDocument(documentId) || activateWorkspaceDocument(documentId)
+    : false;
+}
+
+const _gapByRoot = new Map<string, () => string | null>();
+
+/**
+ * Register the reason a root has NO document to activate — the DECIDED half of
+ * {@link activateRootDocument}'s `false`.
+ *
+ * A root's document is installed asynchronously, so `false` from
+ * `activateRootDocument` means one of two opposite things: "not yet" (boot in
+ * flight) or "never" (this session has settled that this root has no design
+ * surface of its own). Callers cannot tell them apart, so every caller waits
+ * out the full registration window even for an answer that was decided in the
+ * first second — long enough that the asking side has usually given up before
+ * the refusal is spoken.
+ *
+ * The `reason` is a THUNK, evaluated live at each ask, precisely so it can keep
+ * answering `null` while the document may still arrive and only speak once the
+ * question is settled. It is registered by whoever OWNS the decision — the
+ * presenter must never infer why a document is absent.
+ */
+export function registerRootDocumentGap(worldId: string, reason: () => string | null): () => void {
+  _gapByRoot.set(worldId, reason);
+  return () => {
+    if (_gapByRoot.get(worldId) === reason) _gapByRoot.delete(worldId);
+  };
+}
+
+/** Why this root has no document to activate, when that is decided; `null`
+ *  while one may still arrive. */
+export function rootDocumentGap(worldId: string): string | null {
+  return _gapByRoot.get(worldId)?.() ?? null;
+}
+
+const _workspaceGaps = new Set<(documentId: string) => string | null>();
+
+/**
+ * The same DECIDED half, for a workspace document asked for by id.
+ *
+ * `activateWorkspaceDocument` returns `false` with the identical ambiguity
+ * {@link registerRootDocumentGap} describes — "not yet" and "never" are one
+ * answer — and a workspace document has the further case a root cannot have:
+ * the id may name nothing at all. Both are the same question ("why is this
+ * document not here?"), so they share this mechanism rather than growing a
+ * second one; the arms differ only in their KEY, because a root is asked for
+ * by manifest id and a workspace document by document id.
+ *
+ * The resolver takes the requested id rather than being registered per id,
+ * because the ids that will never exist cannot be enumerated in advance — the
+ * owner answers for the whole namespace it installs into. Same thunk contract:
+ * `null` means "no verdict" (boot in flight, or not this owner's question),
+ * and the first owner to speak wins.
+ */
+export function registerWorkspaceDocumentGap(
+  reason: (documentId: string) => string | null,
+): () => void {
+  _workspaceGaps.add(reason);
+  return () => {
+    _workspaceGaps.delete(reason);
+  };
+}
+
+/** Why this workspace document is not here, when that is decided; `null` while
+ *  one may still arrive. */
+export function workspaceDocumentGap(documentId: string): string | null {
+  for (const reason of _workspaceGaps) {
+    const answer = reason(documentId);
+    if (answer !== null) return answer;
+  }
+  return null;
+}