@carbonenginejs/runtime-resource 0.8.0 → 0.9.0

package/dist/texture/CjsTextureParameterProxy.js

@@ -1,133 +1,133 @@
-import { CjsEventEmitter } from '@carbonenginejs/core-types/model';
-
-/**
- * Runtime-only internal texture parameter facade for one array layer.
- *
- * The proxy mirrors the public texture-parameter path API while delegating
- * storage, invalidation, readiness, and adapter ownership to its parent array.
- * Engines bridge public parameters into it; it does not replace persisted
- * parameter entries or their individual source resources. It deliberately
- * carries no shader metadata or backend objects.
- */
-class CjsTextureParameterProxy extends CjsEventEmitter {
-  #parent;
-  #layer;
-  #name;
-  constructor(parent, layer, options = {}) {
-    super();
-    if (!parent || typeof parent.SetLayerResourcePath !== "function") {
-      throw new TypeError("CjsTextureParameterProxy requires a CjsTextureArrayRes-compatible parent.");
-    }
-    if (!Number.isInteger(layer) || layer < 0) {
-      throw new RangeError("CjsTextureParameterProxy layer must be a non-negative integer.");
-    }
-    this.#parent = parent;
-    this.#layer = layer;
-    this.#name = options.name === undefined ? "" : String(options.name);
-  }
-  get resourcePath() {
-    return this.GetResourcePath();
-  }
-
-  /** The aggregate texture resource used by the shader. */
-  get textureRes() {
-    return this.#parent;
-  }
-
-  /** Compatibility alias for textureRes. */
-  get res() {
-    return this.#parent;
-  }
-
-  /** Compatibility alias used by Carbon-shaped texture parameters. */
-  get resource() {
-    return this.#parent;
-  }
-  set resourcePath(value) {
-    this.SetResourcePath(value);
-  }
-  get name() {
-    return this.#name;
-  }
-  set name(value) {
-    this.SetParameterName(value);
-  }
-  GetParent() {
-    return this.#parent;
-  }
-  GetLayerIndex() {
-    return this.#layer;
-  }
-  GetParameterName() {
-    return this.#name;
-  }
-  SetParameterName(value) {
-    const next = value === null || value === undefined ? "" : String(value);
-    if (next === this.#name) return false;
-    const previous = this.#name;
-    this.#name = next;
-    this.EmitEvent("changed", this, "name", next, previous);
-    return true;
-  }
-  GetResourcePath() {
-    return this.#parent.GetLayerResourcePath(this.#layer);
-  }
-  SetResourcePath(value) {
-    const previous = this.GetResourcePath();
-    if (!this.#parent.SetLayerResourcePath(this.#layer, value)) return false;
-    this.EmitEvent("changed", this, "resourcepath", this.GetResourcePath(), previous);
-    return true;
-  }
-  GetValue() {
-    return this.GetResourcePath();
-  }
-  SetValue(value) {
-    if (value === undefined) return false;
-    return this.SetResourcePath(value);
-  }
-  EqualsValue(value) {
-    return String(value ?? "").trim().replace(/\\/gu, "/").replace(/\/+/gu, "/").toLowerCase() === this.GetResourcePath();
-  }
-
-  /** Return the aggregate texture resource used by the shader binding. */
-  GetResource() {
-    return this.#parent;
-  }
-
-  /** Return the optional resolved source resource for this layer. */
-  GetSourceResource() {
-    return this.#parent.GetLayerResource(this.#layer);
-  }
-  SetSourceResource(resource) {
-    const previous = this.GetSourceResource();
-    if (!this.#parent.SetLayerResource(this.#layer, resource)) return false;
-    this.EmitEvent("changed", this, "sourceresource", this.GetSourceResource(), previous);
-    return true;
-  }
-  SetResource(resource) {
-    return this.SetSourceResource(resource);
-  }
-
-  /** Invalidate this layer after an in-place source content revision. */
-  Touch() {
-    this.#parent.TouchLayer(this.#layer);
-    this.EmitEvent("changed", this, "sourcerevision", this.GetSourceResource());
-    return this;
-  }
-  GetResources(out = []) {
-    if (!out.includes(this.#parent)) out.push(this.#parent);
-    return out;
-  }
-  IsPrepared() {
-    return this.#parent.IsPrepared();
-  }
-  IsGood() {
-    return this.#parent.IsGood();
-  }
-  Ready(options = {}) {
-    return this.#parent.Ready(options);
-  }
-}
-
-export { CjsTextureParameterProxy };
-//# sourceMappingURL=CjsTextureParameterProxy.js.map
+import { CjsEventEmitter } from '@carbonenginejs/core-types/model';
+
+/**
+ * Runtime-only internal texture parameter facade for one array layer.
+ *
+ * The proxy mirrors the public texture-parameter path API while delegating
+ * storage, invalidation, readiness, and adapter ownership to its parent array.
+ * Engines bridge public parameters into it; it does not replace persisted
+ * parameter entries or their individual source resources. It deliberately
+ * carries no shader metadata or backend objects.
+ */
+class CjsTextureParameterProxy extends CjsEventEmitter {
+  #parent;
+  #layer;
+  #name;
+  constructor(parent, layer, options = {}) {
+    super();
+    if (!parent || typeof parent.SetLayerResourcePath !== "function") {
+      throw new TypeError("CjsTextureParameterProxy requires a CjsTextureArrayRes-compatible parent.");
+    }
+    if (!Number.isInteger(layer) || layer < 0) {
+      throw new RangeError("CjsTextureParameterProxy layer must be a non-negative integer.");
+    }
+    this.#parent = parent;
+    this.#layer = layer;
+    this.#name = options.name === undefined ? "" : String(options.name);
+  }
+  get resourcePath() {
+    return this.GetResourcePath();
+  }
+
+  /** The aggregate texture resource used by the shader. */
+  get textureRes() {
+    return this.#parent;
+  }
+
+  /** Compatibility alias for textureRes. */
+  get res() {
+    return this.#parent;
+  }
+
+  /** Compatibility alias used by Carbon-shaped texture parameters. */
+  get resource() {
+    return this.#parent;
+  }
+  set resourcePath(value) {
+    this.SetResourcePath(value);
+  }
+  get name() {
+    return this.#name;
+  }
+  set name(value) {
+    this.SetParameterName(value);
+  }
+  GetParent() {
+    return this.#parent;
+  }
+  GetLayerIndex() {
+    return this.#layer;
+  }
+  GetParameterName() {
+    return this.#name;
+  }
+  SetParameterName(value) {
+    const next = value === null || value === undefined ? "" : String(value);
+    if (next === this.#name) return false;
+    const previous = this.#name;
+    this.#name = next;
+    this.EmitEvent("changed", this, "name", next, previous);
+    return true;
+  }
+  GetResourcePath() {
+    return this.#parent.GetLayerResourcePath(this.#layer);
+  }
+  SetResourcePath(value) {
+    const previous = this.GetResourcePath();
+    if (!this.#parent.SetLayerResourcePath(this.#layer, value)) return false;
+    this.EmitEvent("changed", this, "resourcepath", this.GetResourcePath(), previous);
+    return true;
+  }
+  GetValue() {
+    return this.GetResourcePath();
+  }
+  SetValue(value) {
+    if (value === undefined) return false;
+    return this.SetResourcePath(value);
+  }
+  EqualsValue(value) {
+    return String(value ?? "").trim().replace(/\\/gu, "/").replace(/\/+/gu, "/").toLowerCase() === this.GetResourcePath();
+  }
+
+  /** Return the aggregate texture resource used by the shader binding. */
+  GetResource() {
+    return this.#parent;
+  }
+
+  /** Return the optional resolved source resource for this layer. */
+  GetSourceResource() {
+    return this.#parent.GetLayerResource(this.#layer);
+  }
+  SetSourceResource(resource) {
+    const previous = this.GetSourceResource();
+    if (!this.#parent.SetLayerResource(this.#layer, resource)) return false;
+    this.EmitEvent("changed", this, "sourceresource", this.GetSourceResource(), previous);
+    return true;
+  }
+  SetResource(resource) {
+    return this.SetSourceResource(resource);
+  }
+
+  /** Invalidate this layer after an in-place source content revision. */
+  Touch() {
+    this.#parent.TouchLayer(this.#layer);
+    this.EmitEvent("changed", this, "sourcerevision", this.GetSourceResource());
+    return this;
+  }
+  GetResources(out = []) {
+    if (!out.includes(this.#parent)) out.push(this.#parent);
+    return out;
+  }
+  IsPrepared() {
+    return this.#parent.IsPrepared();
+  }
+  IsGood() {
+    return this.#parent.IsGood();
+  }
+  Ready(options = {}) {
+    return this.#parent.Ready(options);
+  }
+}
+
+export { CjsTextureParameterProxy };
+//# sourceMappingURL=CjsTextureParameterProxy.js.map

package/docs/README.md

@@ -0,0 +1,69 @@
+# 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, source adapters, and the queued
+CPU load/publication pipeline. It stops at a published CPU payload; engine
+packages realize that payload into backend objects.
+
+## 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 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/core-types` (event emitter, model
+  contracts) and `@carbonenginejs/core-math` 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, and load/publication queues.
+- 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)
+- [Format subpaths](formats/README.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.
+- [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/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.
+- [formats/README.md](formats/README.md): format import map and per-format
+  output notes.
+- [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 that is not implemented.

package/docs/architecture.md

@@ -0,0 +1,86 @@
+# 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 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.
+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` 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,
+  frame-coalesced texture-array inputs.
+- Raw `CjsEventEmitter` (from `core-types/model`) for manager/runtime events
+  without requiring `CjsModel` inheritance.
+- Path normalization, extension helpers, and source adapters for memory and
+  `fetch`.
+- 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`.
+- `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
+  `@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).
+- AudioBuffer construction, playback, or audio manager behavior.
+
+## 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.
+- `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.
+
+## 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.

package/docs/concepts/resource-lifecycle.md

@@ -0,0 +1,217 @@
+# Resource lifecycle
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource`  
+Audience: Users and integrators  
+Summary: Explains resource states, the load/prepare split, and how a resource request flows from path to published CPU payload.
+
+## Carbon and ccpwgl background
+
+Carbon's resource model separates load from prepare. The source schemas expose
+resource classes through `BlueAsyncRes`, and Carbon notes distinguish
+background load work from main-thread/device prepare work.
+
+ccpwgl makes that split visible in `Tw2Resource`:
+
+```text
+NO_INIT -> REQUESTED -> LOADED -> PREPARED
+```
+
+Additional terminal or cleanup states include `ERROR`, `UNLOADED`, and
+`PURGED`. The important behavior is:
+
+- `Tw2ResMan.LoadResource()` requests a resource.
+- The raw fetch resolves.
+- `Tw2Resource.OnLoaded()` marks bytes or source data as loaded.
+- The resource is queued for prepare.
+- The manager tick later calls `res.Prepare(data)`.
+- The concrete resource calls `OnPrepared()` after prepare work succeeds.
+
+Some ccpwgl concrete `Prepare()` implementations also create WebGL objects.
+That is a historical engine/runtime coupling, not the boundary CarbonEngineJS
+keeps; see [architecture](../architecture.md).
+
+## CarbonEngineJS states
+
+```text
+EMPTY -> REQUESTED/LOADING -> LOADED          (runtime-resource)
+LOADED -> PREPARING -> PREPARED               (engine adapters)
+```
+
+- `EMPTY`: resource identity exists, but no payload has been read.
+- `REQUESTED`: the resource is waiting on a queued or shared source load.
+- `LOADING`: source bytes are available and CPU reader/format work is active.
+- `LOADED`: CPU payload or hydrated object graph exists.
+- `PREPARING`: an engine adapter is realizing backend-owned resources.
+- `PREPARED`: preparation completed successfully and the resource is usable.
+- `FAILED`: CPU loading, conversion, validation, or publication failed before
+  a valid payload was published.
+- `UNLOADED`: resource payload was released.
+- `PURGED`: an inactivity or recorded-byte cache policy evicted the resource
+  from active ownership. Ordinary replacement, `Delete()`, `Clear()`,
+  `ClearCached()`, and shutdown clean owned payloads/adapters but preserve the
+  detached handle's last valid state.
+
+`CjsResMan.LoadObject()` queues one deduplicated background source operation
+per source/path and limits active source operations with
+`maxConcurrentLoads`. After bytes arrive, object construction is split into
+separate main-queue items (`reader/format conversion -> publish`). Publication
+moves the resource to `LOADED`, then stops. ResMan never performs backend
+realization or marks the resource `PREPARED`/`GOOD`. See
+[reference/queues.md](../reference/queues.md) for the queue contract and
+[reference/motherlode-cache.md](../reference/motherlode-cache.md) for
+identity, retention, and release behavior.
+
+## Request workflow
+
+The normal direct resource-path flow is:
+
+```text
+Application / runtime object
+        |
+        | requests "res:/model/ship.gr2"
+        | with optional per-request overrides
+        v
++-----------------------------------------------+
+| CjsLibrary                                    |
+|                                               |
+| - starts from registered default behavior     |
+| - considers registered capability reports     |
+| - chooses requirement / emit / format         |
+| - applies explicit request overrides          |
++-----------------------------------------------+
+        |
+        | path + resolved request options
+        v
++-----------------------------------------------+
+| CjsResMan.GetResource(path, options)          |
+|                                               |
+| - normalize source path and extension         |
+| - resolve the promised output tag             |
++-----------------------------------------------+
+        |
+        v
++-----------------------------------------------+
+| CjsMotherLode.Lookup(resolved key)             |
++-----------------------------------------------+
+        |
+        +--- cache hit ------------------------------+
+        |                                             |
+        |    reuse the CjsResource and any active     |
+        |    load/build operation                     |
+        |                                             |
+        `--- cache miss -----------------------------+
+              |                                       |
+              | resolve class from requirement        |
+              | construct + Initialize()              |
+              | insert into CjsMotherLode              |
+              v                                       |
+        new CjsResource -------------------------------+
+        |
+        | Ready() / GetObject()
+        v
++===============================================+
+| BACKGROUND LOAD QUEUE                         |
+|                                               |
+| - mark resource REQUESTED                     |
+| - share one source operation per source/path  |
+| - obey maxConcurrentLoads                     |
+| - source.Read(path)                           |
++===============================================+
+        |
+        | source bytes
+        v
++===============================================+
+| MAIN PREPARE QUEUE                            |
+|                                               |
+| every box below is a separately budgeted item |
++===============================================+
+        |
+        v
++-----------------------------------------------+
+| Read stage                                    |
+|                                               |
+| current object loader for extension?          |
+|   yes -> call it                              |
+|   no  -> resolve registered formats by        |
+|          bytes + request options               |
++-----------------------------------------------+
+        |
+        | plain payload / hydrated object
+        v
++-----------------------------------------------+
+| Publish stage                                 |
+|                                               |
+| semantic resource -> SetPayload(payload)      |
+| generic resource  -> SetPayload(value)        |
+|                      object aliases payload   |
++-----------------------------------------------+
+        |
+        +--- validation failure --------------------+
+        |                                            |
+        |    resource -> FAILED                      |
+        |    Ready() rejects                         |
+        |                                            |
+        `--- publication succeeds -----------------+
+                    |
+                    | resource -> LOADED
+                    v
+             CjsLibrary returns
+             the built CjsResource/object
+```
+
+Device realization is a separate continuation selected outside ResMan. It can
+run again after adapter eviction or device loss while the CPU payload remains
+resident:
+
+```text
+CjsResource LOADED
+        |
+        | selected engine adapter
+        v
+PREPARING
+        |
+        | create candidate -> verify current target -> synchronous attach
+        v
+PREPARED
+
+failure: destroy candidate -> LOADED (CPU payload retained)
+```
+
+## Retention model
+
+ccpwgl keeps every resource in `Tw2MotherLode` until it is explicitly cleared
+or auto-purged, and its `IsGood()` implicitly calls `KeepAlive()`, so many
+read/check paths keep resources resident. CarbonEngineJS is deliberately more
+explicit:
+
+- `IsGood()`, `IsPrepared()`, and `HasLoaded()` remain pure state checks.
+- `KeepAlive()` and `KeepPayloadAlive()` are the explicit liveness operations.
+- `Lock()` / `Unlock()` maintain a non-underflowing count and prevent identity
+  and payload eviction during a sweep.
+- MotherLode tracks separate identity and CPU-payload frame/time observations.
+- `CjsMotherLode.PurgeInactive()` scans only when explicitly requested and
+  never infers JavaScript reachability. `CjsResMan.Update()` may request it
+  only under an explicitly configured automatic policy.
+
+The CPU/GPU split adds an axis that ccpwgl blurs: CPU payload memory and
+device memory are different budgets. Retention therefore distinguishes:
+
+- resource identity: path, extension, state, error summary, lightweight
+  metadata;
+- CPU payload: plain reader/converter objects, hydrated object graphs, decoded
+  typed arrays;
+- adapter payload: WebGL/WebGPU textures, buffers, shader modules, pipelines.
+
+Identity and lightweight metadata stay resident while CPU payloads and adapter
+payloads release independently. Engine adapters own adapter-resource
+destruction; runtime-resource provides lifecycle hooks and opaque adapter
+slots so cleanup has a consistent place to run. The exact contracts live in
+[reference/motherlode-cache.md](../reference/motherlode-cache.md).
+
+## Related documentation
+
+- [Architecture and boundaries](../architecture.md)
+- [MotherLode identity, cache, and retention](../reference/motherlode-cache.md)
+- [Candidate-first atomic reload](../reference/reload.md)
+- [Queues and the Wait fence](../reference/queues.md)