@carbonenginejs/runtime-resource 0.11.0 → 0.12.0

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

@@ -2,9 +2,9 @@
  * Error raised when a CEWG package or a DXBC-to-GLSL emission cannot be
  * completed safely.
  *
- * This package has no dependency on `@carbonenginejs/format-dxbc`'s internal
- * `DxbcReadError` class (that package only exports its public `CjsDxbcFormat`
- * boundary). Emitter/package failures raised from this package's own code
+ * This format has no dependency on the sibling `formats/dxbc` internal
+ * `DxbcReadError` class (that format only exports its public `CjsDxbcFormat`
+ * boundary). Emitter/package failures raised from this format's own code
  * use this class instead, while thrown messages that document a specific
  * failure mode (see README/tests) are kept identical to their origin in
  * `hlslreader`.

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

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sources":["../../../../../src/formats/webgl/core/errors.js"],"sourcesContent":["/**\n * Error raised when a CEWG package or a DXBC-to-GLSL emission cannot be\n * completed safely.\n *\n * This package has no dependency on `@carbonenginejs/format-dxbc`'s internal\n * `DxbcReadError` class (that package only exports its public `CjsDxbcFormat`\n * boundary). Emitter/package failures raised from this package's own code\n * use this class instead, while thrown messages that document a specific\n * failure mode (see README/tests) are kept identical to their origin in\n * `hlslreader`.\n */\nexport class WebglReadError extends Error\n{\n    /**\n   * Creates a read/emit error with structured location details.\n   *\n   * @param {string} message Human-readable failure reason.\n   * @param {object} [details] Extra reader state such as source, offset, or opcode.\n   */\n    constructor(message, details = {})\n    {\n        super(message);\n        this.name = \"WebglReadError\";\n        this.details = details;\n    }\n}\n"],"names":["WebglReadError","Error","constructor","message","details","name"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMA,cAAc,SAASC,KAAK,CACzC;AACI;AACJ;AACA;AACA;AACA;AACA;AACIC,EAAAA,WAAWA,CAACC,OAAO,EAAEC,OAAO,GAAG,EAAE,EACjC;IACI,KAAK,CAACD,OAAO,CAAC;IACd,IAAI,CAACE,IAAI,GAAG,gBAAgB;IAC5B,IAAI,CAACD,OAAO,GAAGA,OAAO;AAC1B,EAAA;AACJ;;;;"}
+{"version":3,"file":"errors.js","sources":["../../../../../src/formats/webgl/core/errors.js"],"sourcesContent":["/**\n * Error raised when a CEWG package or a DXBC-to-GLSL emission cannot be\n * completed safely.\n *\n * This format has no dependency on the sibling `formats/dxbc` internal\n * `DxbcReadError` class (that format only exports its public `CjsDxbcFormat`\n * boundary). Emitter/package failures raised from this format's own code\n * use this class instead, while thrown messages that document a specific\n * failure mode (see README/tests) are kept identical to their origin in\n * `hlslreader`.\n */\nexport class WebglReadError extends Error\n{\n    /**\n   * Creates a read/emit error with structured location details.\n   *\n   * @param {string} message Human-readable failure reason.\n   * @param {object} [details] Extra reader state such as source, offset, or opcode.\n   */\n    constructor(message, details = {})\n    {\n        super(message);\n        this.name = \"WebglReadError\";\n        this.details = details;\n    }\n}\n"],"names":["WebglReadError","Error","constructor","message","details","name"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMA,cAAc,SAASC,KAAK,CACzC;AACI;AACJ;AACA;AACA;AACA;AACA;AACIC,EAAAA,WAAWA,CAACC,OAAO,EAAEC,OAAO,GAAG,EAAE,EACjC;IACI,KAAK,CAACD,OAAO,CAAC;IACd,IAAI,CAACE,IAAI,GAAG,gBAAgB;IAC5B,IAAI,CAACD,OAAO,GAAGA,OAAO;AAC1B,EAAA;AACJ;;;;"}

package/dist/formats/webgpu/core/packageMetadata.js

@@ -1,5 +1,5 @@
-const FORMAT_WEBGPU_PACKAGE_NAME = "@carbonenginejs/format-webgpu";
-const FORMAT_WEBGPU_PACKAGE_VERSION = "0.6.0";
+const FORMAT_WEBGPU_PACKAGE_NAME = "@carbonenginejs/runtime-resource/formats/webgpu";
+const FORMAT_WEBGPU_PACKAGE_VERSION = "0.11.1";
 const WEBGPU_BACKEND_NAME = "webgpu";
 const DXBC_WGSL_TRANSLATOR_NAME = "dxbc-js-wgsl";
 const DXBC_WGSL_TRANSLATOR_VERSION = FORMAT_WEBGPU_PACKAGE_VERSION;

package/dist/formats/webgpu/core/packageMetadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"packageMetadata.js","sources":["../../../../../src/formats/webgpu/core/packageMetadata.js"],"sourcesContent":["export const FORMAT_WEBGPU_PACKAGE_NAME = \"@carbonenginejs/format-webgpu\";\nexport const FORMAT_WEBGPU_PACKAGE_VERSION = \"0.6.0\";\nexport const WEBGPU_BACKEND_NAME = \"webgpu\";\nexport const DXBC_WGSL_TRANSLATOR_NAME = \"dxbc-js-wgsl\";\nexport const DXBC_WGSL_TRANSLATOR_VERSION = FORMAT_WEBGPU_PACKAGE_VERSION;\n"],"names":["FORMAT_WEBGPU_PACKAGE_NAME","FORMAT_WEBGPU_PACKAGE_VERSION","WEBGPU_BACKEND_NAME","DXBC_WGSL_TRANSLATOR_NAME","DXBC_WGSL_TRANSLATOR_VERSION"],"mappings":"AAAO,MAAMA,0BAA0B,GAAG;AACnC,MAAMC,6BAA6B,GAAG;AACtC,MAAMC,mBAAmB,GAAG;AAC5B,MAAMC,yBAAyB,GAAG;AAClC,MAAMC,4BAA4B,GAAGH;;;;"}
+{"version":3,"file":"packageMetadata.js","sources":["../../../../../src/formats/webgpu/core/packageMetadata.js"],"sourcesContent":["export const FORMAT_WEBGPU_PACKAGE_NAME = \"@carbonenginejs/runtime-resource/formats/webgpu\";\nexport const FORMAT_WEBGPU_PACKAGE_VERSION = \"0.11.1\";\nexport const WEBGPU_BACKEND_NAME = \"webgpu\";\nexport const DXBC_WGSL_TRANSLATOR_NAME = \"dxbc-js-wgsl\";\nexport const DXBC_WGSL_TRANSLATOR_VERSION = FORMAT_WEBGPU_PACKAGE_VERSION;\n"],"names":["FORMAT_WEBGPU_PACKAGE_NAME","FORMAT_WEBGPU_PACKAGE_VERSION","WEBGPU_BACKEND_NAME","DXBC_WGSL_TRANSLATOR_NAME","DXBC_WGSL_TRANSLATOR_VERSION"],"mappings":"AAAO,MAAMA,0BAA0B,GAAG;AACnC,MAAMC,6BAA6B,GAAG;AACtC,MAAMC,mBAAmB,GAAG;AAC5B,MAAMC,yBAAyB,GAAG;AAClC,MAAMC,4BAA4B,GAAGH;;;;"}

package/docs/formats/dxbc/README.md

@@ -0,0 +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)

package/docs/formats/dxbc/architecture.md

@@ -0,0 +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 CEWGPU 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

@@ -0,0 +1,77 @@
+# 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)

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

@@ -0,0 +1,76 @@
+# Class catalog
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/dxbc` maintained classes
+Audience: Users, maintainers, and automated readers
+Summary: Provides one-sentence purpose descriptors for every maintained class in the DXBC format package.
+
+<!-- class:CjsDxbcFormat -->
+## `CjsDxbcFormat`
+
+CarbonEngineJS-facing DXBC (Direct3D shader bytecode) reader.
+
+- Export: `@carbonenginejs/runtime-resource/formats/dxbc`
+- Source: `src/CjsDxbcFormat.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:CjsBinaryReader -->
+## `CjsBinaryReader`
+
+Little-endian binary reader with optional shared string-table references.
+
+- Export: None
+- Source: `src/carbon/CjsBinaryReader.js`
+- Visibility: Internal
+- Kind: Internal implementation
+
+<!-- class:DxbcContainer -->
+## `DxbcContainer`
+
+DirectX shader bytecode container reader.
+
+- Export: None
+- Source: `src/core/container.js`
+- Visibility: Internal
+- Kind: Internal implementation
+
+<!-- class:DxbcInstructionDecoder -->
+## `DxbcInstructionDecoder`
+
+SM4/SM5 instruction-stream decoder over a `DxbcShaderProgram` token array.
+
+- Export: None
+- Source: `src/core/decoder.js`
+- Visibility: Internal
+- Kind: Internal implementation
+
+<!-- class:DxbcReadError -->
+## `DxbcReadError`
+
+Error raised when DirectX shader bytecode cannot be decoded safely.
+
+- Export: None
+- Source: `src/core/errors.js`
+- Visibility: Internal
+- Kind: Internal implementation
+
+<!-- class:DxbcShaderProgram -->
+## `DxbcShaderProgram`
+
+DXBC shader program chunk reader for `SHEX`/`SHDR` token streams.
+
+- Export: None
+- Source: `src/core/program.js`
+- Visibility: Internal
+- Kind: Internal implementation
+
+<!-- class:DxbcSignatureChunk -->
+## `DxbcSignatureChunk`
+
+DXBC input/output signature chunk reader for `ISGN`-family chunks.
+
+- Export: None
+- Source: `src/core/signature.js`
+- Visibility: Internal
+- Kind: Internal implementation

package/docs/formats/dxbc/reference/decoded-output.md

@@ -0,0 +1,122 @@
+# Decoded output contract
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/dxbc` JSON output
+Audience: Shader-tool authors and lowering-backend authors
+Summary: Defines the stable top-level JSON fields and the decoder records consumed by shader-lowering packages.
+
+## Top-level result
+
+`CjsDxbcFormat.read(bytes)` returns:
+
+| Field | Meaning |
+| --- | --- |
+| `source` | Caller-provided diagnostic label. |
+| `container` | Container version, declared size, and chunk summaries. |
+| `program` | Shader stage, shader model, chunk tag, and token count, or `null`. |
+| `inputSignature` | Input signature elements, or `null`. |
+| `outputSignature` | Output signature elements, or `null`. |
+| `patchSignature` | Patch-constant signature elements, or `null`. |
+| `instructions` | Decoded instruction records, or `null` when disabled or absent. |
+
+`Inspect` returns a smaller record containing the container/chunk summary,
+stage name, shader model, and input/output element counts.
+
+## Container records
+
+The container summary includes `version`, `totalSize`, and ordered `chunks`.
+Each chunk record includes its four-character code, byte offset, and payload
+size. JSON output omits raw chunk bytes.
+
+## Program records
+
+Program metadata includes:
+
+- `fourCC`: `SHEX` or `SHDR`;
+- numeric and named program type;
+- major and minor shader-model version; and
+- declared program length in 32-bit words.
+
+Recognized program names are pixel, vertex, geometry, hull, domain, and
+compute. An unknown numeric type remains observable as `"unknown"`.
+
+## Signature elements
+
+Each signature element records its semantic name/index, system-value and
+component types, register index, masks, stream, and minimum-precision value
+when that signature layout provides one.
+
+The reader supports the SM4 and SM5 signature chunk layouts used by `ISGN`,
+`ISG1`, `OSGN`, `OSG1`, `OSG5`, `PCSG`, and `PSG1`.
+
+## Instruction records
+
+Each instruction begins with its source token offset, opcode number/name,
+declared length, and decoded control bits. Depending on the opcode, the record
+may also include:
+
+- destination and source operands with component selection and index records;
+- opcode and operand extensions;
+- declaration-specific fields;
+- resource dimensions and return types;
+- sampler, interpolation, precision, topology, or system-value metadata;
+- custom-data payloads; and
+- unprojected declaration words in `tailTokens`.
+
+Executable instructions reject leftover or missing operand words. Declaration
+records may preserve unfamiliar trailing payload words when their instruction
+framing is valid.
+
+### Compute shared memory and synchronization
+
+Compute thread-group shared-memory declarations expose their register and
+complete allocation shape:
+
+| Declaration | Fields |
+| --- | --- |
+| `dcl_thread_group_shared_memory_raw` | `registerIndex`, `byteCount` |
+| `dcl_thread_group_shared_memory_structured` | `registerIndex`, `structureStride`, `structureCount` |
+
+The declaration operand must identify one immediate thread-group shared-memory
+register. Byte counts and structure strides are positive and DWORD-aligned;
+structured element counts are positive. Any additional well-framed declaration
+words remain observable through `tailTokens`.
+
+The `sync` instruction exposes its numeric `syncFlags` mask and a canonical
+bit-order `syncFlagNames` array. The recognized names are
+`threads_in_group`, `thread_group_shared_memory`,
+`thread_group_uav_memory`, and `global_uav_memory`. These control bits are
+separate from arithmetic result controls, so `sync` never reports saturation.
+Unknown bits remain set in the numeric eight-bit mask even though they have no
+entry in the recognized-name array. Reserved operand and opcode-control bits
+are rejected rather than projected onto the canonical records.
+
+## Shader Model 5.1 bindings
+
+SM5.1 resource declarations may include `bindingRange`:
+
+| Field | Meaning |
+| --- | --- |
+| `rangeId` | Class-local binding-range identity. |
+| `lowerBound` / `upperBound` | Declared register bounds. |
+| `unbounded` | Whether the upper bound represents an unbounded range. |
+| `registerCount` | Finite range size, otherwise `null`. |
+| `registerSpace` | D3D register space. |
+
+Executable resource, sampler, UAV, and constant-buffer operands may include a
+`resourceReference` retaining the range identity, index records, and
+non-uniform flag. Range identity remains separate from the actual register
+index needed by an explicit-binding backend.
+
+SM5.0 declarations keep their direct-register shape.
+
+## JSON conversion
+
+Typed arrays become number arrays, arrays are converted recursively, maps
+become plain objects, sets become arrays, and objects with `toJSON` use that
+projection.
+
+## Related documentation
+
+- [Public API reference](api.md)
+- [Architecture and boundaries](../architecture.md)

package/docs/formats/gr2.md

@@ -32,10 +32,9 @@ const summary = CjsGr2Format.inspect(bytes);
 const asynchronousGraph = await CjsGr2Format.readAsync(bytes);
 ```
 
-The wrapper exposes the normal runtime-resource format metadata and
-`isSupported(bytes)` magic probe. It also exports the migrated
-`CjsFormatGr2` reader engine for compatibility, but new consumers should use
-`CjsGr2Format`.
+`CjsGr2Format` is the one public class: the reader engine plus the normal
+runtime-resource format metadata and the `isSupported(bytes)` magic probe.
+The barrel exports nothing else.
 
 Register it with `CjsResMan` when GR2/GSF should participate in ordinary
 resource loading:

package/docs/formats/hlsl/README.md

@@ -0,0 +1,54 @@
+# Package documentation
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl`
+Audience: Users and integrators
+Summary: Documentation home for the compiled Carbon/Trinity effect-container reader.
+
+## Purpose
+
+`@carbonenginejs/runtime-resource/formats/hlsl` reads versions 8 through 15 of the compiled
+effect container used by Carbon/Trinity. It resolves a permutation and exposes
+techniques, passes, stage metadata, render states, signatures, and opaque
+shader bytecode as JavaScript data.
+
+```js
+import CjsHlslFormat from "@carbonenginejs/runtime-resource/formats/hlsl";
+
+const metadata = CjsHlslFormat.read(bytes, {
+    emit: "metadata"
+});
+```
+
+## Where it fits
+
+- Use this package for the effect container and its metadata.
+- Use `@carbonenginejs/runtime-resource/formats/dxbc` to decode supported embedded Direct3D
+  shader bytecode.
+- Translation backends such as `@carbonenginejs/runtime-resource/formats/webgpu` can consume
+  the metadata and bytecode through their own integration layers.
+- `@carbonenginejs/runtime-resource` consumes packaged portable reflection and
+  owns canonical `Tr2EffectRes`/`Tr2Shader` hydration, selection, and caching.
+- `@carbonenginejs/runtime-trinity` consumes that shader graph through its
+  mutable effect/material facade, parameters, options, and sampler overrides.
+
+The package does not compile HLSL source, translate shader instructions,
+construct canonical runtime model instances, or provide a rendering runtime.
+
+## Start here
+
+- [Architecture](architecture.md)
+- [Reading effects](guides/reading-effects.md)
+- [Hydrating JSON output](guides/hydrating-json-output.md)
+- [API reference](reference/api.md)
+- [Advanced analysis exports](reference/advanced-analysis.md)
+- [JSON graph reference](reference/json-graph.md)
+- [Portable body reflection](reference/portable-reflection.md)
+- [Class catalog](reference/classes/README.md)
+
+## Compatibility
+
+Supported input types are `.sm_hi`, `.sm_lo`, and `.sm_depth` compiled effect
+bodies. Unsupported headers, invalid offsets, truncated data, and invalid
+permutation selections fail with an error rather than returning a partial
+success value.

package/docs/formats/hlsl/architecture.md

@@ -0,0 +1,67 @@
+# Architecture
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl` implementation boundaries
+Audience: Integrators and maintainers
+Summary: Explains the package boundary, parsing flow, output modes, and platform adapters.
+
+## Ownership boundary
+
+The package owns the compiled Carbon/Trinity effect-container boundary:
+headers, string tables, permutation selection, effect descriptions,
+techniques, passes, render states, stage metadata, signatures, and the
+packaging of opaque shader bytecode.
+
+It does not decode shader instructions, compile source code, or own runtime
+resource binding. Those responsibilities remain with bytecode-format,
+translation, and runtime packages.
+
+## Read flow
+
+```text
+caller bytes
+    -> input and option normalization
+    -> effect header, strings, and permutation axes
+    -> selected compiled body
+    -> techniques, passes, and stage metadata
+    -> json | metadata | raw output
+```
+
+`src/CjsHlslFormat.js` is the supported reader boundary. Binary utilities and
+format-shaped compatibility models live below `src/core` and `src/carbon`.
+Their same-named `Tr2*` classes are internal parser DTOs, not canonical runtime
+model identity, and are not independent package entry points.
+
+## Output modes
+
+- `json` is the default interoperable data graph and may include opaque
+  bytecode and constant-value bytes.
+- `metadata` is a compact, bytecode-free graph for inspection and pipeline
+  planning.
+- `raw` exposes internal effect-model instances for advanced tooling and is
+  not a stable schema.
+- `@carbonenginejs/runtime-resource/formats/hlsl/portable` copies one exact body into a versioned,
+  runtime-neutral source-reflection contract. Authored defaults and programs stay
+  separate from mutable renderer realization.
+
+`runtime-resource` owns canonical `Tr2EffectRes`/`Tr2Shader` hydration,
+permutation selection, and caching. `runtime-trinity` owns the mutable
+effect/material facade, parameters, authored options, and sampler overrides.
+Engines own GPU realization.
+
+The graph shapes are documented in
+[reference/json-graph.md](reference/json-graph.md).
+
+## Platform boundary
+
+`read`, `inspect`, and `toJSON` operate on caller-provided bytes and work
+without filesystem access. `readFile` and the CLI are Node-specific adapters.
+The package has no runtime dependencies.
+
+## Error boundary
+
+Structural failures include the source label and read context where available.
+The reader rejects unsupported versions and unsafe reads instead of silently
+guessing a layout. A selected compiled body can record its own decode failure
+in raw or JSON-oriented inspection data where the format model supports that
+state.

package/docs/formats/hlsl/guides/hydrating-json-output.md

@@ -0,0 +1,62 @@
+# Hydrating JSON output
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl` JSON node hydration
+Audience: Advanced users and integrators
+Summary: Explains how callers can replace selected plain JSON nodes with their own constructors.
+
+## Register constructors
+
+The default `json` output uses plain objects. The `classes` option can
+instantiate selected node kinds with caller-provided constructors:
+
+```js
+import CjsHlslFormat from "@carbonenginejs/runtime-resource/formats/hlsl";
+
+const effect = CjsHlslFormat.read(bytes, {
+    classes: {
+        Technique: MyTechnique,
+        StageInput: MyStageInput
+    }
+});
+```
+
+Supported keys are exposed as `CjsHlslFormat.CLASS_KEYS`:
+
+```text
+Root
+Permutation
+EffectDescription
+Technique
+Pass
+StageInput
+Constant
+Resource
+Sampler
+ShaderBytecode
+```
+
+## Reuse a profile
+
+```js
+const reader = new CjsHlslFormat();
+
+reader.SetClass("Technique", MyTechnique);
+reader.SetClasses({ StageInput: MyStageInput });
+
+reader.HasClass("Technique");
+reader.GetClass("Technique");
+
+const effect = reader.Read(bytes);
+```
+
+Hydration changes object prototypes, not the documented field shape. Nested
+records without a class key remain plain JSON-compatible data. Depending on
+the caller's constructors as a serialization schema is discouraged; persist
+the documented graph fields instead.
+
+This feature is caller-selected JSON projection only. It does not consume the
+versioned portable-reflection contract and does not construct canonical
+runtime `Tr2EffectRes` or `Tr2Shader` instances. Canonical
+`CJS_EFFECT_BODY_REFLECTION` hydration belongs to
+`@carbonenginejs/runtime-resource`.