@aura3d/assets 1.3.3 → 1.4.1

package/src/AssetLoader.ts

@@ -1,36 +0,0 @@
-import type { LoadContext } from "./LoadContext";
-
-export interface AssetLoadRequest {
-  readonly url: string;
-  readonly type?: string;
-  readonly signal?: AbortSignal;
-  readonly onProgress?: (event: AssetLoadProgress) => void;
-}
-
-export interface AssetLoadProgress {
-  readonly url: string;
-  readonly phase: "document" | "buffer" | "complete";
-  readonly loadedBytes: number;
-  readonly totalBytes?: number;
-}
-
-export interface AssetLoader<T = unknown> {
-  readonly type: string;
-  canLoad(request: AssetLoadRequest): boolean;
-  dependencies?(request: AssetLoadRequest, context: LoadContext): Promise<readonly string[]> | readonly string[];
-  load(request: AssetLoadRequest, context: LoadContext): Promise<T> | T;
-  dispose?(asset: T): void | Promise<void>;
-}
-
-export class AssetLoadError extends Error {
-  readonly url: string;
-  readonly dependencyChain: readonly string[];
-
-  constructor(message: string, url: string, dependencyChain: readonly string[] = [], cause?: unknown) {
-    super(message);
-    this.name = "AssetLoadError";
-    this.url = url;
-    this.dependencyChain = dependencyChain;
-    this.cause = cause;
-  }
-}

package/src/AssetManager.ts

@@ -1,211 +0,0 @@
-import { AssetCache } from "./AssetCache";
-import { AssetDependencyGraph } from "./AssetDependencyGraph";
-import { AssetHandle } from "./AssetHandle";
-import { AssetLoadError, type AssetLoadProgress, type AssetLoadRequest, type AssetLoader } from "./AssetLoader";
-import { AssetRegistry } from "./AssetRegistry";
-import { LoadContext } from "./LoadContext";
-
-export interface AssetManagerOptions {
-  readonly baseUrl?: string;
-  readonly retries?: number;
-  readonly retryDelayMs?: number;
-}
-
-export interface AssetLoadOptions {
-  readonly type?: string;
-  readonly signal?: AbortSignal;
-  readonly dependencyChain?: readonly string[];
-  readonly retries?: number;
-  readonly retryDelayMs?: number;
-  readonly onProgress?: (event: AssetLoadProgress) => void;
-}
-
-export class AssetManager {
-  readonly registry = new AssetRegistry();
-  readonly cache = new AssetCache();
-  readonly dependencies = new AssetDependencyGraph();
-
-  private readonly baseUrl: string;
-  private readonly defaultRetries: number;
-  private readonly defaultRetryDelayMs: number;
-  private nextId = 1;
-
-  constructor(options: AssetManagerOptions = {}) {
-    this.baseUrl = options.baseUrl ?? "";
-    this.defaultRetries = Math.max(0, Math.trunc(options.retries ?? 0));
-    this.defaultRetryDelayMs = Math.max(0, options.retryDelayMs ?? 0);
-  }
-
-  register(loader: AssetLoader): void {
-    this.registry.register(loader);
-  }
-
-  async load<T = unknown>(url: string, options: AssetLoadOptions = {}): Promise<AssetHandle<T>> {
-    const context = new LoadContext({
-      baseUrl: this.baseUrl,
-      signal: options.signal,
-      dependencyChain: options.dependencyChain,
-      manager: this
-    });
-    const resolvedUrl = context.resolve(url);
-    context.throwIfAborted(resolvedUrl);
-    const key = `${options.type ?? "auto"}:${resolvedUrl}`;
-
-    const cached = this.cache.get<T>(key);
-    if (cached) {
-      return cached.retain();
-    }
-
-    const inFlight = this.cache.getInFlight<T>(key);
-    if (inFlight) {
-      const handle = await this.awaitInFlight(inFlight, context, resolvedUrl);
-      return handle.retain();
-    }
-
-    const request: AssetLoadRequest = { url: resolvedUrl, type: options.type, signal: options.signal, onProgress: options.onProgress };
-    const loader = this.registry.find(request);
-
-    const promise = this.loadWithLoader<T>(loader, request, context.child(resolvedUrl), {
-      retries: Math.max(0, Math.trunc(options.retries ?? this.defaultRetries)),
-      retryDelayMs: Math.max(0, options.retryDelayMs ?? this.defaultRetryDelayMs)
-    });
-    this.cache.setInFlight(key, promise);
-    return promise;
-  }
-
-  async release<T>(handle: AssetHandle<T>): Promise<void> {
-    const remaining = await handle.release();
-    if (remaining > 0) {
-      return;
-    }
-
-    for (const dependencyId of this.dependencies.dependenciesOf(handle.id)) {
-      const dependencyKey = this.cache.keys().find((key) => this.cache.get(key)?.id === dependencyId);
-      const dependency = dependencyKey ? this.cache.get(dependencyKey) : undefined;
-      if (dependency && !dependency.disposed) {
-        await this.release(dependency);
-      }
-    }
-
-    const cacheKey = this.cache.keys().find((key) => this.cache.get(key)?.id === handle.id);
-    if (cacheKey) {
-      this.cache.delete(cacheKey);
-    }
-    this.dependencies.remove(handle.id);
-  }
-
-  private async loadWithLoader<T>(
-    loader: AssetLoader,
-    request: AssetLoadRequest,
-    context: LoadContext,
-    retry: { readonly retries: number; readonly retryDelayMs: number }
-  ): Promise<AssetHandle<T>> {
-    let attempt = 0;
-
-    while (true) {
-      context.throwIfAborted(request.url);
-      const dependencyHandles: Array<AssetHandle<unknown>> = [];
-
-      try {
-        const dependencyUrls = await loader.dependencies?.(request, context);
-
-        for (const dependencyUrl of dependencyUrls ?? []) {
-          context.throwIfAborted(request.url);
-          dependencyHandles.push(await context.loadDependency(dependencyUrl));
-        }
-
-        context.throwIfAborted(request.url);
-        const value = (await loader.load(request, context)) as T;
-        const handle = new AssetHandle<T>({
-          id: `asset-${this.nextId++}`,
-          url: request.url,
-          type: loader.type,
-          value,
-          dispose: (asset) => loader.dispose?.(asset)
-        });
-
-        this.dependencies.addNode(handle.id);
-        for (const dependency of dependencyHandles) {
-          this.dependencies.addDependency(handle.id, dependency.id);
-        }
-
-        return handle;
-      } catch (error) {
-        await this.releaseLoadedDependencies(dependencyHandles);
-
-        if (this.shouldRetry(error, context, attempt, retry.retries)) {
-          attempt += 1;
-          await this.waitForRetry(retry.retryDelayMs, context, request.url);
-          continue;
-        }
-
-        if (error instanceof AssetLoadError) {
-          throw error;
-        }
-
-        throw new AssetLoadError(`Failed to load asset ${request.url}`, request.url, context.dependencyChain, error);
-      }
-    }
-  }
-
-  private async releaseLoadedDependencies(dependencyHandles: readonly AssetHandle<unknown>[]): Promise<void> {
-    for (const dependency of [...dependencyHandles].reverse()) {
-      if (!dependency.disposed) {
-        await this.release(dependency);
-      }
-    }
-  }
-
-  private async awaitInFlight<T>(
-    promise: Promise<AssetHandle<T>>,
-    context: LoadContext,
-    url: string
-  ): Promise<AssetHandle<T>> {
-    if (!context.signal) {
-      return promise;
-    }
-
-    context.throwIfAborted(url);
-
-    return new Promise<AssetHandle<T>>((resolve, reject) => {
-      const abort = () => {
-        reject(new AssetLoadError("Asset load aborted", url, context.dependencyChain, context.signal?.reason));
-      };
-      context.signal?.addEventListener("abort", abort, { once: true });
-      promise.then(
-        (handle) => {
-          context.signal?.removeEventListener("abort", abort);
-          resolve(handle);
-        },
-        (error) => {
-          context.signal?.removeEventListener("abort", abort);
-          reject(error);
-        }
-      );
-    });
-  }
-
-  private shouldRetry(error: unknown, context: LoadContext, attempt: number, retries: number): boolean {
-    if (attempt >= retries) return false;
-    if (context.signal?.aborted) return false;
-    if (error instanceof AssetLoadError && error.message === "Asset load aborted") return false;
-    return true;
-  }
-
-  private async waitForRetry(delayMs: number, context: LoadContext, url: string): Promise<void> {
-    context.throwIfAborted(url);
-    if (delayMs === 0) return;
-
-    await new Promise<void>((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        context.signal?.removeEventListener("abort", abort);
-        resolve();
-      }, delayMs);
-      const abort = () => {
-        clearTimeout(timeout);
-        reject(new AssetLoadError("Asset load aborted", url, context.dependencyChain, context.signal?.reason));
-      };
-      context.signal?.addEventListener("abort", abort, { once: true });
-    });
-  }
-}

package/src/AssetRegistry.ts

@@ -1,44 +0,0 @@
-import type { AssetLoadRequest, AssetLoader } from "./AssetLoader";
-
-export class AssetRegistry {
-  private readonly loaders = new Map<string, AssetLoader>();
-
-  register(loader: AssetLoader): void {
-    if (this.loaders.has(loader.type)) {
-      throw new Error(`Asset loader type already registered: ${loader.type}`);
-    }
-
-    this.loaders.set(loader.type, loader);
-  }
-
-  unregister(type: string): boolean {
-    return this.loaders.delete(type);
-  }
-
-  get(type: string): AssetLoader {
-    const loader = this.loaders.get(type);
-    if (!loader) {
-      throw new Error(`No asset loader registered for type: ${type}`);
-    }
-
-    return loader;
-  }
-
-  find(request: AssetLoadRequest): AssetLoader {
-    if (request.type) {
-      return this.get(request.type);
-    }
-
-    for (const loader of this.loaders.values()) {
-      if (loader.canLoad(request)) {
-        return loader;
-      }
-    }
-
-    throw new Error(`No asset loader can load ${request.url}`);
-  }
-
-  list(): readonly string[] {
-    return [...this.loaders.keys()];
-  }
-}

package/src/AssetRenderDefaults.ts

@@ -1,36 +0,0 @@
-import type { CameraFrameViewport, PerspectiveCameraFrameOptions, RendererPostProcessOptions, RendererShadowOptions } from "@aura3d/rendering";
-import { createLightingDefault } from "@aura3d/rendering";
-
-export type AssetRenderLightingPreset = "studioProduct" | "outdoorDay" | "interiorGallery" | "gameNight";
-
-export interface AssetRenderDefaults {
-  readonly viewport: CameraFrameViewport;
-  readonly camera: "auto-frame";
-  readonly frame: PerspectiveCameraFrameOptions;
-  readonly lighting: AssetRenderLightingPreset;
-  readonly shadows: RendererShadowOptions;
-  readonly postprocess: RendererPostProcessOptions;
-}
-
-export const DEFAULT_ASSET_RENDER_VIEWPORT: CameraFrameViewport = {
-  width: 960,
-  height: 540
-};
-
-export function createAssetRenderDefaults(lighting: AssetRenderLightingPreset = "studioProduct"): AssetRenderDefaults {
-  const defaults = createLightingDefault(lighting);
-  return {
-    viewport: DEFAULT_ASSET_RENDER_VIEWPORT,
-    camera: "auto-frame",
-    frame: {
-      paddingRatio: 0.16,
-      yawRadians: -0.38,
-      pitchRadians: -0.16,
-      nearPadding: 0.18,
-      farPadding: 2.4
-    },
-    lighting,
-    shadows: defaults.shadow,
-    postprocess: defaults.postprocess
-  };
-}

package/src/AudioLoader.ts

@@ -1,41 +0,0 @@
-import type { AssetLoadRequest, AssetLoader } from "./AssetLoader";
-import type { LoadContext } from "./LoadContext";
-
-export interface AudioDecodeContext {
-  decodeAudioData(data: ArrayBuffer): Promise<AudioBuffer> | AudioBuffer;
-}
-
-export interface AudioAsset {
-  readonly url: string;
-  readonly buffer: AudioBuffer;
-}
-
-export class AudioLoader implements AssetLoader<AudioAsset> {
-  readonly type = "audio";
-
-  private readonly audioContext: AudioDecodeContext;
-
-  constructor(audioContext: AudioDecodeContext) {
-    this.audioContext = audioContext;
-  }
-
-  canLoad(request: AssetLoadRequest): boolean {
-    return /\.(?:mp3|wav|ogg|m4a|aac)(?:\?.*)?$/i.test(request.url);
-  }
-
-  async load(request: AssetLoadRequest, context: LoadContext): Promise<AudioAsset> {
-    context.throwIfAborted(request.url);
-
-    if (typeof fetch !== "function") {
-      throw new Error("AudioLoader requires fetch");
-    }
-
-    const response = await fetch(request.url, { signal: request.signal });
-    if (!response.ok) {
-      throw new Error(`Audio request failed with ${response.status}`);
-    }
-
-    const buffer = await this.audioContext.decodeAudioData(await response.arrayBuffer());
-    return { url: request.url, buffer };
-  }
-}

package/src/BlenderExportValidation.ts

@@ -1,227 +0,0 @@
-import { GLTFLoader, type GLTFAsset } from "./GLTFLoader";
-import { LoadContext } from "./LoadContext";
-
-export type BlenderExportValidationStatus = "pass" | "warn" | "fail";
-
-export interface BlenderExportFixtureManifest {
-  readonly schemaVersion: "blender-export-fixtures";
-  readonly sourceName: string;
-  readonly sourceRepository: string;
-  readonly sourceRevision: string;
-  readonly sourceReadme: string;
-  readonly sourceEvidence: string;
-  readonly fixtures: readonly BlenderExportFixture[];
-}
-
-export interface BlenderExportFixture {
-  readonly id: string;
-  readonly name: string;
-  readonly path: string;
-  readonly upstreamPath: string;
-  readonly sourceSha256: string;
-  readonly license: string;
-  readonly expectedGeneratorPattern: string;
-  readonly tags: readonly string[];
-}
-
-export interface BlenderExportFixtureInput extends BlenderExportFixture {
-  readonly sourceText: string;
-}
-
-export interface BlenderExportValidationReport {
-  readonly schemaVersion: "blender-export-validation";
-  readonly generatedAt: string;
-  readonly sourceManifest: Omit<BlenderExportFixtureManifest, "fixtures"> & { readonly fixtureCount: number };
-  readonly summary: Record<BlenderExportValidationStatus, number> & { readonly fixtureCount: number };
-  readonly fixtures: readonly BlenderExportValidationFixtureResult[];
-}
-
-export interface BlenderExportValidationFixtureResult {
-  readonly id: string;
-  readonly name: string;
-  readonly path: string;
-  readonly upstreamPath: string;
-  readonly sourceSha256: string;
-  readonly license: string;
-  readonly tags: readonly string[];
-  readonly generator: string;
-  readonly status: BlenderExportValidationStatus;
-  readonly metrics: {
-    readonly scenes: number;
-    readonly meshes: number;
-    readonly materials: number;
-    readonly textures: number;
-    readonly images: number;
-    readonly animations: number;
-    readonly renderables: number;
-  };
-  readonly diagnostics: readonly BlenderExportValidationDiagnostic[];
-}
-
-export interface BlenderExportValidationDiagnostic {
-  readonly code: string;
-  readonly severity: "info" | "warning" | "error";
-  readonly message: string;
-  readonly nextAction: string;
-}
-
-export async function createBlenderExportValidationReport(
-  manifest: BlenderExportFixtureManifest,
-  fixtureInputs: readonly BlenderExportFixtureInput[],
-  generatedAt = new Date().toISOString()
-): Promise<BlenderExportValidationReport> {
-  assertValidBlenderExportFixtureManifest(manifest);
-  const inputById = new Map(fixtureInputs.map((fixture) => [fixture.id, fixture]));
-  const fixtures = await Promise.all(manifest.fixtures.map(async (fixture) => validateFixture(fixture, inputById.get(fixture.id))));
-  return {
-    schemaVersion: "blender-export-validation",
-    generatedAt,
-    sourceManifest: {
-      schemaVersion: manifest.schemaVersion,
-      sourceName: manifest.sourceName,
-      sourceRepository: manifest.sourceRepository,
-      sourceRevision: manifest.sourceRevision,
-      sourceReadme: manifest.sourceReadme,
-      sourceEvidence: manifest.sourceEvidence,
-      fixtureCount: manifest.fixtures.length
-    },
-    summary: {
-      fixtureCount: fixtures.length,
-      pass: fixtures.filter((fixture) => fixture.status === "pass").length,
-      warn: fixtures.filter((fixture) => fixture.status === "warn").length,
-      fail: fixtures.filter((fixture) => fixture.status === "fail").length
-    },
-    fixtures
-  };
-}
-
-export function assertValidBlenderExportFixtureManifest(manifest: BlenderExportFixtureManifest): BlenderExportFixtureManifest {
-  if (manifest.schemaVersion !== "blender-export-fixtures") {
-    throw new Error("Blender export fixture manifest schemaVersion must be blender-export-fixtures");
-  }
-  if (!manifest.sourceRepository || !/^https:\/\/github\.com\/KhronosGroup\/Vulkan-Samples-Assets/.test(manifest.sourceRepository)) {
-    throw new Error("Blender export fixture manifest must reference KhronosGroup/Vulkan-Samples-Assets");
-  }
-  if (!/^[0-9a-f]{40}$/i.test(manifest.sourceRevision)) {
-    throw new Error("Blender export fixture manifest sourceRevision must be a git SHA");
-  }
-  if (manifest.fixtures.length < 2) {
-    throw new Error("Blender export validation requires multiple fixtures");
-  }
-  const ids = new Set<string>();
-  for (const fixture of manifest.fixtures) {
-    if (ids.has(fixture.id)) {
-      throw new Error(`Blender export fixture id is duplicated: ${fixture.id}`);
-    }
-    ids.add(fixture.id);
-    if (!fixture.path.endsWith(".gltf") && !fixture.path.endsWith(".glb")) {
-      throw new Error(`Blender export fixture ${fixture.id} must be a glTF or GLB file`);
-    }
-    if (!/^[0-9a-f]{64}$/i.test(fixture.sourceSha256)) {
-      throw new Error(`Blender export fixture ${fixture.id} sourceSha256 must be a SHA-256 digest`);
-    }
-    if (!fixture.expectedGeneratorPattern) {
-      throw new Error(`Blender export fixture ${fixture.id} must define expectedGeneratorPattern`);
-    }
-  }
-  return manifest;
-}
-
-async function validateFixture(
-  fixture: BlenderExportFixture,
-  input: BlenderExportFixtureInput | undefined
-): Promise<BlenderExportValidationFixtureResult> {
-  if (!input) {
-    return failureFixture(fixture, "ASSET_BLENDER_EXPORT_SOURCE_MISSING", "Fixture source text was not provided to the validation runner.");
-  }
-  try {
-    const json = JSON.parse(input.sourceText) as { readonly asset?: { readonly generator?: string } };
-    const generator = json.asset?.generator ?? "";
-    const diagnostics: BlenderExportValidationDiagnostic[] = [];
-    if (!new RegExp(fixture.expectedGeneratorPattern, "i").test(generator)) {
-      diagnostics.push({
-        code: "ASSET_BLENDER_EXPORT_GENERATOR_MISMATCH",
-        severity: "error",
-        message: `Expected generator matching ${fixture.expectedGeneratorPattern}, got ${generator || "missing"}.`,
-        nextAction: "Replace the fixture with a confirmed Blender-exported glTF file or update the manifest evidence."
-      });
-    }
-    const asset = await new GLTFLoader().load({ url: dataGLTF(input.sourceText) }, new LoadContext());
-    return resultForAsset(fixture, asset, generator, diagnostics);
-  } catch (error) {
-    return failureFixture(fixture, "ASSET_BLENDER_EXPORT_LOAD_FAILED", error instanceof Error ? error.message : String(error));
-  }
-}
-
-function resultForAsset(
-  fixture: BlenderExportFixture,
-  asset: GLTFAsset,
-  generator: string,
-  diagnostics: readonly BlenderExportValidationDiagnostic[]
-): BlenderExportValidationFixtureResult {
-  const renderables = asset.createScene().collectRenderables().length;
-  const status = diagnostics.some((diagnostic) => diagnostic.severity === "error") ? "fail" : diagnostics.length > 0 ? "warn" : "pass";
-  return {
-    id: fixture.id,
-    name: fixture.name,
-    path: fixture.path,
-    upstreamPath: fixture.upstreamPath,
-    sourceSha256: fixture.sourceSha256,
-    license: fixture.license,
-    tags: fixture.tags,
-    generator,
-    status,
-    metrics: {
-      scenes: asset.scenes.length,
-      meshes: asset.meshes.length,
-      materials: asset.materials.length,
-      textures: asset.textures.length,
-      images: asset.images.length,
-      animations: asset.animations.length,
-      renderables
-    },
-    diagnostics: diagnostics.length > 0 ? diagnostics : [{
-      code: "ASSET_BLENDER_EXPORT_VALIDATED",
-      severity: "info",
-      message: "Fixture was confirmed as Blender-exported glTF and loaded through Aura3D's glTF loader.",
-      nextAction: "Keep this fixture current when changing loader validation, importer settings, or fixture source revision."
-    }]
-  };
-}
-
-function failureFixture(
-  fixture: BlenderExportFixture,
-  code: string,
-  message: string
-): BlenderExportValidationFixtureResult {
-  return {
-    id: fixture.id,
-    name: fixture.name,
-    path: fixture.path,
-    upstreamPath: fixture.upstreamPath,
-    sourceSha256: fixture.sourceSha256,
-    license: fixture.license,
-    tags: fixture.tags,
-    generator: "",
-    status: "fail",
-    metrics: {
-      scenes: 0,
-      meshes: 0,
-      materials: 0,
-      textures: 0,
-      images: 0,
-      animations: 0,
-      renderables: 0
-    },
-    diagnostics: [{
-      code,
-      severity: "error",
-      message,
-      nextAction: "Fix or replace this Blender-export fixture before marking Blender-export validation complete."
-    }]
-  };
-}
-
-function dataGLTF(source: string): string {
-  return `data:model/gltf+json,${encodeURIComponent(source)}`;
-}