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

package/docs/resource/reference/workers.md

@@ -113,8 +113,10 @@ static worker = {
 };
 ```
 
-Format options containing functions, symbols, non-plain instances, cycles, or
-caller-supplied class constructors do not cross the worker boundary.
+Format options containing functions, symbols, unsupported non-plain instances,
+or caller-supplied class constructors do not cross the worker boundary.
+Shared references and cycles in otherwise clone-safe arrays or plain objects
+are accepted; revisiting an object does not force main-thread fallback.
 
 ## Queues and ownership
 

package/docs/sof/reference/classes/core.md

@@ -71,6 +71,6 @@ Implements the deterministic integer pseudo-random sequence used by internal SOF
 Allocates and links the internal compatibility node table, imports self-describing values or legacy document fragments, and retains only nodes reachable from its root.
 
 - Export: None
-- Source: `src/sof/EveSOF.js`
+- Source: `src/sof/SofDocumentBuilder.js`
 - Visibility: Internal
 - Kind: Internal implementation class

package/docs/sof/reference/classes/faction.md

@@ -41,7 +41,7 @@ Stores a faction's semantic color palette and resolves enum-selected colors into
 Reports that a faction-color lookup used an unknown color-slot enum value.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/faction/EveSOFDataFactionColorSet.js`
+- Source: `src/sof/faction/ErrSOFFactionColorSetTypeUnknown.js`
 - Visibility: Public
 - Kind: Public error class
 
@@ -51,7 +51,7 @@ Reports that a faction-color lookup used an unknown color-slot enum value.
 Reports that a known faction-color slot has no color assigned.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/faction/EveSOFDataFactionColorSet.js`
+- Source: `src/sof/faction/ErrSOFFactionColorSetTypeNotFound.js`
 - Visibility: Public
 - Kind: Public error class
 

package/docs/sof/reference/classes/generic.md

@@ -21,7 +21,7 @@ Provides the top-level generic SOF configuration for shaders, material prefixes,
 Reports that a requested area shader is absent from the generic SOF catalog.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/generic/EveSOFDataGeneric.js`
+- Source: `src/sof/generic/ErrSOFAreaShaderNotFound.js`
 - Visibility: Public
 - Kind: Adapted ccpwgl error class
 
@@ -31,7 +31,7 @@ Reports that a requested area shader is absent from the generic SOF catalog.
 Reports that a requested decal shader is absent from the generic SOF catalog.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/generic/EveSOFDataGeneric.js`
+- Source: `src/sof/generic/ErrSOFDecalShaderNotFound.js`
 - Visibility: Public
 - Kind: Adapted ccpwgl error class
 
@@ -41,7 +41,7 @@ Reports that a requested decal shader is absent from the generic SOF catalog.
 Reports that a requested material prefix is absent from the generic SOF catalog.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/generic/EveSOFDataGeneric.js`
+- Source: `src/sof/generic/ErrSOFMaterialPrefixNotFound.js`
 - Visibility: Public
 - Kind: Adapted ccpwgl error class
 
@@ -51,7 +51,7 @@ Reports that a requested material prefix is absent from the generic SOF catalog.
 Reports that a requested pattern-material prefix is absent from the generic SOF catalog.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/generic/EveSOFDataGeneric.js`
+- Source: `src/sof/generic/ErrSOFPatternMaterialPrefixNotFound.js`
 - Visibility: Public
 - Kind: Adapted ccpwgl error class
 

package/docs/sof/reference/classes/pattern.md

@@ -21,7 +21,7 @@ Defines a named two-layer pattern with application groups, per-hull lookup, flip
 Reports that a pattern has no projection for the requested hull.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/pattern/EveSOFDataPattern.js`
+- Source: `src/sof/pattern/ErrSOFProjectionNotFound.js`
 - Visibility: Public
 - Kind: Public error class
 

package/docs/sof/reference/classes/shared.md

@@ -41,7 +41,7 @@ Defines the canonical SOF area slots and provides enum-based lookup for them.
 Reports that a requested canonical area slot has no material assigned.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/shared/EveSOFDataArea.js`
+- Source: `src/sof/shared/ErrSOFAreaTypeNotFound.js`
 - Visibility: Public
 - Kind: Adapted ccpwgl error class
 
@@ -141,7 +141,7 @@ Provides enum-based primary, secondary, tertiary, and marking-logo lookup plus l
 Reports that a logo lookup used an undefined logo-slot enum value.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/shared/EveSOFDataLogoSet.js`
+- Source: `src/sof/shared/ErrSOFLogoSetTypeUnknown.js`
 - Visibility: Public
 - Kind: Adapted ccpwgl error class
 
@@ -151,7 +151,7 @@ Reports that a logo lookup used an undefined logo-slot enum value.
 Reports that a defined logo slot has no logo assigned.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/shared/EveSOFDataLogoSet.js`
+- Source: `src/sof/shared/ErrSOFLogoSetTypeNotFound.js`
 - Visibility: Public
 - Kind: Adapted ccpwgl error class
 
@@ -191,7 +191,7 @@ Stores a named vector parameter and supports assignment and composition; the typ
 Boolean shader parameter whose `GetValue()` broadcasts 1 or 0 to all four components; persists under the same `{name, value}` shape as the base parameter.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/shared/EveSOFDataParameter.js`
+- Source: `src/sof/shared/EveSOFDataParameterBool.js`
 - Visibility: Public
 - Kind: Carbon
 
@@ -201,7 +201,7 @@ Boolean shader parameter whose `GetValue()` broadcasts 1 or 0 to all four compon
 Integer shader parameter whose `GetValue()` broadcasts the value to all four components.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/shared/EveSOFDataParameter.js`
+- Source: `src/sof/shared/EveSOFDataParameterInt.js`
 - Visibility: Public
 - Kind: Carbon
 
@@ -211,7 +211,7 @@ Integer shader parameter whose `GetValue()` broadcasts the value to all four com
 Float shader parameter whose `GetValue()` broadcasts the value to all four components.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/shared/EveSOFDataParameter.js`
+- Source: `src/sof/shared/EveSOFDataParameterFloat.js`
 - Visibility: Public
 - Kind: Carbon
 
@@ -221,7 +221,7 @@ Float shader parameter whose `GetValue()` broadcasts the value to all four compo
 Two-component shader parameter whose `GetValue()` zero-pads z and w.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/shared/EveSOFDataParameter.js`
+- Source: `src/sof/shared/EveSOFDataParameterVector2.js`
 - Visibility: Public
 - Kind: Carbon
 
@@ -231,7 +231,7 @@ Two-component shader parameter whose `GetValue()` zero-pads z and w.
 Three-component shader parameter whose `GetValue()` zero-pads w with 0, not 1.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/shared/EveSOFDataParameter.js`
+- Source: `src/sof/shared/EveSOFDataParameterVector3.js`
 - Visibility: Public
 - Kind: Carbon
 
@@ -241,7 +241,7 @@ Three-component shader parameter whose `GetValue()` zero-pads w with 0, not 1.
 Color shader parameter whose `GetValue()` passes its four components through unchanged.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/shared/EveSOFDataParameter.js`
+- Source: `src/sof/shared/EveSOFDataParameterColor.js`
 - Visibility: Public
 - Kind: Carbon
 
@@ -261,7 +261,7 @@ Defines point-light placement, rotation, intensity, saturation, scale, noise, an
 Defines spotlight placement, intensity, saturation, cone angles, scales, noise, and profile data for an attachment.
 
 - Export: `@carbonenginejs/runtime/sof`
-- Source: `src/sof/shared/EveSOFDataSpotlightAttachment.js`
+- Source: `src/sof/shared/EveSOFDataSpotLightAttachment.js`
 - Visibility: Public
 - Kind: Adapted Carbon concept
 

package/docs/trinity/architecture.md

@@ -17,14 +17,14 @@ serialized in browsers, workers, Node.js tools, and test hosts.
 ```text
 @carbonenginejs/tools-core -- reviewed source --> @carbonenginejs/runtime/trinity
 @carbonenginejs/runtime/trinity -- imports --> src/global + src/resource
-
-@carbonenginejs/runtime/resource -- decoded values --> application composition
-@carbonenginejs/runtime/trinity -- graph and intents --> application composition
-application composition --> host WebGL engine
-application composition --> @carbonenginejs/runtime/engine/webgpu
-```
-
-Runtime dependencies point from `@carbonenginejs/runtime/trinity` to
+
+@carbonenginejs/runtime/resource -- decoded values --> application composition
+application composition -- injects AL --> Tr2RenderContext
+Tr2RenderContext -- binding and draw calls --> selected AL
+selected AL = headless stub, or internal trinityal/webgpu implementation
+```
+
+Runtime dependencies point from `@carbonenginejs/runtime/trinity` to
 `@carbonenginejs/runtime/global` and `@carbonenginejs/runtime/resource`.
 Schema scanning and source emission flow from `@carbonenginejs/tools-core`
 during development, but generated source never imports that Node toolchain.
@@ -32,13 +32,13 @@ during development, but generated source never imports that Node toolchain.
 ## Owned responsibilities
 
 The current package owns:
-
-- Carbon-compatible class identity, schema fields, enums, and graph structure;
-- CPU-side curves, controllers, cameras, transforms, behaviors, and effects;
-- renderer-neutral render batches and ordered render-job intent;
-- per-object semantic values that can be established from graph state;
-- portable lifecycle, distribution, post-process graph, and scene behavior;
-- generated schema intake and the maintained implementations promoted from it.
+
+- Carbon-compatible class identity, schema fields, enums, and graph structure;
+- CPU-side curves, controllers, cameras, transforms, behaviors, and effects;
+- renderer-neutral render batches and ordered render-job execution;
+- per-object semantic values that can be established from graph state;
+- portable lifecycle, distribution, post-process graph, and scene behavior;
+- generated schema intake and the maintained implementations promoted from it.
 
 Trinity's constraint is GPU-free state — no live backend handle in a persisted
 field — not a values-only graph. Classes get the methods needed to match Carbon;
@@ -82,23 +82,26 @@ end still runs when execution throws. Nested jobs receive the same context.
 A render context owns one `CjsTrinityStepExecutor`. `SetStepExecutor` accepts
 only that nominal identity or null, with null restoring the shared
 `CjsDirectTrinityStepExecutor`. The context calls every required executor
-method directly and supplies itself as the fifth step argument. Concrete engine
-recorders extend the base; omitting a required method reaches the base method
+method directly and supplies itself as the fifth step argument. Omitting a
+required executor method reaches the base method
 and throws instead of silently falling back or skipping work.
-
-With `stackGuard` enabled, a job records render-target and depth-stencil stack
+
+With `stackGuard` enabled, a job records render-target and depth-stencil stack
 depths, diagnoses underflow, and unwinds surplus pushes to the entry depth on
-success, yield, or failure. `TriRenderJob` and `TriRenderStep` expose their
-status and result vocabularies as class statics.
-
-The default `Tr2RenderContext` is a GPU-free intent and diagnostic surface.
-`GetIntents()` returns a copy of the full retained history. An executor uses
-`TakeIntents()` for incremental, exactly-once consumption; it advances the
-take cursor so nested jobs cannot realize the same intent twice. The package
-keeps concrete backend recording and dispatch inside the selected engine.
-
-## Vertex-declaration matching
-
+success, yield, or failure. `TriRenderJob` and `TriRenderStep` expose their
+status and result vocabularies as class statics.
+
+The default `Tr2RenderContext` holds a headless `Tr2RenderContextALStub`.
+`SetRenderContextAL` injects the backend; passing null restores the stub.
+Trinity walks batches, applies shader/material state and submits geometry through
+AL binding and draw calls. There is no `GetIntents`/`TakeIntents` history to
+replay. Real backend handles do not belong in persisted fields.
+
+The [WebGPU AL draw path](../trinityal/webgpu/architecture.md#current-al-draw-path)
+documents pipeline resolution, first-use resource realization and frame submission.
+
+## Vertex-declaration matching
+
 `Tr2VertexDefinition` pairs a mesh's vertex element list with a vertex shader's
 declared inputs and returns a resolved binding plan. Engines consume the plan;
 they do not re-derive it, and a WebGL engine caches it as a vertex array object.
@@ -244,12 +247,14 @@ the scene composes them with inverse view and atlas transforms, then
 `RawData.SetAndTransposeIndex` performs the one terminal packing transpose.
 Engines must not transpose, rebuild, or reinterpret those matrices.
 
-Physical shadow work uses the nominal `CjsShadowMapExecutor` installed once on
-the active `Tr2RenderContext`. Engine implementations extend that base and
-realize atlas allocation, split-pass begin/end, screen-result drawing, and
-optional denoising. Every base method throws, and `Tr2ShadowMap` calls the
-installed executor directly, so a missing engine capability cannot degrade to
-a silently skipped shadow pass.
+`Tr2ShadowMap` also owns shadow-pass preparation, split viewport selection,
+state restoration and screen-space resolve, using the resource pool and render
+context's AL. Preparation unbinds the color target and binds the cascade depth
+surface. Resolve borrows an R8 target at scene-depth dimensions, draws through
+`Tr2Renderer.DrawScreenQuad`, clears the effect's runtime texture bindings, and
+optionally calls `Tr2Denoiser.Apply`. The former `CjsShadowMapExecutor` was removed;
+an application does not install a replacement executor. These implementations
+do not by themselves qualify a backend's rendered shadow output.
 
 ### Froxel-fog contract
 
@@ -262,13 +267,14 @@ lighting overrides and before visibility/gather. This caller has landed; the
 driver's broader frame remains deliberately partial. The renderer is scene-owned and its per-frame fill is already
 called directly, so a missing owned method fails visibly.
 
-Physical froxel and volumetric textures, fog passes, environment-map updates,
-variable-store texture publication, and volumetric shadow draws remain engine
-realization. `CjsVolumetricsExecutor` is the nominal throwing base installed on
-the active render context; the maintained graph class delegates the exact
-Carbon-shaped calls directly to that executor. Engines consume the blended
-values and terminal RawData bytes; they do not re-run the priority policy or
-repack constants.
+The former `CjsVolumetricsExecutor` was removed. Remaining fog, volumetric,
+reflection-map and volumetric-shadow passes are explicit throwing methods on
+`Tr2VolumetricsRenderer`, not instructions to implement an external executor.
+Its static empty-texture helpers take the resource pool and still throw.
+`UpdateVariableStore()` is implemented: it takes no arguments and publishes the
+Mie environment-map reference through the global variable store. Backend
+allocation and submission use the AL; the blended values and terminal RawData
+bytes are not recomputed or repacked there.
 
 Fog providers implement the maintained nominal `ITr2FroxelFogSettings`
 identity. Its base method throws; `EveChildFogVolume` supplies the concrete,
@@ -377,7 +383,12 @@ A transient arena record never clears its flag, which is correct rather than a
 leak: it is filled and consumed within one frame, so `ClearDirty` means "these
 bytes have been uploaded", never "this payload is now stable".
 
-A renderable returns whichever shape its constant data actually has:
+A renderable can return a `Tr2PerObjectData` family instance owning or borrowing
+its `RawData` payloads. `GetPayloads()` exposes those payloads. The classes
+provide instance upload methods, but the render context still calls the shared
+static `Tr2PerObjectData.setPerObjectDataToDevice`, which resolves family
+instances through `GetPayloads()`. Producer migration is partial; the same
+resolver still accepts:
 
 - one payload, when a single buffer is bound;
 - a `{ vs, ps }` record, when the vertex and pixel stages take DIFFERENT

package/docs/trinity/concepts/generated-class-lifecycle.md

@@ -80,21 +80,16 @@ implementations before editing them.
 `src/trinity/generated/summary.json` is the receipt from an earlier whole-tree install,
 not a live work queue or an authoritative count of the current generated tree.
 The current `tools-core` emitter operates per class; promotion removes installed
-files without rewriting that historical receipt. Ownership and release checks
-therefore use the current source tree, barrels, parity audit, and gap audit.
-
-`EveDamageOverlay`, `EveModularObjectModifier`, and `EveChildCloud` have left
-generated intake. Their maintained implementations live under `src/trinity/eve`,
-their generated copies are deleted, and exact package-export tombstones block
-the former generated deep paths. The damage overlay now owns the shared CPU
-data rows, the modular modifier consumes an injected SOF builder without a
-Trinity-to-SOF dependency and reacquires graph records after values hydration,
-and the legacy cloud inherits the maintained `EveSpaceObjectChild` ownership
-contract while implementing its portable transform, bounds, and visibility
-behavior.
-
-Generation runs into a tooling-owned scratch corpus or another staging
-directory. Reviewed output is then copied only into generator-owned paths.
+files without rewriting that historical receipt. Ownership and release checks
+therefore use the current source tree, barrels, parity audit, and gap audit.
+
+The [2026-08-25 closure](../reference/implementation-status.md#2026-08-25-carbon-closure)
+records the maintained damage-overlay, modular-modifier and legacy-cloud
+behavior in `src/trinity/eve`. Their generated copies are deleted; exact package-export tombstones
+block the former generated deep paths.
+
+Generation runs into a tooling-owned scratch corpus or another staging
+directory. Reviewed output is then copied only into generator-owned paths.
 The class emitter refuses to overwrite a differing `--out` file unless
 `--force` is supplied; `--force` must not target runtime source.