@carbonenginejs/runtime-resource 0.12.1 → 0.13.0

package/docs/formats/hlsl/README.md

@@ -1,54 +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 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` reads the compiled container directly and
+  owns canonical `Tr2EffectRes`/`Tr2Shader` construction, 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)
+- [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

@@ -1,67 +1,65 @@
-# 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.
+# 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/formats/hlsl/CjsHlslFormat.js` is the supported reader boundary. Binary
+utilities and format-shaped compatibility models live below
+`src/formats/hlsl/core` and `src/formats/hlsl/core/tr2`.
+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.
+
+`runtime-resource` owns canonical `Tr2EffectRes`/`Tr2Shader` construction,
+permutation selection, and caching, reading the compiled container directly. `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

@@ -1,62 +1,60 @@
-# 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`.
+# 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 construct
+canonical runtime `Tr2EffectRes` or `Tr2Shader` instances. Those are built
+from the compiled container bytes by `@carbonenginejs/runtime-resource`.

package/docs/formats/hlsl/guides/reading-effects.md

@@ -1,64 +1,64 @@
-# Reading effects
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-resource/formats/hlsl` read workflows
-Audience: Users and integrators
-Summary: Shows browser-neutral byte reads, permutation selection, inspection, and Node file workflows.
-
-## Read caller-provided bytes
-
-```js
-import CjsHlslFormat from "@carbonenginejs/runtime-resource/formats/hlsl";
-
-const response = await fetch("/shaders/effect.sm_hi");
-const bytes = new Uint8Array(await response.arrayBuffer());
-const effect = CjsHlslFormat.read(bytes);
-```
-
-Use `inspect` when only header and technique summary information is needed:
-
-```js
-const summary = CjsHlslFormat.inspect(bytes, {
-    source: "effect.sm_hi"
-});
-```
-
-## Select a permutation
-
-Without a `permutation` option, the reader applies the container's default
-selection rules. Override individual axes by name and value:
-
-```js
-const effect = CjsHlslFormat.read(bytes, {
-    permutation: [
-        { name: "BLEND_MODE", value: "TRANSPARENT" }
-    ]
-});
-```
-
-A `Map` of names to values is also accepted. Unknown axes or invalid values
-are rejected rather than silently ignored.
-
-## Read compact metadata
-
-```js
-const metadata = CjsHlslFormat.read(bytes, {
-    emit: CjsHlslFormat.OUTPUT_METADATA
-});
-```
-
-Metadata output omits embedded bytecode and constant-value bytes. It retains
-the selected options, techniques, passes, stage resources, signatures, and
-render-state records needed for inspection and pipeline planning.
-
-## Read a file in Node
-
-```js
-const effect = await CjsHlslFormat.readFile("effect.sm_hi");
-```
-
-The CLI provides the same metadata workflow:
-
-```sh
-format-hlsl metadata effect.sm_hi effect.json
-```
+# Reading effects
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl` read workflows
+Audience: Users and integrators
+Summary: Shows browser-neutral byte reads, permutation selection, inspection, and Node file workflows.
+
+## Read caller-provided bytes
+
+```js
+import CjsHlslFormat from "@carbonenginejs/runtime-resource/formats/hlsl";
+
+const response = await fetch("/shaders/effect.sm_hi");
+const bytes = new Uint8Array(await response.arrayBuffer());
+const effect = CjsHlslFormat.read(bytes);
+```
+
+Use `inspect` when only header and technique summary information is needed:
+
+```js
+const summary = CjsHlslFormat.inspect(bytes, {
+    source: "effect.sm_hi"
+});
+```
+
+## Select a permutation
+
+Without a `permutation` option, the reader applies the container's default
+selection rules. Override individual axes by name and value:
+
+```js
+const effect = CjsHlslFormat.read(bytes, {
+    permutation: [
+        { name: "BLEND_MODE", value: "TRANSPARENT" }
+    ]
+});
+```
+
+A `Map` of names to values is also accepted. Unknown axes or invalid values
+are rejected rather than silently ignored.
+
+## Read compact metadata
+
+```js
+const metadata = CjsHlslFormat.read(bytes, {
+    emit: CjsHlslFormat.OUTPUT_METADATA
+});
+```
+
+Metadata output omits embedded bytecode and constant-value bytes. It retains
+the selected options, techniques, passes, stage resources, signatures, and
+render-state records needed for inspection and pipeline planning.
+
+## Read a file in Node
+
+```js
+const effect = await CjsHlslFormat.readFile("effect.sm_hi");
+```
+
+The CLI provides the same metadata workflow:
+
+```sh
+format-hlsl metadata effect.sm_hi effect.json
+```

package/docs/formats/hlsl/reference/advanced-analysis.md

@@ -1,66 +1,61 @@
-# Advanced analysis exports
-
-Status: Experimental
-Scope: `@carbonenginejs/runtime-resource/formats/hlsl` advanced named exports
-Audience: Translation-tool authors and maintainers
-Summary: Documents unstable helpers for raw graph analysis and binding-manifest construction.
-
-## Stability
-
-These exports support translation and inspection tooling that needs internal
-effect-model objects. Their shapes may change without a major version bump.
-Use `CjsHlslFormat.read(..., { emit: "json" })` or `"metadata"` for the
-supported data contracts.
-
-## `readEffectAnalysis`
-
-```js
-import { readEffectAnalysis } from "@carbonenginejs/runtime-resource/formats/hlsl";
-
-const analysis = readEffectAnalysis(bytes, {
-    source: "effect.sm_hi",
-    permutation: [
-        { name: "BLEND_MODE", value: "TRANSPARENT" }
-    ]
-});
-```
-
-The result contains the loaded effect resource, resolved shader, selected
-option and body-index data, effect description, and a binding manifest when
-an effect description is available.
-
-The returned internal parser-DTO effect resource also has
-`GetShaderByIndex(index)`. It decodes one exact permutation-table slot without
-applying global or local option overrides; it is distinct from the canonical
-runtime-resource method that hydrates and caches `Tr2Shader`. Use the versioned
-portable subpath when the result must cross a package or serialization
-boundary. Its `enumerateUniqueEffectBodies(effectRes)` helper inventories
-first-seen raw body identities without populating the parser's mutable shader
-cache.
-
-## `Tr2EffectBindingManifest`
-
-`Tr2EffectBindingManifest` is an exported advanced class that derives
-register-named constant, resource, sampler, and UAV bindings from an internal
-effect description.
-
-```js
-import {
-    readEffectAnalysis,
-    Tr2EffectBindingManifest
-} from "@carbonenginejs/runtime-resource/formats/hlsl";
-
-const analysis = readEffectAnalysis(bytes);
-analysis.bindingManifest instanceof Tr2EffectBindingManifest;
-```
-
-## Render-context helpers
-
-`Tr2RenderContextEnum` contains the format's stage and render-context numeric
-constants. `tr2ShaderStageName(value)` maps a known stage value to its
-readable name. Both are advanced compatibility helpers rather than a stable
-cross-package enumeration contract.
-
-## Related documentation
-
-- [Portable body reflection](portable-reflection.md)
+# Advanced analysis exports
+
+Status: Experimental
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl` advanced named exports
+Audience: Translation-tool authors and maintainers
+Summary: Documents unstable helpers for raw graph analysis and binding-manifest construction.
+
+## Stability
+
+These exports support translation and inspection tooling that needs internal
+effect-model objects. Their shapes may change without a major version bump.
+Use `CjsHlslFormat.read(..., { emit: "json" })` or `"metadata"` for the
+supported data contracts.
+
+## `readEffectAnalysis`
+
+```js
+import { readEffectAnalysis } from "@carbonenginejs/runtime-resource/formats/hlsl";
+
+const analysis = readEffectAnalysis(bytes, {
+    source: "effect.sm_hi",
+    permutation: [
+        { name: "BLEND_MODE", value: "TRANSPARENT" }
+    ]
+});
+```
+
+The result contains the loaded effect resource, resolved shader, selected
+option and body-index data, effect description, and a binding manifest when
+an effect description is available.
+
+The returned internal parser-DTO effect resource also has
+`GetShaderByIndex(index)`. It decodes one exact permutation-table slot without
+applying global or local option overrides, so a body-table index stays stable
+even when an application has set global effect options. It is distinct from the
+canonical `Tr2EffectRes.GetShaderByIndex`, which resolves options, hydrates a
+`Tr2Shader`, and caches it per index.
+
+## Binding manifest
+
+`analysis.bindingManifest` derives register-named constant, resource, sampler,
+and UAV bindings from an internal effect description. Its class is internal to
+the format and is not a published export; treat the manifest as data.
+
+## Source truth and realization
+
+Nothing this subpath returns carries a renderer handle: no shader, program,
+render-state, sampler, or library handles, and no resource sets, heap-view
+arrays, backend layouts, masks, sort values, or caches. Engines own all of
+that. Two consequences are easy to trip over:
+
+- Register dynamic classification is not persisted. It follows per-frame
+  reader and engine policy, and is not an authored binary field.
+- Authored constant defaults are separate from the raw model's mutable
+  `constantValues`. Carbon-compatible sampler-heap realization may zero-extend
+  the latter; it cannot change the authored source prefix.
+
+## Related documentation
+
+- [JSON and metadata graphs](json-graph.md)
+- [Carbon compiled-effect container](../../carbon-effect-container.md)