@volter/editor-core 0.5.57

package/src/coverage/authoring-seam-evidence.ts

@@ -0,0 +1,300 @@
+/**
+ * One structural and operational answer for an AuthoringAdapter.
+ *
+ * This module does not call providers. It inventories their compiler-pinned
+ * shapes and combines those receipts with receipts produced by real consumers
+ * and conformance probes. Shape can reject a malformed carrier immediately;
+ * it can never manufacture an operational pass.
+ */
+
+import {
+  AUTHORING_ADAPTER_SHAPE,
+  AUTHORING_PROVIDER_KEYS,
+  AUTHORING_PROVIDER_SHAPES,
+  type AuthoringAdapter,
+  type AuthoringProviderKey,
+  gradeSeamCarrier,
+  gradeSeamEvidence,
+  HIERARCHY_PROVIDER_SHAPE,
+  type HierarchyProvider,
+  inspectSeamShape,
+  type SeamEvidenceReceipt,
+  type SeamEvidenceVerdict,
+  type SeamProofStage,
+  type SeamShape,
+  type StructuralWriteOutcome,
+  type WriteAck,
+} from '@volter/editor-project/adapter';
+import { liveSeamEvidence, recordLiveSeamEvidence } from './live-seam-evidence';
+
+const EPOCHS = new WeakMap<object, string>();
+let nextEpoch = 1;
+
+/** Stable only for the lifetime of this adapter object. A cold remount creates
+ * a new adapter and therefore cannot inherit receipts from the old one. */
+export function authoringAdapterEpoch(adapter: AuthoringAdapter): string {
+  const object = adapter as object;
+  const existing = EPOCHS.get(object);
+  if (existing) return existing;
+  const epoch = `authoring-${nextEpoch++}`;
+  EPOCHS.set(object, epoch);
+  return epoch;
+}
+
+function recordAuthoringReceipt(options: {
+  readonly adapter: AuthoringAdapter;
+  readonly seam: string;
+  readonly stage: SeamProofStage;
+  readonly outcome: 'pass' | 'fail';
+  readonly detail: string;
+}): void {
+  const epoch = authoringAdapterEpoch(options.adapter);
+  const record = (seam: string, detail: string): void =>
+    recordLiveSeamEvidence({
+      seam,
+      subject: 'authoring-adapter',
+      epoch,
+      stage: options.stage,
+      outcome: options.outcome,
+      source: 'consumer',
+      detail,
+    });
+  record(options.seam, options.detail);
+  const segments = options.seam.split('.');
+  if (segments.length < 3) return;
+  const parent = segments.slice(0, -1).join('.');
+  record(
+    parent,
+    options.outcome === 'pass'
+      ? `${parent} served a real consumer ${options.stage}`
+      : `${parent} failed through its consumer: ${options.detail}`,
+  );
+}
+
+function writeAck(value: unknown): WriteAck | null {
+  if (!value || typeof value !== 'object') return null;
+  const candidate = value as { destination?: unknown; persisted?: unknown };
+  return typeof candidate.destination === 'string' && typeof candidate.persisted === 'boolean'
+    ? (candidate as WriteAck)
+    : null;
+}
+
+/** Record one real consumer call against the exact adapter object it used.
+ *
+ * The epoch, not a display label, is the identity boundary: one root can be
+ * reported under its manifest id in status and under `root` in the ingest
+ * mount report, while both names refer to this same adapter instance. The
+ * receipt is therefore stored under the neutral subject and rebound to the
+ * report's subject in {@link inspectAuthoringAdapterSeams} below.
+ *
+ * Promise-returning provider methods keep their original timing and rejection;
+ * success is recorded only after they settle. A thrown/rejected call records a
+ * failing receipt and is rethrown unchanged.
+ */
+export function recordAuthoringConsumerUse<T>(options: {
+  readonly adapter: AuthoringAdapter;
+  readonly seam: string;
+  readonly stage: SeamProofStage;
+  readonly detail: string;
+  readonly run: () => T;
+}): T {
+  const receipt = (outcome: 'pass' | 'fail', detail: string): void => {
+    recordAuthoringReceipt({ ...options, outcome, detail });
+  };
+  try {
+    const value = options.run();
+    if (value && typeof (value as { then?: unknown }).then === 'function') {
+      return Promise.resolve(value).then(
+        (settled) => {
+          receipt('pass', options.detail);
+          return settled;
+        },
+        (error) => {
+          receipt(
+            'fail',
+            `${options.detail} failed: ${error instanceof Error ? error.message : String(error)}`,
+          );
+          throw error;
+        },
+      ) as unknown as T;
+    }
+    receipt('pass', options.detail);
+    return value;
+  } catch (error) {
+    receipt(
+      'fail',
+      `${options.detail} failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    throw error;
+  }
+}
+
+/** Record a write at the strength its own return value proves. A concrete
+ * WriteAck is a round trip even when it honestly says live-only; `void` proves
+ * only that the effect call returned. This keeps void-returning legacy lanes
+ * from manufacturing the stronger receipt their contract still owes. */
+export function recordAuthoringWriteConsumerUse(options: {
+  readonly adapter: AuthoringAdapter;
+  readonly seam: string;
+  readonly detail: string;
+  readonly run: () => StructuralWriteOutcome;
+}): StructuralWriteOutcome {
+  const success = (value: void | WriteAck): void | WriteAck => {
+    const ack = writeAck(value);
+    recordAuthoringReceipt({
+      adapter: options.adapter,
+      seam: options.seam,
+      stage: ack ? 'round-trip' : 'effect',
+      outcome: 'pass',
+      detail: ack
+        ? `${options.detail}: ${ack.destination} (${ack.persisted ? 'persisted' : 'live-only'})`
+        : `${options.detail}; the provider returned no write acknowledgement`,
+    });
+    return value;
+  };
+  const failure = (error: unknown): never => {
+    recordAuthoringReceipt({
+      adapter: options.adapter,
+      seam: options.seam,
+      stage: 'round-trip',
+      outcome: 'fail',
+      detail: `${options.detail} failed: ${error instanceof Error ? error.message : String(error)}`,
+    });
+    throw error;
+  };
+  try {
+    const value = options.run();
+    return value && typeof (value as { then?: unknown }).then === 'function'
+      ? Promise.resolve(value).then(success, failure)
+      : success(value as void | WriteAck);
+  } catch (error) {
+    return failure(error);
+  }
+}
+
+export interface AuthoringSeamEvidence {
+  readonly subject: string;
+  readonly epoch: string;
+  readonly receipts: readonly SeamEvidenceReceipt[];
+  readonly providers: Readonly<Record<AuthoringProviderKey, SeamEvidenceVerdict>>;
+  /**
+   * The hierarchy CARRIER: well-formed, and every member it advertises proven
+   * at that member's own required stage. This is the door
+   * `authoring/active-adapter.ts` refuses a malformed adapter with — a missing
+   * or mis-kinded `roots`/`node` only ever shows up as a member verdict, so
+   * the refusal needs the carrier grade and not the seam's own.
+   */
+  readonly hierarchy: SeamEvidenceVerdict;
+  /**
+   * The hierarchy WALK — the `editor.hierarchy` seam's own verdict, which is a
+   * different and weaker question than {@link hierarchy}: did a current-epoch
+   * operation walk this root's tree and find it finite, non-empty and
+   * reciprocal (`coverage/authoring-read-probe.ts`)?
+   *
+   * It exists because the CARRIER asks a strictly stronger question: every
+   * member the carrier advertises, proven at that member's own stage. It used
+   * to be an UNANSWERABLE one — `object3D` (required `operation`) and
+   * `idForObject3D` (then required `effect`) are optional-but-PRESENT on every
+   * three adapter, no production consumer records a receipt for either, and
+   * the read probe did not call them, so `gradeSeamCarrier` returned
+   * `unverified` on a perfectly reciprocal tree, forever. Both are pure
+   * lookups and are `operation` now, called and checked against the walk by
+   * `coverage/authoring-read-probe.ts`'s `objectLookupReceipts`, so the
+   * carrier answers its own question on a healthy adapter.
+   * The two grades stay separate regardless: this one is what
+   * `adapter-reach.ts`'s `captureEvidence` reads, and reading the CARRIER
+   * there once left the capture row's `ok` branch DEAD — a healthy
+   * root printed "no current-epoch hierarchy operation proves it projects
+   * this root's runtime" as `info` while the operation had in fact run and
+   * passed. MEASURED 2026-09-19 on a `--template game` scaffold: `info` with
+   * the reciprocity fix in, `gap` with the pre-fix adapter planted — the
+   * failure branch worked, the success branch could not be reached.
+   *
+   * Graded here, beside the carrier and off the SAME receipt set, so the two
+   * answers cannot drift apart in two modules.
+   */
+  readonly hierarchyWalk: SeamEvidenceVerdict;
+}
+
+export function inspectAuthoringAdapterSeams(options: {
+  readonly adapter: AuthoringAdapter;
+  readonly subject: string;
+  readonly epoch?: string | undefined;
+  readonly receipts?: readonly SeamEvidenceReceipt[] | undefined;
+}): AuthoringSeamEvidence {
+  const { adapter, subject } = options;
+  const epoch = options.epoch ?? authoringAdapterEpoch(adapter);
+  const receipts: SeamEvidenceReceipt[] = [
+    ...inspectSeamShape<AuthoringAdapter>({
+      prefix: 'editor',
+      value: adapter,
+      shape: AUTHORING_ADAPTER_SHAPE,
+      subject,
+      epoch,
+    }),
+    ...inspectSeamShape<HierarchyProvider>({
+      prefix: 'editor.hierarchy',
+      value: adapter.hierarchy,
+      shape: HIERARCHY_PROVIDER_SHAPE,
+      subject,
+      epoch,
+    }),
+  ];
+
+  for (const [provider, shape] of Object.entries(AUTHORING_PROVIDER_SHAPES)) {
+    receipts.push(
+      ...inspectSeamShape({
+        prefix: `editor.${provider}`,
+        value: (adapter as unknown as Record<string, unknown>)[provider],
+        shape: shape as SeamShape<object>,
+        subject,
+        epoch,
+      }),
+    );
+  }
+  // An adapter epoch already identifies one concrete carrier. Rebind its live
+  // consumer receipts to this report's display subject so the same operation
+  // closes both the per-root status row (`worldId`) and the ingest report
+  // (`root`) without duplicating or guessing names at the call site.
+  receipts.push(
+    ...liveSeamEvidence.receipts({ epoch }).map((receipt) => ({ ...receipt, subject })),
+  );
+  if (options.receipts) receipts.push(...options.receipts);
+
+  const providers = {} as Record<AuthoringProviderKey, SeamEvidenceVerdict>;
+  for (const provider of AUTHORING_PROVIDER_KEYS) {
+    const nested = (AUTHORING_PROVIDER_SHAPES as Partial<Record<string, SeamShape<object>>>)[
+      provider
+    ];
+    providers[provider] = gradeSeamCarrier({
+      seam: `editor.${provider}`,
+      required: AUTHORING_ADAPTER_SHAPE[provider].required,
+      shape: nested,
+      subject,
+      epoch,
+      receipts,
+    });
+  }
+
+  return {
+    subject,
+    epoch,
+    receipts,
+    providers,
+    hierarchy: gradeSeamCarrier({
+      seam: 'editor.hierarchy',
+      required: AUTHORING_ADAPTER_SHAPE.hierarchy.required,
+      shape: HIERARCHY_PROVIDER_SHAPE as SeamShape<object>,
+      subject,
+      epoch,
+      receipts,
+    }),
+    hierarchyWalk: gradeSeamEvidence({
+      seam: 'editor.hierarchy',
+      required: AUTHORING_ADAPTER_SHAPE.hierarchy.required,
+      subject,
+      epoch,
+      receipts,
+    }),
+  };
+}

package/src/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/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()];
+}

package/src/coverage/live-seam-evidence.ts

@@ -0,0 +1,11 @@
+/** One current-process evidence ledger shared by panels, relay consumers,
+ * coverage, status, and Doctor. It is intentionally ephemeral: project source
+ * remains truth and no VGAI evidence sidecar is invented. */
+
+import { SeamEvidenceLedger, type SeamEvidenceReceipt } from '@volter/editor-project/adapter';
+
+export const liveSeamEvidence = new SeamEvidenceLedger();
+
+export function recordLiveSeamEvidence(receipt: SeamEvidenceReceipt): void {
+  liveSeamEvidence.record(receipt);
+}