@carbonenginejs/runtime-resource 0.9.2 → 0.11.0

package/docs/reference/classes/resources.md

@@ -1,9 +1,9 @@
 # Resources class catalog
 
 Status: Evolving  
-Scope: `@carbonenginejs/runtime-resource` classes under `src/resources`  
+Scope: `@carbonenginejs/runtime-resource` classes under `src/resource`
 Audience: Users, maintainers, and automated readers  
-Summary: Provides one-sentence purpose descriptors for the Carbon-shaped semantic resource and data classes in src/resources.
+Summary: Provides one-sentence purpose descriptors for the Carbon-shaped semantic resource and data classes in the src/resource family tree.
 
 <!-- class:AudioGeometryResData -->
 ## `AudioGeometryResData`
@@ -11,7 +11,7 @@ Summary: Provides one-sentence purpose descriptors for the Carbon-shaped semanti
 Data record mirroring Carbon's per-mesh audio-geometry block: an id plus the vertices, indices, and min/max bounds consumed by audio occlusion.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/AudioGeometryResData.js`
+- Source: `src/resource/audio/AudioGeometryResData.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -21,7 +21,7 @@ Data record mirroring Carbon's per-mesh audio-geometry block: an id plus the ver
 Data record mirroring Carbon's GState binding callback payload, holding the `gsf_path` string that identifies the Granny state file to bind.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/GStateBindingCallbackData.js`
+- Source: `src/resource/geometry/granny/GStateBindingCallbackData.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -31,7 +31,7 @@ Data record mirroring Carbon's GState binding callback payload, holding the `gsf
 Data record mirroring Carbon's per-mesh decal block: an index-buffer allocation reference, a LOD mask, and the per-LOD decal ranges.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/MeshDecalData.js`
+- Source: `src/resource/geometry/MeshDecalData.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -41,17 +41,127 @@ Data record mirroring Carbon's per-mesh decal block: an index-buffer allocation
 Data record mirroring Carbon's per-LOD decal range, holding the start index and primitive count for one decal LOD.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/MeshDecalLodData.js`
+- Source: `src/resource/geometry/MeshDecalLodData.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
 <!-- class:Tr2EffectRes -->
 ## `Tr2EffectRes`
 
-Resource record that owns effect/shader payload facts, including the permutation description, while engine packages decide shader-module, pipeline, bind-group, and sampler realization.
+Resource record that owns an effect package, resolves global and local permutation options, hydrates exact portable reflection into canonical shaders, and caches them by body index.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2EffectRes.js`
+- Source: `src/resource/shader/Tr2EffectRes.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2EffectConstant -->
+## `Tr2EffectConstant`
+
+Canonical device-free reflection record for one named constant, including register layout and exact default bytes.
+
+- Export: `@carbonenginejs/runtime-resource/resource/shader`
+- Source: `src/resource/shader/reflection/Tr2EffectConstant.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2EffectDefine -->
+## `Tr2EffectDefine`
+
+Canonical name/value record for one reflected effect define.
+
+- Export: `@carbonenginejs/runtime-resource/resource/shader`
+- Source: `src/resource/shader/reflection/Tr2EffectDefine.js`
+- Visibility: Public
+- Kind: Faithful Carbon port
+
+<!-- class:Tr2EffectDescription -->
+## `Tr2EffectDescription`
+
+Canonical device-free effect body containing techniques, annotations, and library reflection.
+
+- Export: `@carbonenginejs/runtime-resource/resource/shader`
+- Source: `src/resource/shader/reflection/Tr2EffectDescription.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2EffectLibrary -->
+## `Tr2EffectLibrary`
+
+Canonical reflected shader-library record containing source bytes, exported symbols, and derived ray-tracing entry roles.
+
+- Export: `@carbonenginejs/runtime-resource/resource/shader`
+- Source: `src/resource/shader/reflection/Tr2EffectLibrary.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2EffectParameterAnnotation -->
+## `Tr2EffectParameterAnnotation`
+
+Canonical typed parameter annotation that also preserves its exact raw scalar bits.
+
+- Export: `@carbonenginejs/runtime-resource/resource/shader`
+- Source: `src/resource/shader/reflection/Tr2EffectParameterAnnotation.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2EffectResource -->
+## `Tr2EffectResource`
+
+Canonical stage-resource reflection record for textures, buffers, UAVs, and related binding metadata.
+
+- Export: `@carbonenginejs/runtime-resource/resource/shader`
+- Source: `src/resource/shader/reflection/Tr2EffectResource.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2EffectStageInput -->
+## `Tr2EffectStageInput`
+
+Canonical device-free stage record containing source program bytes, constants, resources, samplers, and signatures.
+
+- Export: `@carbonenginejs/runtime-resource/resource/shader`
+- Source: `src/resource/shader/reflection/Tr2EffectStageInput.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2EffectTechnique -->
+## `Tr2EffectTechnique`
+
+Canonical named technique record containing its ordered reflected passes and shader-type mask.
+
+- Export: `@carbonenginejs/runtime-resource/resource/shader`
+- Source: `src/resource/shader/reflection/Tr2EffectTechnique.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2Pass -->
+## `Tr2Pass`
+
+Canonical reflected pass record containing ordered stage inputs and renderer-neutral render-state values.
+
+- Export: `@carbonenginejs/runtime-resource/resource/shader`
+- Source: `src/resource/shader/reflection/Tr2Pass.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2SamplerSetup -->
+## `Tr2SamplerSetup`
+
+Canonical device-free sampler reflection record preserving static/dynamic setup and nullable source names.
+
+- Export: `@carbonenginejs/runtime-resource/resource/shader`
+- Source: `src/resource/shader/sampler/Tr2SamplerSetup.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2Shader -->
+## `Tr2Shader`
+
+Canonical device-free hydrated shader graph and top-level portable-reflection orchestrator.
+
+- Export: `@carbonenginejs/runtime-resource/resource/shader`
+- Source: `src/resource/shader/Tr2Shader.js`
 - Visibility: Public
 - Kind: Adapted Carbon concept
 
@@ -61,7 +171,7 @@ Resource record that owns effect/shader payload facts, including the permutation
 Data record mirroring Carbon's Granny intersection-query result: hit position, normal, UV, bone index, and mesh/area indices with per-field presence flags.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2GrannyIntersectionResult.js`
+- Source: `src/resource/geometry/granny/Tr2GrannyIntersectionResult.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -71,7 +181,7 @@ Data record mirroring Carbon's Granny intersection-query result: hit position, n
 Resource that holds a plain GState payload, which may carry additive skeleton/state data without models, and validates that skeleton data or additive animations are present.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2GrannyStateRes.js`
+- Source: `src/resource/geometry/granny/Tr2GrannyStateRes.js`
 - Visibility: Public
 - Kind: Adapted Carbon concept
 
@@ -81,7 +191,7 @@ Resource that holds a plain GState payload, which may carry additive skeleton/st
 Resource record that holds a validated canonical RGBA image payload and mirrors its width/height metadata, leaving any device texture realization to engine packages.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2ImageRes.js`
+- Source: `src/resource/texture/Tr2ImageRes.js`
 - Visibility: Public
 - Kind: Adapted Carbon concept
 
@@ -91,47 +201,47 @@ Resource record that holds a validated canonical RGBA image payload and mirrors
 Resource that holds a plain light-profile payload, which may be richer than the data retained by the resource or the active engine adapter.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2LightProfileRes.js`
+- Source: `src/resource/Tr2LightProfileRes.js`
 - Visibility: Public
 - Kind: Adapted Carbon concept
 
 <!-- class:Tr2MaterialArea -->
 ## `Tr2MaterialArea`
 
-Persisted data record mirroring Carbon's material-area node, pairing a material parameter-store reference with a metatype string.
+Associates one material-area metatype with its persisted parameter store.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2MaterialArea.js`
+- Source: `src/resource/shader/Tr2MaterialArea.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
 <!-- class:Tr2MaterialMesh -->
 ## `Tr2MaterialMesh`
 
-Persisted data record mirroring Carbon's material-mesh node, holding the dictionary of material areas for one mesh.
+Holds the persisted material-area dictionary for one material mesh.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2MaterialMesh.js`
+- Source: `src/resource/shader/Tr2MaterialMesh.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
 <!-- class:Tr2MaterialRes -->
 ## `Tr2MaterialRes`
 
-Persisted data record mirroring Carbon's material resource root, holding a name and the dictionary of material meshes.
+Root persisted material record containing its authored name and material mesh dictionary.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2MaterialRes.js`
+- Source: `src/resource/shader/Tr2MaterialRes.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
 <!-- class:Tr2ShaderPermutation -->
 ## `Tr2ShaderPermutation`
 
-Data record mirroring Carbon's shader-permutation description: name, option list, default option, description text, and permutation type.
+Describes one authored effect permutation and the option values a shader resolver may select.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2ShaderPermutation.js`
+- Source: `src/resource/shader/Tr2ShaderPermutation.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -141,7 +251,7 @@ Data record mirroring Carbon's shader-permutation description: name, option list
 CPU-side registry of texture resources participating in LOD management that owns deterministic membership and Carbon-shaped memory counters, while device allocation and budget policy stay in engine packages.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2TextureLodManager.js`
+- Source: `src/resource/texture/Tr2TextureLodManager.js`
 - Visibility: Public
 - Kind: Adapted Carbon concept
 
@@ -151,7 +261,7 @@ CPU-side registry of texture resources participating in LOD management that owns
 Data record mirroring Carbon's texture-LOD update request: the frame number, requested mip change, and RAM-cache flag.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2TextureLodUpdateRequest.js`
+- Source: `src/resource/texture/Tr2TextureLodUpdateRequest.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -161,7 +271,7 @@ Data record mirroring Carbon's texture-LOD update request: the frame number, req
 Persisted data record mirroring Carbon's pack-step channel selection: the source channel index, fill value, and source texture path for one output channel.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2TexturePackChannel.js`
+- Source: `src/resource/texture/Tr2TexturePackChannel.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -171,7 +281,7 @@ Persisted data record mirroring Carbon's pack-step channel selection: the source
 Persisted CPU bitmap-transformation pipeline that executes its ordered steps asynchronously to produce a canonical plain RGBA payload and reports the resource paths its load and pack steps depend on.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2TexturePipeline.js`
+- Source: `src/resource/texture/Tr2TexturePipeline.js`
 - Visibility: Public
 - Kind: Adapted Carbon concept
 
@@ -181,7 +291,7 @@ Persisted CPU bitmap-transformation pipeline that executes its ordered steps asy
 Data record mirroring Carbon's texture-pipeline execution parameters, holding the maximum output width and height.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2TexturePipelineParams.js`
+- Source: `src/resource/texture/Tr2TexturePipelineParams.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -191,7 +301,7 @@ Data record mirroring Carbon's texture-pipeline execution parameters, holding th
 Persisted pipeline-step record mirroring Carbon's compress step, naming the target pixel format and per-channel error weights.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2TexturePipelineStepCompress.js`
+- Source: `src/resource/texture/Tr2TexturePipelineStepCompress.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -201,7 +311,7 @@ Persisted pipeline-step record mirroring Carbon's compress step, naming the targ
 Attribute-free persisted marker step mirroring Carbon's mip-generation step; the mip generation itself happens where the pipeline executes.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2TexturePipelineStepGenerateMips.js`
+- Source: `src/resource/texture/Tr2TexturePipelineStepGenerateMips.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -211,7 +321,7 @@ Attribute-free persisted marker step mirroring Carbon's mip-generation step; the
 Persisted pipeline-step record mirroring Carbon's size-limit step, holding the maximum width and height the bitmap may keep.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2TexturePipelineStepLimitSize.js`
+- Source: `src/resource/texture/Tr2TexturePipelineStepLimitSize.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -221,7 +331,7 @@ Persisted pipeline-step record mirroring Carbon's size-limit step, holding the m
 Persisted pipeline-step record mirroring Carbon's load step, holding the source texture path the pipeline reads.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2TexturePipelineStepLoad.js`
+- Source: `src/resource/texture/Tr2TexturePipelineStepLoad.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -231,7 +341,7 @@ Persisted pipeline-step record mirroring Carbon's load step, holding the source
 Persisted pipeline-step record mirroring Carbon's pack step, naming the target pixel format and the four per-channel pack sources.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/Tr2TexturePipelineStepPack.js`
+- Source: `src/resource/texture/Tr2TexturePipelineStepPack.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -241,7 +351,7 @@ Persisted pipeline-step record mirroring Carbon's pack step, naming the target p
 Resource record that owns geometry payload facts (meshes, optional skeletons and animations) and LOD-force metadata, while engine packages decide device buffers, vertex declarations, and draw-time state.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/TriGeometryRes.js`
+- Source: `src/resource/geometry/TriGeometryRes.js`
 - Visibility: Public
 - Kind: Adapted Carbon concept
 
@@ -251,7 +361,7 @@ Resource record that owns geometry payload facts (meshes, optional skeletons and
 Data record mirroring Carbon's geometry area block: a named draw range with bounds, joint bindings, skinning/morph flags, and ray-tracing structure references.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/TriGeometryResAreaData.js`
+- Source: `src/resource/geometry/TriGeometryResAreaData.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -261,7 +371,7 @@ Data record mirroring Carbon's geometry area block: a named draw range with boun
 Data record mirroring Carbon's geometry joint entry: a joint name, parent-joint index, and inverse world transform.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/TriGeometryResJointData.js`
+- Source: `src/resource/geometry/TriGeometryResJointData.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -271,7 +381,7 @@ Data record mirroring Carbon's geometry joint entry: a joint name, parent-joint
 Data record mirroring Carbon's per-LOD geometry block: mesh reference, naming and screen-size selection data, vertex/primitive counts, UV densities, areas, and buffer-allocation references.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/TriGeometryResLodData.js`
+- Source: `src/resource/geometry/TriGeometryResLodData.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -281,7 +391,7 @@ Data record mirroring Carbon's per-LOD geometry block: mesh reference, naming an
 Data record mirroring Carbon's per-mesh geometry block: name, vertex layout facts, bounds, joint bindings, audio geometry, decals, and the LOD list.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/TriGeometryResMeshData.js`
+- Source: `src/resource/geometry/TriGeometryResMeshData.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -291,7 +401,7 @@ Data record mirroring Carbon's per-mesh geometry block: name, vertex layout fact
 Data record mirroring Carbon's geometry skeleton block, pairing a skeleton name with its joint list.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/TriGeometryResSkeletonData.js`
+- Source: `src/resource/geometry/TriGeometryResSkeletonData.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -301,7 +411,7 @@ Data record mirroring Carbon's geometry skeleton block, pairing a skeleton name
 Resource that owns lifecycle identity for decoded Granny data attached as a plain payload with models or meshes, keeping reader and engine-specific behavior outside the class.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/TriGrannyRes.js`
+- Source: `src/resource/geometry/granny/TriGrannyRes.js`
 - Visibility: Public
 - Kind: Adapted Carbon concept
 
@@ -311,7 +421,7 @@ Resource that owns lifecycle identity for decoded Granny data attached as a plai
 Data record mirroring Carbon's joint binding: a joint name with its oriented-bounding-box minimum and maximum.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/TriJointBinding.js`
+- Source: `src/resource/geometry/TriJointBinding.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -321,7 +431,7 @@ Data record mirroring Carbon's joint binding: a joint name with its oriented-bou
 Data record mirroring Carbon's morph-target geometry constants: vertex-buffer stride, position/tangent offsets and types, and vertex count.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/TriMorphTargetGeometryConstants.js`
+- Source: `src/resource/geometry/TriMorphTargetGeometryConstants.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -331,7 +441,7 @@ Data record mirroring Carbon's morph-target geometry constants: vertex-buffer st
 Data record mirroring Carbon's ray-tracing geometry constants: index/vertex buffer ids and strides plus attribute offsets and types.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/TriRtGeometryConstants.js`
+- Source: `src/resource/geometry/TriRtGeometryConstants.js`
 - Visibility: Public
 - Kind: Faithful Carbon port
 
@@ -341,6 +451,6 @@ Data record mirroring Carbon's ray-tracing geometry constants: index/vertex buff
 Resource record that owns Carbon-style texture identity and validated texture, RGBA, or video payload facts with mirrored dimension/format metadata, while engine packages decide what those facts become on a device.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resources/TriTextureRes.js`
+- Source: `src/resource/texture/TriTextureRes.js`
 - Visibility: Public
 - Kind: Adapted Carbon concept

package/docs/reference/classes/texture.md

@@ -1,9 +1,9 @@
 # Texture class catalog
 
 Status: Evolving  
-Scope: `@carbonenginejs/runtime-resource` classes under `src/texture`  
+Scope: `@carbonenginejs/runtime-resource` classes under `src/resource/texture`
 Audience: Users, maintainers, and automated readers  
-Summary: Provides one-sentence purpose descriptors for the texture-array aggregation classes in src/texture.
+Summary: Provides one-sentence purpose descriptors for the texture-array aggregation classes in src/resource/texture.
 
 <!-- class:CjsTextureArrayRes -->
 ## `CjsTextureArrayRes`
@@ -11,16 +11,16 @@ Summary: Provides one-sentence purpose descriptors for the texture-array aggrega
 Mutable runtime aggregate resource for an ordered texture-array request that coalesces per-layer path changes and invalidations so a resource manager or engine scheduler can prepare the corresponding immutable texture-array payload on a later frame.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/texture/CjsTextureArrayRes.js`
+- Source: `src/resource/texture/CjsTextureArrayRes.js`
 - Visibility: Public
 - Kind: Original CarbonEngineJS class
 
-<!-- class:CjsTextureParameterProxy -->
-## `CjsTextureParameterProxy`
+<!-- class:CjsTextureArrayResParameterProxy -->
+## `CjsTextureArrayResParameterProxy`
 
-Texture-parameter facade for one array layer that mirrors the public path API while delegating storage, invalidation, readiness, and adapter ownership to its parent `CjsTextureArrayRes`, carrying no shader metadata or backend objects itself.
+`CjsTextureArrayRes`-owned parameter facade for one array layer that mirrors the public path API while delegating storage, invalidation, readiness, and adapter ownership to its parent, carrying no shader metadata or backend objects itself.
 
 - Export: `@carbonenginejs/runtime-resource`
-- Source: `src/texture/CjsTextureParameterProxy.js`
+- Source: `src/resource/texture/CjsTextureArrayResParameterProxy.js`
 - Visibility: Public
 - Kind: Original CarbonEngineJS class

package/docs/reference/motherlode-cache.md

@@ -40,6 +40,23 @@ ordinary ownership removals preserve the handle's last resource state;
 `PURGED` is reserved for successful policy eviction through inactivity or
 byte pressure.
 
+`PURGED` is not terminal for the handle. Purge deletes the payload, but the
+handle revives itself: `IsGood()` renews activity through `KeepAlive()`, and
+`KeepAlive()` reloads a purged resource along the ordinary first-load path. A
+consumer therefore never learns that a purge happened and never manages
+retention itself - it asks whether the resource is good, and that question is
+what keeps it, or brings it back.
+
+Liveness follows visibility. Something being drawn is asked about every frame
+and stays live; something that stops being drawn stops being renewed, ages out,
+and has its memory reclaimed; when it is drawn again the next `IsGood()`
+restores it. `Reload()` is bounded by `maxReloadAttempts` precisely because the
+render path calls this every frame, so one permanently missing resource cannot
+become a retry storm. A reload refills the exact handle the consumer holds
+rather than resolving whatever the manager currently caches for that path,
+because a consumer holding a purged handle has no way to discover a
+replacement.
+
 `Startup()` and `Shutdown()` are idempotent. `HasKey`, `Lookup`, `Delete`,
 `GetKeys`, `GetValues`, `GetSize`, `SetCacheSize`, `GetCacheSize`, `GetStats`,
 `TrimCache`, `ReplaceExpected`, `Clear`, and `ClearCached` provide the

package/docs/reference/queues.md

@@ -15,7 +15,8 @@ BACKGROUND: deduplicated source load, limited by maxConcurrentLoads
 MAIN:       reader/format conversion -> resource publication
 ```
 
-The main reader/format operation and publication are separate queue items.
+Without worker execution, the main reader/format operation and publication
+are separate queue items.
 `maxPrepareTime` is a per-pump budget in seconds limiting synchronous
 main-queue work started in one pump, and `maxPrepareItemsPerTick` can add an
 item-count limit. Promise-returning format work remains in flight without
@@ -42,6 +43,12 @@ The selected format class owns conversion to the promised CPU output.
 support, and it does not run backend realization. An engine consumes the
 published CPU resource afterward through its own explicit operation.
 
+When worker loading is selected, a declared worker-safe format read runs on
+the module worker rather than occupying a main-queue item. The guarded
+publication item remains on the main queue. `GetPendingWorkers()` and
+`IsLoading()` include unresolved worker requests, and a queued resource
+operation keeps the worker descendant within its `Wait()` lineage.
+
 ## Queue controls
 
 Blue-compatible queue controls are exposed directly on `CjsResMan`:
@@ -98,5 +105,6 @@ registry.
 ## Related documentation
 
 - [Resource lifecycle concepts](../concepts/resource-lifecycle.md)
+- [Browser worker execution](workers.md)
 - [MotherLode identity, cache, and retention](motherlode-cache.md)
 - [Format subpaths](../formats/README.md)

package/docs/reference/workers.md

@@ -0,0 +1,135 @@
+# Browser worker execution
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource`
+Audience: Browser integrators and format maintainers
+Summary: Defines worker-backed source and format execution while keeping resource publication and class-bearing results on the caller thread.
+
+## Enable worker execution
+
+`CjsResMan` selects the bundled module-worker strategy by default and creates
+the worker lazily on the first eligible source or format read:
+
+```js
+import {
+  CjsResManFetchProvider,
+  CjsResMan
+} from "@carbonenginejs/runtime-resource";
+import { CjsWemFormat } from "@carbonenginejs/runtime-resource/formats/wem";
+
+const resMan = new CjsResMan({
+  paths: {
+    res: "https://cdn.example.invalid/resources/"
+  },
+  source: new CjsResManFetchProvider(),
+  formats: [ CjsWemFormat ]
+});
+```
+
+Pass `useWorkerLoading: false` or call `UseWorkerLoading(false)` when a caller
+requires deterministic main-thread execution.
+
+The default worker entry is resolved relative to the published
+`CjsResManWorkerLoader` module. A browser wrapper may instead inject an
+existing Worker-compatible object, a `workerFactory`, or a `workerUrl` through
+the `workerLoader` constructor option:
+
+```js
+const resMan = new CjsResMan({
+  source,
+  workerLoader: {
+    workerFactory: (url, options) => new Worker(url, options)
+  },
+  useWorkerLoading: true
+});
+```
+
+Failure to create the worker leaves unsupported and later operations on the
+main-thread fallback. A fatal worker error rejects requests already assigned
+to that worker, disables it, and leaves future reads able to fall back.
+
+## Source reads
+
+A source opts into worker execution by implementing:
+
+```js
+CreateWorkerRequest(sourcePath, options) {
+  return {
+    operation: "source.fetch",
+    payload,
+    signal,
+    transfer
+  };
+}
+```
+
+Returning `null` selects the main-thread fallback for that read.
+`CjsResMan` resolves the resource path to a URL before invoking a URL-backed
+provider. `CjsResManFetchProvider` implements the worker contract for its
+normal global `fetch` path and returns `ArrayBuffer` data using transfer
+ownership. An injected fetch implementation remains on the caller thread
+unless its provider is explicitly created with `{ worker: true }`.
+Structural sources that do not declare `requiresUrl` continue to receive the
+normalized resource path.
+
+Fetch request options may include ordinary headers, including an HTTP `Range`
+header. Range capability, status interpretation, and the identity of an
+offset-backed logical resource remain provider policy; `CjsResMan` does not
+invent offset semantics.
+
+## Format reads
+
+A clone-safe format opts in with a static worker declaration:
+
+```js
+static worker = Object.freeze({
+  module: import.meta.url,
+  exportName: "CjsExampleFormat"
+});
+```
+
+The worker dynamically imports that exact module and invokes its static
+`readAsync`/`read` operation, falling back to an instance
+`ReadAsync`/`Read` operation when required. BNK and WEM are worker-enabled.
+Black `json` and `payload` outputs are worker-enabled; Black document/runtime
+outputs remain on the caller thread because structured cloning would discard
+their class identity.
+
+A declaration may restrict clone-safe outputs:
+
+```js
+static worker = Object.freeze({
+  module: import.meta.url,
+  exportName: "CjsExampleFormat",
+  outputTypes: Object.freeze([ "json", "payload" ]),
+  defaultOutput: "json"
+});
+```
+
+Format options containing functions, symbols, non-plain instances, cycles, or
+caller-supplied class constructors do not cross the worker boundary.
+
+## Queues and ownership
+
+Worker-safe format reading runs outside the main preparation queue. Its
+resource-operation root remains visible to `Wait()`, and
+`GetPendingWorkers()`/`IsLoading()` include unresolved worker requests. Once
+the reader settles, guarded resource publication is still enqueued on the
+main queue.
+
+Format input is cloned by default. This preserves source-cache and
+multi-output ownership at the cost of a copy. A format may declare
+`transferInput: true` only when its caller guarantees exclusive ownership of a
+complete `ArrayBuffer`; transferring detaches the caller's buffer. Result
+ArrayBuffers and typed-array backing stores are transferred back
+automatically.
+
+The bundled strategy currently owns one module worker. Asynchronous fetches
+may overlap within it, while synchronous CPU readers are serialized by that
+worker's event loop.
+
+## Related documentation
+
+- [Queues, publication, and the Wait fence](queues.md)
+- [MotherLode identity, cache, and retention](motherlode-cache.md)
+- [Wwise BNK/WEM formats](../formats/wwise.md)