@carbonenginejs/runtime-resource 0.12.2 → 0.13.0

package/docs/reference/queues.md

@@ -1,110 +1,194 @@
-# Queues, publication, and the Wait fence
-
-Status: Evolving  
-Scope: `@carbonenginejs/runtime-resource`  
-Audience: Users and integrators  
-Summary: Defines the two manager-owned queues, publication budgeting, registration, and the `Wait()` fence semantics.
-
-## Queued CPU load and publication
-
-`GetObject()`, `LoadObject()`, and resource `Ready()` use two manager-owned
-queues:
-
-```text
-BACKGROUND: deduplicated source load, limited by maxConcurrentLoads
-MAIN:       reader/format conversion -> resource publication
-```
-
-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
-blocking the JavaScript event loop. The default scheduler keeps promise-based
-calls working; a `CjsLibrary` or direct caller can provide its frame
-scheduler:
-
-```js
-const resMan = new CjsResMan({
-  source,
-  maxConcurrentLoads: 8,
-  maxPrepareTime: 0.005,
-  queueScheduler: callback => requestAnimationFrame(callback)
-});
-
-await resMan.FetchResource("res:/model/ship.gr2", {
-  requirement: "geometry",
-  emit: "cmf"
-});
-```
-
-The selected format class owns conversion to the promised CPU output.
-`CjsResMan` does not inspect WebGL, WebGPU, texture, geometry, or codec
-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`:
-`AddToQueue`, `CancelFromQueue`, `GetNextIdForQueue`, `PumpMainThreadQueue`,
-`PauseQueue`, `ResumeQueue`, `GetPendingLoads`, and `GetPendingPrepares`.
-`Update()`/`Tick()` pump work.
-
-## The Wait fence
-
-`Wait()` synchronously captures queued resource-operation roots and low-level
-queue tasks that already exist when it is called. Captured resource roots
-include publication work enqueued after an asynchronous read; unrelated later
-roots/tasks do not postpone the fence. Failure and queued cancellation count
-as settlement, remain observable through their original operation promises,
-and cross the fence without making `Wait()` reject.
-
-By default `Wait()` pumps the two queues directly within their ordinary
-budgets and never runs automatic purge housekeeping. It preserves pause
-state; `{ pump: false }` leaves all progress to an external driver. A
-standalone canonical `PrepareResourceObjectQueued()` call is a queued root.
-Direct `LoadResourceObject()`, direct `PrepareResourceObject()`, standalone
-`ReadResource()`, and standalone `ReadFormatOnce()` calls bypass both queues
-and are outside this fence unless they own a captured queue task, although
-direct resource mutations are still tracked for safe MotherLode replacement.
-`WaitUrgent()` remains deferred until the queue has real per-item priority
-and urgent-membership semantics.
-
-## Registration
-
-Format classes own input extensions. Resource classes are registered by a
-semantic requirement, never by file extension:
-
-```js
-const resMan = new CjsResMan().Register({
-  source,
-  formats: [ CjsDdsFormat, CjsPngFormat ],
-  resourceTypes: [ TriTextureRes, Tr2ImageRes ]
-});
-
-const texture = resMan.GetResource("res:/image/ship.png", {
-  requirement: "texture",
-  emit: "image"
-});
-const image = resMan.GetResource("res:/image/ship.png", {
-  requirement: "image",
-  emit: "image"
-});
-```
-
-Those are distinct resource identities but share the normalized source-byte
-operation. The manager does not expose an extension-to-resource compatibility
-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)
+# Queues, publication, and the Wait fence
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource`  
+Audience: Users and integrators  
+Summary: Defines the two manager-owned queues, publication budgeting, registration, and the `Wait()` fence semantics.
+
+## Queued CPU load and publication
+
+`GetObject()`, `LoadObject()`, and resource `Ready()` use two manager-owned
+queues:
+
+```text
+BACKGROUND: deduplicated source load, limited by maxConcurrentLoads
+MAIN:       reader/format conversion -> resource publication
+```
+
+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
+blocking the JavaScript event loop. The default scheduler keeps promise-based
+calls working; a `CjsLibrary` or direct caller can provide its frame
+scheduler:
+
+```js
+const resMan = new CjsResMan({
+  source,
+  maxConcurrentLoads: 8,
+  maxPrepareTime: 0.005,
+  queueScheduler: callback => requestAnimationFrame(callback)
+});
+
+await resMan.FetchResource("res:/model/ship.gr2", {
+  requirement: "geometry",
+  emit: "cmf"
+});
+```
+
+The selected format class owns conversion to the promised CPU output.
+`CjsResMan` does not inspect WebGL, WebGPU, texture, geometry, or codec
+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`:
+`AddToQueue`, `CancelFromQueue`, `GetNextIdForQueue`, `PumpMainThreadQueue`,
+`PauseQueue`, `ResumeQueue`, `GetPendingLoads`, and `GetPendingPrepares`.
+`Update()`/`Tick()` pump work.
+
+## The Wait fence
+
+`Wait()` synchronously captures queued resource-operation roots and low-level
+queue tasks that already exist when it is called. Captured resource roots
+include publication work enqueued after an asynchronous read; unrelated later
+roots/tasks do not postpone the fence. Failure and queued cancellation count
+as settlement, remain observable through their original operation promises,
+and cross the fence without making `Wait()` reject.
+
+By default `Wait()` pumps the two queues directly within their ordinary
+budgets and never runs automatic purge housekeeping. It preserves pause
+state; `{ pump: false }` leaves all progress to an external driver. A
+standalone canonical `PrepareResourceObjectQueued()` call is a queued root.
+Direct `LoadResourceObject()`, direct `PrepareResourceObject()`, standalone
+`ReadResource()`, and standalone `ReadFormatOnce()` calls bypass both queues
+and are outside this fence unless they own a captured queue task, although
+direct resource mutations are still tracked for safe MotherLode replacement.
+`WaitUrgent()` remains deferred until the queue has real per-item priority
+and urgent-membership semantics.
+
+## Registration
+
+The Carbon-shaped primary route binds an extension to a resource-compatible
+handler and a format. The handler declares whether the public result is a
+stable resource or a constructed object:
+
+```js
+import {
+  CjsLoadingObject,
+  CjsResMan
+} from "@carbonenginejs/runtime-resource";
+import { CjsBlackFormat } from "@carbonenginejs/runtime-resource/formats/black";
+import { CjsRedFormat } from "@carbonenginejs/runtime-resource/formats/red";
+
+const resMan = new CjsResMan({ source });
+
+resMan.RegisterExtension(".red", CjsLoadingObject, [
+  CjsBlackFormat,
+  CjsRedFormat
+]);
+resMan.RegisterExtension(".black", CjsLoadingObject, [
+  CjsBlackFormat,
+  CjsRedFormat
+]);
+```
+
+Ordered arrays apply request output/media filters first, then evaluate support
+probes in order. The first supported format wins. One format without a probe
+may be the final fallback; it cannot precede another entry. After selection,
+reader failure is final and does not advance to the fallback. Both `.red` and
+`.black` therefore use Black magic first and Red/YAML otherwise, independent
+of the suffix.
+
+A fixed `Target` may hydrate parsed values through its static `from` or
+`fromYAML` method. `Identify(values, context)` may instead return a target
+constructor, `true` to accept the reader result unchanged, or false/null to
+fail. `Target` and `Identify` are mutually exclusive and only valid for object
+handlers. These functions remain on the main thread even when the selected
+format is worker-safe.
+
+The normalized context supplied to formats as the third
+`read(input, options, context)` argument, direct object loaders, `Identify`,
+and `fromYAML` contains the same resource identity fields:
+
+- `ext`: normalized lowercase extension without a leading dot;
+- `resFilePath`: normalized lowercase logical resource path;
+- `fileName`: normalized lowercase final path component; and
+- `url`: the exact translated URL used by a URL-backed source, or `null` for
+  sources that read logical resource paths directly.
+
+`path` remains a compatibility alias for `resFilePath`. URL text is not
+lowercased independently: paths translated from `res:/` already use the
+normalized resource path, while configured URL-base or resolver casing is
+preserved.
+
+The single-format short form:
+
+```js
+import { TriTextureRes } from "@carbonenginejs/runtime-resource/resource/texture";
+import { CjsDdsFormat } from "@carbonenginejs/runtime-resource/formats/dds";
+
+resMan.RegisterExtension("dds", TriTextureRes, CjsDdsFormat);
+```
+
+is equivalent to:
+
+```js
+resMan.RegisterExtension("dds", TriTextureRes, {
+  Format: CjsDdsFormat
+});
+```
+
+`Register({ extensions })` accepts the same route objects keyed by extension.
+Re-registration replaces the route for future uncached handles; an existing
+canonical handle retains the complete route it captured.
+
+The older registries remain independent compatibility and specialization
+seams. `RegisterFormat` adds a format under its self-declared input extensions.
+`RegisterResourceType` selects a resource class from a semantic requirement or
+payload and takes precedence over the extension handler:
+
+```js
+import { CjsResMan } from "@carbonenginejs/runtime-resource";
+import {
+  Tr2ImageRes,
+  TriTextureRes
+} from "@carbonenginejs/runtime-resource/resource/texture";
+import { CjsDdsFormat } from "@carbonenginejs/runtime-resource/formats/dds";
+import { CjsPngFormat } from "@carbonenginejs/runtime-resource/formats/png";
+
+const resMan = new CjsResMan().Register({
+  source,
+  formats: [ CjsDdsFormat, CjsPngFormat ],
+  resourceTypes: [ TriTextureRes, Tr2ImageRes ]
+});
+
+const texture = resMan.GetResource("res:/image/ship.png", {
+  requirement: "texture",
+  emit: "image"
+});
+const image = resMan.GetResource("res:/image/ship.png", {
+  requirement: "image",
+  emit: "image"
+});
+```
+
+Those are distinct resource identities but share the normalized source-byte
+operation. `RegisterObjectLoader` remains the direct legacy byte-to-value
+registration for an extension without an explicit route.
+
+## 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/reload.md

@@ -1,107 +1,107 @@
-# Candidate-first atomic reload
-
-Status: Evolving  
-Scope: `@carbonenginejs/runtime-resource`  
-Audience: Users and integrators  
-Summary: Defines the reload contract that keeps the last published good handle canonical until a distinct candidate has fully succeeded.
-
-## Contract
-
-Reload is candidate-first. When an owner already exists,
-`GetResource(path, { reload: true })` constructs and initializes a distinct
-off-registry candidate without changing ordinary lookup. Calling `Ready()` on
-that candidate, using `GetObject()` / `FetchResource()` with `reload: true`,
-or calling the explicit `ReloadObject()` / `ReloadResource()` helpers starts
-one shared candidate operation that runs the same queued contract:
-
-1. purge-lock the exact former owner and invalidate reusable reads once;
-2. read, convert through the selected format, and publish payload state only
-   on the detached candidate;
-3. require the newest per-key reload token and exact former ownership;
-4. compare-and-swap the fully loaded CPU candidate into MotherLode;
-5. invalidate and clean the displaced handle after the lookup switch.
-
-The manager captures the exact MotherLode, key, former handle, former
-ownership generation, and a newest-request token. Reader, prepare, and
-publication stages mutate only the detached candidate and validate candidate
-authority before and after asynchronous boundaries. A fully loaded CPU
-candidate commits through `CjsMotherLode.ReplaceExpected()` only if the exact
-former owner and newest token still match. The final authority callback and
-exact-record check run immediately before the synchronous map switch, with no
-user cleanup or `await` between the comparison and publication.
-
-After the switch, the displaced ownership generation is invalidated, the
-candidate receives ordinary lifecycle/reconstruction callbacks, and the former
-handle is cleaned exactly once. Existing JavaScript references are not
-retargeted; they keep the displaced handle, while fresh lookup sees the
-committed candidate.
-
-## Failure behavior
-
-Source, format, or publication failure leaves the former handle, state,
-payload, and adapters canonical; the failed candidate's attached payload and
-adapters are cleaned and its original error is retained. An otherwise-
-successful candidate that was superseded, deleted, cleared, or replaced
-rejects with `CJS_RESMAN_STALE_RELOAD_CANDIDATE` and cannot resurrect the
-key. Constructors that return the former singleton are rejected before
-`Initialize()` can mutate it because staging requires a distinct handle.
-
-Failed freshness attempts still invalidate reusable source/format records
-when their work begins; the already-published canonical payload is not
-dependent on those records.
-
-Cleanup errors have explicit sides. Candidate cleanup failure aggregates with
-the original preparation/stale error as
-`CJS_RESMAN_RELOAD_CANDIDATE_CLEANUP_FAILED` while the former owner remains
-canonical. A displaced-owner cleanup failure occurs after publication and
-rejects as `CJS_MOTHERLODE_REPLACE_CLEANUP_FAILED`, whose result explicitly
-reports `committed: true`; the already-good candidate remains canonical.
-
-## Read-cache interaction
-
-`reload: true` synchronously detaches every queued/source/format read record
-for the selected source/path before fresh work starts. Existing consumers
-keep their detached promises; reload does not abort them. Fresh success
-repopulates only caches explicitly requested with `cacheSource: true` or
-`cacheFormat: true`. `InvalidateReadCache(path, { source, sourceRevision })`
-provides the same no-abort invalidation explicitly; omitting
-`sourceRevision` removes all revisions for that source/path. `Delete()`
-remains canonical resource-identity-only, while `Clear()` resets all read
-ledgers. A failed reload preserves the former payload but does not restore
-reusable read-cache entries detached by its explicit freshness request.
-
-## Publication authority and staleness
-
-Every queued, direct, standalone, and candidate resource preparation captures
-an immutable publication authority: the exact MotherLode, canonical key,
-resource handle, and a manager-local ownership generation. The manager
-validates that authority before and after state changes, asynchronous
-reader/format work, and publication. Delete, Clear, successful reload commit,
-or exact-handle reinsertion therefore makes older work reject with
-`CJS_RESMAN_STALE_RESOURCE_OPERATION` before it can enter another state or
-publish. If stale work independently rejects, its original source/format
-error is preserved and `SetError()` is suppressed on the detached handle.
-
-Candidate work is a normal `Wait()` root and blocks synchronous MotherLode
-replacement while active. `Register({ motherLode })` rejects with
-`CJS_RESMAN_ACTIVE_RESOURCE_OPERATIONS` while queued or direct mutations are
-active, including a reload candidate. Normal `Wait()` drains queued roots and
-candidate lineages; a direct caller must await its own load/prepare promise
-before retrying replacement. Canonical and candidate authority prevent late
-publication, but started source or format work is not yet aborted;
-deterministic cleanup applies to the staged candidate resource itself.
-
-## Divergence from Carbon
-
-This availability contract intentionally differs from Carbon.
-`BlueAsyncRes::Reload` cancels/joins work, releases dependent cached data, and
-reloads the same canonical object in place; failure can therefore leave that
-stable handle bad. Carbon MotherLode replacement also switches immediately and
-has no prepare-success gate or rollback. Runtime-resource instead preserves
-the last published good handle until a distinct candidate has succeeded, and
-never silently retargets existing JavaScript references.
-
-## Related documentation
-
-- [MotherLode identity, cache, and retention](motherlode-cache.md)
-- [Queues and the Wait fence](queues.md)
+# Candidate-first atomic reload
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource`  
+Audience: Users and integrators  
+Summary: Defines the reload contract that keeps the last published good handle canonical until a distinct candidate has fully succeeded.
+
+## Contract
+
+Reload is candidate-first. When an owner already exists,
+`GetResource(path, { reload: true })` constructs and initializes a distinct
+off-registry candidate without changing ordinary lookup. Calling `Ready()` on
+that candidate, using `GetObject()` / `FetchResource()` with `reload: true`,
+or calling the explicit `ReloadObject()` / `ReloadResource()` helpers starts
+one shared candidate operation that runs the same queued contract:
+
+1. purge-lock the exact former owner and invalidate reusable reads once;
+2. read, convert through the selected format, and publish payload state only
+   on the detached candidate;
+3. require the newest per-key reload token and exact former ownership;
+4. compare-and-swap the fully loaded CPU candidate into MotherLode;
+5. invalidate and clean the displaced handle after the lookup switch.
+
+The manager captures the exact MotherLode, key, former handle, former
+ownership generation, and a newest-request token. Reader, prepare, and
+publication stages mutate only the detached candidate and validate candidate
+authority before and after asynchronous boundaries. A fully loaded CPU
+candidate commits through `CjsMotherLode.ReplaceExpected()` only if the exact
+former owner and newest token still match. The final authority callback and
+exact-record check run immediately before the synchronous map switch, with no
+user cleanup or `await` between the comparison and publication.
+
+After the switch, the displaced ownership generation is invalidated, the
+candidate receives ordinary lifecycle/reconstruction callbacks, and the former
+handle is cleaned exactly once. Existing JavaScript references are not
+retargeted; they keep the displaced handle, while fresh lookup sees the
+committed candidate.
+
+## Failure behavior
+
+Source, format, or publication failure leaves the former handle, state,
+payload, and adapters canonical; the failed candidate's attached payload and
+adapters are cleaned and its original error is retained. An otherwise-
+successful candidate that was superseded, deleted, cleared, or replaced
+rejects with `CJS_RESMAN_STALE_RELOAD_CANDIDATE` and cannot resurrect the
+key. Constructors that return the former singleton are rejected before
+`Initialize()` can mutate it because staging requires a distinct handle.
+
+Failed freshness attempts still invalidate reusable source/format records
+when their work begins; the already-published canonical payload is not
+dependent on those records.
+
+Cleanup errors have explicit sides. Candidate cleanup failure aggregates with
+the original preparation/stale error as
+`CJS_RESMAN_RELOAD_CANDIDATE_CLEANUP_FAILED` while the former owner remains
+canonical. A displaced-owner cleanup failure occurs after publication and
+rejects as `CJS_MOTHERLODE_REPLACE_CLEANUP_FAILED`, whose result explicitly
+reports `committed: true`; the already-good candidate remains canonical.
+
+## Read-cache interaction
+
+`reload: true` synchronously detaches every queued/source/format read record
+for the selected source/path before fresh work starts. Existing consumers
+keep their detached promises; reload does not abort them. Fresh success
+repopulates only caches explicitly requested with `cacheSource: true` or
+`cacheFormat: true`. `InvalidateReadCache(path, { source, sourceRevision })`
+provides the same no-abort invalidation explicitly; omitting
+`sourceRevision` removes all revisions for that source/path. `Delete()`
+remains canonical resource-identity-only, while `Clear()` resets all read
+ledgers. A failed reload preserves the former payload but does not restore
+reusable read-cache entries detached by its explicit freshness request.
+
+## Publication authority and staleness
+
+Every queued, direct, standalone, and candidate resource preparation captures
+an immutable publication authority: the exact MotherLode, canonical key,
+resource handle, and a manager-local ownership generation. The manager
+validates that authority before and after state changes, asynchronous
+reader/format work, and publication. Delete, Clear, successful reload commit,
+or exact-handle reinsertion therefore makes older work reject with
+`CJS_RESMAN_STALE_RESOURCE_OPERATION` before it can enter another state or
+publish. If stale work independently rejects, its original source/format
+error is preserved and `SetError()` is suppressed on the detached handle.
+
+Candidate work is a normal `Wait()` root and blocks synchronous MotherLode
+replacement while active. `Register({ motherLode })` rejects with
+`CJS_RESMAN_ACTIVE_RESOURCE_OPERATIONS` while queued or direct mutations are
+active, including a reload candidate. Normal `Wait()` drains queued roots and
+candidate lineages; a direct caller must await its own load/prepare promise
+before retrying replacement. Canonical and candidate authority prevent late
+publication, but started source or format work is not yet aborted;
+deterministic cleanup applies to the staged candidate resource itself.
+
+## Divergence from Carbon
+
+This availability contract intentionally differs from Carbon.
+`BlueAsyncRes::Reload` cancels/joins work, releases dependent cached data, and
+reloads the same canonical object in place; failure can therefore leave that
+stable handle bad. Carbon MotherLode replacement also switches immediately and
+has no prepare-success gate or rollback. Runtime-resource instead preserves
+the last published good handle until a distinct candidate has succeeded, and
+never silently retargets existing JavaScript references.
+
+## Related documentation
+
+- [MotherLode identity, cache, and retention](motherlode-cache.md)
+- [Queues and the Wait fence](queues.md)