@carbonenginejs/runtime-resource 0.9.2 → 0.10.0

package/docs/architecture.md

@@ -19,10 +19,13 @@ Engine adapters own device realization:
 LOADED -> PREPARING -> PREPARED
 ```
 
-The package selects and runs registered non-shader readers, hydrates or
-returns the promised CPU outcome, and stores lifecycle state, cache entries,
-and loaded payloads. It never creates WebGL/WebGPU textures, buffers, shader
-modules, pipelines, or bind groups, and it never inspects backend capability.
+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 format package's plain portable reflection, 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.
 
@@ -40,47 +43,67 @@ historical mapping.
 - `CjsResMan` semantic resource construction, registered-format selection,
   concurrency-limited source loading, staged prepare queues, layered
   source/read/resource deduplication, object loader dispatch, and prefetch.
-- `CjsTextureArrayRes` and `CjsTextureParameterProxy` for material-facing,
+- 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.
-- Path normalization, extension helpers, and source adapters for memory and
-  `fetch`.
+- 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; portable hydration; permutation selection; and per-index caching.
 - `Tr2TexturePipeline` CPU-only texture steps and `Tr2TextureLodManager`
   membership.
 - Opaque engine-owned subobject slots for backend adapters.
-- Non-shader format implementations as explicit tree-shakeable subpaths under
+- 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 formats (`format-dxbc`, `format-hlsl`, `format-webgl`,
-  `format-webgpu` remain separate packages).
+- Shader binary decoding, backend translation, and package serialization remain
+  in the standalone shader-format packages. 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.
+  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).
 
 ## Source layout
 
 Authoring source is decorated JavaScript; published output is built ESM in
-`npm/dist`. Completed Carbon data classes live with maintained source under
-`src/resources`; `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.
+`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.

package/docs/concepts/resource-lifecycle.md

@@ -116,7 +116,8 @@ Application / runtime object
 | - mark resource REQUESTED                     |
 | - share one source operation per source/path  |
 | - obey maxConcurrentLoads                     |
-| - source.Read(path)                           |
+| - CjsResMan builds URL when provider needs it |
+| - provider.Read(sourcePath)                   |
 +===============================================+
         |
         | source bytes

package/docs/formats/README.md

@@ -29,6 +29,10 @@ through `SetPayload()`, validate their own required fields, and throw
 `GetPayload()`, `HasPayload()`, and `ReleasePayload()` manage transient CPU
 retention without introducing a parallel DTO class hierarchy.
 
+Clone-safe formats may additionally declare browser-worker execution
+metadata. Worker eligibility never changes the format's direct API; see
+[browser worker execution](../reference/workers.md).
+
 ## Format map
 
 | Format | Class | Import |

package/docs/reference/classes/README.md

@@ -21,12 +21,14 @@ documentation check against the actual source tree.
 
 ## Catalog pages
 
-- [core.md](core.md): the resource manager, MotherLode cache, resource and
-  source classes, and the format/probe bases.
+- [core.md](core.md): the resource manager, MotherLode cache, fetch provider,
+  core resource class, and the format/probe bases.
+- [audio.md](audio.md): raw audio-byte owners and individually addressable
+  audio resource views.
 - [resources.md](resources.md): the Carbon-shaped semantic resource and data
-  classes under `src/resources`.
+  classes in the `src/resource` family tree.
 - [texture.md](texture.md): texture-array aggregation classes under
-  `src/texture`.
+  `src/resource/texture`.
 - [formats.md](formats.md): format entry classes and their internal reader
   machinery under `src/formats`.
 - [dropped.md](dropped.md): retained native shapes under `src/dropped` that

package/docs/reference/classes/audio.md

@@ -0,0 +1,30 @@
+# Audio resource class catalog
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/resource/audio` classes
+Audience: Users, maintainers, and automated readers
+Summary: Catalogs raw audio-byte owners and individually addressable audio resource views.
+
+<!-- class:CjsAudioBufferRes -->
+## `CjsAudioBufferRes`
+
+Physical audio byte-owner resource whose payload may back one complete file or several logical audio files.
+
+- Export: `@carbonenginejs/runtime-resource/resource/audio`
+- Source: `src/resource/audio/CjsAudioBufferRes.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class
+- Notes: Owns raw payload retention and locks without interpreting media IDs,
+  bank members, decoding, or playback.
+
+<!-- class:CjsAudioRes -->
+## `CjsAudioRes`
+
+Individually addressable audio resource representing one complete file over either a complete or windowed physical source.
+
+- Export: `@carbonenginejs/runtime-resource/resource/audio`
+- Source: `src/resource/audio/CjsAudioRes.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class
+- Notes: Carries immutable media metadata, returns detached byte windows, and
+  delegates locks and payload liveness to its backing resource.

package/docs/reference/classes/core.md

@@ -1,7 +1,7 @@
 # Core class catalog
 
 Status: Evolving  
-Scope: `@carbonenginejs/runtime-resource` classes under `src/` and `src/format/`  
+Scope: `@carbonenginejs/runtime-resource` classes under `src/`, `src/resource`, and `src/format/`
 Audience: Users, maintainers, and automated readers  
 Summary: Provides one-sentence purpose descriptors for the resource manager, registry, resource, source, and format/probe base classes.
 
@@ -31,7 +31,7 @@ GPU-free resource manager that resolves paths through registered sources and for
 Small FIFO executor used inside `CjsResMan` that tracks item ids, pause state, concurrency, cancellation, and sync/async completion while queue policy stays in the manager.
 
 - Export: None
-- Source: `src/CjsResManQueue.js`
+- Source: `src/CjsResManWorkQueue.js`
 - Visibility: Internal
 - Kind: Internal implementation class
 
@@ -41,27 +41,47 @@ Small FIFO executor used inside `CjsResMan` that tracks item ids, pause state, c
 Base runtime resource handle that carries normalized path/extension/requirement identity, load state, and an attached CPU payload, with manager lifecycle callbacks supplied by `CjsResMan` after canonical insertion.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/CjsResource.js`
+- Source: `src/resource/CjsResource.js`
 - Visibility: Public
 - Kind: Adapted Carbon concept
 
-<!-- class:CjsMemoryResourceSource -->
-## `CjsMemoryResourceSource`
+<!-- class:CjsResManMainThreadLoader -->
+## `CjsResManMainThreadLoader`
 
-In-memory resource source that maps normalized resource paths to preset values and serves them to reads without any I/O.
+Direct execution strategy that reads through a structural source and invokes registered format facades on the caller thread.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/CjsResourceSource.js`
+- Source: `src/worker/CjsResManMainThreadLoader.js`
+- Visibility: Public
+- Kind: Adapted ccpwgl loader strategy
+
+<!-- class:CjsResManWorkerLoader -->
+## `CjsResManWorkerLoader`
+
+Browser module-worker strategy that correlates source/format requests, transfers owned buffers, propagates cancellation and fatal failure, and delegates unsupported operations to a main-thread loader.
+
+- Export: `@carbonenginejs/runtime-resource`
+- Source: `src/worker/CjsResManWorkerLoader.js`
+- Visibility: Public
+- Kind: Adapted ccpwgl loader strategy
+
+<!-- class:CjsResManWorker -->
+## `CjsResManWorker`
+
+Static browser-worker host that owns its operation/message vocabulary, executes clone-safe source and format operations, installs the message envelope, transfers owned buffers, and serializes failures for `CjsResMan`.
+
+- Export: `@carbonenginejs/runtime-resource/worker`
+- Source: `src/worker/CjsResManWorker.js`
 - Visibility: Public
 - Kind: Original CarbonEngineJS class
 
-<!-- class:CjsFetchResourceSource -->
-## `CjsFetchResourceSource`
+<!-- class:CjsResManFetchProvider -->
+## `CjsResManFetchProvider`
 
-Resource source that resolves a normalized path against an optional base URL and reads response bytes through an injected fetch implementation.
+`CjsResMan` provider that fetches an already-resolved URL on the caller thread or through the resource worker.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/CjsResourceSource.js`
+- Source: `src/CjsResManFetchProvider.js`
 - Visibility: Public
 - Kind: Original CarbonEngineJS class