@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/authoring/viewport-tool-context.ts

@@ -0,0 +1,73 @@
+import type { AuthoringAdapter } from '@volter/project/adapter';
+import type { ShellStore } from '@volter/sdk/kit/shell-store';
+import { adapterOnlyToolOwner, type ViewportToolOwner } from '@volter/sdk/kit/authoring/viewport-tool-owner';
+import { CompositeAuthoringAdapter } from '@volter/sdk/kit/authoring/composite-authoring-adapter';
+import { resolveThreeViewportRootId } from './three-root';
+import { isRootHidden } from '@volter/sdk/kit/authoring/world-session-state';
+
+/**
+ * The one native root whose viewport tools may claim the current selection.
+ *
+ * A composed game can contain several native surfaces at once, but editing
+ * chrome needs one unambiguous coordinate system and capability owner. Empty,
+ * organizational, and cross-root selections therefore resolve to `null`.
+ */
+export interface ViewportToolContext extends ViewportToolOwner {
+  readonly adapter: AuthoringAdapter;
+}
+
+function compositeContext(
+  composite: CompositeAuthoringAdapter,
+  selectedIds: readonly string[],
+): ViewportToolContext | null {
+  const children = composite.childAdapters();
+  let owner: (typeof children)[number] | null = null;
+
+  for (const id of selectedIds) {
+    const child =
+      children.find((candidate) => composite.groupNodeId(candidate.worldId) === id) ??
+      children.find((candidate) => composite.ownerOf(id) === candidate.worldId);
+    // Kind/projection folders and stale ids do not claim native-world tools.
+    if (!child) return null;
+    // A heterogeneous selection has no single native editing context.
+    if (owner && owner.worldId !== child.worldId) return null;
+    owner = child;
+  }
+
+  return owner ? { worldId: owner.worldId, kind: owner.kind, adapter: owner.adapter } : null;
+}
+
+/**
+ * Resolve viewport-tool ownership from selection, never from which roots
+ * merely exist or happen to be visible.
+ */
+export function resolveViewportToolContext(
+  adapter: AuthoringAdapter,
+  selectedIds: Iterable<string>,
+): ViewportToolContext | null {
+  const ids = [...selectedIds];
+  if (ids.length === 0) return null;
+  if (adapter instanceof CompositeAuthoringAdapter) return compositeContext(adapter, ids);
+
+  // Legacy/single-adapter sessions have no manifest kind metadata, and that
+  // fallback is `adapterOnlyToolOwner` — it speaks only the adapter contract,
+  // so it lives below the shell (`viewport-authoring-policy.ts`) as the gizmo
+  // viewport's own default. One copy, read from both sides.
+  const owner = adapterOnlyToolOwner(adapter, ids);
+  return owner ? { ...owner, adapter } : null;
+}
+
+/**
+ * Whether the selected owner is actually painted in this viewport. DOM
+ * layers follow their world eye; the manifest's sole Three root owns the 3D
+ * viewport chrome only while that root is visible.
+ */
+export function isViewportToolContextVisible(
+  store: ShellStore,
+  context: ViewportToolOwner | null,
+): boolean {
+  if (!context) return false;
+  if (context.worldId !== null && isRootHidden(context.worldId)) return false;
+  if (context.kind !== 'three' || context.worldId === null) return true;
+  return resolveThreeViewportRootId(store) === context.worldId;
+}

package/src/kit/authoring/viewport-tool-owner.ts

@@ -0,0 +1,38 @@
+import type { AuthoringAdapter } from '@volter/project/adapter';
+
+/**
+ * The native root whose viewport tools may claim the current selection, as far
+ * as the viewport cares: its KIND (only `three` lets the 3D chrome claim the
+ * surface) and its manifest root id (`null` for a single-adapter session).
+ *
+ * `authoring/viewport-tool-context.ts`'s `ViewportToolContext` is this plus the
+ * adapter, and is structurally assignable to it.
+ */
+export interface ViewportToolOwner {
+  readonly worldId: string | null;
+  readonly kind: string;
+}
+
+/**
+ * Viewport-tool ownership for a SINGLE adapter — no composite, no manifest kind
+ * metadata to read.
+ *
+ * Structural and conservative, unchanged from where it was written
+ * (`authoring/viewport-tool-context.ts`, which now imports it): a rect-capable
+ * selection is DOM; a selection whose every node resolves to an `Object3D` is
+ * three; anything else advertises no kind-specific chrome rather than guessing.
+ * It speaks only the adapter contract, which is why it can be the default here.
+ */
+export function adapterOnlyToolOwner(
+  adapter: AuthoringAdapter,
+  selectedIds: Iterable<string>,
+): ViewportToolOwner | null {
+  const ids = [...selectedIds];
+  if (ids.length === 0) return null;
+  if (ids.some((id) => adapter.hierarchy.node(id) === null)) return null;
+  if (adapter.rects) return { worldId: null, kind: 'dom' };
+  if (ids.every((id) => adapter.hierarchy.object3D?.(id) != null)) {
+    return { worldId: null, kind: 'three' };
+  }
+  return null;
+}

package/src/kit/authoring/world-session-state.ts

@@ -0,0 +1,101 @@
+/**
+ * World session state (B1) — a module-level subscribable singleton (same shape as
+ * `./mount-failure-report.ts`: a bare get/set slot, no subscribe of its own — every
+ * caller that mutates it follows up with `store.notifyIngestEdit()`, which every
+ * panel already re-renders off via `useSyncExternalStore(store.subscribe, …)`)
+ * holding THREE session-local, per-worldId toggles that are NEVER
+ * serialized/persisted (D9: "eye = session-local viewport visibility, never
+ * serialized" — generalized here to all three, none of which is an authored
+ * property):
+ *
+ *  - `hidden` — the eye (A2/D9). LIFTED out of `GameHierarchy.tsx`'s former
+ *    local `useState<Set<string>> hiddenRootIds` (module-private React state
+ *    the design-time layer stack could never see) so `design-time-layers.ts`
+ *    can hide/show a world's actual DOM layer, not just dim its hierarchy row.
+ *  - `interactive` — forwards real pointer events to the layer (for testing
+ *    hover/press states at design time); off by default (`pointer-events:none`
+ *    is the layer's resting state — see `design-time-layers.ts`).
+ *  - `pickLock` — stored here for B4 to consume (layered viewport picking,
+ *    D12): a pick-locked layer is skipped by the topmost-first pick walk.
+ *    B1 only stores/exposes the toggle; nothing reads it yet.
+ *
+ * Keyed by the RAW manifest world id (`CompositeChild.worldId` /
+ * `ResolvedAdapterRoot.id`) — the SAME id `design-time-layers.ts` gets from
+ * `composite.childAdapters()`, NOT the composite's synthetic `world:<id>`
+ * group-node id. `GameHierarchy.tsx` (whose rows ARE keyed by the group-node
+ * id) resolves the raw worldId via `compositeGroupBadge`'s `worldId` field
+ * before calling into this module — see that file's row component.
+ *
+ * A process-lifetime singleton (not project-scoped): switching projects
+ * within the same tab does not reset these toggles. That's a deliberate
+ * relaxation of the former per-mount-React-state behavior (which reset on
+ * every `GameHierarchy` remount) — "session-local" here means "this browser
+ * tab's session", matching D9's own framing; nothing depends on a
+ * project-switch reset.
+ */
+
+export interface RootSessionState {
+  readonly hidden: boolean;
+  readonly interactive: boolean;
+  readonly pickLock: boolean;
+}
+
+const DEFAULT_STATE: RootSessionState = { hidden: false, interactive: false, pickLock: false };
+
+const _states = new Map<string, RootSessionState>();
+
+function get(worldId: string): RootSessionState {
+  return _states.get(worldId) ?? DEFAULT_STATE;
+}
+
+function patch(worldId: string, partial: Partial<RootSessionState>): void {
+  _states.set(worldId, { ...get(worldId), ...partial });
+}
+
+/** The eye (A2/D9): true while `worldId`'s design-time layer is hidden. */
+export function isRootHidden(worldId: string): boolean {
+  return get(worldId).hidden;
+}
+
+export function setRootHidden(worldId: string, hidden: boolean): void {
+  patch(worldId, { hidden });
+}
+
+export function toggleRootHidden(worldId: string): void {
+  setRootHidden(worldId, !isRootHidden(worldId));
+}
+
+/** True while `worldId`'s layer forwards real pointer events (design-time
+ *  hover/press testing) instead of its resting `pointer-events:none`. */
+export function isRootInteractive(worldId: string): boolean {
+  return get(worldId).interactive;
+}
+
+export function setRootInteractive(worldId: string, interactive: boolean): void {
+  patch(worldId, { interactive });
+}
+
+export function toggleRootInteractive(worldId: string): void {
+  setRootInteractive(worldId, !isRootInteractive(worldId));
+}
+
+/** B4 will read this to skip a layer in the topmost-first pick walk; B1 only
+ *  stores/exposes the toggle. */
+export function isRootPickLocked(worldId: string): boolean {
+  return get(worldId).pickLock;
+}
+
+export function setRootPickLock(worldId: string, pickLock: boolean): void {
+  patch(worldId, { pickLock });
+}
+
+export function toggleRootPickLock(worldId: string): void {
+  setRootPickLock(worldId, !isRootPickLocked(worldId));
+}
+
+/** Test-only: drop every world's session state back to defaults so unit
+ *  tests don't leak toggles across cases (this module is a process-lifetime
+ *  singleton — see the header comment). */
+export function _resetRootSessionStateForTest(): void {
+  _states.clear();
+}

package/src/kit/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/project/adapter';
+import { liveSeamEvidence, recordLiveSeamEvidence } from '@volter/sdk/kit/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/kit/availability-tick.ts

@@ -0,0 +1,66 @@
+/**
+ * ONE shared 250ms availability tick replacing the three independent
+ * `setInterval(…, 250)` pollers that W4 left behind (utility availability,
+ * the Dev utility's live-plane gate, and ConnectionStatus's networking-adapter
+ * poll).
+ *
+ * These gates all watch the SAME kind of out-of-band signal — a live play
+ * session's adapters appearing/disappearing without any store/registry
+ * notification — so they don't need three timers, three wakeups, and three
+ * interleaved re-render schedules; they need one heartbeat. The interval is
+ * refcounted: it starts with the first subscriber and stops with the last,
+ * so an idle editor (none of the three consumers mounted) runs no timer at
+ * all — strictly better than the three always-on intervals it replaces.
+ *
+ * `useSyncExternalStore`-shaped on purpose: consumers subscribe and SELECT
+ * the derived value they actually read (`getActiveDebug()` presence, a
+ * connection state, an availability fingerprint) — they re-render only when
+ * that value changes, never on the tick itself. The former version-counter
+ * hook (`useAvailabilityTick`) re-rendered every subscriber 4×/s
+ * unconditionally; with the workspace and every panel subscribed
+ * that measured ~27ms of React work per tick (~110ms/s) in an idle editor —
+ * found 2026-07-31 by the Profiler's long-animation-frame attribution.
+ */
+
+import { useSyncExternalStore } from 'react';
+
+const TICK_MS = 250;
+
+let _version = 0;
+let _intervalId: ReturnType<typeof setInterval> | null = null;
+const _listeners = new Set<() => void>();
+
+function onTick(): void {
+  _version++;
+  for (const fn of _listeners) fn();
+}
+
+/** Subscribe to the shared 250ms tick. Starts the timer on first subscriber,
+ *  stops it with the last. Returns unsubscribe. */
+export function subscribeAvailabilityTick(fn: () => void): () => void {
+  _listeners.add(fn);
+  if (_intervalId === null) _intervalId = setInterval(onTick, TICK_MS);
+  return () => {
+    _listeners.delete(fn);
+    if (_listeners.size === 0 && _intervalId !== null) {
+      clearInterval(_intervalId);
+      _intervalId = null;
+    }
+  };
+}
+
+/** Monotonic tick counter — exposed for tests that assert the timer runs. */
+export function availabilityTickVersion(): number {
+  return _version;
+}
+
+/**
+ * Re-evaluate `select` on every shared availability tick, re-rendering the
+ * caller ONLY when its result changes (`Object.is`). `select` must return a
+ * primitive or a stable reference (an adapter identity, a joined-id string,
+ * a bitmask) — a fresh object every call would defeat the point and re-render
+ * per tick. It runs 4×/s plus once per render, so keep it a cheap read.
+ */
+export function useAvailabilitySelector<T>(select: () => T): T {
+  return useSyncExternalStore(subscribeAvailabilityTick, select, select);
+}