@forgeax/engine-import 0.1.3 → 0.1.6

package/dist/source-package.d.ts

@@ -0,0 +1,60 @@
+import type { ImportedAsset, ImportProduct, ImportProductFinalizeOptions, ImportProductFinalizeResult, Result } from '@forgeax/engine-types';
+import type { ImportRunnerFs, RunImportMeta } from './import-runner.js';
+import type { ImporterRegistry } from './importer-registry.js';
+export type ProducerReadiness = 'before-consume' | 'on-demand';
+export interface ProducerReadinessError {
+    readonly code: 'producer-readiness-invalid';
+    readonly expected: "'before-consume' or 'on-demand'";
+    readonly hint: 'set producerReadiness to before-consume or on-demand';
+    readonly detail: {
+        readonly value: unknown;
+    };
+}
+export type ProducerReadinessResult = {
+    readonly ok: true;
+    readonly value: ProducerReadiness;
+} | {
+    readonly ok: false;
+    readonly error: ProducerReadinessError;
+};
+export declare function parseProducerReadiness(value: unknown): ProducerReadinessResult;
+export interface SourcePackageProducerInput {
+    readonly meta: RunImportMeta;
+    readonly registry: ImporterRegistry;
+    readonly fs: ImportRunnerFs;
+}
+export interface SourcePackageClosureDetail {
+    readonly stage: 'closure';
+    readonly declaredGuids: readonly string[];
+    readonly producedGuids: readonly string[];
+    readonly missingGuids: readonly string[];
+    readonly unexpectedGuids: readonly string[];
+    readonly duplicateGuids: readonly string[];
+}
+export interface SourcePackageClosureError {
+    readonly code: 'source-package-guid-closure-mismatch';
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: SourcePackageClosureDetail;
+}
+export interface SourcePackageProduct {
+    readonly anchorGuid: string;
+    readonly declaredGuids: readonly string[];
+    readonly product: ImportProduct<unknown>;
+}
+type SourcePackageFinalizeError = Extract<ImportProductFinalizeResult, {
+    readonly ok: false;
+}>['error'];
+/** Apply an importer-owned transport finalizer without teaching the adapter its kind. */
+export declare function finalizeSourcePackage(product: ImportProduct<unknown>, finalizer: ((product: ImportProduct<unknown>, options: ImportProductFinalizeOptions) => ImportProductFinalizeResult) | undefined, artifactUrl: ImportProductFinalizeOptions['artifactUrl']): Result<ImportProduct<unknown>, SourcePackageFinalizeError>;
+export type SourcePackageProducerResult = {
+    readonly ok: true;
+    readonly value: SourcePackageProduct;
+} | {
+    readonly ok: false;
+    readonly error: SourcePackageClosureError;
+};
+export declare function produceSourcePackage(input: SourcePackageProducerInput): Promise<SourcePackageProducerResult>;
+export declare function sourcePackageAssetsByGuid(source: SourcePackageProduct): ReadonlyMap<string, ImportedAsset<unknown>>;
+export {};
+//# sourceMappingURL=source-package.d.ts.map

package/dist/source-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-package.d.ts","sourceRoot":"","sources":["../src/source-package.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,aAAa,EACb,aAAa,EACb,4BAA4B,EAC5B,2BAA2B,EAC3B,MAAM,EACP,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG,WAAW,CAAC;AAE/D,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,iCAAiC,CAAC;IACrD,QAAQ,CAAC,IAAI,EAAE,sDAAsD,CAAC;IACtE,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;CAC9C;AAED,MAAM,MAAM,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAA;CAAE,CAAC;AAEnE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAa9E;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;CAC7B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,sCAAsC,CAAC;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;CAC7C;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED,KAAK,0BAA0B,GAAG,OAAO,CACvC,2BAA2B,EAC3B;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;CAAE,CACvB,CAAC,OAAO,CAAC,CAAC;AAEX,yFAAyF;AACzF,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,EAC/B,SAAS,EACL,CAAC,CACC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,EAC/B,OAAO,EAAE,4BAA4B,KAClC,2BAA2B,CAAC,GACjC,SAAS,EACb,WAAW,EAAE,4BAA4B,CAAC,aAAa,CAAC,GACvD,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,0BAA0B,CAAC,CAU5D;AAED,MAAM,MAAM,2BAA2B,GACnC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,yBAAyB,CAAA;CAAE,CAAC;AA0CtE,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,2BAA2B,CAAC,CAsCtC;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,oBAAoB,GAC3B,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAE7C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-import",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -9,9 +9,14 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "browser": "./dist/browser.mjs",
       "import": "./dist/index.mjs"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./mesh-bin": {
+      "types": "./dist/mesh-bin.d.ts",
+      "import": "./dist/mesh-bin.mjs"
+    }
   },
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -22,11 +27,12 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-ecs": "0.1.3",
-    "@forgeax/engine-geometry": "0.1.3",
-    "@forgeax/engine-pack": "0.1.3",
-    "@forgeax/engine-scene": "0.1.3",
-    "@forgeax/engine-types": "0.1.3",
+    "@forgeax/engine-ddc": "0.1.6",
+    "@forgeax/engine-ecs": "0.1.6",
+    "@forgeax/engine-geometry": "0.1.6",
+    "@forgeax/engine-pack": "0.1.6",
+    "@forgeax/engine-scene": "0.1.6",
+    "@forgeax/engine-types": "0.1.6",
     "@noble/hashes": "^2.2.0"
   },
   "devDependencies": {

package/src/__tests__/import-contract-migration.test.ts

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import type { Asset, AssetRelation, ImportedAsset, ImportResult } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import { createImportProduct } from '../import-product.js';
 import { type RunImportMeta, runImport } from '../import-runner.js';
 import { ImporterRegistry } from '../importer-registry.js';
 
@@ -188,3 +189,35 @@ describe('import runner producer fact propagation', () => {
     expect(source).not.toContain("a.kind === 'mesh'");
   });
 });
+
+describe('engine-import terminal product contract', () => {
+  it('projects refs, artifacts, receipts, diagnostics, and source identity together', () => {
+    const result = createImportProduct({
+      assets: [
+        {
+          guid: '019e3969-1d48-7c3b-ac24-6d68f457065f',
+          kind: 'texture',
+          payload: { kind: 'texture', width: 1, height: 1 },
+          refs: [],
+          artifacts: {},
+        },
+      ],
+      sourceDependencies: ['hero.png'],
+      refs: [],
+      artifacts: {},
+      receipts: [],
+      diagnostics: [],
+      sourceRevision: 'sha256:hero',
+      sourceKey: 'hero/albedo',
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.sourceRevision).toBe('sha256:hero');
+    expect(result.value.sourceKey).toBe('hero/albedo');
+    expect(result.value).toHaveProperty('refs');
+    expect(result.value).toHaveProperty('artifacts');
+    expect(result.value).toHaveProperty('receipts');
+    expect(result.value).toHaveProperty('diagnostics');
+  });
+});

package/src/__tests__/import-local-artifacts.test.ts

@@ -66,7 +66,9 @@ describe('asset-local ImportProduct contract', () => {
     expect(result.ok).toBe(true);
     if (result.ok && 'product' in result.value) {
       expect(result.value).not.toHaveProperty('bins');
-      expect(result.value.product).not.toHaveProperty('artifacts');
+      expect(result.value.product.artifacts).toHaveProperty(`${MESH_GUID}/body`);
+      expect(result.value.product.receipts).toHaveLength(2);
+      expect(result.value.product.sourceRevision).toBe('source:fixture.source');
       expect(result.value.pack.assets[0]?.artifacts).toHaveProperty('body');
       expect(result.value.pack.assets[1]?.artifacts).toHaveProperty('body');
     }

package/src/__tests__/owner-chain.integration.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import { createImportProduct } from '../import-product.js';
+
+describe('Import owner chain', () => {
+  it('hands one complete terminal product to the next owner', () => {
+    const result = createImportProduct({
+      assets: [
+        {
+          guid: '019e3969-1d48-7c3b-ac24-6d68f457065f',
+          kind: 'texture',
+          payload: { kind: 'texture' },
+          refs: [],
+          artifacts: {},
+        },
+      ],
+      sourceDependencies: ['hero.png'],
+      refs: [],
+      artifacts: {},
+      receipts: [],
+      diagnostics: [],
+      sourceRevision: 'sha256:hero',
+      sourceKey: 'hero/albedo',
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toMatchObject({
+        sourceRevision: 'sha256:hero',
+        sourceKey: 'hero/albedo',
+        refs: [],
+        artifacts: {},
+        receipts: [],
+        diagnostics: [],
+      });
+    }
+  });
+});

package/src/__tests__/scriptable-pack-host.unit.test.ts

@@ -0,0 +1,86 @@
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { ScanSourceDeclaration } from '@forgeax/engine-pack/scanner';
+import type {
+  Asset,
+  AssetGuid as AssetGuidType,
+  ImportContext,
+  Importer,
+} from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { ImporterRegistry } from '../importer-registry.js';
+import { declaredPackExternalOutputs } from '../scriptable-pack-host.js';
+
+const GUID = '019ffa97-0000-7000-8000-000000000001';
+
+function parseGuid(value: string): AssetGuidType {
+  const parsed = AssetGuid.parse(value);
+  if (!parsed.ok) throw parsed.error;
+  return parsed.value;
+}
+
+describe('ScriptablePack external Meta staging', () => {
+  it('imports ordinary Meta dependencies into the current staged generation', async () => {
+    const importer: Importer = {
+      key: 'fixture',
+      import: async (ctx: ImportContext) => ({
+        ok: true,
+        value: {
+          assets: [
+            {
+              guid: ctx.subAssets[0]?.guid ?? GUID,
+              kind: 'mesh',
+              payload: {
+                kind: 'mesh',
+                vertices: new Float32Array([0, 1, 2]),
+                attributes: {},
+                submeshes: [],
+                materialSlots: [],
+              } satisfies Asset,
+              refs: [],
+              artifacts: {},
+            },
+          ],
+          sourceDependencies: [],
+        },
+      }),
+    };
+    const registry = new ImporterRegistry();
+    registry.register(importer);
+    const declaration = {
+      format: 'meta.json',
+      sourcePath: '/project/assets/model.bin.meta.json',
+      sourceRevision: 'sha256:meta',
+      value: {
+        schemaVersion: '1.0.0',
+        kind: 'external-asset-package',
+        importer: 'fixture',
+        source: 'model.bin',
+        importSettings: {},
+        subAssets: [{ guid: GUID, sourceIndex: 0, kind: 'mesh' }],
+      },
+    } satisfies Extract<ScanSourceDeclaration, { readonly format: 'meta.json' }>;
+
+    const outputs = await declaredPackExternalOutputs(
+      new Map([[declaration.sourcePath, declaration]]),
+      [],
+      [parseGuid(GUID)],
+      {
+        importerRegistry: registry,
+        fsForImport: {
+          readSource: async () => ({ ok: true as const, value: new Uint8Array([1, 2, 3]) }),
+        },
+        assetPaths: {},
+      },
+    );
+
+    expect(outputs).toHaveLength(1);
+    const output = outputs[0];
+    expect(output).toBeDefined();
+    if (output === undefined) return;
+    expect(AssetGuid.format(output.guid)).toBe(GUID);
+    expect(output.asset).toMatchObject({ kind: 'mesh' });
+    expect(Array.from((output.asset as Asset & { vertices: Float32Array }).vertices)).toEqual([
+      0, 1, 2,
+    ]);
+  });
+});

package/src/__tests__/scriptable-pack-product.contract.test.ts

@@ -0,0 +1,47 @@
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { buildScriptablePack } from '../scriptable-pack.js';
+import { createStandardAssetOutputProducerRegistry } from '../scriptable-pack-output-producers.js';
+
+const PACKAGE_ID = AssetGuid.parse('019e3969-1d48-7c3b-ac24-6d68f457065e');
+const HERO_GUID = AssetGuid.parse('019e3969-1d48-7c3b-ac24-6d68f457065f');
+
+describe('ScriptablePack terminal product contract', () => {
+  it('keeps one complete product shape for direct and custom producer outputs', async () => {
+    const result = await buildScriptablePack({
+      definition: {
+        schemaVersion: '1.0.0',
+        packageId: PACKAGE_ID.ok ? PACKAGE_ID.value : ({} as never),
+        assets: {
+          hero: { guid: HERO_GUID.ok ? HERO_GUID.value : ({} as never), kind: 'texture' },
+        },
+        externalAssets: {},
+        build: async () =>
+          ok({
+            hero: {
+              kind: 'texture',
+              width: 1,
+              height: 1,
+              format: 'rgba8unorm',
+              data: new Uint8Array(),
+              colorSpace: 'srgb',
+              mipmap: false,
+            },
+          }),
+      },
+      sourcePath: 'hero.pack.ts',
+      outputs: createStandardAssetOutputProducerRegistry(),
+      sourceClosure: [{ path: 'hero.pack.ts', digest: 'sha256:hero' }],
+      authoringContractVersion: 'scriptable-pack-production/1',
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.product).toHaveProperty('refs');
+    expect(result.value.product).toHaveProperty('artifacts');
+    expect(result.value.product).toHaveProperty('receipts');
+    expect(result.value.product).toHaveProperty('diagnostics');
+    expect(result.value.product).toHaveProperty('sourceRevision');
+  });
+});

package/src/__tests__/scriptable-pack-production-producers.unit.test.ts

@@ -1,5 +1,5 @@
-import { defineComponent } from '@forgeax/engine-ecs';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { ScriptablePackSceneComponent } from '@forgeax/engine-pack/source';
 import type {
   AnimationClip,
   AnimationGraph,
@@ -31,19 +31,17 @@ function guid(value: string): AssetGuidType {
 
 const MATERIAL_GUID = guid('019ffa97-3000-7000-8000-000000000001');
 const MESH_GUID = guid('019ffa97-3000-7000-8000-000000000002');
-const ScriptableMeshFilter = defineComponent('ScriptablePackTestMeshFilter', {
-  assetHandle: 'shared<MeshAsset>',
-});
-const ScriptableMeshRenderer = defineComponent('ScriptablePackTestMeshRenderer', {
-  materials: 'array<shared<MaterialAsset>>',
-});
-const componentCatalog = new Map<
-  string,
-  typeof ScriptableMeshFilter | typeof ScriptableMeshRenderer
->([
-  [ScriptableMeshFilter.name, ScriptableMeshFilter],
-  [ScriptableMeshRenderer.name, ScriptableMeshRenderer],
-]);
+const EQUIRECT_GUID = guid('019ffa97-3000-7000-8000-000000000005');
+const sceneComponents = [
+  {
+    name: 'ScriptablePackTestMeshFilter',
+    fields: { assetHandle: 'shared<MeshAsset>' },
+  },
+  {
+    name: 'ScriptablePackTestMeshRenderer',
+    fields: { materials: 'array<shared<MaterialAsset>>' },
+  },
+] satisfies readonly ScriptablePackSceneComponent[];
 
 const OUTPUT_GUID = guid('019ffa97-3000-7000-8000-000000000010');
 const ATLAS_GUID = guid('019ffa97-3000-7000-8000-000000000011');
@@ -165,8 +163,6 @@ const matrixAssets = [
 ] as const satisfies readonly Asset[];
 
 describe('standard ScriptablePack output producers', () => {
-  void ScriptableMeshFilter;
-  void ScriptableMeshRenderer;
   it('registers the production producer versions for all ordinary Asset kinds', () => {
     const registry = createStandardAssetOutputProducerRegistry();
     expect(registry.versions()).toEqual({
@@ -180,7 +176,7 @@ describe('standard ScriptablePack output producers', () => {
       'particle-effect': 'ordinary-pod/1',
       'render-pipeline': 'ordinary-pod/1',
       sampler: 'ordinary-pod/1',
-      scene: 'scene-pack/2',
+      scene: 'scene-pack/3',
       skeleton: 'ordinary-pod/1',
       skin: 'ordinary-pod/1',
       texture: 'ordinary-pod/1',
@@ -262,7 +258,7 @@ describe('standard ScriptablePack output producers', () => {
   });
 
   it('serializes a scene through component schemas and emits recursive GUID refs', async () => {
-    const registry = createStandardAssetOutputProducerRegistry();
+    const registry = createStandardAssetOutputProducerRegistry(sceneComponents);
     const producer = registry.get('scene');
     expect(producer).toBeDefined();
     if (producer === undefined) return;
@@ -285,7 +281,6 @@ describe('standard ScriptablePack output producers', () => {
       guid: '019ffa97-3000-7000-8000-000000000003',
       sourceKey: 'scene/showcase',
       asset: scene,
-      components: componentCatalog,
     });
 
     expect(result.ok).toBe(true);
@@ -322,6 +317,70 @@ describe('standard ScriptablePack output producers', () => {
     ]);
   });
 
+  it('fails closed when a scene component schema is not declared by the Pack', async () => {
+    const registry = createStandardAssetOutputProducerRegistry();
+    const producer = registry.get('scene');
+    expect(producer).toBeDefined();
+    if (producer === undefined) return;
+
+    const result = await producer.produce({
+      guid: '019ffa97-3000-7000-8000-000000000004',
+      sourceKey: 'scene/unknown-component',
+      asset: {
+        kind: 'scene',
+        entities: [{ localId: 0 as never, components: { Mystery: { asset: 'not-a-ref' } } }],
+      },
+    });
+
+    expect(result).toMatchObject({
+      ok: false,
+      error: {
+        code: 'import-internal-error',
+        detail: { reason: expect.stringContaining('missing from sceneComponents') },
+      },
+    });
+  });
+
+  it('deduplicates one shared scene GUID across multiple component fields', async () => {
+    const registry = createStandardAssetOutputProducerRegistry([
+      ...sceneComponents,
+      { name: 'Skylight', fields: { equirect: 'shared<EquirectAsset>' } },
+      { name: 'SkyboxBackground', fields: { equirect: 'shared<EquirectAsset>' } },
+    ]);
+    const producer = registry.get('scene');
+    expect(producer).toBeDefined();
+    if (producer === undefined) return;
+
+    const result = await producer.produce({
+      guid: '019ffa97-3000-7000-8000-000000000006',
+      sourceKey: 'scene/environment',
+      asset: {
+        kind: 'scene',
+        entities: [
+          {
+            localId: 0 as never,
+            components: { Skylight: { equirect: AssetGuid.format(EQUIRECT_GUID) } },
+          },
+          {
+            localId: 1 as never,
+            components: { SkyboxBackground: { equirect: AssetGuid.format(EQUIRECT_GUID) } },
+          },
+        ],
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.refs).toHaveLength(1);
+    expect(result.value.refs[0]?.guid).toBe(AssetGuid.format(EQUIRECT_GUID));
+    expect(result.value.payload).toMatchObject({
+      entities: [
+        { components: { Skylight: { equirect: 0 } } },
+        { components: { SkyboxBackground: { equirect: 0 } } },
+      ],
+    });
+  });
+
   it('packs mesh bytes and projects material parent references', async () => {
     const registry = createStandardAssetOutputProducerRegistry();
     const mesh = registry.get('mesh');

package/src/__tests__/scriptable-pack-staged-snapshot.unit.test.ts

@@ -74,8 +74,7 @@ describe('ScriptablePack staged asset snapshot source', () => {
     expect(second.ok && second.value.digest).toMatch(/^sha256:/);
   });
 
-  it('fails a content dependency cycle structurally without consulting fallback', async () => {
-    let fallbackReads = 0;
+  it('fails a content dependency cycle structurally', async () => {
     const owners: ScriptablePackStagedOwner[] = [
       {
         id: 'a.pack.ts',
@@ -97,12 +96,6 @@ describe('ScriptablePack staged asset snapshot source', () => {
     const source = createScriptablePackStagedAssetSnapshotSource({
       generation: 1,
       owners,
-      fallback: {
-        async readByGuid() {
-          fallbackReads += 1;
-          return ok({ asset: mesh(8), generation: 0, digest: 'lkg' });
-        },
-      },
     });
     const result = await source.readByGuid(ROOT);
     expect(result).toMatchObject({
@@ -112,14 +105,63 @@ describe('ScriptablePack staged asset snapshot source', () => {
         actual: 'a.pack.ts -> b.pack.ts -> a.pack.ts',
       },
     });
-    expect(fallbackReads).toBe(0);
+  });
+
+  it('fails a content dependency without a local owner', async () => {
+    const source = createScriptablePackStagedAssetSnapshotSource({
+      generation: 1,
+      owners: [
+        {
+          id: 'root.pack.ts',
+          guids: [ROOT],
+          async build(ownerSource) {
+            const result = await ownerSource.readByGuid(DEPENDENCY);
+            return result.ok ? ok([{ guid: ROOT, asset: result.value.asset }]) : result;
+          },
+        },
+      ],
+    });
+
+    await expect(source.readByGuid(ROOT)).resolves.toMatchObject({
+      ok: false,
+      error: {
+        code: 'asset-not-imported',
+        expected: 'a staged local owner for the requested GUID',
+      },
+    });
+  });
+
+  it('resolves declared direct Pack outputs in the same generation', async () => {
+    const source = createScriptablePackStagedAssetSnapshotSource({
+      generation: 3,
+      declaredExternalOutputs: [{ guid: DEPENDENCY, asset: mesh(7) }],
+      owners: [
+        {
+          id: 'root.pack.ts',
+          guids: [ROOT],
+          async build(ownerSource) {
+            const dependency = await ownerSource.readByGuid(DEPENDENCY);
+            return dependency.ok
+              ? ok([
+                  {
+                    guid: ROOT,
+                    asset: mesh((dependency.value.asset as MeshAsset).vertices[0] ?? 0),
+                  },
+                ])
+              : dependency;
+          },
+        },
+      ],
+    });
+    const result = await source.readByGuid(ROOT);
+    expect(result).toMatchObject({ ok: true, value: { generation: 3 } });
+    expect(result.ok && (result.value.asset as MeshAsset).vertices[0]).toBe(7);
   });
 
   it('retries a refused local owner on the same source and coalesces repaired reads', async () => {
     let rootBuilds = 0;
     let dependencyBuilds = 0;
     let healthyBuilds = 0;
-    let fallbackReads = 0;
     let repaired = false;
     let releaseRepair!: () => void;
     const repairBuildGate = new Promise<void>((resolve) => {
@@ -166,12 +208,6 @@ describe('ScriptablePack staged asset snapshot source', () => {
     const source = createScriptablePackStagedAssetSnapshotSource({
       generation: 27,
       owners,
-      fallback: {
-        async readByGuid() {
-          fallbackReads += 1;
-          return ok({ asset: mesh(99), generation: 0, digest: 'sha256:lkg' });
-        },
-      },
     });
 
     const refused = await source.readByGuid(ROOT);
@@ -185,7 +221,6 @@ describe('ScriptablePack staged asset snapshot source', () => {
     });
     expect(rootBuilds).toBe(1);
     expect(dependencyBuilds).toBe(1);
-    expect(fallbackReads).toBe(0);
 
     const healthy = await source.readByGuid(HEALTHY);
     expect(healthy).toMatchObject({
@@ -193,7 +228,6 @@ describe('ScriptablePack staged asset snapshot source', () => {
       value: { generation: 27, digest: 'sha256:healthy' },
     });
     expect(healthyBuilds).toBe(1);
-    expect(fallbackReads).toBe(0);
 
     repaired = true;
     const repairedReads = [
@@ -220,7 +254,6 @@ describe('ScriptablePack staged asset snapshot source', () => {
     expect(rootBuilds).toBe(2);
     expect(dependencyBuilds).toBe(1);
     expect(healthyBuilds).toBe(1);
-    expect(fallbackReads).toBe(0);
 
     const dependency = await source.readByGuid(DEPENDENCY);
     expect(dependency).toMatchObject({
@@ -232,7 +265,6 @@ describe('ScriptablePack staged asset snapshot source', () => {
     expect(memoized).toMatchObject({ ok: true, value: { generation: 27, digest: 'sha256:root' } });
     expect(memoized.ok && (memoized.value.asset as MeshAsset).vertices[0]).toBe(3);
     expect(rootBuilds).toBe(2);
-    expect(fallbackReads).toBe(0);
   });
 
   it('carries the staged generation into every locally built snapshot', async () => {

package/src/browser.ts

@@ -0,0 +1,14 @@
+export { IMPORT_ERROR_HINTS, ImportError } from '@forgeax/engine-types';
+export {
+  type DdcPack,
+  type ImportRunnerFs,
+  normaliseForPack,
+  type RunImportMeta,
+  type RunImportOk,
+  type RunImportProductResult,
+  type RunImportResult,
+  runImport,
+  SHADER_RESERVED_IMPORTER_KEY,
+} from './import-runner.js';
+export { ImporterRegistry } from './importer-registry.js';
+export { packMeshBinV4 } from './mesh-bin.js';