@carbonenginejs/runtime-resource 0.12.2 → 0.13.0

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

@@ -1,98 +1,92 @@
-# API reference
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-resource/formats/hlsl` supported reader API
-Audience: Users and integrators
-Summary: Documents the reader class, options, output modes, and Node adapters.
-
-## Imports
-
-The package root exports `CjsHlslFormat` as both the default and a named
-export:
-
-```js
-import CjsHlslFormat from "@carbonenginejs/runtime-resource/formats/hlsl";
-import { CjsHlslFormat as NamedReader } from "@carbonenginejs/runtime-resource/formats/hlsl";
-```
-
-Additional named exports intended for advanced tooling are documented
-separately in [advanced-analysis.md](advanced-analysis.md).
-
-The versioned `@carbonenginejs/runtime-resource/formats/hlsl/portable` subpath exposes exact
-version-15 body-index reflection plus first-seen exact-byte unique-body
-enumeration for backend packagers. See
-[portable-reflection.md](portable-reflection.md).
-
-## Constructor
-
-```js
-const reader = new CjsHlslFormat({
-    emit: "json",
-    source: "effect.sm_hi",
-    permutation: null,
-    classes: {}
-});
-```
-
-Options are reusable on an instance and can be overridden per call:
-
-- `emit`: `"json"` (default), `"metadata"`, or advanced `"raw"` output.
-- `source`: a caller-supplied label used in diagnostics and output.
-- `permutation`: a `Map` or an array of `{ name, value }` selections.
-- `classes`: constructors used for caller-selected JSON-node projection; this
-  is not canonical runtime shader hydration.
-
-## Instance methods
-
-- `SetValues(options)` updates the reusable profile and returns the reader.
-- `GetValues(options)` returns effective values with optional overrides.
-- `SetClasses(classes)` and `SetClass(type, Class)` configure hydration.
-- `GetClass(type)` and `HasClass(type)` inspect hydration registrations.
-- `Read(input, options)` parses input and emits the configured graph.
-- `Inspect(input, options)` returns header and technique summary data.
-- `ToJSON(value)` converts reader output to JSON-compatible data.
-
-## Static methods
-
-- `CjsHlslFormat.isSupported(input)` performs a header-level support check.
-- `CjsHlslFormat.read(input, options)` performs a one-shot read.
-- `CjsHlslFormat.inspect(input, options)` performs a one-shot inspection.
-- `CjsHlslFormat.toJSON(value)` converts output to JSON-compatible data.
-- `CjsHlslFormat.readFile(path, options)` reads and parses a file in Node.
-
-Inputs may be `Uint8Array`, `ArrayBuffer`, `Buffer`, or `DataView` values.
-Supported container versions are 8 through 15.
-
-## Constants
-
-The class exposes `OUTPUT_JSON`, `OUTPUT_METADATA`, `OUTPUT_RAW`,
-`CLASS_KEYS`, `type`, `mediaTypes`, `inputTypes`, `outputTypes`, and
-`debugOutputTypes`. `inputTypes` contains `sm_hi`, `sm_lo`, and `sm_depth`.
-
-## Output stability
-
-The `json` and `metadata` modes are the supported data contracts described in
-[json-graph.md](json-graph.md). `raw` returns internal parser-DTO
-`Tr2EffectRes` objects, not the canonical runtime-resource class, and may
-change without a major version bump.
-
-## Repository metadata adapter
-
-The repository provides a development script that writes metadata JSON. It is
-not installed as a package `bin`:
-
-```sh
-npm run metadata:hlsl -- effect.sm_hi
-npm run metadata:hlsl -- effect.sm_hi effect.json
-```
-
-When the output path is omitted, the CLI writes `<input-name>.json` in the
-current working directory.
-
-## Related documentation
-
-- [Reading effects](../guides/reading-effects.md)
-- [Hydrating JSON output](../guides/hydrating-json-output.md)
-- [Advanced analysis exports](advanced-analysis.md)
-- [Portable body reflection](portable-reflection.md)
-- [Class catalog](classes/README.md)
+# API reference
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl` supported reader API
+Audience: Users and integrators
+Summary: Documents the reader class, options, output modes, and Node adapters.
+
+## Imports
+
+The package root exports `CjsHlslFormat` as both the default and a named
+export:
+
+```js
+import CjsHlslFormat from "@carbonenginejs/runtime-resource/formats/hlsl";
+import { CjsHlslFormat as NamedReader } from "@carbonenginejs/runtime-resource/formats/hlsl";
+```
+
+Additional named exports intended for advanced tooling are documented
+separately in [advanced-analysis.md](advanced-analysis.md).
+
+## Constructor
+
+```js
+const reader = new CjsHlslFormat({
+    emit: "json",
+    source: "effect.sm_hi",
+    permutation: null,
+    classes: {}
+});
+```
+
+Options are reusable on an instance and can be overridden per call:
+
+- `emit`: `"json"` (default), `"metadata"`, or advanced `"raw"` output.
+- `source`: a caller-supplied label used in diagnostics and output.
+- `permutation`: a `Map` or an array of `{ name, value }` selections.
+- `classes`: constructors used for caller-selected JSON-node projection; this
+  is not canonical runtime shader hydration.
+
+## Instance methods
+
+- `SetValues(options)` updates the reusable profile and returns the reader.
+- `GetValues(options)` returns effective values with optional overrides.
+- `SetClasses(classes)` and `SetClass(type, Class)` configure hydration.
+- `GetClass(type)` and `HasClass(type)` inspect hydration registrations.
+- `Read(input, options)` parses input and emits the configured graph.
+- `Inspect(input, options)` returns header and technique summary data.
+- `ToJSON(value)` converts reader output to JSON-compatible data.
+
+## Static methods
+
+- `CjsHlslFormat.isSupported(input)` performs a header-level support check.
+- `CjsHlslFormat.read(input, options)` performs a one-shot read.
+- `CjsHlslFormat.inspect(input, options)` performs a one-shot inspection.
+- `CjsHlslFormat.toJSON(value)` converts output to JSON-compatible data.
+- `CjsHlslFormat.readFile(path, options)` reads and parses a file in Node.
+
+Inputs may be `Uint8Array`, `ArrayBuffer`, `Buffer`, or `DataView` values.
+Supported container versions are 8 through 15.
+
+## Constants
+
+The class exposes `OUTPUT_JSON`, `OUTPUT_METADATA`, `OUTPUT_RAW`,
+`CLASS_KEYS`, `type`, `mediaTypes`, `inputTypes`, `outputTypes`, and
+`debugOutputTypes`. `inputTypes` contains `sm_hi`, `sm_lo`, and `sm_depth`.
+
+## Output stability
+
+The `json` and `metadata` modes are the supported data contracts described in
+[json-graph.md](json-graph.md). `raw` returns internal parser-DTO
+`Tr2EffectRes` objects, not the canonical runtime-resource class, and may
+change without a major version bump.
+
+## Repository metadata adapter
+
+The repository provides a development script that writes metadata JSON. It is
+not installed as a package `bin`:
+
+```sh
+npm run metadata:hlsl -- effect.sm_hi
+npm run metadata:hlsl -- effect.sm_hi effect.json
+```
+
+When the output path is omitted, the CLI writes `<input-name>.json` in the
+current working directory.
+
+## Related documentation
+
+- [Reading effects](../guides/reading-effects.md)
+- [Hydrating JSON output](../guides/hydrating-json-output.md)
+- [Advanced analysis exports](advanced-analysis.md)
+- [Class catalog](classes/README.md)

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

@@ -1,11 +1,11 @@
-# Class catalog
-
-Status: Deprecated
-Scope: `@carbonenginejs/runtime-resource/formats/hlsl` maintained classes
-Audience: Users, maintainers, and automated readers
-Summary: Points to the canonical package-wide catalogs after format-package consolidation.
-
-The maintained HLSL format entries now live in the
-[package-wide formats class catalog](../../../../reference/classes/formats.md#hlsl).
-Canonical runtime effect-resource and shader-reflection entries live in the
-[resources class catalog](../../../../reference/classes/resources.md).
+# Class catalog
+
+Status: Deprecated
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl` maintained classes
+Audience: Users, maintainers, and automated readers
+Summary: Points to the canonical package-wide catalogs after format-package consolidation.
+
+The maintained HLSL format entries now live in the
+[package-wide formats class catalog](../../../../reference/classes/formats.md#hlsl).
+Canonical runtime effect-resource and shader-reflection entries live in the
+[resources class catalog](../../../../reference/classes/resources.md).

package/docs/formats/hlsl/reference/json-graph.md

@@ -1,100 +1,97 @@
-# JSON and metadata graphs
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-resource/formats/hlsl` emitted data
-Audience: Users and integrators
-Summary: Documents the default JSON graph, compact metadata graph, and permutation selection.
-
-## Default JSON graph
-
-`emit: "json"` is the default:
-
-```text
-Root
-|- version, compilerVersion, sourcePath, bodyCount, loadError
-|- permutations: Permutation[]
-`- effect: EffectDescription | null
-   |- version, effectName, annotations, readError
-   `- techniques: Technique[]
-      `- passes: Pass[]
-         |- renderStates: { key, value }[]
-         `- stageInputs: (StageInput | null)[]
-            |- constants: Constant[]
-            |- resources: Resource[]
-            |- uavs: Resource[]
-            |- samplers: Sampler[]
-            |- signature
-            `- bytecode: ShaderBytecode | null
-```
-
-Bytecode values are opaque payloads. A compatible bytecode-format package
-must decode their instruction streams.
-
-## Permutation selection
-
-By default, `effect` represents the container's default option set. Select
-another compiled body with an array or `Map`:
-
-```js
-const effect = CjsHlslFormat.read(bytes, {
-    permutation: [
-        { name: "BLEND_MODE", value: "TRANSPARENT" }
-    ]
-});
-```
-
-## Metadata graph
-
-`emit: "metadata"` returns compact inspection data without bytecode,
-constant-value bytes, or runtime handles:
-
-```text
-MetadataRoot
-|- version, compilerVersion, sourcePath, bodyCount, loadError
-|- permutations: Permutation[]
-|- bodyIndex
-|- selectedOptions: Option[]
-`- effect: MetadataEffect | null
-   `- techniques: Technique[]
-      `- passes: Pass[]
-         |- renderStates: RenderState[]
-         `- stageInputs: (StageInput | null)[]
-            |- constantValueSize
-            |- constants: Constant[]
-            |- resources: Resource[]
-            |- uavs: Resource[]
-            |- samplers: Sampler[]
-            |- annotations
-            `- signature
-```
-
-Each render-state record retains its numeric `key` and `value`. Known state
-types can also include readable or typed fields such as `name`, `valueName`,
-`valueFloat`, `valueHex`, or `valueFlags`.
-
-## Raw graph
-
-`emit: "raw"` returns the internal parser-DTO `Tr2EffectRes` graph. It is not
-the canonical runtime-resource class. It allows advanced callers to resolve
-multiple permutations after one parse, but it is not a stable or
-serialization-safe schema.
-
-Raw stage and library inputs retain authored `sourceConstantValueSize` /
-`sourceConstantValues` separately from Carbon-compatible mutable constant
-buffers. Libraries retain their source `cjsShaderBytecode` directly. Use
-`@carbonenginejs/runtime-resource/formats/hlsl/portable` to copy those facts into a validated
-handle-free contract.
-
-## Compatibility and failures
-
-The reader supports compiled effect versions 8 through 15. The root or
-selected effect can contain format-defined error fields when a compiled body
-cannot be decoded. Invalid input reads and unsupported layout decisions throw
-rather than being filled with guessed values.
-
-## Related documentation
-
-- [API reference](api.md)
-- [Advanced analysis exports](advanced-analysis.md)
-- [Portable body reflection](portable-reflection.md)
-- [Reading effects](../guides/reading-effects.md)
+# JSON and metadata graphs
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl` emitted data
+Audience: Users and integrators
+Summary: Documents the default JSON graph, compact metadata graph, and permutation selection.
+
+## Default JSON graph
+
+`emit: "json"` is the default:
+
+```text
+Root
+|- version, compilerVersion, sourcePath, bodyCount, loadError
+|- permutations: Permutation[]
+`- effect: EffectDescription | null
+   |- version, effectName, annotations, readError
+   `- techniques: Technique[]
+      `- passes: Pass[]
+         |- renderStates: { key, value }[]
+         `- stageInputs: (StageInput | null)[]
+            |- constants: Constant[]
+            |- resources: Resource[]
+            |- uavs: Resource[]
+            |- samplers: Sampler[]
+            |- signature
+            `- bytecode: ShaderBytecode | null
+```
+
+Bytecode values are opaque payloads. A compatible bytecode-format package
+must decode their instruction streams.
+
+## Permutation selection
+
+By default, `effect` represents the container's default option set. Select
+another compiled body with an array or `Map`:
+
+```js
+const effect = CjsHlslFormat.read(bytes, {
+    permutation: [
+        { name: "BLEND_MODE", value: "TRANSPARENT" }
+    ]
+});
+```
+
+## Metadata graph
+
+`emit: "metadata"` returns compact inspection data without bytecode,
+constant-value bytes, or runtime handles:
+
+```text
+MetadataRoot
+|- version, compilerVersion, sourcePath, bodyCount, loadError
+|- permutations: Permutation[]
+|- bodyIndex
+|- selectedOptions: Option[]
+`- effect: MetadataEffect | null
+   `- techniques: Technique[]
+      `- passes: Pass[]
+         |- renderStates: RenderState[]
+         `- stageInputs: (StageInput | null)[]
+            |- constantValueSize
+            |- constants: Constant[]
+            |- resources: Resource[]
+            |- uavs: Resource[]
+            |- samplers: Sampler[]
+            |- annotations
+            `- signature
+```
+
+Each render-state record retains its numeric `key` and `value`. Known state
+types can also include readable or typed fields such as `name`, `valueName`,
+`valueFloat`, `valueHex`, or `valueFlags`.
+
+## Raw graph
+
+`emit: "raw"` returns the internal parser-DTO `Tr2EffectRes` graph. It is not
+the canonical runtime-resource class. It allows advanced callers to resolve
+multiple permutations after one parse, but it is not a stable or
+serialization-safe schema.
+
+Raw stage and library inputs retain authored `sourceConstantValueSize` /
+`sourceConstantValues` separately from Carbon-compatible mutable constant
+buffers. Libraries retain their source `cjsShaderBytecode` directly.
+
+## Compatibility and failures
+
+The reader supports compiled effect versions 8 through 15. The root or
+selected effect can contain format-defined error fields when a compiled body
+cannot be decoded. Invalid input reads and unsupported layout decisions throw
+rather than being filled with guessed values.
+
+## Related documentation
+
+- [API reference](api.md)
+- [Advanced analysis exports](advanced-analysis.md)
+- [Reading effects](../guides/reading-effects.md)

package/docs/formats/pickle.md

@@ -0,0 +1,82 @@
+# Data-only pickle protocol 0
+
+Status: Experimental
+Scope: `@carbonenginejs/runtime-resource/formats/pickle`
+Audience: Resource integrators handling inert legacy data caches
+Summary: Defines safe protocol-0 pickle decoding without Python object reconstruction.
+
+## Boundary
+
+`CjsPickleFormat` reads `.pickle` bytes through an internal protocol-0 reader.
+It is a data decoder, not a general Python unpickler. It never imports a
+module, resolves a global, calls a reducer, follows a persistent ID, or
+constructs a Python object. Every executable, object-bearing, newer-protocol,
+or unknown opcode fails at its exact byte offset.
+
+The initial reader accepts the protocol-0 scalar, string, list, tuple,
+dictionary, memo, append, and set-item operations required by inert data
+graphs. Lists and tuples become JavaScript arrays. Integers outside the safe
+JavaScript range become lossless decimal strings. Dictionary keys must be
+strings or safe integers; collisions introduced by JSON key normalization are
+rejected.
+
+## Outputs
+
+The default `json` output returns a plain JSON-compatible graph and rejects
+cycles. `payload` and debug `raw` output preserve memo aliases and may contain
+cycles:
+
+```js
+import { CjsPickleFormat } from
+  "@carbonenginejs/runtime-resource/formats/pickle";
+
+const values = CjsPickleFormat.read(bytes);
+const exactGraph = CjsPickleFormat.read(bytes, { emit: "payload" });
+```
+
+`CjsPickleFormat.supportedProtocols` currently contains only protocol `0`.
+The public format name follows the `.pickle` extension so future protocol
+dispatch can be added without changing resource registration. Unsupported
+protocols continue to fail closed until their data-only semantics are
+implemented and tested.
+
+## Resource registration
+
+The format contains no domain target policy. A caller registers the extension
+and decides whether an exact resource path returns raw decoded data or hydrates
+a target:
+
+```js
+import {
+  CjsLoadingObject,
+  CjsResMan
+} from "@carbonenginejs/runtime-resource";
+import { CjsPickleFormat } from
+  "@carbonenginejs/runtime-resource/formats/pickle";
+
+const resMan = new CjsResMan({ source });
+
+resMan.RegisterExtension("pickle", CjsLoadingObject, {
+  Format: CjsPickleFormat,
+  Identify(_values, context) {
+    return context.resFilePath === "res:/data/profile.pickle";
+  }
+});
+```
+
+Resource paths, extensions, and filenames in the context are normalized to
+lowercase. URL-backed sources additionally expose the exact translated URL.
+
+## Limits
+
+Every read is bounded by configurable positive safe-integer limits for input
+bytes, operations, stack depth, memo size and IDs, container items, and string
+bytes. Defaults are conservative for ordinary resource files. Callers may
+lower limits per profile or read; raising them remains an explicit trust and
+memory decision.
+
+## Related documentation
+
+- [Format subpaths](README.md)
+- [Queues, publication, and registration](../reference/queues.md)
+- [Browser worker execution](../reference/workers.md)