@carbonenginejs/runtime-resource 0.12.1 → 0.13.0

package/docs/formats/webgpu/reference/api.md

@@ -1,197 +1,196 @@
-# Public API reference
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-resource/formats/webgpu`
-Audience: Shader-tool authors and engine integrators
-Summary: Lists the public WebGPU format profile, byte-oriented helpers, options, and output contracts.
-
-## Import
-
-```js
-import CjsWebgpuFormat, {
-    CjsWebgpuFormat as WebgpuFormat
-} from "@carbonenginejs/runtime-resource/formats/webgpu";
-```
-
-The default and named exports refer to the same class.
-
-## Reusable profile
-
-Construct a profile when several operations share output, source, schema, or
-class-registration options. `permutation` is also reusable by `AnalyzeEffect`
-and `BuildEffect`; current `Read` and `Inspect` derive the translated body or
-Carbon defaults and do not consume that profile field:
-
-```js
-const reader = new WebgpuFormat({
-    emit: "json",
-    source: "res:/graphics/effect.webgpu/example.sm_hi",
-    decodeInstructions: true,
-    permutation: null
-});
-```
-
-| Instance method | Purpose |
-| --- | --- |
-| `SetValues(options)` | Merges reusable profile defaults. |
-| `GetValues(options?)` | Returns effective values with optional overrides. |
-| `SetClasses(classes)` | Registers several package-shape constructors. |
-| `SetClass(type, Class)` | Registers or removes one constructor. |
-| `GetClass(type)` | Returns one registered constructor. |
-| `HasClass(type)` | Reports whether a constructor is registered. |
-| `Read(bytes, options?)` | Reads Carbon-record CEWGPU bytes. |
-| `Inspect(bytes, options?)` | Returns a compact container summary. |
-| `AnalyzeEffect(bytes, options?)` | Analyzes compiled-effect bytes without packaging. |
-| `BuildEffect(bytes, options?)` | Translates a version-15 effect to CEWGPU bytes. |
-| `BuildShaderIr(input, options?)` | Builds validated shader IR from DXBC or decoded input. |
-| `BuildWgsl(input, options?)` | Emits supported shader IR as WGSL. |
-| `BuildWgslBindingPlan(programs, options?)` | Allocates one binding layout across a pass. |
-| `BuildWgslSet(entries)` | Assembles emitted shaders and pass layouts. |
-| `ToJSON(value)` | Converts format output to JSON-compatible data. |
-
-There is no `Build(chunks)` method. The current wire is a Carbon record tree,
-not a generic chunk container.
-
-## Static helpers
-
-| Static helper | Purpose |
-| --- | --- |
-| `isCewgpu(bytes)` | Reports whether bytes have the Carbon-v15 shape. |
-| `read(bytes, options?)` | Reads one container. |
-| `inspect(bytes, options?)` | Inspects one container. |
-| `analyzeEffect(bytes, options?)` | Analyzes one compiled effect. |
-| `buildEffect(bytes, options?)` | Builds CEWGPU bytes from a version-15 effect. |
-| `buildShaderIr(input, options?)` | Builds shader IR. |
-| `buildWgsl(input, options?)` | Emits WGSL. |
-| `buildWgslBindingPlan(programs, options?)` | Allocates a pass binding plan. |
-| `buildWgslSet(entries)` | Builds a portable WGSL set. |
-| `toJSON(value)` | Converts output to JSON-compatible data. |
-
-`isCewgpu` checks the first dword for Carbon version 15. CEWGPU has no private
-magic or payload tag, so this is a shape check rather than backend identity.
-Callers establish identity through the resource path that supplied the bytes.
-
-## Profile options
-
-| Option | Meaning |
-| --- | --- |
-| `emit` | `"json"` by default or `"raw"` for the internal container reader. |
-| `source` | Caller-owned diagnostic label; it is never opened. |
-| `decodeInstructions` | Includes decoded instruction and IR detail during analysis. |
-| `permutation` | Exact `NAME=VALUE` assertions for `AnalyzeEffect` and `BuildEffect`; ignored by current `Read` and `Inspect`. |
-| `schema` | Optional caller schema record retained by the profile. |
-| `classes` | Optional constructor registrations keyed by `CLASS_KEYS`. |
-
-Class registrations are validated and stored for forward compatibility.
-Current JSON reads return plain data rather than hydrated package classes.
-
-Raw output is an internal reader over the same bytes. It is not a second wire
-format and should not be persisted.
-
-## Read result
-
-JSON `Read` returns:
-
-- `format`, Carbon `version`, and `sourcePath`;
-- derived `info` and `metadata`;
-- the complete derived `permutationGraph`;
-- derived `analysis`, `wgsl`, and `backendBodySet`;
-- convenience `stages`, `shaders`, and `layouts` arrays.
-
-These records are computed from the Carbon header, descriptions, WGSL program
-slots, and backend blocks. They are not stored chunks. The old `chunks` field
-is intentionally absent.
-
-`Inspect` reports the source label, Carbon version, compiler-version bytes,
-permutation count, distinct-body count, and resolved stage/shader/layout
-counts.
-
-## Effect analysis
-
-`AnalyzeEffect` accepts supported compiled-effect versions for diagnostic
-analysis. It resolves exact permutation assertions and may include decoded
-DXBC instructions and compiler IR.
-
-`BuildEffect` is narrower: current packaging requires the version-15 record
-layout. The wire retains every permutation row and non-program description
-field that the mapping can represent; non-dynamic sampler names are
-unrecoverable and stage order is canonicalized. Source-stage DXBC and the
-caller's source hash are not retained in the wire. The build result retains
-full portable source reflection, including source program bytes. Compiler IR
-is transient and is neither stored in the wire nor returned by `BuildEffect`.
-
-Unknown, duplicate, or unresolved permutation assertions fail closed.
-
-## Effect-package options
-
-`mode: "selected"` is the default. It translates the resolved body's
-requested complete passes while keeping every permutation row and
-representable non-program description fields in the container.
-
-`mode: "all"` first lowers the resolved selection, so an unsupported resolved
-body aborts the build. After that gate succeeds, unsupported later bodies
-remain in the container with empty program slots and appear as unsupported in
-the in-memory body-set view. `allPermutations: true` is a compatibility
-spelling for all mode.
-
-`selection` can name a technique, pass index, and complete stage list.
-`bindingPolicy.sharedIdentities` may name compatible cross-stage resources
-that are allowed to share one physical binding.
-
-`source` remains a diagnostic label. `sourceIdentity` and `outputPath` are
-returned build provenance; the wire's backend identity still comes from the
-consumer's resource path.
-
-## Build result and qualification
-
-`BuildEffect` returns:
-
-- `bytes`;
-- build-time `info` and `metadata`;
-- `permutationGraph`, portable `reflection`, and `reflectionBlobs`;
-- selected `analysis` and `wgsl`;
-- `backendBodySet` for all mode;
-- an `inspection` obtained by rereading the emitted bytes; and
-- `qualification`.
-
-The richer fields are caller evidence and are not separately stored in the
-container.
-
-`qualification.packageValid` reports structural construction. It does not
-claim that every body translated, that a pipeline was prepared, or that a
-draw succeeded. `backendComplete` and `runtimeComplete` retain those broader
-boundaries.
-
-## Binding-plan and WGSL-set helpers
-
-`BuildWgslBindingPlan` takes the complete program set for one pass.
-Unshared D3D tuples receive stage-qualified `scopeIdentity` values. A tuple is
-shared only when its base identity appears in `sharedIdentities` and the
-declarations are compatible.
-
-`BuildWgslSet` validates shader keys, layouts, numeric slots, and resource
-transforms. Ordinary sets use version 2. A proven physical-resource
-coalescing uses version 3 and carries an explicit transform recipe.
-
-## Static metadata
-
-The class exposes `OUTPUT_JSON`, `OUTPUT_RAW`, `CLASS_KEYS`, `type`,
-`mediaTypes`, `inputTypes`, `outputTypes`, `debugOutputTypes`,
-`implementationStatus`, `format`, `analysisFormat`, and `packageVersion`.
-
-## Errors
-
-Reads fail closed on malformed Carbon records, sparse or misordered
-permutation tables, out-of-range arena references, trailing record bytes, or a
-program-bearing stage WebGPU cannot express.
-
-Builds additionally fail on unsupported source versions, invalid selection,
-unsupported compiler semantics, ambiguous binding plans, non-`main` entry
-points, and malformed backend blocks.
-
-## Related documentation
-
-- [Effect packaging guide](../guides/effect-packaging.md)
-- [CEWGPU effect container](../formats/cewgpu.md)
-- [WGSL compatibility](wgsl-compatibility.md)
-- [Class-purpose catalog](classes/README.md)
+# Public API reference
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/webgpu`
+Audience: Shader-tool authors and engine integrators
+Summary: Lists the public WebGPU format profile, byte-oriented helpers, options, and output contracts.
+
+## Import
+
+```js
+import CjsWebgpuFormat, {
+    CjsWebgpuFormat as WebgpuFormat
+} from "@carbonenginejs/runtime-resource/formats/webgpu";
+```
+
+The default and named exports refer to the same class.
+
+## Reusable profile
+
+Construct a profile when several operations share output, source, schema, or
+class-registration options. `permutation` is also reusable by `AnalyzeEffect`
+and `BuildEffect`; current `Read` and `Inspect` derive the translated body or
+Carbon defaults and do not consume that profile field:
+
+```js
+const reader = new WebgpuFormat({
+    emit: "json",
+    source: "res:/graphics/effect.webgpu/example.sm_hi",
+    decodeInstructions: true,
+    permutation: null
+});
+```
+
+| Instance method | Purpose |
+| --- | --- |
+| `SetValues(options)` | Merges reusable profile defaults. |
+| `GetValues(options?)` | Returns effective values with optional overrides. |
+| `SetClasses(classes)` | Registers several package-shape constructors. |
+| `SetClass(type, Class)` | Registers or removes one constructor. |
+| `GetClass(type)` | Returns one registered constructor. |
+| `HasClass(type)` | Reports whether a constructor is registered. |
+| `Read(bytes, options?)` | Reads Carbon-record Carbon WebGPU bytes. |
+| `Inspect(bytes, options?)` | Returns a compact container summary. |
+| `AnalyzeEffect(bytes, options?)` | Analyzes compiled-effect bytes without packaging. |
+| `BuildEffect(bytes, options?)` | Translates a version-15 effect to Carbon WebGPU bytes. |
+| `BuildShaderIr(input, options?)` | Builds validated shader IR from DXBC or decoded input. |
+| `BuildWgsl(input, options?)` | Emits supported shader IR as WGSL. |
+| `BuildWgslBindingPlan(programs, options?)` | Allocates one binding layout across a pass. |
+| `BuildWgslSet(entries)` | Assembles emitted shaders and pass layouts. |
+| `ToJSON(value)` | Converts format output to JSON-compatible data. |
+
+There is no `Build(chunks)` method. The current wire is a Carbon record tree,
+not a generic chunk container.
+
+## Static helpers
+
+| Static helper | Purpose |
+| --- | --- |
+| `isCarbonWebgpu(bytes)` | Reports whether bytes have the Carbon-v15 shape. |
+| `read(bytes, options?)` | Reads one container. |
+| `inspect(bytes, options?)` | Inspects one container. |
+| `analyzeEffect(bytes, options?)` | Analyzes one compiled effect. |
+| `buildEffect(bytes, options?)` | Builds Carbon WebGPU bytes from a version-15 effect. |
+| `buildShaderIr(input, options?)` | Builds shader IR. |
+| `buildWgsl(input, options?)` | Emits WGSL. |
+| `buildWgslBindingPlan(programs, options?)` | Allocates a pass binding plan. |
+| `buildWgslSet(entries)` | Builds a portable WGSL set. |
+| `toJSON(value)` | Converts output to JSON-compatible data. |
+
+`isCarbonWebgpu` checks the first dword for Carbon version 15. Carbon WebGPU has no private
+magic or payload tag, so this is a shape check rather than backend identity.
+Callers establish identity through the resource path that supplied the bytes.
+
+## Profile options
+
+| Option | Meaning |
+| --- | --- |
+| `emit` | `"json"` by default or `"raw"` for the internal container reader. |
+| `source` | Caller-owned diagnostic label; it is never opened. |
+| `decodeInstructions` | Includes decoded instruction and IR detail during analysis. |
+| `permutation` | Exact `NAME=VALUE` assertions for `AnalyzeEffect` and `BuildEffect`; ignored by current `Read` and `Inspect`. |
+| `schema` | Optional caller schema record retained by the profile. |
+| `classes` | Optional constructor registrations keyed by `CLASS_KEYS`. |
+
+Class registrations are validated and stored for forward compatibility.
+Current JSON reads return plain data rather than hydrated package classes.
+
+Raw output is an internal reader over the same bytes. It is not a second wire
+format and should not be persisted.
+
+## Read result
+
+JSON `Read` returns:
+
+- `format`, Carbon `version`, and `sourcePath`;
+- derived `info` and `metadata`;
+- the complete derived `permutationGraph`;
+- derived `analysis`, `wgsl`, and `backendBodySet`;
+- convenience `stages`, `shaders`, and `layouts` arrays.
+
+These records are computed from the Carbon header, descriptions, WGSL program
+slots, and backend blocks. They are not stored chunks. The old `chunks` field
+is intentionally absent.
+
+`Inspect` reports the source label, Carbon version, compiler-version bytes,
+permutation count, distinct-body count, and resolved stage/shader/layout
+counts.
+
+## Effect analysis
+
+`AnalyzeEffect` accepts supported compiled-effect versions for diagnostic
+analysis. It resolves exact permutation assertions and may include decoded
+DXBC instructions and compiler IR.
+
+`BuildEffect` is narrower: current packaging requires the version-15 record
+layout. The wire retains every permutation row and non-program description
+field that the mapping can represent, including non-dynamic sampler names and
+the file's authored pass-stage order. Source-stage DXBC and the caller's source
+hash are not retained in the wire. Compiler IR is transient and is neither
+stored in the wire nor returned by `BuildEffect`.
+
+Unknown, duplicate, or unresolved permutation assertions fail closed.
+
+## Effect-package options
+
+`mode: "selected"` is the default. It translates the resolved body's
+requested complete passes while keeping every permutation row and
+representable non-program description fields in the container.
+
+`mode: "all"` first lowers the resolved selection, so an unsupported resolved
+body aborts the build. After that gate succeeds, unsupported later bodies
+remain in the container with empty program slots and appear as unsupported in
+the in-memory body-set view. `allPermutations: true` is a compatibility
+spelling for all mode.
+
+`selection` can name a technique, pass index, and complete stage list.
+`bindingPolicy.sharedIdentities` may name compatible cross-stage resources
+that are allowed to share one physical binding.
+
+`source` remains a diagnostic label. `sourceIdentity` and `outputPath` are
+returned build provenance; the wire's backend identity still comes from the
+consumer's resource path.
+
+## Build result and qualification
+
+`BuildEffect` returns:
+
+- `bytes`;
+- build-time `info` and `metadata`;
+- `permutationGraph`;
+- selected `analysis` and `wgsl`;
+- `backendBodySet` for all mode;
+- an `inspection` obtained by rereading the emitted bytes; and
+- `qualification`.
+
+The richer fields are caller evidence and are not separately stored in the
+container.
+
+`qualification.packageValid` reports structural construction. It does not
+claim that every body translated, that a pipeline was prepared, or that a
+draw succeeded. `backendComplete` and `runtimeComplete` retain those broader
+boundaries.
+
+## Binding-plan and WGSL-set helpers
+
+`BuildWgslBindingPlan` takes the complete program set for one pass.
+Unshared D3D tuples receive stage-qualified `scopeIdentity` values. A tuple is
+shared only when its base identity appears in `sharedIdentities` and the
+declarations are compatible.
+
+`BuildWgslSet` validates shader keys, layouts, numeric slots, and resource
+transforms. Ordinary sets use version 2. A proven physical-resource
+coalescing uses version 3 and carries an explicit transform recipe.
+
+## Static metadata
+
+The class exposes `OUTPUT_JSON`, `OUTPUT_RAW`, `CLASS_KEYS`, `type`,
+`mediaTypes`, `inputTypes`, `outputTypes`, `debugOutputTypes`,
+`implementationStatus`, `format`, `analysisFormat`, and `packageVersion`.
+
+## Errors
+
+Reads fail closed on malformed Carbon records, sparse or misordered
+permutation tables, out-of-range arena references, trailing record bytes, or a
+program-bearing stage WebGPU cannot express.
+
+Builds additionally fail on unsupported source versions, invalid selection,
+unsupported compiler semantics, ambiguous binding plans, non-`main` entry
+points, and malformed backend blocks.
+
+## Related documentation
+
+- [Effect packaging guide](../guides/effect-packaging.md)
+- [Carbon WebGPU effect container](../formats/carbon-webgpu.md)
+- [WGSL compatibility](wgsl-compatibility.md)
+- [Class-purpose catalog](classes/README.md)

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

@@ -1,9 +1,9 @@
-# WebGPU class catalog
-
-Status: Deprecated
-Scope: `@carbonenginejs/runtime-resource/formats/webgpu` maintained classes
-Audience: Users, maintainers, and automated readers
-Summary: Points to the canonical package-wide class catalog after format-package consolidation.
-
-The maintained WebGPU entries now live in the
-[package-wide formats class catalog](../../../../reference/classes/formats.md#webgpu).
+# WebGPU class catalog
+
+Status: Deprecated
+Scope: `@carbonenginejs/runtime-resource/formats/webgpu` maintained classes
+Audience: Users, maintainers, and automated readers
+Summary: Points to the canonical package-wide class catalog after format-package consolidation.
+
+The maintained WebGPU entries now live in the
+[package-wide formats class catalog](../../../../reference/classes/formats.md#webgpu).