@carbonenginejs/runtime-resource 0.12.0 → 0.12.1

package/docs/formats/webgl/reference/classes/README.md

@@ -1,96 +1,9 @@
-# Class catalog
+# WebGL class catalog
 
-Status: Evolving
+Status: Deprecated
 Scope: `@carbonenginejs/runtime-resource/formats/webgl` maintained classes
 Audience: Users, maintainers, and automated readers
-Summary: Provides one-sentence purpose descriptors for every maintained class.
+Summary: Points to the canonical package-wide class catalog after format-package consolidation.
 
-<!-- class:CjsWebglFormat -->
-## `CjsWebglFormat`
-
-CarbonEngineJS-facing format surface for `.cewg` WebGL shader packages, and a DXBC -> GLSL ES 3.00 emitter for the WebGL2 vertex/pixel/map-style-compute stages ccpwgl targets.
-
-- Export: `@carbonenginejs/runtime-resource/formats/webgl`
-- Source: `src/CjsWebglFormat.js`
-- Visibility: Public
-- Kind: CarbonEngineJS
-
-<!-- class:CewgPackage -->
-## `CewgPackage`
-
-Reader for CarbonEngineJS CEWG shader packages emitted by `hlsl2webgl`.
-
-- Export: None
-- Source: `src/core/cewg/CewgPackage.js`
-- Visibility: Internal
-- Kind: Internal implementation
-
-<!-- class:CewgPackageBuilder -->
-## `CewgPackageBuilder`
-
-Builds CarbonEngineJS CEWG shader package bytes.
-
-- Export: None
-- Source: `src/core/cewg/CewgPackageBuilder.js`
-- Visibility: Internal
-- Kind: Internal implementation
-
-<!-- class:CjsBinaryReader -->
-## `CjsBinaryReader`
-
-Minimal little-endian binary reader for the flat CEWG chunk container.
-
-- Export: None
-- Source: `src/core/cewg/binary.js`
-- Visibility: Internal
-- Kind: Internal implementation
-
-<!-- class:ReflectionBlobStore -->
-## `ReflectionBlobStore`
-
-Builds a deterministic deduplicated byte arena for portable reflection.
-
-- Export: None
-- Source: `src/core/effectReflectionPackage.js`
-- Visibility: Internal
-- Kind: Internal implementation
-
-<!-- class:CjsWebglReadError -->
-## `CjsWebglReadError`
-
-Error raised when a CEWG package or a DXBC-to-GLSL emission cannot be completed safely.
-
-- Export: None
-- Source: `src/core/errors.js`
-- Visibility: Internal
-- Kind: Internal implementation
-
-<!-- class:DxbcGlslEmitter -->
-## `DxbcGlslEmitter`
-
-DXBC -> GLSL ES 3.00 emitter for vertex and pixel stages.
-
-- Export: None
-- Source: `src/core/glsl/DxbcGlslEmitter.js`
-- Visibility: Internal
-- Kind: Internal implementation
-
-<!-- class:DxbcGlslHelperRegistry -->
-## `DxbcGlslHelperRegistry`
-
-Registry of GLSL helper functions the emitter can require per shader.
-
-- Export: None
-- Source: `src/core/glsl/DxbcGlslHelpers.js`
-- Visibility: Internal
-- Kind: Internal implementation
-
-<!-- class:DxbcGlslOperandFormatter -->
-## `DxbcGlslOperandFormatter`
-
-Formats decoded DXBC operands as GLSL ES 3.00 expressions and assignments.
-
-- Export: None
-- Source: `src/core/glsl/DxbcGlslOperandFormatter.js`
-- Visibility: Internal
-- Kind: Internal implementation
+The maintained WebGL entries now live in the
+[package-wide formats class catalog](../../../../reference/classes/formats.md#webgl).

package/docs/formats/webgpu/README.md

@@ -3,32 +3,35 @@
 Status: Evolving
 Scope: `@carbonenginejs/runtime-resource/formats/webgpu`
 Audience: Shader-tool authors, engine integrators, and maintainers
-Summary: Explains the CEWGPU package format, compiled-effect conversion API, and bounded DXBC-to-WGSL compiler.
+Summary: Explains the Carbon-record CEWGPU format, compiled-effect conversion API, and bounded DXBC-to-WGSL compiler.
 
 ## Purpose
 
-`@carbonenginejs/runtime-resource/formats/webgpu` reads and builds CEWGPU shader packages and
-converts supported compiled effect stages into portable WGSL package data. It
+`@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 CEWGPU assembly.
+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 complete source
-permutation topology in `PGRF` and, for version-15 effects, complete portable
-reflection for every unique body in RFLX v2/RBLB. ANLS/WGSL remain selected
-backend-body data, so backend and runtime completeness are still open.
+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 `format-webgpu` when you need to:
+Use the WebGPU format subpath when you need to:
 
 - inspect or build a `.cewgpu` 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
-- convert one selected compiled-effect body/pass scope into a CEWGPU package while
-  preserving its complete version-15 source permutation graph and all-unique
-  portable reflection.
+- 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
@@ -40,15 +43,15 @@ belong in `@carbonenginejs/engine-webgpu`.
 ```text
 compiled effect bytes
         |
-        +---- format-hlsl ---- effect and binding metadata
+        +---- formats/hlsl ---- effect and binding metadata
         |
-        +---- format-dxbc ---- decoded shader programs
+        +---- formats/dxbc ---- decoded shader programs
         |                              |
         +------------------------------+
                        |
                        v
-                format-webgpu
-          analysis + WGSL + CEWGPU
+               formats/webgpu
+       analysis + WGSL + Carbon records
                        |
                        v
                  engine-webgpu

package/docs/formats/webgpu/architecture.md

@@ -7,10 +7,10 @@ Summary: Defines the package's compiler, container, dependency, and engine bound
 
 ## Purpose
 
-`format-webgpu` is the transformation and package layer between compiled
-Carbon-style effects and WebGPU engine realization. It converts supported
-shader programs into portable WGSL descriptors without creating live GPU
-objects.
+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
 
@@ -35,12 +35,15 @@ then package data to the engine.
 
 ## Owned responsibilities
 
-- Reading, inspecting, and building the CEWGPU v1 chunk container.
+- Reading, inspecting, and building Carbon-record CEWGPU containers.
 - Resolving one compiled-effect permutation and complete pass.
-- Validating and preserving every source permutation index and raw-body alias
-  in a backend-neutral identity-only graph.
-- Packing every unique version-15 body's complete shared portable reflection,
-  with exact immutable byte vectors in one validated blob arena.
+- 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.
@@ -51,11 +54,11 @@ then package data to the engine.
 
 ## Ownership elsewhere
 
-- `format-hlsl` owns compiled-effect parsing, permutation resolution,
+- `@carbonenginejs/runtime-resource/formats/hlsl` owns compiled-effect parsing, permutation resolution,
   unique-body enumeration, binding-manifest interpretation, and the shared
   body-local portable reflection schema/validator.
-- `format-dxbc` owns DXBC container and instruction decoding.
-- `engine-webgpu` owns `GPUDevice`, shader-module compilation, bind groups,
+- `@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.