@forgeax/engine-render 0.1.7 → 0.1.19

package/dist/chunk-RXZ3RGOU.mjs

@@ -0,0 +1,53 @@
+import { ResourceInvalidValueError } from '@forgeax/engine-ecs/projection';
+import { err, ok } from '@forgeax/engine-types';
+
+// src/systems/transparent-sort-config.ts
+var TRANSPARENT_SORT_CONFIG_KEY = "TransparentSortConfig";
+var TRANSPARENT_SORT_MODE_LAYER_Z = 0;
+var TRANSPARENT_SORT_MODE_LAYER_Y = 1;
+var TRANSPARENT_SORT_MODE_LAYER_YZ = 2;
+var TRANSPARENT_SORT_MODE_DISTANCE = 3;
+var TransparentSort = Object.freeze({
+  layerZ: TRANSPARENT_SORT_MODE_LAYER_Z,
+  layerY: TRANSPARENT_SORT_MODE_LAYER_Y,
+  layerYZ: TRANSPARENT_SORT_MODE_LAYER_YZ,
+  distance: TRANSPARENT_SORT_MODE_DISTANCE,
+  configure: setTransparentSortConfig
+});
+var DEFAULT_CONFIG = Object.freeze({
+  mode: TRANSPARENT_SORT_MODE_LAYER_Z,
+  yzAlpha: 1
+});
+var VALID_MODES = /* @__PURE__ */ new Set([
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_YZ,
+  TRANSPARENT_SORT_MODE_DISTANCE
+]);
+var EXPECTED_MODE = "mode \u2208 {0, 1, 2, 3}";
+var HINT_MODE = "0=layer-z, 1=layer-y, 2=layer-yz, 3=distance";
+function getTransparentSortConfig(world) {
+  if (!world.hasResource(TRANSPARENT_SORT_CONFIG_KEY)) {
+    return DEFAULT_CONFIG;
+  }
+  return world.getResource(TRANSPARENT_SORT_CONFIG_KEY);
+}
+function setTransparentSortConfig(world, cfg) {
+  if (!VALID_MODES.has(cfg.mode)) {
+    return err(
+      new ResourceInvalidValueError(EXPECTED_MODE, HINT_MODE, {
+        receivedMode: cfg.mode,
+        receivedKey: TRANSPARENT_SORT_CONFIG_KEY
+      })
+    );
+  }
+  world.insertResource(TRANSPARENT_SORT_CONFIG_KEY, {
+    mode: cfg.mode,
+    yzAlpha: cfg.yzAlpha
+  });
+  return ok(void 0);
+}
+
+export { TRANSPARENT_SORT_MODE_DISTANCE, TRANSPARENT_SORT_MODE_LAYER_Y, TRANSPARENT_SORT_MODE_LAYER_YZ, TRANSPARENT_SORT_MODE_LAYER_Z, TransparentSort, getTransparentSortConfig };
+//# sourceMappingURL=chunk-RXZ3RGOU.mjs.map
+//# sourceMappingURL=chunk-RXZ3RGOU.mjs.map

package/dist/chunk-RXZ3RGOU.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/systems/transparent-sort-config.ts"],"names":[],"mappings":";;;;AAkGO,IAAM,2BAAA,GAA8B,uBAAA;AAGpC,IAAM,6BAAA,GAAgC;AAGtC,IAAM,6BAAA,GAAgC;AAGtC,IAAM,8BAAA,GAAiC;AAGvC,IAAM,8BAAA,GAAiC;AAGvC,IAAM,eAAA,GAAkB,OAAO,MAAA,CAAO;AAAA,EAC3C,MAAA,EAAQ,6BAAA;AAAA,EACR,MAAA,EAAQ,6BAAA;AAAA,EACR,OAAA,EAAS,8BAAA;AAAA,EACT,QAAA,EAAU,8BAAA;AAAA,EACV,SAAA,EAAW;AACb,CAAU;AAMV,IAAM,cAAA,GAAwC,OAAO,MAAA,CAAO;AAAA,EAC1D,IAAA,EAAM,6BAAA;AAAA,EACN,OAAA,EAAS;AACX,CAAC,CAAA;AAED,IAAM,WAAA,uBAAuC,GAAA,CAAY;AAAA,EACvD,6BAAA;AAAA,EACA,6BAAA;AAAA,EACA,8BAAA;AAAA,EACA;AACF,CAAC,CAAA;AAOD,IAAM,aAAA,GAAgB,0BAAA;AACtB,IAAM,SAAA,GAAY,8CAAA;AA2BX,SAAS,yBAAyB,KAAA,EAAqC;AAC5E,EAAA,IAAI,CAAC,KAAA,CAAM,WAAA,CAAY,2BAA2B,CAAA,EAAG;AACnD,IAAA,OAAO,cAAA;AAAA,EACT;AACA,EAAA,OAAO,KAAA,CAAM,YAAmC,2BAA2B,CAAA;AAC7E;AAwCO,SAAS,wBAAA,CACd,OACA,GAAA,EACyC;AACzC,EAAA,IAAI,CAAC,WAAA,CAAY,GAAA,CAAI,GAAA,CAAI,IAAI,CAAA,EAAG;AAC9B,IAAA,OAAO,GAAA;AAAA,MACL,IAAI,yBAAA,CAA0B,aAAA,EAAe,SAAA,EAAW;AAAA,QACtD,cAAc,GAAA,CAAI,IAAA;AAAA,QAClB,WAAA,EAAa;AAAA,OACd;AAAA,KACH;AAAA,EACF;AACA,EAAA,KAAA,CAAM,eAAsC,2BAAA,EAA6B;AAAA,IACvE,MAAM,GAAA,CAAI,IAAA;AAAA,IACV,SAAS,GAAA,CAAI;AAAA,GACd,CAAA;AACD,EAAA,OAAO,GAAG,MAAS,CAAA;AACrB","file":"chunk-RXZ3RGOU.mjs","sourcesContent":["// @forgeax/engine-runtime - TransparentSortConfig KV resource + helpers.\n//\n// feat-20260520-2d-sprite-layer-mvp M-2 w14 / requirements AC-08 + AC-18\n// path (2)/(3) + AC-19 derivation audit (5).\n//\n// Surface:\n//   - interface  TransparentSortConfig { mode: number; yzAlpha: number }\n//   - constant   TRANSPARENT_SORT_CONFIG_KEY   = 'TransparentSortConfig'\n//   - constants  TRANSPARENT_SORT_MODE_LAYER_Z  = 0  (horizontal-z)\n//                TRANSPARENT_SORT_MODE_LAYER_Y  = 1  (Y-sort)\n//                TRANSPARENT_SORT_MODE_LAYER_YZ = 2  (Y-Z blend)\n//   - helper     getTransparentSortConfig(world): TransparentSortConfig\n//   - helper     setTransparentSortConfig(world, cfg):\n//                  Result<void, ResourceInvalidValueError>\n//\n// 5-view selection table (charter F1 progressive disclosure for AI users\n// reading IDE hover on this header; same SSOT mirrored in\n// apps/hello/sprite/README.md M-4 w33):\n//\n//   | view              | mode | yzAlpha | sortValue formula              |\n//   |:------------------|:----:|:-------:|:--------------------------------|\n//   | horizontal (side) |  0   |   ---   | posZ                            |\n//   | top-down          |  1   |   ---   | -(posY - pivot.y * size.y)      |\n//   | Don't Starve      |  2   |   1.0   | (posY - pivot.y * size.y) + posZ|\n//   | isometric         |  2   |   0.5   | (posY - pivot.y * size.y) + 0.5*posZ |\n//   | JRPG (foot pivot) |  1   |   ---   | -(posY - pivot.y * size.y)      |\n//\n// AC-18 path (2): @fallback getTransparentSortConfig KV missing returns\n//   default; no warn; no throw (legal default state, not an error state).\n// AC-18 path (3): @fallback setTransparentSortConfig mode out-of-range\n//   does NOT silently coerce to mode=0 — returns Result.err with the\n//   4 SSOT fields locked by plan-strategy D-4 so AI users can self-repair\n//   via .code / .expected / .hint / .detail property access (charter P3).\n// AC-18 path (3) carve-out: yzAlpha range is intentionally NOT validated;\n//   mode=0 / mode=1 ignore the field entirely, mode=2 reads it, mode=3\n//   (distance) also reads it for compat but ignores it (squared-distance\n//   formula does not use yzAlpha). The silent-ignore is the documented\n//   charter P3 \"legal default\" boundary.\n//\n// @new-surface KV resource: ECS has no defineResource factory at this\n//   feat's commit time; the TS POD interface + string KV key form is the\n//   minimum-new-surface route. The world resource store\n//   (insertResource / getResource / hasResource) is reused unchanged\n//   (requirements §2.2.G derivation row 5).\n// @derives world.hasResource / world.insertResource / world.getResource\n//   KV API (packages/ecs/src/resource.ts + world.ts: insertResource l.490,\n//   getResource l.498, hasResource l.503).\n// @fallback getTransparentSortConfig KV missing returns\n//   { mode: 0, yzAlpha: 1.0 }; no warn; no throw.\n// @fallback setTransparentSortConfig mode out-of-range returns Result.err\n//   with code='resource-invalid-value'; never silently coerced.\n//\n// charter mapping: F1 (single-import barrel + 5-view JSDoc table on\n// hover) + P3 (structured failure on mode out-of-range; legal-default\n// fallback distinguished from error fallback) + P4 (consistent\n// abstraction — same world.{has,get,insert}Resource KV API as every\n// other engine resource consumer).\n\nimport type { World } from '@forgeax/engine-ecs';\nimport { ResourceInvalidValueError } from '@forgeax/engine-ecs/projection';\nimport { err, ok, type Result } from '@forgeax/engine-types';\n\n// ────────────────────────────────────────────────────────────────────────────\n// POD interface + KV key + 3 named mode constants\n// ────────────────────────────────────────────────────────────────────────────\n\n/**\n * Transparent-bucket sort configuration (plain-data POD). Lives as a\n * world-level resource keyed by `TRANSPARENT_SORT_CONFIG_KEY`.\n *\n * Fields:\n *   - `mode \\u2208 {0, 1, 2, 3}` selects the sort formula\n *     (`TRANSPARENT_SORT_MODE_LAYER_Z` / `_LAYER_Y` / `_LAYER_YZ` / `_DISTANCE`).\n *   - `yzAlpha` (mode=2 only) blends Y-axis into Z-axis: 1.0 weights\n *     posZ equally with `posY - pivot.y * size.y` (Don't-Starve style),\n *     0.5 weights posZ at half (isometric). mode=0 / mode=1 ignore the\n *     field (documented charter P3 legal-default boundary).\n */\nexport interface TransparentSortConfig {\n  readonly mode: number;\n  readonly yzAlpha: number;\n}\n\n/** Extract-stage POD consumed by the transparent-sort owner. */\nexport interface TransparentEntry {\n  readonly entityIndex: number;\n  readonly materialHandle: number;\n  readonly layer: number;\n  readonly posX: number;\n  readonly posY: number;\n  readonly posZ: number;\n  readonly pivotY: number;\n  readonly sizeY: number;\n  readonly sortKey?: number | undefined;\n  readonly renderableIndex?: number | undefined;\n}\n\n/** World resource key for `TransparentSortConfig` KV entry. */\nexport const TRANSPARENT_SORT_CONFIG_KEY = 'TransparentSortConfig' as const;\n\n/** horizontal / side-scroller: sortValue = posZ. */\nexport const TRANSPARENT_SORT_MODE_LAYER_Z = 0;\n\n/** top-down / JRPG: sortValue = -(posY - pivot.y * size.y) (foot pivot Y-sort). */\nexport const TRANSPARENT_SORT_MODE_LAYER_Y = 1;\n\n/** Don't-Starve / isometric: sortValue = (posY - pivot.y * size.y) + yzAlpha * posZ. */\nexport const TRANSPARENT_SORT_MODE_LAYER_YZ = 2;\n\n/** 3D distance: sortValue = -(dist^2) to cameraPos, back-to-front (far first). */\nexport const TRANSPARENT_SORT_MODE_DISTANCE = 3;\n\n/** Grouped authoring values and the single configuration operation. */\nexport const TransparentSort = Object.freeze({\n  layerZ: TRANSPARENT_SORT_MODE_LAYER_Z,\n  layerY: TRANSPARENT_SORT_MODE_LAYER_Y,\n  layerYZ: TRANSPARENT_SORT_MODE_LAYER_YZ,\n  distance: TRANSPARENT_SORT_MODE_DISTANCE,\n  configure: setTransparentSortConfig,\n} as const);\n\n// ────────────────────────────────────────────────────────────────────────────\n// Internal: silent default + mode validity check\n// ────────────────────────────────────────────────────────────────────────────\n\nconst DEFAULT_CONFIG: TransparentSortConfig = Object.freeze({\n  mode: TRANSPARENT_SORT_MODE_LAYER_Z,\n  yzAlpha: 1.0,\n});\n\nconst VALID_MODES: ReadonlySet<number> = new Set<number>([\n  TRANSPARENT_SORT_MODE_LAYER_Z,\n  TRANSPARENT_SORT_MODE_LAYER_Y,\n  TRANSPARENT_SORT_MODE_LAYER_YZ,\n  TRANSPARENT_SORT_MODE_DISTANCE,\n]);\n\n// The expected / hint literals are the SSOT locked by plan-strategy D-4.\n// They MUST round-trip byte-for-byte into ResourceInvalidValueError so AI\n// users can read err.expected / err.hint for self-repair (charter P3).\n// `\\u2208` is the math \"is-element-of\" symbol; the ASCII source escape\n// keeps the file English-only per AGENTS.md §Conventions.\nconst EXPECTED_MODE = 'mode \\u2208 {0, 1, 2, 3}';\nconst HINT_MODE = '0=layer-z, 1=layer-y, 2=layer-yz, 3=distance';\n\n// ────────────────────────────────────────────────────────────────────────────\n// Helpers\n// ────────────────────────────────────────────────────────────────────────────\n\n/**\n * Read the world's `TransparentSortConfig` resource.\n *\n * @fallback KV missing returns `{ mode: 0, yzAlpha: 1.0 }`\n * (`TRANSPARENT_SORT_MODE_LAYER_Z`, horizontal-z safe default).\n * NO warn, NO throw — KV missing is a legal state (not an error state),\n * mirroring how a sprite-free scene is a legal state for the renderer\n * even though render-system has a transparent bucket. plan-strategy D-2:\n * `hasResource` guard precedes the read so this helper never trips\n * `ResourceNotFoundError` from `world.getResource`.\n *\n * @example\n *   const cfg = getTransparentSortConfig(world);\n *   // cfg.mode === 0, cfg.yzAlpha === 1.0 when no resource inserted.\n *\n * @example\n *   world.insertResource(TRANSPARENT_SORT_CONFIG_KEY,\n *     { mode: TRANSPARENT_SORT_MODE_LAYER_Y, yzAlpha: 1.0 });\n *   const cfg = getTransparentSortConfig(world);\n *   // cfg.mode === 1, cfg.yzAlpha === 1.0 (yzAlpha ignored by mode=1).\n */\nexport function getTransparentSortConfig(world: World): TransparentSortConfig {\n  if (!world.hasResource(TRANSPARENT_SORT_CONFIG_KEY)) {\n    return DEFAULT_CONFIG;\n  }\n  return world.getResource<TransparentSortConfig>(TRANSPARENT_SORT_CONFIG_KEY);\n}\n\n/**\n * Write the world's `TransparentSortConfig` resource, validating `mode`.\n *\n * Returns `Result<void, ResourceInvalidValueError>`:\n *\n *   - `ok` — mode is in `{0, 1, 2, 3}`; the resource is inserted /\n *     overwritten via `world.insertResource`.\n *   - `err` — mode is out of range; the resource is NOT mutated;\n *     `err.error` is a `ResourceInvalidValueError` instance carrying:\n *       `.code === 'resource-invalid-value'`\n *       `.expected === 'mode \\u2208 {0, 1, 2, 3}'`\n *       `.hint === '0=layer-z, 1=layer-y, 2=layer-yz, 3=distance'`\n *       `.detail.receivedMode === <the rejected mode>`\n *\n * @fallback mode out-of-range is NEVER silently coerced to mode=0 —\n * `Result.err` is the only fail-mode (charter P3 structured failure).\n * AI users read `.code / .expected / .hint / .detail` properties to\n * self-repair, NOT the human-readable `.message` string.\n *\n * @fallback yzAlpha range is intentionally not validated; mode=0 / mode=1\n * ignore the field, mode=2 reads it. The silent-ignore is the\n * documented charter P3 \"legal default\" boundary (plan-strategy D-4 +\n * AC-18 path (3) carve-out).\n *\n * @example success path:\n *   const r = setTransparentSortConfig(world,\n *     { mode: TRANSPARENT_SORT_MODE_LAYER_YZ, yzAlpha: 0.5 });\n *   if (!r.ok) return r;\n *\n * @example failure path:\n *   const r = setTransparentSortConfig(world, { mode: 99, yzAlpha: 1.0 });\n *   if (!r.ok) {\n *     // r.error.code === 'resource-invalid-value'\n *     // r.error.expected === 'mode \\u2208 {0, 1, 2, 3}'\n *     // r.error.hint === '0=layer-z, 1=layer-y, 2=layer-yz, 3=distance'\n *     // r.error.detail.receivedMode === 99\n *   }\n */\nexport function setTransparentSortConfig(\n  world: World,\n  cfg: TransparentSortConfig,\n): Result<void, ResourceInvalidValueError> {\n  if (!VALID_MODES.has(cfg.mode)) {\n    return err(\n      new ResourceInvalidValueError(EXPECTED_MODE, HINT_MODE, {\n        receivedMode: cfg.mode,\n        receivedKey: TRANSPARENT_SORT_CONFIG_KEY,\n      }),\n    );\n  }\n  world.insertResource<TransparentSortConfig>(TRANSPARENT_SORT_CONFIG_KEY, {\n    mode: cfg.mode,\n    yzAlpha: cfg.yzAlpha,\n  });\n  return ok(undefined);\n}\n"]}

package/dist/{chunk-CQXZC5XI.mjs → chunk-VFPLTKCU.mjs}

@@ -1,45 +1,23 @@
-import { defineComponent } from '@forgeax/engine-ecs';
-
-// src/components/sprite-animation.ts
-var SpriteAnimation = defineComponent("SpriteAnimation", {
-  frameCount: { type: "u32" },
-  frameDuration: { type: "f32" },
-  currentFrame: { type: "u32", transient: true },
-  accumDt: { type: "f32", transient: true },
-  regions: { type: "array<f32>" },
-  playbackMode: { type: "u32" }
-});
-var SpriteInstances = defineComponent("SpriteInstances", {
-  transforms: { type: "array<f32>" },
-  regions: { type: "array<f32>" }
-});
-var SpriteRegionOverride = defineComponent("SpriteRegionOverride", {
-  region: { type: "array<f32, 4>" }
-});
-var TilemapSort = Object.freeze({
-  layer: 0,
-  perCell: 1
-});
-function decodeSortScope(raw) {
-  return raw === 1 ? "per-cell" : "layer";
-}
-var TileLayer = defineComponent("TileLayer", {
-  tiles: { type: "array<u32>" },
-  layerOrder: { type: "i32", default: 0 },
-  dirty: { type: "u8", default: 0 },
-  sortScope: { type: "u8", default: 0 }
-});
-var Tilemap = defineComponent("Tilemap", {
-  cols: { type: "u32", default: 0 },
-  rows: { type: "u32", default: 0 },
-  // tileSize carries an explicit layer-2 default [1,1] (unit cell); the array
-  // layer-3 fallback is all-zero, so the default MUST be explicit (D-5).
-  tileSize: { type: "array<f32, 2>", default: new Float32Array([1, 1]) },
-  chunkSize: { type: "u32", default: 16 },
-  tileset: { type: "string" }
-});
+import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '@forgeax/engine-shader';
 
 // src/materials.ts
+var MaterialTransmissionContractError = class extends Error {
+  code = "material-transmission-contract-invalid";
+  expected = "transmission material values satisfy finite ranges and Forward depth rules";
+  hint = "repair the named transmission value or pass state before publishing the material";
+  detail;
+  constructor(parameter, reason, actual) {
+    super(`Materials.standard: ${parameter} violates the transmission contract (${reason})`);
+    this.name = "MaterialTransmissionContractError";
+    this.detail = {
+      code: "material-transmission-contract-invalid",
+      material: "Standard",
+      parameter,
+      reason,
+      ...actual === void 0 ? {} : { actual }
+    };
+  }
+};
 var SPRITE_PREMULTIPLIED_ALPHA_BLEND = {
   color: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
   alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" }
@@ -50,33 +28,29 @@ function authoredColorParameter(name, type, colorSpace, optional = false) {
   return {
     name,
     type,
-    ...type === "color" && colorSpace === "srgb" ? {} : { colorSpace },
+    ...colorSpace === "srgb" ? {} : { colorSpace },
     ...optional ? { optional: true } : {}
   };
 }
 function standardParameters(colorSpace) {
-  return [
-    authoredColorParameter("baseColor", "color", colorSpace),
-    { name: "metallic", type: "f32" },
-    { name: "roughness", type: "f32" },
-    { name: "metallicChannel", type: "f32", optional: true },
-    { name: "roughnessChannel", type: "f32", optional: true },
-    { name: "aoChannel", type: "f32", optional: true },
-    { name: "extraChannel", type: "f32", optional: true },
-    authoredColorParameter("emissive", "vec3", colorSpace, true),
-    { name: "emissiveIntensity", type: "f32", optional: true },
-    { name: "occlusionStrength", type: "f32", optional: true },
-    { name: "alphaCutoff", type: "f32", optional: true },
-    { name: "clearcoat", type: "f32", optional: true },
-    { name: "clearcoatRoughness", type: "f32", optional: true },
-    authoredColorParameter("specularTint", "vec3", colorSpace, true),
-    { name: "baseColorTexture", type: "texture", optional: true },
-    { name: "metallicRoughnessTexture", type: "texture", optional: true },
-    { name: "normalTexture", type: "texture", optional: true },
-    { name: "specularTintTexture", type: "texture", optional: true },
-    { name: "emissiveTexture", type: "texture", optional: true },
-    { name: "occlusionTexture", type: "texture", optional: true }
-  ];
+  return DEFAULT_STANDARD_PBR_PARAM_SCHEMA.map((entry) => {
+    const type = entry.type.startsWith("texture") ? "texture" : entry.type;
+    const isRequired = entry.name === "baseColor" || entry.name === "metallic" || entry.name === "roughness";
+    const authoredColor = entry.type === "color" || entry.type === "vec3" && entry.name !== "attenuationColor";
+    const schemaColorSpace = "colorSpace" in entry ? entry.colorSpace : void 0;
+    const colorSpaceProjection = {};
+    if (authoredColor && !(type === "color" && colorSpace === "srgb")) {
+      colorSpaceProjection.colorSpace = colorSpace;
+    } else if (!authoredColor && schemaColorSpace !== void 0) {
+      colorSpaceProjection.colorSpace = schemaColorSpace;
+    }
+    return {
+      name: entry.name,
+      type,
+      ...colorSpaceProjection,
+      ...isRequired ? {} : { optional: true }
+    };
+  });
 }
 function unlitParameters(colorSpace) {
   return [
@@ -126,6 +100,15 @@ function validateChannel(name, value) {
     throw new Error(`Materials.standard: ${name} must be an integer in [0, 3], got ${value}`);
   }
 }
+function validateFiniteRange(name, value, minimum, maximum) {
+  if (value === void 0 || !Number.isFinite(value)) {
+    if (value === void 0) return;
+    throw new MaterialTransmissionContractError(name, "non-finite", value);
+  }
+  if (value < minimum || maximum !== void 0 && value > maximum) {
+    throw new MaterialTransmissionContractError(name, "range", value);
+  }
+}
 function standard(opts) {
   const occlusionStrength = opts.occlusionStrength ?? 1;
   if (occlusionStrength < 0 || occlusionStrength > 1) {
@@ -138,12 +121,33 @@ function standard(opts) {
   }
   validateChannel("metallicChannel", opts.metallicChannel);
   validateChannel("roughnessChannel", opts.roughnessChannel);
+  const transmission = opts.transmission ?? 0;
+  const ior = opts.ior ?? 1.5;
+  const thickness = opts.thickness ?? 0;
+  const attenuationColor = opts.attenuationColor ?? [1, 1, 1];
+  validateFiniteRange("transmission", transmission, 0, 1);
+  validateFiniteRange("ior", ior, 1);
+  validateFiniteRange("thickness", thickness, 0);
+  validateFiniteRange("attenuationDistance", opts.attenuationDistance, Number.MIN_VALUE);
+  if (attenuationColor.length !== 3 || attenuationColor.some((value) => !Number.isFinite(value) || value < 0 || value > 1)) {
+    throw new MaterialTransmissionContractError("attenuationColor", "shape", attenuationColor);
+  }
+  if (transmission > 0 && opts.renderState?.blend !== void 0) {
+    throw new MaterialTransmissionContractError("transmission", "blend", opts.renderState.blend);
+  }
+  if (transmission > 0 && opts.renderState?.depthWriteEnabled === true) {
+    throw new MaterialTransmissionContractError("transmission", "depth-write", true);
+  }
   const values = {
     baseColor: opts.baseColor,
     metallic: opts.metallic ?? 0,
     roughness: opts.roughness ?? 0.5,
     occlusionStrength,
-    specularTint: opts.specularTint ?? [1, 1, 1]
+    specularTint: opts.specularTint ?? [1, 1, 1],
+    transmission,
+    ior,
+    thickness,
+    attenuationColor
   };
   if (opts.metallicChannel !== void 0) values.metallicChannel = opts.metallicChannel;
   if (opts.roughnessChannel !== void 0) values.roughnessChannel = opts.roughnessChannel;
@@ -162,10 +166,16 @@ function standard(opts) {
     values.specularTintTexture = opts.specularTintTexture;
   }
   if (opts.alphaCutoff !== void 0) values.alphaCutoff = opts.alphaCutoff;
+  if (opts.transmissionTexture !== void 0) values.transmissionTexture = opts.transmissionTexture;
+  if (opts.thicknessTexture !== void 0) values.thicknessTexture = opts.thicknessTexture;
+  if (opts.attenuationDistance !== void 0) values.attenuationDistance = opts.attenuationDistance;
+  const forwardRenderState = transmission > 0 ? { ...opts.renderState ?? {}, depthWriteEnabled: false } : opts.renderState;
   const passes = [
-    pass("forward", STANDARD_MODULE, opts.renderState, "fs_main", opts.queue),
-    pass("deferred", STANDARD_MODULE, opts.renderState, "fs_gbuffer", opts.queue)
+    pass("forward", STANDARD_MODULE, forwardRenderState, "fs_main", opts.queue)
   ];
+  if (transmission === 0) {
+    passes.push(pass("deferred", STANDARD_MODULE, opts.renderState, "fs_gbuffer", opts.queue));
+  }
   if (opts.castShadow !== false) passes.push(pass("shadow-caster", STANDARD_MODULE, void 0));
   return {
     kind: "material",
@@ -177,6 +187,6 @@ function standard(opts) {
 }
 var Materials = { unlit, standard };
 
-export { Materials, SPRITE_PREMULTIPLIED_ALPHA_BLEND, SpriteAnimation, SpriteInstances, SpriteRegionOverride, TileLayer, Tilemap, TilemapSort, decodeSortScope };
-//# sourceMappingURL=chunk-CQXZC5XI.mjs.map
-//# sourceMappingURL=chunk-CQXZC5XI.mjs.map
+export { MaterialTransmissionContractError, Materials, SPRITE_PREMULTIPLIED_ALPHA_BLEND };
+//# sourceMappingURL=chunk-VFPLTKCU.mjs.map
+//# sourceMappingURL=chunk-VFPLTKCU.mjs.map

package/dist/chunk-VFPLTKCU.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/materials.ts"],"names":[],"mappings":"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","file":"chunk-VFPLTKCU.mjs","sourcesContent":["import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '@forgeax/engine-shader';\nimport type {\n  MaterialAsset,\n  MaterialColorSpace,\n  MaterialParameter,\n  MaterialPass,\n  MaterialRenderState,\n  MaterialValue,\n} from '@forgeax/engine-types';\n\nexport type MaterialTransmissionValidationReason =\n  | 'non-finite'\n  | 'range'\n  | 'shape'\n  | 'blend'\n  | 'depth-write';\n\n/** Structured authoring failure for the Standard transmission contract. */\nexport class MaterialTransmissionContractError extends Error {\n  readonly code = 'material-transmission-contract-invalid' as const;\n  readonly expected = 'transmission material values satisfy finite ranges and Forward depth rules';\n  readonly hint =\n    'repair the named transmission value or pass state before publishing the material';\n  readonly detail: {\n    readonly code: 'material-transmission-contract-invalid';\n    readonly material: 'Standard';\n    readonly parameter:\n      | 'transmission'\n      | 'ior'\n      | 'thickness'\n      | 'attenuationColor'\n      | 'attenuationDistance';\n    readonly reason: MaterialTransmissionValidationReason;\n    readonly actual?: unknown;\n  };\n\n  constructor(\n    parameter: (typeof MaterialTransmissionContractError.prototype.detail)['parameter'],\n    reason: MaterialTransmissionValidationReason,\n    actual?: unknown,\n  ) {\n    super(`Materials.standard: ${parameter} violates the transmission contract (${reason})`);\n    this.name = 'MaterialTransmissionContractError';\n    this.detail = {\n      code: 'material-transmission-contract-invalid',\n      material: 'Standard',\n      parameter,\n      reason,\n      ...(actual === undefined ? {} : { actual }),\n    };\n  }\n}\n\nexport const SPRITE_PREMULTIPLIED_ALPHA_BLEND: GPUBlendState = {\n  color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },\n  alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },\n};\n\nconst STANDARD_MODULE = 'forgeax_material::standard';\nconst UNLIT_MODULE = 'forgeax_material::unlit';\nconst SPRITE_MODULE = 'forgeax_material::sprite';\n\nfunction authoredColorParameter(\n  name: string,\n  type: 'color' | 'vec3',\n  colorSpace: MaterialColorSpace,\n  optional = false,\n): MaterialParameter {\n  return {\n    name,\n    type,\n    ...(type === 'color' && colorSpace === 'srgb' ? {} : { colorSpace }),\n    ...(optional ? { optional: true } : {}),\n  };\n}\n\nfunction standardParameters(colorSpace: MaterialColorSpace): readonly MaterialParameter[] {\n  return DEFAULT_STANDARD_PBR_PARAM_SCHEMA.map((entry) => {\n    const type = entry.type.startsWith('texture') ? 'texture' : entry.type;\n    const isRequired =\n      entry.name === 'baseColor' || entry.name === 'metallic' || entry.name === 'roughness';\n    const authoredColor =\n      entry.type === 'color' || (entry.type === 'vec3' && entry.name !== 'attenuationColor');\n    const schemaColorSpace = 'colorSpace' in entry ? entry.colorSpace : undefined;\n    const colorSpaceProjection: { colorSpace?: MaterialColorSpace } = {};\n    if (authoredColor && !(type === 'color' && colorSpace === 'srgb')) {\n      colorSpaceProjection.colorSpace = colorSpace;\n    } else if (!authoredColor && schemaColorSpace !== undefined) {\n      colorSpaceProjection.colorSpace = schemaColorSpace;\n    }\n    return {\n      name: entry.name,\n      type,\n      ...colorSpaceProjection,\n      ...(isRequired ? {} : { optional: true }),\n    } as MaterialParameter;\n  });\n}\n\nfunction unlitParameters(colorSpace: MaterialColorSpace): readonly MaterialParameter[] {\n  return [\n    authoredColorParameter('baseColor', 'color', colorSpace),\n    { name: 'alphaCutoff', type: 'f32', optional: true },\n    { name: 'baseColorTexture', type: 'texture', optional: true },\n  ];\n}\n\nfunction pass(\n  name: string,\n  module: string,\n  renderState: MaterialRenderState | undefined,\n  fragmentEntry?: string,\n  queue?: number,\n): MaterialPass {\n  const lightMode =\n    name === 'shadow-caster' ? 'ShadowCaster' : name === 'deferred' ? 'Deferred' : 'Forward';\n  const authoredState = (renderState ?? {}) as Readonly<Record<string, unknown>>;\n  const authoredTags = authoredState.tags as Readonly<Record<string, string>> | undefined;\n  return {\n    name,\n    program: {\n      module,\n      ...(fragmentEntry === undefined ? {} : { fragmentEntry }),\n    },\n    renderState: {\n      ...authoredState,\n      tags: { LightMode: lightMode, ...authoredTags },\n      ...(queue === undefined ? {} : { queue }),\n    },\n  };\n}\n\ninterface UnlitOpts {\n  /** Asset-side authored color space. Defaults to sRGB. */\n  readonly colorSpace?: MaterialColorSpace;\n  readonly castShadow?: boolean;\n  readonly baseColorTexture?: MaterialValue;\n  readonly alphaCutoff?: number;\n  readonly renderState?: MaterialRenderState;\n  readonly queue?: number;\n}\n\nfunction unlit(rgba: readonly [number, number, number, number], opts?: UnlitOpts): MaterialAsset {\n  if (opts?.alphaCutoff !== undefined && (opts.alphaCutoff < 0 || opts.alphaCutoff > 1)) {\n    throw new Error(`Materials.unlit: alphaCutoff must be in [0, 1], got ${opts.alphaCutoff}`);\n  }\n  const values: Record<string, MaterialValue> = { baseColor: rgba };\n  if (opts?.baseColorTexture !== undefined) values.baseColorTexture = opts.baseColorTexture;\n  if (opts?.alphaCutoff !== undefined) values.alphaCutoff = opts.alphaCutoff;\n  const passes: [MaterialPass, ...MaterialPass[]] = [\n    pass('forward', UNLIT_MODULE, opts?.renderState, undefined, opts?.queue),\n  ];\n  if (opts?.castShadow !== false) passes.push(pass('shadow-caster', UNLIT_MODULE, undefined));\n  return {\n    kind: 'material',\n    ...(opts?.colorSpace === undefined || opts.colorSpace === 'srgb'\n      ? {}\n      : { colorSpace: opts.colorSpace }),\n    passes,\n    parameters: unlitParameters(opts?.colorSpace ?? 'srgb'),\n    values,\n  };\n}\n\ninterface StandardOpts {\n  /** Asset-side authored color space for baseColor/emissive/specularTint. Defaults to sRGB. */\n  readonly colorSpace?: MaterialColorSpace;\n  readonly baseColor: readonly [number, number, number, number];\n  readonly metallic?: number;\n  readonly roughness?: number;\n  /** Texture channel used for the metallic factor; glTF defaults to B (2). */\n  readonly metallicChannel?: number;\n  /** Texture channel used for the roughness factor; glTF defaults to G (1). */\n  readonly roughnessChannel?: number;\n  readonly clearcoat?: number;\n  readonly clearcoatRoughness?: number;\n  readonly specularTint?: readonly [number, number, number];\n  readonly specularTintTexture?: MaterialValue;\n  readonly emissive?: readonly [number, number, number];\n  readonly emissiveIntensity?: number;\n  readonly emissiveTexture?: MaterialValue;\n  readonly baseColorTexture?: MaterialValue;\n  readonly metallicRoughnessTexture?: MaterialValue;\n  readonly normalTexture?: MaterialValue;\n  readonly occlusionTexture?: MaterialValue;\n  readonly occlusionStrength?: number;\n  readonly alphaCutoff?: number;\n  readonly transmission?: number;\n  readonly transmissionTexture?: MaterialValue;\n  readonly ior?: number;\n  readonly thickness?: number;\n  readonly thicknessTexture?: MaterialValue;\n  readonly attenuationColor?: readonly [number, number, number];\n  readonly attenuationDistance?: number;\n  readonly renderState?: MaterialRenderState;\n  readonly castShadow?: boolean;\n  readonly queue?: number;\n}\n\nfunction validateChannel(\n  name: 'metallicChannel' | 'roughnessChannel',\n  value: number | undefined,\n): void {\n  if (value !== undefined && (!Number.isInteger(value) || value < 0 || value > 3)) {\n    throw new Error(`Materials.standard: ${name} must be an integer in [0, 3], got ${value}`);\n  }\n}\n\nfunction validateFiniteRange(\n  name: 'transmission' | 'ior' | 'thickness' | 'attenuationDistance',\n  value: number | undefined,\n  minimum: number,\n  maximum?: number,\n): void {\n  if (value === undefined || !Number.isFinite(value)) {\n    if (value === undefined) return;\n    throw new MaterialTransmissionContractError(name, 'non-finite', value);\n  }\n  if (value < minimum || (maximum !== undefined && value > maximum)) {\n    throw new MaterialTransmissionContractError(name, 'range', value);\n  }\n}\n\nfunction standard(opts: StandardOpts): MaterialAsset {\n  const occlusionStrength = opts.occlusionStrength ?? 1;\n  if (occlusionStrength < 0 || occlusionStrength > 1) {\n    throw new Error(\n      `Materials.standard: occlusionStrength must be in [0, 1], got ${occlusionStrength}`,\n    );\n  }\n  if (opts.alphaCutoff !== undefined && (opts.alphaCutoff < 0 || opts.alphaCutoff > 1)) {\n    throw new Error(`Materials.standard: alphaCutoff must be in [0, 1], got ${opts.alphaCutoff}`);\n  }\n  validateChannel('metallicChannel', opts.metallicChannel);\n  validateChannel('roughnessChannel', opts.roughnessChannel);\n  const transmission = opts.transmission ?? 0;\n  const ior = opts.ior ?? 1.5;\n  const thickness = opts.thickness ?? 0;\n  const attenuationColor = opts.attenuationColor ?? [1, 1, 1];\n  validateFiniteRange('transmission', transmission, 0, 1);\n  validateFiniteRange('ior', ior, 1);\n  validateFiniteRange('thickness', thickness, 0);\n  validateFiniteRange('attenuationDistance', opts.attenuationDistance, Number.MIN_VALUE);\n  if (\n    attenuationColor.length !== 3 ||\n    attenuationColor.some((value) => !Number.isFinite(value) || value < 0 || value > 1)\n  ) {\n    throw new MaterialTransmissionContractError('attenuationColor', 'shape', attenuationColor);\n  }\n  if (transmission > 0 && opts.renderState?.blend !== undefined) {\n    throw new MaterialTransmissionContractError('transmission', 'blend', opts.renderState.blend);\n  }\n  if (transmission > 0 && opts.renderState?.depthWriteEnabled === true) {\n    throw new MaterialTransmissionContractError('transmission', 'depth-write', true);\n  }\n  const values: Record<string, MaterialValue> = {\n    baseColor: opts.baseColor,\n    metallic: opts.metallic ?? 0,\n    roughness: opts.roughness ?? 0.5,\n    occlusionStrength,\n    specularTint: opts.specularTint ?? [1, 1, 1],\n    transmission,\n    ior,\n    thickness,\n    attenuationColor,\n  };\n  if (opts.metallicChannel !== undefined) values.metallicChannel = opts.metallicChannel;\n  if (opts.roughnessChannel !== undefined) values.roughnessChannel = opts.roughnessChannel;\n  if (opts.clearcoat !== undefined) values.clearcoat = opts.clearcoat;\n  if (opts.clearcoatRoughness !== undefined) values.clearcoatRoughness = opts.clearcoatRoughness;\n  if (opts.emissive !== undefined) values.emissive = opts.emissive;\n  if (opts.emissiveIntensity !== undefined) values.emissiveIntensity = opts.emissiveIntensity;\n  if (opts.emissiveTexture !== undefined) values.emissiveTexture = opts.emissiveTexture;\n  if (opts.baseColorTexture !== undefined) values.baseColorTexture = opts.baseColorTexture;\n  if (opts.metallicRoughnessTexture !== undefined) {\n    values.metallicRoughnessTexture = opts.metallicRoughnessTexture;\n  }\n  if (opts.normalTexture !== undefined) values.normalTexture = opts.normalTexture;\n  if (opts.occlusionTexture !== undefined) values.occlusionTexture = opts.occlusionTexture;\n  if (opts.specularTintTexture !== undefined) {\n    values.specularTintTexture = opts.specularTintTexture;\n  }\n  if (opts.alphaCutoff !== undefined) values.alphaCutoff = opts.alphaCutoff;\n  if (opts.transmissionTexture !== undefined) values.transmissionTexture = opts.transmissionTexture;\n  if (opts.thicknessTexture !== undefined) values.thicknessTexture = opts.thicknessTexture;\n  if (opts.attenuationDistance !== undefined) values.attenuationDistance = opts.attenuationDistance;\n  const forwardRenderState =\n    transmission > 0 ? { ...(opts.renderState ?? {}), depthWriteEnabled: false } : opts.renderState;\n  const passes: [MaterialPass, ...MaterialPass[]] = [\n    pass('forward', STANDARD_MODULE, forwardRenderState, 'fs_main', opts.queue),\n  ];\n  if (transmission === 0) {\n    passes.push(pass('deferred', STANDARD_MODULE, opts.renderState, 'fs_gbuffer', opts.queue));\n  }\n  if (opts.castShadow !== false) passes.push(pass('shadow-caster', STANDARD_MODULE, undefined));\n  return {\n    kind: 'material',\n    ...(opts.colorSpace === undefined || opts.colorSpace === 'srgb'\n      ? {}\n      : { colorSpace: opts.colorSpace }),\n    passes,\n    parameters: standardParameters(opts.colorSpace ?? 'srgb'),\n    values,\n  };\n}\n\nexport const Materials = { unlit, standard } as const;\n\nexport { SPRITE_MODULE };\n"]}