@carbonenginejs/runtime 0.1.0-alpha.2 → 0.1.0-alpha.3

package/docs/resource/reference/classes/texture.md

@@ -3,7 +3,7 @@
 Status: Evolving  
 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/resource/texture.
+Summary: Provides one-sentence purpose descriptors for the texture-array aggregation and procedural texture constructor classes in src/resource/texture.
 
 <!-- class:CjsTextureArrayRes -->
 ## `CjsTextureArrayRes`
@@ -24,3 +24,13 @@ Mutable runtime aggregate resource for an ordered texture-array request that coa
 - Source: `src/resource/texture/CjsTextureArrayResParameterProxy.js`
 - Visibility: Public
 - Kind: Original CarbonEngineJS class
+
+<!-- class:SolidColorTextureConstructor -->
+## `SolidColorTextureConstructor`
+
+Carbon's `dynamic:/color` resource constructor, which builds the 1x1 `TriTextureRes` a `dynamic:/color/r,g,b,a` path names and is registered on a manager through `RegisterSolidColorTexture`.
+
+- Export: `@carbonenginejs/runtime/resource`
+- Source: `src/resource/texture/SolidColorTextureConstructor.js`
+- Visibility: Public
+- Kind: Faithful Carbon port

package/docs/resource/reference/motherlode-cache.md

@@ -1,7 +1,7 @@
 # MotherLode identity, cache, and retention
 
 Status: Evolving  
-Scope: `@carbonenginejs/runtime/resource`
+Scope: `@carbonenginejs/runtime/resource`
 Audience: Users and integrators  
 Summary: Defines canonical resource identity, ownership and replacement, the recorded-byte cache, payload retention, read-cache provenance, and purge contracts.
 
@@ -49,9 +49,9 @@ 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 can recover through ordinary liveness checks: asking whether the
-resource is good keeps it or brings it back. Purge remains observable through
-`IsPurged()` and resource events; callers may also manage retention explicitly.
+consumer can recover through ordinary liveness checks: asking whether the
+resource is good keeps it or brings it back. Purge remains observable through
+`IsPurged()` and resource events; callers may also manage retention explicitly.
 
 Liveness follows visibility. Something being drawn is asked about every frame
 and stays live; something that stops being drawn stops being renewed, ages out,
@@ -77,7 +77,7 @@ weak-reference and refcount transitions. JavaScript cannot reproduce that
 ownership test reliably, so `CjsMotherLode` budgets only entries that a caller
 explicitly classifies with `{ cached: true, bytes }`; JavaScript reachability
 is never inferred. The byte value is an exact caller-supplied safe-integer
-eviction weight, not a heuristic walk of the resource graph; the resource layer
+eviction weight, not a heuristic walk of the resource graph; the resource layer
 does not walk arbitrary cyclic/shared object graphs or invoke payload getters
 to guess size.
 
@@ -99,11 +99,11 @@ remaining over-budget state. Trimming never reads, prepares, or reloads data.
 
 ## Payload retention
 
-Readers and converters return plain transient payloads, not resource classes
-or DTO models. Payloads may exceed a consumer's needs: each resource validates
-required fields before publication and retains needed scalars and references;
-adapters may retain additional references in adapter-owned state. Prefer referencing payload-owned
-typed arrays to copying them merely to change ownership.
+Readers and converters return plain transient payloads, not resource classes
+or DTO models. Payloads may exceed a consumer's needs: each resource validates
+required fields before publication and retains needed scalars and references;
+adapters may retain additional references in adapter-owned state. Prefer referencing payload-owned
+typed arrays to copying them merely to change ownership.
 
 The lifecycle treats resource residency and payload residency independently:
 
@@ -178,9 +178,22 @@ WebGPU adapters side by side should normally pass the same payload to both
 consumers and retain it until both have finished. Copying is an explicit
 consumer operation, justified when a consumer must mutate data, transfer and
 detach an `ArrayBuffer`, or retain an independently writable snapshot. The
-consumer should copy only the fields it requires; the resource layer does not
+consumer should copy only the fields it requires; the resource layer does not
 automatically deep-clone payload or typed-array bundles.
 
+One kind of route is the exception, because it hands out objects rather than
+data. An OBJECT-mode extension route that hydrates a `Target` (or an `Identify`
+result) follows Carbon's `BlueResMan::LoadObject`, which caches a builder and
+creates a new object on every call. Its payload is the decoded plain values,
+and every `GetObject()`, `LoadObject()`, `FetchObject()` and `Ready()` caller
+receives its own object hydrated from a structured copy of them, so no two
+callers share a nested array or typed array. Nothing is re-read. Callers
+joining an in-flight load also receive their own object, so for these routes
+the operation's promise is not shared. Values that cannot be structured-copied
+fail the load with `CJS_RESOURCE_EXTENSION_TARGET_FAILED`. Routes without a
+Target, RESOURCE-mode routes, and `Identify` results of `true` keep the shared
+read-only rule above.
+
 ## Read-cache provenance
 
 Source and parsed-format caches use explicit provenance, separate from

package/docs/resource/reference/queues.md

@@ -1,7 +1,7 @@
 # Queues, publication, and the Wait fence
 
 Status: Evolving  
-Scope: `@carbonenginejs/runtime/resource`
+Scope: `@carbonenginejs/runtime/resource`
 Audience: Users and integrators  
 Summary: Defines the two manager-owned queues, publication budgeting, registration, and the `Wait()` fence semantics.
 
@@ -197,6 +197,28 @@ the same registered constructor.
 `RegisterObjectLoader` remains the direct legacy byte-to-value registration for
 an extension without an explicit route.
 
+## Dynamic resources
+
+A `dynamic:/<name>/<query>` path is built by a registered constructor rather
+than read from a source, as in Carbon's `BlueResMan::GetResourceHelper`.
+`RegisterResourceConstructor(name, constructor)` registers an object whose
+`GetResource(query)` returns a resource; names are lowercased, and
+`UnregisterResourceConstructor(name)` removes one. The lookup sits below the
+MotherLode lookup, so identical queries share one resource, and the resource is
+inserted not cacheable (Carbon's `CACHING_NOT_ALLOWED`). A dynamic resource never
+falls back to a source read. An unknown name raises
+`CJS_RESMAN_DYNAMIC_CONSTRUCTOR_MISSING`, a constructor that returns no resource
+raises `CJS_RESMAN_DYNAMIC_RESOURCE_UNAVAILABLE`, and `GetObject()` on a dynamic
+resource without a payload rejects with that resource's error.
+
+`RegisterSolidColorTexture(resMan)` registers Carbon's `color` constructor. It is
+an explicit composition call, like `RegisterShaderResources`, rather than
+Carbon's static registration. `dynamic:/color/r,g,b,a` is a 1x1 `TriTextureRes`
+whose `rgba32float` payload holds the colour quantized through the half-float
+codec, parsed exactly as Carbon's `ParseColor`; a malformed query fails the
+texture with `CJS_TEXTURE_PROCEDURAL_PATH_INVALID`. The WebGPU device does not
+yet upload `rgba32float` payloads, and `dynamic:/gradient_1d/` is not ported.
+
 ## Related documentation
 
 - [Resource lifecycle concepts](../concepts/resource-lifecycle.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbonenginejs/runtime",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "private": false,
   "description": "Browser-safe CarbonEngineJS runtime: resource and format readers, the Trinity/EVE object graph, SOF, audio, character, and the WebGPU renderer.",
   "type": "module",