@forgeax/engine-assets-runtime 0.0.0-dev.8d955ade1c79

package/src/index.ts

@@ -0,0 +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 {
+  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';
+// ─── 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 {
+  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/artifact-cache.ts

@@ -0,0 +1,65 @@
+import type { AssetLoadError, Result } from '@forgeax/engine-types';
+
+export interface ArtifactCacheSnapshot {
+  readonly entries: number;
+  readonly pending: number;
+  readonly hits: number;
+  readonly misses: number;
+}
+
+export class ArtifactCache {
+  private readonly values = new Map<string, Uint8Array>();
+  private readonly pending = new Map<string, Promise<Result<Uint8Array, AssetLoadError>>>();
+  private hits = 0;
+  private misses = 0;
+
+  read(
+    contentAddress: string,
+    reader: () => Promise<Result<Uint8Array, AssetLoadError>>,
+  ): Promise<Result<Uint8Array, AssetLoadError>> {
+    const value = this.values.get(contentAddress);
+    if (value !== undefined) {
+      this.hits += 1;
+      return Promise.resolve({ ok: true, value: new Uint8Array(value) } as Result<
+        Uint8Array,
+        AssetLoadError
+      >);
+    }
+    const pending = this.pending.get(contentAddress);
+    if (pending !== undefined) {
+      this.hits += 1;
+      return pending;
+    }
+    this.misses += 1;
+    const request = Promise.resolve()
+      .then(reader)
+      .then((result) => {
+        if (result.ok) this.values.set(contentAddress, new Uint8Array(result.value));
+        return result;
+      })
+      .finally(() => {
+        if (this.pending.get(contentAddress) === request) this.pending.delete(contentAddress);
+      });
+    this.pending.set(contentAddress, request);
+    return request;
+  }
+
+  clear(contentAddress?: string): void {
+    if (contentAddress === undefined) {
+      this.values.clear();
+      this.pending.clear();
+      return;
+    }
+    this.values.delete(contentAddress);
+    this.pending.delete(contentAddress);
+  }
+
+  snapshot(): ArtifactCacheSnapshot {
+    return Object.freeze({
+      entries: this.values.size,
+      pending: this.pending.size,
+      hits: this.hits,
+      misses: this.misses,
+    });
+  }
+}

package/src/internal/asset-graph.ts

@@ -0,0 +1,420 @@
+import type { AssetLoadError, Result } from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+import { freezeRuntimePayload } from './immutable-payload.js';
+
+export interface AssetGraphValue<P> {
+  readonly value: P;
+  readonly refs: readonly string[];
+}
+
+export interface AssetGraphOptions<
+  P extends { readonly value: unknown; readonly refs: readonly string[] },
+> {
+  readonly read: (guid: string, signal: AbortSignal) => Promise<Result<P, AssetLoadError>>;
+  readonly maxConcurrentReads?: number;
+}
+
+export interface AssetGraphCounters {
+  readonly loads: number;
+  readonly cacheHits: number;
+  readonly readErrors: number;
+  readonly noChange: number;
+  readonly listenerFailures: number;
+}
+
+export interface AssetGraphSnapshot {
+  readonly epoch: number;
+  readonly ready: readonly string[];
+  readonly pending: number;
+  readonly resources: number;
+  readonly sccs: readonly (readonly string[])[];
+  readonly counters: AssetGraphCounters;
+}
+
+type GraphResult<P> = Result<P, AssetLoadError>;
+type GraphListener = (snapshot: AssetGraphSnapshot) => void;
+
+function cancelled(guid: string): AssetLoadError {
+  return {
+    code: 'asset-load-cancelled',
+    expected: 'the request AbortSignal to remain live until asset closure completes',
+    hint: 'retry with a live AbortSignal when the request is still needed',
+    detail: { guid },
+  };
+}
+
+function disposed(scopeId = 'asset-runtime'): AssetLoadError {
+  return {
+    code: 'asset-runtime-disposed',
+    expected: 'an active asset runtime scope',
+    hint: 'obtain a new Registry from the current realm',
+    detail: { scopeId },
+  };
+}
+
+function superseded(guid: string, generation: number): AssetLoadError {
+  return {
+    code: 'asset-superseded',
+    expected: 'the load ticket to remain current until promotion',
+    hint: 'load the current publication after the Catalog change',
+    detail: { guid, generation },
+  };
+}
+
+function thrown(guid: string): AssetLoadError {
+  return {
+    code: 'asset-decode-failed',
+    expected: 'the graph reader to return a Result',
+    hint: 'repair the owner reader and retry the current publication',
+    detail: { guid, kind: 'asset-graph-reader' },
+  };
+}
+
+function freezeSnapshot(snapshot: AssetGraphSnapshot): AssetGraphSnapshot {
+  return Object.freeze({
+    ...snapshot,
+    ready: Object.freeze([...snapshot.ready]),
+    sccs: Object.freeze(snapshot.sccs.map((scc) => Object.freeze([...scc]))),
+    counters: Object.freeze({ ...snapshot.counters }),
+  });
+}
+
+export class AssetGraph<P extends { readonly value: unknown; readonly refs: readonly string[] }> {
+  private readonly read: AssetGraphOptions<P>['read'];
+  private readonly limit: number;
+  private readonly ready = new Map<string, P>();
+  private readonly forward = new Map<string, Set<string>>();
+  private readonly reverse = new Map<string, Set<string>>();
+  private readonly reads = new Map<string, Promise<GraphResult<P>>>();
+  private readonly requests = new Map<string, Promise<GraphResult<P>>>();
+  private readonly listeners = new Set<GraphListener>();
+  private readonly sccs: (readonly string[])[] = [];
+  private activeReads = 0;
+  private readWaiters: (() => void)[] = [];
+  private disposed = false;
+  private epoch = 0;
+  private counters: AssetGraphCounters = {
+    loads: 0,
+    cacheHits: 0,
+    readErrors: 0,
+    noChange: 0,
+    listenerFailures: 0,
+  };
+  private currentSnapshot: AssetGraphSnapshot;
+
+  constructor(options: AssetGraphOptions<P>) {
+    this.read = options.read;
+    this.limit = Math.max(1, Math.floor(options.maxConcurrentReads ?? 8));
+    this.currentSnapshot = freezeSnapshot({
+      epoch: 0,
+      ready: [],
+      pending: 0,
+      resources: 0,
+      sccs: [],
+      counters: this.counters,
+    });
+  }
+
+  load(guid: string, signal = new AbortController().signal): Promise<GraphResult<P>> {
+    const canonicalGuid = guid.toLowerCase();
+    if (this.disposed) return Promise.resolve(err(disposed()));
+    if (signal.aborted) return Promise.resolve(err(cancelled(canonicalGuid)));
+    const cached = this.ready.get(canonicalGuid);
+    if (cached !== undefined) {
+      this.counters = {
+        ...this.counters,
+        cacheHits: this.counters.cacheHits + 1,
+        noChange: this.counters.noChange + 1,
+      };
+      this.publish();
+      return Promise.resolve(ok(cached));
+    }
+    const existing = this.requests.get(canonicalGuid);
+    if (existing !== undefined) {
+      this.counters = { ...this.counters, cacheHits: this.counters.cacheHits + 1 };
+      return existing;
+    }
+    this.counters = { ...this.counters, loads: this.counters.loads + 1 };
+    const ticketEpoch = this.epoch;
+    const request = this.loadClosure(canonicalGuid, signal, ticketEpoch).finally(() => {
+      if (this.requests.get(canonicalGuid) === request) this.requests.delete(canonicalGuid);
+      this.publish();
+    });
+    this.requests.set(canonicalGuid, request);
+    this.publish();
+    return request;
+  }
+
+  invalidate(guid: string): readonly string[] {
+    const affected = this.collectAffected([guid.toLowerCase()]);
+    this.drop(affected);
+    this.epoch += 1;
+    this.publish();
+    return [...affected].sort();
+  }
+
+  invalidateForCatalogChange(guids?: readonly string[]): void {
+    if (this.disposed) return;
+    const affected =
+      guids === undefined || guids.length === 0
+        ? new Set([...this.ready.keys(), ...this.requests.keys(), ...this.reads.keys()])
+        : this.collectAffected(guids.map((item) => item.toLowerCase()));
+    this.drop(affected);
+    this.epoch += 1;
+    this.publish();
+  }
+
+  subscribe(listener: GraphListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  snapshot(): AssetGraphSnapshot {
+    return this.currentSnapshot;
+  }
+
+  lookup(guid: string): P['value'] | undefined {
+    return this.ready.get(guid.toLowerCase())?.value;
+  }
+
+  guidOf(value: P['value']): string | undefined {
+    for (const [guid, entry] of this.ready) {
+      if (entry.value === value) return guid;
+    }
+    return undefined;
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.epoch += 1;
+    this.ready.clear();
+    this.forward.clear();
+    this.reverse.clear();
+    this.reads.clear();
+    const waiters = this.readWaiters;
+    this.readWaiters = [];
+    for (const resolve of waiters) resolve();
+    this.publish();
+  }
+
+  private async loadClosure(
+    root: string,
+    signal: AbortSignal,
+    ticketEpoch: number,
+  ): Promise<GraphResult<P>> {
+    const values = new Map<string, P>();
+    const visiting = new Set<string>();
+    const visited = new Set<string>();
+    const group = new Set<string>();
+    const result = await this.visit(root, signal, visiting, visited, values, group);
+    if (!result.ok) return result;
+    if (this.disposed) return err(disposed());
+    if (signal.aborted) return err(cancelled(root));
+    if (ticketEpoch !== this.epoch) return err(superseded(root, ticketEpoch));
+    for (const [guid, value] of values) this.promote(guid, value);
+    this.recordScc();
+    return ok(values.get(root) as P);
+  }
+
+  private async visit(
+    guid: string,
+    signal: AbortSignal,
+    visiting: Set<string>,
+    visited: Set<string>,
+    values: Map<string, P>,
+    group: Set<string>,
+  ): Promise<GraphResult<P>> {
+    if (visiting.has(guid)) {
+      group.add(guid);
+      return ok({ value: undefined as unknown as P, refs: [] } as unknown as P);
+    }
+    if (visited.has(guid)) return ok(values.get(guid) as P);
+    const cached = this.ready.get(guid);
+    if (cached !== undefined) {
+      values.set(guid, cached);
+      visited.add(guid);
+      return ok(cached);
+    }
+    visiting.add(guid);
+    const read = await this.readOnce(guid, signal);
+    if (!read.ok) {
+      visiting.delete(guid);
+      return read;
+    }
+    values.set(guid, read.value);
+    group.add(guid);
+    this.link(guid, read.value.refs);
+    for (const ref of read.value.refs) {
+      const child = await this.visit(ref, signal, visiting, visited, values, group);
+      if (!child.ok) {
+        visiting.delete(guid);
+        return err({
+          code: 'asset-dependency-failed',
+          expected: 'every referenced asset to load successfully',
+          hint: 'repair the dependency publication and retry the root asset',
+          detail: { guid, dependencyGuid: ref },
+        });
+      }
+    }
+    visiting.delete(guid);
+    visited.add(guid);
+    return ok(read.value);
+  }
+
+  private readOnce(guid: string, signal: AbortSignal): Promise<GraphResult<P>> {
+    const existing = this.reads.get(guid);
+    if (existing !== undefined) return existing;
+    const request = this.withPermit(async () => {
+      if (this.disposed) return err(disposed());
+      if (signal.aborted) return err(cancelled(guid));
+      try {
+        const result = await this.read(guid, signal);
+        if (signal.aborted) return err(cancelled(guid));
+        if (!result.ok)
+          this.counters = { ...this.counters, readErrors: this.counters.readErrors + 1 };
+        return result;
+      } catch {
+        this.counters = { ...this.counters, readErrors: this.counters.readErrors + 1 };
+        return err(thrown(guid));
+      }
+    });
+    this.reads.set(guid, request);
+    void request.finally(() => {
+      if (this.reads.get(guid) === request) this.reads.delete(guid);
+    });
+    return request;
+  }
+
+  private async withPermit<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.activeReads >= this.limit) {
+      await new Promise<void>((resolve) => this.readWaiters.push(resolve));
+    }
+    this.activeReads += 1;
+    try {
+      return await operation();
+    } finally {
+      this.activeReads -= 1;
+      this.readWaiters.shift()?.();
+    }
+  }
+
+  private link(guid: string, refs: readonly string[]): void {
+    const previous = this.forward.get(guid) ?? new Set<string>();
+    for (const ref of previous) this.reverse.get(ref)?.delete(guid);
+    const next = new Set(refs.map((ref) => ref.toLowerCase()));
+    this.forward.set(guid, next);
+    for (const ref of next) {
+      const dependents = this.reverse.get(ref) ?? new Set<string>();
+      dependents.add(guid);
+      this.reverse.set(ref, dependents);
+    }
+  }
+
+  private collectAffected(guids: readonly string[]): Set<string> {
+    const affected = new Set<string>();
+    const queue = [...guids];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (current === undefined || affected.has(current)) continue;
+      affected.add(current);
+      for (const dependent of this.reverse.get(current) ?? []) queue.push(dependent);
+    }
+    return affected;
+  }
+
+  private drop(affected: ReadonlySet<string>): void {
+    for (const item of affected) {
+      for (const ref of this.forward.get(item) ?? []) this.reverse.get(ref)?.delete(item);
+      for (const dependent of this.reverse.get(item) ?? []) {
+        this.forward.get(dependent)?.delete(item);
+      }
+    }
+    for (const item of affected) {
+      this.ready.delete(item);
+      this.requests.delete(item);
+      this.reads.delete(item);
+      this.forward.delete(item);
+      this.reverse.delete(item);
+    }
+    this.sccs.splice(0, this.sccs.length);
+  }
+
+  private promote(guid: string, value: P): void {
+    if (value === undefined) return;
+    this.ready.set(
+      guid,
+      Object.freeze({
+        ...value,
+        value: freezeRuntimePayload(value.value),
+        refs: Object.freeze([...value.refs]),
+      }) as P,
+    );
+  }
+
+  private recordScc(): void {
+    const indexByGuid = new Map<string, number>();
+    const lowByGuid = new Map<string, number>();
+    const stack: string[] = [];
+    const onStack = new Set<string>();
+    let nextIndex = 0;
+    const components: string[][] = [];
+    const visit = (guid: string): void => {
+      indexByGuid.set(guid, nextIndex);
+      lowByGuid.set(guid, nextIndex);
+      nextIndex += 1;
+      stack.push(guid);
+      onStack.add(guid);
+      for (const ref of this.forward.get(guid) ?? []) {
+        if (!indexByGuid.has(ref)) {
+          visit(ref);
+          lowByGuid.set(guid, Math.min(lowByGuid.get(guid) ?? 0, lowByGuid.get(ref) ?? 0));
+        } else if (onStack.has(ref)) {
+          lowByGuid.set(guid, Math.min(lowByGuid.get(guid) ?? 0, indexByGuid.get(ref) ?? 0));
+        }
+      }
+      if (lowByGuid.get(guid) !== indexByGuid.get(guid)) return;
+      const component: string[] = [];
+      let member: string | undefined;
+      do {
+        member = stack.pop();
+        if (member === undefined) break;
+        onStack.delete(member);
+        component.push(member);
+      } while (member !== guid);
+      if (component.length > 1 || this.forward.get(guid)?.has(guid) === true)
+        components.push(component.sort());
+    };
+    for (const guid of this.forward.keys()) if (!indexByGuid.has(guid)) visit(guid);
+    this.sccs.splice(
+      0,
+      this.sccs.length,
+      ...components.map((component) => Object.freeze(component)),
+    );
+  }
+
+  private publish(): void {
+    this.currentSnapshot = freezeSnapshot({
+      epoch: this.epoch,
+      ready: [...this.ready.keys()].sort(),
+      pending: this.requests.size + this.reads.size,
+      resources: this.ready.size,
+      sccs: this.sccs,
+      counters: this.counters,
+    });
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(this.currentSnapshot);
+      } catch {
+        this.counters = {
+          ...this.counters,
+          listenerFailures: Math.min(1024, this.counters.listenerFailures + 1),
+        };
+        this.currentSnapshot = freezeSnapshot({
+          ...this.currentSnapshot,
+          counters: this.counters,
+        });
+      }
+    }
+  }
+}