@forgeax/engine-pack 0.1.3 → 0.1.4

package/README.md

@@ -70,6 +70,25 @@ source.
 
 Pack or external source plus Meta owns author facts. DDC and Catalog are derived projections; they are not author databases or write authorities.
 
+## Engine builtin mesh descriptors
+
+The Engine-owned primitive mesh identities are published from one UUIDv5 table
+(`@forgeax/engine-pack/builtin`). A standalone DevKit build materializes only
+the missing rows as an ordinary Pack v2 tuple; Geometry then derives the mesh
+payload from the `procedural-*` token at load time.
+
+| Descriptor | GUID source | Geometry token |
+|:--|:--|:--|
+| Cube | `HANDLE_CUBE` | `procedural-cube` |
+| Triangle | `HANDLE_TRIANGLE` | `procedural-triangle` |
+| Quad | `HANDLE_QUAD` | `procedural-quad` |
+| Sphere | `HANDLE_SPHERE` | `procedural-sphere` |
+| Nine-slice quad | `HANDLE_NINESLICE_QUAD` | `procedural-nine-slice-quad` |
+| Cylinder | `HANDLE_CYLINDER` | `procedural-cylinder` |
+
+This keeps the runtime registry generic while ensuring a packaged game can
+resolve legacy scene references without a second process-static asset owner.
+
 > [!IMPORTANT]
 > The pack contract has one material authoring shape: a `MaterialAsset` payload. The cook stage resolves inheritance, values, texture coordinates, module references, artifact bytes, and a receipt into one record. Runtime consumers use the GUID and catalog locator; they do not author a second shader resource.
 
@@ -115,14 +134,26 @@ by a demo-side mesh substitute.
 
 Build-time importers write source meta and producer receipts; the Vite plugin publishes the locator. Runtime packages consume the resulting Pack v2 bytes and must not import this Node-only evidence adapter. See [`packages/types/src/asset-evidence.ts`](../types/src/asset-evidence.ts) for the exact schema and closed errors.
 
+Browser runtime code uses the focused Pack subpaths instead of the Node-oriented
+root barrel. The root entry remains the build-time scanner/evidence surface.
+
+| Runtime need | Browser-safe entry |
+|:--|:--|
+| Pack v2 validation and parsing | `@forgeax/engine-pack/runtime` |
+| Artifact locator validation | `@forgeax/engine-pack/artifact-path` |
+| Cooked material records | `@forgeax/engine-pack/material-cook` |
+| Mesh wire facts | `@forgeax/engine-pack/mesh-bin-contract` |
+
 ## Quick start
 
 ### ScriptablePack source
 
-Use `@forgeax/engine-pack/source` when one trusted TypeScript source declares and builds a multi-asset package. The definition owns `packageId`, every output `guid`, `sourceKey`, `kind`, and optional display `name`. `build(reader)` returns ordinary typed Assets keyed by the same `sourceKey` set; it cannot publish, mutate Catalog, or mint identity.
+Use `@forgeax/engine-pack/source` when one trusted TypeScript source declares and builds a multi-asset package. The definition owns `packageId`, every output `guid`, `sourceKey`, `kind`, optional display `name`, and the scene component schema needed to externalize scene refs. `build(reader)` returns ordinary typed Assets keyed by the same `sourceKey` set; it cannot publish, mutate Catalog, or mint identity.
 
 ```ts
 import type { ScriptablePackDefinition } from '@forgeax/engine-pack/source';
+import { Camera } from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
 
 export default {
   schemaVersion: '1.0.0',
@@ -131,11 +162,18 @@ export default {
     mesh: { guid: meshGuid, kind: 'mesh', name: 'Generated Mesh' },
     scene: { guid: sceneGuid, kind: 'scene', name: 'Generated Scene' },
   },
+  sceneComponents: [Transform, Camera],
   externalAssets: { material: materialGuid },
   build: async (assets) => ({ ok: true, value: { mesh, scene } }),
 } satisfies ScriptablePackDefinition;
 ```
 
+`sceneComponents` is optional for packs that never produce a `scene`. When a
+scene is produced, declare every component used by its entities in the same
+definition; the isolated Pack worker projects the tokens to a neutral,
+serializable schema. A scene component missing from that declaration is a
+fail-closed producer error, not a lookup into a global World schema.
+
 `forgeax-engine-remote-asset meta <source.pack.ts> --json` executes module initialization, validates the default export, and projects canonical Meta without calling `build`. `@forgeax/engine-pack/source-node` accepts a host executor with `load` and optional `dispose`; `timeoutMs` bounds module initialization and `buildTimeoutMs` bounds one `build(reader)` call. A build timeout returns one structured `pack-source-load-failed` Result with `detail.phase: 'build'`, the configured `timeoutMs`, and deterministic cleanup of the isolated worker and compile root.
 
 The default worker executes the complete relative TypeScript module closure on the supported Node floor, including Node 22 hosts that do not load `.ts` files directly. It transpiles that closure into a disposable ESM directory, resolves bare imports through the source project's nearest `node_modules`, and removes the directory when the worker is disposed. Bulk producers use the internal `createScriptablePackModuleExecutorPool()` with two recyclable workers; a pooled lease is released after metadata projection or one build, so a generation never retains one live Worker-backed definition per source.
@@ -218,8 +256,7 @@ Two sidecar JSON files live next to each source file in an asset directory:
 Both package schemas accept producer-owned `packageId`, `provenance`,
 `revision`, and structured `diagnostics`. Asset/output rows may declare a
 stable `sourceKey`; `sourceIndex` is positional evidence only. The runtime
-function `diffTopology(previous, next)` (also exported as
-`calculateTopologyDiff`) preserves GUIDs by `sourceKey`, reports additions,
+function `diffTopology(previous, next)` preserves GUIDs by `sourceKey`, reports additions,
 removals, and kind changes, and marks multi-output source-index-only matching
 as ambiguous.
 
@@ -358,6 +395,17 @@ wire-format oracles, never as a second layout table.
 > owning build-time importer/native cooker and `lookup/verify --guid --project
 > --catalog --json` before publishing the replacement.
 
+## Owner product and inventory contract
+
+`scanInventory(...)` is the Pack-owned source inventory boundary. It preserves
+GUID identity, source revision, source key, and source index before importer
+work begins.
+
+`finalizePackageProduct(...)` accepts the terminal producer product, validates
+one receipt per GUID, validates asset-local artifact paths and bytes, and emits
+the deterministic package URL and digest. Producers provide policy through the
+finalizer sink; Pack owns package serialization and publication facts.
+
 ## Entry subpaths
 
 | Subpath | Exports |