@aura3d/assets 1.4.0 → 1.4.1

package/src/AssetBundleCacheFixtures.ts

@@ -1,290 +0,0 @@
-export type AssetBundleCacheEvictionPolicy = "lru" | "lfu" | "fifo" | "ttl" | "size";
-
-export interface AssetBundleCacheInput {
-  readonly assetId: string;
-  readonly url: string;
-  readonly meshCount: number;
-  readonly materialCount: number;
-  readonly textureCount: number;
-  readonly animationCount: number;
-  readonly skinCount: number;
-  readonly morphTargetCount: number;
-  readonly decodedTextureBytes?: number;
-}
-
-export interface AssetBundleManifestEvidenceEntry {
-  readonly id: string;
-  readonly path: string;
-  readonly type: "document" | "buffer" | "texture" | "material" | "animation" | "metadata";
-  readonly sizeBytes: number;
-  readonly dependencies: readonly string[];
-}
-
-export interface AssetBundleCacheEvidence {
-  readonly source: "origin-master-asset-bundle-cache-adapted";
-  readonly manifest: {
-    readonly id: string;
-    readonly version: "external-parity-generated";
-    readonly assetCount: number;
-    readonly totalBytes: number;
-    readonly entries: readonly AssetBundleManifestEvidenceEntry[];
-  };
-  readonly dependencyGraph: {
-    readonly rootAssetId: string;
-    readonly loadOrder: readonly string[];
-    readonly releaseOrder: readonly string[];
-    readonly directDependencies: readonly string[];
-    readonly transitiveDependencies: readonly string[];
-    readonly cycleDetected: false;
-  };
-  readonly cache: {
-    readonly policy: AssetBundleCacheEvictionPolicy;
-    readonly maxEntries: number;
-    readonly maxBytes: number;
-    readonly cachedEntries: number;
-    readonly memoryBytes: number;
-    readonly hits: number;
-    readonly misses: number;
-    readonly evictions: number;
-    readonly hitRate: number;
-    readonly retainedAssetIds: readonly string[];
-    readonly evictedAssetIds: readonly string[];
-  };
-  readonly productionReadiness: {
-    readonly bundleManifest: true;
-    readonly dependencySorting: true;
-    readonly memoryBudgetEviction: true;
-    readonly cacheTelemetry: true;
-    readonly inFlightDeduplicationBoundary: true;
-  };
-  readonly blockedClaims: readonly string[];
-  readonly claimBoundary: string;
-  readonly hash: string;
-}
-
-export function createAssetBundleCacheEvidence(input: AssetBundleCacheInput): AssetBundleCacheEvidence {
-  assertInput(input);
-  const rootId = normalizeAssetId(input.assetId);
-  const entries = createManifestEntries(rootId, input);
-  const loadOrder = topologicalSort(entries);
-  const releaseOrder = [...loadOrder].reverse();
-  const cache = simulateCache(loadOrder, entries);
-  const manifest = {
-    id: `${rootId}-bundle`,
-    version: "external-parity-generated" as const,
-    assetCount: entries.length,
-    totalBytes: sumBytes(entries),
-    entries
-  };
-  const directDependencies = entries.find((entry) => entry.id === rootId)?.dependencies ?? [];
-  const evidenceCore = {
-    manifest,
-    dependencyGraph: {
-      rootAssetId: rootId,
-      loadOrder,
-      releaseOrder,
-      directDependencies,
-      transitiveDependencies: loadOrder.filter((id) => id !== rootId),
-      cycleDetected: false as const
-    },
-    cache
-  };
-  return {
-    source: "origin-master-asset-bundle-cache-adapted",
-    ...evidenceCore,
-    productionReadiness: {
-      bundleManifest: true,
-      dependencySorting: true,
-      memoryBudgetEviction: true,
-      cacheTelemetry: true,
-      inFlightDeduplicationBoundary: true
-    },
-    blockedClaims: [
-      "Unity Addressables catalog parity",
-      "Unreal Asset Manager primary asset parity",
-      "IndexedDB persistent cache certification",
-      "CDN cache invalidation and patch streaming parity",
-      "native platform asset bundle packaging parity"
-    ],
-    claimBoundary: "This evidence ports the old branch asset bundle/cache concepts into deterministic ExternalParity manifest, dependency-order, and memory-budget telemetry for loaded glTF assets. It does not claim Unity Addressables, Unreal Asset Manager, persistent browser storage, CDN patch streaming, or native bundle packaging parity.",
-    hash: stableHash(JSON.stringify(evidenceCore))
-  };
-}
-
-function createManifestEntries(rootId: string, input: AssetBundleCacheInput): readonly AssetBundleManifestEvidenceEntry[] {
-  const textureCount = Math.max(0, Math.trunc(input.textureCount));
-  const materialCount = Math.max(0, Math.trunc(input.materialCount));
-  const meshCount = Math.max(0, Math.trunc(input.meshCount));
-  const animationCount = Math.max(0, Math.trunc(input.animationCount));
-  const textureIds = Array.from({ length: Math.max(1, textureCount) }, (_, index) => `${rootId}:texture-${index + 1}`);
-  const entries: AssetBundleManifestEvidenceEntry[] = [
-    {
-      id: rootId,
-      path: input.url,
-      type: "document",
-      sizeBytes: 2048 + materialCount * 256 + meshCount * 512,
-      dependencies: [
-        `${rootId}:geometry-buffer`,
-        `${rootId}:material-manifest`,
-        `${rootId}:metadata`,
-        ...(animationCount > 0 ? [`${rootId}:animation`] : [])
-      ]
-    },
-    {
-      id: `${rootId}:geometry-buffer`,
-      path: `${input.url}#geometry-buffer`,
-      type: "buffer",
-      sizeBytes: 8192 + meshCount * 32768 + input.skinCount * 4096 + input.morphTargetCount * 8192,
-      dependencies: []
-    },
-    {
-      id: `${rootId}:material-manifest`,
-      path: `${input.url}#materials`,
-      type: "material",
-      sizeBytes: 1024 + materialCount * 768,
-      dependencies: textureIds
-    },
-    {
-      id: `${rootId}:metadata`,
-      path: `${input.url}#loader-diagnostics`,
-      type: "metadata",
-      sizeBytes: 1024,
-      dependencies: []
-    }
-  ];
-
-  for (let index = 0; index < textureIds.length; index += 1) {
-    entries.push({
-      id: textureIds[index] ?? `${rootId}:texture-${index + 1}`,
-      path: `${input.url}#texture-${index + 1}`,
-      type: "texture",
-      sizeBytes: Math.max(4096, Math.trunc((input.decodedTextureBytes ?? textureCount * 65536) / Math.max(1, textureCount))),
-      dependencies: []
-    });
-  }
-
-  if (animationCount > 0) {
-    entries.push({
-      id: `${rootId}:animation`,
-      path: `${input.url}#animation`,
-      type: "animation",
-      sizeBytes: 2048 + animationCount * 4096,
-      dependencies: [`${rootId}:geometry-buffer`]
-    });
-  }
-
-  return entries;
-}
-
-function topologicalSort(entries: readonly AssetBundleManifestEvidenceEntry[]): readonly string[] {
-  const byId = new Map(entries.map((entry) => [entry.id, entry]));
-  const sorted: string[] = [];
-  const visited = new Set<string>();
-  const visiting = new Set<string>();
-  const visit = (id: string): void => {
-    if (visited.has(id)) return;
-    if (visiting.has(id)) throw new Error(`Asset bundle dependency cycle detected: ${id}`);
-    visiting.add(id);
-    for (const dependency of byId.get(id)?.dependencies ?? []) {
-      visit(dependency);
-    }
-    visiting.delete(id);
-    visited.add(id);
-    sorted.push(id);
-  };
-  for (const entry of entries) visit(entry.id);
-  return sorted;
-}
-
-function simulateCache(loadOrder: readonly string[], entries: readonly AssetBundleManifestEvidenceEntry[]): AssetBundleCacheEvidence["cache"] {
-  const byId = new Map(entries.map((entry) => [entry.id, entry]));
-  const maxEntries = Math.max(3, Math.min(6, loadOrder.length - 1));
-  const maxBytes = Math.max(32768, Math.trunc(sumBytes(entries) * 0.72));
-  const retained = new Map<string, { readonly sizeBytes: number; accessCount: number; lastAccess: number }>();
-  const evicted: string[] = [];
-  let clock = 0;
-  let memoryBytes = 0;
-  let hits = 0;
-  let misses = 0;
-  let evictions = 0;
-
-  for (const id of loadOrder) {
-    clock += 1;
-    const hit = retained.get(id);
-    if (hit) {
-      hit.accessCount += 1;
-      hit.lastAccess = clock;
-      hits += 1;
-      continue;
-    }
-    misses += 1;
-    const sizeBytes = byId.get(id)?.sizeBytes ?? 0;
-    while ((retained.size >= maxEntries || memoryBytes + sizeBytes > maxBytes) && retained.size > 0) {
-      const victim = [...retained.entries()].sort((left, right) => left[1].lastAccess - right[1].lastAccess)[0];
-      if (!victim) break;
-      retained.delete(victim[0]);
-      memoryBytes -= victim[1].sizeBytes;
-      evicted.push(victim[0]);
-      evictions += 1;
-    }
-    if (sizeBytes <= maxBytes) {
-      retained.set(id, { sizeBytes, accessCount: 1, lastAccess: clock });
-      memoryBytes += sizeBytes;
-    }
-  }
-
-  for (const id of loadOrder.slice(-2)) {
-    if (retained.has(id)) {
-      retained.get(id)!.accessCount += 1;
-      hits += 1;
-    } else {
-      misses += 1;
-    }
-  }
-
-  return {
-    policy: "lru",
-    maxEntries,
-    maxBytes,
-    cachedEntries: retained.size,
-    memoryBytes,
-    hits,
-    misses,
-    evictions,
-    hitRate: Number((hits / Math.max(1, hits + misses)).toFixed(4)),
-    retainedAssetIds: [...retained.keys()],
-    evictedAssetIds: evicted
-  };
-}
-
-function assertInput(input: AssetBundleCacheInput): void {
-  if (input.assetId.trim().length === 0) throw new Error("assetId is required.");
-  if (input.url.trim().length === 0) throw new Error("url is required.");
-  for (const [name, value] of Object.entries({
-    meshCount: input.meshCount,
-    materialCount: input.materialCount,
-    textureCount: input.textureCount,
-    animationCount: input.animationCount,
-    skinCount: input.skinCount,
-    morphTargetCount: input.morphTargetCount
-  })) {
-    if (!Number.isFinite(value) || value < 0) throw new Error(`${name} must be a non-negative finite number.`);
-  }
-}
-
-function normalizeAssetId(id: string): string {
-  return id.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "asset";
-}
-
-function sumBytes(entries: readonly AssetBundleManifestEvidenceEntry[]): number {
-  return entries.reduce((sum, entry) => sum + entry.sizeBytes, 0);
-}
-
-function stableHash(value: string): string {
-  let hash = 2166136261;
-  for (let index = 0; index < value.length; index += 1) {
-    hash ^= value.charCodeAt(index);
-    hash = Math.imul(hash, 16777619);
-  }
-  return (hash >>> 0).toString(16).padStart(8, "0");
-}

package/src/AssetCache.ts

@@ -1,76 +0,0 @@
-import { AssetHandle } from "./AssetHandle";
-
-interface CacheEntry<T> {
-  readonly handle: AssetHandle<T>;
-  readonly promise?: Promise<AssetHandle<T>>;
-}
-
-export interface AssetCacheSnapshot {
-  readonly cachedEntries: number;
-  readonly inFlightEntries: number;
-  readonly totalEntries: number;
-  readonly keys: readonly string[];
-}
-
-export class AssetCache {
-  private readonly entries = new Map<string, CacheEntry<unknown>>();
-  private readonly inFlight = new Map<string, Promise<AssetHandle<unknown>>>();
-
-  has(key: string): boolean {
-    return this.entries.has(key) || this.inFlight.has(key);
-  }
-
-  get<T>(key: string): AssetHandle<T> | undefined {
-    const entry = this.entries.get(key);
-    if (!entry) {
-      return undefined;
-    }
-
-    return entry.handle as AssetHandle<T>;
-  }
-
-  getInFlight<T>(key: string): Promise<AssetHandle<T>> | undefined {
-    return this.inFlight.get(key) as Promise<AssetHandle<T>> | undefined;
-  }
-
-  set<T>(key: string, handle: AssetHandle<T>): void {
-    this.entries.set(key, { handle: handle as unknown as AssetHandle<unknown> });
-  }
-
-  setInFlight<T>(key: string, promise: Promise<AssetHandle<T>>): void {
-    this.inFlight.set(key, promise as Promise<AssetHandle<unknown>>);
-    promise
-      .then((handle) => {
-        this.entries.set(key, { handle: handle as unknown as AssetHandle<unknown> });
-      })
-      .catch(() => {
-        // Failed loads are intentionally not cached; callers receive the original rejection.
-      })
-      .finally(() => {
-        this.inFlight.delete(key);
-      });
-  }
-
-  delete(key: string): boolean {
-    return this.entries.delete(key);
-  }
-
-  clear(): void {
-    this.entries.clear();
-    this.inFlight.clear();
-  }
-
-  keys(): readonly string[] {
-    return [...new Set([...this.entries.keys(), ...this.inFlight.keys()])];
-  }
-
-  snapshot(): AssetCacheSnapshot {
-    const keys = this.keys();
-    return {
-      cachedEntries: this.entries.size,
-      inFlightEntries: this.inFlight.size,
-      totalEntries: keys.length,
-      keys
-    };
-  }
-}

package/src/AssetCompatibility.ts

@@ -1,224 +0,0 @@
-import {
-  assertValidGLTFCorpusManifest,
-  createGLTFCorpusReport,
-  type AssetDiagnostic,
-  type AssetImportSettings,
-  type GLTFCorpusAssetReport,
-  type GLTFCorpusManifest,
-  type GLTFCorpusReport
-} from "./AssetCorpus";
-import type { BlenderExportValidationReport } from "./BlenderExportValidation";
-
-export type AssetCompatibilityLoaderName = "aura3d" | "threejs" | "babylonjs" | "blender-export";
-export type AssetCompatibilityStatus = "pass" | "warn" | "expected-fail" | "not-run";
-
-export interface AssetLoaderCompatibilityResult {
-  readonly loader: AssetCompatibilityLoaderName;
-  readonly status: AssetCompatibilityStatus;
-  readonly diagnostics: readonly AssetDiagnostic[];
-}
-
-export interface AssetCompatibilityReportAsset {
-  readonly id: string;
-  readonly name: string;
-  readonly format: string;
-  readonly tags: readonly string[];
-  readonly sourceUri: string;
-  readonly sourceRevision: string;
-  readonly sourceSha256: string;
-  readonly importSettings: AssetImportSettings;
-  readonly loaders: readonly AssetLoaderCompatibilityResult[];
-}
-
-export interface AssetCompatibilityReport {
-  readonly schemaVersion: "asset-compatibility-report";
-  readonly generatedAt: string;
-  readonly sourceManifest: GLTFCorpusReport["sourceManifest"];
-  readonly fixtureStatus: {
-    readonly blenderExportFixtures: "present" | "missing";
-  };
-  readonly blenderExportValidation?: BlenderExportValidationReport;
-  readonly summary: {
-    readonly assetCount: number;
-    readonly aura3d: Record<AssetCompatibilityStatus, number>;
-    readonly threejs: Record<AssetCompatibilityStatus, number>;
-    readonly babylonjs: Record<AssetCompatibilityStatus, number>;
-    readonly blenderExport: Record<AssetCompatibilityStatus, number>;
-  };
-  readonly assets: readonly AssetCompatibilityReportAsset[];
-}
-
-export interface AssetCompatibilityReportOptions {
-  readonly generatedAt?: string;
-  readonly blenderExportFixturesPresent?: boolean;
-  readonly blenderExportValidation?: BlenderExportValidationReport;
-  readonly externalLoaderResults?: readonly ExternalAssetLoaderCompatibilityResult[];
-  readonly blenderExportResults?: readonly BlenderExportCompatibilityResult[];
-}
-
-export interface ExternalAssetLoaderCompatibilityResult extends AssetLoaderCompatibilityResult {
-  readonly assetId: string;
-  readonly loader: "threejs" | "babylonjs";
-}
-
-export interface BlenderExportCompatibilityResult extends AssetLoaderCompatibilityResult {
-  readonly assetId: string;
-  readonly loader: "blender-export";
-}
-
-export function createAssetCompatibilityReport(
-  manifest: GLTFCorpusManifest,
-  options: AssetCompatibilityReportOptions = {}
-): AssetCompatibilityReport {
-  const validated = assertValidGLTFCorpusManifest(manifest);
-  const corpusReport = createGLTFCorpusReport(validated, options.generatedAt ?? new Date().toISOString());
-  const blenderExportFixturesPresent = options.blenderExportFixturesPresent ?? options.blenderExportValidation !== undefined;
-  const externalResults = indexExternalLoaderResults(options.externalLoaderResults ?? []);
-  const blenderExportResults = indexBlenderExportResults(options.blenderExportResults ?? []);
-  const assets = corpusReport.assets.map((asset) => createCompatibilityAsset(asset, blenderExportFixturesPresent, externalResults, blenderExportResults));
-
-  return {
-    schemaVersion: "asset-compatibility-report",
-    generatedAt: corpusReport.generatedAt,
-    sourceManifest: corpusReport.sourceManifest,
-    fixtureStatus: {
-      blenderExportFixtures: blenderExportFixturesPresent ? "present" : "missing"
-    },
-    ...(options.blenderExportValidation ? { blenderExportValidation: options.blenderExportValidation } : {}),
-    summary: {
-      assetCount: assets.length,
-      aura3d: summarize(assets, "aura3d"),
-      threejs: summarize(assets, "threejs"),
-      babylonjs: summarize(assets, "babylonjs"),
-      blenderExport: summarize(assets, "blender-export")
-    },
-    assets
-  };
-}
-
-function createCompatibilityAsset(
-  asset: GLTFCorpusAssetReport,
-  blenderExportFixturesPresent: boolean,
-  externalResults: ReadonlyMap<string, AssetLoaderCompatibilityResult>,
-  blenderExportResults: ReadonlyMap<string, AssetLoaderCompatibilityResult>
-): AssetCompatibilityReportAsset {
-  return {
-    id: asset.id,
-    name: asset.name,
-    format: asset.format,
-    tags: asset.tags,
-    sourceUri: asset.sourceUri,
-    sourceRevision: asset.sourceRevision,
-    sourceSha256: asset.sourceSha256,
-    importSettings: asset.importSettings,
-    loaders: [
-      {
-        loader: "aura3d",
-        status: asset.expectedStatus === "expected-fail" ? "expected-fail" : asset.expectedStatus,
-        diagnostics: asset.diagnostics
-      },
-      externalResults.get(externalResultKey(asset.id, "threejs")) ?? externalLoaderScaffold("threejs", asset),
-      externalResults.get(externalResultKey(asset.id, "babylonjs")) ?? externalLoaderScaffold("babylonjs", asset),
-      blenderExportResults.get(asset.id) ?? blenderExportScaffold(asset, blenderExportFixturesPresent)
-    ]
-  };
-}
-
-function indexExternalLoaderResults(
-  results: readonly ExternalAssetLoaderCompatibilityResult[]
-): ReadonlyMap<string, AssetLoaderCompatibilityResult> {
-  const indexed = new Map<string, AssetLoaderCompatibilityResult>();
-  for (const result of results) {
-    indexed.set(externalResultKey(result.assetId, result.loader), {
-      loader: result.loader,
-      status: result.status,
-      diagnostics: result.diagnostics
-    });
-  }
-  return indexed;
-}
-
-function indexBlenderExportResults(
-  results: readonly BlenderExportCompatibilityResult[]
-): ReadonlyMap<string, AssetLoaderCompatibilityResult> {
-  const indexed = new Map<string, AssetLoaderCompatibilityResult>();
-  for (const result of results) {
-    indexed.set(result.assetId, {
-      loader: result.loader,
-      status: result.status,
-      diagnostics: result.diagnostics
-    });
-  }
-  return indexed;
-}
-
-function externalResultKey(assetId: string, loader: "threejs" | "babylonjs"): string {
-  return `${assetId}:${loader}`;
-}
-
-function externalLoaderScaffold(loader: "threejs" | "babylonjs", asset: GLTFCorpusAssetReport): AssetLoaderCompatibilityResult {
-  return {
-    loader,
-    status: "not-run",
-    diagnostics: [
-      diagnostic(
-        `ASSET_${loader.toUpperCase()}_LOADER_NOT_RUN`,
-        "External loader compatibility has not been executed in this bounded slice.",
-        `Run ${asset.id} through a pinned ${loader} GLTFLoader version and record pass, warn, or expected-fail evidence before claiming ${loader} parity.`
-      )
-    ]
-  };
-}
-
-function blenderExportScaffold(asset: GLTFCorpusAssetReport, fixturesPresent: boolean): AssetLoaderCompatibilityResult {
-  if (fixturesPresent) {
-    return {
-      loader: "blender-export",
-      status: "not-run",
-      diagnostics: [
-        diagnostic(
-          "ASSET_BLENDER_EXPORT_VALIDATION_PENDING",
-          "Blender export fixtures were detected, but no export validation runner is wired in this slice.",
-          `Run ${asset.id} or the matching fixture through the Blender exporter validation command and record the exported glTF diagnostics.`
-        )
-      ]
-    };
-  }
-  return {
-    loader: "blender-export",
-    status: "not-run",
-    diagnostics: [
-      diagnostic(
-        "ASSET_BLENDER_EXPORT_FIXTURES_MISSING",
-        "No Blender-export fixtures are present in the asset test corpus.",
-        "Add checked-in exported glTF/GLB fixtures before marking Blender-export validation complete."
-      )
-    ]
-  };
-}
-
-function summarize(
-  assets: readonly AssetCompatibilityReportAsset[],
-  loader: AssetCompatibilityLoaderName
-): Record<AssetCompatibilityStatus, number> {
-  const counts: Record<AssetCompatibilityStatus, number> = {
-    pass: 0,
-    warn: 0,
-    "expected-fail": 0,
-    "not-run": 0
-  };
-  for (const asset of assets) {
-    const result = asset.loaders.find((entry) => entry.loader === loader);
-    counts[result?.status ?? "not-run"] += 1;
-  }
-  return counts;
-}
-
-function diagnostic(code: string, message: string, nextAction: string): AssetDiagnostic {
-  return {
-    code,
-    severity: "info",
-    message,
-    nextAction
-  };
-}