@forgeax/engine-assets-runtime 0.1.19 → 0.1.20

package/dist/__tests__/texture-pack-loader.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=texture-pack-loader.unit.test.d.ts.map

package/dist/__tests__/texture-pack-loader.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture-pack-loader.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/texture-pack-loader.unit.test.ts"],"names":[],"mappings":""}

package/dist/decode-image-bytes.d.ts

@@ -25,8 +25,8 @@ import type { ImageError, Result, TextureAsset } from '@forgeax/engine-types';
  * @param opts - Optional decode overrides:
  *   - `colorSpace`: `'srgb'` (default) or `'linear'`. Derives POD `format`:
  *     `srgb -> 'rgba8unorm-srgb'`, `linear -> 'rgba8unorm'`.
- *   - `mipmap`: `true` (default) or `false`. When true, `mipLevelCount` is
- *     computed via `numMipLevels({ width, height })`; when false, forced 1.
+ *   - `mipmap`: `true` (default) or `false`. When true, the producer requests
+ *     generated mips; when false, it keeps one authored level.
  * @returns `ok(TextureAsset)` on success; `err(ImageError)` on failure.
  *
  * @example

package/dist/decode-image-bytes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decode-image-bytes.d.ts","sourceRoot":"","sources":["../src/decode-image-bytes.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAa9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,UAAU,GAAG,WAAW,EAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9D,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC,CAkC3C"}
+{"version":3,"file":"decode-image-bytes.d.ts","sourceRoot":"","sources":["../src/decode-image-bytes.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAY9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,UAAU,GAAG,WAAW,EAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9D,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC,CA8B3C"}

package/dist/errors/asset.d.ts

@@ -1,5 +1,25 @@
 import type { MeshBinHeaderV4 } from '@forgeax/engine-pack';
 import { AssetError, type AssetMeshBinContractFacts, type AssetMeshBinContractViolationReason } from '@forgeax/engine-types';
+export type TexturePackVerificationCause = 'byte-length' | 'digest-mismatch' | 'packing-order-mismatch' | 'shape-mismatch';
+export interface TexturePackVerificationDetail {
+    readonly guid: string;
+    readonly sourceKey: string;
+    readonly generation: number;
+    readonly stage: 'producer' | 'loader';
+    readonly cause: TexturePackVerificationCause;
+    readonly expectedBytes?: number;
+    readonly actualBytes?: number;
+    readonly expectedDigest?: string;
+    readonly actualDigest?: string;
+}
+/** Structured failure for the producer/loader texture contract. */
+export declare class TexturePackVerificationError extends Error {
+    readonly code: "texture-pack-verification-failed";
+    readonly expected: string;
+    readonly hint = "repair the producer output and retry the same texture GUID generation";
+    readonly detail: TexturePackVerificationDetail;
+    constructor(detail: TexturePackVerificationDetail, expected: string);
+}
 export declare class MeshBinAssetError extends AssetError {
     readonly subject: "mesh-bin";
     readonly sourceKey: string;

package/dist/errors/asset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"asset.d.ts","sourceRoot":"","sources":["../../src/errors/asset.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EACL,UAAU,EAEV,KAAK,yBAAyB,EAC9B,KAAK,mCAAmC,EACzC,MAAM,uBAAuB,CAAC;AAE/B,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,QAAQ,CAAC,OAAO,EAAG,UAAU,CAAU;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,8EAA8E;gBAEnF,IAAI,EAAE;QAChB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG;YAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,mCAAmC,CAAC;QACtD,QAAQ,CAAC,aAAa,CAAC,EAAE,yBAAyB,CAAC;QACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,yBAAyB,CAAC;KAClD;CAyBF;AAID;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iCAAiC;IAChD,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,CAAC;IACvD,yGAAyG;IACzG,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;GASG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,QAAQ,CAAC,IAAI,EAAG,gCAAgC,CAAU;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,iCAAiC,CAAC;gBAGjD,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,EAC7C,mBAAmB,CAAC,EAAE,MAAM;CA2B/B;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,QAAQ,CAAC,IAAI,EAAG,6BAA6B,CAAU;IACvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,8BAA8B,CAAC;gBAEpC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAajE;AAID;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,IAAI,EAAG,2BAA2B,CAAU;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,4BAA4B,CAAC;gBAElC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAajE;AAID;;;;;GAKG;AACH,MAAM,WAAW,uCAAuC;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,qBAAa,sCAAuC,SAAQ,KAAK;IAC/D,QAAQ,CAAC,IAAI,EAAG,yCAAyC,CAAU;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,uCAAuC,CAAC;gBAE7C,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAS1D;AAID;;;;;;;;GAQG;AACH,MAAM,WAAW,qCAAqC;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,qBAAa,oCAAqC,SAAQ,KAAK;IAC7D,QAAQ,CAAC,IAAI,EAAG,qCAAqC,CAAU;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,qCAAqC,CAAC;gBAE3C,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;CAYhD;AAID;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB,gCAAgC,GAChC,6BAA6B,GAC7B,2BAA2B,GAC3B,sCAAsC,GACtC,oCAAoC,CAAC"}
+{"version":3,"file":"asset.d.ts","sourceRoot":"","sources":["../../src/errors/asset.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EACL,UAAU,EAEV,KAAK,yBAAyB,EAC9B,KAAK,mCAAmC,EACzC,MAAM,uBAAuB,CAAC;AAE/B,MAAM,MAAM,4BAA4B,GACpC,aAAa,GACb,iBAAiB,GACjB,wBAAwB,GACxB,gBAAgB,CAAC;AAErB,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,4BAA4B,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,mEAAmE;AACnE,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,EAAG,kCAAkC,CAAU;IAC5D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,2EAA2E;IACxF,QAAQ,CAAC,MAAM,EAAE,6BAA6B,CAAC;gBAEnC,MAAM,EAAE,6BAA6B,EAAE,QAAQ,EAAE,MAAM;CAMpE;AAED,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,QAAQ,CAAC,OAAO,EAAG,UAAU,CAAU;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,8EAA8E;gBAEnF,IAAI,EAAE;QAChB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG;YAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,mCAAmC,CAAC;QACtD,QAAQ,CAAC,aAAa,CAAC,EAAE,yBAAyB,CAAC;QACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,yBAAyB,CAAC;KAClD;CAyBF;AAID;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iCAAiC;IAChD,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,CAAC;IACvD,yGAAyG;IACzG,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;GASG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,QAAQ,CAAC,IAAI,EAAG,gCAAgC,CAAU;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,iCAAiC,CAAC;gBAGjD,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,EAC7C,mBAAmB,CAAC,EAAE,MAAM;CA2B/B;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,QAAQ,CAAC,IAAI,EAAG,6BAA6B,CAAU;IACvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,8BAA8B,CAAC;gBAEpC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAajE;AAID;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,IAAI,EAAG,2BAA2B,CAAU;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,4BAA4B,CAAC;gBAElC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAajE;AAID;;;;;GAKG;AACH,MAAM,WAAW,uCAAuC;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,qBAAa,sCAAuC,SAAQ,KAAK;IAC/D,QAAQ,CAAC,IAAI,EAAG,yCAAyC,CAAU;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,uCAAuC,CAAC;gBAE7C,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAS1D;AAID;;;;;;;;GAQG;AACH,MAAM,WAAW,qCAAqC;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,qBAAa,oCAAqC,SAAQ,KAAK;IAC7D,QAAQ,CAAC,IAAI,EAAG,qCAAqC,CAAU;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,qCAAqC,CAAC;gBAE3C,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;CAYhD;AAID;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB,gCAAgC,GAChC,6BAA6B,GAC7B,2BAA2B,GAC3B,sCAAsC,GACtC,oCAAoC,CAAC"}

package/dist/index.mjs

@@ -695,217 +695,6 @@ function unpackMeshBinV4(bytes, sourceKey) {
   };
   return ok(mesh);
 }
-var deviceCache = /* @__PURE__ */ new WeakMap();
-var MIPMAP_WGSL = `
-struct VsOut {
-  @builtin(position) clip : vec4<f32>,
-  @location(0)       uv   : vec2<f32>,
-};
-
-@vertex
-fn vs_main(@builtin(vertex_index) vid : u32) -> VsOut {
-  // 3 vertices forming an oversized triangle: (-1,-1), (-1,3), (3,-1)
-  var positions = array<vec2<f32>, 3>(
-    vec2<f32>(-1.0, -1.0),
-    vec2<f32>(-1.0,  3.0),
-    vec2<f32>( 3.0, -1.0),
-  );
-  let pos = positions[vid];
-  var out : VsOut;
-  out.clip = vec4<f32>(pos, 0.0, 1.0);
-  // NDC -> UV with Y-flip fused into a single MAD.
-  out.uv = pos * vec2<f32>(0.5, -0.5) + vec2<f32>(0.5);
-  return out;
-}
-
-@group(0) @binding(0) var src_sampler : sampler;
-@group(0) @binding(1) var src_texture : texture_2d<f32>;
-
-@fragment
-fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
-  return textureSample(src_texture, src_sampler, in.uv);
-}
-`;
-function numMipLevels(size) {
-  const max = Math.max(size.width, size.height);
-  if (max <= 1) return 1;
-  return Math.floor(Math.log2(max)) + 1;
-}
-function mipmapCacheSize(device) {
-  const cache = deviceCache.get(device);
-  return cache?.pipelines.size ?? 0;
-}
-async function getOrCreateMipmapPipeline(device, format, asyncCreateShaderModule) {
-  const cache = await ensureDeviceCache(device, asyncCreateShaderModule);
-  if (!cache.ok) return cache;
-  const existing = cache.value.pipelines.get(format);
-  if (existing !== void 0) {
-    return ok$1(existing);
-  }
-  const layoutRes = device.createPipelineLayout({
-    label: "mipmap-pl",
-    bindGroupLayouts: [cache.value.layout]
-  });
-  if (!layoutRes.ok) return layoutRes;
-  const pipelineRes = device.createRenderPipeline({
-    label: `mipmap-pipeline-${format}`,
-    layout: layoutRes.value,
-    vertex: { module: cache.value.module, entryPoint: "vs_main" },
-    fragment: {
-      module: cache.value.module,
-      entryPoint: "fs_main",
-      targets: [{ format }]
-    },
-    primitive: { topology: "triangle-list" }
-  });
-  if (!pipelineRes.ok) return pipelineRes;
-  cache.value.pipelines.set(format, pipelineRes.value);
-  return pipelineRes;
-}
-async function ensureDeviceCache(device, asyncCreateShaderModule) {
-  const existing = deviceCache.get(device);
-  if (existing !== void 0) return ok$1(existing);
-  const moduleRes = await asyncCreateShaderModule(device, {
-    code: MIPMAP_WGSL,
-    label: "mipmap-wgsl"
-  });
-  if (!moduleRes.ok) return moduleRes;
-  const samplerRes = device.createSampler({
-    magFilter: "linear",
-    minFilter: "linear",
-    mipmapFilter: "linear"
-  });
-  if (!samplerRes.ok) return samplerRes;
-  const FRAGMENT_STAGE = 2;
-  const layoutRes = device.createBindGroupLayout({
-    label: "mipmap-bgl",
-    entries: [
-      { binding: 0, visibility: FRAGMENT_STAGE, sampler: { type: "filtering" } },
-      {
-        binding: 1,
-        visibility: FRAGMENT_STAGE,
-        texture: { sampleType: "float", viewDimension: "2d" }
-      }
-    ]
-  });
-  if (!layoutRes.ok) return layoutRes;
-  const cache = {
-    sampler: samplerRes.value,
-    module: moduleRes.value,
-    layout: layoutRes.value,
-    pipelines: /* @__PURE__ */ new Map()
-  };
-  deviceCache.set(device, cache);
-  return ok$1(cache);
-}
-function recordMipmapBlit(device, texture, levels, pipeline, cache) {
-  const encoderRes = device.createCommandEncoder({ label: "mipmap-encoder" });
-  if (!encoderRes.ok) return encoderRes;
-  const encoder = encoderRes.value;
-  for (let i = 1; i < levels; i++) {
-    const srcViewRes = device.createTextureView(texture, {
-      baseMipLevel: i - 1,
-      mipLevelCount: 1,
-      dimension: "2d"
-    });
-    if (!srcViewRes.ok) return srcViewRes;
-    const dstViewRes = device.createTextureView(texture, {
-      baseMipLevel: i,
-      mipLevelCount: 1,
-      dimension: "2d"
-    });
-    if (!dstViewRes.ok) return dstViewRes;
-    const bindGroupRes = device.createBindGroup({
-      label: `mipmap-bg-${i}`,
-      layout: cache.layout,
-      entries: [
-        { binding: 0, resource: { kind: "sampler", value: cache.sampler } },
-        { binding: 1, resource: { kind: "textureView", value: srcViewRes.value } }
-      ]
-    });
-    if (!bindGroupRes.ok) return bindGroupRes;
-    const pass = encoder.beginRenderPass({
-      label: `mipmap-pass-${i}`,
-      colorAttachments: [
-        {
-          view: dstViewRes.value,
-          clearValue: { r: 0, g: 0, b: 0, a: 1 },
-          loadOp: "clear",
-          storeOp: "store"
-        }
-      ]
-    });
-    pass.setPipeline(pipeline);
-    pass.setBindGroup(0, bindGroupRes.value);
-    pass.draw(3, 1, 0, 0);
-    pass.end();
-  }
-  const finishRes = encoder.finish();
-  if (!finishRes.ok) return finishRes;
-  return device.queue.submit([finishRes.value]);
-}
-function blitMipmapsSync(device, texture, descriptor) {
-  const levels = descriptor.levels ?? numMipLevels(descriptor);
-  if (levels <= 1) return ok$1(void 0);
-  const cache = deviceCache.get(device);
-  if (cache === void 0) {
-    return err(
-      new RhiError({
-        code: "rhi-not-available",
-        expected: "mipmap pipeline cache prewarmed for this device before blitMipmapsSync",
-        hint: "call prewarmMipmapPipeline(device, formats) at renderer.ready before the synchronous record-stage mipmap blit"
-      })
-    );
-  }
-  const pipeline = cache.pipelines.get(descriptor.format);
-  if (pipeline === void 0) {
-    return err(
-      new RhiError({
-        code: "rhi-not-available",
-        expected: `mipmap pipeline for format ${descriptor.format} prewarmed`,
-        hint: `format ${descriptor.format} was not prewarmed; add it to the prewarmMipmapPipeline format list at renderer.ready`
-      })
-    );
-  }
-  return recordMipmapBlit(device, texture, levels, pipeline, cache);
-}
-function encodeMipmapLevel(device, pass, sourceView, format) {
-  const cache = deviceCache.get(device);
-  if (cache === void 0) {
-    return err(
-      new RhiError({
-        code: "rhi-not-available",
-        expected: "mipmap pipeline cache prewarmed for the graph device before encoding",
-        hint: "call prewarmMipmapPipeline(device, formats) at renderer.ready"
-      })
-    );
-  }
-  const pipeline = cache.pipelines.get(format);
-  if (pipeline === void 0) {
-    return err(
-      new RhiError({
-        code: "rhi-not-available",
-        expected: `mipmap pipeline for format ${format} prewarmed`,
-        hint: `format ${format} was not prewarmed; add it to the renderer prewarm list`
-      })
-    );
-  }
-  const bindGroup = device.createBindGroup({
-    label: "mipmap-graph-bind-group",
-    layout: cache.layout,
-    entries: [
-      { binding: 0, resource: { kind: "sampler", value: cache.sampler } },
-      { binding: 1, resource: { kind: "textureView", value: sourceView } }
-    ]
-  });
-  if (!bindGroup.ok) return bindGroup;
-  pass.setPipeline(pipeline);
-  pass.setBindGroup(0, bindGroup.value);
-  pass.draw(3, 1, 0, 0);
-  return ok$1(void 0);
-}
-
-// src/loaders/pack-artifact.ts
 function firstArtifact(input) {
   return input.artifacts.body ?? Object.values(input.artifacts)[0];
 }
@@ -916,6 +705,34 @@ function payloadNumber(payload, key2, fallback) {
 function payloadColorSpace(payload) {
   return payload.colorSpace === "linear" ? "linear" : "srgb";
 }
+function payloadTextureShape(payload) {
+  const shape = payload.shape;
+  if (!record(shape) || typeof shape.viewDimension !== "string" || !record(shape.extent)) {
+    return void 0;
+  }
+  const { width, height, layers, depth } = shape.extent;
+  if (!positiveInteger(width) || !positiveInteger(height)) return void 0;
+  if (shape.viewDimension === "2d" && layers === void 0 && depth === void 0) {
+    return { viewDimension: "2d", extent: { width, height } };
+  }
+  if (shape.viewDimension === "2d-array" && positiveInteger(layers) && depth === void 0) {
+    return { viewDimension: "2d-array", extent: { width, height, layers } };
+  }
+  if (shape.viewDimension === "3d" && positiveInteger(depth) && layers === void 0) {
+    return { viewDimension: "3d", extent: { width, height, depth } };
+  }
+  return void 0;
+}
+function payloadTextureMips(payload) {
+  const mips = payload.mips;
+  if (!record(mips) || typeof mips.kind !== "string") return void 0;
+  if (mips.kind === "none") return { kind: "none" };
+  if (mips.kind === "generate") return { kind: "generate" };
+  if (mips.kind === "packed" && positiveInteger(mips.levelCount)) {
+    return { kind: "packed", levelCount: mips.levelCount };
+  }
+  return void 0;
+}
 function invalidPackAsset(input, expected) {
   return {
     ok: false,
@@ -1070,8 +887,6 @@ async function loadTexturePack(input, ctx) {
   if (artifact === void 0)
     return invalidPackAsset(input, "texture asset-local image artifact");
   const payload = input.payload;
-  const width = payloadNumber(payload, "width", 0);
-  const height = payloadNumber(payload, "height", 0);
   const colorSpace = payloadColorSpace(payload);
   const codec = artifact.descriptor.assetCodec;
   const profile = codecProfile(codec);
@@ -1119,13 +934,14 @@ async function loadTexturePack(input, ctx) {
         ok: true,
         value: {
           kind: "texture",
-          width: transcoded.value.width,
-          height: transcoded.value.height,
+          shape: {
+            viewDimension: "2d",
+            extent: { width: transcoded.value.width, height: transcoded.value.height }
+          },
           format: target,
           data,
           colorSpace,
-          mipmap: transcoded.value.mips.length > 1,
-          mipLevelCount: Math.max(1, transcoded.value.mips.length)
+          mips: { kind: "packed", levelCount: Math.max(1, transcoded.value.mips.length) }
         }
       };
     } catch (error) {
@@ -1203,13 +1019,14 @@ async function loadTexturePack(input, ctx) {
         ok: true,
         value: {
           kind: "texture",
-          width: transcoded.value.width,
-          height: transcoded.value.height,
+          shape: {
+            viewDimension: "2d",
+            extent: { width: transcoded.value.width, height: transcoded.value.height }
+          },
           format: target,
           data,
           colorSpace,
-          mipmap: transcoded.value.mips.length > 1,
-          mipLevelCount: Math.max(1, transcoded.value.mips.length)
+          mips: { kind: "packed", levelCount: Math.max(1, transcoded.value.mips.length) }
         }
       };
     } catch (error) {
@@ -1234,18 +1051,23 @@ async function loadTexturePack(input, ctx) {
       };
     }
   }
-  const mipmap = payload.mipmap === true;
+  const shape = payloadTextureShape(payload);
+  const mips = payloadTextureMips(payload);
+  if (shape === void 0 || mips === void 0) {
+    return invalidPackAsset(
+      input,
+      "texture payload with a valid shape and mip policy"
+    );
+  }
   return {
     ok: true,
     value: {
       kind: "texture",
-      width,
-      height,
+      shape,
       format: payload.format ?? (colorSpace === "srgb" ? "rgba8unorm-srgb" : "rgba8unorm"),
       data: artifact.bytes,
       colorSpace,
-      mipmap,
-      mipLevelCount: mipmap ? numMipLevels({ width, height }) : 1
+      mips
     }
   };
 }
@@ -6899,16 +6721,13 @@ async function decodeImageBytes(bytes, mime, opts = {}) {
   }
   const dec = decoded.value;
   const format = colorSpace === "srgb" ? "rgba8unorm-srgb" : "rgba8unorm";
-  const mipLevelCount = mipmap ? numMipLevels({ width: dec.width, height: dec.height }) : 1;
   const pod = {
     kind: "texture",
-    width: dec.width,
-    height: dec.height,
+    shape: { viewDimension: "2d", extent: { width: dec.width, height: dec.height } },
     format,
     data: dec.bytes,
     colorSpace,
-    mipmap,
-    mipLevelCount
+    mips: mipmap ? { kind: "generate" } : { kind: "none" }
   };
   return ok(pod);
 }
@@ -8318,6 +8137,215 @@ function inspectMaterialRuntime(ready) {
     status: "Ready"
   };
 }
+var deviceCache = /* @__PURE__ */ new WeakMap();
+var MIPMAP_WGSL = `
+struct VsOut {
+  @builtin(position) clip : vec4<f32>,
+  @location(0)       uv   : vec2<f32>,
+};
+
+@vertex
+fn vs_main(@builtin(vertex_index) vid : u32) -> VsOut {
+  // 3 vertices forming an oversized triangle: (-1,-1), (-1,3), (3,-1)
+  var positions = array<vec2<f32>, 3>(
+    vec2<f32>(-1.0, -1.0),
+    vec2<f32>(-1.0,  3.0),
+    vec2<f32>( 3.0, -1.0),
+  );
+  let pos = positions[vid];
+  var out : VsOut;
+  out.clip = vec4<f32>(pos, 0.0, 1.0);
+  // NDC -> UV with Y-flip fused into a single MAD.
+  out.uv = pos * vec2<f32>(0.5, -0.5) + vec2<f32>(0.5);
+  return out;
+}
+
+@group(0) @binding(0) var src_sampler : sampler;
+@group(0) @binding(1) var src_texture : texture_2d<f32>;
+
+@fragment
+fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
+  return textureSample(src_texture, src_sampler, in.uv);
+}
+`;
+function numMipLevels(size) {
+  const max = Math.max(size.width, size.height);
+  if (max <= 1) return 1;
+  return Math.floor(Math.log2(max)) + 1;
+}
+function mipmapCacheSize(device) {
+  const cache = deviceCache.get(device);
+  return cache?.pipelines.size ?? 0;
+}
+async function getOrCreateMipmapPipeline(device, format, asyncCreateShaderModule) {
+  const cache = await ensureDeviceCache(device, asyncCreateShaderModule);
+  if (!cache.ok) return cache;
+  const existing = cache.value.pipelines.get(format);
+  if (existing !== void 0) {
+    return ok$1(existing);
+  }
+  const layoutRes = device.createPipelineLayout({
+    label: "mipmap-pl",
+    bindGroupLayouts: [cache.value.layout]
+  });
+  if (!layoutRes.ok) return layoutRes;
+  const pipelineRes = device.createRenderPipeline({
+    label: `mipmap-pipeline-${format}`,
+    layout: layoutRes.value,
+    vertex: { module: cache.value.module, entryPoint: "vs_main" },
+    fragment: {
+      module: cache.value.module,
+      entryPoint: "fs_main",
+      targets: [{ format }]
+    },
+    primitive: { topology: "triangle-list" }
+  });
+  if (!pipelineRes.ok) return pipelineRes;
+  cache.value.pipelines.set(format, pipelineRes.value);
+  return pipelineRes;
+}
+async function ensureDeviceCache(device, asyncCreateShaderModule) {
+  const existing = deviceCache.get(device);
+  if (existing !== void 0) return ok$1(existing);
+  const moduleRes = await asyncCreateShaderModule(device, {
+    code: MIPMAP_WGSL,
+    label: "mipmap-wgsl"
+  });
+  if (!moduleRes.ok) return moduleRes;
+  const samplerRes = device.createSampler({
+    magFilter: "linear",
+    minFilter: "linear",
+    mipmapFilter: "linear"
+  });
+  if (!samplerRes.ok) return samplerRes;
+  const FRAGMENT_STAGE = 2;
+  const layoutRes = device.createBindGroupLayout({
+    label: "mipmap-bgl",
+    entries: [
+      { binding: 0, visibility: FRAGMENT_STAGE, sampler: { type: "filtering" } },
+      {
+        binding: 1,
+        visibility: FRAGMENT_STAGE,
+        texture: { sampleType: "float", viewDimension: "2d" }
+      }
+    ]
+  });
+  if (!layoutRes.ok) return layoutRes;
+  const cache = {
+    sampler: samplerRes.value,
+    module: moduleRes.value,
+    layout: layoutRes.value,
+    pipelines: /* @__PURE__ */ new Map()
+  };
+  deviceCache.set(device, cache);
+  return ok$1(cache);
+}
+function recordMipmapBlit(device, texture, levels, pipeline, cache) {
+  const encoderRes = device.createCommandEncoder({ label: "mipmap-encoder" });
+  if (!encoderRes.ok) return encoderRes;
+  const encoder = encoderRes.value;
+  for (let i = 1; i < levels; i++) {
+    const srcViewRes = device.createTextureView(texture, {
+      baseMipLevel: i - 1,
+      mipLevelCount: 1,
+      dimension: "2d"
+    });
+    if (!srcViewRes.ok) return srcViewRes;
+    const dstViewRes = device.createTextureView(texture, {
+      baseMipLevel: i,
+      mipLevelCount: 1,
+      dimension: "2d"
+    });
+    if (!dstViewRes.ok) return dstViewRes;
+    const bindGroupRes = device.createBindGroup({
+      label: `mipmap-bg-${i}`,
+      layout: cache.layout,
+      entries: [
+        { binding: 0, resource: { kind: "sampler", value: cache.sampler } },
+        { binding: 1, resource: { kind: "textureView", value: srcViewRes.value } }
+      ]
+    });
+    if (!bindGroupRes.ok) return bindGroupRes;
+    const pass = encoder.beginRenderPass({
+      label: `mipmap-pass-${i}`,
+      colorAttachments: [
+        {
+          view: dstViewRes.value,
+          clearValue: { r: 0, g: 0, b: 0, a: 1 },
+          loadOp: "clear",
+          storeOp: "store"
+        }
+      ]
+    });
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, bindGroupRes.value);
+    pass.draw(3, 1, 0, 0);
+    pass.end();
+  }
+  const finishRes = encoder.finish();
+  if (!finishRes.ok) return finishRes;
+  return device.queue.submit([finishRes.value]);
+}
+function blitMipmapsSync(device, texture, descriptor) {
+  const levels = descriptor.levels ?? numMipLevels(descriptor);
+  if (levels <= 1) return ok$1(void 0);
+  const cache = deviceCache.get(device);
+  if (cache === void 0) {
+    return err(
+      new RhiError({
+        code: "rhi-not-available",
+        expected: "mipmap pipeline cache prewarmed for this device before blitMipmapsSync",
+        hint: "call prewarmMipmapPipeline(device, formats) at renderer.ready before the synchronous record-stage mipmap blit"
+      })
+    );
+  }
+  const pipeline = cache.pipelines.get(descriptor.format);
+  if (pipeline === void 0) {
+    return err(
+      new RhiError({
+        code: "rhi-not-available",
+        expected: `mipmap pipeline for format ${descriptor.format} prewarmed`,
+        hint: `format ${descriptor.format} was not prewarmed; add it to the prewarmMipmapPipeline format list at renderer.ready`
+      })
+    );
+  }
+  return recordMipmapBlit(device, texture, levels, pipeline, cache);
+}
+function encodeMipmapLevel(device, pass, sourceView, format) {
+  const cache = deviceCache.get(device);
+  if (cache === void 0) {
+    return err(
+      new RhiError({
+        code: "rhi-not-available",
+        expected: "mipmap pipeline cache prewarmed for the graph device before encoding",
+        hint: "call prewarmMipmapPipeline(device, formats) at renderer.ready"
+      })
+    );
+  }
+  const pipeline = cache.pipelines.get(format);
+  if (pipeline === void 0) {
+    return err(
+      new RhiError({
+        code: "rhi-not-available",
+        expected: `mipmap pipeline for format ${format} prewarmed`,
+        hint: `format ${format} was not prewarmed; add it to the renderer prewarm list`
+      })
+    );
+  }
+  const bindGroup = device.createBindGroup({
+    label: "mipmap-graph-bind-group",
+    layout: cache.layout,
+    entries: [
+      { binding: 0, resource: { kind: "sampler", value: cache.sampler } },
+      { binding: 1, resource: { kind: "textureView", value: sourceView } }
+    ]
+  });
+  if (!bindGroup.ok) return bindGroup;
+  pass.setPipeline(pipeline);
+  pass.setBindGroup(0, bindGroup.value);
+  pass.draw(3, 1, 0, 0);
+  return ok$1(void 0);
+}
 
 // src/plugin.ts
 function assetsPlugin(assets) {