@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/__tests__/prepared-graphics-snapshot.unit.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import { createPreparedGraphicsStore } from '../features/prepared-graphics-store';
+
+describe('prepared graphics operation snapshots', () => {
+  it('retains normalized descriptors and upload bytes after producer mutation', () => {
+    const store = createPreparedGraphicsStore();
+    const transaction = store.beginFrame('snapshot.feature', 3);
+    const pipeline: {
+      shader: string;
+      vertexLayout: string;
+      colorFormats: GPUTextureFormat[];
+      depthFormat: GPUTextureFormat;
+      topology: 'triangle-strip';
+      indexFormat: 'uint32';
+      renderState: {
+        depthWriteEnabled: boolean;
+        blend: GPUBlendState;
+      };
+    } = {
+      shader: 'synthetic::forward',
+      vertexLayout: 'position',
+      colorFormats: ['rgba8unorm'],
+      depthFormat: 'depth24plus-stencil8',
+      topology: 'triangle-strip',
+      indexFormat: 'uint32',
+      renderState: {
+        depthWriteEnabled: false,
+        blend: {
+          color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
+          alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
+        },
+      },
+    };
+    const vertexData = new Float32Array([0, 1, 2, 3, 4, 5]);
+    const indexData = new Uint16Array([0, 1, 2]);
+
+    const pipelineRef = transaction.prepare('pipeline', 'forward', pipeline);
+    const bindingsRef = transaction.prepare('bindings', 'forward', {
+      pipeline: pipelineRef.unwrap(),
+      values: { tint: [1, 0, 0, 1] },
+    });
+    const vertexRef = transaction.prepare('vertex-data', 'triangle', {
+      layout: 'position',
+      data: vertexData,
+    });
+    const indexRef = transaction.prepare('index-data', 'triangle', {
+      format: 'uint16',
+      data: indexData,
+    });
+
+    expect(pipelineRef.ok).toBe(true);
+    expect(bindingsRef.ok).toBe(true);
+    expect(vertexRef.ok).toBe(true);
+    expect(indexRef.ok).toBe(true);
+    if (!pipelineRef.ok || !bindingsRef.ok || !vertexRef.ok || !indexRef.ok) return;
+
+    pipeline.colorFormats[0] = 'bgra8unorm';
+    pipeline.renderState.depthWriteEnabled = true;
+    pipeline.renderState.blend.color.dstFactor = 'zero';
+    vertexData[0] = 99;
+    indexData[0] = 99;
+
+    expect(transaction.commit().ok).toBe(true);
+    const snapshot = store.snapshot('snapshot.feature');
+    const pipelineItem = snapshot.items.find((item) => item.kind === 'pipeline');
+    const bindingsItem = snapshot.items.find((item) => item.kind === 'bindings');
+    const vertexItem = snapshot.items.find((item) => item.kind === 'vertex-data');
+    const indexItem = snapshot.items.find((item) => item.kind === 'index-data');
+
+    expect(pipelineItem?.descriptor).toMatchObject({
+      shader: 'synthetic::forward',
+      vertexLayout: 'position',
+      colorFormats: ['rgba8unorm'],
+      depthFormat: 'depth24plus-stencil8',
+      topology: 'triangle-strip',
+      indexFormat: 'uint32',
+      renderState: {
+        depthWriteEnabled: false,
+        blend: {
+          color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
+          alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
+        },
+      },
+    });
+    expect(bindingsItem?.descriptor).toMatchObject({
+      pipeline: pipelineRef.value,
+      values: { tint: [1, 0, 0, 1] },
+    });
+    expect(vertexItem?.descriptor).toMatchObject({
+      layout: 'position',
+      data: [0, 1, 2, 3, 4, 5],
+    });
+    expect(indexItem?.descriptor).toMatchObject({ format: 'uint16', data: [0, 1, 2] });
+    expect(vertexItem?.uploadBytes).toEqual(
+      Array.from(new Uint8Array(new Float32Array([0, 1, 2, 3, 4, 5]).buffer)),
+    );
+    expect(indexItem?.uploadBytes).toEqual(
+      Array.from(new Uint8Array(new Uint16Array([0, 1, 2]).buffer)),
+    );
+
+    for (const item of snapshot.items) {
+      expect(Object.keys(item.reference).sort()).toEqual(['generation', 'kind']);
+    }
+  });
+});

package/src/__tests__/prepared-graphics-store.unit.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it } from 'vitest';
+import type { RenderFeatureGpuBufferRef } from '../features/prepared-gpu-work';
+import {
+  createPreparedGraphicsStore,
+  type PreparedGraphicsKind,
+} from '../features/prepared-graphics-store';
+
+function prepare(
+  transaction: ReturnType<ReturnType<typeof createPreparedGraphicsStore>['beginFrame']>,
+  kind: PreparedGraphicsKind,
+  name: string,
+) {
+  return transaction.prepare(kind, name, { signature: `${kind}:${name}` });
+}
+
+describe('prepared graphics store transactions', () => {
+  it('reuses committed same-generation resources and keeps new resources in the overlay', () => {
+    const store = createPreparedGraphicsStore();
+    const first = store.beginFrame('synthetic.feature', 4);
+    const committed = prepare(first, 'pipeline', 'forward');
+    expect(committed.ok).toBe(true);
+    expect(first.committedItems()).toHaveLength(0);
+    expect(first.overlayItems()).toHaveLength(1);
+    expect(first.commit().ok).toBe(true);
+
+    const second = store.beginFrame('synthetic.feature', 4);
+    const reused = prepare(second, 'pipeline', 'forward');
+    const fresh = prepare(second, 'bindings', 'forward');
+    expect(reused.ok).toBe(true);
+    expect(fresh.ok).toBe(true);
+    if (committed.ok && reused.ok) expect(reused.value).toBe(committed.value);
+    expect(second.committedItems()).toHaveLength(1);
+    expect(second.overlayItems()).toHaveLength(1);
+  });
+
+  it('aborts the overlay without changing committed ownership', () => {
+    const store = createPreparedGraphicsStore();
+    const initial = store.beginFrame('synthetic.feature', 1);
+    prepare(initial, 'pipeline', 'forward');
+    initial.commit();
+
+    const failed = store.beginFrame('synthetic.feature', 1);
+    prepare(failed, 'bindings', 'forward');
+    failed.abort();
+
+    expect(store.snapshot('synthetic.feature')).toMatchObject({
+      generation: 1,
+      items: [{ kind: 'pipeline', name: 'forward' }],
+    });
+    expect(failed.overlayItems()).toEqual([]);
+    expect(failed.commit().ok).toBe(false);
+  });
+
+  it('retires committed resources that the next successful frame does not touch', () => {
+    const store = createPreparedGraphicsStore();
+    const first = store.beginFrame('synthetic.feature', 1);
+    prepare(first, 'pipeline', 'forward');
+    prepare(first, 'bindings', 'stale');
+    first.commit();
+
+    const second = store.beginFrame('synthetic.feature', 1);
+    prepare(second, 'pipeline', 'forward');
+    expect(second.committedItems()).toMatchObject([{ kind: 'pipeline', name: 'forward' }]);
+    second.commit();
+
+    expect(store.snapshot('synthetic.feature')).toMatchObject({
+      generation: 1,
+      items: [{ kind: 'pipeline', name: 'forward' }],
+    });
+  });
+
+  it('rebinds a same-name GPU buffer after an absent frame retires its descriptor', () => {
+    const store = createPreparedGraphicsStore();
+    const firstBuffer = Object.freeze({
+      name: 'particles',
+      generation: 4,
+    }) as RenderFeatureGpuBufferRef;
+    const first = store.beginFrame('synthetic.feature', 4);
+    const firstVertex = first.prepare('vertex-data', 'particles', {
+      layout: 'particle-instance',
+      buffer: firstBuffer,
+    });
+    expect(firstVertex.ok).toBe(true);
+    expect(first.commit().ok).toBe(true);
+
+    const absent = store.beginFrame('synthetic.feature', 4);
+    expect(absent.commit().ok).toBe(true);
+    expect(store.snapshot('synthetic.feature').items).toEqual([]);
+
+    const replacementBuffer = Object.freeze({
+      name: 'particles',
+      generation: 4,
+    }) as RenderFeatureGpuBufferRef;
+    const restored = store.beginFrame('synthetic.feature', 4);
+    const restoredVertex = restored.prepare('vertex-data', 'particles', {
+      layout: 'particle-instance',
+      buffer: replacementBuffer,
+    });
+    expect(restoredVertex.ok).toBe(true);
+    if (firstVertex.ok && restoredVertex.ok) {
+      expect(restoredVertex.value).not.toBe(firstVertex.value);
+    }
+  });
+
+  it('keeps ownership scoped to the feature and generation', () => {
+    const store = createPreparedGraphicsStore();
+    const alpha = store.beginFrame('synthetic.alpha', 2);
+    const beta = store.beginFrame('synthetic.beta', 2);
+    const old = store.beginFrame('synthetic.alpha', 1);
+    prepare(alpha, 'vertex-data', 'quad');
+    prepare(beta, 'vertex-data', 'quad');
+    prepare(old, 'vertex-data', 'quad');
+    alpha.commit();
+    beta.commit();
+    old.commit();
+
+    expect(store.snapshot('synthetic.alpha').items).toHaveLength(1);
+    expect(store.snapshot('synthetic.beta').items).toHaveLength(1);
+    expect(store.snapshot('synthetic.alpha').generation).toBe(1);
+  });
+
+  it('retires untouched descriptors so a same-name GPU buffer can be rebound', () => {
+    const store = createPreparedGraphicsStore();
+    const firstBuffer = Object.freeze({
+      name: 'particles',
+      generation: 4,
+    }) as RenderFeatureGpuBufferRef;
+    const first = store.beginFrame('synthetic.feature', 4);
+    const firstVertex = first.prepare('vertex-data', 'particles', {
+      layout: 'particle-instance',
+      buffer: firstBuffer,
+    });
+    expect(firstVertex.ok).toBe(true);
+    expect(first.commit().ok).toBe(true);
+
+    const absent = store.beginFrame('synthetic.feature', 4);
+    expect(absent.commit().ok).toBe(true);
+    expect(store.snapshot('synthetic.feature').items).toEqual([]);
+
+    const replacementBuffer = Object.freeze({
+      name: 'particles',
+      generation: 4,
+    }) as RenderFeatureGpuBufferRef;
+    const restored = store.beginFrame('synthetic.feature', 4);
+    const restoredVertex = restored.prepare('vertex-data', 'particles', {
+      layout: 'particle-instance',
+      buffer: replacementBuffer,
+    });
+    expect(restoredVertex.ok).toBe(true);
+    if (firstVertex.ok && restoredVertex.ok) {
+      expect(restoredVertex.value).not.toBe(firstVertex.value);
+    }
+  });
+});

package/src/__tests__/prepared-graphics-validation.unit.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  PreparedKind,
+  RenderFeatureDrawRecord,
+  RenderFeatureGraphicsPassDescriptor,
+  RenderFeaturePreparedGraphicsState,
+  RenderFeaturePreparedRef,
+} from '../features/prepared-graphics';
+import { validateRenderFeatureGraphicsPass } from '../features/prepared-graphics';
+
+type Ledger = {
+  setPipeline: number;
+  setBindGroup: number;
+  setVertexBuffer: number;
+  setIndexBuffer: number;
+  draw: number;
+};
+
+function ref<Kind extends PreparedKind>(
+  kind: Kind,
+  generation = 7,
+): RenderFeaturePreparedRef<Kind> {
+  return { kind, generation };
+}
+
+const pipeline = ref('pipeline');
+const secondPipeline = ref('pipeline');
+const bindings = ref('bindings');
+const vertices = ref('vertex-data');
+const indices = ref('index-data');
+
+const vertexDraw: RenderFeatureDrawRecord = {
+  kind: 'draw',
+  pipeline,
+  bindings: [bindings],
+  vertexData: [{ slot: 0, resource: vertices }],
+  command: { vertexCount: 3, instanceCount: 1 },
+};
+
+const indexedDraw: RenderFeatureDrawRecord = {
+  kind: 'draw-indexed',
+  pipeline,
+  bindings: [bindings],
+  vertexData: [{ slot: 0, resource: vertices }],
+  indexData: { resource: indices, format: 'uint16' },
+  command: { indexCount: 3, instanceCount: 1 },
+};
+
+const vertexPass: RenderFeatureGraphicsPassDescriptor = {
+  attachments: {
+    colors: [{ resource: 'color', format: 'rgba8unorm', loadOp: 'load', storeOp: 'store' }],
+  },
+  draws: [vertexDraw],
+};
+
+const indexedPass: RenderFeatureGraphicsPassDescriptor = {
+  ...vertexPass,
+  draws: [indexedDraw],
+};
+
+const state: RenderFeaturePreparedGraphicsState = {
+  capabilityAvailable: true,
+  generation: 7,
+  attachments: [{ resource: 'color', format: 'rgba8unorm' }],
+  pipeline,
+  bindings: [bindings],
+  vertexData: [vertices],
+  indexData: [indices],
+};
+
+function expectRejected(
+  pass: RenderFeatureGraphicsPassDescriptor,
+  nextState: RenderFeaturePreparedGraphicsState,
+  ledger: Ledger,
+): void {
+  const result = validateRenderFeatureGraphicsPass('validation.feature', pass, nextState);
+  expect(result.ok).toBe(false);
+  if (!result.ok) {
+    expect('detail' in result.error).toBe(true);
+    if ('detail' in result.error && result.error.detail !== undefined) {
+      expect(result.error.detail).toMatchObject({ featureIdentity: 'validation.feature' });
+    }
+  }
+  expect(ledger).toEqual({
+    setPipeline: 0,
+    setBindGroup: 0,
+    setVertexBuffer: 0,
+    setIndexBuffer: 0,
+    draw: 0,
+  });
+}
+
+describe('prepared graphics validation before RHI mutation', () => {
+  it('accepts vertex-only and indexed records with complete state', () => {
+    expect(validateRenderFeatureGraphicsPass('validation.feature', vertexPass, state)).toEqual({
+      ok: true,
+      value: { acceptedDrawCount: 1 },
+    });
+    expect(validateRenderFeatureGraphicsPass('validation.feature', indexedPass, state)).toEqual({
+      ok: true,
+      value: { acceptedDrawCount: 1 },
+    });
+  });
+
+  it('accepts draws that use any prepared pipeline in the current pass', () => {
+    const secondDraw = { ...vertexDraw, pipeline: secondPipeline };
+    expect(
+      validateRenderFeatureGraphicsPass(
+        'validation.feature',
+        { ...vertexPass, draws: [vertexDraw, secondDraw] },
+        { ...state, pipelines: [pipeline, secondPipeline] },
+      ),
+    ).toEqual({ ok: true, value: { acceptedDrawCount: 2 } });
+  });
+
+  it('rejects each missing state category before the first RHI mutation', () => {
+    const cases: Array<[RenderFeatureGraphicsPassDescriptor, RenderFeaturePreparedGraphicsState]> =
+      [
+        [vertexPass, { ...state, pipeline: undefined }],
+        [vertexPass, { ...state, bindings: [] }],
+        [vertexPass, { ...state, vertexData: [] }],
+        [indexedPass, { ...state, indexData: [] }],
+        [vertexPass, { ...state, attachments: [] }],
+      ];
+    for (const [pass, nextState] of cases) {
+      expectRejected(pass, nextState, {
+        setPipeline: 0,
+        setBindGroup: 0,
+        setVertexBuffer: 0,
+        setIndexBuffer: 0,
+        draw: 0,
+      });
+    }
+  });
+
+  it('rejects foreign kind and stale generation references without recording', () => {
+    const ledger = {
+      setPipeline: 0,
+      setBindGroup: 0,
+      setVertexBuffer: 0,
+      setIndexBuffer: 0,
+      draw: 0,
+    };
+    expectRejected(vertexPass, { ...state, pipeline: ref('bindings') }, ledger);
+    expectRejected(vertexPass, { ...state, pipeline: ref('pipeline', 8) }, ledger);
+  });
+
+  it('rejects layout, format, and indexed-shape mismatches without a partial draw', () => {
+    const ledger = {
+      setPipeline: 0,
+      setBindGroup: 0,
+      setVertexBuffer: 0,
+      setIndexBuffer: 0,
+      draw: 0,
+    };
+    expectRejected(vertexPass, { ...state, vertexData: [ref('vertex-data', 8)] }, ledger);
+    expectRejected(
+      vertexPass,
+      { ...state, attachments: [{ resource: 'color', format: 'bgra8unorm' }] },
+      ledger,
+    );
+    expectRejected(
+      {
+        ...vertexPass,
+        draws: [{ ...vertexDraw, indexData: { resource: indices, format: 'uint16' } }],
+      },
+      state,
+      ledger,
+    );
+    expectRejected(
+      { ...indexedPass, draws: [{ ...indexedDraw, indexData: undefined }] },
+      state,
+      ledger,
+    );
+  });
+});

package/src/__tests__/profiler-default-off.test.ts

@@ -0,0 +1,22 @@
+import { createProfiler } from '@forgeax/engine-profiler';
+import { describe, expect, it } from 'vitest';
+import type { RendererOptions } from '../render-contract';
+
+describe('Render profiler default-off allocation boundary', () => {
+  it('keeps the complete render capability path at zero event objects', () => {
+    const allocationReport = { profilerEventObjectAllocations: 0 };
+    const profiler = createProfiler({ enabled: false, allocationReport });
+    const options = { profiler } satisfies RendererOptions;
+
+    expect(options.profiler).toBe(profiler);
+    expect({
+      profilerEventObjectAllocations: allocationReport.profilerEventObjectAllocations,
+      artifact: profiler.latestCapture(),
+      activeCaptureId: profiler.activeCaptureId(),
+    }).toEqual({
+      profilerEventObjectAllocations: 0,
+      artifact: undefined,
+      activeCaptureId: undefined,
+    });
+  });
+});

package/src/__tests__/profiler-phase-catalog.test.ts

@@ -0,0 +1,66 @@
+import { readFileSync } from 'node:fs';
+import { createProfiler } from '@forgeax/engine-profiler';
+import { describe, expect, it } from 'vitest';
+
+import {
+  RENDER_PHASE_CATALOG,
+  RENDER_RECORD_PHASE_CATALOG,
+  RENDER_SCENE_STATE_PHASE_CATALOG,
+} from '../render-contract';
+
+describe('Render profiler phase catalog ownership', () => {
+  it('matches the profiler receiver set and includes nested record owners', () => {
+    const profiler = createProfiler();
+    expect(profiler.registerPhaseCatalog('render', RENDER_PHASE_CATALOG).ok).toBe(true);
+    expect(RENDER_PHASE_CATALOG).toHaveLength(5 + RENDER_RECORD_PHASE_CATALOG.length);
+    expect(new Set(RENDER_PHASE_CATALOG).size).toBe(RENDER_PHASE_CATALOG.length);
+    expect(new Set(RENDER_PHASE_CATALOG)).toEqual(new Set(profiler.phaseCatalog.render));
+    expect(RENDER_RECORD_PHASE_CATALOG).toEqual(
+      expect.arrayContaining([
+        'record/graph-execute/g-buffer/material-bind-groups',
+        'record/graph-execute/g-buffer/pipeline-selection',
+        'record/graph-execute/g-buffer/draw-submit',
+        'record/graph-execute/g-buffer/geometry-loop',
+        'record/graph-execute/forward/material-bind-groups',
+        'record/graph-execute/forward/pipeline-selection',
+        'record/graph-execute/forward/draw-submit',
+        'record/graph-execute/forward/geometry-loop',
+      ]),
+    );
+    expect(RENDER_SCENE_STATE_PHASE_CATALOG).toEqual(
+      expect.arrayContaining([
+        'record/scene-state/fold-buckets',
+        'record/scene-state/lighting-prep',
+        'record/scene-state/ambient-resolution',
+        'record/scene-state/hdrp-cluster',
+        'record/scene-state/hdrp-cluster/binner',
+        'record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy',
+        'record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/light-aabb',
+        'record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/cluster-occupancy',
+        'record/scene-state/hdrp-cluster/binner/cluster-reserve',
+        'record/scene-state/hdrp-cluster/binner/input-preparation',
+        'record/scene-state/hdrp-cluster/binner/bin-core',
+        'record/scene-state/hdrp-cluster/binner/light-index-write',
+        'record/scene-state/hdrp-cluster/binner/light-index-write/bounds-read',
+        'record/scene-state/hdrp-cluster/binner/light-index-write/cluster-write',
+        'record/scene-state/hdrp-cluster/payload-packing',
+        'record/scene-state/hdrp-cluster/buffer-upload',
+      ]),
+    );
+  });
+
+  it('rejects a second Render catalog definition', () => {
+    const profiler = createProfiler();
+    expect(profiler.registerPhaseCatalog('render', RENDER_PHASE_CATALOG).ok).toBe(true);
+    const duplicate = profiler.registerPhaseCatalog('render', RENDER_PHASE_CATALOG);
+    expect(duplicate.ok).toBe(false);
+    if (!duplicate.ok) expect(duplicate.error.code).toBe('phase-catalog-conflict');
+  });
+
+  it('keeps the phase declaration in the Render owner module', () => {
+    const source = readFileSync(new URL('../render-contract.ts', import.meta.url), 'utf8');
+    expect(source).toContain('RENDER_PHASE_CATALOG');
+    expect(source).not.toContain('RenderPhaseObserver');
+    expect(source).not.toContain('renderFrameSeq');
+  });
+});

package/src/__tests__/profiler-phase-integration.test.ts

@@ -0,0 +1,62 @@
+import { createProfiler, type ProfileFrameToken } from '@forgeax/engine-profiler';
+import { describe, expect, it } from 'vitest';
+
+import { RENDER_PHASE_CATALOG } from '../render-contract';
+
+function start(profiler: ReturnType<typeof createProfiler>) {
+  const result = profiler.startCapture({ frameLimit: 2, eventLimit: 16 });
+  if (!result.ok) throw new Error(result.error.code);
+  return result.value;
+}
+
+function finish(profiler: ReturnType<typeof createProfiler>) {
+  const session = profiler.activeSession();
+  if (session === undefined) throw new Error('capture is not active');
+  const result = session.finish();
+  if (!result.ok) throw new Error(result.error.code);
+  return result.value;
+}
+
+describe('Render profiler phase integration', () => {
+  it('joins an App token to a Render-only frame without a second capture', () => {
+    const profiler = createProfiler({
+      phaseCatalog: { app: ['frame-total'], render: RENDER_PHASE_CATALOG },
+    });
+    const session = start(profiler);
+    const token: ProfileFrameToken = { captureId: session.captureId, frameId: 1 };
+
+    expect(session.beginFrame(token.frameId).ok).toBe(true);
+    expect(session.beginPhase({ source: 'app', phase: 'frame-total' }).ok).toBe(true);
+    expect(session.endPhase().ok).toBe(true);
+    expect(session.beginPhase({ source: 'render', phase: 'extract' }).ok).toBe(true);
+    expect(session.endPhase().ok).toBe(true);
+    expect(
+      session.recordSkip({ source: 'render', phase: 'bind-groups', reason: 'no-render' }).ok,
+    ).toBe(true);
+    expect(session.beginPhase({ source: 'render', phase: 'record' }).ok).toBe(true);
+    expect(session.endPhase().ok).toBe(true);
+    expect(session.endFrame().ok).toBe(true);
+
+    const capture = finish(profiler);
+    expect(capture.captureId).toBe(token.captureId);
+    expect(capture.records.map((record) => record.frameId)).toEqual([1, 1, 1, 1]);
+    const skip = capture.records.find((record) => record.kind === 'skip');
+    expect(skip).toMatchObject({ phase: 'bind-groups', reason: 'no-render' });
+    expect(skip && 'durationMicros' in skip).toBe(false);
+  });
+
+  it('retains direct Render-only frames with a new frame identity', () => {
+    const profiler = createProfiler({ phaseCatalog: { app: [], render: RENDER_PHASE_CATALOG } });
+    const session = start(profiler);
+
+    expect(session.beginFrame(1).ok).toBe(true);
+    expect(session.beginPhase({ source: 'render', phase: 'record' }).ok).toBe(true);
+    expect(session.endPhase().ok).toBe(true);
+    expect(session.endFrame().ok).toBe(true);
+
+    const capture = finish(profiler);
+    expect(capture.phaseCatalog.app).toEqual([]);
+    expect(capture.phaseCatalog.render).toEqual(RENDER_PHASE_CATALOG);
+    expect(capture.records[0]).toMatchObject({ source: 'render', frameId: 1, phase: 'record' });
+  });
+});

package/src/__tests__/profiler-phase-token.test.ts

@@ -0,0 +1,79 @@
+import { createProfiler, type ProfileFrameToken } from '@forgeax/engine-profiler';
+import { describe, expect, it } from 'vitest';
+
+import {
+  type DrawOwnerOptions,
+  RENDER_PHASE_CATALOG,
+  RENDER_RECORD_PHASE_CATALOG,
+  type RenderPhase,
+} from '../render-contract';
+
+const RENDER_PHASES: readonly RenderPhase[] = [
+  'extract',
+  'bind-groups',
+  'features',
+  'sort',
+  'record',
+  ...RENDER_RECORD_PHASE_CATALOG,
+];
+
+function startSession(profiler: ReturnType<typeof createProfiler>) {
+  const result = profiler.startCapture({ frameLimit: 1, eventLimit: 16 });
+  if (!result.ok) throw new Error(result.error.code);
+  return result.value;
+}
+
+describe('Render profiler token and skip contract', () => {
+  it('exposes owner phases and accepts an App frame token', () => {
+    expect(RENDER_PHASE_CATALOG).toEqual(RENDER_PHASES);
+    const token: ProfileFrameToken = {
+      captureId: 'capture-0001',
+      frameId: 3,
+    };
+    const options: DrawOwnerOptions = {
+      cameraOwner: 0,
+      resourceOwner: 0,
+      profileFrame: token,
+    };
+    expect(options).toMatchObject({ profileFrame: token });
+  });
+
+  it('records Render duration and skip facts without fabricating skip duration', () => {
+    const profiler = createProfiler({ phaseCatalog: { app: [], render: RENDER_PHASE_CATALOG } });
+    const session = startSession(profiler);
+    expect(session.beginFrame(1).ok).toBe(true);
+    for (const phase of ['extract', 'features', 'sort', 'record'] as const) {
+      expect(session.beginPhase({ source: 'render', phase }).ok).toBe(true);
+      expect(session.endPhase().ok).toBe(true);
+    }
+    expect(
+      session.recordSkip({
+        source: 'render',
+        phase: 'bind-groups',
+        reason: 'camera-unavailable',
+      }).ok,
+    ).toBe(true);
+    expect(session.endFrame().ok).toBe(true);
+    const result = session.finish();
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const skip = result.value.records.find(
+      (record) => record.kind === 'skip' && record.phase === 'bind-groups',
+    );
+    expect(skip).toMatchObject({ kind: 'skip', reason: 'camera-unavailable' });
+    expect(skip && 'durationMicros' in skip).toBe(false);
+  });
+
+  it('supports a direct Render-only frame when no App token is supplied', () => {
+    const profiler = createProfiler({ phaseCatalog: { app: [], render: RENDER_PHASE_CATALOG } });
+    const session = startSession(profiler);
+    expect(session.beginFrame(1).ok).toBe(true);
+    expect(session.beginPhase({ source: 'render', phase: 'record' }).ok).toBe(true);
+    expect(session.endPhase().ok).toBe(true);
+    expect(session.endFrame().ok).toBe(true);
+    const result = session.finish();
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.records[0]).toMatchObject({ source: 'render', frameId: 1 });
+  });
+});