@forgeax/engine-render 0.1.33 → 0.1.34

package/src/__tests__/device-loss-fanout.unit.test.ts

@@ -1,4 +1,4 @@
-import type { RhiDevice } from '@forgeax/engine-rhi';
+import { err, type RhiDevice, RhiError } from '@forgeax/engine-rhi';
 import { rhi } from '@forgeax/engine-rhi-null';
 import { describe, expect, it } from 'vitest';
 import { attachDeviceLostFanout } from '../assembly/recovery/device-loss-fanout';
@@ -20,6 +20,41 @@ function deferred<T>(): {
 }
 
 describe('device loss fan-out generation fence', () => {
+  it('forwards replacement-device validation errors and fences retired devices', () => {
+    let current = 0;
+    const errorRegistry = new RhiErrorListenerRegistry();
+    const errors: unknown[] = [];
+    errorRegistry.add((error) => errors.push(error));
+    const failure = new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: 'valid GPU work',
+      hint: 'repair the pipeline',
+    });
+    const native: { onuncapturederror?: (event: unknown) => void } = {};
+    attachDeviceLostFanout(
+      { lost: new Promise(() => undefined) } as unknown as RhiDevice,
+      {
+        rhi,
+        _internal_getRawDevice: () => native,
+        translateErrorEventToRhiError: () => err(failure),
+      },
+      {
+        lostRegistry: new LostListenerRegistry(),
+        errorRegistry,
+        healthRegistry: new HealthListenerRegistry(),
+        generation: 1,
+        currentGeneration: () => current,
+      },
+    );
+    expect(native.onuncapturederror).toBeTypeOf('function');
+    current = 1;
+    native.onuncapturederror?.({});
+    expect(errors).toEqual([failure]);
+    current = 2;
+    native.onuncapturederror?.({});
+    expect(errors).toEqual([failure]);
+  });
+
   it('counts a late old-generation notification without changing active health', async () => {
     const lost = deferred<{ readonly reason: 'unknown'; readonly message: string }>();
     const lostRegistry = new LostListenerRegistry();

package/src/__tests__/docs-gate-green.unit.test.ts

@@ -1,22 +1,133 @@
 import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
 import { describe, expect, it } from 'vitest';
 
 function read(relativePath: string): string {
   return readFileSync(new URL(relativePath, import.meta.url), 'utf8');
 }
 
+function publicPackagePaths(): ts.MapLike<string[]> {
+  const paths: ts.MapLike<string[]> = {};
+  for (const packageName of [
+    '@forgeax/engine-assets-runtime',
+    '@forgeax/engine-ecs',
+    '@forgeax/engine-geometry',
+    '@forgeax/engine-render',
+    '@forgeax/engine-scene',
+    '@forgeax/engine-types',
+  ]) {
+    const packageDirectory = packageName.slice('@forgeax/engine-'.length);
+    paths[packageName] = [`packages/${packageDirectory}/src/index.ts`];
+  }
+  return paths;
+}
+
 const renderReadme = read('../../README.md');
 const assetsReadme = read('../../../assets-runtime/README.md');
 const instancesSource = read('../components/instances.ts');
+const repositoryRoot = fileURLToPath(new URL('../../../../', import.meta.url));
+
+function readWaterConsumerCodeBlock(): string {
+  const marker = renderReadme.indexOf('export async function drawProbeLitWater(');
+  const blockStart = renderReadme.lastIndexOf('```ts', marker);
+  const blockEnd = renderReadme.indexOf('```', marker);
+  expect(marker).toBeGreaterThanOrEqual(0);
+  expect(blockStart).toBeGreaterThanOrEqual(0);
+  expect(blockEnd).toBeGreaterThan(blockStart);
+  return renderReadme.slice(blockStart + '```ts'.length, blockEnd);
+}
+
+function semanticDiagnosticsFor(sourceText: string): readonly ts.Diagnostic[] {
+  const virtualFile = path.join(repositoryRoot, 'packages/render/.docs-gate/water-consumer.ts');
+  const options: ts.CompilerOptions = {
+    allowImportingTsExtensions: true,
+    baseUrl: repositoryRoot,
+    ignoreDeprecations: '6.0',
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    noEmit: true,
+    paths: publicPackagePaths(),
+    skipLibCheck: true,
+    strict: true,
+    target: ts.ScriptTarget.ES2022,
+    types: ['node'],
+  };
+  const defaultHost = ts.createCompilerHost(options, true);
+  const host: ts.CompilerHost = {
+    ...defaultHost,
+    fileExists: (fileName) => fileName === virtualFile || defaultHost.fileExists(fileName),
+    readFile: (fileName) =>
+      fileName === virtualFile ? sourceText : defaultHost.readFile(fileName),
+    getSourceFile: (fileName, languageVersion, onError, shouldCreateNewSourceFile) =>
+      fileName === virtualFile
+        ? ts.createSourceFile(fileName, sourceText, languageVersion, true, ts.ScriptKind.TS)
+        : defaultHost.getSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile),
+  };
+  const program = ts.createProgram([virtualFile], options, host);
+  const sourceFile = program.getSourceFile(virtualFile);
+  expect(sourceFile).toBeDefined();
+  return [
+    ...program.getOptionsDiagnostics(),
+    ...program.getSyntacticDiagnostics(sourceFile),
+    ...program.getSemanticDiagnostics(sourceFile),
+  ];
+}
+
+function formatDiagnostics(diagnostics: readonly ts.Diagnostic[]): string[] {
+  return diagnostics.map((diagnostic) =>
+    ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'),
+  );
+}
 
 describe('M4 material and Instances documentation contract', () => {
+  it('semantically checks the complete public water consumer code block', () => {
+    const snippet = readWaterConsumerCodeBlock();
+    const recovery = snippet.indexOf('const recoverAndRepublish = async');
+    expect(recovery).toBeGreaterThanOrEqual(0);
+    const diagnostics = semanticDiagnosticsFor(snippet);
+    expect(formatDiagnostics(diagnostics)).toEqual([]);
+    expect(snippet).not.toContain('renderer.initialization');
+    expect(snippet).toContain('const attachment = renderer.attach(world);');
+    expect(snippet).toContain('if (!attachment.ok) throw attachment.error;');
+    expect(snippet).toContain('const attached = attachment.value;');
+    for (const consumer of [
+      'renderer.inspect().frame.deviceGeneration',
+      'renderer.attach(world)',
+      '.draw({',
+    ]) {
+      expect(snippet.indexOf(consumer)).toBeGreaterThanOrEqual(0);
+    }
+    for (const recoveryFact of [
+      "renderer.state() !== 'device-lost'",
+      'await renderer.recover()',
+      'page.reconfigureDevice(nextDeviceGeneration)',
+      'const previousRanges = ranges',
+      'ranges = reserveFreshRanges()',
+      'projectionRevision += 1',
+      'publishDynamicInput(world.getResource(Time).elapsed)',
+      'submitted = await submitAndObserve()',
+      'const inspection = renderer.inspect()',
+      'submitted.deviceGeneration !== publishedDeviceGeneration',
+    ]) {
+      expect(snippet.indexOf(recoveryFact, recovery)).toBeGreaterThanOrEqual(recovery);
+    }
+    expect(snippet).toContain(
+      'renderer.setSurfaceDynamicInput({ page, ranges, projectionRevision, frameTime: now })',
+    );
+    expect(snippet).toContain('retry the same lease after the page and ranges are revalidated');
+    expect(snippet).not.toContain('commitUpload(');
+    expect(snippet).not.toContain('consume(');
+  }, 30_000);
+
   it('keeps resident observation and derived-bounds recovery discoverable', () => {
     for (const token of [
       'renderer.inspect().meshMaterialBindings[]',
       '`ready`, `pending`, `failed`, or `last-known-good`',
       'nearest structured preparation',
       'does not keep a second readiness ledger',
-      '`Instances` is a lightweight ECS association',
+      '`Instances.transforms` holds packed column-major mat4 values in World-managed',
       'derives CPU union bounds',
       'conservative no-cull result',
       'mesh AABB',