@forgeax/engine-assets-runtime 0.1.4 → 0.1.7

package/src/index.ts

@@ -1,22 +1,189 @@
+// @forgeax/engine-assets-runtime -- public API barrel.
+//
+// Tier 2.1 package extracted from @forgeax/engine-runtime
+// (feat-20260705-runtime-tier2-decomposition M1). The asset registry, loader
+// registry, GUID resolution, default-loader wiring, builtin handles, and the
+// dynamic-texture / mipmap helpers live here; the runtime package injects the
+// post-spawn hook + extra loaders (audio / video) at the createRenderer
+// assembly point.
+//
+// w14 public surface: exports exactly the asset-cluster symbols that the
+// runtime package (src + __tests__) consumes plus what the pre-w14 runtime
+// barrel re-exported to external consumers. Downstream apps repoint to this
+// package in w15 (the runtime barrel no longer re-exports any asset symbol).
+
 export type {
-  AssetDecoder,
-  AssetDecoderInput,
-  AssetDecoderLease,
-  AssetKind,
-  AssetLoadError,
-  AssetPublicationTuple,
-  CatalogEntry,
-  PackV2,
-  Result,
+  AnimationClip,
+  AnimationGraph,
+  AudioClipAsset,
+  EquirectAsset,
+  FontAsset,
+  MaterialAsset,
+  ParticleEffectAsset,
+  RenderPipelineAsset,
+  SamplerAsset,
+  SceneAsset,
+  SkeletonAsset,
+  SkinAsset,
+  TextureAsset,
+  TilesetAsset,
+  VideoAsset,
 } from '@forgeax/engine-types';
-
 export { defineAssetKind } from './asset-kind.js';
-export { type CatalogListener, type CatalogSource, createCatalogSource } from './catalog-source.js';
+// ─── AssetRegistry + Asset / MeshAsset type aliases ─────────────────────────
+export type {
+  Asset,
+  CatalogReconcileError,
+  CatalogReconcileResult,
+  MeshAsset,
+} from './asset-registry';
+export { AssetRegistry } from './asset-registry';
+// ─── Process-static builtin payload registry + vertex-layout SSOT ───────────
 export {
-  type AssetLoadOptions,
-  type AssetRegistry,
-  type AssetRegistryOptions,
-  type AssetRegistrySnapshot,
-  type AssetRegistrySnapshotCounters,
+  BUILTIN_BASE,
+  BUILTIN_CUBE,
+  BUILTIN_CYLINDER,
+  BUILTIN_NINESLICE_QUAD,
+  BUILTIN_QUAD,
+  BUILTIN_SPHERE,
+  BUILTIN_TRIANGLE,
+  BuiltinAssetRegistry,
+} from './builtin-asset-registry';
+export { type CatalogListener, type CatalogSource, createCatalogSource } from './catalog-source';
+// ─── Runtime image byte decoder (tweak-20260714 M1) ──────────────────────────
+export { decodeImageBytes } from './decode-image-bytes';
+// ─── Dynamic per-frame texture store ────────────────────────────────────────
+export {
+  adaptDynamicTextureDevice,
+  type DynamicTextureDevice,
+  DynamicTextureStore,
+} from './dynamic-texture-store';
+// ─── Asset cluster error model (closed union + classes) ─────────────────────
+export type {
+  AssetRuntimeError,
+  AssetRuntimeErrorCode,
+  MaterialResolvedEmptyPassesDetail,
+  SceneCollectAssetGuidUnresolvedDetail,
+  SceneCollectEntityRefOutOfClosureDetail,
+} from './errors/asset';
+export {
+  MaterialResolvedEmptyPassesError,
+  MeshBinAssetError,
+  MeshSsboCapacityExceededError,
+  MeshSsboCeilingReachedError,
+  SceneCollectAssetGuidUnresolvedError,
+  SceneCollectEntityRefOutOfClosureError,
+} from './errors/asset';
+// ─── Builtin mesh handles (re-exported by asset-registry from ./handles) ─────
+export {
+  builtinMeshGuid,
+  HANDLE_CUBE,
+  HANDLE_CYLINDER,
+  HANDLE_NINESLICE_QUAD,
+  HANDLE_QUAD,
+  HANDLE_SPHERE,
+  HANDLE_TRIANGLE,
+} from './handles';
+// The five-action runtime registry is distinct from the legacy authoring
+// AssetRegistry class above. Keep its resolver on the public package boundary
+// so render/VFX hosts never reach through `/internal` to inspect loaded assets.
+export {
+  type AssetRegistry as RuntimeAssetRegistry,
+  type AssetRegistryResolver,
   createAssetRegistry,
+  getAssetRegistryResolver,
 } from './internal/load-asset.js';
+// ─── Loader-injection surface ───────────────────────────────────────────────
+export { LoaderRegistry } from './loader-registry';
+// ─── Default loader tables + individual loaders (pre-w14 consumer face) ──────
+export {
+  animationClipLoader,
+  animationGraphLoader,
+  audioLoader,
+  INLINE_PACK_LOADERS,
+  materialLoader,
+  meshLoader,
+  particleEffectLoader,
+  renderPipelineLoader,
+  sceneLoader,
+  skeletonLoader,
+  skinLoader,
+  tilesetLoader,
+} from './loaders/inline-pack';
+// ─── Mesh binary container decode ───────────────────────────────────────────
+export {
+  type UnpackedMeshBin,
+  unpackMeshBinV4,
+} from './loaders/mesh-bin';
+export {
+  equirectLoader,
+  fontLoader,
+  PACK_ARTIFACT_LOADERS,
+  renderPipelineLoader as renderPipelineArtifactLoader,
+  textureLoader,
+  tilesetLoader as tilesetArtifactLoader,
+} from './loaders/pack-artifact';
+export { MaterialGenerationCache } from './material/generation-cache';
+export { inspectMaterialRuntime, type MaterialRuntimeInfo } from './material/inspection';
+export {
+  createMaterialLoader,
+  type MaterialLoadError,
+  type MaterialLoadErrorCode,
+  type MaterialLoadErrorDetail,
+  type MaterialLoaderOptions,
+  type MaterialLoadRequest,
+  type MaterialPublication,
+  type MaterialReady,
+} from './material/loader';
+export {
+  installMaterialReadyShaders,
+  materialParametersToParamSchema,
+  runtimeMaterialShaderId,
+} from './material/runtime-shader';
+// ─── Mipmap generation helpers ──────────────────────────────────────────────
+export {
+  blitMipmapsSync,
+  getOrCreateMipmapPipeline,
+  type MipmapBlitDevice,
+  type MipmapShaderModuleFactory,
+  mipmapCacheSize,
+  numMipLevels,
+} from './mipmap-generator';
+// ─── Register-time payload validation ───────────────────────────────────────
+export { type TilesetValidateOptions, validateTilesetPayload } from './payload-validate';
+export { assetLoaderPlugin, assetsPlugin, packLoaderPlugin } from './plugin';
+export {
+  createRuntimeAssetEvidenceAdapter,
+  type RuntimeEvidenceSource,
+} from './registry/asset-evidence';
+export { CatalogReplica, type CatalogReplicaSnapshot } from './registry/catalog-state';
+export type { PostSpawnHook, SkinJointResolver } from './registry/instantiate';
+// ─── Scene instantiate collaboration contract types (D-1 injected hook) ─────
+export { buildSceneChildContext } from './registry/instantiate';
+export { loadMaterialReadyByGuid } from './registry/load-by-guid';
+export {
+  compareScenePublicationFences,
+  createScenePublicationFence,
+  observeScenePublication,
+  parseScenePublicationFence,
+  SCENE_PUBLICATION_FENCE_SCHEMA,
+  SCENE_PUBLICATION_RECOVERY_ACTIONS,
+  type ScenePublicationFence,
+  type ScenePublicationFenceError,
+  type ScenePublicationFencePhase,
+  type ScenePublicationObservation,
+  scenePublicationFenceFromCatalog,
+} from './registry/scene-publication-fence';
+// ─── Handle-to-payload resolution ───────────────────────────────────────────
+export { resolveAssetHandle, walkMaterialPassesOverSharedRefs } from './resolve-asset-handle';
+export {
+  type ResolvedTilesetRuntime,
+  resolveTilesetRuntime,
+  type TilesetAtlasLookup,
+  type TilesetRuntimeError,
+  type TilesetRuntimeErrorCode,
+} from './resolve-tileset-runtime';
+// Public scene-pack boundary: editor/play hosts reuse the engine's canonical
+// refs-index -> SceneAsset reconstruction when refreshing a saved SceneAsset.
+export { parseScenePayload } from './scene-payload';
+export { createDefaultLoaderRegistry, wireDefaultLoaders } from './wire-default-loaders';

package/src/internal.ts

@@ -1,5 +1,6 @@
 export { CatalogSession } from './internal/catalog-session.js';
 export {
+  type AssetRegistry,
   type AssetRegistryResolver,
   getAssetRegistryResolver,
 } from './internal/load-asset.js';

package/src/loader-registry.ts

@@ -0,0 +1,157 @@
+// @forgeax/engine-assets-runtime - LoaderRegistry (feat-20260603-asset-import-loader-injection M1 / w2).
+//
+// The runtime half of the engine's third DIP instance (after RHI + Console):
+// an injectable table that maps `asset.kind` -> a `Loader` (the contract SSOT
+// lives in `@forgeax/engine-types`, plan-strategy D-2). `AssetRegistry` holds
+// one of these (constructor-injected, D-7) and dispatches `loadByGuid` through
+// `get(kind)` instead of a hardcoded `if (kind === ...)` chain (D-1).
+//
+// Shape mirrors the Console `Registry` (packages/console/src/registry.ts)
+// register/lookup pattern (research Finding 8), with one deliberate
+// difference: the injected unit here is an **object** `{ kind, load }`, not a
+// bare function, because a "one kind -> one loader" dispatch table is the
+// natural shape (plan-strategy D-1 alt-B rejection).
+//
+// Fail-fast semantics (charter P3): `register` throws on a malformed loader
+// or duplicate kind at wire time, so one canonical owner cannot be silently
+// replaced by a later seed table.
+
+import type { ArtifactDescriptor, LoadContext, Loader } from '@forgeax/engine-types';
+
+export interface PackArtifactInput {
+  readonly descriptor: ArtifactDescriptor;
+  readonly bytes: Uint8Array;
+}
+
+export interface PackLoaderInput {
+  readonly guid: string;
+  readonly kind: string;
+  readonly payload: Record<string, unknown>;
+  readonly refs: readonly string[];
+  readonly artifacts: Readonly<Record<string, PackArtifactInput>>;
+}
+
+export interface PackLoader {
+  readonly kind: string;
+  load(input: PackLoaderInput, ctx: LoadContext): unknown;
+}
+
+export type PackLoadResult =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false; readonly error: unknown };
+
+/**
+ * Injectable `asset.kind` -> {@link Loader} table held by `AssetRegistry`.
+ *
+ * @example Wire + dispatch (host side)
+ * ```ts
+ * import { LoaderRegistry, wireDefaultLoaders } from '@forgeax/engine-assets-runtime';
+ * const loaders = new LoaderRegistry();
+ * wireDefaultLoaders(loaders);
+ * const meshLoader = loaders.get('mesh'); // Loader | undefined
+ * ```
+ */
+export class LoaderRegistry {
+  // feat-20260623 M4 / w13: the Map stores Loader<unknown> so host custom kinds
+  // (Loader<MyPayload>) are accepted. The P in Loader<P> is covariant (output
+  // only: load() returns P), so Loader<Asset> is assignable to Loader<unknown>.
+  private readonly loaders = new Map<string, Loader<unknown>>();
+  private readonly packLoaders = new Map<string, PackLoader>();
+
+  /**
+   * Register a loader for its `loader.kind`. Fail-fast on a malformed loader
+   * (charter P3); rejects a repeated kind so the canonical owner cannot be replaced.
+   *
+   * @param loader the `{ kind, load }` object to register.
+   * @throws TypeError when `loader.kind` is empty or `loader.load` is not a
+   *   function — a wire-time misconfiguration the host must fix.
+   */
+  register(loader: Loader<unknown>): () => void {
+    if (typeof loader.kind !== 'string' || loader.kind.length === 0) {
+      throw new TypeError(
+        `LoaderRegistry.register: loader.kind must be a non-empty string (got ${JSON.stringify(loader.kind)})`,
+      );
+    }
+    if (typeof loader.load !== 'function') {
+      throw new TypeError(
+        `LoaderRegistry.register: loader.load must be a function for kind "${loader.kind}"`,
+      );
+    }
+    if (this.loaders.has(loader.kind)) {
+      throw new TypeError(`LoaderRegistry.register: duplicate loader kind "${loader.kind}"`);
+    }
+    this.loaders.set(loader.kind, loader);
+    return () => {
+      if (this.loaders.get(loader.kind) === loader) this.loaders.delete(loader.kind);
+    };
+  }
+
+  registerPackLoader(loader: PackLoader): () => void {
+    if (typeof loader.kind !== 'string' || loader.kind.length === 0) {
+      throw new TypeError('LoaderRegistry.registerPackLoader: kind must be non-empty');
+    }
+    if (typeof loader.load !== 'function') {
+      throw new TypeError(
+        `LoaderRegistry.registerPackLoader: load must be a function for ${loader.kind}`,
+      );
+    }
+    if (this.packLoaders.has(loader.kind)) {
+      throw new TypeError(
+        `LoaderRegistry.registerPackLoader: duplicate loader kind "${loader.kind}"`,
+      );
+    }
+    this.packLoaders.set(loader.kind, loader);
+    return () => {
+      if (this.packLoaders.get(loader.kind) === loader) this.packLoaders.delete(loader.kind);
+    };
+  }
+
+  async loadPack(input: PackLoaderInput, ctx: LoadContext): Promise<PackLoadResult> {
+    const packLoader = this.packLoaders.get(input.kind);
+    if (packLoader !== undefined) {
+      const output = await packLoader.load(input, ctx);
+      if (isPackLoadResult(output)) return output;
+      return { ok: true, value: output };
+    }
+    const loader = this.loaders.get(input.kind);
+    if (loader === undefined) {
+      return { ok: false, error: new Error(`no loader registered for ${input.kind}`) };
+    }
+    if (loader.loadPack !== undefined) {
+      const output = await loader.loadPack(input, ctx);
+      if (isPackLoadResult(output)) return output;
+      return { ok: true, value: output };
+    }
+    const output = await loader.load(input.payload, input.refs, ctx);
+    if (isPackLoadResult(output)) return output;
+    return { ok: true, value: output };
+  }
+
+  /**
+   * Look up the loader registered for `kind`. Returns `undefined` when no
+   * loader is wired — the `AssetRegistry` consumer maps that to a structured
+   * `AssetError(code='loader-not-registered')` with the registered kinds in
+   * `.detail` (charter P3).
+   */
+  get(kind: string): Loader<unknown> | undefined {
+    return this.loaders.get(kind);
+  }
+
+  /**
+   * The kinds currently wired, in insertion order. Fed into the
+   * `loader-not-registered` error `.detail.registeredKinds` so AI users see
+   * exactly what is injectable.
+   */
+  registeredKinds(): readonly string[] {
+    return [...this.loaders.keys()];
+  }
+}
+
+function isPackLoadResult(value: unknown): value is PackLoadResult {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'ok' in value &&
+    typeof (value as { ok?: unknown }).ok === 'boolean'
+  );
+}