@forgeax/engine-rhi-debug 0.0.0-dev.8d955ade1c79

package/src/__tests__/tree-shake.unit.test.ts

@@ -0,0 +1,151 @@
+// m3-3: tree-shake grep gate — verify FORGEAX_ENGINE_RHI_DEBUG=0 bundle does NOT
+// contain 'engine-rhi-debug' string (AC-03).
+//
+// This test uses a static grep on the hello-cube production bundle. The
+// coverage job materializes that cold bundle before running package tests, so
+// an absent dist is a real gate failure rather than an implicit pass.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+function findDistFiles(rootDir: string): string[] {
+  const results: string[] = [];
+  function walk(dir: string): void {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+        walk(full);
+      } else if (
+        (e.name.endsWith('.mjs') || e.name.endsWith('.js')) &&
+        full.includes('/dist/assets/')
+      ) {
+        results.push(full);
+      }
+    }
+  }
+  walk(rootDir);
+  return results;
+}
+
+// I-14 fix-up (round 1 implement-review): the prior shape silently returned
+// when no dist bundles existed (cold worktree), making the gate look green
+// without a real grep. The explicit coverage prebuild now makes the absence
+// assertion below actionable.
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ENGINE_ROOT = path.resolve(__dirname, '..', '..', '..', '..');
+const COLD_DIST_ROOT = path.resolve(ENGINE_ROOT, 'apps', 'hello', 'cube', 'dist', 'assets');
+const DIST_FILES = findDistFiles(COLD_DIST_ROOT);
+
+describe('tree-shake grep gate (AC-03)', () => {
+  it('hello-cube cold production dist exists and does not contain engine-rhi-debug string', () => {
+    expect(DIST_FILES.length).toBeGreaterThan(0);
+    // Grep each .mjs file for the forbidden string.
+    const violations: string[] = [];
+    for (const fp of DIST_FILES) {
+      let content: string;
+      try {
+        content = fs.readFileSync(fp, 'utf-8');
+      } catch {
+        continue;
+      }
+      if (content.includes('engine-rhi-debug')) {
+        violations.push(fp);
+      }
+    }
+
+    // All demo dist bundles must be clean.
+    expect(violations).toEqual([]);
+  });
+});
+
+// Browser entry node-identifier grep (AC-16).
+//
+// The browser entry and its bundled import closure must carry zero Node-only
+// dependencies. The root remains realm-neutral and is tested separately.
+
+const BROWSER_DIST = path.resolve(__dirname, '..', '..', 'dist', 'browser.mjs');
+const BROWSER_DIST_EXISTS = fs.existsSync(BROWSER_DIST);
+
+const BARREL_SRC = path.resolve(__dirname, '..', 'index.ts');
+
+describe('browser entry isolation (AC-16)', () => {
+  it.skipIf(!BROWSER_DIST_EXISTS)(
+    'browser.mjs + import closure contain no fs / pngjs / ws identifiers',
+    () => {
+      const content = fs.readFileSync(BROWSER_DIST, 'utf-8');
+      // Match Node-builtin imports + the two Node-only deps by their import
+      // shapes. recorder-core / tape-format are inlined by tsup, so a hit here
+      // means the isolation broke (a node-tainted module crept into the closure).
+      const forbidden: RegExp[] = [
+        /\bnode:fs\b/,
+        /\bnode:path\b/,
+        /\bnode:crypto\b/,
+        /from\s+['"]fs['"]/,
+        /from\s+['"]path['"]/,
+        /\bpngjs\b/,
+        /from\s+['"]ws['"]/,
+        /require\(\s*['"]ws['"]\s*\)/,
+      ];
+      const hits = forbidden.filter((re) => re.test(content)).map((re) => re.source);
+      expect(hits).toEqual([]);
+    },
+  );
+
+  it('barrel index.ts does not re-export browser transport symbols', () => {
+    const barrel = fs.readFileSync(BARREL_SRC, 'utf-8');
+    const leaked = ['captureAndUpload', 'uploadTape'].filter((sym) => barrel.includes(sym));
+    expect(leaked).toEqual([]);
+  });
+});
+
+describe('retained core dependency boundary (OOS-5)', () => {
+  it('does not include viewer or host dependency identifiers in core production sources', () => {
+    const sourceFiles = [
+      'index.ts',
+      'frame-model.ts',
+      'protocol/codec.ts',
+      'replay/session.ts',
+    ].map((file) => path.resolve(__dirname, '..', file));
+    const forbidden = [
+      '@codemirror/',
+      'dockview',
+      '@forgeax/engine-naga',
+      "from 'react'",
+      'node:fs',
+      'node:path',
+    ];
+    const hits = sourceFiles.flatMap((file) => {
+      const source = fs.readFileSync(file, 'utf8');
+      return forbidden.filter((token) => source.includes(token)).map((token) => `${file}:${token}`);
+    });
+    expect(hits).toEqual([]);
+  });
+});
+
+describe('v7 cold model path', () => {
+  it('keeps protocol and model sources free of host-only imports', () => {
+    const sourcePaths = [
+      path.resolve(__dirname, '..', 'protocol', 'codec.ts'),
+      path.resolve(__dirname, '..', 'protocol', 'validation.ts'),
+      path.resolve(__dirname, '..', 'protocol', 'event-semantics.ts'),
+      path.resolve(__dirname, '..', 'protocol', 'tape-index.ts'),
+      path.resolve(__dirname, '..', 'frame-model.ts'),
+    ];
+    const forbidden = /^\s*(?:import|export).*\b(?:node:|pngjs|webgpu|vite|rhi-webgpu|rhi-wgpu)\b/m;
+    const hits = sourcePaths.flatMap((sourcePath) => {
+      const source = fs.readFileSync(sourcePath, 'utf8');
+      return forbidden.test(source) ? [sourcePath] : [];
+    });
+    expect(hits).toEqual([]);
+  });
+});

package/src/__tests__/types.test.ts

@@ -0,0 +1,257 @@
+// Unit — RhiCallEvent + Tape + work inspection type validation.
+//
+// Verifies that ~5 RhiCallEvent kinds can be constructed at the type level,
+// that they are JSON-serializable (no native GPU objects in the shape),
+// and that Tape / work inspection / RhiCapsRecorded types compile.
+
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type {
+  InspectBindingEntry,
+  InspectReport,
+  RhiCallEvent,
+  RhiCallEventBeginRenderPass,
+  RhiCallEventCreateBuffer,
+  RhiCallEventDraw,
+  RhiCallEventDrawIndexed,
+  RhiCallEventSetBindGroup,
+  RhiCallEventSetPipeline,
+  RhiCallEventWriteBuffer,
+  RhiCapsRecorded,
+  Tape,
+} from '../types';
+
+describe('RhiCallEvent — closed union constructibility', () => {
+  it('createBuffer event shape', () => {
+    const ev: RhiCallEventCreateBuffer = {
+      kind: 'createBuffer',
+      handleId: 'buf-1',
+      desc: {
+        size: 256,
+        usage: 0,
+        mappedAtCreation: false,
+      },
+    };
+    expectTypeOf(ev).toMatchTypeOf<RhiCallEvent>();
+    // JSON serializable check
+    const json = JSON.stringify(ev);
+    expect(json).toContain('createBuffer');
+  });
+
+  it('writeBuffer event shape', () => {
+    const ev: RhiCallEventWriteBuffer = {
+      kind: 'writeBuffer',
+      handleId: 'buf-1',
+      bufferOffset: 0,
+      dataHash: 'abc123',
+      size: 256,
+    };
+    expectTypeOf(ev).toMatchTypeOf<RhiCallEvent>();
+    const json = JSON.stringify(ev);
+    expect(json).toContain('writeBuffer');
+  });
+
+  it('beginRenderPass event shape', () => {
+    const ev: RhiCallEventBeginRenderPass = {
+      kind: 'beginRenderPass',
+      cmdHandleId: 'cmd:1',
+      passHandleId: 'pass:1',
+      desc: {
+        colorAttachments: [],
+      },
+      colorAttachmentViewHandleIds: [],
+    };
+    expectTypeOf(ev).toMatchTypeOf<RhiCallEvent>();
+    // No native GPUTextureView in the shape — AC-10
+    const json = JSON.stringify(ev);
+    expect(json).not.toContain('[object');
+  });
+
+  it('setPipeline + draw event chain', () => {
+    const setP: RhiCallEventSetPipeline = {
+      kind: 'setPipeline',
+      passHandleId: 'pass:1',
+      pipelineHandleId: 'pipeline:1',
+    };
+    const draw: RhiCallEventDraw = {
+      kind: 'draw',
+      passHandleId: 'pass:1',
+      vertexCount: 3,
+      instanceCount: 1,
+      firstVertex: 0,
+      firstInstance: 0,
+    };
+    const indexedDraw: RhiCallEventDrawIndexed = {
+      kind: 'drawIndexed',
+      passHandleId: 'pass:1',
+      indexCount: 36,
+      instanceCount: 1,
+      firstIndex: 0,
+      baseVertex: 0,
+      firstInstance: 0,
+    };
+    expectTypeOf(setP).toMatchTypeOf<RhiCallEvent>();
+    expectTypeOf(draw).toMatchTypeOf<RhiCallEvent>();
+    expectTypeOf(indexedDraw).toMatchTypeOf<RhiCallEvent>();
+  });
+
+  it('setBindGroup event shape', () => {
+    const ev: RhiCallEventSetBindGroup = {
+      kind: 'setBindGroup',
+      passHandleId: 'pass:1',
+      index: 0,
+      bindGroupHandleId: 'bg:1',
+      dynamicOffsets: [0, 256],
+    };
+    expectTypeOf(ev).toMatchTypeOf<RhiCallEvent>();
+  });
+
+  it('closed union rejects non-existent kind (type-level)', () => {
+    // Verify RhiCallEvent is a discriminated union with ~40 kinds.
+    // The kind field is the discriminant — all union members have kind.
+    expectTypeOf<RhiCallEvent>().toHaveProperty('kind');
+    // The kind discriminator should match RHI method names
+    expectTypeOf<RhiCallEventCreateBuffer['kind']>().toMatchTypeOf<'createBuffer'>();
+  });
+});
+
+describe('Tape — constructibility', () => {
+  it('minimal tape compiles', () => {
+    const tape: Tape = {
+      formatVersion: 2,
+      rhiCapsRecorded: {
+        canvasFormat: 'bgra8unorm',
+        rgba16floatRenderable: true,
+        float32Filterable: false,
+        textureCompressionBc: true,
+        textureCompressionEtc2: false,
+        textureCompressionAstc: false,
+        storageBuffer: true,
+        timestampQuery: false,
+      },
+      events: [
+        {
+          kind: 'frameMark',
+          frameIdx: 0,
+        },
+      ],
+      blobPool: new Map(),
+    };
+    expectTypeOf(tape).toMatchTypeOf<Tape>();
+    expect(tape.formatVersion).toBe(2);
+    expect(tape.events).toHaveLength(1);
+  });
+
+  it('tape with events + blobPool compiles', () => {
+    const buf = new ArrayBuffer(16);
+    const tape: Tape = {
+      formatVersion: 2,
+      rhiCapsRecorded: {
+        canvasFormat: 'bgra8unorm',
+        rgba16floatRenderable: false,
+        float32Filterable: false,
+        textureCompressionBc: false,
+        textureCompressionEtc2: false,
+        textureCompressionAstc: false,
+        storageBuffer: true,
+        timestampQuery: false,
+      },
+      events: [
+        { kind: 'frameMark', frameIdx: 0 },
+        {
+          kind: 'createBuffer',
+          handleId: 'buf-1',
+          desc: { size: 16, usage: 0, mappedAtCreation: false },
+        },
+        {
+          kind: 'writeBuffer',
+          handleId: 'buf-1',
+          bufferOffset: 0,
+          dataHash: 'a1b2c3',
+          size: 16,
+        },
+      ],
+      blobPool: new Map([['a1b2c3', buf]]),
+    };
+    expect(tape.formatVersion).toBe(2);
+    expect(tape.blobPool.get('a1b2c3')).toBe(buf);
+  });
+});
+
+describe('RhiCapsRecorded — constructibility', () => {
+  it('minimal caps', () => {
+    const caps: RhiCapsRecorded = {
+      canvasFormat: 'bgra8unorm',
+      rgba16floatRenderable: false,
+      float32Filterable: false,
+      textureCompressionBc: false,
+      textureCompressionEtc2: false,
+      textureCompressionAstc: false,
+      storageBuffer: false,
+      timestampQuery: false,
+    };
+    expect(caps.canvasFormat).toBe('bgra8unorm');
+    expect(caps.rgba16floatRenderable).toBe(false);
+  });
+});
+
+describe('InspectReport — constructibility', () => {
+  it('full report without rt compiles', () => {
+    const report: InspectReport = {
+      frameIdx: 0,
+      workIndex: 5,
+      passIdx: 0,
+      bindings: [],
+      drawCall: {
+        pipelineKind: 'render',
+        pipelineHandleId: 'pipeline:1',
+      },
+    };
+    expectTypeOf(report).toMatchTypeOf<InspectReport>();
+    expect(report.frameIdx).toBe(0);
+    expect(report.workIndex).toBe(5);
+    expect(report.rt).toBeUndefined();
+  });
+
+  it('report with rt path as string (not base64)', () => {
+    const report: InspectReport = {
+      frameIdx: 0,
+      workIndex: 42,
+      passIdx: 1,
+      bindings: [],
+      drawCall: {
+        pipelineKind: 'compute',
+        pipelineHandleId: 'pipeline:2',
+        dispatchX: 16,
+        dispatchY: 1,
+        dispatchZ: 1,
+      },
+      rt: '.forgeax-debug/test-run/inspect/d0042-rt0.png',
+    };
+    // AC-19: rt is a path string, not base64 data URI
+    expect(report.rt).toContain('png');
+    expect(report.rt).not.toContain('base64');
+    expect(report.rt).not.toContain('data:');
+  });
+});
+
+describe('InspectBindingEntry — constructibility', () => {
+  it('buffer kind', () => {
+    const entry: InspectBindingEntry = {
+      groupIndex: 0,
+      entryIndex: 0,
+      handleId: 'buf-3',
+      kind: 'buffer',
+    };
+    expect(entry.kind).toBe('buffer');
+  });
+
+  it('texture kind', () => {
+    const entry: InspectBindingEntry = {
+      groupIndex: 1,
+      entryIndex: 2,
+      handleId: 'texture:5',
+      kind: 'texture',
+    };
+    expect(entry.kind).toBe('texture');
+  });
+});

package/src/browser.ts

@@ -0,0 +1,146 @@
+// @forgeax/engine-rhi-debug/browser -- browser-only capture transport.
+
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { RhiDebugError } from './errors';
+import type { CaptureFrameOptions, EncodedTape, RecorderAttachment } from './recorder/session';
+
+export interface BrowserCaptureProvider {
+  captureFrame(options?: CaptureFrameOptions): Promise<Result<EncodedTape, RhiDebugError>>;
+}
+
+export interface BrowserCaptureOptions {
+  readonly endpoint?: string;
+  readonly runId?: string;
+  readonly capture?: CaptureFrameOptions;
+  readonly signal?: AbortSignal;
+}
+
+export interface BrowserArtifactRef {
+  readonly kind: 'rhi-tape';
+  readonly digest: string;
+  readonly path?: string;
+}
+
+export type BrowserCaptureError =
+  | {
+      readonly code: 'browser-capture-transport-unavailable';
+      readonly expected: string;
+      readonly hint: string;
+      readonly detail: { readonly endpoint: string };
+    }
+  | {
+      readonly code: 'browser-capture-upload-failed';
+      readonly expected: string;
+      readonly hint: string;
+      readonly detail: { readonly endpoint: string; readonly status: number };
+    }
+  | {
+      readonly code: 'browser-capture-response-invalid';
+      readonly expected: string;
+      readonly hint: string;
+      readonly detail: { readonly endpoint: string; readonly cause: string };
+    };
+
+export function browserCaptureProvider(attachment: RecorderAttachment): BrowserCaptureProvider {
+  return attachment;
+}
+
+export async function captureAndUpload(
+  provider: BrowserCaptureProvider,
+  options: BrowserCaptureOptions = {},
+): Promise<Result<BrowserArtifactRef, RhiDebugError | BrowserCaptureError>> {
+  const captureOptions = mergeCaptureOptions(options.capture, options.signal);
+  const captured = await provider.captureFrame(captureOptions);
+  if (!captured.ok) return captured;
+  return uploadTape(captured.value, options);
+}
+
+export async function uploadTape(
+  tape: Pick<EncodedTape, 'bytes' | 'digest'>,
+  options: BrowserCaptureOptions = {},
+): Promise<Result<BrowserArtifactRef, BrowserCaptureError>> {
+  const endpoint = options.endpoint ?? '/__forgeax-debug/tape';
+  const runId = options.runId ?? createRunId();
+  const url = `${endpoint}?runId=${encodeURIComponent(runId)}`;
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-forgeax-rhitape' },
+      body: copyBytes(tape.bytes),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+  } catch {
+    return err({
+      code: 'browser-capture-transport-unavailable',
+      expected: 'the configured RHI tape endpoint to accept a browser upload',
+      hint: 'start the Vite RHI-debug transport or provide a reachable endpoint',
+      detail: { endpoint },
+    });
+  }
+
+  if (!response.ok) {
+    return err({
+      code: 'browser-capture-upload-failed',
+      expected: 'the RHI tape endpoint to accept the validated artifact',
+      hint: 'inspect the endpoint response and retry one capture',
+      detail: { endpoint, status: response.status },
+    });
+  }
+
+  let value: unknown;
+  try {
+    value = await response.json();
+  } catch (cause) {
+    return err({
+      code: 'browser-capture-response-invalid',
+      expected: 'the RHI tape endpoint to return a JSON artifact reference',
+      hint: 'check the dev transport response body before retrying',
+      detail: { endpoint, cause: String(cause) },
+    });
+  }
+  if (!isArtifactRef(value)) {
+    return err({
+      code: 'browser-capture-response-invalid',
+      expected: 'the RHI tape endpoint to return a rhi-tape artifact reference',
+      hint: 'check the endpoint contract and capture again',
+      detail: { endpoint, cause: 'response is not a rhi-tape artifact reference' },
+    });
+  }
+  return ok(value);
+}
+
+function mergeCaptureOptions(
+  capture: CaptureFrameOptions | undefined,
+  signal: AbortSignal | undefined,
+): CaptureFrameOptions | undefined {
+  if (capture === undefined && signal === undefined) return undefined;
+  return { ...capture, ...(signal === undefined ? {} : { signal }) };
+}
+
+function createRunId(): string {
+  const randomUUID = globalThis.crypto?.randomUUID;
+  return randomUUID === undefined
+    ? `rhi-capture-${Date.now().toString(36)}`
+    : `rhi-capture-${randomUUID()}`;
+}
+
+function copyBytes(bytes: Uint8Array): ArrayBuffer {
+  const copy = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(copy).set(bytes);
+  return copy;
+}
+
+function isArtifactRef(value: unknown): value is BrowserArtifactRef {
+  if (value === null || typeof value !== 'object') return false;
+  const candidate = value as {
+    readonly kind?: unknown;
+    readonly digest?: unknown;
+    readonly path?: unknown;
+  };
+  return (
+    candidate.kind === 'rhi-tape' &&
+    typeof candidate.digest === 'string' &&
+    (candidate.path === undefined || typeof candidate.path === 'string')
+  );
+}