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

package/docs/resource/formats/webgpu/reference/wgsl-compatibility.md

@@ -1282,93 +1282,62 @@ the all-body path initially omitted the particle-clear effect-profile
 preflight. The synthetic fixtures cannot express either condition, so an
 all-body corpus sweep is part of this feature's verification, not an optional
 extra.
-
-## Consumer boundary: resource transforms
-
-The `trinityal/webgpu` layer accepts `CJS_WGSL_SET` versions 1, 2 and 3, and realizes
-`texture-2d-array` resource transforms. The discriminator is the **feature**,
-never the document version and never `texture.viewDimension`:
-
-- a **source-declared** `texture_2d_array` keeps every one of its bindings and
-  needs no assembly. Gating on `viewDimension` would reject the very packages
-  the exact draw gate renders — the selected Quad V5 body binds a plain
-  `texture_2d_array<f32>` with no transform, and both Quad families carry
-  `cube` bindings.
-- a **transformed** binding carries `transformId` and `arrayLayerCount`, and its
-  merged-away inputs are absent from the layout. It cannot be fed from one
-  source texture, so the consumer assembles the layers.
-
-Only `kind: texture-2d-array`, `version: 1`,
-`representation: native-or-rgba8`, and `missingLayer: reject` are realized.
-Anything else throws a diagnostic naming the offending field, because the
-failure mode of guessing is WGSL a device accepts and pixels that are quietly
-wrong.
-
-Both halves of the claim are validated, not just the record: exactly one binding
-must carry each declared transform, at the declared output identity, with a
-matching `arrayLayerCount`, a `texture_2d_array<f32>` type, visibility to the
-transform's stage, and **no surviving binding for any merged-away input**. A
-survivor would still be bindable and would silently receive a texture the shader
-never reads. Symmetrically, a binding claiming an undeclared transform, or
-declaring array layers without one, is rejected.
-
-### The analysis is pre-transform; the layout is post-transform
-
-This asymmetry is the one thing a consumer must not get wrong. The reflection
-still lists every declared resource under its own register, including inputs the
-producer merged away; the layout is shorter by exactly those inputs. Checking
-one against the other reports the merge as drift. The merged array occupies the
-**layer-0 input's slot**, which is required rather than assumed, so the binding a
-consumer must fill is unambiguous.
-
-Layers are written in declared order, layer *i* from `inputs[i]`, and must agree
-on size and format because one texture cannot hold layers that do not. A missing
-input is rejected rather than substituted: any stand-in layer would change the
-rendered result while still validating.
-
-Realized and drawn, all with zero WGSL warnings:
-
-| Family | Layers | Merged into | Evidence |
+
+## Consumer boundary: resource transforms
+
+The [version-3 contract](../formats/carbon-webgpu.md#version-3-resource-transforms)
+owns supported recipes and record/layout validation; the
+[device API](../../../../trinityal/webgpu/reference/api.md#device-boundary)
+owns caller-supplied layer assembly. Unsupported fields fail with a diagnostic
+naming the field. Validation rejects undeclared transforms, orphan layer-count
+claims, and surviving bindings for merged-away inputs.
+
+Discriminate by **feature**, not document version or `texture.viewDimension`:
+
+- **Source-declared** arrays retain their bindings and need no assembly. The
+  selected Quad V5 body binds `texture_2d_array<f32>` without a transform;
+  both Quad families also carry `cube` bindings.
+- **Transformed** bindings carry `transformId` and `arrayLayerCount`; their
+  merged-away inputs are absent. Supply the assembled layers, not one source.
+
+### The analysis is pre-transform; the layout is post-transform
+
+Reflection retains each declared register, including merged-away inputs;
+physical layout omits those inputs. Comparing them as identical would report
+the intended merge as drift. The contract requires the array to reuse layer
+zero's slot, preserve declared input order, and reject missing or incompatible
+layers.
+
+Realized and drawn, all with zero WGSL warnings:
+
+| Family | Layers | Merged into | Evidence |
 | --- | --- | --- | --- |
 | `unpackedskinned_quadheatdetailv5` | 2 | `Detail1Map` slot | 22 over 22 bindings, 3 cases, detail changed 570/635 covered pixels |
-| `unpacked_quaddetailv5` | 3 | `Detail1Map` slot | both detail controls changed 1116/1116 covered pixels |
-| `unpackedskinned_quaddetailv5` | 3 | `Detail1Map` slot | 634/635 and 635/635, indexed non-identity bones observed |
-
-The `Detail1` and `Detail2` delta maps were **distinct** in every case. That is
-the assertion that matters: a collapsed or misordered assembly would produce
-identical deltas while still rendering and still validating.
-
-Source-declared array textures are now realized rather than merely accepted:
-the engine creates a layered 2D texture with a `2d-array` view and binds it
-through the same adapter, gated by a synthetic two-layer draw that asserts each
-layer's pixels exactly. A single-layer array view is legal and distinct from a
-plain 2D view, because a shader declaring `texture_2d_array<f32>` needs the
-array view whatever its layer count. A layout asking for the dimension the view
-was not created with fails closed, since a view's dimension is fixed at
-creation and cannot be reinterpreted.
-
-This matters beyond the transform case: the High `.sm_depth` Quad V5 `Main`
-pass binds `LightProfileArray` as a plain `texture_2d_array<f32>` with no
-transform at all, so array-texture realization is a prerequisite for any
-High-tier draw gate, not a detail of transform support.
-
-Array-texture realization is what made transform support possible: the engine
-allocates the array itself and fills layer *i* from `inputs[i]`, which is the
-only way a binding whose other inputs were removed can be filled at all. The
-Detail and HeatDetail family gates draw under this contract. The Environment
-family has not been exercised and should be treated as unverified rather than
-working.
-
-Accepting version 3 also tightened three structural checks that were written
-`=== 2` and would otherwise have silently downgraded every version-3 package to
-version-1 semantics: shared binding identities must span at least two stages,
-and explicit D3D and scope identities are both required. That downgrade would
-have been invisible to the exact draw gate, because DX11 and DX12 downgrade
-identically and the bit-exact comparison would have stayed green.
-
-## Verification contract
-
-Every shader-emission, layout, or transform compatibility change requires the
+| `unpacked_quaddetailv5` | 3 | `Detail1Map` slot | both detail controls changed 1116/1116 covered pixels |
+| `unpackedskinned_quaddetailv5` | 3 | `Detail1Map` slot | 634/635 and 635/635, indexed non-identity bones observed |
+
+`Detail1` and `Detail2` delta maps were **distinct** in every case: collapsed
+or misordered assembly could render and validate but produce identical deltas.
+
+Source-declared arrays are also realized: a synthetic two-layer draw checks
+each layer's pixels exactly through the same adapter. A single-layer
+`2d-array` view remains distinct from plain 2D; a layout requesting a dimension
+other than the view's fixed creation dimension fails closed. High `.sm_depth`
+Quad V5 `Main` binds `LightProfileArray` without a transform, so this support
+is a prerequisite for High-tier draw gates.
+
+The Detail and HeatDetail gates exercise layer assembly under this contract;
+**Environment remains unverified**.
+
+Version 3 exposed three checks incorrectly gated by `=== 2`: shared identities
+must span at least two stages, and explicit D3D and scope identities are both
+required. Otherwise version 3 would silently acquire version-1 semantics. Exact
+DX11/DX12 draw comparison would miss that regression because both would downgrade
+identically.
+
+## Verification contract
+
+Every shader-emission, layout, or transform compatibility change requires the
 package suite and a representative `trinityal/webgpu` browser gate on a real
 WebGPU device with zero WGSL warnings. Format-level qualification cannot detect
 every WGSL scoping or validator failure, so browser validation remains part of

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/docs/trinityal/reference/classes/dropped.md

@@ -7,7 +7,7 @@ Summary: Provides one-sentence purpose descriptors for abstraction-layer donor c
 
 Every class here comes from a backend Carbon compiles instead of ours. That is
 not on its own a reason to ignore one: `MetalWorkQueue` is the declared model
-for `CjsWebgpuWorkQueue`, and of the seven below, five describe behaviour this
+for `CjsWebgpuWorkQueue`, and of the eight below, six describe behaviour this
 package already ports under different names. They are written so the
 correspondence is checkable rather than assumed.
 
@@ -71,6 +71,16 @@ Carbon's deferred render-pass attachment record, whose behaviour this package po
 - Visibility: Internal
 - Kind: Faithful Carbon port
 
+<!-- class:MetalWorkQueue -->
+## `MetalWorkQueue`
+
+Carbon's Metal command recorder, whose encoder-lifetime half this package ports as `CjsWebgpuWorkQueue` while the pipeline, resource sets and render context's draw verbs take the rest of its surface.
+
+- Export: None
+- Source: `src/trinityal/dropped/MetalWorkQueue.js`
+- Visibility: Internal
+- Kind: Faithful Carbon port
+
 <!-- class:ShaderResourceMask -->
 ## `ShaderResourceMask`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbonenginejs/runtime",
-  "version": "0.1.0-alpha.1",
+  "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",