@carbonenginejs/runtime-resource 0.12.2 → 0.14.0

package/dist/formats/webgl/core/buildGlslEffectContainer.js

@@ -0,0 +1,70 @@
+import { buildCarbonEffectContainer } from '../../../format/carbonEffect/buildCarbonEffectContainer.js';
+import { writeGlslBackendBlock } from './glslBackendBlock.js';
+
+/**
+ * The WebGL 2 backend adapter for the shared Carbon container builder.
+ *
+ * The record layout, the permutation walk and the description mapping are shared
+ * with WebGPU and live in `format/carbonEffect/buildCarbonEffectContainer.js`.
+ * What remains here is the two backend-varying decisions: a program is GLSL ES
+ * 3.00 text, and a pass's trailing block is the GLSL lowering data.
+ *
+ * There is no entry-point assertion to make. GLSL's entry point is `main` by
+ * language rule rather than by our emitter's choice, so unlike WGSL there is
+ * nothing a future lowerer could change.
+ */
+
+/**
+ * Encodes one GLSL stage program.
+ *
+ * @param {object} shader Translated shader record.
+ * @returns {Uint8Array} Program bytes.
+ */
+function encodeProgram(shader) {
+  return new TextEncoder().encode(shader.code);
+}
+
+/**
+ * Builds the per-pass backend block for one pass of one translated body.
+ *
+ * A pass whose stages added no lowering data emits no block at all rather than
+ * an empty one, so the description ends where Carbon's would and the optional
+ * block stays genuinely optional.
+ *
+ * @param {object} unit Pass translation unit.
+ * @param {string} passKey Enclosing pass key.
+ * @returns {Uint8Array|null} Block bytes, or null when the pass has none.
+ */
+function encodeBackendBlock(unit, passKey) {
+  const stages = unit.block;
+  const transforms = (unit.resourceTransforms ?? []).filter(transform => transform.layoutKey === passKey);
+  if (!stages && !transforms.length) return null;
+  return writeGlslBackendBlock({
+    stages: stages ?? {},
+    transforms
+  });
+}
+
+/** The WebGL encoders, as the shared builder's backend argument. */
+const GLSL_CONTAINER_BACKEND = Object.freeze({
+  encodeProgram,
+  encodeBackendBlock
+});
+
+/**
+ * Builds the complete WebGL 2 effect container.
+ *
+ * @param {object} effectRes Loaded version-15 `Tr2EffectRes`.
+ * @param {object} permutationGraph Validated `PGRF` document.
+ * @param {object} backendBodySet Translated GLSL bodies.
+ * @param {object} [options] Container options.
+ * @param {number[]|Uint8Array} [options.compilerVersion] Four version bytes.
+ * @param {string} [options.sourceHash] 32 ASCII hash characters.
+ * @returns {{bytes:Uint8Array, permutationCount:number, bodyCount:number}} Container and its body accounting.
+ */
+function buildGlslEffectContainer(effectRes, permutationGraph, backendBodySet, options = {}) {
+  return buildCarbonEffectContainer(effectRes, permutationGraph, backendBodySet, GLSL_CONTAINER_BACKEND, options);
+}
+
+export { GLSL_CONTAINER_BACKEND, buildGlslEffectContainer };
+//# sourceMappingURL=buildGlslEffectContainer.js.map

package/dist/formats/webgl/core/buildGlslEffectContainer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildGlslEffectContainer.js","sources":["../../../../../src/formats/webgl/core/buildGlslEffectContainer.js"],"sourcesContent":["import {\n    buildCarbonEffectContainer\n} from \"../../../format/carbonEffect/buildCarbonEffectContainer.js\";\nimport { writeGlslBackendBlock } from \"./glslBackendBlock.js\";\n\n/**\n * The WebGL 2 backend adapter for the shared Carbon container builder.\n *\n * The record layout, the permutation walk and the description mapping are shared\n * with WebGPU and live in `format/carbonEffect/buildCarbonEffectContainer.js`.\n * What remains here is the two backend-varying decisions: a program is GLSL ES\n * 3.00 text, and a pass's trailing block is the GLSL lowering data.\n *\n * There is no entry-point assertion to make. GLSL's entry point is `main` by\n * language rule rather than by our emitter's choice, so unlike WGSL there is\n * nothing a future lowerer could change.\n */\n\n/**\n * Encodes one GLSL stage program.\n *\n * @param {object} shader Translated shader record.\n * @returns {Uint8Array} Program bytes.\n */\nfunction encodeProgram(shader)\n{\n    return new TextEncoder().encode(shader.code);\n}\n\n/**\n * Builds the per-pass backend block for one pass of one translated body.\n *\n * A pass whose stages added no lowering data emits no block at all rather than\n * an empty one, so the description ends where Carbon's would and the optional\n * block stays genuinely optional.\n *\n * @param {object} unit Pass translation unit.\n * @param {string} passKey Enclosing pass key.\n * @returns {Uint8Array|null} Block bytes, or null when the pass has none.\n */\nfunction encodeBackendBlock(unit, passKey)\n{\n    const stages = unit.block;\n    const transforms = (unit.resourceTransforms ?? [])\n        .filter((transform) => transform.layoutKey === passKey);\n\n    if (!stages && !transforms.length) return null;\n\n    return writeGlslBackendBlock({ stages: stages ?? {}, transforms });\n}\n\n/** The WebGL encoders, as the shared builder's backend argument. */\nexport const GLSL_CONTAINER_BACKEND = Object.freeze({ encodeProgram, encodeBackendBlock });\n\n/**\n * Builds the complete WebGL 2 effect container.\n *\n * @param {object} effectRes Loaded version-15 `Tr2EffectRes`.\n * @param {object} permutationGraph Validated `PGRF` document.\n * @param {object} backendBodySet Translated GLSL bodies.\n * @param {object} [options] Container options.\n * @param {number[]|Uint8Array} [options.compilerVersion] Four version bytes.\n * @param {string} [options.sourceHash] 32 ASCII hash characters.\n * @returns {{bytes:Uint8Array, permutationCount:number, bodyCount:number}} Container and its body accounting.\n */\nexport function buildGlslEffectContainer(\n    effectRes,\n    permutationGraph,\n    backendBodySet,\n    options = {}\n)\n{\n    return buildCarbonEffectContainer(\n        effectRes,\n        permutationGraph,\n        backendBodySet,\n        GLSL_CONTAINER_BACKEND,\n        options\n    );\n}\n\nexport default buildGlslEffectContainer;\n"],"names":["encodeProgram","shader","TextEncoder","encode","code","encodeBackendBlock","unit","passKey","stages","block","transforms","resourceTransforms","filter","transform","layoutKey","length","writeGlslBackendBlock","GLSL_CONTAINER_BACKEND","Object","freeze","buildGlslEffectContainer","effectRes","permutationGraph","backendBodySet","options","buildCarbonEffectContainer"],"mappings":";;;AAKA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,aAAaA,CAACC,MAAM,EAC7B;EACI,OAAO,IAAIC,WAAW,EAAE,CAACC,MAAM,CAACF,MAAM,CAACG,IAAI,CAAC;AAChD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,kBAAkBA,CAACC,IAAI,EAAEC,OAAO,EACzC;AACI,EAAA,MAAMC,MAAM,GAAGF,IAAI,CAACG,KAAK;AACzB,EAAA,MAAMC,UAAU,GAAG,CAACJ,IAAI,CAACK,kBAAkB,IAAI,EAAE,EAC5CC,MAAM,CAAEC,SAAS,IAAKA,SAAS,CAACC,SAAS,KAAKP,OAAO,CAAC;EAE3D,IAAI,CAACC,MAAM,IAAI,CAACE,UAAU,CAACK,MAAM,EAAE,OAAO,IAAI;AAE9C,EAAA,OAAOC,qBAAqB,CAAC;AAAER,IAAAA,MAAM,EAAEA,MAAM,IAAI,EAAE;AAAEE,IAAAA;AAAW,GAAC,CAAC;AACtE;;AAEA;MACaO,sBAAsB,GAAGC,MAAM,CAACC,MAAM,CAAC;EAAEnB,aAAa;AAAEK,EAAAA;AAAmB,CAAC;;AAEzF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASe,wBAAwBA,CACpCC,SAAS,EACTC,gBAAgB,EAChBC,cAAc,EACdC,OAAO,GAAG,EAAE,EAEhB;EACI,OAAOC,0BAA0B,CAC7BJ,SAAS,EACTC,gBAAgB,EAChBC,cAAc,EACdN,sBAAsB,EACtBO,OACJ,CAAC;AACL;;;;"}

package/dist/formats/webgl/core/effectPackage.js

@@ -1,19 +1,32 @@
-import { EFFECT_INFO_VERSION } from './effectPackageValidation.js';
 import { CjsHlslFormat } from '../../hlsl/CjsHlslFormat.js';
 import { HlslRenderContextEnum, hlslShaderStageName } from '../../hlsl/core/tr2/HlslRenderContextEnum.js';
-import '../../../format/CjsByteReader.js';
 import '@carbonenginejs/runtime-utils/bytes';
-import '../../hlsl/core/tr2/shader/HlslEffectResource.js';
+import '../../hlsl/core/carbonDescriptionToRuntime.js';
+import '../../../format/CjsByteReader.js';
+import '../../../format/compareUtf8.js';
 import { HlslEffectBindingManifest } from '../../hlsl/core/tr2/shader/HlslEffectBindingManifest.js';
 import { buildEffectPermutationGraph, EFFECT_PERMUTATION_GRAPH_VERSION, EFFECT_PERMUTATION_GRAPH_FORMAT, EFFECT_PERMUTATION_GRAPH_CHUNK } from '../../../format/effect/effectPermutationGraph.js';
-import { buildCompleteEffectReflection, EFFECT_REFLECTION_CHUNK, EFFECT_REFLECTION_BLOB_CHUNK } from '../../../format/effect/effectReflectionPackage.js';
-import { buildPackage, inspectWithValues, emitGlslWithOptions } from './helpers.js';
+import { emitGlslWithOptions } from './helpers.js';
+import { inspectGlslEffectContainer } from './inspectGlslEffectContainer.js';
+import { inspectRasterCompleteness } from './glslEffectCompleteness.js';
+import { recogniseDetailMapFamily } from '../../hlsl/core/detailMapFamily.js';
+import { stripLocalLightBindings, recogniseLocalLightFamily } from '../../hlsl/core/localLightFamily.js';
+import { buildGlslBackendBodySet } from './glslBackendBodySet.js';
+import { buildGlslEffectContainer } from './buildGlslEffectContainer.js';
 import { sha256Utf8, sha256Bytes } from '../../../format/effect/sha256.js';
 
+/**
+ * INFO record version for the in-memory build result.
+ *
+ * This lived in effectPackageValidation.js, which validated a written chunk
+ * package by reading it back. There is no chunk package to read back, so that
+ * file is gone and its one surviving constant lives with its only user.
+ */
+const EFFECT_INFO_VERSION = 3;
 const PACKAGE_VERSION = "0.11.1";
 
 /**
- * Builds a complete CEWG package from compiled Tr2 effect bytes.
+ * Builds a complete Carbon WebGL package from compiled Tr2 effect bytes.
  *
  * This browser-safe path owns whole-effect selection, stage translation,
  * package assembly, and structural qualification. Filesystem and native-tool
@@ -39,10 +52,6 @@ function buildEffectPackage(input, options = {}) {
     throw new Error("Effect package requires a version-15 compiled effect, got version " + (effectRes.m_version ?? "unknown"));
   }
   const permutationGraph = buildEffectPermutationGraph(effectRes);
-  const reflectionPackage = effectRes.m_version === 15 ? buildCompleteEffectReflection(effectRes, permutationGraph, {
-    sourceIdentity,
-    sourcePath: values.source
-  }) : null;
   const variants = buildExportVariants(effectRes, values.allPermutations);
   const bodyMap = new Map();
   const stageMap = new Map();
@@ -73,7 +82,9 @@ function buildEffectPackage(input, options = {}) {
       bodySize: variant.bodySize,
       firstVariantKey: variant.key,
       error: collection.errors.length ? collection.errors.join("; ") : null,
-      manifest: manifest.toJSON(),
+      // Dropping the light family removes its declarations from the
+      // shader, so the manifest must stop advertising them too.
+      manifest: values.localLights === "drop" ? stripLocalLightBindings(manifest.toJSON()) : manifest.toJSON(),
       stages: []
     };
     for (const stage of collection.stages) {
@@ -104,6 +115,8 @@ function buildEffectPackage(input, options = {}) {
         shaderSize: stage.bytecode.shaderSize,
         stringTableOffset: stage.bytecode.stringTableOffset,
         bytes: stage.bytecode.bytes,
+        detailMapArray: stage.detailMapArray,
+        localLights: stage.localLights,
         contracts: [{
           stageKey,
           techniqueName: stage.techniqueName,
@@ -130,10 +143,15 @@ function buildEffectPackage(input, options = {}) {
   const failedShaders = translatedShaders.filter(record => !record.hlsl2webgl?.ok && !record.excluded);
   const excludedShaders = translatedShaders.filter(record => record.excluded);
   const failedBodies = bodies.filter(body => body.error);
+  // The same rule the validator applies to a finished file. This function used
+  // to carry its own copy, and the two had already drifted: the local one had
+  // dropped `hlsl2webgl.reason` from its reason chain, so the library and the
+  // validator could describe one incomplete pass two different ways. If two
+  // places must agree, one of them calls the other.
   const rasterCompleteness = inspectRasterCompleteness(stages, translatedShaders);
   const availableShaderCount = translatedShaders.filter(record => record.hlsl2webgl?.ok && record.source).length;
   const info = {
-    format: "CEWG",
+    format: "CARBON_WEBGL",
     formatVersion: EFFECT_INFO_VERSION,
     packageKind: values.allPermutations ? "tr2-effect-webgl-permutations" : "tr2-effect-webgl",
     targetBackend: "webgl",
@@ -154,11 +172,9 @@ function buildEffectPackage(input, options = {}) {
     permutationMode: values.allPermutations ? "all" : "selected",
     defaultPermutationIndex: defaultPermutationIndex(effectRes.m_permutations),
     sourceEffectVersion: effectRes.m_version,
-    ...(reflectionPackage ? {
-      sourceBodyCoverage: "all-unique",
-      backendBodyCoverage: values.allPermutations ? "all" : "selected",
-      backendProgramCoverage: selectionCoversWholeEffect(values.selection) ? "all-stages" : "filtered"
-    } : {}),
+    sourceBodyCoverage: "all-unique",
+    backendBodyCoverage: values.allPermutations ? "all" : "selected",
+    backendProgramCoverage: selectionCoversWholeEffect(values.selection) ? "all-stages" : "filtered",
     permutationCount: variants.length,
     uniqueBodyCount: bodies.length,
     sourcePermutationCount: permutationGraph.variants.length,
@@ -171,9 +187,6 @@ function buildEffectPackage(input, options = {}) {
       permutationCount: permutationGraph.variants.length,
       uniqueBodyCount: permutationGraph.bodies.length
     },
-    ...(reflectionPackage ? {
-      effectReflection: reflectionPackage.pointer
-    } : {}),
     bodyStageCount: stages.length,
     uniqueShaderCount: translatedShaders.length,
     translatedShaderCount: translatedShaders.length - failedShaders.length - excludedShaders.length,
@@ -187,7 +200,7 @@ function buildEffectPackage(input, options = {}) {
     allowFailures: values.allowFailures,
     completeness: {
       packageValid: true,
-      sourceComplete: reflectionPackage !== null,
+      sourceComplete: effectRes.m_version === 15,
       backendComplete: false,
       runtimeComplete: false
     }
@@ -208,7 +221,7 @@ function buildEffectPackage(input, options = {}) {
     }))
   };
   const glsl = {
-    format: "CEWG_GLSL_SET",
+    format: "CARBON_WEBGL_GLSL_SET",
     formatVersion: 1,
     language: "es300",
     permutationMode: info.permutationMode,
@@ -237,23 +250,40 @@ function buildEffectPackage(input, options = {}) {
     availableShaderCount
   });
   if (!qualification.ok && !values.allowFailures) {
-    throw new Error(`CEWG target is incomplete; output was not built. ${qualification.errors.join("; ")}`);
-  }
-  const chunks = [["INFO", info], ["META", metadata], [EFFECT_PERMUTATION_GRAPH_CHUNK, permutationGraph], ...(reflectionPackage ? [[EFFECT_REFLECTION_CHUNK, reflectionPackage.reflection], [EFFECT_REFLECTION_BLOB_CHUNK, reflectionPackage.blobBytes]] : []), ["GLSL", glsl]];
-  if (values.includeSourceEffect) {
-    chunks.push(["TR2E", values.sourceBytes]);
+    throw new Error(`Carbon WebGL target is incomplete; output was not built. ${qualification.errors.join("; ")}`);
   }
-  const bytes = buildPackage(chunks);
-  const inspection = inspectWithValues(bytes, {
+
+  // The container is the effect. `bytes` is its bytes, and there is no second
+  // artifact — the chunk package this function used to build alongside it is
+  // gone, along with the chunk assembly that produced it.
+  //
+  // `info`, `metadata`, `glsl` and `permutationGraph` are still returned.
+  // They are the in-memory build result, which is richer than
+  // anything the wire carries: the reasons a translation failed live there and
+  // nowhere else. What changed is that they are no longer *also* serialised
+  // into tagged chunks beside the container.
+  const backendBodySet = buildGlslBackendBodySet({
+    bodies,
+    stages,
+    shaders: translatedShaders,
+    variants,
+    permutationGraph
+  });
+  const container = buildGlslEffectContainer(effectRes, permutationGraph, backendBodySet, {
+    compilerVersion: effectRes.m_compilerVersionBytes
+  });
+  const bytes = container.bytes;
+  const inspection = inspectGlslEffectContainer(bytes, {
     source: values.source
   });
   return Object.freeze({
     bytes,
+    permutationCount: container.permutationCount,
+    bodyCount: container.bodyCount,
+    backendBodySet,
     info: Object.freeze(info),
     metadata: Object.freeze(metadata),
     permutationGraph,
-    reflection: reflectionPackage?.reflection ?? null,
-    reflectionBlobs: reflectionPackage?.blobBytes ?? null,
     glsl: Object.freeze(glsl),
     inspection: Object.freeze(inspection),
     qualification: Object.freeze(qualification)
@@ -261,7 +291,7 @@ function buildEffectPackage(input, options = {}) {
 }
 function normalizeOptions(input, options) {
   if (!options || typeof options !== "object" || Array.isArray(options)) {
-    throw new TypeError("CEWG effect options must be an object");
+    throw new TypeError("Carbon WebGL effect options must be an object");
   }
   const sourceBytes = toBytes(input);
   const source = String(options.source ?? "memory").trim() || "memory";
@@ -271,24 +301,36 @@ function normalizeOptions(input, options) {
     stage: options.stage === undefined || options.stage === null ? null : String(options.stage).toLowerCase()
   });
   if (selection.pass !== null && (!Number.isSafeInteger(selection.pass) || selection.pass < 0)) {
-    throw new TypeError("CEWG effect pass must be a non-negative integer or null");
+    throw new TypeError("Carbon WebGL effect pass must be a non-negative integer or null");
   }
   if (selection.stage !== null && !["vertex", "pixel", "compute"].includes(selection.stage)) {
-    throw new TypeError(`Unsupported CEWG effect stage: ${selection.stage}`);
+    throw new TypeError(`Unsupported Carbon WebGL effect stage: ${selection.stage}`);
   }
   if (options.emitterOptions !== undefined && (!options.emitterOptions || typeof options.emitterOptions !== "object" || Array.isArray(options.emitterOptions))) {
-    throw new TypeError("CEWG emitterOptions must be an object");
+    throw new TypeError("Carbon WebGL emitterOptions must be an object");
   }
   return {
     sourceBytes,
     source,
-    outputPath: normalizeOptionalString(options.outputPath, "CEWG outputPath"),
+    outputPath: normalizeOptionalString(options.outputPath, "Carbon WebGL outputPath"),
     sourceIdentity: options.sourceIdentity ?? null,
     generatedAt: options.generatedAt === undefined || options.generatedAt === null ? null : new Date(options.generatedAt).toISOString(),
     allPermutations: options.allPermutations !== false,
     allowFailures: options.allowFailures === true,
-    includeSourceEffect: options.includeSourceEffect === true,
     selection,
+    // How to lower a recognised local-light family. Defaults to leaving it
+    // alone, so a caller that does not ask gets the shader's own resources
+    // and the honest texture count.
+    localLights: normalizeLocalLightMode(options.localLights),
+    // Whether to keep `LightProfileArray`. Defaults to dropping it, because
+    // it costs a fragment sampler unit that the quad family does not have
+    // to spare, and because nothing currently selects a profile: the index
+    // lives in flags bits 4-15 and every `GetCarbonLightData()` writes only
+    // bit 0, so the shader's own guard skips the lookup for every light. A
+    // dropped profile is therefore observationally identical today and a
+    // real loss only once profile indices are written.
+    // See /docs/contracts/carbon-light-data.md.
+    lightProfile: normalizeLightProfileMode(options.lightProfile),
     emitterOptions: {
       ...(options.emitterOptions ?? {})
     }
@@ -317,7 +359,7 @@ function toBytes(input) {
   if (ArrayBuffer.isView(input)) {
     return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
   }
-  throw new TypeError("CEWG effect input must be Uint8Array, ArrayBuffer, or ArrayBufferView bytes");
+  throw new TypeError("Carbon WebGL effect input must be Uint8Array, ArrayBuffer, or ArrayBufferView bytes");
 }
 function defaultPermutationIndex(permutations) {
   let multiplier = 1;
@@ -428,7 +470,12 @@ function collectStages(effectDescription, selection) {
           resources: mapToJson(stageInput.resources),
           samplers: mapToJson(stageInput.samplers),
           uavs: mapToJson(stageInput.uavs),
-          constants: cloneJson(stageInput.constants ?? [])
+          constants: cloneJson(stageInput.constants ?? []),
+          // Recognised from reflection here, applied by the emitter.
+          // The recogniser is shared with WebGPU so both backends
+          // merge exactly the same registers.
+          detailMapArray: recogniseDetailMapFamily(mapToJson(stageInput.resources)),
+          localLights: recogniseLocalLightFamily(mapToJson(stageInput.resources))
         });
       }
       if (!selection.stage && declaredStageCount === 0) {
@@ -441,15 +488,137 @@ function collectStages(effectDescription, selection) {
     errors
   };
 }
+
+/** Local-light lowering modes this packager accepts. */
+const LOCAL_LIGHT_MODES = Object.freeze(["none", "packed-texture", "constant-buffer", "drop"]);
+
+/** How `LightProfileArray` is treated. */
+const LIGHT_PROFILE_MODES = Object.freeze(["drop", "keep"]);
+
+/**
+ * Normalizes the light-profile mode.
+ *
+ * @param {string|undefined|null} value Requested mode.
+ * @returns {string} Normalized mode.
+ */
+function normalizeLightProfileMode(value) {
+  const mode = value === undefined || value === null ? "drop" : String(value);
+  if (!LIGHT_PROFILE_MODES.includes(mode)) {
+    throw new TypeError(`Carbon WebGL lightProfile must be one of ${LIGHT_PROFILE_MODES.join(", ")}; got "${mode}"`);
+  }
+  return mode;
+}
+
+/**
+ * Emitter options that drop `LightProfileArray` and neutralise its samples.
+ *
+ * Only applies when the local-light family is left alone. `packed-texture`,
+ * `constant-buffer` and `drop` each already decide what happens to the profile
+ * register, and asking for it twice would either be redundant or fight them.
+ *
+ * @param {object|null} plan Recognised local-light family, if any.
+ * @param {string} localLightMode Normalized local-light mode.
+ * @param {string} profileMode Normalized light-profile mode.
+ * @returns {object|null} Emitter options, or null when nothing to do.
+ */
+function lightProfileEmitterOptions(plan, localLightMode, profileMode) {
+  if (profileMode !== "drop" || localLightMode !== "none") return null;
+  if (!Number.isInteger(plan?.profileRegister)) return null;
+  return {
+    neutralResourceRegisters: [plan.profileRegister]
+  };
+}
+
+/**
+ * Normalizes the local-light lowering mode.
+ *
+ * @param {string|undefined|null} value Requested mode.
+ * @returns {string} Normalized mode.
+ */
+function normalizeLocalLightMode(value) {
+  if (value === undefined || value === null) return "none";
+  const mode = String(value);
+  if (!LOCAL_LIGHT_MODES.includes(mode)) {
+    throw new TypeError(`Carbon WebGL localLights must be one of ${LOCAL_LIGHT_MODES.join(", ")}; got "${mode}"`);
+  }
+  return mode;
+}
+
+/**
+ * Builds the emitter profile that lowers a recognised local-light family.
+ *
+ * Carbon's local lights are two structured buffers plus an optional profile
+ * texture. WebGL 2 has no structured buffers, so one of these lowerings is
+ * required for the shader to bind its lights at all; WebGPU needs none of it and
+ * binds them natively.
+ *
+ * The constants here match the CLI packager's resolvers exactly, so the two
+ * pipelines produce identical output while they still both exist. They are not
+ * endorsements: `dataTexelBase` and `capacity` are values that happened to work,
+ * and the constant-buffer route is known to fail on light count.
+ *
+ * @param {object} plan Recognised local-light family.
+ * @param {string} mode Lowering mode.
+ * @returns {object|null} Emitter options fragment, or null when not lowering.
+ */
+function localLightEmitterOptions(plan, mode) {
+  if (!plan || mode === "none") return null;
+  if (mode === "drop") {
+    // No lighting at all: the declarations go and every read lowers to zero.
+    // Kept because isolating a lighting problem is easier without lights,
+    // not because the texture budget needs it any more.
+    return {
+      stubResourceRegisters: plan.registers
+    };
+  }
+  if (mode === "packed-texture") {
+    return {
+      lightPackedTexture: {
+        indexRegister: plan.indexRegister,
+        dataRegister: plan.dataRegister,
+        profileRegister: plan.profileRegister,
+        registerIndex: plan.indexRegister,
+        name: "cjsLocalLightTexture",
+        dataTexelBase: 131072
+      }
+    };
+  }
+  if (mode === "constant-buffer") {
+    // Slot 6 is `g_uiTransforms` in the constant-buffer slot contract. There
+    // is no collision on space-object shaders, which carry no UI transforms,
+    // but this is squatting on a reserved number and should move.
+    return {
+      lightConstantBuffer: {
+        indexRegister: plan.indexRegister,
+        dataRegister: plan.dataRegister,
+        profileRegister: plan.profileRegister,
+        registerIndex: 6,
+        name: "cb6",
+        capacity: 40
+      }
+    };
+  }
+  throw new Error(`Unknown local-light lowering mode "${mode}"`);
+}
 function translateStages(shaderMap, stageMap, values) {
   const emitInto = (record, pairVaryings) => {
     try {
+      const profileNeutral = lightProfileEmitterOptions(record.localLights, values.localLights, values.lightProfile);
+      // Remembered on the record so the body set can emit the resource
+      // transform that accounts for the dropped resource. The transform's
+      // identity includes the pass key, which is not known here.
+      if (profileNeutral) record.lightProfileNeutral = record.localLights;
       const result = emitGlslWithOptions(record.bytes, {
         ...values.emitterOptions,
         source: `${values.source}#${record.firstStageKey}`,
         ...(pairVaryings?.length ? {
           pairVaryings
-        } : {})
+        } : {}),
+        ...(record.detailMapArray ? {
+          detailMapArrayRegisters: record.detailMapArray.registers
+        } : {}),
+        ...(localLightEmitterOptions(record.localLights, values.localLights) ?? {}),
+        ...(profileNeutral ?? {})
       });
       const stageInterface = normalizeBitangentStageInterface(result, record);
       record.emit = {
@@ -662,80 +831,19 @@ function validateStageSourceShape(record) {
   if (record.stageName === "pixel" && (hasVertexOutput || hasVertexInterface) && !hasFragmentOutput) {
     return "pixel stage source looks like vertex GLSL";
   }
-  if (record.stageName === "compute" && !/\bcewgUav\d+(_s\d+)?\b/u.test(source)) {
-    return "compute stage source does not write any cewgUav output";
+  if (record.stageName === "compute" && !/\bcjsUav\d+(_s\d+)?\b/u.test(source)) {
+    return "compute stage source does not write any cjsUav output";
   }
   return null;
 }
-function inspectRasterCompleteness(stages, shaders) {
-  const shaderMap = new Map(shaders.map(shader => [shader.key, shader]));
-  const groups = new Map();
-  for (const stage of stages) {
-    if (!["vertex", "pixel"].includes(stage.stageName)) {
-      continue;
-    }
-    const key = `${stage.bodyKey}:${stage.techniqueName}:${stage.passIndex}`;
-    const group = groups.get(key) ?? {
-      key,
-      bodyKey: stage.bodyKey,
-      techniqueName: stage.techniqueName,
-      passIndex: stage.passIndex,
-      vertex: null,
-      pixel: null,
-      duplicateStages: []
-    };
-    if (group[stage.stageName]) {
-      group.duplicateStages.push(stage.stageName);
-    }
-    group[stage.stageName] = stage;
-    groups.set(key, group);
-  }
-  const incompletePasses = [];
-  let completePassCount = 0;
-  for (const group of groups.values()) {
-    const missingStages = [];
-    const unavailableStages = [];
-    for (const stageName of ["vertex", "pixel"]) {
-      const stage = group[stageName];
-      if (!stage) {
-        missingStages.push(stageName);
-        continue;
-      }
-      const shader = shaderMap.get(stage.shaderKey);
-      if (!shader?.hlsl2webgl?.ok || !shader.source) {
-        unavailableStages.push({
-          stageName,
-          stageKey: stage.key,
-          shaderKey: stage.shaderKey,
-          reason: shader?.hlsl2webgl?.validationError || shader?.hlsl2webgl?.error || shader?.excluded?.reason || "translated source is unavailable"
-        });
-      }
-    }
-    if (!missingStages.length && !unavailableStages.length && !group.duplicateStages.length) {
-      completePassCount++;
-    } else {
-      incompletePasses.push({
-        ...group,
-        missingStages,
-        unavailableStages,
-        duplicateStages: [...new Set(group.duplicateStages)].sort()
-      });
-    }
-  }
-  return {
-    expectedPassCount: groups.size,
-    completePassCount,
-    incompletePasses
-  };
-}
 function normalizeSourceIdentity(values) {
   const identity = values.sourceIdentity;
   if (identity !== null && (!identity || typeof identity !== "object" || Array.isArray(identity))) {
-    throw new TypeError("CEWG sourceIdentity must be an object");
+    throw new TypeError("Carbon WebGL sourceIdentity must be an object");
   }
   const sha256 = sha256Bytes(values.sourceBytes);
   if (identity?.sha256 !== undefined && identity?.sha256 !== null && identity.sha256 !== sha256) {
-    throw new Error("CEWG sourceIdentity.sha256 does not match the exact effect input bytes");
+    throw new Error("Carbon WebGL sourceIdentity.sha256 does not match the exact effect input bytes");
   }
   return Object.freeze({
     filePath: identity?.filePath ?? values.source,
@@ -759,11 +867,11 @@ function qualifyEffectPackage({
   availableShaderCount
 }) {
   const errors = [];
-  if (info.format !== "CEWG" || glsl.format !== "CEWG_GLSL_SET") {
-    errors.push("invalid CEWG package envelope");
+  if (info.format !== "CARBON_WEBGL" || glsl.format !== "CARBON_WEBGL_GLSL_SET") {
+    errors.push("invalid Carbon WebGL package envelope");
   }
   if (!Array.isArray(metadata.variants) || !Array.isArray(glsl.shaders)) {
-    errors.push("missing CEWG graph arrays");
+    errors.push("missing Carbon WebGL graph arrays");
   }
   if (failedShaders.length) {
     errors.push(`${failedShaders.length} shader translation(s) failed`);