@forgeax/engine-runtime 0.1.2

package/src/scene-instances/__tests__/post-spawn-resolve-joints.unit.test.ts

@@ -0,0 +1,183 @@
+// post-spawn-resolve-joints.unit.test.ts — tweak-20260611 M5 / D-7 (subtree-scope).
+//
+// Coverage:
+//   - single-instance resolver: existing behavior (joints wire correctly).
+//   - multi-instance resolver: three spawns of the same SceneAsset must each
+//     wire to their own subtree's joint entities (NOT entity ids of instance 0).
+//   - missing joint inside subtree: structured error 'skin-joint-path-unresolved'.
+
+import { World } from '@forgeax/engine-ecs';
+import { postSpawnResolveJoints } from '@forgeax/engine-render/internal';
+import { ChildOf, Name } from '@forgeax/engine-scene';
+import { Skin } from '@forgeax/engine-skinning';
+import type { SkinAsset } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+
+/**
+ * Build a 3-joint linear chain `Root -> Spine -> Hip` rooted at a fresh entity,
+ * with shared Name strings across spawns. Returns the spawnRoot + the three
+ * descendant entities for assertion. The Skin component is attached to the
+ * spawn root with a synthetic skeleton handle (the resolver's resolveSkinAsset
+ * is wired to return a fixed SkinAsset for any handle in this test).
+ */
+function spawnFoxLikeChain(world: World, skeletonHandle: number) {
+  const root = world.spawn({ component: Name, data: { value: 'Root' } }).unwrap();
+  const spine = world.spawn({ component: Name, data: { value: 'Spine' } }).unwrap();
+  const hip = world.spawn({ component: Name, data: { value: 'Hip' } }).unwrap();
+
+  // ChildOf is the writable edge; ECS materializes its Children target.
+  world.addComponent(spine, { component: ChildOf, data: { parent: root } }).unwrap();
+  world.addComponent(hip, { component: ChildOf, data: { parent: spine } }).unwrap();
+
+  // Skin lives on the root; resolver gets `skeleton` field as a number handle.
+  world
+    .addComponent(root, {
+      component: Skin,
+      // biome-ignore lint/suspicious/noExplicitAny: test fixture stamps a synthetic skeleton handle for resolver isolation; the resolver is mocked.
+      data: { skeleton: skeletonHandle as any, joints: new Uint32Array() },
+    })
+    .unwrap();
+
+  return { root, spine, hip };
+}
+
+describe('postSpawnResolveJoints — single instance', () => {
+  it('wires Skin.joints[] to subtree entities for one spawn', () => {
+    const world = new World();
+    const skinAsset: SkinAsset = {
+      kind: 'skin',
+      skeletonGuid: '00000000-0000-0000-0000-000000000001',
+      jointPaths: ['Root', 'Spine', 'Hip'],
+    };
+
+    const { root, spine, hip } = spawnFoxLikeChain(world, 1);
+
+    const result = postSpawnResolveJoints(world, { resolveSkinAsset: () => skinAsset }, root);
+
+    expect(result.ok).toBe(true);
+    const got = world.get(root, Skin);
+    expect(got.ok).toBe(true);
+    if (!got.ok) return;
+    const joints = Array.from(got.value.joints as ArrayLike<number>);
+    expect(joints).toEqual([root, spine, hip]);
+  });
+});
+
+describe('postSpawnResolveJoints — multi instance (D-7 subtree-scope)', () => {
+  it('three spawns each wire to their own subtree entities — not instance-0', () => {
+    const world = new World();
+    const skinAsset: SkinAsset = {
+      kind: 'skin',
+      skeletonGuid: '00000000-0000-0000-0000-000000000001',
+      jointPaths: ['Root', 'Spine', 'Hip'],
+    };
+
+    // Three independent spawns — same Name strings collide across instances.
+    const a = spawnFoxLikeChain(world, 1);
+    const b = spawnFoxLikeChain(world, 1);
+    const c = spawnFoxLikeChain(world, 1);
+
+    // Resolve each spawn independently.
+    expect(postSpawnResolveJoints(world, { resolveSkinAsset: () => skinAsset }, a.root).ok).toBe(
+      true,
+    );
+    expect(postSpawnResolveJoints(world, { resolveSkinAsset: () => skinAsset }, b.root).ok).toBe(
+      true,
+    );
+    expect(postSpawnResolveJoints(world, { resolveSkinAsset: () => skinAsset }, c.root).ok).toBe(
+      true,
+    );
+
+    const ja = Array.from(
+      (world.get(a.root, Skin) as { ok: true; value: { joints: ArrayLike<number> } }).value.joints,
+    );
+    const jb = Array.from(
+      (world.get(b.root, Skin) as { ok: true; value: { joints: ArrayLike<number> } }).value.joints,
+    );
+    const jc = Array.from(
+      (world.get(c.root, Skin) as { ok: true; value: { joints: ArrayLike<number> } }).value.joints,
+    );
+
+    // AC-09: the three spawns' joint entity arrays must be pairwise distinct.
+    expect(ja).toEqual([a.root, a.spine, a.hip]);
+    expect(jb).toEqual([b.root, b.spine, b.hip]);
+    expect(jc).toEqual([c.root, c.spine, c.hip]);
+    expect(ja).not.toEqual(jb);
+    expect(jb).not.toEqual(jc);
+    expect(ja).not.toEqual(jc);
+  });
+
+  it('does not wire across spawn roots — instance 1 is untouched after instance 0 resolves', () => {
+    const world = new World();
+    const skinAsset: SkinAsset = {
+      kind: 'skin',
+      skeletonGuid: '00000000-0000-0000-0000-000000000001',
+      jointPaths: ['Root', 'Spine', 'Hip'],
+    };
+    const a = spawnFoxLikeChain(world, 1);
+    const b = spawnFoxLikeChain(world, 1);
+
+    // Resolve only a; b should remain joints=[] (resolver was not invoked for b).
+    postSpawnResolveJoints(world, { resolveSkinAsset: () => skinAsset }, a.root);
+
+    const jb = Array.from(
+      (world.get(b.root, Skin) as { ok: true; value: { joints: ArrayLike<number> } }).value.joints,
+    );
+    expect(jb).toEqual([]);
+  });
+});
+
+describe('postSpawnResolveJoints — error path', () => {
+  it('returns skin-joint-path-unresolved when leaf name not present in subtree', () => {
+    const world = new World();
+    const skinAsset: SkinAsset = {
+      kind: 'skin',
+      skeletonGuid: '00000000-0000-0000-0000-000000000001',
+      // Each entry is a slash-separated path; leaf name is the last segment
+      // and the resolver matches on it. 'NoSuchBone' does not exist in the
+      // subtree we built, so the resolver fails on this path.
+      jointPaths: ['Root/Spine/NoSuchBone'],
+    };
+
+    const { root } = spawnFoxLikeChain(world, 1);
+
+    const result = postSpawnResolveJoints(world, { resolveSkinAsset: () => skinAsset }, root);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('skin-joint-path-unresolved');
+    if (result.error.code !== 'skin-joint-path-unresolved') return;
+    expect(result.error.detail.path).toEqual(['Root', 'Spine', 'NoSuchBone']);
+    expect(result.error.detail.failedAtIndex).toBe(2);
+  });
+
+  it('warns on same-name sibling within a single subtree (D-6a still active)', () => {
+    const world = new World();
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+    // Two siblings both named 'Bone' under one root.
+    const root = world.spawn({ component: Name, data: { value: 'Root' } }).unwrap();
+    const bone1 = world.spawn({ component: Name, data: { value: 'Bone' } }).unwrap();
+    const bone2 = world.spawn({ component: Name, data: { value: 'Bone' } }).unwrap();
+    world.addComponent(bone1, { component: ChildOf, data: { parent: root } }).unwrap();
+    world.addComponent(bone2, { component: ChildOf, data: { parent: root } }).unwrap();
+    world
+      .addComponent(root, {
+        component: Skin,
+        // biome-ignore lint/suspicious/noExplicitAny: test fixture stamps a synthetic skeleton handle for resolver isolation; the resolver is mocked.
+        data: { skeleton: 1 as any, joints: new Uint32Array() },
+      })
+      .unwrap();
+
+    const skinAsset: SkinAsset = {
+      kind: 'skin',
+      skeletonGuid: '00000000-0000-0000-0000-000000000001',
+      jointPaths: ['Bone'],
+    };
+    postSpawnResolveJoints(world, { resolveSkinAsset: () => skinAsset }, root);
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0]?.[0]).toMatch(/same-name sibling.*Bone.*matches 2/);
+    warnSpy.mockRestore();
+  });
+});

package/src/scene-utils/mount-override-fold.ts

@@ -0,0 +1,217 @@
+// feat-20260713-mount-override-component-add-and-shared-ref-round M5 / w20 —
+// collect fold: derive the runtime-authored MountOverride[] for one nested
+// SceneInstance anchor (plan-strategy D-3).
+//
+// ── What it does ──
+// Given a nested anchor's SceneInstanceState, walk each live member entity and
+// diff its live component columns against the member's authored baseline (the
+// source SceneAsset's layer-1 values, filled with schema defaults so the
+// comparison is against a fully-populated row). Every difference becomes a
+// MountOverride the collect step splices into the parent's `mounts[].overrides`:
+//   - a component present live but absent in source  -> component-ADD override
+//     ({ localId, comp, value }) whose value is the whole filled component map;
+//   - a field whose live value differs from baseline -> field-PATCH override
+//     ({ localId, comp, field, value }) for that single field;
+//   - a component present in source but absent live   -> NOT emitted (OOS-6:
+//     component-remove deltas do not fold back this feat).
+//
+// ── Value domain ──
+// The fold emits values in the LIVE domain: shared<T> fields carry numeric
+// handles, not GUID strings. The caller (rootsToSceneAsset / serialize wiring,
+// w21) performs the handle->GUID reverse-lookup with the two-state NULL-sentinel
+// handling (scalar handle 0 -> omit, array handle 0 -> keep positional 0),
+// reusing the same classifier the owned-entity serialization uses. Keeping the
+// fold registry-free means it stays a pure World+state read (D-3 / §2.5).
+//
+// ── localId namespace ──
+// Emitted `localId` is in the CHILD scene's namespace (0-based, exactly what
+// `state.entityToLocalId` maps to). The collect caller rebases it into the
+// parent namespace by adding the mount window's `memberFirst`, so the override
+// addresses the same slot the apply path validates against
+// (`_validateMountOverrides`: [memberFirst, memberFirst + memberCount)).
+//
+// ── Idempotency (AC-04) ──
+// A parent-authored mount-time override is applied to the child member's LIVE
+// column at instantiate time, and the child's source SceneAsset does not carry
+// it — so `live - source` re-derives it every round. Emitting it exactly once
+// (never separately re-passing state.mountTimeOverrides on top) keeps the
+// override entry set stable across save->load->save cycles: lossless without
+// doubling. (Runtime fact grounding this: parent-authored overrides on a nested
+// member land in the PARENT anchor's state, not the folded child anchor's; the
+// child anchor's own mountTimeOverrides is empty. See the M5 implement report.)
+
+import {
+  componentDefinition,
+  type Component as EcsComponent,
+  type EntityHandle,
+  type World,
+} from '@forgeax/engine-ecs';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { fillComponentDefaults } from '@forgeax/engine-ecs/projection';
+import type {
+  Handle,
+  LocalEntityId,
+  MountOverride,
+  SceneAsset,
+  SceneEntity,
+} from '@forgeax/engine-types';
+import type { SceneAssetPort } from '../scene-asset-port';
+
+/** Minimal structural view of a SceneInstanceState the fold reads (D-4 boundary:
+ * `world.getSceneInstanceState(root).value` is structurally assignable). */
+export interface FoldSceneInstanceState {
+  readonly source: Handle<'SceneAsset', 'shared'>;
+  readonly entityToLocalId: Map<EntityHandle, LocalEntityId>;
+}
+
+/** Component names that never participate in an authored baseline diff: the
+ * essential row-identity column, and structural hierarchy relationship
+ * holders/mirrors (ChildOf/Children) whose live values are re-wired by
+ * instantiate, not authored. */
+function excludedComponentNames(): Set<string> {
+  return new Set<string>(['Entity', 'ChildOf', 'Children']);
+}
+
+/** Normalize an array-like (typed array or Array) to a plain array for
+ * structural comparison; pass non-array values through unchanged. */
+function normalize(value: unknown): unknown {
+  if (
+    Array.isArray(value) ||
+    value instanceof Uint32Array ||
+    value instanceof Float32Array ||
+    value instanceof Int32Array ||
+    value instanceof Float64Array ||
+    value instanceof Uint8Array ||
+    value instanceof Int16Array ||
+    value instanceof Uint16Array
+  ) {
+    return Array.from(value as ArrayLike<unknown>);
+  }
+  return value;
+}
+
+/** Structural value equality after array normalization (handles Float32Array vs
+ * number[] and nested arrays via JSON). Both inputs are column-shape values. */
+function valuesEqual(a: unknown, b: unknown): boolean {
+  return JSON.stringify(normalize(a)) === JSON.stringify(normalize(b));
+}
+
+/** Build the per-field baseline map for a member from its source node, filled
+ * with schema defaults so it matches the fully-populated live row. Transient
+ * fields are dropped (they are never authored / never serialized, D-5). */
+function baselineFields(
+  comp: EcsComponent<string>,
+  sourceRaw: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  const filled = fillComponentDefaults(comp, sourceRaw ?? {});
+  const out: Record<string, unknown> = {};
+  const fields = componentDefinition(comp).fields;
+  for (const fieldName of Object.keys(componentSchema(comp))) {
+    if (fields[fieldName]?.transient) continue;
+    out[fieldName] = filled[fieldName];
+  }
+  return out;
+}
+
+/** Read the live, non-transient, non-entity field values of a component on an
+ * entity into a plain map. Entity-type fields are dropped: their live value is a
+ * live EntityHandle while the source carries a LocalEntityId, so they cannot be
+ * diffed without remap — entity-ref override deltas are out of scope this feat
+ * (the AC set centers on shared/asset fields + component-add). */
+function liveFields(
+  world: World,
+  entity: EntityHandle,
+  comp: EcsComponent<string>,
+): Record<string, unknown> | undefined {
+  const res = world.get(entity, comp);
+  if (!res.ok) return undefined;
+  const val = res.value as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  const fields = componentDefinition(comp).fields;
+  const schema = componentSchema(comp) as Record<string, string>;
+  for (const fieldName of Object.keys(schema)) {
+    if (fields[fieldName]?.transient) continue;
+    const fieldType = schema[fieldName];
+    if (fieldType === 'entity' || fieldType === 'array<entity>') continue;
+    out[fieldName] = normalize(val[fieldName]);
+  }
+  return out;
+}
+
+/**
+ * Fold one nested anchor's live member state into the runtime-authored
+ * MountOverride[] (child-namespace localIds, live value domain). See file
+ * header for the full contract. Returns [] when nothing differs from source.
+ */
+export function foldMountOverrides(
+  world: World,
+  assets: SceneAssetPort,
+  state: FoldSceneInstanceState,
+): MountOverride[] {
+  const sourceRes = assets.resolve<SceneAsset>(
+    world,
+    state.source as unknown as Handle<string, 'shared'>,
+  );
+  if (!sourceRes.ok) return [];
+  const source = sourceRes.value as SceneAsset;
+
+  // Index source entities by localId for O(1) baseline lookup.
+  const sourceByLid = new Map<number, SceneEntity>();
+  for (const node of source.entities) {
+    sourceByLid.set(node.localId as unknown as number, node);
+  }
+
+  const excluded = excludedComponentNames();
+  const registered = world.components.entries();
+  const overrides: MountOverride[] = [];
+
+  // Deterministic member order (localId ascending) so collect output is a pure
+  // function of the graph (mirrors rootsToSceneAsset D-7 ordering discipline).
+  const members: Array<[EntityHandle, number]> = [];
+  for (const [entity, lid] of state.entityToLocalId) {
+    members.push([entity, lid as unknown as number]);
+  }
+  members.sort((a, b) => a[1] - b[1]);
+
+  for (const [entity, lid] of members) {
+    const sourceNode = sourceByLid.get(lid);
+    const sourceComps = (sourceNode?.components ?? {}) as Record<string, Record<string, unknown>>;
+
+    for (const [compName, compToken] of registered) {
+      if (excluded.has(compName)) continue;
+      if (componentDefinition(compToken).policy.transient) continue;
+      const comp = compToken as EcsComponent<string>;
+      if (Object.keys(componentSchema(comp)).length === 0) continue;
+
+      const live = liveFields(world, entity, comp);
+      if (live === undefined) continue; // component absent live
+
+      const sourceRaw = sourceComps[compName];
+      if (sourceRaw === undefined) {
+        // Component present live but absent in source -> component-ADD override.
+        // Emit the whole live component value map (apply upserts with defaults).
+        overrides.push({
+          localId: lid as unknown as LocalEntityId,
+          comp: compName,
+          value: live,
+        });
+        continue;
+      }
+
+      // Component present in both -> per-field diff (field-PATCH overrides).
+      const baseline = baselineFields(comp, sourceRaw);
+      for (const fieldName of Object.keys(live)) {
+        if (!valuesEqual(live[fieldName], baseline[fieldName])) {
+          overrides.push({
+            localId: lid as unknown as LocalEntityId,
+            comp: compName,
+            field: fieldName,
+            value: live[fieldName],
+          });
+        }
+      }
+    }
+  }
+
+  return overrides;
+}

package/src/shadow-m3-calibrate.ts

@@ -0,0 +1,171 @@
+import { describe, expect, it } from 'vitest';
+
+export const SHADOW_PERFORMANCE_ARTIFACT_SCHEMA = 'forgeax.shadow-performance/v1';
+
+export type ShadowDiagnosticsMode = 'off' | 'on';
+
+export interface ShadowPerformanceProvenance {
+  readonly commit: string;
+  readonly chrome: string | null;
+  readonly viewport: { readonly width: number; readonly height: number } | null;
+  readonly devicePixelRatio: number | null;
+  readonly trajectory: string;
+  readonly diagnostics: ShadowDiagnosticsMode;
+}
+
+export interface ShadowPerformanceFrame {
+  readonly frame: number;
+  readonly cpuFrameMs: number;
+  readonly gpuFrameMs: number | null;
+}
+
+export interface ShadowPerformanceArtifact {
+  readonly schema: typeof SHADOW_PERFORMANCE_ARTIFACT_SCHEMA;
+  readonly status: 'measured' | 'unavailable';
+  readonly provenance: ShadowPerformanceProvenance;
+  readonly frames: readonly ShadowPerformanceFrame[];
+  readonly summary: {
+    readonly frameCount: number;
+    readonly cpuFrameP95Ms: number | null;
+    readonly cpuFpsP01: number | null;
+    readonly gpuFrameP95Ms: number | null;
+    readonly gpuTimestamp: 'available' | 'unavailable';
+    readonly unavailableReason: string | null;
+  };
+}
+
+export interface ShadowPerformanceCaptureInput {
+  readonly provenance: ShadowPerformanceProvenance;
+  readonly frames: readonly ShadowPerformanceFrame[];
+  readonly unavailableReason?: string;
+}
+
+function assertFiniteNonNegative(value: number, field: string): void {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`${field} must be a finite non-negative number`);
+  }
+}
+
+function nearestRank(values: readonly number[], quantile: number): number | null {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((left, right) => left - right);
+  const rank = Math.max(1, Math.ceil(quantile * sorted.length));
+  return sorted[rank - 1] ?? null;
+}
+
+function validateProvenance(provenance: ShadowPerformanceProvenance): void {
+  if (provenance.commit.trim().length === 0) throw new Error('commit is required');
+  if (provenance.trajectory.trim().length === 0) throw new Error('trajectory is required');
+  if (provenance.viewport !== null) {
+    if (!Number.isInteger(provenance.viewport.width) || provenance.viewport.width <= 0) {
+      throw new Error('viewport.width must be a positive integer');
+    }
+    if (!Number.isInteger(provenance.viewport.height) || provenance.viewport.height <= 0) {
+      throw new Error('viewport.height must be a positive integer');
+    }
+  }
+  if (provenance.devicePixelRatio !== null) {
+    assertFiniteNonNegative(provenance.devicePixelRatio, 'devicePixelRatio');
+    if (provenance.devicePixelRatio === 0) throw new Error('devicePixelRatio must be positive');
+  }
+}
+
+function validateFrames(frames: readonly ShadowPerformanceFrame[]): void {
+  let previousFrame = -1;
+  for (const sample of frames) {
+    if (!Number.isInteger(sample.frame) || sample.frame <= previousFrame) {
+      throw new Error('frame samples must have strictly increasing frame numbers');
+    }
+    previousFrame = sample.frame;
+    assertFiniteNonNegative(sample.cpuFrameMs, 'cpuFrameMs');
+    if (sample.gpuFrameMs !== null) assertFiniteNonNegative(sample.gpuFrameMs, 'gpuFrameMs');
+  }
+}
+
+export function summarizeShadowPerformanceCapture(
+  input: ShadowPerformanceCaptureInput,
+): ShadowPerformanceArtifact {
+  validateProvenance(input.provenance);
+  validateFrames(input.frames);
+  const cpuSamples = input.frames.map((sample) => sample.cpuFrameMs);
+  const gpuSamples = input.frames.flatMap((sample) =>
+    sample.gpuFrameMs === null ? [] : [sample.gpuFrameMs],
+  );
+  const gpuTimestamp = gpuSamples.length === input.frames.length && input.frames.length > 0;
+  const unavailableReason =
+    input.unavailableReason ??
+    (input.frames.length === 0
+      ? 'no frame samples were captured'
+      : gpuTimestamp
+        ? null
+        : 'GPU timestamp query was unavailable; CPU timings remain diagnostic only');
+  return {
+    schema: SHADOW_PERFORMANCE_ARTIFACT_SCHEMA,
+    status: input.frames.length === 0 ? 'unavailable' : 'measured',
+    provenance: input.provenance,
+    frames: input.frames,
+    summary: {
+      frameCount: input.frames.length,
+      cpuFrameP95Ms: nearestRank(cpuSamples, 0.95),
+      cpuFpsP01: nearestRank(
+        cpuSamples.map((frameMs) => (frameMs === 0 ? Number.POSITIVE_INFINITY : 1000 / frameMs)),
+        0.01,
+      ),
+      gpuFrameP95Ms: nearestRank(gpuSamples, 0.95),
+      gpuTimestamp: gpuTimestamp ? 'available' : 'unavailable',
+      unavailableReason,
+    },
+  };
+}
+
+export function unavailableShadowPerformanceCapture(
+  provenance: ShadowPerformanceProvenance,
+  reason: string,
+): ShadowPerformanceArtifact {
+  if (reason.trim().length === 0) throw new Error('unavailable reason is required');
+  return summarizeShadowPerformanceCapture({ provenance, frames: [], unavailableReason: reason });
+}
+
+describe('shadow performance artifact contract', () => {
+  it('uses nearest-rank p95 and records CPU-only evidence when GPU timestamps are absent', () => {
+    const artifact = summarizeShadowPerformanceCapture({
+      provenance: {
+        commit: 'test-commit',
+        chrome: 'test-chrome',
+        viewport: { width: 1280, height: 720 },
+        devicePixelRatio: 1,
+        trajectory: 'cod-door-forward-back',
+        diagnostics: 'off',
+      },
+      frames: [
+        { frame: 1, cpuFrameMs: 10, gpuFrameMs: null },
+        { frame: 2, cpuFrameMs: 12, gpuFrameMs: null },
+        { frame: 3, cpuFrameMs: 20, gpuFrameMs: null },
+      ],
+    });
+    expect(artifact.schema).toBe(SHADOW_PERFORMANCE_ARTIFACT_SCHEMA);
+    expect(artifact.status).toBe('measured');
+    expect(artifact.summary.cpuFrameP95Ms).toBe(20);
+    expect(artifact.summary.gpuTimestamp).toBe('unavailable');
+    expect(artifact.summary.gpuFrameP95Ms).toBeNull();
+    expect(artifact.summary.unavailableReason).toContain('GPU timestamp');
+  });
+
+  it('does not turn an empty capture into a passing baseline', () => {
+    const artifact = unavailableShadowPerformanceCapture(
+      {
+        commit: 'test-commit',
+        chrome: null,
+        viewport: null,
+        devicePixelRatio: null,
+        trajectory: 'cod-door-forward-back',
+        diagnostics: 'on',
+      },
+      'browser was not available',
+    );
+    expect(artifact.status).toBe('unavailable');
+    expect(artifact.summary.frameCount).toBe(0);
+    expect(artifact.summary.cpuFrameP95Ms).toBeNull();
+    expect(artifact.summary.unavailableReason).toBe('browser was not available');
+  });
+});

package/src/sprite-param-values.ts

@@ -0,0 +1,61 @@
+/**
+ * Type-only helper mirroring the `forgeax::sprite` shader's paramSchema
+ * (sprite.material.json). Field set is 1:1 with paramSchema entries; field
+ * order matches schema order so the std140 UBO layout (slot 0..3 = colorTint
+ * / region / pivotAndSize / slicesAndMode) reads top-to-bottom.
+ *
+ * feat-20260625-refactor-sprite-as-transparent-mesh M3 / w11 (D-4, D-6,
+ * F-3): paramSchema is now UBO-aligned (the 4 vec4 fields match the WGSL
+ * Material struct field names 1:1 so the generic std140 UBO writer
+ * `applyParamSnapshotToUbo` walks `derive(paramSchema).uboLayout.entries`
+ * and writes each field at its declared offset, no sprite-specific path).
+ *
+ * AI-user discoverability: annotate a sprite material's `values`
+ * literal as `SpriteParamValues` to get autocomplete on `slicesAndMode`,
+ * `pivotAndSize`, etc. Without the annotation the literal binds to
+ * `MaterialAsset.values: Record<string, unknown>` and field
+ * autocomplete is unavailable.
+ *
+ * Required fields:
+ * - `baseColorTexture`: AssetGuid string of a registered TextureAsset
+ *   (renamed from the pre-w11 `texture` field for cross-material name
+ *   consistency, D-4).
+ *
+ * Optional UBO fields (omit for identity defaults):
+ * - `colorTint`: vec4 `[r, g, b, a]` — texture sample multiplier
+ *   (rgb * colorTint.rgb, alpha * colorTint.a). Default `[1, 1, 1, 1]`.
+ * - `region`: vec4 `[uMin, vMin, uW, vH]` — atlas sub-region. Default
+ *   `[0, 0, 1, 1]`. Host pre-folds flipX / flipY into this vec4 (D-8):
+ *   `flipX -> region.x += region.z; region.z = -region.z` (analog for Y).
+ *   When composing with {@link SpriteRegionOverride}, the override
+ *   replaces this asset-side region.
+ * - `pivotAndSize`: vec4 `[pivotX, pivotY, sizeX, sizeY]` — `.xy` is the
+ *   pivot (0..1 normalised); `.zw` is the DEAD SLOT post-w11 (D-6 unit-
+ *   quad: world scale flows entirely through Transform.world, no longer
+ *   double-applied via the UBO). Default `[0.5, 0.5, 1, 1]`.
+ * - `slicesAndMode`: vec4 `[left, top, right, bottom-signed]` — 9-slice
+ *   border widths in UV (0..1) on the source texture region. Sum of
+ *   opposite borders must be < 1 (left+right < region width, top+bottom
+ *   < region height); register-time validation surfaces structured
+ *   `AssetError`. The `.w` carries the sliceMode sentinel: positive (or 0)
+ *   = stretch (middle band stretches with the entity's scale, default);
+ *   NEGATIVE = tile (middle band tiles via sampler `addressMode='repeat'`).
+ *   Default `[0, 0, 0, 0]` (no 9-slice). Authoring tip: callers who want
+ *   to keep the legacy `slices` + `sliceMode` split can compute
+ *   `slicesAndMode = [l, t, r, mode===1 ? -b : b]` at the call site.
+ *
+ * Composes with {@link SpriteRegionOverride}: when both are present, the
+ * `slicesAndMode` are interpreted relative to the per-entity `region`
+ * override (AC-14), not the material's `values.region`.
+ *
+ * Sibling type, not a sibling asset kind: `MaterialAsset` is the only
+ * material asset shape; using `SpriteParamValues` as an annotation does
+ * not branch the closed `AssetUnion` (plan-strategy section D-1).
+ */
+export type SpriteParamValues = {
+  baseColorTexture: string;
+  colorTint?: readonly [number, number, number, number];
+  region?: readonly [number, number, number, number];
+  pivotAndSize?: readonly [number, number, number, number];
+  slicesAndMode?: readonly [number, number, number, number];
+};