@forgeax/engine-render 0.1.2

package/src/__tests__/render-feature-assembly.test-d.ts

@@ -0,0 +1,51 @@
+import { ok } from '@forgeax/engine-types';
+import type { RenderFeature } from '../features/types';
+import type { RendererOptions } from '../renderer';
+
+type BoundsFrame = {
+  readonly visibleCount: number;
+};
+
+type OverlayFrame = {
+  readonly layer: 'overlay';
+};
+
+const boundsFeature = {
+  identity: 'test.bounds',
+  extract({ owner }) {
+    return ok({ visibleCount: owner });
+  },
+  prepare(data: BoundsFrame) {
+    const count: number = data.visibleCount;
+    void count;
+    return ok(undefined);
+  },
+  contribute(data: BoundsFrame) {
+    const count: number = data.visibleCount;
+    void count;
+    return ok(undefined);
+  },
+} satisfies RenderFeature<BoundsFrame>;
+
+const overlayFeature = {
+  identity: 'test.overlay',
+  extract() {
+    return ok({ layer: 'overlay' as const });
+  },
+  prepare(data: OverlayFrame) {
+    const layer: 'overlay' = data.layer;
+    void layer;
+    return ok(undefined);
+  },
+  contribute(data: OverlayFrame) {
+    const layer: 'overlay' = data.layer;
+    void layer;
+    return ok(undefined);
+  },
+} satisfies RenderFeature<OverlayFrame>;
+
+const rendererOptions = {
+  features: [boundsFeature, overlayFeature],
+} satisfies RendererOptions;
+
+void rendererOptions;

package/src/__tests__/render-feature-construction.unit.test.ts

@@ -0,0 +1,124 @@
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { RenderFeatureStageFailedError } from '../errors/render';
+import { createRenderFeatureHost, type RenderFeatureOwnedResource } from '../features/host';
+import type { RenderFeature } from '../features/types';
+
+function feature(identity: string): RenderFeature<{ readonly ready: true }> {
+  return {
+    identity,
+    extract: () => ok({ ready: true }),
+    prepare: () => ok(undefined),
+    contribute: () => ok(undefined),
+  };
+}
+
+function resource(
+  name: string,
+  release: () => ReturnType<RenderFeatureOwnedResource['release']>,
+): RenderFeatureOwnedResource {
+  return {
+    handle: { __renderFeatureResource: Symbol(name) } as never,
+    release,
+  };
+}
+
+describe('render feature construction ownership', () => {
+  it('rejects duplicate identity before a host can acquire resources', () => {
+    const result = createRenderFeatureHost([
+      feature('synthetic.shared'),
+      feature('synthetic.shared'),
+    ]);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok && result.error.code === 'render-feature-registration-conflict') {
+      expect(result.error.code).toBe('render-feature-registration-conflict');
+      expect(result.error.detail.featureIdentity).toBe('synthetic.shared');
+    }
+  });
+
+  it('cleans transferred resources in registration order and isolates failures', () => {
+    const host = createRenderFeatureHost([
+      feature('synthetic.first'),
+      feature('synthetic.second'),
+    ]).unwrap();
+    const released: string[] = [];
+
+    host.registerResource(
+      'synthetic.first',
+      resource('first', () => {
+        released.push('first');
+        return ok(undefined);
+      }),
+    );
+    host.registerResource(
+      'synthetic.second',
+      resource('second-fails', () => {
+        released.push('second-fails');
+        return err(
+          new RenderFeatureStageFailedError('synthetic.second', 1, 'dispose', 'renderer-recover'),
+        );
+      }),
+    );
+    host.registerResource(
+      'synthetic.second',
+      resource('second-after-failure', () => {
+        released.push('second-after-failure');
+        return ok(undefined);
+      }),
+    );
+
+    const disposed = host.dispose();
+
+    expect(released).toEqual(['first', 'second-fails', 'second-after-failure']);
+    expect(disposed.ok).toBe(false);
+    if (!disposed.ok && disposed.error.code === 'render-feature-stage-failed') {
+      expect(disposed.error.code).toBe('render-feature-stage-failed');
+      expect(disposed.error.detail.stage).toBe('dispose');
+      const cleanupFailures = disposed.error.detail.cleanupFailures;
+      expect(cleanupFailures).toHaveLength(1);
+      if (cleanupFailures !== undefined) {
+        expect(cleanupFailures[0]?.featureIdentity).toBe('synthetic.second');
+      }
+    }
+
+    expect(host.dispose()).toEqual(ok(undefined));
+    expect(released).toEqual(['first', 'second-fails', 'second-after-failure']);
+  });
+
+  it('uninstalls one feature without disposing its neighbors', () => {
+    const disposed: string[] = [];
+    const first = {
+      ...feature('synthetic.first'),
+      dispose: () => {
+        disposed.push('first');
+        return ok(undefined);
+      },
+    };
+    const second = {
+      ...feature('synthetic.second'),
+      dispose: () => {
+        disposed.push('second');
+        return ok(undefined);
+      },
+    };
+    const host = createRenderFeatureHost([first, second]).unwrap();
+    const released: string[] = [];
+    host.registerResource(
+      'synthetic.first',
+      resource('first', () => {
+        released.push('first');
+        return ok(undefined);
+      }),
+    );
+
+    expect(host.uninstall(first)).toEqual(ok(undefined));
+    expect(host.features).toEqual([second]);
+    expect(released).toEqual(['first']);
+    expect(disposed).toEqual(['first']);
+    expect(host.uninstall(first)).toEqual(ok(undefined));
+
+    expect(host.dispose()).toEqual(ok(undefined));
+    expect(disposed).toEqual(['first', 'second']);
+  });
+});

package/src/__tests__/render-feature-context.test-d.ts

@@ -0,0 +1,81 @@
+import type { World } from '@forgeax/engine-ecs';
+import { ok } from '@forgeax/engine-types';
+import type { RenderFeature } from '../features/types';
+
+type Frame = {
+  readonly count: number;
+};
+
+const feature = {
+  identity: 'synthetic.context-boundary',
+  extract(context) {
+    const worlds: readonly World[] = context.worlds;
+    const owner: number = context.owner;
+    const frameNumber: number = context.frameNumber;
+    void worlds;
+    void owner;
+    void frameNumber;
+
+    // @ts-expect-error extract must not receive a prepare-stage runtime surface
+    context.runtime;
+    // @ts-expect-error extract must not receive a GPU command encoder
+    context.encoder;
+    return ok({ count: worlds.length });
+  },
+  prepare(data, context) {
+    const count: number = data.count;
+    const caps = context.caps;
+    const resources = context.resources;
+    const targets = context.targets;
+    const frame = context.frame;
+    const reportError = context.reportError;
+    void count;
+    void caps;
+    void resources;
+    void targets;
+    void frame;
+    void reportError;
+
+    // @ts-expect-error prepare must not receive the live World collection
+    context.worlds;
+    // @ts-expect-error prepare must not receive the complete pipeline context
+    context.pipeline;
+    // @ts-expect-error prepare must not receive a raw device
+    context.device;
+    // @ts-expect-error prepare must not expose submit or compute commands
+    context.submit;
+    // @ts-expect-error prepare must not expose storage or indirect commands
+    context.storageBuffer;
+    // @ts-expect-error prepare must not expose the full command encoder
+    context.commandEncoder;
+    return ok(undefined);
+  },
+  contribute(data, context) {
+    const count: number = data.count;
+    const frame = context.frame;
+    const resources = context.resources;
+    const targets = context.targets;
+    const reportError = context.reportError;
+    void count;
+    void frame;
+    void resources;
+    void targets;
+    void reportError;
+
+    // @ts-expect-error contribute must not receive the live World collection
+    context.worlds;
+    // @ts-expect-error contribute must not receive the complete pipeline context
+    context.pipeline;
+    // @ts-expect-error contribute must not expose raw device access
+    context.device;
+    // @ts-expect-error contribute must not expose submit, compute, or storage commands
+    context.submit;
+    // @ts-expect-error contribute must not expose indirect draw commands
+    context.drawIndirect;
+    // @ts-expect-error Wave1 stops at the graph seam and exposes no GPU commands
+    context.commands;
+    return ok(undefined);
+  },
+} satisfies RenderFeature<Frame>;
+
+void feature;

package/src/__tests__/render-feature-contract.test-d.ts

@@ -0,0 +1,58 @@
+import { ok } from '@forgeax/engine-types';
+import type { RenderFeature } from '../features/types';
+
+type AlphaFrame = {
+  readonly visibleCount: number;
+};
+
+type BetaFrame = {
+  readonly bounds: readonly [number, number, number, number];
+};
+
+const alphaFeature = {
+  identity: 'synthetic.alpha',
+  extract({ owner }) {
+    const frame: AlphaFrame = { visibleCount: owner };
+    return ok(frame);
+  },
+  prepare(data: AlphaFrame) {
+    const count: number = data.visibleCount;
+    void count;
+    return ok(undefined);
+  },
+  contribute(data: AlphaFrame) {
+    const count: number = data.visibleCount;
+    void count;
+    return ok(undefined);
+  },
+} satisfies RenderFeature<AlphaFrame>;
+
+const betaFeature = {
+  identity: 'synthetic.beta',
+  extract() {
+    return ok({ bounds: [0, 0, 1, 1] as const });
+  },
+  prepare(data: BetaFrame) {
+    const bounds: BetaFrame['bounds'] = data.bounds;
+    void bounds;
+    return ok(undefined);
+  },
+  contribute(data: BetaFrame) {
+    const bounds: BetaFrame['bounds'] = data.bounds;
+    void bounds;
+    return ok(undefined);
+  },
+} satisfies RenderFeature<BetaFrame>;
+
+const heterogeneousFeatures = [
+  alphaFeature,
+  betaFeature,
+] satisfies readonly RenderFeature<unknown>[];
+
+for (const feature of heterogeneousFeatures) {
+  const identity: string = feature.identity;
+  void identity;
+}
+
+void alphaFeature;
+void betaFeature;

package/src/__tests__/render-feature-diagnostics.unit.test.ts

@@ -0,0 +1,151 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { RenderFeatureStageFailedError } from '../errors/render';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import type { RenderFeature } from '../features/types';
+
+const caps = (compute: boolean): Readonly<RhiCaps> => ({ compute }) as unknown as RhiCaps;
+
+function gatedFeature(): RenderFeature<{ readonly frame: number }> {
+  return {
+    identity: 'synthetic.gated',
+    requiredCapabilities: ['compute'],
+    extract: ({ frameNumber }) => ok({ frame: frameNumber }),
+    prepare: () => ok(undefined),
+    contribute: () => ok(undefined),
+  };
+}
+
+describe('render feature diagnostics and capability gate', () => {
+  it('notifies only lifecycle projection changes and stops after unsubscribe', () => {
+    const host = createRenderFeatureHost([gatedFeature()], caps(true)).unwrap();
+    let notifications = 0;
+    const unsubscribe = host.subscribeDiagnostics(() => {
+      notifications += 1;
+    });
+
+    expect(host.setStatus('synthetic.gated', 'active')).toEqual(ok(undefined));
+    expect(notifications).toBe(0);
+
+    expect(host.setStatus('synthetic.gated', 'disabled')).toEqual(ok(undefined));
+    expect(notifications).toBe(1);
+    expect(host.setStatus('synthetic.gated', 'active')).toEqual(ok(undefined));
+    expect(notifications).toBe(2);
+
+    unsubscribe();
+    expect(host.setStatus('synthetic.gated', 'disabled')).toEqual(ok(undefined));
+    expect(notifications).toBe(2);
+  });
+
+  it('isolates a throwing diagnostics observer from renderer lifecycle changes', () => {
+    const host = createRenderFeatureHost([gatedFeature()], caps(true)).unwrap();
+    let healthyNotifications = 0;
+    host.subscribeDiagnostics(() => {
+      throw new Error('observer failed');
+    });
+    host.subscribeDiagnostics(() => {
+      healthyNotifications += 1;
+    });
+
+    expect(host.setStatus('synthetic.gated', 'disabled')).toEqual(ok(undefined));
+    expect(host.diagnostics()[0]?.status).toBe('disabled');
+    expect(healthyNotifications).toBe(1);
+    expect(() => host.dispose()).not.toThrow();
+  });
+
+  it('installs a late feature once and keeps identity conflicts explicit', () => {
+    const host = createRenderFeatureHost([], caps(true)).unwrap();
+    const feature = gatedFeature();
+    expect(host.install(feature)).toEqual(ok(undefined));
+    expect(host.install(feature)).toEqual(ok(undefined));
+    expect(host.size).toBe(1);
+    expect(host.install(gatedFeature())).toMatchObject({
+      ok: false,
+      error: { code: 'render-feature-registration-conflict' },
+    });
+    expect(
+      runRenderFeatureFrame(host, {
+        worlds: [],
+        owner: 0,
+        frameNumber: 1,
+        caps: caps(true),
+      }).stageEvents,
+    ).toHaveLength(3);
+  });
+
+  it('disables without a capability and re-enables only after recover re-evaluation', () => {
+    const host = createRenderFeatureHost([gatedFeature()], caps(false)).unwrap();
+    const first = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: caps(false),
+    });
+
+    expect(first.stageEvents).toEqual([]);
+    expect(first.errors).toHaveLength(1);
+    expect(first.errors[0]?.code).toBe('render-feature-capability-missing');
+    expect(host.diagnostics()[0]?.status).toBe('disabled');
+
+    const stillDisabled = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 2,
+      caps: caps(true),
+    });
+    expect(stillDisabled.stageEvents).toEqual([]);
+
+    expect(host.recover({ frameNumber: 3, caps: caps(true) })).toEqual(ok(undefined));
+    expect(host.diagnostics()[0]?.status).toBe('active');
+    expect(
+      runRenderFeatureFrame(host, {
+        worlds: [],
+        owner: 0,
+        frameNumber: 3,
+        caps: caps(true),
+      }).stageEvents,
+    ).toHaveLength(3);
+  });
+
+  it('replaces the latest stage failure after retry and returns deep readonly snapshots', () => {
+    let shouldFail = true;
+    const feature: RenderFeature<{ readonly ready: true }> = {
+      identity: 'synthetic.latest-error',
+      extract: () => ok({ ready: true }),
+      prepare: () => {
+        if (shouldFail) {
+          return err(
+            new RenderFeatureStageFailedError('synthetic.latest-error', 0, 'prepare', 'next-frame'),
+          );
+        }
+        return ok(undefined);
+      },
+      contribute: () => ok(undefined),
+    };
+    const host = createRenderFeatureHost([feature], caps(true)).unwrap();
+
+    runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: caps(true),
+    });
+    const failed = host.diagnostics();
+    expect(failed[0]?.latestError?.code).toBe('render-feature-stage-failed');
+    expect(Object.isFrozen(failed)).toBe(true);
+    expect(Object.isFrozen(failed[0])).toBe(true);
+    expect(Object.isFrozen(failed[0]?.latestError)).toBe(true);
+    expect(Object.isFrozen(failed[0]?.latestError?.detail)).toBe(true);
+
+    shouldFail = false;
+    runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 2,
+      caps: caps(true),
+    });
+    expect(host.diagnostics()[0]?.status).toBe('active');
+    expect(host.diagnostics()[0]?.latestError).toBeUndefined();
+  });
+});

package/src/__tests__/render-feature-docs.unit.test.ts

@@ -0,0 +1,88 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import {
+  RenderFeatureCapabilityMissingError,
+  RenderFeaturePassOrderConflictError,
+  RenderFeatureRegistrationConflictError,
+  RenderFeatureStageFailedError,
+} from '../errors/render';
+
+function read(relativePath: string): string {
+  return readFileSync(new URL(relativePath, import.meta.url), 'utf8');
+}
+
+const renderReadme = read('../../README.md');
+const runtimeReadme = read('../../../runtime/README.md');
+const appSkill = read('../../../../skills/forgeax-engine-app/SKILL.md');
+
+// M4-06 prepends the direct-light contract; keep the existing first-read
+// vocabulary assertion wide enough to cover that approved contract.
+const topSurface = renderReadme.slice(0, 18000);
+
+describe('RenderFeature documentation surface', () => {
+  it('keeps the first-read public route and four-term vocabulary indexable', () => {
+    for (const token of [
+      '## RenderFeature: the producer seam',
+      'type FrameData',
+      'createRenderer(canvas, { features: [feature] })',
+      "context.staging.addPass('named-pass'",
+      'execute: ({ pass })',
+      'active RenderGraph',
+      'RenderFeature',
+      'RenderPipeline',
+      'RenderGraph pass',
+      'Material pass',
+    ]) {
+      expect(topSurface).toContain(token);
+    }
+    expect(topSurface).not.toContain('passContext.commands');
+    expect(topSurface).toContain('graph-only Wave 1 feature');
+    expect(runtimeReadme).toContain('createRenderer(canvas, options?, bundler?)');
+    expect(appSkill).toContain('Renderer feature assembly');
+  });
+
+  it('indexes capability, structured error, recovery, disposal, and pipeline switching', () => {
+    const surface = `${renderReadme}\n${runtimeReadme}\n${appSkill}`;
+    for (const token of [
+      'Readonly<RhiCaps>',
+      'RenderError',
+      'error.code',
+      'error.hint',
+      'error.detail',
+      'renderFeatureDiagnostics()',
+      'renderer.recover()',
+      'renderer.dispose()',
+      'renderer.registerPipeline(id, pipeline)',
+    ]) {
+      expect(surface).toContain(token);
+    }
+  });
+
+  it('keeps the error hint actions aligned with the recovery matrix', () => {
+    const cases = [
+      {
+        error: new RenderFeatureRegistrationConflictError('test.feature', 1, 0),
+        recoveryToken: 'registration',
+      },
+      {
+        error: new RenderFeatureStageFailedError('test.feature', 1, 'prepare', 'next-frame'),
+        recoveryToken: 'next frame',
+      },
+      {
+        error: new RenderFeatureCapabilityMissingError('test.feature', 1, 'compute'),
+        recoveryToken: 'capability',
+      },
+      {
+        error: new RenderFeaturePassOrderConflictError('test.feature', 1, 'overlay', 'main'),
+        recoveryToken: 'reorder',
+      },
+    ];
+
+    for (const { error, recoveryToken } of cases) {
+      expect(error.hint.toLowerCase()).toContain(recoveryToken);
+      expect(`${renderReadme}\n${runtimeReadme}\n${appSkill}`.toLowerCase()).toContain(
+        recoveryToken,
+      );
+    }
+  });
+});

package/src/__tests__/render-feature-error-code-owner.test-d.ts

@@ -0,0 +1,27 @@
+import { expectTypeOf, it } from 'vitest';
+import type {
+  RenderFeatureErrorCode,
+  RenderFeatureErrorDescriptor,
+  RenderFeatureErrorDetailByCode,
+} from '../features/types';
+import type {
+  RenderFeatureErrorCode as PublicRenderFeatureErrorCode,
+  RenderFeatureErrorDescriptor as PublicRenderFeatureErrorDescriptor,
+} from '../index';
+
+type DescriptorDetailsByCode = {
+  [Code in keyof RenderFeatureErrorDetailByCode]: Extract<
+    RenderFeatureErrorDescriptor,
+    { readonly code: Code }
+  >['detail'];
+};
+
+it('derives the public feature error code projection from its detail map', () => {
+  expectTypeOf<RenderFeatureErrorCode>().toEqualTypeOf<keyof RenderFeatureErrorDetailByCode>();
+  expectTypeOf<keyof RenderFeatureErrorDetailByCode>().toEqualTypeOf<RenderFeatureErrorCode>();
+  expectTypeOf<PublicRenderFeatureErrorCode>().toEqualTypeOf<RenderFeatureErrorCode>();
+  expectTypeOf<PublicRenderFeatureErrorDescriptor>().toEqualTypeOf<RenderFeatureErrorDescriptor>();
+  expectTypeOf<DescriptorDetailsByCode>().toEqualTypeOf<RenderFeatureErrorDetailByCode>();
+  expectTypeOf<'render-feature-not-real'>().not.toExtend<RenderFeatureErrorCode>();
+  expectTypeOf<'render-feature-not-real'>().not.toExtend<PublicRenderFeatureErrorCode>();
+});

package/src/__tests__/render-feature-errors.unit.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { ObservationUnavailableError } from '../errors/render';
+import type { RenderFeatureErrorCode, RenderFeatureErrorDescriptor } from '../features/types';
+
+const renderFeatureErrorCodes: readonly RenderFeatureErrorCode[] = [
+  'render-feature-registration-conflict',
+  'render-feature-stage-failed',
+  'render-feature-capability-missing',
+  'render-feature-pass-order-conflict',
+  'render-feature-preparation-failed',
+  'render-feature-prepared-state-mismatch',
+  'render-feature-draw-recording-failed',
+];
+
+function describeError(error: RenderFeatureErrorDescriptor): string {
+  switch (error.code) {
+    case 'render-feature-registration-conflict':
+      return error.detail.featureIdentity;
+    case 'render-feature-stage-failed':
+      return `${error.detail.featureIdentity}:${error.detail.stage}`;
+    case 'render-feature-capability-missing':
+      return error.detail.featureIdentity;
+    case 'render-feature-pass-order-conflict':
+      return error.detail.featureIdentity;
+    case 'render-feature-preparation-failed':
+      return error.detail.featureIdentity;
+    case 'render-feature-prepared-state-mismatch':
+      return error.detail.featureIdentity;
+    case 'render-feature-draw-recording-failed':
+      return error.detail.featureIdentity;
+  }
+}
+
+describe('render feature error vocabulary', () => {
+  it('keeps the four feature codes closed and machine-readable', () => {
+    expect(renderFeatureErrorCodes).toHaveLength(7);
+    expect(describeError).toBeTypeOf('function');
+  });
+
+  it('keeps observation recovery structured and producer-owned', () => {
+    const error = new ObservationUnavailableError('stale', 'draw a fresh current frame');
+    expect(error.code).toBe('observation-unavailable');
+    expect(error.expected).toContain('rgba16float');
+    expect(error.hint).toContain('fresh');
+    expect(error.detail).toEqual({ reason: 'stale', recovery: 'draw-current-frame' });
+  });
+});

package/src/__tests__/render-feature-gpu-buffer-usage-owner.test-d.ts

@@ -0,0 +1,46 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type {
+  RenderFeatureGpuBufferDescriptor,
+  RenderFeatureGpuBufferUsage,
+} from '../features/prepared-gpu-work';
+
+type ExpectedBufferUsage = 'storage' | 'uniform' | 'indirect' | 'vertex' | 'index' | 'copy-src';
+
+const preparedGpuWorkSource = readFileSync(
+  new URL('../features/prepared-gpu-work.ts', import.meta.url),
+  'utf8',
+);
+
+describe('render feature GPU buffer usage owner', () => {
+  it('keeps the public usage vocabulary bilateral and descriptor-assignable', () => {
+    expectTypeOf<RenderFeatureGpuBufferUsage>().toEqualTypeOf<ExpectedBufferUsage>();
+    expectTypeOf<ExpectedBufferUsage>().toEqualTypeOf<RenderFeatureGpuBufferUsage>();
+
+    const descriptor = {
+      size: 24,
+      usage: ['storage', 'uniform', 'indirect', 'vertex', 'index', 'copy-src'],
+    } as const satisfies RenderFeatureGpuBufferDescriptor;
+    expectTypeOf<(typeof descriptor.usage)[number]>().toEqualTypeOf<RenderFeatureGpuBufferUsage>();
+
+    const acceptsDescriptor = (_descriptor: RenderFeatureGpuBufferDescriptor): void => {};
+    acceptsDescriptor(descriptor);
+    // @ts-expect-error unknown usage keys remain outside the closed owner vocabulary.
+    acceptsDescriptor({ size: 4, usage: ['map-read'] });
+  });
+
+  it('keeps BUFFER_USAGE as the executable source of the public vocabulary', () => {
+    expect(preparedGpuWorkSource).toContain(
+      'export type RenderFeatureGpuBufferUsage = keyof typeof BUFFER_USAGE;',
+    );
+    expect(preparedGpuWorkSource).not.toContain(
+      "export type RenderFeatureGpuBufferUsage =\n  | 'storage'",
+    );
+    expect(preparedGpuWorkSource).toContain('storage: 0x0080');
+    expect(preparedGpuWorkSource).toContain('uniform: 0x0040');
+    expect(preparedGpuWorkSource).toContain('indirect: 0x0100');
+    expect(preparedGpuWorkSource).toContain('vertex: 0x0020');
+    expect(preparedGpuWorkSource).toContain('index: 0x0010');
+    expect(preparedGpuWorkSource).toContain("'copy-src': 0x0004");
+  });
+});