@forgeax/engine-import 0.1.2

package/src/scriptable-pack-output-producers.ts

@@ -0,0 +1,466 @@
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { externalizeSceneAsset } from '@forgeax/engine-scene';
+import type {
+  AnimationGraph,
+  Asset,
+  AssetGuid as AssetGuidType,
+  AssetRef,
+  AudioClipAsset,
+  EquirectAsset,
+  FontAsset,
+  ImportedArtifactBody,
+  MaterialAsset,
+  MaterialTextureReference,
+  MaterialTextureValue,
+  MeshAsset,
+  ParticleEffectAsset,
+  RenderPipelineAsset,
+  Result,
+  SamplerAsset,
+  SceneAsset,
+  SkeletonAsset,
+  SkinAsset,
+  TextureAsset,
+  TilesetAsset,
+  VideoAsset,
+} from '@forgeax/engine-types';
+import { err, ImportError, MATERIAL_TEXTURE_SLOTS, ok } from '@forgeax/engine-types';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+import { packMeshBinV4 } from './mesh-bin.js';
+import {
+  type AssetOutputInput,
+  type AssetOutputProducer,
+  AssetOutputProducerRegistry,
+  type AssetOutputProduct,
+} from './scriptable-pack.js';
+
+function producerError(input: AssetOutputInput, reason: unknown): ImportError {
+  return new ImportError({
+    code: 'import-internal-error',
+    expected: `ScriptablePack ${input.asset.kind} output ${input.sourceKey} to satisfy its domain producer contract`,
+    hint: 'fix the generated Asset payload and rebuild the ScriptablePack',
+    detail: { reason: reason instanceof Error ? reason.message : String(reason) },
+  });
+}
+
+function formatGuid(value: AssetGuidType | string): string {
+  if (typeof value === 'string') {
+    const parsed = AssetGuid.parse(value);
+    if (!parsed.ok) throw parsed.error;
+    return AssetGuid.format(parsed.value);
+  }
+  return AssetGuid.format(value);
+}
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, child]) => `${JSON.stringify(key)}:${canonical(child)}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+function particleProgramArtifact(effect: ParticleEffectAsset): {
+  readonly program: ParticleEffectAsset['program'];
+  readonly bytes: Uint8Array;
+  readonly fingerprint: string;
+} {
+  const artifactProgram = { format: effect.program.format, emitters: effect.program.emitters };
+  const bytes = new TextEncoder().encode(canonical(artifactProgram));
+  const fingerprint = `sha256:${bytesToHex(sha256(bytes))}`;
+  return {
+    program: { ...effect.program, fingerprint },
+    bytes,
+    fingerprint,
+  };
+}
+
+function materialProduct(input: AssetOutputInput): AssetOutputProduct {
+  if (input.asset.kind !== 'material') throw new TypeError('expected MaterialAsset');
+  const material = input.asset as MaterialAsset;
+  const refs: AssetRef[] = [];
+  const addRef = (
+    guid: AssetGuidType | string,
+    sourceField: NonNullable<AssetRef['sourceField']>,
+  ): number => {
+    refs.push({ guid: formatGuid(guid), sourceField });
+    return refs.length - 1;
+  };
+
+  const addMaterialRef = (
+    value: MaterialTextureReference,
+    sourceField: NonNullable<AssetRef['sourceField']>,
+  ): number => {
+    if (typeof value === 'number') {
+      throw new TypeError('material texture references must be GUIDs, not runtime handles');
+    }
+    return addRef(value, sourceField);
+  };
+
+  const textureFields =
+    material.parameters === undefined
+      ? new Set<string>(MATERIAL_TEXTURE_SLOTS)
+      : new Set(
+          material.parameters
+            .filter((parameter) => parameter.type === 'texture')
+            .map((parameter) => parameter.name),
+        );
+
+  const parent =
+    material.parent === undefined ? undefined : addRef(material.parent, { fieldName: 'parent' });
+  const values: Record<string, unknown> = {};
+  for (const fieldName of Object.keys(material.values ?? {}).sort()) {
+    const value = material.values?.[fieldName];
+    if (typeof value === 'string' && textureFields.has(fieldName)) {
+      values[fieldName] = addMaterialRef(value, { componentName: '<material>', fieldName });
+    } else if (
+      value !== null &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      'texture' in value
+    ) {
+      const texture = value as MaterialTextureValue;
+      values[fieldName] = {
+        ...texture,
+        texture: addMaterialRef(texture.texture, { componentName: '<material>', fieldName }),
+        ...(texture.sampler === undefined
+          ? {}
+          : {
+              sampler: addMaterialRef(texture.sampler, {
+                componentName: '<material>',
+                fieldName: `${fieldName}.sampler`,
+              }),
+            }),
+      };
+    } else {
+      values[fieldName] = value;
+    }
+  }
+
+  const { parent: _parent, values: _values, ...materialShape } = material;
+  return {
+    payload: {
+      ...materialShape,
+      ...(parent === undefined ? {} : { parent }),
+      ...(material.values === undefined ? {} : { values }),
+    },
+    refs,
+    artifacts: {},
+  };
+}
+
+export const materialAssetOutputProducer: AssetOutputProducer = {
+  kind: 'material',
+  version: 'material-pack/1',
+  produce(input): Result<AssetOutputProduct, ImportError> {
+    try {
+      return ok(materialProduct(input));
+    } catch (error) {
+      return err(producerError(input, error));
+    }
+  },
+};
+
+function meshProduct(input: AssetOutputInput): AssetOutputProduct {
+  if (input.asset.kind !== 'mesh') throw new TypeError('expected MeshAsset');
+  const mesh = input.asset as MeshAsset;
+  const refs: AssetRef[] = [];
+  for (let slotIndex = 0; slotIndex < mesh.materialSlots.length; slotIndex++) {
+    const defaultMaterial = mesh.materialSlots[slotIndex]?.defaultMaterial;
+    if (defaultMaterial === undefined) continue;
+    refs.push({
+      guid: formatGuid(defaultMaterial),
+      sourceField: { fieldName: 'materialSlots', arrayIndex: slotIndex },
+    });
+  }
+  return {
+    payload: mesh,
+    refs,
+    artifacts: {
+      body: {
+        mediaType: 'application/x-forgeax-mesh',
+        assetCodec: { name: 'mesh-binary', version: '4' },
+        bytes: (() => {
+          const packed = packMeshBinV4(
+            mesh,
+            input.sourceKey,
+            refs.map((reference) => reference.guid),
+          );
+          if (!packed.ok) {
+            throw packed.error;
+          }
+          return packed.value;
+        })(),
+      },
+    },
+  };
+}
+
+export const meshAssetOutputProducer: AssetOutputProducer = {
+  kind: 'mesh',
+  version: 'mesh-binary/4',
+  produce(input): Result<AssetOutputProduct, ImportError> {
+    try {
+      return ok(meshProduct(input));
+    } catch (error) {
+      return err(producerError(input, error));
+    }
+  },
+};
+
+function sceneProduct(input: AssetOutputInput): AssetOutputProduct {
+  if (input.asset.kind !== 'scene') throw new TypeError('expected SceneAsset');
+  const externalized = externalizeSceneAsset(input.asset as SceneAsset, (componentName) => {
+    const component = input.components?.get(componentName);
+    return component === undefined ? undefined : componentSchema(component);
+  });
+  if (!externalized.ok) throw new TypeError(`scene field ${externalized.error.field} is invalid`);
+  return {
+    payload: { kind: 'scene', ...externalized.value.payload },
+    refs: externalized.value.refs,
+    artifacts: {},
+  };
+}
+
+function jsonArtifact(value: unknown): ImportedArtifactBody {
+  return {
+    mediaType: 'application/json',
+    assetCodec: { name: 'forgeax-json', version: '1' },
+    bytes: new TextEncoder().encode(JSON.stringify(value)),
+  };
+}
+
+function ref(guid: AssetGuidType, fieldName: string, arrayIndex?: number): AssetRef {
+  return {
+    guid: formatGuid(guid),
+    sourceField: { fieldName, ...(arrayIndex === undefined ? {} : { arrayIndex }) },
+  };
+}
+
+function bytes(value: Uint8Array | Uint8ClampedArray): Uint8Array {
+  return Uint8Array.from(value);
+}
+
+function ordinaryPodProduct(input: AssetOutputInput): AssetOutputProduct {
+  const asset = input.asset;
+  switch (asset.kind) {
+    case 'texture': {
+      const texture = asset as TextureAsset;
+      return {
+        payload: texture,
+        refs: [],
+        artifacts: {
+          body: {
+            mediaType: 'image/raw',
+            assetCodec: { name: 'raw-image', version: '1' },
+            bytes: bytes(texture.data),
+          },
+        },
+      };
+    }
+    case 'equirect': {
+      const equirect = asset as EquirectAsset;
+      return {
+        payload: equirect,
+        refs: [],
+        artifacts: {
+          body: {
+            mediaType: 'image/raw',
+            assetCodec: { name: 'raw-image', version: '1' },
+            bytes: bytes(equirect.data),
+          },
+        },
+      };
+    }
+    case 'sampler': {
+      const sampler = asset as SamplerAsset;
+      return { payload: sampler, refs: [], artifacts: { body: jsonArtifact(sampler) } };
+    }
+    case 'font': {
+      const font = asset as FontAsset;
+      const atlas = ref(font.atlas, 'atlas');
+      const sampler = ref(font.sampler, 'sampler');
+      return {
+        payload: {
+          kind: font.kind,
+          glyphs: font.glyphs,
+          common: font.common,
+          atlasGuid: atlas.guid,
+          samplerGuid: sampler.guid,
+        },
+        refs: [atlas, sampler],
+        artifacts: { body: jsonArtifact(font) },
+      };
+    }
+    case 'render-pipeline': {
+      const pipeline = asset as RenderPipelineAsset;
+      return {
+        payload: pipeline,
+        refs: [],
+        artifacts: { body: jsonArtifact(pipeline) },
+      };
+    }
+    case 'tileset': {
+      const tileset = asset as TilesetAsset;
+      const refs = tileset.atlases.map((atlas, index) => {
+        const parsed = AssetGuid.parse(atlas);
+        if (!parsed.ok) throw parsed.error;
+        return ref(parsed.value, 'atlases', index);
+      });
+      return {
+        payload: { ...tileset, atlases: refs.map((_entry, index) => index) },
+        refs,
+        artifacts: { body: jsonArtifact(tileset) },
+      };
+    }
+    case 'video': {
+      const video = asset as VideoAsset;
+      try {
+        const url = new URL(video.url);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+          throw new Error('unsupported URL scheme');
+      } catch (error) {
+        throw new TypeError(
+          `video URL is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+      return { payload: video, refs: [], artifacts: {} };
+    }
+    case 'skeleton': {
+      const skeleton = asset as SkeletonAsset;
+      return {
+        payload: skeleton,
+        refs: [],
+        artifacts: { body: jsonArtifact(skeleton) },
+      };
+    }
+    case 'skin': {
+      const skin = asset as SkinAsset;
+      const skeletonGuid = AssetGuid.parse(skin.skeletonGuid);
+      if (!skeletonGuid.ok) throw skeletonGuid.error;
+      return {
+        payload: skin,
+        refs: [ref(skeletonGuid.value, 'skeletonGuid')],
+        artifacts: { body: jsonArtifact(skin) },
+      };
+    }
+    case 'animation-clip':
+      return {
+        payload: asset,
+        refs: [],
+        artifacts: { body: jsonArtifact(asset) },
+      };
+    case 'animation-graph': {
+      const graph = asset as AnimationGraph;
+      const refs: AssetRef[] = [];
+      const nodes = graph.nodes.map((node, index) => {
+        if (node.type !== 'clip') return node;
+        const parsed = AssetGuid.parse(node.clip);
+        if (!parsed.ok) throw parsed.error;
+        const referenceIndex = refs.push(ref(parsed.value, 'nodes', index)) - 1;
+        return { ...node, clip: referenceIndex };
+      });
+      return {
+        payload: { kind: graph.kind, root: graph.root, nodes },
+        refs,
+        artifacts: { body: jsonArtifact(graph) },
+      };
+    }
+    case 'audio': {
+      const audio = asset as AudioClipAsset;
+      return {
+        payload: {
+          kind: audio.kind,
+          sourceKey: audio.sourceKey,
+          mediaType: audio.mediaType,
+          bytes: audio.bytes.slice(),
+        },
+        refs: [],
+        artifacts: {
+          source: {
+            mediaType: audio.mediaType,
+            assetCodec: { name: 'browser-audio', version: '1' },
+            bytes: audio.bytes.slice(),
+          },
+        },
+      };
+    }
+    case 'particle-effect': {
+      const effect = asset as ParticleEffectAsset;
+      const cooked = particleProgramArtifact(effect);
+      return {
+        payload: { ...effect, programFingerprint: cooked.fingerprint, program: cooked.program },
+        refs: [],
+        artifacts: {
+          'particle-effect/program.json': {
+            mediaType: 'application/json',
+            assetCodec: { name: 'forgeax-vfx-program', version: effect.program.format },
+            bytes: cooked.bytes,
+          },
+        },
+      };
+    }
+    case 'material':
+    case 'mesh':
+    case 'scene':
+      throw new TypeError(`ordinary producer received already-owned ${asset.kind} asset`);
+  }
+}
+
+const ordinaryAssetOutputProducer: AssetOutputProducer = {
+  kind: 'texture',
+  version: 'ordinary-pod/1',
+  produce(input) {
+    try {
+      return ok(ordinaryPodProduct(input));
+    } catch (error) {
+      return err(producerError(input, error));
+    }
+  },
+};
+
+function createOrdinaryAssetOutputProducer(kind: Asset['kind']): AssetOutputProducer {
+  return { ...ordinaryAssetOutputProducer, kind };
+}
+
+export const sceneAssetOutputProducer: AssetOutputProducer = {
+  kind: 'scene',
+  version: 'scene-pack/2',
+  produce(input): Result<AssetOutputProduct, ImportError> {
+    try {
+      return ok(sceneProduct(input));
+    } catch (error) {
+      return err(producerError(input, error));
+    }
+  },
+};
+
+export function createStandardAssetOutputProducerRegistry(): AssetOutputProducerRegistry {
+  const registry = new AssetOutputProducerRegistry();
+  registry.register(materialAssetOutputProducer);
+  registry.register(meshAssetOutputProducer);
+  registry.register(sceneAssetOutputProducer);
+  for (const kind of [
+    'texture',
+    'equirect',
+    'sampler',
+    'font',
+    'render-pipeline',
+    'tileset',
+    'video',
+    'skeleton',
+    'skin',
+    'animation-clip',
+    'animation-graph',
+    'audio',
+    'particle-effect',
+  ] as const) {
+    registry.register(createOrdinaryAssetOutputProducer(kind));
+  }
+  return registry;
+}

package/src/scriptable-pack-staged-snapshot.ts

@@ -0,0 +1,161 @@
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { ScriptablePackError } from '@forgeax/engine-pack/source';
+import type { Asset, AssetGuid as AssetGuidType, ImportError, Result } from '@forgeax/engine-types';
+import { AssetError, err, ok } from '@forgeax/engine-types';
+import type {
+  ScriptablePackAssetSnapshot,
+  ScriptablePackAssetSnapshotSource,
+  ScriptablePackDomainError,
+  ScriptablePackStagedOutput,
+} from './scriptable-pack.js';
+
+export type ScriptablePackSnapshotError =
+  | AssetError
+  | ImportError
+  | ScriptablePackError
+  | ScriptablePackDomainError;
+
+export interface ScriptablePackStagedOwner {
+  readonly id: string;
+  readonly guids: readonly AssetGuidType[];
+  build(
+    source: ScriptablePackAssetSnapshotSource,
+  ): Promise<Result<readonly ScriptablePackStagedOutput[], ScriptablePackSnapshotError>>;
+}
+
+export interface ScriptablePackStagedSnapshotOptions {
+  readonly generation: number;
+  readonly owners: readonly ScriptablePackStagedOwner[];
+  /** A prebuilt authority only. Local source ownership always wins. */
+  readonly fallback?: ScriptablePackAssetSnapshotSource;
+}
+
+function stable(value: unknown): string {
+  if (ArrayBuffer.isView(value)) {
+    return `${value.constructor.name}:${JSON.stringify(Array.from(new Uint8Array(value.buffer, value.byteOffset, value.byteLength)))}`;
+  }
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stable(record[key])}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+async function assetDigest(asset: Asset): Promise<string> {
+  const bytes = new TextEncoder().encode(stable(asset));
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+  return `sha256:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('')}`;
+}
+
+function cycleError(stack: readonly string[], owner: string, guid: string): ScriptablePackError {
+  const cycleStart = stack.indexOf(owner);
+  const cycle = [...stack.slice(cycleStart), owner];
+  return {
+    code: 'pack-source-build-cycle',
+    expected: 'an acyclic graph of ScriptablePack content dependencies',
+    actual: cycle.join(' -> '),
+    hint: 'break one content read edge or convert it to a reference-only dependency',
+    retryable: false,
+    recoveryActions: ['inspect-content-dependency-graph', 'edit-source'],
+    detail: { sourcePath: owner, sourceKey: guid, incomingRefs: cycle },
+  };
+}
+
+function missingOutputError(owner: string, guid: string): ScriptablePackError {
+  return {
+    code: 'pack-source-output-invalid',
+    expected: `owner ${owner} to stage every declared output including ${guid}`,
+    hint: 'return one output for every GUID declared by the staged owner',
+    detail: { missingGuids: [guid], unexpectedSourceKeys: [], kindMismatches: [] },
+  };
+}
+
+/**
+ * One-build authority for current-generation ScriptablePack content reads.
+ * Local owners are built lazily, memoized, and never resolved through an old Catalog/DDC generation.
+ */
+export function createScriptablePackStagedAssetSnapshotSource(
+  options: ScriptablePackStagedSnapshotOptions,
+): ScriptablePackAssetSnapshotSource {
+  const ownerByGuid = new Map<string, ScriptablePackStagedOwner>();
+  for (const owner of options.owners) {
+    if (owner.id.trim().length === 0) throw new TypeError('staged owner id must be non-empty');
+    for (const guid of owner.guids) {
+      const key = AssetGuid.format(guid).toLowerCase();
+      const existing = ownerByGuid.get(key);
+      if (existing !== undefined) {
+        throw new TypeError(`staged GUID ${key} is owned by both ${existing.id} and ${owner.id}`);
+      }
+      ownerByGuid.set(key, owner);
+    }
+  }
+
+  const snapshots = new Map<string, ScriptablePackAssetSnapshot>();
+  const builds = new Map<string, Promise<Result<void, ScriptablePackSnapshotError>>>();
+
+  const sourceFor = (stack: readonly string[]): ScriptablePackAssetSnapshotSource => ({
+    async readByGuid(guid) {
+      const key = AssetGuid.format(guid).toLowerCase();
+      const cached = snapshots.get(key);
+      if (cached !== undefined) return ok(structuredClone(cached));
+      const owner = ownerByGuid.get(key);
+      if (owner === undefined) {
+        if (options.fallback !== undefined) return options.fallback.readByGuid(guid);
+        return err(
+          new AssetError({
+            code: 'asset-not-imported',
+            expected: 'a staged local owner or explicit prebuilt fallback for the requested GUID',
+            hint: 'declare the local ScriptablePack output or configure a prebuilt asset authority',
+          }),
+        );
+      }
+      if (stack.includes(owner.id)) return err(cycleError(stack, owner.id, key));
+
+      let building = builds.get(owner.id);
+      if (building === undefined) {
+        building = (async () => {
+          const built = await owner.build(sourceFor([...stack, owner.id]));
+          if (!built.ok) {
+            builds.delete(owner.id);
+            return built;
+          }
+          const next = new Map<string, ScriptablePackAssetSnapshot>();
+          for (const output of built.value) {
+            const outputGuid = AssetGuid.format(output.guid).toLowerCase();
+            if (ownerByGuid.get(outputGuid) !== owner) {
+              builds.delete(owner.id);
+              return err(missingOutputError(owner.id, outputGuid));
+            }
+            next.set(outputGuid, {
+              asset: structuredClone(output.asset),
+              generation: options.generation,
+              digest: output.digest ?? (await assetDigest(output.asset)),
+            });
+          }
+          for (const declared of owner.guids) {
+            const declaredGuid = AssetGuid.format(declared).toLowerCase();
+            if (!next.has(declaredGuid)) {
+              builds.delete(owner.id);
+              return err(missingOutputError(owner.id, declaredGuid));
+            }
+          }
+          for (const [outputGuid, snapshot] of next) snapshots.set(outputGuid, snapshot);
+          return ok(undefined);
+        })();
+        builds.set(owner.id, building);
+      }
+      const built = await building;
+      if (!built.ok) return built;
+      const staged = snapshots.get(key);
+      return staged === undefined
+        ? err(missingOutputError(owner.id, key))
+        : ok(structuredClone(staged));
+    },
+  });
+
+  return sourceFor([]);
+}