@forgeax/engine-pack 0.1.3 → 0.1.6

package/src/scriptable-pack-node.ts

@@ -22,6 +22,7 @@ import {
   type ScriptablePackDefinition,
   type ScriptablePackError,
   type ScriptablePackReadError,
+  type ScriptablePackSourceClosureEntry,
   validateScriptablePackDefinition,
 } from './scriptable-pack.js';
 
@@ -76,13 +77,17 @@ export async function readOptionalBuildCache<T>(cache: OptionalBuildCache<T>): P
   return { value: await cache.coldCook(), fromCache: false };
 }
 
-/** Serializable source-closure evidence shared by scanner and producer paths. */
-export interface ScriptablePackSourceClosureEntry {
-  readonly path: string;
-  readonly digest: string;
+export interface LoadScriptablePackOptions {
+  /** Maximum time allowed for module initialization in the isolated worker. */
+  readonly timeoutMs?: number;
+  /** Maximum time allowed for one definition.build(reader) in the isolated worker. */
+  readonly buildTimeoutMs?: number;
+  readonly executor?: ScriptablePackModuleExecutor;
+  /** Release the isolated loader after identity projection when build will not be called. */
+  readonly metadataOnly?: boolean;
 }
 
-async function resolveRelativeSourceImport(
+async function resolveRelativeImport(
   sourcePath: string,
   specifier: string,
 ): Promise<string | undefined> {
@@ -111,38 +116,33 @@ async function resolveRelativeSourceImport(
   return undefined;
 }
 
-/** Inventory a ScriptablePack module without importing or executing it. */
+/** Capture one immutable ScriptablePack module closure for inventory and production. */
 export async function inventoryScriptablePackSource(
   sourcePath: string,
+  initialSourceText?: string,
 ): Promise<readonly ScriptablePackSourceClosureEntry[]> {
-  const pending = [await realpath(sourcePath)];
+  const root = await realpath(sourcePath);
+  const pending = [root];
   const seen = new Set<string>();
   const entries: ScriptablePackSourceClosureEntry[] = [];
   while (pending.length > 0) {
     const path = pending.pop();
     if (path === undefined || seen.has(path)) continue;
     seen.add(path);
-    const bytes = await readFile(path);
+    const bytes =
+      path === root && initialSourceText !== undefined
+        ? new TextEncoder().encode(initialSourceText)
+        : await readFile(path);
     entries.push({ path, digest: `sha256:${createHash('sha256').update(bytes).digest('hex')}` });
-    const imports = ts.preProcessFile(new TextDecoder().decode(bytes), true, true).importedFiles;
-    for (const imported of imports) {
-      const resolved = await resolveRelativeSourceImport(path, imported.fileName);
+    const source = new TextDecoder().decode(bytes);
+    for (const imported of ts.preProcessFile(source, true, true).importedFiles) {
+      const resolved = await resolveRelativeImport(path, imported.fileName);
       if (resolved !== undefined) pending.push(await realpath(resolved));
     }
   }
   return entries.sort((left, right) => left.path.localeCompare(right.path));
 }
 
-export interface LoadScriptablePackOptions {
-  /** Maximum time allowed for module initialization in the isolated worker. */
-  readonly timeoutMs?: number;
-  /** Maximum time allowed for one definition.build(reader) in the isolated worker. */
-  readonly buildTimeoutMs?: number;
-  readonly executor?: ScriptablePackModuleExecutor;
-  /** Release the isolated loader after identity projection when build will not be called. */
-  readonly metadataOnly?: boolean;
-}
-
 interface StructuredFailure {
   readonly name?: unknown;
   readonly code?: unknown;
@@ -246,6 +246,10 @@ class WorkerScriptablePackExecutor implements ScriptablePackModuleExecutor {
         if (message === null || typeof message !== 'object') return;
         const value = message as Record<string, unknown>;
         if (value.kind === 'loaded') {
+          // The scan keeps this executor alive for the later no-reopen build
+          // route, but an idle source worker must not keep a Vite/Vitest host
+          // process alive after its own work has settled.
+          worker.unref();
           worker.off('message', onMessage);
           resolveLoad({
             default:
@@ -966,7 +970,7 @@ export default {
   packageId: ${guidExpression(manifest.packageId)},
   ${manifest.name === undefined ? '' : `name: ${JSON.stringify(manifest.name)},\n  `}assets,
   externalAssets,
-  build: () => ok(Object.fromEntries(Object.entries(assets).map(([sourceKey, asset]) => [sourceKey, createOutput(asset.kind)])) as never),
+  build: () => ok(Object.fromEntries(Object.entries(assets).map(([sourceKey, asset]) => [sourceKey, createOutput(asset.kind)])) as Record<string, Asset>),
 } satisfies ScriptablePackDefinition;
 `;
 }
@@ -1000,7 +1004,7 @@ function definitionFromCanonical(
     ...(manifest.name === undefined ? {} : { name: manifest.name }),
     assets,
     externalAssets,
-    build: () => ok({} as never),
+    build: () => ok({} as Record<string, never>),
   });
 }
 

package/src/scriptable-pack-worker.ts

@@ -21,6 +21,7 @@ type LoadedDefinition = {
   readonly packageId?: unknown;
   readonly name?: unknown;
   readonly assets?: unknown;
+  readonly sceneComponents?: unknown;
   readonly externalAssets?: unknown;
   readonly build?: unknown;
 };
@@ -232,6 +233,7 @@ async function loadDefinition(task: {
             packageId: definition.packageId,
             name: definition.name,
             assets: definition.assets,
+            sceneComponents: definition.sceneComponents,
             externalAssets: definition.externalAssets,
           },
   });

package/src/scriptable-pack.ts

@@ -25,6 +25,15 @@ export const SCRIPTABLE_PACK_ASSET_KINDS = [
   'particle-effect',
 ] as const satisfies readonly ScriptablePackAssetKind[];
 
+/** Machine-readable producer/loader floor owned by engine-pack. */
+export const SCRIPTABLE_PACK_CAPABILITY_MANIFEST = {
+  assetKinds: SCRIPTABLE_PACK_ASSET_KINDS,
+  durablePayload: true,
+  refs: true,
+  artifacts: true,
+  hostCapabilities: ['audio-install', 'video-play', 'particle-execute'] as const,
+} as const;
+
 export function isScriptablePackAssetKind(value: string): value is ScriptablePackAssetKind {
   return (SCRIPTABLE_PACK_ASSET_KINDS as readonly string[]).includes(value);
 }
@@ -43,6 +52,43 @@ export type ScriptablePackAssetDeclarations = Readonly<
 
 export type ScriptablePackExternalAssets = Readonly<Record<string, AssetGuid>>;
 
+/**
+ * Component-shaped input accepted by a ScriptablePack scene declaration.
+ * Engine component tokens satisfy this shape; plain `{ type }` rows keep the
+ * Pack contract independent of ECS and survive the isolated module worker.
+ */
+export interface ScriptablePackSceneComponentInput {
+  readonly name: string;
+  readonly fields: Readonly<Record<string, string | { readonly type: string }>>;
+}
+
+/** Neutral scene schema projection owned by the Pack definition. */
+export interface ScriptablePackSceneComponent {
+  readonly name: string;
+  readonly fields: Readonly<Record<string, string>>;
+}
+
+function sceneComponentFieldType(value: unknown): string | undefined {
+  if (typeof value === 'string') return value;
+  if (isRecord(value) && typeof value.type === 'string') return value.type;
+  return undefined;
+}
+
+/** Derive the frozen, ECS-neutral schema used by scene output producers. */
+export function projectScriptablePackSceneComponents(
+  components: readonly ScriptablePackSceneComponentInput[] | undefined,
+): readonly ScriptablePackSceneComponent[] {
+  return (components ?? []).map((component) => ({
+    name: component.name,
+    fields: Object.fromEntries(
+      Object.entries(component.fields).map(([fieldName, field]) => [
+        fieldName,
+        sceneComponentFieldType(field) as string,
+      ]),
+    ),
+  }));
+}
+
 /** Pack-facing name for the shared Engine publication envelope. */
 export type ScriptablePackPublicationEnvelope = AssetPublicationEnvelope;
 
@@ -96,6 +142,8 @@ export interface ScriptablePackDefinition<
   readonly packageId: AssetGuid;
   readonly name?: string;
   readonly assets: TAssets;
+  /** Component tokens/schema rows used by scene ref externalization. */
+  readonly sceneComponents?: readonly ScriptablePackSceneComponentInput[];
   readonly externalAssets: TExternal;
   readonly build: (
     assetReader: AssetReader,
@@ -104,6 +152,11 @@ export interface ScriptablePackDefinition<
     | Promise<ScriptablePackBuildResult<TAssets, TError>>;
 }
 
+export interface ScriptablePackSourceClosureEntry {
+  readonly path: string;
+  readonly digest: string;
+}
+
 export interface ScriptablePackMetaJson {
   readonly schemaVersion: '1.0.0';
   readonly kind: 'external-asset-package';
@@ -707,7 +760,7 @@ function invalid(
   });
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
+export function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
@@ -734,11 +787,23 @@ function freezeDefinition(
       guid.slice() as AssetGuid,
     ]),
   );
+  const sceneComponents =
+    definition.sceneComponents === undefined
+      ? undefined
+      : Object.freeze(
+          projectScriptablePackSceneComponents(definition.sceneComponents).map((component) =>
+            Object.freeze({
+              ...component,
+              fields: Object.freeze({ ...component.fields }),
+            }),
+          ),
+        );
   return Object.freeze({
     ...definition,
     packageId: definition.packageId.slice() as AssetGuid,
     assets: Object.freeze(assets),
     externalAssets: Object.freeze(externalAssets),
+    ...(sceneComponents === undefined ? {} : { sceneComponents }),
   });
 }
 
@@ -773,6 +838,63 @@ export function validateScriptablePackDefinition(
       sourcePath,
     );
   }
+  if (value.sceneComponents !== undefined) {
+    if (!Array.isArray(value.sceneComponents)) {
+      return invalid(
+        '$.sceneComponents',
+        'an array of component tokens or neutral schema rows when present',
+        value.sceneComponents,
+        sourcePath,
+      );
+    }
+    const componentNames = new Set<string>();
+    for (const [componentIndex, component] of value.sceneComponents.entries()) {
+      if (!isRecord(component)) {
+        return invalid(
+          `$.sceneComponents[${componentIndex}]`,
+          'a component token or neutral schema row',
+          component,
+          sourcePath,
+        );
+      }
+      if (typeof component.name !== 'string' || component.name.trim().length === 0) {
+        return invalid(
+          `$.sceneComponents[${componentIndex}].name`,
+          'a non-empty component name',
+          component.name,
+          sourcePath,
+        );
+      }
+      if (componentNames.has(component.name)) {
+        return invalid(
+          `$.sceneComponents[${componentIndex}].name`,
+          'component names to be unique within one ScriptablePack',
+          component.name,
+          sourcePath,
+        );
+      }
+      componentNames.add(component.name);
+      if (!isRecord(component.fields)) {
+        return invalid(
+          `$.sceneComponents[${componentIndex}].fields`,
+          'a field-name to schema-type object',
+          component.fields,
+          sourcePath,
+        );
+      }
+      for (const [fieldName, field] of Object.entries(component.fields)) {
+        const type = sceneComponentFieldType(field);
+        if (fieldName.trim().length === 0 || type === undefined || type.trim().length === 0) {
+          return invalid(
+            `$.sceneComponents[${componentIndex}].fields`,
+            'field names with non-empty string schema types',
+            field,
+            sourcePath,
+          );
+        }
+      }
+    }
+  }
   if (typeof value.build !== 'function') {
     return invalid('$.build', 'a build(assetReader) function', value.build, sourcePath);
   }

package/src/topology.ts

@@ -152,5 +152,6 @@ export function diffTopology(
   return { preserved, added, removed, changedKind, ambiguous };
 }
 
-/** Alias named after the producer-facing contract wording. */
 export const calculateTopologyDiff = diffTopology;
+
+/** Alias named after the producer-facing contract wording. */