@carbonenginejs/runtime-resource 0.12.1 → 0.13.0

package/docs/reference/texture-arrays.md

@@ -1,113 +1,113 @@
-# Texture arrays and update generations
-
-Status: Evolving  
-Scope: `@carbonenginejs/runtime-resource`  
-Audience: Users and integrators  
-Summary: Defines the texture-array proxy surface, the requested/prepared revision boundary, and the adapter commit contract.
-
-## Layer proxies
-
-Texture-array resources expose one ordinary-looking proxy per ordered layer:
-
-```js
-const textureArray = new CjsTextureArrayRes({
-  paths: [
-    "res:/detail1.dds",
-    "res:/detail2.dds",
-    "res:/detail3.dds"
-  ],
-  layerNames: [ "Detail1Map", "Detail2Map", "Detail3Map" ],
-  updateScheduler: resource => frameQueue.add(resource)
-});
-
-const detail2 = textureArray.GetLayerParameter(1);
-detail2.SetValue("res:/replacement.dds");
-
-detail2.textureRes === textureArray; // true
-```
-
-Proxy setters only update their source path and invalidate the parent. The
-parent is scheduled once even if several proxies change in the same frame.
-The next-frame consumer calls `Update()` or `ConsumeUpdateRequest()` to
-obtain one immutable ordered snapshot. Runtime-resource does not know which
-shader metadata caused the aggregate request; shader packages and engine
-adapters map public parameter names to layer indices.
-
-Public effect parameters remain separate from these internal proxies. Their
-authored paths and individual 2D source resources are not replaced by the
-aggregate. An engine-owned, non-persisted bridge mirrors public changes into
-the fixed internal layers.
-
-## Update generations
-
-`CjsTextureArrayRes` is a derived multi-source resource with an explicit
-requested/prepared revision boundary:
-
-```text
-proxy/source change
-    -> requested revision + dirty layer
-    -> one scheduled next-frame snapshot
-    -> consumed/in-flight request
-    -> adapter candidate preparation
-    -> guarded adapter + prepared-revision publication
-```
-
-`ConsumeUpdateRequest()` produces an immutable snapshot and marks that
-revision in flight. A current consumed revision may be completed through
-`CommitPreparedAdapterRevision()`, failed through `FailUpdateRequest()`, or
-returned to the queue through `RetryUpdateRequest()`. Commit-before-consume
-and stale commits are rejected; rejected candidate allocations are destroyed
-by default.
-
-Publication installs the adapter allocation and prepared revision before
-completion events run. The result returns the displaced allocation to the
-adapter owner for post-publication destruction. A reentrant source change may
-therefore request a newer revision without allowing stale completion to
-replace it. The previous prepared allocation and `IsGood()` remain usable
-while a replacement is pending or if replacement preparation fails.
-
-`Ready()` is specialized for this derived resource: it resolves when the
-generation requested at call time has been published, rather than delegating
-to a single-source object loader. Initial preparation failure rejects it.
-
-## Adapter commit example
-
-Consumed snapshots are explicit in-flight generations. An adapter either
-publishes the current candidate atomically, requeues retryable work, or
-records failure:
-
-```js
-const request = textureArray.ConsumeUpdateRequest();
-
-try {
-  const candidate = await adapter.PrepareTextureArray(request);
-  const result = textureArray.CommitPreparedAdapterRevision(
-    request.revision,
-    "webgpu",
-    candidate
-  );
-
-  // A rejected/stale candidate is destroyed by the commit method by default.
-  // The adapter owns disposal of a successfully displaced allocation.
-  result.displaced?.destroy();
-} catch (error) {
-  textureArray.FailUpdateRequest(request.revision, error, { retry: true });
-}
-
-await textureArray.Ready(); // the generation requested at call time
-```
-
-## Sources and topology
-
-Logical paths and resolved sources are independent. `SetLayerResource()`
-attaches a resolved or LOD-specific source without rewriting the logical
-requested path or persistence. `TouchLayer()` invalidates an in-place source
-revision. `HandleAdapterLoss()` drops an unusable adapter allocation and
-schedules a complete topology rebuild. Topology-changing snapshots set
-`topologyChanged: true` and report only valid current layer indices in
-`dirtyLayers`.
-
-## Related documentation
-
-- [Architecture and boundaries](../architecture.md)
-- [Texture CPU pipeline and LOD membership](texture-pipeline.md)
+# Texture arrays and update generations
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource`  
+Audience: Users and integrators  
+Summary: Defines the texture-array proxy surface, the requested/prepared revision boundary, and the adapter commit contract.
+
+## Layer proxies
+
+Texture-array resources expose one ordinary-looking proxy per ordered layer:
+
+```js
+const textureArray = new CjsTextureArrayRes({
+  paths: [
+    "res:/detail1.dds",
+    "res:/detail2.dds",
+    "res:/detail3.dds"
+  ],
+  layerNames: [ "Detail1Map", "Detail2Map", "Detail3Map" ],
+  updateScheduler: resource => frameQueue.add(resource)
+});
+
+const detail2 = textureArray.GetLayerParameter(1);
+detail2.SetValue("res:/replacement.dds");
+
+detail2.textureRes === textureArray; // true
+```
+
+Proxy setters only update their source path and invalidate the parent. The
+parent is scheduled once even if several proxies change in the same frame.
+The next-frame consumer calls `Update()` or `ConsumeUpdateRequest()` to
+obtain one immutable ordered snapshot. Runtime-resource does not know which
+shader metadata caused the aggregate request; shader packages and engine
+adapters map public parameter names to layer indices.
+
+Public effect parameters remain separate from these internal proxies. Their
+authored paths and individual 2D source resources are not replaced by the
+aggregate. An engine-owned, non-persisted bridge mirrors public changes into
+the fixed internal layers.
+
+## Update generations
+
+`CjsTextureArrayRes` is a derived multi-source resource with an explicit
+requested/prepared revision boundary:
+
+```text
+proxy/source change
+    -> requested revision + dirty layer
+    -> one scheduled next-frame snapshot
+    -> consumed/in-flight request
+    -> adapter candidate preparation
+    -> guarded adapter + prepared-revision publication
+```
+
+`ConsumeUpdateRequest()` produces an immutable snapshot and marks that
+revision in flight. A current consumed revision may be completed through
+`CommitPreparedAdapterRevision()`, failed through `FailUpdateRequest()`, or
+returned to the queue through `RetryUpdateRequest()`. Commit-before-consume
+and stale commits are rejected; rejected candidate allocations are destroyed
+by default.
+
+Publication installs the adapter allocation and prepared revision before
+completion events run. The result returns the displaced allocation to the
+adapter owner for post-publication destruction. A reentrant source change may
+therefore request a newer revision without allowing stale completion to
+replace it. The previous prepared allocation and `IsGood()` remain usable
+while a replacement is pending or if replacement preparation fails.
+
+`Ready()` is specialized for this derived resource: it resolves when the
+generation requested at call time has been published, rather than delegating
+to a single-source object loader. Initial preparation failure rejects it.
+
+## Adapter commit example
+
+Consumed snapshots are explicit in-flight generations. An adapter either
+publishes the current candidate atomically, requeues retryable work, or
+records failure:
+
+```js
+const request = textureArray.ConsumeUpdateRequest();
+
+try {
+  const candidate = await adapter.PrepareTextureArray(request);
+  const result = textureArray.CommitPreparedAdapterRevision(
+    request.revision,
+    "webgpu",
+    candidate
+  );
+
+  // A rejected/stale candidate is destroyed by the commit method by default.
+  // The adapter owns disposal of a successfully displaced allocation.
+  result.displaced?.destroy();
+} catch (error) {
+  textureArray.FailUpdateRequest(request.revision, error, { retry: true });
+}
+
+await textureArray.Ready(); // the generation requested at call time
+```
+
+## Sources and topology
+
+Logical paths and resolved sources are independent. `SetLayerResource()`
+attaches a resolved or LOD-specific source without rewriting the logical
+requested path or persistence. `TouchLayer()` invalidates an in-place source
+revision. `HandleAdapterLoss()` drops an unusable adapter allocation and
+schedules a complete topology rebuild. Topology-changing snapshots set
+`topologyChanged: true` and report only valid current layer indices in
+`dirtyLayers`.
+
+## Related documentation
+
+- [Architecture and boundaries](../architecture.md)
+- [Texture CPU pipeline and LOD membership](texture-pipeline.md)

package/docs/reference/texture-pipeline.md

@@ -1,53 +1,53 @@
-# Texture CPU pipeline and LOD membership
-
-Status: Evolving  
-Scope: `@carbonenginejs/runtime-resource`  
-Audience: Users and integrators  
-Summary: Defines the `Tr2TexturePipeline` CPU-only step contract and `Tr2TextureLodManager` membership ownership.
-
-## Tr2TexturePipeline
-
-`Tr2TexturePipeline` is the Carbon texture-specific CPU bitmap pipeline, not a
-general resource prepare stage. `GetResourceDependencies()` returns the sorted
-unique paths required by load and channel-pack steps. `Execute()` resolves
-those inputs from an explicit `inputs` map/object, an async `load(path)`
-callback, or an injected `CjsResMan`, then returns a canonical plain
-`rgba8unorm` payload:
-
-```js
-import {
-  Tr2TexturePipeline,
-  Tr2TexturePipelineStepLoad,
-  Tr2TexturePipelineStepLimitSize
-} from "@carbonenginejs/runtime-resource";
-
-const load = new Tr2TexturePipelineStepLoad();
-load.path = "res:/texture/source.png";
-const limit = new Tr2TexturePipelineStepLimitSize();
-limit.maxWidth = 512;
-
-const pipeline = new Tr2TexturePipeline();
-pipeline.steps = [ load, limit ];
-const rgba = await pipeline.Execute(0, 0, { resMan });
-```
-
-The maintained runtime path currently accepts canonical `rgba8unorm` inputs.
-Load copies the source bitmap, limit-size repeatedly performs a 2x2 CPU
-downsample, pack builds logical RGBA channels from independent inputs, and
-Carbon's present compress step remains validation-only because the native
-method is itself a no-op. Unsupported step types fail explicitly.
-
-For the decoded-DDS fallback contract used by 2D texture inputs, see the
-[DDS notes in the format map](../formats/README.md#dds-decoded-fallback).
-
-## Tr2TextureLodManager
-
-`Tr2TextureLodManager` owns only ordered resource membership through
-`RegisterTexture()`, `UnregisterTexture()`, and `GetManagedTextures()`.
-Engine packages continue to own GPU allocations, upload accounting, device
-budgets, capability limits, and device-loss recovery.
-
-## Related documentation
-
-- [Texture arrays and update generations](texture-arrays.md)
-- [Format subpaths](../formats/README.md)
+# Texture CPU pipeline and LOD membership
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource`  
+Audience: Users and integrators  
+Summary: Defines the `Tr2TexturePipeline` CPU-only step contract and `Tr2TextureLodManager` membership ownership.
+
+## Tr2TexturePipeline
+
+`Tr2TexturePipeline` is the Carbon texture-specific CPU bitmap pipeline, not a
+general resource prepare stage. `GetResourceDependencies()` returns the sorted
+unique paths required by load and channel-pack steps. `Execute()` resolves
+those inputs from an explicit `inputs` map/object, an async `load(path)`
+callback, or an injected `CjsResMan`, then returns a canonical plain
+`rgba8unorm` payload:
+
+```js
+import {
+  Tr2TexturePipeline,
+  Tr2TexturePipelineStepLoad,
+  Tr2TexturePipelineStepLimitSize
+} from "@carbonenginejs/runtime-resource";
+
+const load = new Tr2TexturePipelineStepLoad();
+load.path = "res:/texture/source.png";
+const limit = new Tr2TexturePipelineStepLimitSize();
+limit.maxWidth = 512;
+
+const pipeline = new Tr2TexturePipeline();
+pipeline.steps = [ load, limit ];
+const rgba = await pipeline.Execute(0, 0, { resMan });
+```
+
+The maintained runtime path currently accepts canonical `rgba8unorm` inputs.
+Load copies the source bitmap, limit-size repeatedly performs a 2x2 CPU
+downsample, pack builds logical RGBA channels from independent inputs, and
+Carbon's present compress step remains validation-only because the native
+method is itself a no-op. Unsupported step types fail explicitly.
+
+For the decoded-DDS fallback contract used by 2D texture inputs, see the
+[DDS notes in the format map](../formats/README.md#dds-decoded-fallback).
+
+## Tr2TextureLodManager
+
+`Tr2TextureLodManager` owns only ordered resource membership through
+`RegisterTexture()`, `UnregisterTexture()`, and `GetManagedTextures()`.
+Engine packages continue to own GPU allocations, upload accounting, device
+budgets, capability limits, and device-loss recovery.
+
+## Related documentation
+
+- [Texture arrays and update generations](texture-arrays.md)
+- [Format subpaths](../formats/README.md)

package/docs/reference/workers.md

@@ -1,135 +1,142 @@
-# 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 = {
-  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 = {
-  module: import.meta.url,
-  exportName: "CjsExampleFormat",
-  outputTypes: [ "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)
+# 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 = {
+  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.
+
+Resource-backed format methods receive `(input, options, context)`. The
+clone-safe context crosses the worker boundary with its normalized lowercase
+`resFilePath`, `ext`, and `fileName`, its compatible `path` alias, and the
+exact translated `url` used by a URL-backed source (or `null` for structural
+sources). Direct descriptor reads that are not attached to a resource receive
+`null` for the third argument.
+
+A declaration may restrict clone-safe outputs:
+
+```js
+static worker = {
+  module: import.meta.url,
+  exportName: "CjsExampleFormat",
+  outputTypes: [ "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)