@carbonenginejs/runtime-resource 0.13.0 → 0.14.0

package/docs/formats/dxbc/README.md

@@ -1,68 +1,68 @@
-# DXBC format documentation
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-resource/formats/dxbc`
-Audience: Shader-tool authors, lowering-backend authors, and maintainers
-Summary: Explains the pure-JavaScript DXBC reader, its decoded output, and its boundary with effect and shader-lowering packages.
-
-## Purpose
-
-`@carbonenginejs/runtime-resource/formats/dxbc` owns pure-JavaScript reading of Microsoft DXBC
-containers. It validates the chunk directory, decodes input/output/patch
-signatures, reads SM4/SM5 program headers, and converts instruction tokens into
-structured records.
-
-The package preserves unfamiliar declaration payload words as `tailTokens`
-where the framing is valid. Executable instructions decode strictly and reject
-malformed operand lengths.
-
-## Use this package when
-
-Use `format-dxbc` when you need:
-
-- cheap DXBC identification and container inspection;
-- plain JSON-compatible signatures and instruction records;
-- internal decoder objects for an advanced shader backend; or
-- a browser-safe byte decoder with no native executable or filesystem
-  dependency.
-
-Do not place target-language lowering rules here. GLSL emission belongs to
-`@carbonenginejs/runtime-resource/formats/webgl`, and WGSL emission belongs to
-`@carbonenginejs/runtime-resource/formats/webgpu`.
-
-## Where it fits
-
-```text
-compiled effects
-      |
-      v
- format-hlsl
-      |
-      | opaque DXBC stage bytes
-      v
- format-dxbc
-      |
-      +---- decoded records ----> format-webgl
-      |
-      +---- decoded records ----> format-webgpu
-```
-
-The public decoder contract is Microsoft DXBC data. Package-local binary
-utilities are internal implementation details and are not public npm subpaths.
-
-## Start here
-
-```js
-import { CjsDxbcFormat } from "@carbonenginejs/runtime-resource/formats/dxbc";
-
-const decoded = CjsDxbcFormat.read(shaderBytes, {
-    source: "example.dxbc"
-});
-```
-
-## Documentation map
-
-- [Architecture and boundaries](architecture.md)
-- [Public API reference](reference/api.md)
-- [Decoded output contract](reference/decoded-output.md)
-- [Class-purpose catalog](reference/classes/README.md)
+# DXBC format documentation
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/dxbc`
+Audience: Shader-tool authors, lowering-backend authors, and maintainers
+Summary: Explains the pure-JavaScript DXBC reader, its decoded output, and its boundary with effect and shader-lowering packages.
+
+## Purpose
+
+`@carbonenginejs/runtime-resource/formats/dxbc` owns pure-JavaScript reading of Microsoft DXBC
+containers. It validates the chunk directory, decodes input/output/patch
+signatures, reads SM4/SM5 program headers, and converts instruction tokens into
+structured records.
+
+The package preserves unfamiliar declaration payload words as `tailTokens`
+where the framing is valid. Executable instructions decode strictly and reject
+malformed operand lengths.
+
+## Use this package when
+
+Use `format-dxbc` when you need:
+
+- cheap DXBC identification and container inspection;
+- plain JSON-compatible signatures and instruction records;
+- internal decoder objects for an advanced shader backend; or
+- a browser-safe byte decoder with no native executable or filesystem
+  dependency.
+
+Do not place target-language lowering rules here. GLSL emission belongs to
+`@carbonenginejs/runtime-resource/formats/webgl`, and WGSL emission belongs to
+`@carbonenginejs/runtime-resource/formats/webgpu`.
+
+## Where it fits
+
+```text
+compiled effects
+      |
+      v
+ format-hlsl
+      |
+      | opaque DXBC stage bytes
+      v
+ format-dxbc
+      |
+      +---- decoded records ----> format-webgl
+      |
+      +---- decoded records ----> format-webgpu
+```
+
+The public decoder contract is Microsoft DXBC data. Package-local binary
+utilities are internal implementation details and are not public npm subpaths.
+
+## Start here
+
+```js
+import { CjsDxbcFormat } from "@carbonenginejs/runtime-resource/formats/dxbc";
+
+const decoded = CjsDxbcFormat.read(shaderBytes, {
+    source: "example.dxbc"
+});
+```
+
+## Documentation map
+
+- [Architecture and boundaries](architecture.md)
+- [Public API reference](reference/api.md)
+- [Decoded output contract](reference/decoded-output.md)
+- [Class-purpose catalog](reference/classes/README.md)

package/docs/formats/dxbc/architecture.md

@@ -1,80 +1,80 @@
-# Architecture and boundaries
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-resource/formats/dxbc`
-Audience: Shader-tool authors, lowering-backend authors, and maintainers
-Summary: Defines DXBC decoding ownership, strictness, dependency direction, and target-language non-goals.
-
-## Purpose
-
-`format-dxbc` turns caller-supplied DXBC bytes into validated container,
-signature, program, operand, declaration, and instruction records. It stops
-before target-language code generation.
-
-## Dependency direction
-
-```text
-caller or format-hlsl
-          |
-          | DXBC bytes
-          v
-     format-dxbc
-       /      \
-      v        v
-format-webgl  format-webgpu
-```
-
-The package has no runtime dependency and its public source works in browsers
-and Node. Lowering packages depend on its decoded records; it does not import
-them.
-
-## Owned responsibilities
-
-- DXBC magic, header, checksum field, total-size, and chunk-directory parsing.
-- Bounds-checked access to chunk payloads.
-- `ISGN`, `ISG1`, `OSGN`, `OSG1`, `OSG5`, `PCSG`, and `PSG1` signature
-  records.
-- `SHEX` and `SHDR` program version and token-stream reading.
-- SM4/SM5 opcode, operand, declaration, control, and extension-token decoding.
-- SM5.1 binding-range and resource-reference records.
-- JSON-compatible output and an internal raw-object mode.
-- Structured decode errors with source and offset details.
-
-## Ownership elsewhere
-
-- Compiled effect containers, permutations, techniques, and binding manifests
-  belong to `format-hlsl`.
-- GLSL ES generation and WebGL-specific register/storage policy belong to
-  `format-webgl`.
-- WGSL generation, pass-global WebGPU binding allocation, and Carbon WebGPU assembly
-  belong to `format-webgpu`.
-- GPU shader-module and pipeline realization belongs to engine packages.
-
-## Strictness
-
-The reader validates container and chunk bounds before exposing data.
-Executable instructions must consume exactly their declared token length.
-Declarations decode the payload forms implemented by the package and retain
-remaining valid words in `tailTokens`, allowing unusual stages to remain
-inspectable without pretending every declaration payload has a specialized
-projection.
-
-The opcode-name table covers the SM4/SM5 vocabulary used for framing. That does
-not imply every opcode has a target-language implementation in every lowering
-package.
-
-## Output stability
-
-`emit: "json"` is the stable integration surface. It returns plain data and
-converts typed arrays into number arrays.
-
-`emit: "raw"` exposes package-internal class instances for advanced backends.
-Those classes are not public npm exports; consumers should treat their concrete
-constructors as internal and depend only on the fields used by the owning
-lowering package.
-
-## Related documentation
-
-- [Package documentation](README.md)
-- [Public API reference](reference/api.md)
-- [Decoded output contract](reference/decoded-output.md)
+# Architecture and boundaries
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/dxbc`
+Audience: Shader-tool authors, lowering-backend authors, and maintainers
+Summary: Defines DXBC decoding ownership, strictness, dependency direction, and target-language non-goals.
+
+## Purpose
+
+`format-dxbc` turns caller-supplied DXBC bytes into validated container,
+signature, program, operand, declaration, and instruction records. It stops
+before target-language code generation.
+
+## Dependency direction
+
+```text
+caller or format-hlsl
+          |
+          | DXBC bytes
+          v
+     format-dxbc
+       /      \
+      v        v
+format-webgl  format-webgpu
+```
+
+The package has no runtime dependency and its public source works in browsers
+and Node. Lowering packages depend on its decoded records; it does not import
+them.
+
+## Owned responsibilities
+
+- DXBC magic, header, checksum field, total-size, and chunk-directory parsing.
+- Bounds-checked access to chunk payloads.
+- `ISGN`, `ISG1`, `OSGN`, `OSG1`, `OSG5`, `PCSG`, and `PSG1` signature
+  records.
+- `SHEX` and `SHDR` program version and token-stream reading.
+- SM4/SM5 opcode, operand, declaration, control, and extension-token decoding.
+- SM5.1 binding-range and resource-reference records.
+- JSON-compatible output and an internal raw-object mode.
+- Structured decode errors with source and offset details.
+
+## Ownership elsewhere
+
+- Compiled effect containers, permutations, techniques, and binding manifests
+  belong to `format-hlsl`.
+- GLSL ES generation and WebGL-specific register/storage policy belong to
+  `format-webgl`.
+- WGSL generation, pass-global WebGPU binding allocation, and Carbon WebGPU assembly
+  belong to `format-webgpu`.
+- GPU shader-module and pipeline realization belongs to engine packages.
+
+## Strictness
+
+The reader validates container and chunk bounds before exposing data.
+Executable instructions must consume exactly their declared token length.
+Declarations decode the payload forms implemented by the package and retain
+remaining valid words in `tailTokens`, allowing unusual stages to remain
+inspectable without pretending every declaration payload has a specialized
+projection.
+
+The opcode-name table covers the SM4/SM5 vocabulary used for framing. That does
+not imply every opcode has a target-language implementation in every lowering
+package.
+
+## Output stability
+
+`emit: "json"` is the stable integration surface. It returns plain data and
+converts typed arrays into number arrays.
+
+`emit: "raw"` exposes package-internal class instances for advanced backends.
+Those classes are not public npm exports; consumers should treat their concrete
+constructors as internal and depend only on the fields used by the owning
+lowering package.
+
+## Related documentation
+
+- [Package documentation](README.md)
+- [Public API reference](reference/api.md)
+- [Decoded output contract](reference/decoded-output.md)

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

@@ -1,77 +1,105 @@
-# Public API reference
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-resource/formats/dxbc`
-Audience: Shader-tool authors and lowering-backend authors
-Summary: Defines the public `CjsDxbcFormat` profile, one-shot helpers, options, and failure behavior.
-
-## Export
-
-The package root exports `CjsDxbcFormat` as both a named and default export:
-
-```js
-import CjsDxbcFormat, {
-    CjsDxbcFormat as DxbcFormat
-} from "@carbonenginejs/runtime-resource/formats/dxbc";
-```
-
-No internal container, signature, program, decoder, or error class is exposed
-through the package export map.
-
-## Reusable profile
-
-```js
-const reader = new DxbcFormat({
-    emit: "json",
-    source: "example.dxbc",
-    decodeInstructions: true
-});
-
-const decoded = reader.Read(shaderBytes);
-const summary = reader.Inspect(shaderBytes);
-```
-
-| Instance method | Purpose |
-| --- | --- |
-| `SetValues(options)` | Merges reusable profile defaults and returns the profile. |
-| `GetValues(options?)` | Returns effective values with optional per-call overrides. |
-| `Read(bytes, options?)` | Reads one DXBC payload using the effective profile. |
-| `Inspect(bytes, options?)` | Returns container, stage, shader-model, and signature counts without instruction decoding. |
-
-## One-shot helpers
-
-| Static helper | Purpose |
-| --- | --- |
-| `isDxbc(bytes)` | Returns `true` when input starts with the DXBC magic; invalid input returns `false`. |
-| `read(bytes, options?)` | Reads one DXBC payload. |
-| `inspect(bytes, options?)` | Inspects one payload without instruction decoding. |
-| `toJSON(value)` | Deep-converts supported values to JSON-compatible data. |
-
-The class also exposes `OUTPUT_JSON`, `OUTPUT_RAW`, input/output media metadata,
-and the format's supported input type.
-
-## Options
-
-| Option | Default | Meaning |
-| --- | --- | --- |
-| `emit` | `"json"` | `"json"` returns plain data; `"raw"` returns internal decoder objects. |
-| `source` | `"memory"` | Caller-owned label included in error details; no path is opened. |
-| `decodeInstructions` | `true` | When false, reads the container, signatures, and program header without decoding instructions. |
-
-Inputs may be `Uint8Array`, `ArrayBuffer`, Node `Buffer`, `DataView`, or another
-array-buffer view.
-
-## Errors
-
-Invalid options and unsupported input types throw `TypeError`. Malformed DXBC
-throws an internal `DxbcReadError` carrying a stable human-readable message and
-a `details` record with relevant source, offset, size, chunk, or opcode
-information.
-
-`isDxbc` is the non-throwing sniff operation.
-
-## Related documentation
-
-- [Decoded output contract](decoded-output.md)
-- [Architecture and boundaries](../architecture.md)
-- [Class-purpose catalog](classes/README.md)
+# Public API reference
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/dxbc`
+Audience: Shader-tool authors and lowering-backend authors
+Summary: Defines the public `CjsDxbcFormat` profile, one-shot helpers, options, and failure behavior.
+
+## Export
+
+The package root exports `CjsDxbcFormat` as both a named and default export:
+
+```js
+import CjsDxbcFormat, {
+    CjsDxbcFormat as DxbcFormat
+} from "@carbonenginejs/runtime-resource/formats/dxbc";
+```
+
+No internal container, signature, program, decoder, or error class is exposed
+through the package export map.
+
+## Reusable profile
+
+```js
+const reader = new DxbcFormat({
+    emit: "json",
+    source: "example.dxbc",
+    decodeInstructions: true
+});
+
+const decoded = reader.Read(shaderBytes);
+const summary = reader.Inspect(shaderBytes);
+```
+
+| Instance method | Purpose |
+| --- | --- |
+| `SetValues(options)` | Merges reusable profile defaults and returns the profile. |
+| `GetValues(options?)` | Returns effective values with optional per-call overrides. |
+| `Read(bytes, options?)` | Reads one DXBC payload using the effective profile. |
+| `Inspect(bytes, options?)` | Returns container, stage, shader-model, and signature counts without instruction decoding. |
+
+## One-shot helpers
+
+| Static helper | Purpose |
+| --- | --- |
+| `isDxbc(bytes)` | Returns `true` when input starts with the DXBC magic; invalid input returns `false`. |
+| `read(bytes, options?)` | Reads one DXBC payload. |
+| `inspect(bytes, options?)` | Inspects one payload without instruction decoding. |
+| `disassemble(input, options?)` | Returns an assembly listing of the decoded instruction stream. |
+| `toJSON(value)` | Deep-converts supported values to JSON-compatible data. |
+
+The class also exposes `OUTPUT_JSON`, `OUTPUT_RAW`, input/output media metadata,
+and the format's supported input type.
+
+## Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `emit` | `"json"` | `"json"` returns plain data; `"raw"` returns internal decoder objects. |
+| `source` | `"memory"` | Caller-owned label included in error details; no path is opened. |
+| `decodeInstructions` | `true` | When false, reads the container, signatures, and program header without decoding instructions. |
+
+Inputs may be `Uint8Array`, `ArrayBuffer`, Node `Buffer`, `DataView`, or another
+array-buffer view.
+
+## Disassembly
+
+`disassemble` renders decoded instructions as assembly text. It exists so a
+translated shader can be checked against the bytecode it was translated from:
+comparing emitted GLSL or WGSL against the original HLSL proves nothing, because
+the compiler that produced the bytecode already rewrote the program, and an
+emitter cannot be its own oracle.
+
+```js
+const listing = CjsDxbcFormat.disassemble(stageBytes);
+```
+
+Bytes, a previous `read` result, and a decoder record are all accepted, so a
+caller that already decoded the payload does not decode it twice.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `declarations` | `true` | Include declaration instructions. |
+| `numbers` | `true` | Prefix executable instructions with their index. Declarations are not numbered, so the numbering matches the order a backend walks. |
+| `indent` | `true` | Indent control-flow bodies. |
+
+Component selection prints exactly as encoded rather than normalized. A
+destination mask selects source components by position, so `mad r[2].xyw,
+r[2].xxxx, v[3].xyxz, r[5].xyxz` writes `x`, `y`, and `w` from source components
+0, 1, and 3. Normalizing that away would hide the most common class of
+translation mistake.
+
+## Errors
+
+Invalid options and unsupported input types throw `TypeError`. Malformed DXBC
+throws an internal `DxbcReadError` carrying a stable human-readable message and
+a `details` record with relevant source, offset, size, chunk, or opcode
+information.
+
+`isDxbc` is the non-throwing sniff operation.
+
+## Related documentation
+
+- [Decoded output contract](decoded-output.md)
+- [Architecture and boundaries](../architecture.md)
+- [Class-purpose catalog](classes/README.md)

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

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