@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/workspace-utility-registry.ts

@@ -0,0 +1,161 @@
+/**
+ * Workspace UTILITY registry (W0, docs/EDITOR-WORKSPACE-SHELL-TODO.md §7 —
+ * the shell-contract slice of §9 W0). Utilities are the TRANSIENT
+ * output/debug surfaces of §1.4/§5: Console, Problems, Build Output, Debug
+ * Console, story-scoped addon results, and project `placement: 'utility'`
+ * tools. They live in the collapsible bottom drawer (closed by default from
+ * W4 on) — never substantial editors, which are documents
+ * (`workspace-document-registry.ts`).
+ *
+ * `components/WorkspaceDock.tsx` renders default-visible registrations as
+ * Dockview panels in the collapsed-by-default bottom edge group. Other
+ * registrations remain addressable by semantic commands and are created on
+ * demand (built-ins register via `components/core-utilities.tsx`;
+ * migration map: docs/workspace-shell/W0-INVENTORY.md).
+ *
+ * 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 may surface on its collapsed tab (the Console
+ *  error/warn count is the worked first-party example). */
+export interface WorkspaceUtilityBadge {
+  readonly count: number;
+  readonly severity: 'info' | 'warn' | 'error';
+}
+
+/** 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;
+  /** 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. Debug Console / Machine Events
+   *  exist only while a live play 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 belongs in a clean default layout. Defaults to `true`.
+   * Event/output surfaces can remain registered and discoverable while
+   * appearing 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 (docs/EDITOR-WORKSPACE-SHELL-TODO.md §7).',
+    );
+  }
+  const stored: StoredUtility = { registration, seq: _seq++ };
+  _utilities = [..._utilities, stored];
+  notifyChanged();
+  return () => {
+    if (!_utilities.includes(stored)) return;
+    _utilities = _utilities.filter((u) => u !== stored);
+    notifyChanged();
+  };
+}
+
+function sorted(): WorkspaceUtilityRegistration[] {
+  return [..._utilities]
+    .sort((a, b) => (a.registration.order ?? 0) - (b.registration.order ?? 0) || a.seq - b.seq)
+    .map((u) => u.registration);
+}
+
+/** 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;
+    }
+  });
+}
+
+/** 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/world-document-routing.ts

@@ -0,0 +1,16 @@
+import { activateWorkspaceDocument } from './workspace-document-registry';
+
+const _documentIdByWorld = new Map<string, string>();
+
+export function registerWorldDocumentRoute(worldId: string, documentId: string): () => void {
+  _documentIdByWorld.set(worldId, documentId);
+  return () => {
+    if (_documentIdByWorld.get(worldId) === documentId) _documentIdByWorld.delete(worldId);
+  };
+}
+
+/** Activate the edit-time document that owns a manifest world. */
+export function activateWorldDocument(worldId: string): boolean {
+  const documentId = _documentIdByWorld.get(worldId);
+  return documentId ? activateWorkspaceDocument(documentId) : false;
+}