@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/content-entry-source-registry.ts

@@ -0,0 +1,184 @@
+/**
+ * A CONTENT ENTRY IS SOURCED, NOT DERIVED — the fourth 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) and
+ * `chrome-slot-registry.ts` (the host owns the place, a package owns what sits
+ * there). Here: the host owns the Content SCOPE — the grid, the chips, the
+ * sort, the search, the selection and the drag — and a package owns WHY a
+ * project component is content at all, what it looks like, and what opening it
+ * means.
+ *
+ * WHY IT EXISTS. The Content scope of `components/AssetBrowser.tsx` already
+ * concatenates two sources it does not own: the active adapter facet's
+ * document entries and `liveAuthoringAssets(adapter)`. A THIRD was hard-wired
+ * — `pickComponentPreviewStory` decided which components were content and
+ * `StoryComponentThumbnail` painted them — which made the host's Content
+ * browser know what portable CSF is, and dragged the story registry (and
+ * therefore Storybook) into every editor boot, a `models` build that authors
+ * no stories included (WORK.md §Stories leave the host, edge 1 — the ONE new
+ * door that design mints). The shape is transcribed from
+ * `chrome-slot-registry.ts`: register / list / subscribe / version, with the
+ * same owner-replaces-owner rule for an HMR re-evaluation.
+ *
+ * NOTHING REGISTERED IS A REAL ANSWER. A build whose package list carries no
+ * content source lists documents and assets and no component tiles — the same
+ * honest emptiness a document kind with no registered opener gives.
+ *
+ * WHAT THE HOST STILL OWNS, and why it is not a leak: the COMPONENT INDEX
+ * (`services.listProjectComponents()`, the server's own scan) is the host's,
+ * and it is handed to every source as context. A source answers "which of
+ * these, and why" — it never rescans the project.
+ */
+
+import type { AdapterSurface } from '@volter/project/adapter';
+import type { ComponentType } from 'react';
+import type { ProjectComponentEntry } from '@volter/sdk/kit/asset-workflow/project-content';
+import type { WorkspaceStateStore } from './workspace-document-restore';
+
+/**
+ * A component as a SOURCE sees it: what it is called, where its module is,
+ * which surface it mounts on. Deliberately narrower than the host's own index
+ * row (`ProjectComponentEntry`, which is assignable to it), because the other
+ * caller of this registry has exactly these three facts and no index: the
+ * Inspector, asking for the picture of ONE component.
+ */
+export interface ContentComponentRef {
+  readonly name: string;
+  readonly path: string;
+  readonly surface: ProjectComponentEntry['surface'];
+}
+
+/** What a source is asked ABOUT: components, and the surface the question is
+ *  focused on (`null` = no active authoring surface, so nothing is filtered
+ *  out by surface). The Content scope passes its whole index; the Inspector
+ *  passes one. */
+export interface ContentEntrySourceContext {
+  readonly components: readonly ContentComponentRef[];
+  readonly surface: AdapterSurface | null;
+}
+
+/** One admitted component. `detail` is the source's own reason — opaque to the
+ *  host, handed back to the source's `Thumbnail` and `open`. */
+export interface ContentEntry {
+  /** Unique within the source; the host keys its row on `<source>:<id>`. */
+  readonly id: string;
+  /** The component this entry depicts — the very ref the source was given. */
+  readonly component: ContentComponentRef;
+  /** The source's own reason, opaque by construction: only the source that
+   *  minted the entry ever reads it, and it casts. */
+  readonly detail: unknown;
+}
+
+export interface ContentEntryThumbnailProps {
+  readonly entry: ContentEntry;
+  /** Bumped by the panel when a preview must be re-taken. */
+  readonly previewRevision: number;
+  readonly width?: number;
+  readonly height?: number;
+}
+
+export interface ContentEntrySource {
+  /** The source's id, in its own vocabulary. Part of every row key. */
+  readonly id: string;
+  /** Which module registered it. Re-registering the same owner+id REPLACES,
+   *  so an HMR re-evaluation leaves one source, not two. */
+  readonly owner: string;
+  /** Ascending; ties keep registration order. */
+  readonly order?: number;
+  readonly entries: (context: ContentEntrySourceContext) => readonly ContentEntry[];
+  /** The source's OWN change signal — its ledger settling, a discovery pass
+   *  finishing. The panel re-reads on it without knowing what moved. */
+  readonly subscribe: (listener: () => void) => () => void;
+  /** Paints the tile. A stable component type (not a closure per entry), so
+   *  the grid re-renders rather than remounting every preview. */
+  readonly Thumbnail: ComponentType<ContentEntryThumbnailProps>;
+  /** Double-click: open whatever this entry's subject opens as. */
+  readonly open: (store: WorkspaceStateStore, entry: ContentEntry, title: string) => void;
+}
+
+const _sources: ContentEntrySource[] = [];
+const listeners = new Set<() => void>();
+/** Live teardowns for the per-source subscriptions the registry re-fans. */
+const sourceSubscriptions = new Map<ContentEntrySource, () => void>();
+let version = 0;
+
+function publish(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+/** Install a source. Returns the teardown. */
+export function registerContentEntrySource(source: ContentEntrySource): () => void {
+  const stale = _sources.findIndex((item) => item.owner === source.owner && item.id === source.id);
+  if (stale >= 0) {
+    const [removed] = _sources.splice(stale, 1);
+    if (removed) {
+      sourceSubscriptions.get(removed)?.();
+      sourceSubscriptions.delete(removed);
+    }
+  }
+  _sources.push(source);
+  _sources.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  sourceSubscriptions.set(source, source.subscribe(publish));
+  publish();
+  return () => {
+    const at = _sources.indexOf(source);
+    if (at < 0) return;
+    _sources.splice(at, 1);
+    sourceSubscriptions.get(source)?.();
+    sourceSubscriptions.delete(source);
+    publish();
+  };
+}
+
+const EMPTY: readonly ContentEntrySource[] = [];
+
+/** Everything registered, in order. A stable array per version, so it is a
+ *  safe `useSyncExternalStore` snapshot. */
+export function contentEntrySources(): readonly ContentEntrySource[] {
+  return _sources.length === 0 ? EMPTY : _sources;
+}
+
+/** ONE subscription for the panel: the registry's own changes AND every
+ *  registered source's. What changed is never the panel's question. */
+export function subscribeContentEntrySources(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function contentEntrySourceRegistryVersion(): number {
+  return version;
+}
+
+/**
+ * THE SAME QUESTION, ABOUT ONE COMPONENT: the first registered source that
+ * admits it, and the entry it minted — what the INSPECTOR asks when it wants a
+ * picture of a component it cannot photograph natively (a canvas entity with
+ * no Object3D, a selected component-backed asset).
+ *
+ * It is deliberately not a second door. "Is this component content, and what
+ * does it look like?" is one question; the Content grid asks it of the whole
+ * index and the Inspector of a single ref, and both take back the same
+ * `{ source, entry }` pair to paint with `source.Thumbnail`.
+ */
+export function contentEntryForComponent(
+  component: ContentComponentRef,
+): { readonly source: ContentEntrySource; readonly entry: ContentEntry } | null {
+  for (const source of _sources) {
+    // Surface `null`: the Inspector is asking about THIS component, not about
+    // what belongs on the surface currently in focus.
+    const entry = source.entries({ components: [component], surface: null })[0];
+    if (entry) return { source, entry };
+  }
+  return null;
+}
+
+/** Test-only reset (mirrors the restore, open and chrome-slot registries'). */
+export function __resetContentEntrySourcesForTest(): void {
+  for (const stop of sourceSubscriptions.values()) stop();
+  sourceSubscriptions.clear();
+  _sources.length = 0;
+  publish();
+}

package/src/kit/contribution-surfaces.ts

@@ -0,0 +1,48 @@
+/**
+ * The native surfaces a contribution is handed beyond the kit's own (`surfaces.Object3DAuthoring`
+ * and the rest a medium's integration adds to `ToolContributionSurfaces` from its public API), as
+ * that integration registers them. The kit forwards whatever is registered under a surface's name
+ * and imports no medium: a composition without the integration registers none, and a
+ * contribution that asks for one shows the kit's placeholder until one is.
+ *
+ * The surfaces reach contributions through their props, not an import, because a project's
+ * contributions are modules of the project's own graph and cannot import the editor's components.
+ */
+import type { ComponentType } from 'react';
+import type { ToolContributionSurfaces } from '../contributions';
+
+export type ContributionSurfaceRegistration = {
+  readonly [Name in keyof ToolContributionSurfaces]?: ToolContributionSurfaces[Name];
+};
+
+const registered = new Map<string, ComponentType<never>>();
+const listeners = new Set<() => void>();
+
+function notify(): void {
+  for (const listener of listeners) listener();
+}
+
+/** Install an integration's surfaces by name. Returns the teardown. */
+export function registerContributionSurfaces(surfaces: ContributionSurfaceRegistration): () => void {
+  const entries = Object.entries(surfaces) as [string, ComponentType<never>][];
+  for (const [name, surface] of entries) registered.set(name, surface);
+  notify();
+  return () => {
+    for (const [name, surface] of entries) {
+      if (registered.get(name) === surface) registered.delete(name);
+    }
+    notify();
+  };
+}
+
+/** The surface registered under `name`, or null when no integration has registered one. */
+export function contributionSurface(name: string): ComponentType<never> | null {
+  return registered.get(name) ?? null;
+}
+
+export function subscribeContributionSurfaces(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}

package/src/kit/coverage/canvas-reveal.ts

@@ -0,0 +1,192 @@
+/**
+ * WHICH CANVAS IS PRESENTING, and the bounded failsafe for when NONE is.
+ *
+ * The `canvas-revealed` ontology invariant (`ontology-invariants.ts`) asks one
+ * question: is this session drawing onto a surface nobody can see? Its own
+ * `fix` text has always named "the reveal failsafe" — and there wasn't one.
+ * This module is both halves, kept pure (facts in, decision out) so every
+ * transition is testable with no browser, the same contract the invariants
+ * themselves follow.
+ *
+ * ## Half one: the measurement was picking the wrong canvas
+ *
+ * The facts used to come from `findPrimaryCanvas`, which ranks by painted
+ * AREA and is blind to visibility — a canvas hidden by `visibility: hidden`
+ * keeps its full bounding box. Measured live on a racing-game ingest session
+ * (2026-08-15): during Play the Scene document's render overlay is hidden
+ * with an inline `visibility: hidden` while the game's own canvas
+ * fills the pane. The editor's Scene canvas — full-size, correctly hidden,
+ * shallower in the tree — won the ranking, so the invariant reported
+ * "4 frame(s) produced in 3389ms while the viewport canvas is hidden
+ * (visibility: hidden)" for a session whose screenshot showed the game
+ * rendering perfectly. A standing warning on a healthy session is the failure
+ * mode the invariant module's own comments warn about, so it is fixed at the
+ * source: **a session is revealed when ANY of its canvases is revealed**, and
+ * only when every one of them is hidden does the row name the largest one's
+ * reason.
+ *
+ * ## Half two: firing, not just reporting
+ *
+ * When every canvas IS hidden while frames are being produced, reporting is
+ * not enough — the user is looking at a blank viewport and the fix is one
+ * style write away. The failsafe fires it, and is deliberately narrow:
+ *
+ *  - **Only inline hiding on the canvas ITSELF.** A canvas hidden by an
+ *    ancestor (a render overlay) or by a stylesheet rule is somebody
+ *    else's decision, expressed somewhere this must not reach into.
+ *  - **Only a canvas with no declared owner.** The editor's own viewport
+ *    canvas is inline `opacity: 0` whenever `isThreejsSurfaceVisible` says so
+ *    — a computed decision with a name — and React would re-apply it anyway.
+ *    Fighting it would put a permanent false alarm on every DOM-only project.
+ *  - **Once per canvas, after a bounded wait.** A mount is legitimately hidden
+ *    for a moment; a failsafe that fires on the transient is a failsafe that
+ *    cries wolf. And a failsafe is an emergency, never a policy: it clears the
+ *    style once and then stops, so it can never become the mechanism a broken
+ *    reveal path quietly relies on.
+ *
+ * Firing is LOUD by design. The ledger entry says the failsafe fired, what it
+ * had to undo, and that this is a defect worth reporting upstream — because a
+ * silently-repaired reveal is a reveal nobody ever fixes.
+ */
+
+/** One canvas as the DOM layer measured it. */
+export interface CanvasVisibilityFact {
+  /** How the message names it — a `data-testid`, a class, or its index. */
+  readonly label: string;
+  /** Painted area in CSS px², used only to pick the one the row speaks for. */
+  readonly area: number;
+  /** Why it is not visible, in the measurement's own words, or `null` when it
+   *  IS visible. */
+  readonly hiddenBy: string | null;
+  /** Which of the canvas' OWN inline style properties is what hides it, or
+   *  `null` when the hiding comes from anywhere else (an ancestor, a
+   *  stylesheet, a zero-size box). Only this is ever cleared. */
+  readonly inlineHiding: 'opacity' | 'visibility' | 'display' | null;
+  /** True when this canvas' visibility is nobody's declared decision. The
+   *  editor's own viewport canvas is `false` — see the module header. */
+  readonly failsafeEligible: boolean;
+}
+
+/**
+ * Why the session has no visible presentation surface, in the measurement's
+ * own words — `undefined` when there is no canvas to measure at all, `null`
+ * when at least one canvas is revealed.
+ *
+ * This is the whole of half one: the presence of ONE revealed canvas is what
+ * makes the session presentable, whatever the others are doing.
+ */
+export function presentingCanvasHiddenBy(
+  canvases: readonly CanvasVisibilityFact[],
+): string | null | undefined {
+  if (canvases.length === 0) return undefined;
+  if (canvases.some((canvas) => canvas.hiddenBy === null)) return null;
+  const largest = [...canvases].sort((a, b) => b.area - a.area)[0];
+  return largest?.hiddenBy ?? null;
+}
+
+/**
+ * One line per hidden canvas: which one, why, and whose doing it is.
+ *
+ * The row used to say only "the viewport canvas is hidden (visibility:
+ * hidden)" — a sentence you cannot act on, because a session has several
+ * canvases and the reason does not say which of them is the subject or who
+ * hid it. Verifying this work against a live session was blocked on exactly
+ * that gap, which is the argument for it being in the report rather than in a
+ * debug affordance.
+ */
+export function hiddenCanvasBreakdown(
+  canvases: readonly CanvasVisibilityFact[],
+): readonly string[] {
+  return canvases
+    .filter((canvas) => canvas.hiddenBy !== null)
+    .sort((a, b) => b.area - a.area)
+    .map(
+      (canvas) =>
+        `${canvas.label} (${canvas.hiddenBy}, ${
+          canvas.inlineHiding === null
+            ? 'from an ancestor or a stylesheet'
+            : canvas.failsafeEligible
+              ? 'its own inline style, unowned'
+              : 'its own inline style, by a declared owner'
+        }, ${Math.round(canvas.area)}px²)`,
+    );
+}
+
+/**
+ * THE ONE SUBJECT DEFINITION — a canvas hiding ITSELF with nobody owning that
+ * decision. Both the invariant row and the failsafe below turn on this, which
+ * is why it is a function rather than two filters that could drift apart.
+ *
+ * Two facts have to line up, and each was measured as a false positive on the
+ * same live racing-ingest session (2026-08-15) when it did not:
+ *
+ *  - hidden by its OWN box or inline style. On the UI Components document,
+ *    every canvas is hidden by an ANCESTOR — the editor
+ *    showing a different document, which is what the user opened.
+ *  - and NOT a canvas whose visibility is somebody's declared decision. The
+ *    editor's own viewport canvas carries inline `opacity: 0` from
+ *    `isThreejsSurfaceVisible`, so during Play over an ingest root it read as
+ *    "a canvas hiding itself" and kept the row violating on a healthy session.
+ */
+export function selfHiddenSubjects(
+  canvases: readonly CanvasVisibilityFact[],
+): readonly CanvasVisibilityFact[] {
+  return canvases.filter((canvas) => canvas.failsafeEligible && canvas.inlineHiding !== null);
+}
+
+/**
+ * Of the hidden canvases, is any of them {@link selfHiddenSubjects | hiding
+ * itself}? `null` when nothing is hidden at all — there is no question to
+ * answer.
+ */
+export function anyCanvasHidesItself(canvases: readonly CanvasVisibilityFact[]): boolean | null {
+  if (!canvases.some((canvas) => canvas.hiddenBy !== null)) return null;
+  return selfHiddenSubjects(canvases).length > 0;
+}
+
+/**
+ * How long the all-hidden-while-drawing condition must hold before the
+ * failsafe fires. Longer than one vitals sample, so the condition has to
+ * SURVIVE a sample rather than merely be observed once during a mount.
+ */
+export const REVEAL_FAILSAFE_DEADLINE_MS = 4_000;
+
+export type RevealFailsafeDecision =
+  | { readonly fire: false }
+  | { readonly fire: true; readonly target: CanvasVisibilityFact; readonly ledger: string };
+
+export interface RevealFailsafeInput {
+  readonly canvases: readonly CanvasVisibilityFact[];
+  /** Frames the page produced in the sample window. */
+  readonly framesProduced: number;
+  /** How long the condition has held, or `null` when this is the first sample
+   *  that has seen it (nothing has held yet). */
+  readonly hiddenForMs: number | null;
+  readonly deadlineMs?: number;
+}
+
+/**
+ * Whether to force the reveal, and the ledger line that must accompany it.
+ *
+ * Every gate is a fact the caller measured; nothing here reads a clock or the
+ * DOM.
+ */
+export function decideRevealFailsafe(input: RevealFailsafeInput): RevealFailsafeDecision {
+  const deadline = input.deadlineMs ?? REVEAL_FAILSAFE_DEADLINE_MS;
+  if (input.framesProduced <= 0) return { fire: false };
+  if (input.hiddenForMs === null || input.hiddenForMs < deadline) return { fire: false };
+  if (presentingCanvasHiddenBy(input.canvases) === null) return { fire: false };
+  const target = [...selfHiddenSubjects(input.canvases)].sort((a, b) => b.area - a.area)[0];
+  if (!target) return { fire: false };
+  return {
+    fire: true,
+    target,
+    ledger:
+      `canvas reveal FAILSAFE FIRED — the "${target.label}" canvas was still hidden by its own ` +
+      `inline ${target.inlineHiding} (${target.hiddenBy}) ${Math.round(input.hiddenForMs / 1000)}s ` +
+      'after frames started arriving, so the editor cleared that style to put the picture on ' +
+      'screen. THIS IS A DEFECT, not a feature: the mount path that hid this canvas never ran ' +
+      'its own reveal, and the failsafe fires ONCE — a second mount in this state stays blank. ' +
+      'Report it upstream with the mount that owns this canvas.',
+  };
+}

package/src/kit/coverage/design-time-surfaces.ts

@@ -0,0 +1,101 @@
+/**
+ * THE DESIGN-TIME SURFACE REGISTRY — every place the editor mounts a game's own
+ * content while it is NOT playing, and the content clock each one publishes.
+ *
+ * ## CONTENT time vs PRESENTATION time (the one policy, stated once)
+ *
+ * A design-time surface renders continuously, and that is fine: the camera
+ * orbit, a turntable, the standard viewport dressing and the editor's own
+ * helpers are PRESENTATION and are editor-owned, so they may move while the
+ * editor is in Edit. What may NOT move is CONTENT — the mounted world's
+ * `update(dt)`, an animation mixer, a `useFrame` clock, a simulation step —
+ * because Edit is static (ARCHITECTURE-CORE §Rules). An interactive document
+ * may advance content only through its explicit animation/simulation transport;
+ * opening the document itself never advances it. Off-screen capture operations
+ * may request their own bounded settle before producing a still.
+ *
+ * ## WHY A REGISTRY, rather than a field on one surface's session class
+ *
+ * Edit-static was enforced at the Scene view's design session only, so the
+ * SAME content mounted on any other surface kept running: a GLB train animated
+ * in the Asset Lab while every instrument reported a still editor (owner find,
+ * 2026-08-15). The check therefore enumerates SURFACES, and a surface that
+ * publishes no clock is reported UNMEASURED BY NAME rather than assumed still —
+ * silence is the one case that would let a surface animate in Edit with the
+ * vitals green, which is the defect this registry exists to make impossible.
+ *
+ * A surface's clock is monotonic seconds of ITS OWN content time. Its absolute
+ * value means nothing; `coverage/session-vitals.ts` only ever asks whether two
+ * readings differ, which is what makes camera orbit (which never touches it)
+ * irrelevant to the answer.
+ *
+ * ## THE TRANSPORT IS THE SANCTION
+ *
+ * "Edit is static" has always meant *nothing plays on its own* — the origin
+ * note behind the row says it out loud: a game running "with nothing having
+ * pressed ▶". A document's own animation/simulation transport IS that press,
+ * so content time advancing WHILE a transport is engaged is the sanctioned
+ * case, not the violation. A surface therefore publishes a second reading
+ * beside its clock: how many times an ENGAGED transport advanced it
+ * ({@link DesignTimeSurface.transportAdvances}). The row fires only when the
+ * clock moved and that counter did not.
+ */
+
+export interface DesignTimeSurface {
+  /**
+   * Stable per MOUNT — the document id only for the one mount that IS the
+   * document. Two mounts of one document (its viewport and a chromeless
+   * preview of it) are two surfaces: registration is last-wins and the vitals
+   * consumer keys its per-window sample history by this id, so a shared id
+   * makes the survivor answer for both — a held preview clock once spoke for a
+   * viewport that was visibly animating (measured 2026-08-30). Suffix, or
+   * sequence, anything that is not the document itself.
+   */
+  readonly id: string;
+  /** What the vitals row calls it out loud. */
+  readonly label: string;
+  /**
+   * Monotonic seconds of THIS surface's content time, or `null` when the host
+   * cannot currently make an honest comparison. Interactive document boot is
+   * never such a window: it publishes zero immediately because it performs no
+   * hidden simulation.
+   */
+  readonly contentClock: () => number | null;
+  /**
+   * Monotonic count of the times an ENGAGED transport (this document's
+   * animation transport, its simulation transport's play or step) advanced
+   * this surface's content time.
+   *
+   * Compared the same way the clock is: two readings, and only whether they
+   * DIFFER. A counter — not a "is a transport playing right now" boolean —
+   * because the question is about the window BETWEEN two samples, and a
+   * boolean answers about the instant of the sample: a single-frame step, or
+   * a transport paused between two reads, would both report "nothing engaged"
+   * over a window in which a transport was the only thing that ran.
+   *
+   * A surface that omits this publishes no transport at all, so ANY advance of
+   * its clock is unsanctioned — which is the honest reading for a surface (a
+   * preview card, a turntable) that has no ▶ to press.
+   */
+  readonly transportAdvances?: () => number;
+}
+
+const surfaces = new Map<string, DesignTimeSurface>();
+
+/**
+ * Publish one live design-time surface. Returns its withdrawal — the ONE
+ * teardown path, and it is safe to call after the id has been re-registered by
+ * a later mount (it withdraws only its own entry).
+ */
+export function registerDesignTimeSurface(surface: DesignTimeSurface): () => void {
+  surfaces.set(surface.id, surface);
+  return () => {
+    if (surfaces.get(surface.id) !== surface) return;
+    surfaces.delete(surface.id);
+  };
+}
+
+/** Every live design-time surface, for the vitals collector. */
+export function allDesignTimeSurfaces(): readonly DesignTimeSurface[] {
+  return [...surfaces.values()];
+}