@flighthq/vite-plugin-manifest 0.5.1-next.1680.bdc44c6

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@flighthq/vite-plugin-manifest",
+  "version": "0.5.1-next.1680.bdc44c6",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flighthq/flight.git",
+    "directory": "packages/vite-plugin-manifest"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/log": "0.5.1-next.1680.bdc44c6",
+    "@flighthq/requirement-codegen": "0.5.1-next.1680.bdc44c6",
+    "@flighthq/scene3d-formats": "0.5.1-next.1680.bdc44c6",
+    "@flighthq/swf": "0.5.1-next.1680.bdc44c6",
+    "@flighthq/types": "0.5.1-next.1680.bdc44c6"
+  },
+  "devDependencies": {
+    "@flighthq/render": "*",
+    "@flighthq/requirement": "*",
+    "@flighthq/scene2d-dom": "*",
+    "typescript": "^5.3.0",
+    "vite": "*"
+  },
+  "description": "Vite plugin serving generated Flight registration source from analyzed content",
+  "sideEffects": false,
+  "peerDependencies": {
+    "vite": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": false
+    }
+  }
+}

package/src/contentAnalyzers.test.ts

@@ -0,0 +1,59 @@
+import { RequirementFacet } from '@flighthq/types/contract';
+
+import { DEFAULT_CONTENT_ANALYZERS } from './contentAnalyzers';
+
+describe('DEFAULT_CONTENT_ANALYZERS', () => {
+  it('covers the formats Flight analyzes, keyed by lowercase extension', () => {
+    expect(Object.keys(DEFAULT_CONTENT_ANALYZERS).sort()).toEqual(['.awd', '.awd2', '.swf']);
+  });
+
+  it('is frozen, so one project cannot mutate the table another build reads', () => {
+    expect(Object.isFrozen(DEFAULT_CONTENT_ANALYZERS)).toBe(true);
+  });
+
+  it('delegates to the SWF analyzer rather than reimplementing the walk', () => {
+    const set = DEFAULT_CONTENT_ANALYZERS['.swf'](createSwfWithShowFrame());
+    expect(set.covers).toEqual([RequirementFacet.DocumentFormat]);
+    expect(set.requirements).toEqual([{ facet: RequirementFacet.DocumentFormat, key: 'ShowFrame' }]);
+  });
+
+  it('accepts either AWD suffix, resolving both to the same analyzer', () => {
+    const fromAwd = DEFAULT_CONTENT_ANALYZERS['.awd'](createAwd2WithCamera());
+    const fromAwd2 = DEFAULT_CONTENT_ANALYZERS['.awd2'](createAwd2WithCamera());
+    expect(fromAwd2.requirements).toEqual(fromAwd.requirements);
+  });
+
+  it('delegates to the AWD2 analyzer rather than reimplementing the walk', () => {
+    const set = DEFAULT_CONTENT_ANALYZERS['.awd'](createAwd2WithCamera());
+    expect(set.covers).toEqual([RequirementFacet.DocumentFormat]);
+    expect(set.requirements).toEqual([{ facet: RequirementFacet.DocumentFormat, key: 'Camera' }]);
+  });
+
+  it('reports an empty but covered set for content it cannot read', () => {
+    const set = DEFAULT_CONTENT_ANALYZERS['.swf'](new Uint8Array());
+    expect(set.requirements).toEqual([]);
+    expect(set.covers).toEqual([RequirementFacet.DocumentFormat]);
+  });
+});
+
+function createSwfWithShowFrame(): Uint8Array {
+  const body = new Uint8Array([0x00, 0x00, 0x18, 0x01, 0x00, 0x40, 0x00, 0x00, 0x00]);
+  const file = new Uint8Array(8 + body.length);
+  file.set([0x46, 0x57, 0x53, 9], 0);
+  new DataView(file.buffer).setUint32(4, file.length, true);
+  file.set(body, 8);
+  return file;
+}
+
+function createAwd2WithCamera(): Uint8Array {
+  const file = new Uint8Array(12 + 11);
+  file.set([0x41, 0x57, 0x44, 2, 1, 0, 0, 0], 0);
+  const view = new DataView(file.buffer);
+  view.setUint32(8, 11, true);
+  view.setUint32(12, 1, true);
+  file[16] = 0;
+  file[17] = 42;
+  file[18] = 0;
+  view.setUint32(19, 0, true);
+  return file;
+}

package/src/manifestComposition.test.ts

@@ -0,0 +1,33 @@
+import { mergeRenderOptions } from '@flighthq/render/contract';
+import { mergeSwfParseOptions } from '@flighthq/swf/contract';
+import type { RenderStateOptions, SwfParseOptions } from '@flighthq/types/contract';
+
+// A build that imports two documents gets two fragments per backend, and composes them with the merge
+// function the OWNING package exports — not with a generic merge living here. These tests pin that
+// composition end to end: the fragments are the shape the plugin emits, and the result is what an
+// application spreads into createRenderState / parseSwf.
+describe('multi-file composition', () => {
+  it('unions node renderers from two documents instead of letting the last file win', () => {
+    const firstDocument: RenderStateOptions = { nodeRenderers: new Map([['ShowFrame', 'showFrameImpl' as never]]) };
+    const secondDocument: RenderStateOptions = { nodeRenderers: new Map([['DefineShape', 'shapeImpl' as never]]) };
+    const composed = mergeRenderOptions(firstDocument, secondDocument);
+    expect([...composed.nodeRenderers!.keys()]).toEqual(['ShowFrame', 'DefineShape']);
+  });
+
+  it('concatenates parser handlers across documents, preserving import order', () => {
+    const firstDocument: SwfParseOptions = { tags: ['showFrameHandler' as never] };
+    const secondDocument: SwfParseOptions = { tags: ['shapeHandler' as never] };
+    expect(mergeSwfParseOptions(firstDocument, secondDocument).tags).toEqual(['showFrameHandler', 'shapeHandler']);
+  });
+
+  it('keeps a document whose fragment is empty from erasing another document’s contribution', () => {
+    const populated: RenderStateOptions = { nodeRenderers: new Map([['ShowFrame', 'impl' as never]]) };
+    expect([...mergeRenderOptions(populated, {}).nodeRenderers!.keys()]).toEqual(['ShowFrame']);
+    expect([...mergeRenderOptions({}, populated).nodeRenderers!.keys()]).toEqual(['ShowFrame']);
+  });
+
+  it('composes three documents in one call, in argument order', () => {
+    const composed = mergeSwfParseOptions({ tags: ['a' as never] }, { tags: ['b' as never] }, { tags: ['c' as never] });
+    expect(composed.tags).toEqual(['a', 'b', 'c']);
+  });
+});

package/src/manifestModuleSource.test.ts

@@ -0,0 +1,179 @@
+import {
+  generateManifestModuleSource,
+  MANIFEST_BACKEND_EXPORTS,
+  MANIFEST_PARSER_BACKEND,
+} from './manifestModuleSource';
+
+describe('generateManifestModuleSource', () => {
+  it('exports every backend fragment plus parserOptions, even when a backend needs nothing', () => {
+    const source = generateManifestModuleSource([row('gl', 'scene.node-kind', 'Shape')], '.swf').source;
+    for (const name of ['canvasOptions', 'domOptions', 'glOptions', 'wgpuOptions', 'parserOptions']) {
+      expect(source).toContain(`export const ${name} =`);
+    }
+    expect(source).toContain('export const canvasOptions = {};');
+  });
+
+  it('spreads a scene kind into the matching options field as a Map', () => {
+    const source = generateManifestModuleSource([row('gl', 'scene.node-kind', 'Shape')], '.swf').source;
+    expect(source).toContain('export const glOptions = {');
+    expect(source).toContain('nodeRenderers: new Map([');
+    expect(source).toContain("['Shape', glShapeImpl],");
+  });
+
+  it('writes a precise named import for every referenced symbol', () => {
+    const source = generateManifestModuleSource(
+      [row('gl', 'scene.node-kind', 'Shape'), row('wgpu', 'scene.material-kind', 'Standard')],
+      '.swf',
+    ).source;
+    const imports = source.split('\n').filter((line) => line.startsWith('import '));
+    expect(imports).toEqual([
+      "import { glShapeImpl } from '@acme/gl';",
+      "import { wgpuStandardImpl } from '@acme/wgpu';",
+    ]);
+    expect(source).not.toContain('import *');
+  });
+
+  // CanvasRenderOptions and DomRenderOptions declare NO kind-keyed fields on base: canvas takes its
+  // registries as a separate constructor parameter and DOM accepts none. So a row aimed at either is
+  // reported rather than emitted into a field that does not exist. Pending an API ruling, this pins
+  // what the plugin does today instead of pretending the fragment would spread.
+  it.each(['canvas', 'dom', 'gl', 'wgpu'])('emits a nodeRenderers fragment for %s', (backend) => {
+    const result = generateManifestModuleSource([row(backend, 'scene.node-kind', 'Shape')], '.swf');
+    expect(result.source).toContain(`export const ${backend}Options = {\n  nodeRenderers: new Map([`);
+    expect(result.problems).toEqual([]);
+  });
+
+  // The backend sets are NOT interchangeable, and these are the real differences on base.
+  it('reports materialRenderers aimed at dom, which DomRenderOptions does not declare', () => {
+    const result = generateManifestModuleSource([row('dom', 'scene.material-kind', 'Standard')], '.swf');
+    expect(result.source).toContain('export const domOptions = {};');
+    expect(result.problems).toEqual([
+      'backend dom has no materialRenderers field: dropped scene.material-kind Standard',
+    ]);
+  });
+
+  it('reports blendRealizations aimed at canvas, which CanvasRenderStateOptions does not declare', () => {
+    const result = generateManifestModuleSource([row('canvas', 'scene.blend-mode', 'Multiply')], '.swf');
+    expect(result.problems).toEqual([
+      'backend canvas has no blendRealizations field: dropped scene.blend-mode Multiply',
+    ]);
+  });
+
+  it('keeps each backend in its own fragment', () => {
+    const source = generateManifestModuleSource(
+      [row('gl', 'scene.node-kind', 'Shape'), row('wgpu', 'scene.node-kind', 'Shape')],
+      '.swf',
+    ).source;
+    expect(source).toContain("export const glOptions = {\n  nodeRenderers: new Map([\n    ['Shape', glShapeImpl],");
+    expect(source).toContain("export const wgpuOptions = {\n  nodeRenderers: new Map([\n    ['Shape', wgpuShapeImpl],");
+  });
+
+  it('routes parser-backend rows to parserOptions under the format\u2019s own field', () => {
+    expect(
+      generateManifestModuleSource([row(MANIFEST_PARSER_BACKEND, 'document.format', 'DefineShape')], '.swf').source,
+    ).toContain('export const parserOptions = {\n  tags: [');
+    expect(
+      generateManifestModuleSource([row(MANIFEST_PARSER_BACKEND, 'document.format', 'Camera')], '.awd2').source,
+    ).toContain('export const parserOptions = {\n  blocks: [');
+  });
+
+  it('sends the same facet to a render fragment or to the parser by the row\u2019s backend', () => {
+    const source = generateManifestModuleSource(
+      [row(MANIFEST_PARSER_BACKEND, 'document.format', 'DefineShape'), row('gl', 'document.format', 'DefineShape')],
+      '.swf',
+    ).source;
+    expect(source).toContain('export const parserOptions = {\n  tags: [\n    parserDefineShapeImpl,');
+    expect(source).toContain(
+      "export const glOptions = {\n  nodeRenderers: new Map([\n    ['DefineShape', glDefineShapeImpl],",
+    );
+  });
+
+  it('preserves catalog order for handlers, because a handler list is ordered', () => {
+    const source = generateManifestModuleSource(
+      [
+        row(MANIFEST_PARSER_BACKEND, 'document.format', 'Second'),
+        row(MANIFEST_PARSER_BACKEND, 'document.format', 'First'),
+      ],
+      '.swf',
+    ).source;
+    // Measured inside the fragment: the import lines above it are sorted, so a whole-file indexOf
+    // would be testing the import order instead of the handler order.
+    const fragment = source.slice(source.indexOf('export const parserOptions'));
+    expect(fragment.indexOf('parserSecondImpl')).toBeLessThan(fragment.indexOf('parserFirstImpl'));
+  });
+
+  it('sorts map entries by kind so the same rows always emit the same bytes', () => {
+    const a = row('gl', 'scene.node-kind', 'Alpha');
+    const b = row('gl', 'scene.node-kind', 'Beta');
+    expect(generateManifestModuleSource([a, b], '.swf').source).toBe(
+      generateManifestModuleSource([b, a], '.swf').source,
+    );
+  });
+
+  it('REPORTS an unmapped facet rather than skipping it silently', () => {
+    const result = generateManifestModuleSource([row('gl', 'compression.kind', 'Deflate')], '.swf');
+    expect(result.source).toContain('export const glOptions = {};');
+    expect(result.source).not.toContain('glDeflateImpl');
+    expect(result.problems).toEqual([
+      'facet compression.kind has no render-state options field: dropped Deflate for gl',
+    ]);
+  });
+
+  it.each(['compression.kind', 'physics2d.joint-kind', 'scene.resource-mime-type'])(
+    'reports %s, the facets with no render-state field',
+    (facet) => {
+      const result = generateManifestModuleSource([row('gl', facet, 'Thing')], '.swf');
+      expect(result.problems).toHaveLength(1);
+      expect(result.problems[0]).toContain(facet);
+    },
+  );
+
+  it('does not leak a GL-only field into wgpu, and says so', () => {
+    const result = generateManifestModuleSource(
+      [row('gl', 'scene.blend-mode', 'Multiply'), row('wgpu', 'scene.blend-mode', 'Multiply')],
+      '.swf',
+    );
+    expect(result.source).toContain('export const glOptions = {\n  blendRealizations: new Map([');
+    expect(result.source).toContain('export const wgpuOptions = {};');
+    expect(result.problems).toEqual(['backend wgpu has no blendRealizations field: dropped scene.blend-mode Multiply']);
+    expect(result.source).not.toContain('wgpuMultiplyImpl');
+  });
+
+  it('reports a row naming a backend it does not know', () => {
+    const result = generateManifestModuleSource([row('metal', 'scene.node-kind', 'Shape')], '.swf');
+    expect(result.problems).toEqual(['unknown backend metal: dropped scene.node-kind Shape']);
+  });
+
+  it('emits a valid module with no imports when nothing resolved', () => {
+    const source = generateManifestModuleSource([], '.swf').source;
+    expect(source).not.toContain('import ');
+    expect(source).toContain('export const parserOptions = {};');
+  });
+});
+
+describe('MANIFEST_BACKEND_EXPORTS', () => {
+  it('names one flat export per backend', () => {
+    expect(MANIFEST_BACKEND_EXPORTS).toEqual({
+      canvas: 'canvasOptions',
+      dom: 'domOptions',
+      gl: 'glOptions',
+      wgpu: 'wgpuOptions',
+    });
+  });
+});
+
+function row(backend: string, facet: string, kind: string) {
+  const symbol = `${backend}${kind}Impl`;
+  return {
+    entry: {
+      backend,
+      facet: facet as never,
+      implementationImport: `@acme/${backend}`,
+      implementationSymbol: symbol,
+      kind,
+      registrarImport: `@acme/${backend}`,
+      registrarSymbol: `register${kind}`,
+    },
+    kind,
+  };
+}

package/src/manifestPlugin.test.ts

@@ -0,0 +1,166 @@
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { createRequirementSet } from '@flighthq/requirement/contract';
+import { RequirementFacet } from '@flighthq/types/contract';
+
+import { MANIFEST_PARSER_BACKEND } from './manifestModuleSource';
+import { createManifestPlugin, MANIFEST_QUERY_SUFFIX } from './manifestPlugin';
+
+describe('createManifestPlugin', () => {
+  it('claims only ?manifest imports, resolving them against the importer directory', async () => {
+    const plugin = createManifestPlugin({ catalog: { entries: [] } });
+    expect(plugin.resolveId('./asset.swf')).toBeNull();
+    expect(plugin.resolveId('./styles.css')).toBeNull();
+    const resolved = plugin.resolveId(`./asset.swf${MANIFEST_QUERY_SUFFIX}`, '/project/src/main.ts')!;
+    expect(resolved.startsWith('\0flight-manifest:')).toBe(true);
+    expect(resolved.endsWith('/project/src/asset.swf')).toBe(true);
+  });
+
+  it('loads nothing for an id it did not resolve', async () => {
+    const plugin = createManifestPlugin({ catalog: { entries: [] } });
+    expect(await plugin.load('/project/src/main.ts')).toBeNull();
+  });
+
+  it('serves fragments for the one file imported, resolved across every backend', async () => {
+    const { dir, plugin } = await fixture();
+    const source = (await load(plugin, dir, 'a.swf'))!;
+    expect(source).toContain("import { glShowFrame } from '@acme/gl';");
+    expect(source).toContain("import { wgpuShowFrame } from '@acme/wgpu';");
+    expect(source).toContain("export const glOptions = {\n  nodeRenderers: new Map([\n    ['ShowFrame', glShowFrame],");
+    expect(source).toContain(
+      "export const wgpuOptions = {\n  nodeRenderers: new Map([\n    ['ShowFrame', wgpuShowFrame],",
+    );
+    // canvas and dom carry no kind-keyed options fields on base, so their fragments are empty and
+    // still exported — an application can spread every fragment unconditionally.
+    expect(source).toContain('export const canvasOptions = {};');
+    expect(source).toContain('export const domOptions = {};');
+  });
+
+  it('reads the exact file imported, so two documents give different modules', async () => {
+    const { dir, plugin } = await fixture();
+    await writeFile(join(dir, 'b.swf'), Buffer.from(createSwf(TAG_SET_BACKGROUND_COLOR)));
+    const a = await load(plugin, dir, 'a.swf');
+    const b = await load(plugin, dir, 'b.swf');
+    expect(a).not.toBe(b);
+    expect(a).toContain("['ShowFrame', wgpuShowFrame]");
+    expect(b).toContain('export const wgpuOptions = {};');
+  });
+
+  it('invalidates per imported source, leaving other files cached', async () => {
+    const { dir, plugin } = await fixture();
+    await writeFile(join(dir, 'b.swf'), Buffer.from(createSwf(TAG_SHOW_FRAME)));
+    const beforeA = await load(plugin, dir, 'a.swf');
+    const beforeB = await load(plugin, dir, 'b.swf');
+
+    // Rewrite a.swf to content with no ShowFrame, then invalidate ONLY a.swf.
+    await writeFile(join(dir, 'a.swf'), Buffer.from(createSwf(TAG_SET_BACKGROUND_COLOR)));
+    await writeFile(join(dir, 'b.swf'), Buffer.from(createSwf(TAG_SET_BACKGROUND_COLOR)));
+    plugin.handleHotUpdate({ file: join(dir, 'a.swf') });
+
+    expect(await load(plugin, dir, 'a.swf')).not.toBe(beforeA);
+    // b.swf changed on disk too, but nothing invalidated it, so its cached module must stand.
+    expect(await load(plugin, dir, 'b.swf')).toBe(beforeB);
+  });
+
+  it('reports an unsupported format and still serves a spreadable empty module', async () => {
+    const { dir, diagnostics, plugin } = await fixture();
+    await writeFile(join(dir, 'notes.txt'), 'not content');
+    const source = (await load(plugin, dir, 'notes.txt'))!;
+    expect(diagnostics.some((m) => m.includes('unsupported content format'))).toBe(true);
+    expect(source).toContain('export const canvasOptions = {};');
+    expect(source).toContain('export const parserOptions = {};');
+  });
+
+  it('reports an unreadable file rather than failing the build', async () => {
+    const { dir, diagnostics, plugin } = await fixture();
+    expect(await load(plugin, dir, 'missing.swf')).toContain('export const glOptions = {};');
+    expect(diagnostics.some((m) => m.includes('analyzer failed'))).toBe(true);
+  });
+
+  it('reports a requirement no catalog entry satisfies', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'flight-vite-'));
+    await writeFile(join(dir, 'a.swf'), Buffer.from(createSwf(TAG_SHOW_FRAME)));
+    const diagnostics: string[] = [];
+    const plugin = createManifestPlugin({
+      catalog: { entries: [] },
+      onDiagnostic: (message) => diagnostics.push(message),
+    });
+    await load(plugin, dir, 'a.swf');
+    expect(diagnostics.some((m) => m.includes('no catalog entry for document.format ShowFrame'))).toBe(true);
+  });
+
+  it('drives resolution through an EXTERNAL catalog, since the built-in catalog ships empty', async () => {
+    const { dir, plugin } = await fixture();
+    // BUILT_IN_REQUIREMENT_CATALOG_ENTRIES is deliberately empty on base, so every row that reaches a
+    // fragment came from the catalog the caller passed in. This pins that the external path is the
+    // real one rather than incidental.
+    expect(await load(plugin, dir, 'a.swf')).toContain("['ShowFrame', glShowFrame]");
+
+    const empty = createManifestPlugin({ catalog: { entries: [] }, onDiagnostic: () => {} });
+    const source = (await load(empty, dir, 'a.swf'))!;
+    expect(source).toContain('export const glOptions = {};');
+    expect(source).not.toContain('glShowFrame');
+  });
+
+  it('reports every requirement no backend in the external catalog can satisfy', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'flight-vite-'));
+    await writeFile(join(dir, 'a.swf'), Buffer.from(createSwf(TAG_SHOW_FRAME)));
+    const diagnostics: string[] = [];
+    const plugin = createManifestPlugin({
+      catalog: { entries: [] },
+      onDiagnostic: (message) => diagnostics.push(message),
+    });
+    await load(plugin, dir, 'a.swf');
+    expect(diagnostics.some((m) => m.includes('no catalog entry for document.format ShowFrame'))).toBe(true);
+  });
+});
+
+const TAG_SHOW_FRAME = 1;
+const TAG_SET_BACKGROUND_COLOR = 9;
+
+function entry(backend: string, facet: string, kind: string, symbol: string) {
+  return {
+    backend,
+    facet: facet as never,
+    implementationImport: `@acme/${backend}`,
+    implementationSymbol: symbol,
+    kind,
+    registrarImport: `@acme/${backend}`,
+    registrarSymbol: `register${kind}`,
+  };
+}
+
+async function fixture() {
+  const dir = await mkdtemp(join(tmpdir(), 'flight-vite-'));
+  await writeFile(join(dir, 'a.swf'), Buffer.from(createSwf(TAG_SHOW_FRAME)));
+  const diagnostics: string[] = [];
+  const plugin = createManifestPlugin({
+    catalog: {
+      entries: [
+        entry('wgpu', RequirementFacet.DocumentFormat, 'ShowFrame', 'wgpuShowFrame'),
+        entry('gl', RequirementFacet.DocumentFormat, 'ShowFrame', 'glShowFrame'),
+        entry(MANIFEST_PARSER_BACKEND, RequirementFacet.DocumentFormat, 'ShowFrame', 'parserShowFrame'),
+      ],
+    },
+    onDiagnostic: (message) => diagnostics.push(message),
+  });
+  return { diagnostics, dir, plugin };
+}
+
+async function load(plugin: ReturnType<typeof createManifestPlugin>, dir: string, name: string) {
+  const id = plugin.resolveId(`./${name}${MANIFEST_QUERY_SUFFIX}`, join(dir, 'main.ts'))!;
+  return plugin.load(id);
+}
+
+// A minimal SWF carrying exactly one tag of the given code, built inline so the tests need no fixture.
+function createSwf(code: number): Uint8Array {
+  const tagHeader = code << 6;
+  const body = new Uint8Array([0x00, 0x00, 0x18, 0x01, 0x00, tagHeader & 0xff, (tagHeader >> 8) & 0xff, 0x00, 0x00]);
+  const file = new Uint8Array(8 + body.length);
+  file.set([0x46, 0x57, 0x53, 9], 0);
+  new DataView(file.buffer).setUint32(4, file.length, true);
+  file.set(body, 8);
+  return file;
+}

package/src/manifestTreeShaking.test.ts

@@ -0,0 +1,172 @@
+import { mkdir, mkdtemp, readFile, readdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { RequirementFacet } from '@flighthq/types/contract';
+import { build } from 'vite';
+
+import { MANIFEST_PARSER_BACKEND } from './manifestModuleSource';
+import { createManifestPlugin, MANIFEST_QUERY_SUFFIX } from './manifestPlugin';
+
+// Tree shaking is a property of a BUNDLER, not of the emitted string. Reading the generated source
+// only shows what was offered; these tests run a real Vite production build and read what survived.
+const BUILD_TIMEOUT_MS = 60_000;
+
+describe('vite build', () => {
+  it(
+    'keeps only the backend fragment the entry imported, dropping the other implementations',
+    async () => {
+      const dir = await project();
+      await writeFile(
+        join(dir, 'src', 'main.js'),
+        `import { glOptions } from './asset.swf${MANIFEST_QUERY_SUFFIX}';\nglobalThis.out = glOptions;\n`,
+      );
+      const bundle = await bundleOf(dir);
+
+      expect(bundle).toContain('GL_IMPLEMENTATION_MARKER');
+      expect(bundle).not.toContain('CANVAS_IMPLEMENTATION_MARKER');
+      expect(bundle).not.toContain('WGPU_IMPLEMENTATION_MARKER');
+      expect(bundle).not.toContain('PARSER_IMPLEMENTATION_MARKER');
+    },
+    BUILD_TIMEOUT_MS,
+  );
+
+  it(
+    'keeps only the parser fragment when that is what the entry imported',
+    async () => {
+      const dir = await project();
+      await writeFile(
+        join(dir, 'src', 'main.js'),
+        `import { parserOptions } from './asset.swf${MANIFEST_QUERY_SUFFIX}';\nglobalThis.out = parserOptions;\n`,
+      );
+      const bundle = await bundleOf(dir);
+
+      expect(bundle).toContain('PARSER_IMPLEMENTATION_MARKER');
+      expect(bundle).not.toContain('GL_IMPLEMENTATION_MARKER');
+      expect(bundle).not.toContain('CANVAS_IMPLEMENTATION_MARKER');
+    },
+    BUILD_TIMEOUT_MS,
+  );
+
+  it(
+    'keeps every implementation an entry actually imports, across two backends',
+    async () => {
+      const dir = await project();
+      await writeFile(
+        join(dir, 'src', 'main.js'),
+        `import { glOptions, wgpuOptions } from './asset.swf${MANIFEST_QUERY_SUFFIX}';\n` +
+          'globalThis.out = [glOptions, wgpuOptions];\n',
+      );
+      const bundle = await bundleOf(dir);
+
+      expect(bundle).toContain('GL_IMPLEMENTATION_MARKER');
+      expect(bundle).toContain('WGPU_IMPLEMENTATION_MARKER');
+      expect(bundle).not.toContain('PARSER_IMPLEMENTATION_MARKER');
+    },
+    BUILD_TIMEOUT_MS,
+  );
+
+  it(
+    'produces a spreadable fragment carrying the kind the content required',
+    async () => {
+      const dir = await project();
+      await writeFile(
+        join(dir, 'src', 'main.js'),
+        `import { glOptions } from './asset.swf${MANIFEST_QUERY_SUFFIX}';\nglobalThis.out = glOptions;\n`,
+      );
+      const bundle = await bundleOf(dir);
+      // The fragment reaches the bundle as a real Map literal keyed by the requirement's kind, which is
+      // what lets an application spread it straight into createGlRenderState.
+      expect(bundle).toContain('ShowFrame');
+      expect(bundle).toContain('nodeRenderers');
+    },
+    BUILD_TIMEOUT_MS,
+  );
+
+  it(
+    'retains BOTH canvas and gl when the entry imports both fragments',
+    async () => {
+      const dir = await project();
+      await writeFile(
+        join(dir, 'src', 'main.js'),
+        `import { canvasOptions, glOptions } from './asset.swf${MANIFEST_QUERY_SUFFIX}';\n` +
+          'globalThis.out = [canvasOptions, glOptions];\n',
+      );
+      const bundle = await bundleOf(dir);
+
+      // A canvas fragment is a Partial<CanvasRenderStateOptions> spread straight into
+      // createCanvasRenderState(options), so canvas carries real implementations and both survive.
+      // wgpu and the parser do not, which is what makes this a retention test rather than a tautology.
+      expect(bundle).toContain('CANVAS_IMPLEMENTATION_MARKER');
+      expect(bundle).toContain('GL_IMPLEMENTATION_MARKER');
+      expect(bundle).not.toContain('WGPU_IMPLEMENTATION_MARKER');
+      expect(bundle).not.toContain('PARSER_IMPLEMENTATION_MARKER');
+    },
+    BUILD_TIMEOUT_MS,
+  );
+});
+
+async function bundleOf(dir: string): Promise<string> {
+  await build({
+    build: {
+      minify: false,
+      outDir: join(dir, 'dist'),
+      rollupOptions: { input: join(dir, 'src', 'main.js') },
+      write: true,
+    },
+    configFile: false,
+    logLevel: 'silent',
+    plugins: [createManifestPlugin({ catalog: { entries: catalogEntries(dir) }, onDiagnostic: () => {} })],
+    root: dir,
+  });
+  const outDir = join(dir, 'dist');
+  const files = (await readdir(outDir, { recursive: true, withFileTypes: true }))
+    .filter((e) => e.isFile() && e.name.endsWith('.js'))
+    .map((e) => join(e.parentPath ?? outDir, e.name));
+  const contents = await Promise.all(files.map((file) => readFile(file, 'utf8')));
+  return contents.join('\n');
+}
+
+function catalogEntries(dir: string) {
+  const impl = (backend: string) => join(dir, 'src', `${backend}Impl.js`);
+  return [
+    entry('canvas', RequirementFacet.DocumentFormat, 'ShowFrame', 'canvasShowFrame', impl('canvas')),
+    entry('gl', RequirementFacet.DocumentFormat, 'ShowFrame', 'glShowFrame', impl('gl')),
+    entry('wgpu', RequirementFacet.DocumentFormat, 'ShowFrame', 'wgpuShowFrame', impl('wgpu')),
+    entry(MANIFEST_PARSER_BACKEND, RequirementFacet.DocumentFormat, 'ShowFrame', 'parserShowFrame', impl('parser')),
+  ];
+}
+
+function entry(backend: string, facet: string, kind: string, symbol: string, module: string) {
+  return {
+    backend,
+    facet: facet as never,
+    implementationImport: module,
+    implementationSymbol: symbol,
+    kind,
+    registrarImport: module,
+    registrarSymbol: `register${kind}`,
+  };
+}
+
+async function project(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'flight-vite-build-'));
+  await mkdir(join(dir, 'src'), { recursive: true });
+  await writeFile(join(dir, 'src', 'asset.swf'), Buffer.from(createSwfWithShowFrame()));
+  for (const backend of ['canvas', 'gl', 'wgpu', 'parser']) {
+    await writeFile(
+      join(dir, 'src', `${backend}Impl.js`),
+      `export const ${backend}ShowFrame = '${backend.toUpperCase()}_IMPLEMENTATION_MARKER';\n`,
+    );
+  }
+  return dir;
+}
+
+function createSwfWithShowFrame(): Uint8Array {
+  const body = new Uint8Array([0x00, 0x00, 0x18, 0x01, 0x00, 0x40, 0x00, 0x00, 0x00]);
+  const file = new Uint8Array(8 + body.length);
+  file.set([0x46, 0x57, 0x53, 9], 0);
+  new DataView(file.buffer).setUint32(4, file.length, true);
+  file.set(body, 8);
+  return file;
+}