@carbonenginejs/runtime-resource 0.13.0 → 0.14.0

package/dist/worker/protocol.js

@@ -1,12 +1,12 @@
-const Operation = Object.freeze({
-  FETCH: "source.fetch",
-  FORMAT_READ: "format.read"
-});
-const Message = Object.freeze({
-  CANCEL: "cancel",
-  EXECUTE: "execute",
-  RESULT: "result"
-});
-
-export { Message, Operation };
-//# sourceMappingURL=protocol.js.map
+const Operation = Object.freeze({
+  FETCH: "source.fetch",
+  FORMAT_READ: "format.read"
+});
+const Message = Object.freeze({
+  CANCEL: "cancel",
+  EXECUTE: "execute",
+  RESULT: "result"
+});
+
+export { Message, Operation };
+//# sourceMappingURL=protocol.js.map

package/docs/README.md

@@ -1,98 +1,98 @@
-# Package documentation
-
-Status: Evolving  
-Scope: `@carbonenginejs/runtime-resource`  
-Audience: Users and integrators  
-Summary: Documentation home for the GPU-free resource lifecycle, cache, format, and object-loading package.
-
-## Purpose
-
-`@carbonenginejs/runtime-resource` owns the GPU-free resource layer of
-CarbonEngineJS: resource identity and state, the MotherLode cache, semantic
-resource classes, registered format readers, fetch providers, and the queued
-CPU load/publication pipeline. It stops at a published CPU payload; engine
-packages realize that payload into backend objects. It also owns the canonical
-device-free `Tr2EffectRes`/`Tr2Shader` reflection graph, built by reading the
-compiled Carbon container directly.
-
-## Use this package when
-
-- you need Carbon-shaped resource loading (`res:/` paths, requirement/emit
-  selection, `Ready()`/`GetObject()`) without choosing a GPU backend;
-- you need one of the non-shader format readers as a tree-shakeable subpath
-  (`@carbonenginejs/runtime-resource/formats/<name>`);
-- you need canonical effect permutation selection or immutable shader
-  reflection records from `@carbonenginejs/runtime-resource/resource/shader`;
-- you need canonical raw audio resources for complete files or byte windows
-  over shared physical sources;
-- you are writing an engine adapter that consumes published CPU payloads and
-  needs the documented retention, reload, and texture-array contracts.
-
-## Where it fits
-
-- Foundations consumed: `@carbonenginejs/runtime-utils` (event emitter, model
-  contracts) and `@carbonenginejs/runtime-utils` where formats need math values.
-- Normal consumers: `runtime-core` (configures and exposes a `CjsResMan`),
-  `runtime-trinity` and `runtime-sof` (request GPU-free objects), and engine
-  packages (`engine-webgpu`, future WebGL engines) that realize prepared
-  resources.
-- Owned responsibility: resource identity, cache, CPU payload lifecycle,
-  format selection and conversion, load/publication queues, and canonical
-  device-free effect/shader reflection hydration and selection.
-- Owned elsewhere: WebGL/WebGPU realization, device budgets, and device-loss
-  recovery belong to engine packages; shader formats belong to the dedicated
-  shader format packages.
-
-## Start here
-
-- [Architecture and boundaries](architecture.md)
-- [Resource lifecycle concepts](concepts/resource-lifecycle.md)
-- [Shader resource model](concepts/shader-resource-model.md)
-- [Format subpaths](formats/README.md)
-- [Carbon compiled-effect container](formats/carbon-effect-container.md)
-
-## Documentation map
-
-- [architecture.md](architecture.md): package boundary, relationships, and the
-  GPU-free split.
-- [concepts/resource-lifecycle.md](concepts/resource-lifecycle.md): states,
-  the load/prepare split, and the request workflow.
-- [concepts/shader-resource-model.md](concepts/shader-resource-model.md): how
-  `Tr2EffectRes`, `Tr2Shader` and `Tr2Effect` relate, verified against Carbon —
-  one file, many permutations, many effects sharing them.
-- [concepts/writing-an-engine-adapter.md](concepts/writing-an-engine-adapter.md):
-  the coupling rules and the reflection/topology seam for engine packages —
-  read before writing a second engine.
-- [reference/motherlode-cache.md](reference/motherlode-cache.md): canonical
-  identity, byte-budget cache, payload retention, and purge contracts.
-- [reference/reload.md](reference/reload.md): the candidate-first atomic
-  reload contract.
-- [reference/queues.md](reference/queues.md): queued CPU load, publication,
-  registration, and the `Wait()` fence.
-- [reference/workers.md](reference/workers.md): browser-worker source and
-  declared worker-safe format execution.
-- [reference/classes/audio.md](reference/classes/audio.md): complete/shared
-  audio byte owners and individually addressable audio resource views.
-- [reference/classes/resources.md](reference/classes/resources.md): canonical
-  resource records, effect selection, and shader-reflection classes.
-- [reference/texture-arrays.md](reference/texture-arrays.md): texture-array
-  proxies, update generations, and adapter commits.
-- [reference/texture-pipeline.md](reference/texture-pipeline.md):
-  `Tr2TexturePipeline` CPU steps and `Tr2TextureLodManager` membership.
-- [reference/events.md](reference/events.md): the `CjsEventEmitter` contract
-  and event memory rules.
-- [reference/classes/README.md](reference/classes/README.md): the searchable
-  one-sentence class-purpose catalog.
-- [formats/README.md](formats/README.md): format import map and per-format
-  output notes.
-- [formats/carbon-effect-container.md](formats/carbon-effect-container.md): the
-  public v15 compiled-effect binary layout, extension rules, shared byte reader
-  and writer, and arena offset policy a byte-exact re-emit depends on.
-- [formats/gr2.md](formats/gr2.md): Granny GR2/GSF reading, output modes,
-  conversions, graph shape, and class hydration.
-- [formats/wwise.md](formats/wwise.md): Wwise soundbank and media readers.
-- [formats/stl.md](formats/stl.md): STL geometry export.
-- [formats/provenance.md](formats/provenance.md): format ownership, fork
-  provenance, and retained snapshots.
-- [roadmap.md](roadmap.md): approved future direction with explicit current
-  boundary context where needed to interpret the plan.
+# Package documentation
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource`  
+Audience: Users and integrators  
+Summary: Documentation home for the GPU-free resource lifecycle, cache, format, and object-loading package.
+
+## Purpose
+
+`@carbonenginejs/runtime-resource` owns the GPU-free resource layer of
+CarbonEngineJS: resource identity and state, the MotherLode cache, semantic
+resource classes, registered format readers, fetch providers, and the queued
+CPU load/publication pipeline. It stops at a published CPU payload; engine
+packages realize that payload into backend objects. It also owns the canonical
+device-free `Tr2EffectRes`/`Tr2Shader` reflection graph, built by reading the
+compiled Carbon container directly.
+
+## Use this package when
+
+- you need Carbon-shaped resource loading (`res:/` paths, requirement/emit
+  selection, `Ready()`/`GetObject()`) without choosing a GPU backend;
+- you need one of the non-shader format readers as a tree-shakeable subpath
+  (`@carbonenginejs/runtime-resource/formats/<name>`);
+- you need canonical effect permutation selection or immutable shader
+  reflection records from `@carbonenginejs/runtime-resource/resource/shader`;
+- you need canonical raw audio resources for complete files or byte windows
+  over shared physical sources;
+- you are writing an engine adapter that consumes published CPU payloads and
+  needs the documented retention, reload, and texture-array contracts.
+
+## Where it fits
+
+- Foundations consumed: `@carbonenginejs/runtime-utils` (event emitter, model
+  contracts) and `@carbonenginejs/runtime-utils` where formats need math values.
+- Normal consumers: `runtime-core` (configures and exposes a `CjsResMan`),
+  `runtime-trinity` and `runtime-sof` (request GPU-free objects), and engine
+  packages (`engine-webgpu`, future WebGL engines) that realize prepared
+  resources.
+- Owned responsibility: resource identity, cache, CPU payload lifecycle,
+  format selection and conversion, load/publication queues, and canonical
+  device-free effect/shader reflection hydration and selection.
+- Owned elsewhere: WebGL/WebGPU realization, device budgets, and device-loss
+  recovery belong to engine packages; shader formats belong to the dedicated
+  shader format packages.
+
+## Start here
+
+- [Architecture and boundaries](architecture.md)
+- [Resource lifecycle concepts](concepts/resource-lifecycle.md)
+- [Shader resource model](concepts/shader-resource-model.md)
+- [Format subpaths](formats/README.md)
+- [Carbon compiled-effect container](formats/carbon-effect-container.md)
+
+## Documentation map
+
+- [architecture.md](architecture.md): package boundary, relationships, and the
+  GPU-free split.
+- [concepts/resource-lifecycle.md](concepts/resource-lifecycle.md): states,
+  the load/prepare split, and the request workflow.
+- [concepts/shader-resource-model.md](concepts/shader-resource-model.md): how
+  `Tr2EffectRes`, `Tr2Shader` and `Tr2Effect` relate, verified against Carbon —
+  one file, many permutations, many effects sharing them.
+- [concepts/writing-an-engine-adapter.md](concepts/writing-an-engine-adapter.md):
+  the coupling rules and the reflection/topology seam for engine packages —
+  read before writing a second engine.
+- [reference/motherlode-cache.md](reference/motherlode-cache.md): canonical
+  identity, byte-budget cache, payload retention, and purge contracts.
+- [reference/reload.md](reference/reload.md): the candidate-first atomic
+  reload contract.
+- [reference/queues.md](reference/queues.md): queued CPU load, publication,
+  registration, and the `Wait()` fence.
+- [reference/workers.md](reference/workers.md): browser-worker source and
+  declared worker-safe format execution.
+- [reference/classes/audio.md](reference/classes/audio.md): complete/shared
+  audio byte owners and individually addressable audio resource views.
+- [reference/classes/resources.md](reference/classes/resources.md): canonical
+  resource records, effect selection, and shader-reflection classes.
+- [reference/texture-arrays.md](reference/texture-arrays.md): texture-array
+  proxies, update generations, and adapter commits.
+- [reference/texture-pipeline.md](reference/texture-pipeline.md):
+  `Tr2TexturePipeline` CPU steps and `Tr2TextureLodManager` membership.
+- [reference/events.md](reference/events.md): the `CjsEventEmitter` contract
+  and event memory rules.
+- [reference/classes/README.md](reference/classes/README.md): the searchable
+  one-sentence class-purpose catalog.
+- [formats/README.md](formats/README.md): format import map and per-format
+  output notes.
+- [formats/carbon-effect-container.md](formats/carbon-effect-container.md): the
+  public v15 compiled-effect binary layout, extension rules, shared byte reader
+  and writer, and arena offset policy a byte-exact re-emit depends on.
+- [formats/gr2.md](formats/gr2.md): Granny GR2/GSF reading, output modes,
+  conversions, graph shape, and class hydration.
+- [formats/wwise.md](formats/wwise.md): Wwise soundbank and media readers.
+- [formats/stl.md](formats/stl.md): STL geometry export.
+- [formats/provenance.md](formats/provenance.md): format ownership, fork
+  provenance, and retained snapshots.
+- [roadmap.md](roadmap.md): approved future direction with explicit current
+  boundary context where needed to interpret the plan.

package/docs/architecture.md

@@ -1,118 +1,118 @@
-# Architecture and boundaries
-
-Status: Evolving  
-Scope: `@carbonenginejs/runtime-resource`  
-Audience: Users and integrators  
-Summary: Defines the GPU-free boundary this package owns and how engine and runtime packages relate to it.
-
-## The GPU-free split
-
-`runtime-resource` owns the GPU-free half of the Carbon resource lifecycle:
-
-```text
-EMPTY -> REQUESTED/LOADING -> LOADED
-```
-
-Engine adapters own device realization:
-
-```text
-LOADED -> PREPARING -> PREPARED
-```
-
-The package selects and runs registered readers, hydrates or returns the
-promised CPU outcome, and stores lifecycle state, cache entries, and loaded
-payloads. For compiled effects it independently validates complete permutation
-topology and the Carbon v15 container records it read itself, selects a
-permutation, and hydrates a canonical device-free `Tr2Shader` graph. It never
-creates WebGL/WebGPU textures, buffers, shader modules, pipelines, or bind
-groups, and it never inspects backend capability.
-A realization failure destroys its candidate and returns the resource to
-`LOADED` without discarding the valid CPU payload.
-
-This deliberately differs from Carbon and ccpwgl, whose resource classes live
-inside an engine that can prepare GPU objects directly. Keeping the
-format/resource layer reusable means stopping before GPU work; see
-[resource lifecycle concepts](concepts/resource-lifecycle.md) for the
-historical mapping.
-
-## What the package owns
-
-- `CjsResource` state and Carbon-style resource methods.
-- `CjsMotherLode` canonical identity, explicit replacement results, activity
-  and lock metadata, deterministic payload/adapter cleanup, and cache stats.
-- `CjsResMan` extension-selected resource/object handlers, semantic resource
-  overrides, ordered and legacy registered-format selection,
-  concurrency-limited source loading, staged prepare queues, layered
-  source/read/resource deduplication, object loader dispatch, and prefetch.
-- Main-thread and browser-worker resource execution strategies, including
-  transferable fetch results and declared worker-safe CPU readers.
-- `CjsTextureArrayRes` and `CjsTextureArrayResParameterProxy` for material-facing,
-  frame-coalesced texture-array inputs.
-- `CjsAudioBufferRes` for physical audio-byte ownership and `CjsAudioRes` for
-  complete or windowed individually addressable audio files.
-- Raw `CjsEventEmitter` (from `runtime-utils/model`) for manager/runtime events
-  without requiring `CjsModel` inheritance.
-- Resource-path normalization and URL resolution, including prefix bases and
-  an injectable complete resolver, with fetch execution delegated to a
-  URL-only provider.
-- Resource-specific geometry traversal and payload adaptation, composed with
-  shared vector, matrix, bounds, sphere, ray, and mesh math from
-  `runtime-utils` rather than maintaining another math implementation here.
-- Plain reader/converter payload objects with focused shared validators.
-- Canonical Carbon resource classes that validate and hold CPU payloads
-  privately: `TriTextureRes`, `TriGeometryRes`, `Tr2EffectRes`, `Tr2ImageRes`,
-  `TriGrannyRes`, `Tr2GrannyStateRes`, and `Tr2LightProfileRes`.
-- Canonical device-free shader/reflection classes: `Tr2Shader`, its effect,
-  technique, pass, stage, constant, resource, sampler, annotation, and library
-  records; Carbon-binary hydration; permutation selection; and per-index caching.
-- `Tr2TexturePipeline` CPU-only texture steps and `Tr2TextureLodManager`
-  membership.
-- Opaque engine-owned subobject slots for backend adapters.
-- Format implementations as explicit tree-shakeable subpaths under
-  `@carbonenginejs/runtime-resource/formats/<name>`.
-
-## What the package does not own
-
-- WebGL/WebGPU realization, allocations, upload accounting, device budgets,
-  capability limits, and device-loss recovery (engine packages).
-- Shader binary decoding, backend translation, and package serialization live
-  in the explicit `runtime-resource/formats/{hlsl,dxbc,webgl,webgpu}` subpaths.
-  Backend shader objects remain in engine packages.
-- AudioBuffer construction, playback, or audio manager behavior.
-- Audio-library document construction, enrichment, media-ID interpretation,
-  and delivery-route selection.
-
-## Package relationships
-
-- `runtime-core` may configure and expose a `CjsResMan`, but does not own its
-  implementation.
-- `runtime-trinity` and `runtime-sof` may request GPU-free objects and
-  resources without selecting an engine. Trinity owns the mutable
-  `Tr2Effect`/`Tr2Material` facade, parameters, options, and sampler overrides;
-  it consumes the resource-owned shader graph.
-- `engine-webgpu` and future WebGL engines consume loaded resources and own
-  all backend allocations, preparation, replacement, and destruction.
-
-Concrete formats are not imported or registered by the package root; see
-[formats/README.md](formats/README.md) for the import rule and map.
-Worker-safe formats provide their own exact module declaration and remain
-explicit registrations; see [browser worker execution](reference/workers.md).
-
-Extension routes are manager-local configuration. They bind an extension to a
-handler plus one format or an ordered format chain. The handler's
-`ResourceHandlerMode` declaration determines whether path-only `Fetch()`
-returns the stable resource or the constructed object. The route snapshot is
-captured by the canonical handle, so later registration changes affect only a
-new identity after explicit deletion or clearing. Target construction and
-dynamic identification run after any worker decode on the main thread.
-
-## Source layout
-
-Authoring source is decorated JavaScript; published output is built ESM in
-`npm/dist`. Resource owners and their direct Carbon data records live under
-`src/resource`, grouped as `audio`, `geometry`, `geometry/granny`, `shader`,
-and `texture`; worker execution and its message protocol live under `src/worker`;
-`src/generated` is reserved for unresolved active ports and is currently
-absent. Native shapes that JavaScript replaces or does not use are retained
-only under `src/dropped`, with their disposition documented there, and are
-never exported or bundled.
+# Architecture and boundaries
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource`  
+Audience: Users and integrators  
+Summary: Defines the GPU-free boundary this package owns and how engine and runtime packages relate to it.
+
+## The GPU-free split
+
+`runtime-resource` owns the GPU-free half of the Carbon resource lifecycle:
+
+```text
+EMPTY -> REQUESTED/LOADING -> LOADED
+```
+
+Engine adapters own device realization:
+
+```text
+LOADED -> PREPARING -> PREPARED
+```
+
+The package selects and runs registered readers, hydrates or returns the
+promised CPU outcome, and stores lifecycle state, cache entries, and loaded
+payloads. For compiled effects it independently validates complete permutation
+topology and the Carbon v15 container records it read itself, selects a
+permutation, and hydrates a canonical device-free `Tr2Shader` graph. It never
+creates WebGL/WebGPU textures, buffers, shader modules, pipelines, or bind
+groups, and it never inspects backend capability.
+A realization failure destroys its candidate and returns the resource to
+`LOADED` without discarding the valid CPU payload.
+
+This deliberately differs from Carbon and ccpwgl, whose resource classes live
+inside an engine that can prepare GPU objects directly. Keeping the
+format/resource layer reusable means stopping before GPU work; see
+[resource lifecycle concepts](concepts/resource-lifecycle.md) for the
+historical mapping.
+
+## What the package owns
+
+- `CjsResource` state and Carbon-style resource methods.
+- `CjsMotherLode` canonical identity, explicit replacement results, activity
+  and lock metadata, deterministic payload/adapter cleanup, and cache stats.
+- `CjsResMan` extension-selected resource/object handlers, semantic resource
+  overrides, ordered and legacy registered-format selection,
+  concurrency-limited source loading, staged prepare queues, layered
+  source/read/resource deduplication, object loader dispatch, and prefetch.
+- Main-thread and browser-worker resource execution strategies, including
+  transferable fetch results and declared worker-safe CPU readers.
+- `CjsTextureArrayRes` and `CjsTextureArrayResParameterProxy` for material-facing,
+  frame-coalesced texture-array inputs.
+- `CjsAudioBufferRes` for physical audio-byte ownership and `CjsAudioRes` for
+  complete or windowed individually addressable audio files.
+- Raw `CjsEventEmitter` (from `runtime-utils/model`) for manager/runtime events
+  without requiring `CjsModel` inheritance.
+- Resource-path normalization and URL resolution, including prefix bases and
+  an injectable complete resolver, with fetch execution delegated to a
+  URL-only provider.
+- Resource-specific geometry traversal and payload adaptation, composed with
+  shared vector, matrix, bounds, sphere, ray, and mesh math from
+  `runtime-utils` rather than maintaining another math implementation here.
+- Plain reader/converter payload objects with focused shared validators.
+- Canonical Carbon resource classes that validate and hold CPU payloads
+  privately: `TriTextureRes`, `TriGeometryRes`, `Tr2EffectRes`, `Tr2ImageRes`,
+  `TriGrannyRes`, `Tr2GrannyStateRes`, and `Tr2LightProfileRes`.
+- Canonical device-free shader/reflection classes: `Tr2Shader`, its effect,
+  technique, pass, stage, constant, resource, sampler, annotation, and library
+  records; Carbon-binary hydration; permutation selection; and per-index caching.
+- `Tr2TexturePipeline` CPU-only texture steps and `Tr2TextureLodManager`
+  membership.
+- Opaque engine-owned subobject slots for backend adapters.
+- Format implementations as explicit tree-shakeable subpaths under
+  `@carbonenginejs/runtime-resource/formats/<name>`.
+
+## What the package does not own
+
+- WebGL/WebGPU realization, allocations, upload accounting, device budgets,
+  capability limits, and device-loss recovery (engine packages).
+- Shader binary decoding, backend translation, and package serialization live
+  in the explicit `runtime-resource/formats/{hlsl,dxbc,webgl,webgpu}` subpaths.
+  Backend shader objects remain in engine packages.
+- AudioBuffer construction, playback, or audio manager behavior.
+- Audio-library document construction, enrichment, media-ID interpretation,
+  and delivery-route selection.
+
+## Package relationships
+
+- `runtime-core` may configure and expose a `CjsResMan`, but does not own its
+  implementation.
+- `runtime-trinity` and `runtime-sof` may request GPU-free objects and
+  resources without selecting an engine. Trinity owns the mutable
+  `Tr2Effect`/`Tr2Material` facade, parameters, options, and sampler overrides;
+  it consumes the resource-owned shader graph.
+- `engine-webgpu` and future WebGL engines consume loaded resources and own
+  all backend allocations, preparation, replacement, and destruction.
+
+Concrete formats are not imported or registered by the package root; see
+[formats/README.md](formats/README.md) for the import rule and map.
+Worker-safe formats provide their own exact module declaration and remain
+explicit registrations; see [browser worker execution](reference/workers.md).
+
+Extension routes are manager-local configuration. They bind an extension to a
+handler plus one format or an ordered format chain. The handler's
+`ResourceHandlerMode` declaration determines whether path-only `Fetch()`
+returns the stable resource or the constructed object. The route snapshot is
+captured by the canonical handle, so later registration changes affect only a
+new identity after explicit deletion or clearing. Target construction and
+dynamic identification run after any worker decode on the main thread.
+
+## Source layout
+
+Authoring source is decorated JavaScript; published output is built ESM in
+`npm/dist`. Resource owners and their direct Carbon data records live under
+`src/resource`, grouped as `audio`, `geometry`, `geometry/granny`, `shader`,
+and `texture`; worker execution and its message protocol live under `src/worker`;
+`src/generated` is reserved for unresolved active ports and is currently
+absent. Native shapes that JavaScript replaces or does not use are retained
+only under `src/dropped`, with their disposition documented there, and are
+never exported or bundled.