@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/asset-compare-core.ts

@@ -0,0 +1,171 @@
+/**
+ * B8.4 — pure math for the Asset Lab compare mode (the editor's `screenshot
+ * <model.glb> --compare <ref.glb>` command): silhouette masks, IoU, the overlay pixel recipe,
+ * forward-facing normalization, and the equal-height placement that lets a
+ * procedural humanoid be scored numerically against a reference GLB.
+ *
+ * Deliberately DOM/WebGL-free so the whole scoring contract is unit-testable
+ * in node (`packages/editor/test/asset-compare-core.test.ts`); the browser
+ * rendering half lives in `asset-compare.ts`.
+ */
+
+export const ASSET_COMPARE_VIEWS = ['front', 'side'] as const;
+export type AssetCompareView = (typeof ASSET_COMPARE_VIEWS)[number];
+
+/** Both models are scaled to this height, feet at y=0, centered on x=z=0. */
+export const COMPARE_TARGET_HEIGHT = 1;
+/** Fixed orthographic frame: half-height around the model's mid-height. The
+ *  10% margin keeps equal-height silhouettes fully in frame while wasting
+ *  little resolution — and, being CONSTANT, makes captures deterministic
+ *  across runs (a stated gate) and comparable across assets. */
+export const COMPARE_FRAME_HALF_HEIGHT = 0.55;
+export const COMPARE_FRAME_CENTER_Y = COMPARE_TARGET_HEIGHT / 2;
+
+/** Silhouettes render as a flat unlit white override on solid black, so the
+ *  mask threshold sits mid-range — antialiased edge pixels land on the side
+ *  of the ramp they dominate. */
+export const SILHOUETTE_LUMA_THRESHOLD = 128;
+
+/** Overlay legend (RGB). The overlay is machine-generated review evidence:
+ *  every pixel is exactly one of these four colors. */
+export const OVERLAY_BACKGROUND_RGB = [24, 26, 31] as const;
+export const OVERLAY_ASSET_ONLY_RGB = [235, 137, 52] as const; // orange — the asset under test
+export const OVERLAY_REF_ONLY_RGB = [56, 189, 248] as const; // cyan — the reference
+export const OVERLAY_OVERLAP_RGB = [236, 240, 238] as const; // near-white — agreement
+
+/**
+ * Binary silhouette mask from RGBA pixels of a white-on-black render: a
+ * pixel belongs to the silhouette when any color channel crosses the
+ * threshold. Returns one byte (0|1) per pixel.
+ */
+export function silhouetteMaskFromRgba(rgba: ArrayLike<number>, pixelCount: number): Uint8Array {
+  if (rgba.length < pixelCount * 4) {
+    throw new Error(
+      `Silhouette mask expected ${pixelCount * 4} RGBA bytes but received ${rgba.length}.`,
+    );
+  }
+  const mask = new Uint8Array(pixelCount);
+  for (let pixel = 0; pixel < pixelCount; pixel++) {
+    const offset = pixel * 4;
+    const value =
+      rgba[offset]! >= SILHOUETTE_LUMA_THRESHOLD ||
+      rgba[offset + 1]! >= SILHOUETTE_LUMA_THRESHOLD ||
+      rgba[offset + 2]! >= SILHOUETTE_LUMA_THRESHOLD;
+    mask[pixel] = value ? 1 : 0;
+  }
+  return mask;
+}
+
+export interface MaskOverlapStats {
+  intersection: number;
+  union: number;
+  aCount: number;
+  bCount: number;
+  /** intersection / union; 0 when the union is empty (guard emptiness upstream). */
+  iou: number;
+}
+
+/** Silhouette intersection-over-union between two same-length binary masks. */
+export function maskIoU(a: Uint8Array, b: Uint8Array): MaskOverlapStats {
+  if (a.length !== b.length) {
+    throw new Error(`Mask IoU requires equal-size masks (${a.length} vs ${b.length}).`);
+  }
+  let intersection = 0;
+  let aCount = 0;
+  let bCount = 0;
+  for (let index = 0; index < a.length; index++) {
+    const inA = a[index] !== 0;
+    const inB = b[index] !== 0;
+    if (inA) aCount++;
+    if (inB) bCount++;
+    if (inA && inB) intersection++;
+  }
+  const union = aCount + bCount - intersection;
+  return { intersection, union, aCount, bCount, iou: union === 0 ? 0 : intersection / union };
+}
+
+/**
+ * The compare overlay: both silhouettes on one image in visibly distinct
+ * colors — asset-only orange, reference-only cyan, agreement near-white on a
+ * dark background. Returns opaque RGBA bytes ready for an ImageData.
+ */
+export function overlayRgba(
+  assetMask: Uint8Array,
+  refMask: Uint8Array,
+): Uint8ClampedArray<ArrayBuffer> {
+  if (assetMask.length !== refMask.length) {
+    throw new Error(
+      `Overlay requires equal-size masks (${assetMask.length} vs ${refMask.length}).`,
+    );
+  }
+  const out = new Uint8ClampedArray(assetMask.length * 4);
+  for (let pixel = 0; pixel < assetMask.length; pixel++) {
+    const inAsset = assetMask[pixel] !== 0;
+    const inRef = refMask[pixel] !== 0;
+    const color =
+      inAsset && inRef
+        ? OVERLAY_OVERLAP_RGB
+        : inAsset
+          ? OVERLAY_ASSET_ONLY_RGB
+          : inRef
+            ? OVERLAY_REF_ONLY_RGB
+            : OVERLAY_BACKGROUND_RGB;
+    const offset = pixel * 4;
+    out[offset] = color[0];
+    out[offset + 1] = color[1];
+    out[offset + 2] = color[2];
+    out[offset + 3] = 255;
+  }
+  return out;
+}
+
+/** A structurally valid forward vector ([x,y,z], finite, non-degenerate in
+ *  the ground plane) or null — used to read GLB `extras`/`userData.forward`
+ *  without trusting arbitrary content. */
+export function parseForwardVector(value: unknown): [number, number, number] | null {
+  if (!Array.isArray(value) || value.length !== 3) return null;
+  const [x, y, z] = value as unknown[];
+  if (typeof x !== 'number' || typeof y !== 'number' || typeof z !== 'number') return null;
+  if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) return null;
+  if (Math.hypot(x, z) < 1e-6) return null; // vertical/zero forward cannot define a facing
+  return [x, y, z];
+}
+
+/**
+ * The Y rotation (radians) that turns a model whose forward is `forward`
+ * to face +Z — the direction the fixed front camera looks from. Facing is a
+ * ground-plane property; the vector's y component is ignored.
+ */
+export function forwardYawRadians(forward: readonly [number, number, number]): number {
+  const [x, , z] = forward;
+  if (!Number.isFinite(x) || !Number.isFinite(z) || Math.hypot(x, z) < 1e-6) {
+    throw new Error(`Cannot derive a facing from forward vector [${forward.join(', ')}].`);
+  }
+  return Math.atan2(x, z);
+}
+
+export interface NormalizedPlacement {
+  scale: number;
+  /** Applied AFTER the scale: ground at y=0, footprint centered at x=z=0. */
+  position: [number, number, number];
+}
+
+/**
+ * Bounding-box height normalization (the decided compare framing): scale the
+ * model so its bounds stand `targetHeight` tall, then place it with its
+ * ground plane at y=0 and its bounds center on the x=0/z=0 axis.
+ */
+export function normalizedPlacement(
+  min: readonly [number, number, number],
+  max: readonly [number, number, number],
+  targetHeight: number = COMPARE_TARGET_HEIGHT,
+): NormalizedPlacement {
+  const height = max[1] - min[1];
+  if (!Number.isFinite(height) || height <= 0) {
+    throw new Error(`Compare normalization needs positive model height, got ${height}.`);
+  }
+  const scale = targetHeight / height;
+  const centerX = (min[0] + max[0]) / 2;
+  const centerZ = (min[2] + max[2]) / 2;
+  return { scale, position: [-centerX * scale, -min[1] * scale, -centerZ * scale] };
+}

package/src/kit/asset-editor-context.tsx

@@ -0,0 +1,101 @@
+/**
+ * Context contributed by the active typed Asset Editor to the existing editor
+ * shell. Asset documents own content; the workspace owns placement. Keeping
+ * this as a tiny external store lets the status bar and the workspace's
+ * inspection surface resolution know WHICH document is active without an
+ * Asset Editor recreating those panes inside the center.
+ *
+ * It carries FACTS ONLY — id, title, type, status. Never markup: an open
+ * asset document is a SUBJECT PRODUCER, and what it produces goes through the
+ * one composer into the one inspector box like everything else. A React node
+ * put on this store would be a second, invisible way for a document to render
+ * somewhere else, and there is exactly one.
+ */
+
+import { useSyncExternalStore } from 'react';
+import { createHmrRegistrationGroup, type HmrRegistrationContext } from '@volter/sdk/kit/hmr-registration-group';
+import { registerWorkspaceStatus } from './workspace-status-registry';
+
+export interface AssetEditorContextValue {
+  readonly documentId: string;
+  readonly title: string;
+  readonly type: string;
+  readonly status?: string;
+}
+
+interface ActiveAssetEditorContext extends AssetEditorContextValue {
+  readonly token: symbol;
+}
+
+let active: ActiveAssetEditorContext | null = null;
+let version = 0;
+const listeners = new Set<() => void>();
+
+function notifyChanged(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeAssetEditorContext(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function assetEditorContextVersion(): number {
+  return version;
+}
+
+export function getActiveAssetEditorContext(): AssetEditorContextValue | null {
+  return active;
+}
+
+/** Activate one document contribution. The returned disposer only clears the
+ * exact activation it created, so an older tab unmount cannot erase a newer
+ * active tab's context. */
+export function activateAssetEditorContext(value: AssetEditorContextValue): () => void {
+  const token = Symbol(value.documentId);
+  active = { ...value, token };
+  notifyChanged();
+  return () => {
+    if (active?.token !== token) return;
+    active = null;
+    notifyChanged();
+  };
+}
+
+export function AssetEditorStatus() {
+  useSyncExternalStore(subscribeAssetEditorContext, assetEditorContextVersion);
+  const context = getActiveAssetEditorContext();
+  return context?.status ? (
+    <span className="volter-status-copy" data-testid="status-asset-editor" data-status-tone="muted">
+      {context.status}
+    </span>
+  ) : null;
+}
+
+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,
+  'asset-editor-shell-contributions',
+);
+
+export function ensureAssetEditorShellContributionsRegistered(): void {
+  registrationGroup.ensure((track) => {
+    track(
+      registerWorkspaceStatus({
+        id: 'asset-editor-status',
+        name: 'Asset editor',
+        align: 'left',
+        order: 40,
+        Content: AssetEditorStatus,
+      }),
+    );
+  });
+}
+
+ensureAssetEditorShellContributionsRegistered();
+
+export function __resetAssetEditorContextForTest(): void {
+  active = null;
+  notifyChanged();
+}

package/src/kit/asset-events.ts

@@ -0,0 +1,96 @@
+import { connectEvents } from '@volter/sdk/kit/editor-api';
+import { announceAssetReload } from '@volter/sdk/kit/project-asset-refresh';
+
+export interface AssetMovedEvent {
+  oldPath: string;
+  newPath: string;
+  updatedFiles: string[];
+}
+
+export interface AssetsChangedEvent {
+  readonly paths?: readonly string[];
+}
+
+/**
+ * Connect to the editor server's SSE endpoint for asset events.
+ * Returns a cleanup function to disconnect.
+ */
+export function connectAssetEvents(
+  onAssetMoved: (event: AssetMovedEvent) => void,
+  onAssetsChanged: (event: AssetsChangedEvent) => void = () => {},
+): () => void {
+  // Browser mode (Phase A2): no Node dev server / SSE. A rename can't be
+  // reconstructed from self-derived watch events — a move surfaces as an
+  // unlinked `remove` + `create` with no old→new pairing — so asset-move sync
+  // stays a server-only signal (revisit with A4's external-change detection).
+  const source = connectEvents();
+
+  source.addEventListener('asset-moved', (e: MessageEvent) => {
+    try {
+      const data = JSON.parse(e.data) as AssetMovedEvent;
+      onAssetMoved(data);
+    } catch {
+      /* ignore malformed events */
+    }
+  });
+  source.addEventListener('assets-changed', (event: MessageEvent) => {
+    let detail: AssetsChangedEvent;
+    try {
+      detail = JSON.parse(event.data) as AssetsChangedEvent;
+    } catch {
+      detail = {};
+    }
+    const paths =
+      detail.paths?.map((path) => `/${path.replace(/^\/?public\//, '').replace(/^\//, '')}`) ?? [];
+    announceAssetReload(paths);
+    onAssetsChanged(detail);
+  });
+
+  return () => source.close();
+}
+
+export function connectToolFileEvents(onChanged: () => void): () => void {
+  const source = connectEvents();
+  source.addEventListener('tool-files-changed', () => onChanged());
+  return () => source.close();
+}
+
+/** Root declarations affect project configuration and adapter capabilities. */
+export function connectProjectDeclarationEvents(onChanged: () => void): () => void {
+  const source = connectEvents();
+  source.addEventListener('project-declarations-changed', onChanged);
+  return () => source.close();
+}
+
+/**
+ * Connect to the editor server's SSE endpoint for project STORY file
+ * add/unlink events (C3, spec §9). Mirrors `connectToolFileEvents` for
+ * `*.stories.tsx` / `*.stories.ts` anywhere under `src/` — the React hierarchy's
+ * `refreshProjectStories()` is a cheap full rescan, same discipline as
+ * `refreshProjectTools`.
+ */
+/**
+ * The editor server's `source-files-changed`: any `src/` file that is neither
+ * a tool nor a story — the files contributed FINDERS read (a models project's
+ * `src/models/*.ts`). Carries the project-relative path; the browser lane
+ * cannot name one and reports `''`.
+ */
+export function connectSourceFileEvents(onChanged: (path: string) => void): () => void {
+  const source = connectEvents();
+  source.addEventListener('source-files-changed', (event) => {
+    let path = '';
+    try {
+      path = String((JSON.parse((event as MessageEvent).data) as { path?: string }).path ?? '');
+    } catch {
+      /* a payload without a path still means "something changed" */
+    }
+    onChanged(path);
+  });
+  return () => source.close();
+}
+
+export function connectStoryFileEvents(onChanged: () => void): () => void {
+  const source = connectEvents();
+  source.addEventListener('story-files-changed', () => onChanged());
+  return () => source.close();
+}

package/src/kit/asset-inspector-actions.ts

@@ -0,0 +1,87 @@
+/**
+ * The verbs an `asset.inspector` contribution offers for the asset it is
+ * currently showing — published BY the section, because the section is what
+ * knows.
+ *
+ * WHY NOT A STATIC EXPORT. The first shape of this was `export const
+ * actions(asset)`, resolved synchronously beside `match(asset)`. It could
+ * only filter on the path, while the section itself decides structurally —
+ * the Edit Mesh door imports the module and calls `build()` — so the panel
+ * and `inspect().quickActions` disagreed: measured 2026-09-03, every `src/**`
+ * script offered "Edit mesh" through the control API while the human saw the
+ * button on mesh modules alone. A verb the human cannot see is exactly what
+ * `editor.inspect()` promises never to report, so the declaration moved to
+ * where the answer is.
+ *
+ * The section calls `props.setActions(...)` when it knows (and `[]` when it
+ * knows the answer is no); this store keys the list by contribution and
+ * asset, so a stale answer for a previous selection can never be served, and
+ * bumps a version `inspection/use-active-inspection.ts` subscribes to, the
+ * same way the section registry does.
+ */
+import type { ToolAssetInspectorAction } from '@volter/sdk/contributions';
+
+interface Published {
+  readonly assetPath: string;
+  readonly actions: readonly ToolAssetInspectorAction[];
+}
+
+const published = new Map<string, Published>();
+let version = 0;
+const listeners = new Set<() => void>();
+
+function changed(): void {
+  version += 1;
+  for (const listener of listeners) listener();
+}
+
+/** Publish (or clear) one contribution's verbs for the asset it is showing. */
+export function setAssetInspectorActions(
+  contributionId: string,
+  assetPath: string,
+  actions: readonly ToolAssetInspectorAction[],
+): void {
+  const current = published.get(contributionId);
+  if (
+    current &&
+    current.assetPath === assetPath &&
+    current.actions.length === actions.length &&
+    current.actions.every((action, i) => action === actions[i])
+  ) {
+    return;
+  }
+  published.set(contributionId, { assetPath, actions });
+  changed();
+}
+
+/** Forget a contribution's verbs (its section unmounted). */
+export function clearAssetInspectorActions(contributionId: string): void {
+  if (!published.delete(contributionId)) return;
+  changed();
+}
+
+/** Every verb published FOR this asset, in contribution registration order.
+ *  A list published for a different asset is ignored rather than served. */
+export function assetInspectorActionsFor(assetPath: string): readonly ToolAssetInspectorAction[] {
+  const out: ToolAssetInspectorAction[] = [];
+  for (const entry of published.values()) {
+    if (entry.assetPath !== assetPath) continue;
+    out.push(...entry.actions);
+  }
+  return out;
+}
+
+export function subscribeAssetInspectorActions(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function assetInspectorActionsVersion(): number {
+  return version;
+}
+
+/** Test seam, mirroring the other module-scope stores. */
+export function __resetAssetInspectorActionsForTest(): void {
+  published.clear();
+  version = 0;
+}

package/src/kit/asset-selection-viewer-registry.ts

@@ -0,0 +1,113 @@
+/**
+ * WHO DRAWS *THIS* SELECTED ASSET — the tenth registry in the family of
+ * `workspace-document-restore.ts` (a kind owns its persisted state),
+ * `document-open-registry.ts` (a kind owns how it opens),
+ * `chrome-slot-registry.ts` (the host owns the place, a package owns what
+ * sits there), `content-entry-source-registry.ts` (the host owns the Content
+ * scope, a package owns why a component is content),
+ * `authoring/design-time-mount-registry.ts`, `component-board-registry.ts`,
+ * `component-states-registry.ts` and `static-panel-presentation-registry.ts`.
+ * Here: the host owns the Inspector's asset SECTION — the thumbnail, the
+ * metadata rows, the tool sections, the empty state — and a package owns the
+ * body for an asset the host has no way to draw.
+ *
+ * WHY IT EXISTS. `components/asset-selection-section.tsx` opened with
+ * `if (asset.online) { … <OnlineAssetDetail/> … }` — the Inspector knowing
+ * that an asset can come from an external catalog, and importing that
+ * catalog's whole detail view (421 lines, plus the import-job ledger it
+ * writes) into every editor boot, a `models` build that has no catalog
+ * included (WORK.md §The open-source launch, the final audit's online-library
+ * row). The sibling of `contentEntryForComponent`: one question — "is there a
+ * registered body for this subject, and what is it" — asked of a registry
+ * instead of answered by a branch.
+ *
+ * THE SHAPE is transcribed from `content-entry-source-registry.ts` (register /
+ * list / subscribe, owner-replaces-owner for an HMR re-evaluation, a stable
+ * EMPTY array so a reader's `useSyncExternalStore` snapshot is stable). TWO
+ * deliberate differences:
+ *  - NO per-registration `subscribe` to re-fan. A content SOURCE has a ledger
+ *    that settles asynchronously; a viewer is a pure function of the asset
+ *    the host already re-renders on. The registry's own change signal is all
+ *    a reader needs, and a hook with nothing to subscribe to is a name that
+ *    got built because it was named.
+ *  - `match(asset)` IS THE WHOLE DISCRIMINATOR. The host never asks "is this
+ *    online" again; it asks who claims the asset. First match wins, in
+ *    registration order, so a build with no catalog package falls through to
+ *    the host's own generic body — which is the answer it always gave for
+ *    every asset that was not online.
+ *
+ * NOTHING REGISTERED IS A REAL ANSWER: the generic body, exactly as before.
+ */
+
+import type { ComponentType } from 'react';
+import type { SelectedAsset } from '@volter/sdk/kit/asset-selection';
+
+export interface AssetSelectionViewerProps {
+  readonly asset: SelectedAsset;
+}
+
+export interface AssetSelectionViewer {
+  /** The viewer's id, in its own vocabulary. */
+  readonly id: string;
+  /** Which module registered it. Re-registering the same owner+id REPLACES. */
+  readonly owner: string;
+  /** Ascending; ties keep registration order. */
+  readonly order?: number;
+  /** Does this viewer claim the selected asset? The host asks; it never
+   *  inspects the asset for a lane's own fields itself. */
+  readonly match: (asset: SelectedAsset) => boolean;
+  /** The Inspector body for a claimed asset, rendered INSTEAD of the host's
+   *  generic one — the viewer owns everything below the section's frame,
+   *  including any actions it wants. */
+  readonly View: ComponentType<AssetSelectionViewerProps>;
+}
+
+const _viewers: AssetSelectionViewer[] = [];
+const listeners = new Set<() => void>();
+let version = 0;
+
+function publish(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+/** Install a viewer. Returns the teardown. */
+export function registerAssetSelectionViewer(viewer: AssetSelectionViewer): () => void {
+  const stale = _viewers.findIndex((item) => item.owner === viewer.owner && item.id === viewer.id);
+  if (stale >= 0) _viewers.splice(stale, 1);
+  _viewers.push(viewer);
+  _viewers.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  publish();
+  return () => {
+    const at = _viewers.indexOf(viewer);
+    if (at < 0) return;
+    _viewers.splice(at, 1);
+    publish();
+  };
+}
+
+/** The first registered viewer that claims this asset, or `null` — "nobody
+ *  registered a body for it", which is a real answer and never an error. */
+export function assetSelectionViewerFor(asset: SelectedAsset): AssetSelectionViewer | null {
+  for (const viewer of _viewers) if (viewer.match(asset)) return viewer;
+  return null;
+}
+
+/** ONE subscription for the Inspector section. */
+export function subscribeAssetSelectionViewers(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function assetSelectionViewersVersion(): number {
+  return version;
+}
+
+/** Test-only reset (mirrors the restore, open, chrome-slot, content-source,
+ *  design-time-mount, component-board and static-panel registries'). */
+export function __resetAssetSelectionViewersForTest(): void {
+  _viewers.length = 0;
+  publish();
+}