@carbonenginejs/runtime-resource 0.13.0 → 0.14.0

package/docs/formats/webgpu/README.md

@@ -1,84 +1,84 @@
-# WebGPU format documentation
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-resource/formats/webgpu`
-Audience: Shader-tool authors, engine integrators, and maintainers
-Summary: Explains the Carbon-record Carbon WebGPU format, compiled-effect conversion API, and bounded DXBC-to-WGSL compiler.
-
-## Purpose
-
-`@carbonenginejs/runtime-resource/formats/webgpu` reads and builds WebGPU
-effect containers and converts supported compiled-effect stages into WGSL. It
-owns effect analysis, DXBC-to-intermediate-representation lowering, WGSL
-emission, pass-global binding planning, and the WebGPU backend block carried by
-Carbon version-15 records.
-
-Unsupported requested shader semantics fail explicitly instead of producing a
-partially translated selected pass. `BuildEffect` preserves every permutation
-row and representable non-program description/reflection fields in the Carbon
-container. Non-dynamic sampler names are unrecoverable and stage order is
-canonicalized. Source-stage DXBC is replaced by WGSL or an empty program slot.
-Selected mode writes WGSL only for the resolved body's requested passes; all
-mode attempts every distinct body after the resolved body passes the initial
-translation gate. Backend and runtime completeness remain broader gates.
-
-## Use this package when
-
-Use the WebGPU format subpath when you need to:
-
-- inspect or build a `.carbonwebgpu` package;
-- analyze caller-supplied compiled effect bytes;
-- lower supported DXBC vertex and fragment programs to WGSL;
-- build one collision-free WebGPU binding layout across a complete pass; or
-- translate selected or all distinct version-15 effect bodies while preserving
-  permutation topology and representable non-program reflection fields.
-
-Use `@carbonenginejs/runtime-resource/formats/hlsl` directly for effect metadata without WGSL
-conversion, and `@carbonenginejs/runtime-resource/formats/dxbc` directly for standalone DXBC
-inspection. GPU device, shader-module, bind-group, and pipeline realization
-belong in `@carbonenginejs/engine-webgpu`.
-
-## Where it fits
-
-```text
-compiled effect bytes
-        |
-        +---- formats/hlsl ---- effect and binding metadata
-        |
-        +---- formats/dxbc ---- decoded shader programs
-        |                              |
-        +------------------------------+
-                       |
-                       v
-               formats/webgpu
-       analysis + WGSL + Carbon records
-                       |
-                       v
-                 engine-webgpu
-```
-
-The package is browser-safe at its public source boundary. Repository-only
-commands may adapt filesystem input for development, but the core conversion
-path accepts bytes and does not depend on Node filesystem APIs or native
-executables.
-
-## Start here
-
-```js
-import { CjsWebgpuFormat } from "@carbonenginejs/runtime-resource/formats/webgpu";
-
-const summary = CjsWebgpuFormat.inspect(packageBytes);
-const packageData = CjsWebgpuFormat.read(packageBytes);
-```
-
-For compiled-effect conversion, continue with the
-[effect packaging guide](guides/effect-packaging.md).
-
-## Documentation map
-
-- [Architecture and boundaries](architecture.md)
-- [Effect packaging guide](guides/effect-packaging.md)
-- [Public API reference](reference/api.md)
-- [Carbon WebGPU package format](formats/carbon-webgpu.md)
-- [WGSL compatibility](reference/wgsl-compatibility.md)
-- [Class-purpose catalog](reference/classes/README.md)
+# WebGPU format documentation
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/webgpu`
+Audience: Shader-tool authors, engine integrators, and maintainers
+Summary: Explains the Carbon-record Carbon WebGPU format, compiled-effect conversion API, and bounded DXBC-to-WGSL compiler.
+
+## Purpose
+
+`@carbonenginejs/runtime-resource/formats/webgpu` reads and builds WebGPU
+effect containers and converts supported compiled-effect stages into WGSL. It
+owns effect analysis, DXBC-to-intermediate-representation lowering, WGSL
+emission, pass-global binding planning, and the WebGPU backend block carried by
+Carbon version-15 records.
+
+Unsupported requested shader semantics fail explicitly instead of producing a
+partially translated selected pass. `BuildEffect` preserves every permutation
+row and representable non-program description/reflection fields in the Carbon
+container. Non-dynamic sampler names are unrecoverable and stage order is
+canonicalized. Source-stage DXBC is replaced by WGSL or an empty program slot.
+Selected mode writes WGSL only for the resolved body's requested passes; all
+mode attempts every distinct body after the resolved body passes the initial
+translation gate. Backend and runtime completeness remain broader gates.
+
+## Use this package when
+
+Use the WebGPU format subpath when you need to:
+
+- inspect or build a `.carbonwebgpu` package;
+- analyze caller-supplied compiled effect bytes;
+- lower supported DXBC vertex and fragment programs to WGSL;
+- build one collision-free WebGPU binding layout across a complete pass; or
+- translate selected or all distinct version-15 effect bodies while preserving
+  permutation topology and representable non-program reflection fields.
+
+Use `@carbonenginejs/runtime-resource/formats/hlsl` directly for effect metadata without WGSL
+conversion, and `@carbonenginejs/runtime-resource/formats/dxbc` directly for standalone DXBC
+inspection. GPU device, shader-module, bind-group, and pipeline realization
+belong in `@carbonenginejs/engine-webgpu`.
+
+## Where it fits
+
+```text
+compiled effect bytes
+        |
+        +---- formats/hlsl ---- effect and binding metadata
+        |
+        +---- formats/dxbc ---- decoded shader programs
+        |                              |
+        +------------------------------+
+                       |
+                       v
+               formats/webgpu
+       analysis + WGSL + Carbon records
+                       |
+                       v
+                 engine-webgpu
+```
+
+The package is browser-safe at its public source boundary. Repository-only
+commands may adapt filesystem input for development, but the core conversion
+path accepts bytes and does not depend on Node filesystem APIs or native
+executables.
+
+## Start here
+
+```js
+import { CjsWebgpuFormat } from "@carbonenginejs/runtime-resource/formats/webgpu";
+
+const summary = CjsWebgpuFormat.inspect(packageBytes);
+const packageData = CjsWebgpuFormat.read(packageBytes);
+```
+
+For compiled-effect conversion, continue with the
+[effect packaging guide](guides/effect-packaging.md).
+
+## Documentation map
+
+- [Architecture and boundaries](architecture.md)
+- [Effect packaging guide](guides/effect-packaging.md)
+- [Public API reference](reference/api.md)
+- [Carbon WebGPU package format](formats/carbon-webgpu.md)
+- [WGSL compatibility](reference/wgsl-compatibility.md)
+- [Class-purpose catalog](reference/classes/README.md)

package/docs/formats/webgpu/architecture.md

@@ -1,95 +1,95 @@
-# Architecture and boundaries
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-resource/formats/webgpu`
-Audience: Shader-tool authors, engine integrators, and maintainers
-Summary: Defines the package's compiler, container, dependency, and engine boundaries.
-
-## Purpose
-
-The WebGPU format subpath is the transformation and package layer between
-compiled Carbon effects and WebGPU engine realization. It converts supported
-shader programs into WGSL and writes Carbon version-15 effect records without
-creating live GPU objects.
-
-## Dependency direction
-
-```text
-@carbonenginejs/runtime-resource/formats/hlsl
-          |
-          +---- effect selection and binding metadata
-          |
-          v
-@carbonenginejs/runtime-resource/formats/webgpu <---- @carbonenginejs/runtime-resource/formats/dxbc
-          |                              decoded DXBC
-          |
-          +---- Carbon WebGPU bytes, analysis, WGSL, canonical layouts
-          |
-          v
-@carbonenginejs/engine-webgpu
-```
-
-Node build tools may call the public byte-oriented API, but the format package
-does not import the toolchain. Dependency direction remains tools to formats,
-then package data to the engine.
-
-## Owned responsibilities
-
-- Reading, inspecting, and building Carbon-record Carbon WebGPU containers.
-- Resolving one compiled-effect permutation and complete pass.
-- Preserving every source permutation row and representable non-program
-  description field; non-dynamic sampler names are unrecoverable and stage
-  order is canonicalized.
-  Stored-body identity is exact emitted-description-byte identity; it does not
-  promise to retain the source alias partition after programs are replaced.
-- Writing WGSL to program slots and bind-group/transform data to the optional
-  per-pass backend block.
-- Normalizing effect, stage, binding, and decoded DXBC analysis.
-- Building validated shader intermediate representation and structured control
-  flow.
-- Lowering the supported vertex and fragment profiles to WGSL.
-- Allocating a pass-global binding plan with explicit stage scope.
-- Assembling emitted shaders and layouts into a portable WGSL set.
-- Rejecting unsupported or ambiguous semantics with explicit diagnostics.
-
-## Ownership elsewhere
-
-- `@carbonenginejs/runtime-resource/formats/hlsl` owns compiled-effect parsing, permutation resolution,
-  unique-body enumeration, and binding-manifest interpretation.
-- `@carbonenginejs/runtime-resource/formats/dxbc` owns DXBC container and instruction decoding.
-- `@carbonenginejs/engine-webgpu` owns `GPUDevice`, shader-module compilation, bind groups,
-  pipelines, resource realization, device loss, and draw execution.
-- Node tooling owns indexed input acquisition, filesystem adapters, caching,
-  build reports, and optional native comparison.
-- `runtime-resource` owns effect-resource lifecycle, permutation selection,
-  canonical device-free `Tr2Shader` hydration, and shader caching.
-- `runtime-trinity` owns authored effect/material facades, parameters, options,
-  sampler overrides, and scene references.
-
-## Browser and Node boundary
-
-The public class accepts `ArrayBuffer`, typed-array, and compatible byte views.
-Its source does not read files, inspect processes, or invoke native programs.
-This allows applications to fetch or select bytes and build Carbon WebGPU data in a
-browser.
-
-The repository's command-line scripts are development adapters over the same
-public operations. They are not a second compiler contract.
-
-## Shader target
-
-The general translation target is DX11 SM5.0 vertex and fragment bytecode.
-The compiler also admits a finite, frozen set of exact bounded compute
-profiles. DX12 SM5.1 input is useful for differential analysis where
-supported, but DX12-only bindless resource ranges are not part of the current
-translation target.
-
-Geometry, hull, and domain stages, plus compute programs outside the admitted
-profiles, are not emitted. The exact supported and adapted boundaries are
-listed in [WGSL compatibility](reference/wgsl-compatibility.md).
-
-## Related documentation
-
-- [Package documentation](README.md)
-- [Carbon WebGPU package format](formats/carbon-webgpu.md)
-- [Public API reference](reference/api.md)
+# Architecture and boundaries
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/webgpu`
+Audience: Shader-tool authors, engine integrators, and maintainers
+Summary: Defines the package's compiler, container, dependency, and engine boundaries.
+
+## Purpose
+
+The WebGPU format subpath is the transformation and package layer between
+compiled Carbon effects and WebGPU engine realization. It converts supported
+shader programs into WGSL and writes Carbon version-15 effect records without
+creating live GPU objects.
+
+## Dependency direction
+
+```text
+@carbonenginejs/runtime-resource/formats/hlsl
+          |
+          +---- effect selection and binding metadata
+          |
+          v
+@carbonenginejs/runtime-resource/formats/webgpu <---- @carbonenginejs/runtime-resource/formats/dxbc
+          |                              decoded DXBC
+          |
+          +---- Carbon WebGPU bytes, analysis, WGSL, canonical layouts
+          |
+          v
+@carbonenginejs/engine-webgpu
+```
+
+Node build tools may call the public byte-oriented API, but the format package
+does not import the toolchain. Dependency direction remains tools to formats,
+then package data to the engine.
+
+## Owned responsibilities
+
+- Reading, inspecting, and building Carbon-record Carbon WebGPU containers.
+- Resolving one compiled-effect permutation and complete pass.
+- Preserving every source permutation row and representable non-program
+  description field; non-dynamic sampler names are unrecoverable and stage
+  order is canonicalized.
+  Stored-body identity is exact emitted-description-byte identity; it does not
+  promise to retain the source alias partition after programs are replaced.
+- Writing WGSL to program slots and bind-group/transform data to the optional
+  per-pass backend block.
+- Normalizing effect, stage, binding, and decoded DXBC analysis.
+- Building validated shader intermediate representation and structured control
+  flow.
+- Lowering the supported vertex and fragment profiles to WGSL.
+- Allocating a pass-global binding plan with explicit stage scope.
+- Assembling emitted shaders and layouts into a portable WGSL set.
+- Rejecting unsupported or ambiguous semantics with explicit diagnostics.
+
+## Ownership elsewhere
+
+- `@carbonenginejs/runtime-resource/formats/hlsl` owns compiled-effect parsing, permutation resolution,
+  unique-body enumeration, and binding-manifest interpretation.
+- `@carbonenginejs/runtime-resource/formats/dxbc` owns DXBC container and instruction decoding.
+- `@carbonenginejs/engine-webgpu` owns `GPUDevice`, shader-module compilation, bind groups,
+  pipelines, resource realization, device loss, and draw execution.
+- Node tooling owns indexed input acquisition, filesystem adapters, caching,
+  build reports, and optional native comparison.
+- `runtime-resource` owns effect-resource lifecycle, permutation selection,
+  canonical device-free `Tr2Shader` hydration, and shader caching.
+- `runtime-trinity` owns authored effect/material facades, parameters, options,
+  sampler overrides, and scene references.
+
+## Browser and Node boundary
+
+The public class accepts `ArrayBuffer`, typed-array, and compatible byte views.
+Its source does not read files, inspect processes, or invoke native programs.
+This allows applications to fetch or select bytes and build Carbon WebGPU data in a
+browser.
+
+The repository's command-line scripts are development adapters over the same
+public operations. They are not a second compiler contract.
+
+## Shader target
+
+The general translation target is DX11 SM5.0 vertex and fragment bytecode.
+The compiler also admits a finite, frozen set of exact bounded compute
+profiles. DX12 SM5.1 input is useful for differential analysis where
+supported, but DX12-only bindless resource ranges are not part of the current
+translation target.
+
+Geometry, hull, and domain stages, plus compute programs outside the admitted
+profiles, are not emitted. The exact supported and adapted boundaries are
+listed in [WGSL compatibility](reference/wgsl-compatibility.md).
+
+## Related documentation
+
+- [Package documentation](README.md)
+- [Carbon WebGPU package format](formats/carbon-webgpu.md)
+- [Public API reference](reference/api.md)