@forgeax/engine-pack 0.1.3 → 0.1.4

package/src/__tests__/scanner-inventory.contract.test.ts

@@ -0,0 +1,167 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { AssetGuid } from '../guid.js';
+import { scan, scanInventory } from '../scanner.js';
+
+const GUID = '019e3969-1d48-7c3b-ac24-6d68f457065f';
+
+function guid(value: string): Uint8Array {
+  const parsed = AssetGuid.parse(value);
+  if (!parsed.ok) throw parsed.error;
+  return parsed.value;
+}
+
+describe('engine-pack scanner inventory contract', () => {
+  const roots: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+  });
+
+  it('returns one inventory declaration with source identity before finalization', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-inventory-'));
+    roots.push(root);
+    await writeFile(
+      join(root, 'hero.pack.json'),
+      JSON.stringify({
+        schemaVersion: '2.0.0',
+        kind: 'internal-text-package',
+        assets: [
+          {
+            guid: GUID,
+            kind: 'texture',
+            payload: { kind: 'texture', width: 1, height: 1 },
+            refs: [],
+            sourceKey: 'hero/albedo',
+            sourceIndex: 0,
+          },
+        ],
+      }),
+    );
+
+    const result = await scanInventory([root]);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.inventory).toHaveLength(1);
+    expect(result.value.inventory[0]).toMatchObject({
+      guid: GUID,
+      sourceKey: 'hero/albedo',
+      sourceIndex: 0,
+    });
+  });
+
+  it('returns the parsed Meta, Pack, and ScriptablePack declarations from one scan pass', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-declarations-'));
+    roots.push(root);
+
+    const metaPath = join(root, 'hero.meta.json');
+    const packPath = join(root, 'environment.pack.json');
+    const scriptablePath = join(root, 'effects.pack.ts');
+    const meta = {
+      schemaVersion: '1.0.0',
+      kind: 'external-asset-package',
+      importer: 'image',
+      source: 'hero.png',
+      importSettings: {},
+      subAssets: [
+        { guid: '019e3969-1d48-7c3b-ac24-6d68f4570660', sourceIndex: 0, kind: 'texture' },
+      ],
+    } as const;
+    const pack = {
+      schemaVersion: '2.0.0',
+      kind: 'internal-text-package',
+      assets: [
+        {
+          guid: '019e3969-1d48-7c3b-ac24-6d68f4570661',
+          kind: 'texture',
+          payload: { kind: 'texture', width: 1, height: 1 },
+          refs: [],
+        },
+      ],
+    } as const;
+    await writeFile(join(root, 'hero.png'), 'source');
+    await writeFile(metaPath, JSON.stringify(meta));
+    await writeFile(packPath, JSON.stringify(pack));
+    await writeFile(scriptablePath, '// scanner fixture');
+
+    const scriptablePackageId = guid('019e3969-1d48-7c3b-ac24-6d68f4570662');
+    const scriptableAssetGuid = guid('019e3969-1d48-7c3b-ac24-6d68f4570663');
+    const result = await scanInventory([root], {
+      scriptablePack: {
+        executor: {
+          load: async () => ({
+            default: {
+              schemaVersion: '1.0.0',
+              packageId: scriptablePackageId,
+              assets: { effect: { guid: scriptableAssetGuid, kind: 'scene' } },
+              externalAssets: {},
+              build: () => ({ ok: true, value: {} }),
+            },
+          }),
+        },
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.declarations.size).toBe(3);
+    expect(result.value.declarations.get(metaPath)).toMatchObject({
+      format: 'meta.json',
+      sourcePath: metaPath,
+      value: meta,
+    });
+    expect(result.value.declarations.get(packPath)).toMatchObject({
+      format: 'pack.json',
+      sourcePath: packPath,
+      value: pack,
+    });
+    const scriptableDeclaration = result.value.declarations.get(scriptablePath);
+    expect(scriptableDeclaration).toMatchObject({
+      format: 'pack.ts',
+      sourcePath: scriptablePath,
+      value: {
+        importer: 'pack-ts',
+        packageId: '019e3969-1d48-7c3b-ac24-6d68f4570662',
+        subAssets: [{ sourceKey: 'effect', kind: 'scene' }],
+      },
+    });
+    expect(
+      scriptableDeclaration?.format === 'pack.ts' ? scriptableDeclaration.meta : undefined,
+    ).toBe(scriptableDeclaration?.format === 'pack.ts' ? scriptableDeclaration.value : undefined);
+  });
+
+  it('releases the ScriptablePack loader for the path-only scan contract', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-pack-scan-release-'));
+    roots.push(root);
+    const scriptablePath = join(root, 'effects.pack.ts');
+    await writeFile(scriptablePath, '// scanner fixture');
+
+    const packageId = guid('019e3969-1d48-7c3b-ac24-6d68f4570664');
+    const assetGuid = guid('019e3969-1d48-7c3b-ac24-6d68f4570665');
+    let disposals = 0;
+    const result = await scan([root], {
+      scriptablePack: {
+        executor: {
+          load: async () => ({
+            default: {
+              schemaVersion: '1.0.0',
+              packageId,
+              assets: { effect: { guid: assetGuid, kind: 'scene' } },
+              externalAssets: {},
+              build: () => ({ ok: true, value: {} }),
+            },
+          }),
+          dispose: async () => {
+            disposals += 1;
+          },
+        },
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    expect(disposals).toBe(1);
+  });
+});

package/src/__tests__/scanner-inventory.test.ts

@@ -44,28 +44,32 @@ describe('AssetInventory', () => {
 
   it('projects the ScriptablePack declaration and owner outputs', () => {
     const { inventory, sourcePath } = getFixture();
-    const declaration = inventory.declarationsByPath.get(sourcePath);
+    const declaration = inventory.declarations.get(sourcePath);
     expect(declaration).toMatchObject({
+      format: 'pack.ts',
       sourcePath,
-      producer: 'scriptable-pack',
-      outputs: [{ guid, sourceKey: 'mesh', kind: 'mesh', refs: [] }],
-      externalGuids: [],
-      diagnostics: [],
+      meta: {
+        importer: 'pack-ts',
+        subAssets: [{ guid, sourceKey: 'mesh', kind: 'mesh' }],
+      },
     });
   });
 
   it('projects source closure evidence', async () => {
     const { inventory, sourcePath } = getFixture();
-    const declaration = inventory.declarationsByPath.get(sourcePath);
-    expect(declaration?.sourceClosure?.map((entry) => entry.path)).toEqual([
-      await realpath(sourcePath),
-    ]);
+    const declaration = inventory.declarations.get(sourcePath);
+    expect(
+      declaration?.format === 'pack.ts'
+        ? declaration.sourceClosure.map((entry) => entry.path)
+        : undefined,
+    ).toEqual([await realpath(sourcePath)]);
   });
 
-  it('indexes the output GUID and ScriptablePack metadata', () => {
+  it('indexes the ScriptablePack declaration without a second metadata registry', () => {
     const { inventory, sourcePath } = getFixture();
-    expect(inventory.sourceByGuid.get(guid)).toBe(sourcePath);
-    expect(inventory.scriptablePackMeta.get(sourcePath)?.subAssets).toEqual([
+    const declaration = inventory.declarations.get(sourcePath);
+    expect(inventory.inventory).toEqual([]);
+    expect(declaration?.format === 'pack.ts' ? declaration.meta.subAssets : undefined).toEqual([
       { guid, sourceIndex: 0, sourceKey: 'mesh', kind: 'mesh' },
     ]);
   });

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

@@ -112,6 +112,48 @@ describe('ScriptablePack definition and Meta projection', () => {
     ]);
   });
 
+  it('freezes component-token schemas as an ECS-neutral scene projection', () => {
+    const source = definition();
+    const input = {
+      ...source,
+      sceneComponents: [
+        {
+          name: 'MeshFilter',
+          fields: { assetHandle: { type: 'shared<MeshAsset>', default: 0 } },
+        },
+      ],
+    };
+    const validated = validateScriptablePackDefinition(input, 'scene-components.pack.ts');
+    expect(validated.ok).toBe(true);
+    if (!validated.ok) return;
+
+    expect(validated.value.sceneComponents).toEqual([
+      { name: 'MeshFilter', fields: { assetHandle: 'shared<MeshAsset>' } },
+    ]);
+    expect(validated.value.sceneComponents?.[0]).not.toBe(input.sceneComponents[0]);
+  });
+
+  it('rejects duplicate scene component names before build', () => {
+    const source = definition();
+    const validated = validateScriptablePackDefinition(
+      {
+        ...source,
+        sceneComponents: [
+          { name: 'MeshFilter', fields: {} },
+          { name: 'MeshFilter', fields: {} },
+        ],
+      },
+      'duplicate-scene-components.pack.ts',
+    );
+    expect(validated).toMatchObject({
+      ok: false,
+      error: {
+        code: 'pack-source-definition-invalid',
+        detail: { propertyPath: '$.sceneComponents[1].name' },
+      },
+    });
+  });
+
   it('rejects duplicate local GUIDs before build', () => {
     const source = definition();
     const duplicate = {

package/src/atlas/shelf-pack.ts

@@ -82,6 +82,24 @@ export type ShelfPackOutcome =
   | { readonly ok: true; readonly value: ShelfPackResult }
   | { readonly ok: false; readonly error: ShelfPackError };
 
+function sizeExceeded(
+  image: AtlasImageInput,
+  maxAtlasSize: number,
+): { readonly ok: false; readonly error: ShelfPackError } {
+  return {
+    ok: false,
+    error: {
+      code: 'atlas-size-exceeded',
+      detail: {
+        name: image.name,
+        width: image.width,
+        height: image.height,
+        maxAtlasSize,
+      },
+    },
+  };
+}
+
 function nextPow2(n: number): number {
   if (n <= 1) return 1;
   let p = 1;
@@ -104,18 +122,7 @@ export function shelfPack(
 
   for (const img of images) {
     if (img.width > maxAtlasSize || img.height > maxAtlasSize) {
-      return {
-        ok: false,
-        error: {
-          code: 'atlas-size-exceeded',
-          detail: {
-            name: img.name,
-            width: img.width,
-            height: img.height,
-            maxAtlasSize,
-          },
-        },
-      };
+      return sizeExceeded(img, maxAtlasSize);
     }
   }
 
@@ -148,18 +155,7 @@ export function shelfPack(
       currentShelfHeight = img.height;
     }
     if (cursorY + img.height > maxAtlasSize) {
-      return {
-        ok: false,
-        error: {
-          code: 'atlas-size-exceeded',
-          detail: {
-            name: img.name,
-            width: img.width,
-            height: img.height,
-            maxAtlasSize,
-          },
-        },
-      };
+      return sizeExceeded(img, maxAtlasSize);
     }
     regions.push({ name: img.name, x: cursorX, y: cursorY, w: img.width, h: img.height });
     cursorX += img.width;

package/src/build.ts

@@ -0,0 +1,137 @@
+// @forgeax/engine-pack/build
+// Node-only catalog, source scanning, package finalization, and build evidence.
+
+export type {
+  AnimationClip,
+  AnimationGraph,
+  Asset,
+  AudioClipAsset,
+  EquirectAsset,
+  FontAsset,
+  MaterialAsset,
+  MeshAsset,
+  PackV2,
+  PackV2Error,
+  ParticleEffectAsset,
+  RenderPipelineAsset,
+  SamplerAsset,
+  SceneAsset,
+  SkeletonAsset,
+  SkinAsset,
+  TextureAsset,
+  TilesetAsset,
+  VideoAsset,
+} from '@forgeax/engine-types';
+export type { ArtifactPathContext } from './artifact-path.js';
+export { validateArtifactPath } from './artifact-path.js';
+export {
+  buildCatalogProjection,
+  type CatalogAuthority,
+  type CatalogBuildError,
+  type CatalogBuildErrorCode,
+  type CatalogBuildProjectionOptions,
+  type CatalogBuildResult,
+  type CatalogImporterPolicy,
+  type CatalogProducerVisibility,
+  metaPathForGuid,
+} from './catalog-builder.js';
+export { calculateCatalogDelta } from './catalog-delta.js';
+export {
+  type CatalogOutputDeclaration,
+  type CatalogProducerMeta,
+  type CookedPackageProjection,
+  catalogProjectionFor,
+  currentProjectionFor,
+  findReservedAssetKindConflict,
+  type PackageCatalogInput,
+  projectCookedPackageEntry,
+  projectExternalCatalogEntries,
+  projectPackageCatalog,
+  projectRuntimeCatalogRow,
+  type RuntimeCatalogRowInput,
+} from './catalog-projection.js';
+export {
+  type CookedMaterialRecord,
+  collectMaterialCookRefs,
+  createMaterialArtifactDigest,
+  type MaterialCookArtifact,
+  type MaterialCookIdentityExpectation,
+  type MaterialCookReceipt,
+  type MaterialCookRecordError,
+  type MaterialCookRefs,
+  projectCookedMaterialRecord,
+  serializeCookedMaterialRecord,
+  serializeMaterialCookReceipt,
+  validateCookedMaterialRecord,
+  validateMaterialCookReceipt,
+} from './evidence/material-cook.js';
+export { buildOfflineAssetEvidence, packageVerification } from './evidence/offline-evidence.js';
+export {
+  decodeMeshBinHeader,
+  MESH_BIN_DIGEST_BYTES,
+  MESH_BIN_HEADER_V4_BYTES,
+  MESH_BIN_PROJECTION_VERSION,
+  MESH_BIN_VERSION,
+  type MeshBinContractError,
+  type MeshBinHeaderResult,
+  type MeshBinHeaderV4,
+  writeMeshBinHeader,
+} from './mesh-bin-contract.js';
+export {
+  type AuthoredPackAssetInput,
+  type AuthoredPackInput,
+  type FinalizedPackageProduct,
+  finalizePackageProduct,
+  finalizePackageTransportSource,
+  type PackageArtifactBody,
+  type PackageFinalizePolicy,
+  type PackageFinalizeResult,
+  type PackageFinalizerError,
+  type PackageProduct,
+  type PackageProductAsset,
+  packageTransportRevision,
+  upgradeLegacyAuthoredPack,
+} from './package-finalizer.js';
+export { validateProducerContract, validateProducerOutputs } from './producer-contract.js';
+export { parsePackV2, validateMeta, validatePack, validatePackV2 } from './runtime.js';
+export {
+  createRuntimePackPublication,
+  type RuntimePackAssetInput,
+  type RuntimePackEnvelope,
+  type RuntimePackInput,
+  type RuntimePackPublication,
+  type RuntimePackPublicationInput,
+} from './runtime-publication.js';
+export {
+  type InventoryDeclaration,
+  type ScanInventory,
+  type ScanOptions,
+  type ScriptablePackInventoryDeclaration,
+  type ScriptablePackScanOptions,
+  STANDARD_SCRIPTABLE_PACK_SCAN_OPTIONS,
+  scanInventory,
+} from './scanner.js';
+export {
+  type AssetReader,
+  isScriptablePackAssetKind,
+  projectScriptablePackMeta,
+  projectScriptablePackSceneComponents,
+  SCRIPTABLE_PACK_ASSET_KINDS,
+  SCRIPTABLE_PACK_CAPABILITY_MANIFEST,
+  type ScriptablePackAssetDeclaration,
+  type ScriptablePackAssetDeclarations,
+  type ScriptablePackAssetFor,
+  type ScriptablePackAssetKind,
+  type ScriptablePackDefinition,
+  type ScriptablePackError,
+  type ScriptablePackExternalAssets,
+  type ScriptablePackMetaJson,
+  type ScriptablePackOutputs,
+  type ScriptablePackPublicationEnvelope,
+  type ScriptablePackReadError,
+  type ScriptablePackSceneComponent,
+  type ScriptablePackSceneComponentInput,
+  type ScriptablePackSourceClosureEntry,
+  validateScriptablePackDefinition,
+} from './scriptable-pack.js';
+export { calculateTopologyDiff, diffTopology } from './topology.js';

package/src/builtin.ts

@@ -77,3 +77,41 @@ export const BUILTIN_HANDLE_TRIANGLE = await deriveSync('HANDLE_TRIANGLE');
  * Derived from: deriveBuiltin('HANDLE_QUAD') under FORGEAX_NAMESPACE.
  */
 export const BUILTIN_HANDLE_QUAD = await deriveSync('HANDLE_QUAD');
+
+/** Pre-computed UUIDv5 for the Engine-owned sphere mesh descriptor. */
+export const BUILTIN_HANDLE_SPHERE = await deriveSync('HANDLE_SPHERE');
+
+/** Pre-computed UUIDv5 for the Engine-owned nine-slice quad descriptor. */
+export const BUILTIN_HANDLE_NINESLICE_QUAD = await deriveSync('HANDLE_NINESLICE_QUAD');
+
+/** Pre-computed UUIDv5 for the Engine-owned cylinder mesh descriptor. */
+export const BUILTIN_HANDLE_CYLINDER = await deriveSync('HANDLE_CYLINDER');
+
+export type BuiltinMeshGeometry =
+  | 'procedural-cube'
+  | 'procedural-triangle'
+  | 'procedural-quad'
+  | 'procedural-sphere'
+  | 'procedural-nine-slice-quad'
+  | 'procedural-cylinder';
+
+/**
+ * The complete Engine-owned procedural mesh catalog.
+ *
+ * These are Pack descriptors, not runtime payloads: the Geometry decoder
+ * expands each `geometry` token into its validated MeshAsset. DevKit uses this
+ * list to materialize only the descriptors a standalone project does not
+ * already author, keeping the shipped game self-contained without duplicate
+ * GUID declarations.
+ */
+export const BUILTIN_MESH_ASSETS: ReadonlyArray<{
+  readonly guid: string;
+  readonly geometry: BuiltinMeshGeometry;
+}> = Object.freeze([
+  { guid: BUILTIN_HANDLE_CUBE, geometry: 'procedural-cube' },
+  { guid: BUILTIN_HANDLE_TRIANGLE, geometry: 'procedural-triangle' },
+  { guid: BUILTIN_HANDLE_QUAD, geometry: 'procedural-quad' },
+  { guid: BUILTIN_HANDLE_SPHERE, geometry: 'procedural-sphere' },
+  { guid: BUILTIN_HANDLE_NINESLICE_QUAD, geometry: 'procedural-nine-slice-quad' },
+  { guid: BUILTIN_HANDLE_CYLINDER, geometry: 'procedural-cylinder' },
+]);