@forgeax/engine-runtime 0.1.4 → 0.1.7

package/src/__tests__/video-cache-regression.unit.test.ts

@@ -1,186 +0,0 @@
-// feat-20260623-world-space-video-asset M4 / w12 — AC-08: static texture
-// cache regression.
-//
-// AC-08 (requirements.md): video per-frame upload must NOT enter the
-// GpuResourceStore.ensureResident permanent-cache path. The video frame is a
-// transient resource (re-uploaded every frame), the antithesis of the
-// "upload once / cache forever" semantics ensureResident implements. The M4
-// design (plan-strategy D-3) routes video through a separate DynamicTextureStore
-// and leaves ensureResident untouched (the cube-texture eager path is the
-// precedent: it also never enters the ensureResident switch).
-//
-// Two regression anchors:
-//   1. structural — ensureResident's `switch (pod.kind)` keeps exactly two arms
-//      (`mesh` + `texture`) and gains NO `case 'video'`. The switch has no
-//      `default`, so a video arm would be the only way video could pollute the
-//      cache; this source-level scan fails fast if a later edit adds one.
-//   2. behavioral — a static TextureAsset still resolves through ensureResident
-//      with cache-hit semantics: the second ensureResident for the same handle
-//      reuses the GPU texture (no second createTexture) and returns the same
-//      cached view. This proves the M4 video work did not perturb the static
-//      texture cache.
-
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-
-import { GpuResourceStore } from '@forgeax/engine-render/internal';
-import type { Result, RhiCaps } from '@forgeax/engine-rhi';
-import { err, ok, RhiError } from '@forgeax/engine-rhi';
-import type { EquirectAsset, Handle, TextureAsset } from '@forgeax/engine-types';
-import { toShared } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
-
-const STORE_SRC = fileURLToPath(
-  new URL('../../../render/src/gpu-resource-store.ts', import.meta.url),
-);
-
-function texturePodFixture(): TextureAsset {
-  return {
-    kind: 'texture',
-    width: 2,
-    height: 2,
-    format: 'rgba8unorm-srgb',
-    data: new Uint8Array(2 * 2 * 4).fill(188),
-    colorSpace: 'srgb',
-    mipmap: false,
-  };
-}
-
-interface CreateProbe {
-  textures: number;
-  views: number;
-}
-
-// biome-ignore lint/suspicious/noExplicitAny: opaque mock GPU device surface
-function makeMockDevice(probe: CreateProbe): any {
-  const okShim = <T>(v: T) => ({ ok: true as const, value: v });
-  return {
-    createShaderModule: () => okShim({ __mock: 'shader' }),
-    createSampler: () => okShim({ __mock: 'sampler' }),
-    createBindGroupLayout: () => okShim({ __mock: 'bgl' }),
-    createPipelineLayout: () => okShim({ __mock: 'layout' }),
-    createRenderPipeline: () => okShim({ __mock: 'pipeline' }),
-    createBindGroup: () => okShim({ __mock: 'bindGroup' }),
-    createBuffer: (desc: { size?: number }) => okShim({ __mock: 'buffer', size: desc.size ?? 0 }),
-    createTexture: () => {
-      probe.textures += 1;
-      return okShim({ __mock: `texture-${probe.textures}` });
-    },
-    createTextureView: () => {
-      probe.views += 1;
-      return okShim({ __mock: `view-${probe.views}` });
-    },
-    destroyBuffer: (): Result<void, RhiError> => ok(undefined),
-    destroyTexture: (): Result<void, RhiError> => ok(undefined),
-    queue: {
-      writeBuffer: () => okShim(undefined),
-      writeTexture: () => okShim(undefined),
-      submit: () => okShim(undefined),
-    },
-  };
-}
-
-const mockCaps: RhiCaps = {
-  backendKind: 'webgpu',
-  compute: true,
-  timestampQuery: false,
-  timestampPeriodNanoseconds: null,
-  indirectDrawing: false,
-  textureCompressionBc: false,
-  textureCompressionEtc2: false,
-  textureCompressionAstc: false,
-  multiDrawIndirect: false,
-  pushConstants: false,
-  textureBindingArray: false,
-  samplerAliasing: false,
-  firstInstanceIndirect: false,
-  storageBuffer: true,
-  storageTexture: false,
-  rgba16floatRenderable: true,
-  rg11b10ufloatRenderable: false,
-  float32Filterable: false,
-  maxColorAttachments: 8,
-};
-
-function makeRegisterCube(): (
-  pod: EquirectAsset,
-) => Result<Handle<'EquirectAsset', 'shared'>, never> {
-  let next = 1000;
-  return () => ok(toShared<'EquirectAsset'>(next++));
-}
-
-// biome-ignore lint/suspicious/noExplicitAny: shader-module factory shim
-const shaderFactory = async (_d: any, desc: { code: string; label?: string }) =>
-  ok({ __mock: 'shader', label: desc.label ?? '' }) as never;
-
-function configuredStore(probe: CreateProbe): GpuResourceStore {
-  const store = new GpuResourceStore();
-  store.configureGpuDevice(
-    makeMockDevice(probe),
-    shaderFactory,
-    makeRegisterCube() as never,
-    mockCaps,
-  );
-  return store;
-}
-
-describe('AC-08 — ensureResident switch stays 2-arm (no video) (M4 / w12)', () => {
-  it('ensureResident has exactly the mesh + texture case arms and no `case "video"`', () => {
-    const src = readFileSync(STORE_SRC, 'utf8');
-    // Locate the ensureResident body and isolate its `switch (pod.kind)`.
-    const fnIdx = src.indexOf('ensureResident(');
-    expect(fnIdx, 'ensureResident not found in gpu-resource-store.ts').toBeGreaterThan(-1);
-    const switchIdx = src.indexOf('switch (pod.kind)', fnIdx);
-    expect(switchIdx, 'switch (pod.kind) not found in ensureResident').toBeGreaterThan(-1);
-    // Scan from the switch to the next top-level method boundary (the
-    // uploadTexture jsdoc) so we only inspect ensureResident's switch.
-    const switchEnd = src.indexOf('async uploadTexture', switchIdx);
-    expect(switchEnd).toBeGreaterThan(switchIdx);
-    const switchBody = src.slice(switchIdx, switchEnd);
-
-    const caseArms = [...switchBody.matchAll(/case\s+'([a-z-]+)'\s*:/g)].map((m) => m[1]);
-    expect(caseArms).toEqual(['mesh', 'texture']);
-    expect(switchBody.includes("case 'video'")).toBe(false);
-    // No `default:` arm — exhaustiveness is enforced by tsc-b, so a third
-    // reachable kind (video) would be a compile error, never a silent cache
-    // poison. Assert the absence so a later `default` does not mask it.
-    expect(/\bdefault\s*:/.test(switchBody)).toBe(false);
-  });
-});
-
-describe('AC-08 — static texture cache-hit behavior unchanged (M4 / w12)', () => {
-  it('second ensureResident for the same texture handle reuses the GPU texture (cache hit)', () => {
-    const probe: CreateProbe = { textures: 0, views: 0 };
-    const store = configuredStore(probe);
-    const handle = toShared<'TextureAsset'>(4096);
-
-    const first = store.ensureResident(handle, texturePodFixture());
-    expect(first.ok).toBe(true);
-    const firstView = store.getTextureGpuView(handle);
-    expect(firstView).toBeDefined();
-    const texturesAfterFirst = probe.textures;
-    expect(texturesAfterFirst).toBeGreaterThan(0);
-
-    // Second call: cache hit — no new GPU texture is created, same view returned.
-    const second = store.ensureResident(handle, texturePodFixture());
-    expect(second.ok).toBe(true);
-    expect(probe.textures).toBe(texturesAfterFirst);
-    expect(store.getTextureGpuView(handle)).toBe(firstView);
-  });
-
-  it('a fresh handle does NOT hit the cache (distinct texture allocation)', () => {
-    const probe: CreateProbe = { textures: 0, views: 0 };
-    const store = configuredStore(probe);
-
-    expect(store.ensureResident(toShared<'TextureAsset'>(5001), texturePodFixture()).ok).toBe(true);
-    const afterOne = probe.textures;
-    expect(store.ensureResident(toShared<'TextureAsset'>(5002), texturePodFixture()).ok).toBe(true);
-    expect(probe.textures).toBeGreaterThan(afterOne);
-  });
-
-  it('RhiError surfaces import cleanly (compile anchor)', () => {
-    const e = new RhiError({ code: 'feature-not-enabled', expected: 'x', hint: 'y' });
-    expect(e).toBeInstanceOf(RhiError);
-    expect(err(e).ok).toBe(false);
-  });
-});

package/src/asset-kind.ts

@@ -1,7 +0,0 @@
-import type { BuiltinAssetKind, BuiltinAssetKindToken } from '@forgeax/engine-types';
-
-/** Create the typed expected-kind token used by every runtime load call. */
-export function builtinAssetKind<K extends BuiltinAssetKind>(kind: K): BuiltinAssetKindToken<K> {
-  const token = { kind } as BuiltinAssetKindToken<K>;
-  return Object.freeze(token);
-}

package/src/errors/sprite-animation.ts

@@ -1,5 +0,0 @@
-// Runtime-owned animation tick failures.
-
-export type SpriteAnimationErrorCode = 'sprite-animation-invalid';
-
-export { SpriteAnimationInvalidError } from '@forgeax/engine-ecs/projection';

package/src/scene-asset-port.ts

@@ -1,32 +0,0 @@
-import type { World } from '@forgeax/engine-ecs';
-import type { Asset, Handle, Result } from '@forgeax/engine-types';
-import { err, handleSlot, ok } from '@forgeax/engine-types';
-
-export interface SceneAssetPortError {
-  readonly code: 'scene-asset-unresolved';
-  readonly expected: string;
-  readonly hint: string;
-  readonly detail: { readonly handle: number };
-}
-
-/** Runtime's explicit bridge to scene-owned shared asset identity. */
-export interface SceneAssetPort {
-  resolve<T extends Asset>(world: World, handle: Handle<string, 'shared'>): Result<T, unknown>;
-  guidOf(asset: Asset): string | undefined;
-}
-
-export function createSceneAssetPort(guidOf: (asset: Asset) => string | undefined): SceneAssetPort {
-  return {
-    resolve<T extends Asset>(world: World, handle: Handle<string, 'shared'>) {
-      const shared = world.sharedRefs.resolve<string, T>(handle);
-      if (shared.ok) return ok(shared.value as T);
-      return err<SceneAssetPortError>({
-        code: 'scene-asset-unresolved',
-        expected: 'the handle to identify a World.sharedRefs-owned scene asset',
-        hint: 'allocate the asset through the active World shared-ref owner before collecting the scene',
-        detail: { handle: handleSlot(handle) },
-      });
-    },
-    guidOf,
-  };
-}

package/src/scene-collect-errors.ts

@@ -1,30 +0,0 @@
-export class SceneCollectEntityRefOutOfClosureError extends Error {
-  readonly code = 'scene-collect-entity-ref-out-of-closure' as const;
-  readonly expected: string;
-  readonly hint = 'Expand roots to include the target entity, or remove the reference.';
-  readonly detail: { readonly entity: number; readonly field: string; readonly target: number };
-
-  constructor(entity: number, field: string, target: number) {
-    super(
-      `entity ${entity} field ${field} references entity ${target} outside the collected roots`,
-    );
-    this.name = 'SceneCollectEntityRefOutOfClosureError';
-    this.expected = `entity ${entity} field ${field} to reference an entity inside the collected roots`;
-    this.detail = { entity, field, target };
-  }
-}
-
-export class SceneCollectAssetGuidUnresolvedError extends Error {
-  readonly code = 'scene-collect-asset-guid-unresolved' as const;
-  readonly expected: string;
-  readonly hint =
-    'Provide a GUID through the active scene asset port before collecting shared asset fields.';
-  readonly detail: { readonly field: string; readonly handle: number | string };
-
-  constructor(field: string, handle: number | string) {
-    super(`shared asset field ${field} has no GUID for handle ${handle}`);
-    this.name = 'SceneCollectAssetGuidUnresolvedError';
-    this.expected = `shared asset field ${field} to resolve through the active scene asset port`;
-    this.detail = { field, handle };
-  }
-}

package/src/shadow-m3-calibrate.ts

@@ -1,171 +0,0 @@
-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');
-  });
-});