@forgeax/engine-render 0.1.20 → 0.1.23

package/dist/chunk-HZUPSYW7.mjs

@@ -0,0 +1,1104 @@
+import { LifecycleConstructionError, RenderTargetDescriptorInvalidError } from './chunk-QODA5UKU.mjs';
+import { ok, err, derive } from '@forgeax/engine-types';
+import '@forgeax/engine-rhi';
+import { vec3 } from '@forgeax/engine-math';
+import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '@forgeax/engine-shader';
+
+var DeviceResourceRef = class {
+  kind;
+  owner;
+  generation;
+  value;
+  constructor(kind, owner, generation, value) {
+    this.kind = kind;
+    this.owner = owner;
+    this.generation = generation;
+    this.value = value;
+  }
+  isCurrent(scope) {
+    return scope.accepts(this);
+  }
+  isStale(scope) {
+    return !this.isCurrent(scope);
+  }
+};
+var DeviceScope = class _DeviceScope {
+  generation;
+  owner;
+  parent;
+  lifecycleState = "active";
+  resources = [];
+  children = [];
+  constructor(generation, owner, parent) {
+    this.generation = generation;
+    this.owner = owner;
+    this.parent = parent;
+    parent?.children.push(this);
+  }
+  static create(generation, owner) {
+    if (!Number.isSafeInteger(generation) || generation < 0) {
+      throw new RangeError("DeviceScope generation must be a non-negative safe integer.");
+    }
+    if (owner.length === 0) throw new TypeError("DeviceScope owner must not be empty.");
+    return new _DeviceScope(generation, owner);
+  }
+  get state() {
+    return this.lifecycleState;
+  }
+  get childrenSnapshot() {
+    return [...this.children];
+  }
+  /** Create a renderer-owned child scope without exposing a second device owner. */
+  createChild(owner) {
+    if (this.lifecycleState !== "active") {
+      throw new Error("Cannot create a child DeviceScope from an inactive scope.");
+    }
+    if (owner.length === 0) throw new TypeError("DeviceScope child owner must not be empty.");
+    return new _DeviceScope(this.generation, owner, this);
+  }
+  ref(kind, value) {
+    const ref = new DeviceResourceRef(kind, this.owner, this.generation, value);
+    this.resources.push({ ref, cleanup: () => void 0 });
+    return ref;
+  }
+  accepts(ref) {
+    return this.lifecycleState === "active" && ref.owner === this.owner && ref.generation === this.generation;
+  }
+  isAlive() {
+    return this.lifecycleState === "active";
+  }
+  resourceDelta() {
+    return this.resources.length;
+  }
+  /** @internal */
+  _adopt(kind, value, cleanup) {
+    const ref = new DeviceResourceRef(kind, this.owner, this.generation, value);
+    this.resources.push({
+      ref,
+      cleanup
+    });
+    return ref;
+  }
+  /** @internal */
+  _clearResources() {
+    const resources = this.resources.splice(0);
+    for (const resource of resources.reverse()) {
+      try {
+        const pending = resource.cleanup(resource.ref.value);
+        if (pending instanceof Promise) void pending.catch(() => void 0);
+      } catch {
+      }
+    }
+    return resources;
+  }
+  /** Mark an active child as retiring without releasing in-flight resources. */
+  beginRetire() {
+    if (this.lifecycleState === "active") this.lifecycleState = "retiring";
+  }
+  retire() {
+    if (this.lifecycleState !== "active" && this.lifecycleState !== "retiring") return;
+    this.lifecycleState = "retiring";
+    this._clearResources();
+    this.lifecycleState = "retired";
+  }
+  abandon() {
+    if (this.lifecycleState !== "active") return;
+    this.lifecycleState = "abandoned";
+    this._clearResources();
+  }
+  dispose() {
+    if (this.lifecycleState === "disposed") return;
+    this.lifecycleState = "disposed";
+    this._clearResources();
+  }
+  async replace(generation, resources) {
+    const replacement = new _DeviceScope(generation, this.owner, this);
+    const transaction = new LifecycleTransaction(replacement);
+    for (const resource of resources) transaction.add(resource);
+    const result = await transaction.commit();
+    if (!result.ok) {
+      replacement.abandon();
+      return result;
+    }
+    if (!this.isAlive()) {
+      replacement.dispose();
+      return transaction.failure("dispose");
+    }
+    this.retire();
+    return ok(replacement);
+  }
+  /** @internal */
+  _receipt() {
+    return {
+      owner: this.owner,
+      generation: this.generation,
+      resourceCount: this.resources.length
+    };
+  }
+};
+var LifecycleTransaction = class {
+  constructor(scope, options = {}) {
+    this.scope = scope;
+    this.options = options;
+  }
+  scope;
+  resources = [];
+  options;
+  committed = false;
+  add(spec) {
+    if (this.committed) throw new Error("LifecycleTransaction is already committed.");
+    this.resources.push(spec);
+    return this;
+  }
+  async commit() {
+    if (this.committed) return this.failure("create");
+    this.committed = true;
+    const created = [];
+    for (let index = 0; index < this.resources.length; index += 1) {
+      const spec = this.resources[index];
+      if (spec === void 0) continue;
+      try {
+        if (this.options.failureAt === index + 1) {
+          throw new Error(`injected lifecycle failure at ${index + 1}`);
+        }
+        const value = await spec.create();
+        if (!this.scope.isAlive()) {
+          await this.cleanupOne(spec, value, created);
+          return this.failure("dispose");
+        }
+        created.push({ spec, value });
+      } catch (cause) {
+        const cleanupFailures = await this.cleanupCreated(created);
+        return this.failure("create", spec.kind, cleanupFailures, cause);
+      }
+    }
+    if (!this.scope.isAlive()) {
+      const cleanupFailures = await this.cleanupCreated(created);
+      return this.failure("dispose", this.resources.at(-1)?.kind ?? "listener", cleanupFailures);
+    }
+    for (const item of created) this.scope._adopt(item.spec.kind, item.value, item.spec.cleanup);
+    return ok(this.scope);
+  }
+  failure(operation, resourceKind = this.resources.at(-1)?.kind ?? "listener", cleanupFailures = [], cause = void 0) {
+    return err({
+      primary: new LifecycleConstructionError({
+        owner: this.scope.owner,
+        generation: this.scope.generation,
+        operation,
+        resourceKind,
+        cause,
+        cleanupFailures,
+        receipt: this.scope._receipt()
+      }),
+      cleanupFailures,
+      receipt: this.scope._receipt()
+    });
+  }
+  async cleanupCreated(created) {
+    const failures = [];
+    for (let index = created.length - 1; index >= 0; index -= 1) {
+      const item = created[index];
+      if (item === void 0) continue;
+      try {
+        await item.spec.cleanup(item.value);
+      } catch (cause) {
+        failures.push({ resourceKind: item.spec.kind, cause });
+      }
+    }
+    return failures;
+  }
+  async cleanupOne(spec, value, created) {
+    await this.cleanupCreated(created);
+    try {
+      await spec.cleanup(value);
+    } catch {
+    }
+  }
+};
+
+// src/gpu-usage.ts
+var GPU_BUFFER_USAGE_VERTEX = 32;
+var GPU_BUFFER_USAGE_INDEX = 16;
+var GPU_BUFFER_USAGE_COPY_DST = 8;
+var GPU_BUFFER_USAGE_COPY_SRC = 4;
+var GPU_BUFFER_USAGE_UNIFORM = 64;
+var GPU_BUFFER_USAGE_STORAGE = 128;
+var GPU_BUFFER_USAGE_INDIRECT = 256;
+var GPU_BUFFER_USAGE_MAP_READ = 1;
+var GPU_BUFFER_USAGE_QUERY_RESOLVE = 512;
+
+// src/prepare/extended-lighting/resources.ts
+var EXTENDED_LIGHTING_TOPOLOGY = "extendedLighting";
+var IES_SLICE_CAPACITY = 32;
+var COOKIE_SLICE_CAPACITY = 32;
+var IES_SLICE_WIDTH = 256;
+var IES_SLICE_HEIGHT = 128;
+var COOKIE_SLICE_SIZE = 256;
+var COOKIE_MATRIX_BYTES = 32 * 16 * Float32Array.BYTES_PER_ELEMENT;
+var EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES = 20;
+function extendedLightingSampledTextureCapacityAvailable(maxSampledTexturesPerShaderStage) {
+  return maxSampledTexturesPerShaderStage !== void 0 && maxSampledTexturesPerShaderStage >= EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES;
+}
+function deriveExtendedLightingCapability(device) {
+  const maxSampledTextures = device.limits.maxSampledTexturesPerShaderStage;
+  if (!extendedLightingSampledTextureCapacityAvailable(maxSampledTextures)) {
+    return {
+      admitted: false,
+      topology: EXTENDED_LIGHTING_TOPOLOGY,
+      reason: `maxSampledTexturesPerShaderStage ${maxSampledTextures ?? 0} < ${EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES}`
+    };
+  }
+  const maxLayers = device.limits.maxTextureArrayLayers ?? 0;
+  const maxUniformBuffers = device.limits.maxUniformBuffersPerShaderStage ?? 0;
+  if (maxLayers < IES_SLICE_CAPACITY) {
+    return {
+      admitted: false,
+      topology: EXTENDED_LIGHTING_TOPOLOGY,
+      reason: `maxTextureArrayLayers ${maxLayers} < ${IES_SLICE_CAPACITY}`
+    };
+  }
+  if (maxUniformBuffers < 1) {
+    return {
+      admitted: false,
+      topology: EXTENDED_LIGHTING_TOPOLOGY,
+      reason: `maxUniformBuffersPerShaderStage ${maxUniformBuffers} < 1`
+    };
+  }
+  if (!device.caps.storageBuffer || !device.caps.rgba16floatRenderable || !device.caps.samplerAliasing) {
+    return {
+      admitted: false,
+      topology: EXTENDED_LIGHTING_TOPOLOGY,
+      reason: "required storage-buffer, rgba16float, or sampler capability is unavailable"
+    };
+  }
+  return { admitted: true, topology: EXTENDED_LIGHTING_TOPOLOGY, reason: void 0 };
+}
+function worldEntityKey(worldId, entityKey) {
+  return worldId * 4294967296 + entityKey;
+}
+var ZERO_CAMERA_CLEAR_FALLBACK = [0, 0, 0, 1];
+var textureIdentities = /* @__PURE__ */ new WeakMap();
+var nextTextureIdentity = 1;
+function getTextureIdentity(texture) {
+  const object = texture;
+  const existing = textureIdentities.get(object);
+  if (existing !== void 0) return existing;
+  const identity = nextTextureIdentity++;
+  textureIdentities.set(object, identity);
+  return identity;
+}
+function validateGraphTargetCaptureReadback(input) {
+  const { bytes, expectedByteLength, sentinel, allowZero = false } = input;
+  if (bytes.byteLength !== expectedByteLength)
+    return { ok: false, code: "capture-readback-length" };
+  if (sentinel?.every((value, index) => bytes[index] === value)) {
+    return { ok: false, code: "capture-readback-untouched-sentinel" };
+  }
+  if (!allowZero && bytes.every((value) => value === 0)) {
+    return { ok: false, code: "capture-readback-empty" };
+  }
+  for (let index = 0; index + 1 < bytes.length; index += 2) {
+    const exponent = (bytes[index + 1] ?? 0) >>> 2 & 31;
+    if (exponent === 31) return { ok: false, code: "capture-readback-non-finite" };
+  }
+  return { ok: true };
+}
+function makeZeroCameraFallbackSnapshot() {
+  const identityWorld = new Float32Array(16);
+  identityWorld[0] = 1;
+  identityWorld[5] = 1;
+  identityWorld[10] = 1;
+  identityWorld[15] = 1;
+  return {
+    position: vec3.create(0, 0, 0),
+    world: identityWorld,
+    fov: Math.PI / 4,
+    aspect: 1,
+    near: 0.1,
+    far: 100,
+    // feat-20260613 M6 / w20: synthetic camera defaults to perspective so
+    // the CSM extract path stays consistent with the previously-implicit
+    // perspective shape (unchanged behavior; explicit field).
+    projection: "perspective",
+    orthoLeft: -1,
+    orthoRight: 1,
+    orthoBottom: -1,
+    orthoTop: 1,
+    tonemap: "none",
+    exposure: 1,
+    whitePoint: 4,
+    antialias: "none",
+    bloom: "off",
+    bloomThreshold: 1,
+    bloomIntensity: 1,
+    bloomBlurRadius: 4,
+    clearColor: ZERO_CAMERA_CLEAR_FALLBACK
+  };
+}
+
+// src/gpu-stage.ts
+var GPU_SHADER_STAGE_VERTEX = 1;
+var GPU_SHADER_STAGE_FRAGMENT = 2;
+var GPU_SHADER_STAGE_COMPUTE = 4;
+var BGL_ONLY_SPEC_STUB = Object.freeze({
+  shader: { id: "", passKind: "forward", variantSet: void 0 },
+  attachments: { colorFormats: [], depthFormat: void 0, sampleCount: 1 },
+  geometry: { topology: "triangle-list", vertexLayout: {} },
+  renderState: void 0
+});
+function buildPbrMaterialUserRegionEntries(paramSchema = DEFAULT_STANDARD_PBR_PARAM_SCHEMA) {
+  const derived = derive(paramSchema);
+  const entries = derived.bglEntries.map(
+    (entry) => ({
+      binding: entry.binding,
+      visibility: entry.visibility,
+      ...entry.buffer === void 0 ? {} : { buffer: entry.buffer },
+      ...entry.sampler === void 0 ? {} : { sampler: entry.sampler },
+      ...entry.texture === void 0 ? {} : { texture: entry.texture },
+      ...entry.storageTexture === void 0 ? {} : { storageTexture: entry.storageTexture }
+    })
+  );
+  const ubo = entries[0];
+  if (ubo !== void 0 && ubo.binding === 0 && ubo.buffer?.type === "uniform") {
+    entries[0] = {
+      binding: 0,
+      visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
+      buffer: { type: "uniform", hasDynamicOffset: true }
+    };
+  }
+  return entries;
+}
+function appendInjection(bgl, kind) {
+  const start = bgl.length;
+  switch (kind) {
+    case "ibl":
+      return [
+        // binding start+0: irradianceMap (texture_cube)
+        {
+          binding: start,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          texture: { sampleType: "float", viewDimension: "cube" }
+        },
+        // binding start+1: irradianceSampler
+        {
+          binding: start + 1,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          sampler: { type: "filtering" }
+        },
+        // binding start+2: prefilterMap (texture_cube)
+        {
+          binding: start + 2,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          texture: { sampleType: "float", viewDimension: "cube" }
+        },
+        // binding start+3: prefilterSampler
+        {
+          binding: start + 3,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          sampler: { type: "filtering" }
+        },
+        // binding start+4: brdfLut (texture_2d)
+        {
+          binding: start + 4,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          texture: { sampleType: "float", viewDimension: "2d" }
+        },
+        // binding start+5: brdfLutSampler
+        {
+          binding: start + 5,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          sampler: { type: "filtering" }
+        },
+        // binding start+6: uniform { intensity: f32 }
+        {
+          binding: start + 6,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          buffer: { type: "uniform" }
+        }
+      ];
+    case "lightmap":
+      return [
+        // emissive sampler + texture pair
+        {
+          binding: start,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          sampler: { type: "filtering" }
+        },
+        {
+          binding: start + 1,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          texture: { sampleType: "float", viewDimension: "2d" }
+        },
+        // occlusion sampler + texture pair
+        {
+          binding: start + 2,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          sampler: { type: "filtering" }
+        },
+        {
+          binding: start + 3,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          texture: { sampleType: "float", viewDimension: "2d" }
+        }
+      ];
+    case "shadow":
+      return [
+        {
+          binding: start,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          sampler: { type: "comparison" }
+        },
+        {
+          binding: start + 1,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          texture: { sampleType: "depth", viewDimension: "2d" }
+        }
+      ];
+    case "transmission":
+      return [
+        {
+          binding: start,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          sampler: { type: "filtering" }
+        },
+        {
+          binding: start + 1,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          texture: { sampleType: "float", viewDimension: "2d" }
+        }
+      ];
+  }
+}
+function buildPbrViewBglEntries(caps) {
+  const entries = [
+    {
+      binding: 0,
+      visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
+      // View captures use the same bind group with a per-face view slot.
+      // Keeping this dynamic is also valid for the display slot at offset 0.
+      buffer: { type: "uniform", hasDynamicOffset: true }
+    },
+    {
+      binding: 3,
+      visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
+      texture: { sampleType: "depth", viewDimension: "2d" }
+    },
+    {
+      binding: 4,
+      visibility: GPU_SHADER_STAGE_FRAGMENT,
+      sampler: { type: "comparison" }
+    },
+    // feat-20260612-point-light-shadows-urp-hdrp Round-2 F-1: point shadow
+    // cube_array depth atlas. Bound to either the real ShadowAtlas
+    // cube_array view (when point shadows are active) or a 1x1x6 fallback
+    // cube_array view cleared to 1.0 (fully lit). Visibility is FRAGMENT
+    // only -- the directional binding 3 is VERTEX|FRAGMENT for shadow
+    // probe-debug sampling, but the cube atlas has no host-side probe path.
+    {
+      binding: 5,
+      visibility: GPU_SHADER_STAGE_FRAGMENT,
+      texture: { sampleType: "depth", viewDimension: "cube-array" }
+    },
+    // feat-20260612-point-light-shadows-urp-hdrp Round-2 F-1: point shadow
+    // params UBO. Carries `array<vec4<f32>, 4>` = 64 B with one lane per
+    // shadow-casting point light slot (shadowAtlasLayer in [0, 4)). Each
+    // lane stores `(near, far, 1/(far-near), 0)` so the fragment-shader
+    // depth-ref reconstruction (lighting-punctual.wgsl evalPointShadowed)
+    // can avoid sampling DirectLightSlot for the URP path. The shared
+    // DirectLightSlot metadata remains the identity owner, so binding 6 is
+    // unused on HDRP shaders even though the BGL declares it (charter P4 single SSOT
+    // BGL across pipelines; the HDRP variant simply doesn't reference the
+    // binding in WGSL, which is allowed).
+    {
+      binding: 6,
+      visibility: GPU_SHADER_STAGE_FRAGMENT,
+      buffer: { type: "uniform" }
+    },
+    // feat-20260613-csm-cascaded-shadow-maps M5 / w28: shadowCasterCascade
+    // UBO (16 B). Carries the 0-based cascade index of the shadow pass
+    // currently being rasterized so `shadow_caster.wgsl` can index into
+    // `view.lightViewProj_X` per cascade. Shifted from binding 5 to
+    // binding 7 on 2026-06-13 to make room for point-shadow bindings 5/6
+    // (they predate this feat in main; CSM's slot was the optimal-yield
+    // give since point-shadow needs FRAGMENT-only and the cascade UBO
+    // needs vertex-stage too — keeping cascade higher avoids interleaving
+    // visibility flags within the contiguous shadow-binding cluster).
+    {
+      binding: 7,
+      visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
+      buffer: { type: "uniform" }
+    },
+    // feat-20260625-spot-light-shadow-mapping M3 / w14 (D-5): spot shadow
+    // atlas. A single `texture_depth_2d` holding up to 4 spot shadows in a 2x2
+    // tile grid (urp-pipeline.ts spotShadowDepth). FRAGMENT-only — the spot
+    // shadow factor is reconstructed at fragment time via perspective-divide in
+    // `evalSpotShadowed` (lighting-punctual.wgsl).
+    //
+    // ALWAYS-ON (no caps gate, unlike the point cube_array atlas at binding 5
+    // which rides POINT_SHADOW_AVAILABLE): spot uses `texture_depth_2d` which is
+    // compat-safe in every WebGPU profile, so the binding is unconditionally
+    // declared. The matching WGSL declaration is `spotShadowMap` at @group(0)
+    // binding 8 in common.wgsl (also unconditional) — the two must stay in
+    // lock-step or WebGPU validation rejects the bind group at smoke time
+    // (memory: BGL shape mismatch is a browser-path-only bug). No binding 9
+    // sampler: spot reuses the comparison sampler at binding 4.
+    // feat-20260625-spot-light-shadow-mapping M3 / w14 (D-5): spot shadow 2D
+    // atlas, the LAST view-BG binding. The per-spot fragment-read perspective
+    // lightViewProj matrices that w24 originally declared at a standalone
+    // binding 9 uniform buffer were folded into the View UBO (binding 0,
+    // `view.spotLightViewProj`) in w25 (scope-amend webkit-fallback): the
+    // standalone binding pushed the WebGL2 fallback fragment uniform-buffer
+    // count to 12, over GLES 3.0's `max_uniform_buffers_per_shader_stage = 11`,
+    // crashing pipeline-layout creation on the compat path (this feat's target).
+    {
+      binding: 8,
+      visibility: GPU_SHADER_STAGE_FRAGMENT,
+      texture: { sampleType: "depth", viewDimension: "2d" }
+    }
+  ];
+  const extendedLighting = caps.extendedLighting ?? true;
+  if (extendedLighting) {
+    entries.push(
+      {
+        binding: 9,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        sampler: { type: "filtering" }
+      },
+      {
+        binding: 11,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: "float", viewDimension: "2d-array" }
+      },
+      {
+        binding: 12,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: "float", viewDimension: "2d-array" }
+      },
+      {
+        binding: 13,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: "float", viewDimension: "2d" }
+      },
+      {
+        binding: 14,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: "float", viewDimension: "2d" }
+      },
+      {
+        binding: 15,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        buffer: { type: "uniform" }
+      }
+    );
+  } else if (caps.projectorAvailable !== false) {
+    entries.push(
+      {
+        binding: 11,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: "float", viewDimension: "2d" }
+      },
+      {
+        binding: 12,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        sampler: { type: "filtering" }
+      }
+    );
+  }
+  entries.push({
+    binding: 10,
+    visibility: GPU_SHADER_STAGE_VERTEX,
+    buffer: { type: "uniform", hasDynamicOffset: true }
+  });
+  return entries;
+}
+function buildPbrPipelineLayouts(device, caps) {
+  const viewBglRes = device.createBindGroupLayout(
+    buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, { kind: "pbr-view", caps })
+  );
+  if (!viewBglRes.ok) throw viewBglRes.error;
+  const materialBglRes = device.createBindGroupLayout(
+    buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, { kind: "pbr-material-merged" })
+  );
+  if (!materialBglRes.ok) throw materialBglRes.error;
+  const meshArrayBglRes = device.createBindGroupLayout(
+    buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, { kind: "pbr-mesh-array", caps })
+  );
+  if (!meshArrayBglRes.ok) throw meshArrayBglRes.error;
+  const instancesBglRes = device.createBindGroupLayout(
+    buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, {
+      kind: "pbr-instances",
+      caps: { ...caps, probeBlend: false }
+    })
+  );
+  if (!instancesBglRes.ok) throw instancesBglRes.error;
+  const probeInstancesBglRes = caps.storageBuffer ? device.createBindGroupLayout(
+    buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, {
+      kind: "pbr-instances",
+      caps: { ...caps, probeBlend: true }
+    })
+  ) : { ok: true, value: instancesBglRes.value };
+  if (!probeInstancesBglRes.ok) throw probeInstancesBglRes.error;
+  const layouts = [
+    viewBglRes.value,
+    materialBglRes.value,
+    meshArrayBglRes.value,
+    instancesBglRes.value
+  ];
+  const pipelineLayoutRes = device.createPipelineLayout({
+    label: "pbr-pl",
+    bindGroupLayouts: layouts
+  });
+  if (!pipelineLayoutRes.ok) throw pipelineLayoutRes.error;
+  const probeLayouts = [viewBglRes.value, materialBglRes.value, meshArrayBglRes.value, probeInstancesBglRes.value];
+  let probePipelineLayout = null;
+  if (caps.storageBuffer) {
+    const probePipelineLayoutRes = device.createPipelineLayout({
+      label: "pbr-probe-pl",
+      bindGroupLayouts: probeLayouts
+    });
+    if (!probePipelineLayoutRes.ok) throw probePipelineLayoutRes.error;
+    probePipelineLayout = probePipelineLayoutRes.value;
+  }
+  return {
+    pipelineLayout: pipelineLayoutRes.value,
+    viewBgl: viewBglRes.value,
+    materialBgl: materialBglRes.value,
+    meshArrayBgl: meshArrayBglRes.value,
+    instancesBgl: instancesBglRes.value,
+    probeInstancesBgl: probeInstancesBglRes.value,
+    probePipelineLayout,
+    bindGroupLayouts: layouts
+  };
+}
+var SKIN_MATERIAL_SHADER_ID = "forgeax::pbr-skin";
+var SHADOW_CASTER_SHADER_ID = "forgeax::default-shadow-caster";
+function shadowCasterVariantSet(storageBuffer, skinned) {
+  const skinningDisabled = !skinned;
+  if (storageBuffer && skinningDisabled) return "";
+  return `SKINNING_DISABLED=${String(skinningDisabled)}+STORAGE_BUFFER_AVAILABLE=${String(storageBuffer)}`;
+}
+function resolvePipelineGroup2Contract(source) {
+  const withoutComments = source.replace(/\/\*[\s\S]*?\*\//gu, "").replace(/\/\/.*$/gmu, "");
+  const bindings = [
+    ...withoutComments.matchAll(/@group\s*\(\s*2\s*\)\s*@binding\s*\(\s*(\d+)\s*\)/gu)
+  ].map((match) => Number(match[1]));
+  const hasSkinBindings = bindings.includes(1) || bindings.includes(2);
+  const hasClusterBindings = bindings.some((binding) => binding >= 3);
+  if (hasSkinBindings && hasClusterBindings) return "skin-cluster";
+  if (hasSkinBindings) return "skin";
+  if (hasClusterBindings) return "cluster";
+  return "mesh";
+}
+function isStandardPbrMaterialShader(shaderId) {
+  return shaderId === "forgeax::default-standard-pbr" || shaderId === SKIN_MATERIAL_SHADER_ID || shaderId === "forgeax::default-standard-pbr-skin";
+}
+function buildPbrSkinLayouts(device, caps, pbr) {
+  const skinMeshArrayBglRes = device.createBindGroupLayout(
+    buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, {
+      kind: "pbr-skin-mesh-array",
+      caps
+    })
+  );
+  if (!skinMeshArrayBglRes.ok) throw skinMeshArrayBglRes.error;
+  const layouts = [
+    pbr.viewBgl,
+    pbr.materialBgl,
+    skinMeshArrayBglRes.value,
+    pbr.instancesBgl
+  ];
+  const pipelineLayoutRes = device.createPipelineLayout({
+    label: "pbr-skin-pl",
+    bindGroupLayouts: layouts
+  });
+  if (!pipelineLayoutRes.ok) throw pipelineLayoutRes.error;
+  const probeLayouts = [pbr.viewBgl, pbr.materialBgl, skinMeshArrayBglRes.value, pbr.probeInstancesBgl];
+  let probePipelineLayout = null;
+  if (caps.storageBuffer) {
+    const probePipelineLayoutRes = device.createPipelineLayout({
+      label: "pbr-skin-probe-pl",
+      bindGroupLayouts: probeLayouts
+    });
+    if (!probePipelineLayoutRes.ok) throw probePipelineLayoutRes.error;
+    probePipelineLayout = probePipelineLayoutRes.value;
+  }
+  return {
+    pipelineLayout: pipelineLayoutRes.value,
+    viewBgl: pbr.viewBgl,
+    materialBgl: pbr.materialBgl,
+    meshArrayBgl: skinMeshArrayBglRes.value,
+    instancesBgl: pbr.instancesBgl,
+    probeInstancesBgl: pbr.probeInstancesBgl,
+    probePipelineLayout,
+    bindGroupLayouts: layouts
+  };
+}
+function createPbrSkinMeshBindGroupEntries(meshBuffer, meshSize, paletteBuffer, paletteWindowBytes) {
+  return [
+    {
+      binding: 0,
+      resource: { kind: "buffer", value: { buffer: meshBuffer, offset: 0, size: meshSize } }
+    },
+    ...[1, 2].map((binding) => ({
+      binding,
+      resource: {
+        kind: "buffer",
+        value: {
+          buffer: paletteBuffer,
+          offset: 0,
+          size: paletteWindowBytes
+        }
+      }
+    }))
+  ];
+}
+function pbrSkinMeshDynamicOffsets(meshOffset, paletteOffset) {
+  return [meshOffset, paletteOffset, paletteOffset];
+}
+var SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET = "";
+function createHdrpBindGroupLayoutDescriptor() {
+  const meshBufType = "read-only-storage";
+  const clusterBufType = "read-only-storage";
+  return {
+    label: "hdrp-unified-bgl-group2",
+    entries: [
+      {
+        binding: 0,
+        // Standard fragment lighting (transmission/refraction and clustered
+        // evaluation) reads the same mesh transform window as the vertex
+        // stage. Keep this visibility in the HDRP descriptor aligned with
+        // the URP mesh-array descriptor; restricting it to vertex makes the
+        // HDRP pipeline invalid when fs_main accesses `meshes[0]`.
+        visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
+        buffer: { type: meshBufType, hasDynamicOffset: true }
+      },
+      // Bindings 1 and 2 stay absent for the URP physical isolation gap.
+      {
+        binding: 3,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        buffer: { type: clusterBufType, hasDynamicOffset: false }
+      },
+      {
+        binding: 4,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        buffer: { type: clusterBufType, hasDynamicOffset: false }
+      },
+      {
+        binding: 5,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        buffer: { type: clusterBufType, hasDynamicOffset: false }
+      },
+      {
+        binding: 6,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        buffer: { type: "uniform", hasDynamicOffset: false }
+      },
+      {
+        binding: 7,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: "float", viewDimension: "2d", multisampled: false }
+      },
+      {
+        binding: 8,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        sampler: { type: "filtering" }
+      }
+    ]
+  };
+}
+function createHdrpSkinBindGroupLayoutDescriptor() {
+  const base = createHdrpBindGroupLayoutDescriptor();
+  const baseEntries = base.entries;
+  if (baseEntries === void 0 || baseEntries[0] === void 0) {
+    throw new Error("HDRP base group(2) layout must declare mesh binding 0");
+  }
+  const paletteType = "read-only-storage";
+  return {
+    label: "hdrp-skin-unified-bgl-group2",
+    entries: [
+      baseEntries[0],
+      {
+        binding: 1,
+        visibility: GPU_SHADER_STAGE_VERTEX,
+        buffer: { type: paletteType, hasDynamicOffset: true }
+      },
+      {
+        binding: 2,
+        visibility: GPU_SHADER_STAGE_VERTEX,
+        buffer: { type: paletteType, hasDynamicOffset: true }
+      },
+      ...baseEntries.slice(1)
+    ]
+  };
+}
+function resolveMaterialParamSchema(spec, options) {
+  if (options.materialParamSchema !== void 0) return options.materialParamSchema;
+  if (options.registry !== void 0) {
+    const lookup = options.registry.findMaterialArtifact(spec.shader.id);
+    if (lookup.ok) return lookup.value.paramSchema;
+  }
+  return void 0;
+}
+function buildBindGroupLayoutDescriptor(spec, options) {
+  switch (options.kind) {
+    case "pbr-view": {
+      const caps = options.caps ?? { };
+      return {
+        label: "pbr-view-bgl",
+        entries: buildPbrViewBglEntries(caps)
+      };
+    }
+    case "pbr-mesh-array": {
+      const caps = options.caps ?? { storageBuffer: true };
+      const meshBufType = caps.storageBuffer ? "read-only-storage" : "uniform";
+      return {
+        label: "pbr-mesh-array-bgl",
+        entries: [
+          {
+            binding: 0,
+            visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
+            buffer: { type: meshBufType, hasDynamicOffset: true }
+          }
+        ]
+      };
+    }
+    case "pbr-instances": {
+      const caps = options.caps ?? { storageBuffer: true };
+      const meshBufType = caps.storageBuffer ? "read-only-storage" : "uniform";
+      const entries = [
+        {
+          binding: 0,
+          visibility: GPU_SHADER_STAGE_VERTEX,
+          buffer: { type: meshBufType, hasDynamicOffset: false }
+        },
+        ...caps.probeBlend === true ? [
+          {
+            // Per-object fragment lane; the record is always exactly 160B.
+            binding: 1,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            buffer: { type: meshBufType, hasDynamicOffset: true }
+          }
+        ] : []
+      ];
+      return {
+        label: caps.probeBlend === true ? "pbr-probe-instances-bgl" : "pbr-instances-bgl",
+        entries: entries.map(
+          (entry) => entry.binding === 0 ? {
+            ...entry,
+            // Standard transmission reads the same per-instance transform in
+            // fs_main to convert glTF unit-space thickness into world metres.
+            visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT
+          } : entry
+        )
+      };
+    }
+    case "pbr-skin-mesh-array": {
+      const caps = options.caps ?? { storageBuffer: true };
+      const meshBufType = caps.storageBuffer ? "read-only-storage" : "uniform";
+      return {
+        label: "pbr-skin-mesh-array-bgl",
+        entries: [
+          {
+            binding: 0,
+            visibility: GPU_SHADER_STAGE_VERTEX,
+            buffer: { type: meshBufType, hasDynamicOffset: true }
+          },
+          {
+            binding: 1,
+            visibility: GPU_SHADER_STAGE_VERTEX,
+            buffer: { type: meshBufType, hasDynamicOffset: true }
+          },
+          {
+            binding: 2,
+            visibility: GPU_SHADER_STAGE_VERTEX,
+            buffer: { type: meshBufType, hasDynamicOffset: true }
+          }
+        ]
+      };
+    }
+    case "pbr-material-merged": {
+      const resolvedSchema = resolveMaterialParamSchema(spec, options);
+      const userRegion = buildPbrMaterialUserRegionEntries(resolvedSchema);
+      const afterIbl = [...userRegion, ...appendInjection(userRegion, "ibl")];
+      const merged = [...afterIbl, ...appendInjection(afterIbl, "transmission")];
+      return {
+        label: "pbr-material-skylight-bgl",
+        entries: merged
+      };
+    }
+    case "unlit-material": {
+      const resolvedSchema = resolveMaterialParamSchema(spec, options);
+      return {
+        label: "unlit-material-bgl",
+        entries: buildPbrMaterialUserRegionEntries(resolvedSchema)
+      };
+    }
+    case "hdrp-7-slot": {
+      const desc = createHdrpBindGroupLayoutDescriptor();
+      return {
+        label: desc.label ?? "hdrp-unified-bgl-group2",
+        entries: [...desc.entries ?? []]
+      };
+    }
+    case "fullscreen-post": {
+      return {
+        label: "fullscreen-post-bgl",
+        entries: buildFullscreenPostInputEntries(spec)
+      };
+    }
+    case "fullscreen-post-with-params": {
+      return {
+        label: "fullscreen-post-with-params-bgl",
+        entries: [
+          ...buildFullscreenPostInputEntries(spec),
+          {
+            binding: 2,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            buffer: { type: "uniform" }
+          }
+        ]
+      };
+    }
+    case "fullscreen-post-with-scene-depth": {
+      return {
+        label: "fullscreen-post-with-scene-depth-bgl",
+        entries: [
+          ...buildFullscreenPostInputEntries(spec),
+          {
+            binding: 2,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            buffer: { type: "uniform" }
+          },
+          {
+            binding: 3,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            texture: { sampleType: "depth", viewDimension: "2d" }
+          },
+          {
+            binding: 4,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            sampler: { type: "non-filtering" }
+          }
+        ]
+      };
+    }
+    case "fullscreen-post-with-scene-depth-msaa": {
+      return {
+        label: "fullscreen-post-with-scene-depth-msaa-bgl",
+        entries: [
+          ...buildFullscreenPostInputEntries(spec),
+          {
+            binding: 2,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            buffer: { type: "uniform" }
+          },
+          {
+            binding: 3,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            texture: { sampleType: "depth", viewDimension: "2d", multisampled: true }
+          },
+          {
+            binding: 4,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            sampler: { type: "non-filtering" }
+          }
+        ]
+      };
+    }
+  }
+}
+function buildFullscreenPostInputEntries(spec) {
+  const inputFormat = spec.attachments.depthFormat ?? spec.attachments.colorFormats[0];
+  const sampleType = inputFormat === "depth32float" || inputFormat === "depth24plus" || inputFormat === "depth24plus-stencil8" || inputFormat === "depth16unorm" ? "depth" : inputFormat === "r32float" ? "unfilterable-float" : "float";
+  return [
+    {
+      binding: 0,
+      visibility: GPU_SHADER_STAGE_FRAGMENT,
+      texture: { sampleType, viewDimension: "2d" }
+    },
+    {
+      binding: 1,
+      visibility: GPU_SHADER_STAGE_FRAGMENT,
+      sampler: {
+        type: sampleType === "depth" ? "comparison" : "filtering"
+      }
+    }
+  ];
+}
+
+// src/scene/probe-blend-record.ts
+var PROBE_BLEND_RECORD_BYTE_SIZE = 160;
+var PROBE_BLEND_RECORD_STRIDE = 256;
+var PROBE_BLEND_RECORD_CAPACITY = 64;
+function probeBlendRecordOffset(objectKey) {
+  if (!Number.isInteger(objectKey) || objectKey < 0) {
+    throw new Error("probe blend record requires a non-negative object key");
+  }
+  return (objectKey + 1) * PROBE_BLEND_RECORD_STRIDE;
+}
+
+// src/targets/material-source.ts
+var sourceBindings = /* @__PURE__ */ new WeakMap();
+function sourceToken() {
+  return Object.freeze({});
+}
+function resolveRenderTargetMaterialSource(source) {
+  return sourceBindings.get(source);
+}
+function invalid(field, value, expected) {
+  return {
+    ok: false,
+    error: new RenderTargetDescriptorInvalidError({ field, value, expected })
+  };
+}
+function createRenderTargetMaterialSource(target, descriptor, options) {
+  if (options.aspect !== "color") return invalid("aspect", options.aspect, "color");
+  if (options.dimension !== descriptor.shape) {
+    return invalid("dimension", options.dimension, `dimension matches ${descriptor.shape}`);
+  }
+  const mipCount = descriptor.mipLevels === 1 ? 1 : Math.floor(Math.log2(Math.max(descriptor.width, descriptor.height))) + 1;
+  if (!Number.isInteger(options.mipLevel) || options.mipLevel < 0 || options.mipLevel >= mipCount) {
+    return invalid("mipLevel", options.mipLevel, `an admitted mip level below ${mipCount}`);
+  }
+  if (!Number.isInteger(options.generation) || options.generation < 0) {
+    return invalid("generation", options.generation, "a non-negative device generation");
+  }
+  const result = {
+    ok: true,
+    value: Object.freeze({
+      source: sourceToken(),
+      target,
+      generation: options.generation,
+      shape: descriptor.shape,
+      format: descriptor.format,
+      view: Object.freeze({
+        dimension: options.dimension,
+        mipLevel: options.mipLevel,
+        resolveRequired: descriptor.sampleCount === 4
+      })
+    })
+  };
+  sourceBindings.set(result.value.source, result.value);
+  return result;
+}
+
+// src/systems/pass-selector.ts
+function matchPass(tags, selector) {
+  if (Object.keys(selector).length === 0) return true;
+  for (const [key, allowedValues] of Object.entries(selector)) {
+    const passValue = tags[key];
+    if (passValue === void 0) return false;
+    if (allowedValues.length === 0) return false;
+    if (!allowedValues.includes(passValue)) return false;
+  }
+  return true;
+}
+function selectPasses(passes, selector) {
+  if (Object.keys(selector).length === 0) return passes;
+  return passes.filter(
+    (p) => matchPass(p.renderState?.tags ?? {}, selector)
+  );
+}
+
+export { COOKIE_MATRIX_BYTES, COOKIE_SLICE_CAPACITY, COOKIE_SLICE_SIZE, DeviceScope, EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES, EXTENDED_LIGHTING_TOPOLOGY, GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_COPY_SRC, GPU_BUFFER_USAGE_INDEX, GPU_BUFFER_USAGE_INDIRECT, GPU_BUFFER_USAGE_MAP_READ, GPU_BUFFER_USAGE_QUERY_RESOLVE, GPU_BUFFER_USAGE_STORAGE, GPU_BUFFER_USAGE_UNIFORM, GPU_BUFFER_USAGE_VERTEX, GPU_SHADER_STAGE_COMPUTE, GPU_SHADER_STAGE_FRAGMENT, GPU_SHADER_STAGE_VERTEX, IES_SLICE_CAPACITY, IES_SLICE_HEIGHT, IES_SLICE_WIDTH, PROBE_BLEND_RECORD_BYTE_SIZE, PROBE_BLEND_RECORD_CAPACITY, PROBE_BLEND_RECORD_STRIDE, SHADOW_CASTER_SHADER_ID, SKIN_MATERIAL_SHADER_ID, SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET, buildBindGroupLayoutDescriptor, buildPbrMaterialUserRegionEntries, buildPbrPipelineLayouts, buildPbrSkinLayouts, createHdrpBindGroupLayoutDescriptor, createHdrpSkinBindGroupLayoutDescriptor, createPbrSkinMeshBindGroupEntries, createRenderTargetMaterialSource, deriveExtendedLightingCapability, extendedLightingSampledTextureCapacityAvailable, getTextureIdentity, isStandardPbrMaterialShader, makeZeroCameraFallbackSnapshot, matchPass, pbrSkinMeshDynamicOffsets, probeBlendRecordOffset, resolvePipelineGroup2Contract, resolveRenderTargetMaterialSource, selectPasses, shadowCasterVariantSet, validateGraphTargetCaptureReadback, worldEntityKey };
+//# sourceMappingURL=chunk-HZUPSYW7.mjs.map
+//# sourceMappingURL=chunk-HZUPSYW7.mjs.map