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

package/docs/trinityal/webgpu/architecture.md

@@ -10,6 +10,11 @@ Summary: Defines what the WebGPU engine package owns and what callers must suppl
 The package turns validated, already-selected Carbon WebGPU descriptors and explicit
 caller data into generation-bound WebGPU objects and encoded draws.
 
+The live Trinity integration uses an injected abstraction-layer context; see
+[Current AL draw path](#current-al-draw-path). The explicit-descriptor APIs and
+internal harness adapters described elsewhere on this page remain available,
+but are not the mechanism by which Trinity submits its batches.
+
 ## Current ownership
 
 `CjsWebgpuPackage` normalizes decoded package data into mutable shader,
@@ -98,196 +103,129 @@ the accessor pair.
 Carbon WebGPU bytes can be decoded by an injected reader. Offline corpus tooling can
 produce packages for qualification, but it is not an engine dependency.
 
-## Trinity batch boundary
-
-The internal `CjsWebgpuTrinityBatchDispatcher` extends the GPU-free Trinity
-dispatcher contract and consumes canonical `Tr2RenderBatch`,
-`ITriRenderBatchAccumulator`, and `TriRenderBatchMap` instances. Its injected
-resolver extends `CjsTrinityBatchResolver`. Composition validates those owned
-identities once; batch preparation and encoding then call the required methods
-directly. The resolver maps CPU material, geometry, and object-data references
-to an already-decoded pipeline recipe, WebGPU-owned geometry, and complete
-binding values.
-
-The dispatcher owns only the binding set it creates. Geometry, textures,
-samplers, decoded packages, and logical values remain owned by their
-resolvers. It maps indexed and non-indexed draw arguments, rejects unsupported
-topologies and incompatible pipeline recipes, and rolls back its binding set
-when draw creation fails.
-
-Mesh batches may carry only a `geometrySource` area range and leave their draw
-arguments zero. `ResolveGeometry` may therefore return a complete indexed or
-non-indexed `draw` override derived from CPU geometry facts and the engine's
-realized buffer packing. Producers with explicit draw arguments continue to
-use the batch fields. The dispatcher validates either path before draw
-creation.
-
-It also snapshots both vectors of a finalized nominal
-`ITriRenderBatchAccumulator`, preserves their internal order,
-encodes GDPR before ordinary batches, and owns the collected binding-set
-lifecycle as one unit. GDPR entries use the same non-indirect path as ordinary
-entries, matching Carbon's fallback semantics; the indirect-draw sink is a
-DirectX 12 and Metal capability that WebGPU has not been given here.
-
-Encoding is **grouped**. Runs of adjacent batches that share a pipeline, vertex
-buffers and index buffer hoist those bindings to the run's first batch, as
-Carbon's `RenderBatchGroup` hoists them to a group. Two deliberate differences
-from Carbon: the index buffer is part of the predicate, because Carbon may omit
-it only while every geometry is suballocated from one process-global buffer and
-this engine gives each geometry its own; and runs are derived at encode time
-rather than read from a precomputed partition. Order is never changed — sorting
-belongs to Trinity, and reordering here would break golden-image comparison
-between backends.
-
-Bind groups stay per batch. Every prepared batch creates its own binding set
-even from identical values, which is where per-object data lives, and Carbon
-likewise applies per-object constants per batch.
+<a id="trinity-batch-boundary"></a>
+
+## Harness batch adapter
+
+Separate from live AL submission, the internal
+[dispatcher](../../../src/trinityal/webgpu/core/CjsWebgpuTrinityBatchDispatcher.js)
+consumes nominal `Tr2RenderBatch`, `ITriRenderBatchAccumulator`,
+`TriRenderBatchMap` and an injected `CjsTrinityBatchResolver`. Composition
+validates identities once; subsequent calls are direct. These adapters are not
+public package-root exports.
+
+Resolvers own packages, geometry, textures, samplers and values. The dispatcher
+owns each batch's binding set and rolls it back if draw creation fails.
+Geometry-source batches may receive a complete indexed/non-indexed `draw`
+override; explicit batch arguments remain supported. Unsupported topology and
+incompatible recipes are rejected.
+
+Accumulator vectors retain order, GDPR first, using non-indirect fallback draws.
+Adjacent groups share pipeline/vertex/**index** bindings; bind groups remain
+per batch. Unlike Carbon's precomputed partition, runs are derived at encoding
+time and include index-buffer identity because these geometries need not share
+one global buffer. Sorting remains Trinity's responsibility. See
+[grouping implementation](../../../src/trinityal/webgpu/core/CjsWebgpuEncodeState.js).
+
+Batch maps preserve insertion order. Resolvers receive the same shallow-copied,
+unfrozen preparation context, with numeric `batchType` for map preparation.
+Callers own batch-type meaning, technique/pass selection and compatible passes.
+The synchronous [pass encoder](../../../src/trinityal/webgpu/core/CjsWebgpuTrinityPassEncoder.js)
+accepts an existing caller-supplied command encoder, ordered descriptors and
+prepared-map selections; multiple types may
+share a pass or use separately prepared maps. Configuration must also be
+synchronous. It ends every begun pass, including on failure, but does not own
+attachments, command-buffer completion or submission.
+
+The [harness guide](guides/webgpu-harness.md#synthetic-eve-family-comparisons)
+owns synthetic-family gates. They do not load production EVE assets or establish
+production frequency/scheduling. Decoded-data boundaries remain unchanged when
+format readers move; only the injected reader/material resolver changes.
 
 ## Dynamic uniform offsets
 
-A dynamic binding is bound once and re-aimed per draw through the offsets given
-to `setBindGroup`, which is what lets many objects share one ring buffer instead
-of taking a buffer each. `CreateDraw` accepts `dynamicOffsets` keyed by binding
-identity.
-
-Three rules are enforced because each fails quietly otherwise:
-
-- the bind group's own resource describes the **window** the shader sees, not
-  the whole buffer, since WebGPU adds the per-draw offset to it;
-- offsets are ordered by **binding number within the group**, derived from the
-  layout rather than from the order a caller lists them;
-- a group with dynamic offsets is re-set on **every** draw even when the bind
-  group object is unchanged, because the offsets are exactly what differs
-  between two objects sharing a buffer. Eliding that set would draw them all at
-  the same slot.
+`CreateDraw` takes `dynamicOffsets` keyed by binding identity. Every dynamic
+binding requires a device-limit-aligned offset; missing offsets do not default to zero.
+Package/layout dynamic flags must agree. Bind resources specify the shader's
+**window**, not the whole buffer. The device orders offsets by binding number
+within each group and rebinds dynamic groups on every draw, even if their object
+identity is unchanged. See [offset validation and draw encoding](../../../src/trinityal/webgpu/CjsWebgpuDevice.js).
 
-A missing offset is an error rather than a defaulted zero, which would aim every
-object at the first slot and read as a scene bug. Offsets must respect the
-device's minimum alignment. A binding marked dynamic in the package but not in
-its layout, or the reverse, is rejected at preparation: WebGPU would otherwise
-reject the bind group much later with a message naming neither side.
-
-Storage buffers are caller-owned and bind through `resources` as a
-`GPUBufferBinding`; the engine creates and owns uniform buffers only.
+Storage `GPUBufferBinding` values supplied through `resources` remain caller-owned; this API creates and
+owns uniform buffers only.
 
 ## Textures
 
-The texture adapter accepts uncompressed 8/16/32-bit formats, the BC1–BC7
-block-compressed family, mip chains, 2D, 2D-array, cube and cube-array views.
-That range exists because real EVE textures arrive as DDS carrying
-block-compressed data with full mip chains, and environment probes are cubes.
-
-**Block compression is why the layout is computed rather than assumed.** For an
-uncompressed format a row is `width * bytesPerPixel` and a level is `height`
-rows. For a compressed one both are wrong: `bytesPerRow` counts *block* rows and
-`rowsPerImage` is `ceil(height / 4)`. Passing pixel rows for a BC texture does
-not fail loudly — it uploads a fraction of the data and reads garbage. An
-uncompressed format is expressed as a 1×1 block so there is one code path and
-the compressed case cannot drift from the plain one.
-
-The same rounding keeps a BC mip chain honest: a 1×1 level still occupies a
-whole block, so the tail levels of any chain are the same size, and computing a
-level's footprint from its pixel dimensions alone under-counts them.
-
-Mip chains are stored **layer-major** — each layer's complete chain, then the
-next — because that is how DDS stores an array or a cube. One level across
-layers is therefore not contiguous, so a chain is written per layer per level
-rather than in one call.
-
-BC formats require the `texture-compression-bc` device feature, which is checked
-and named before anything is created rather than left to fail inside
-`createTexture`.
+The adapter supports uncompressed 8/16/32-bit and BC1–BC7 formats, mip chains,
+and 2D, 2D-array, cube and cube-array views. BC requires
+`texture-compression-bc`, checked before creation. Inputs are **layer-major**:
+each layer's complete mip chain. Multi-level chains upload per layer/level;
+single-mip inputs may upload all layers together. Compressed footprints
+use block rows (`ceil(height / 4)`), including a complete block for tiny mip
+levels; uncompressed formats use the same calculation with 1×1 blocks.
+See [texture layout](../../../src/trinityal/webgpu/core/textureLayout.js) and
+[device upload](../../../src/trinityal/webgpu/CjsWebgpuDevice.js).
 
 ## Pipeline caching
 
-Effect realization splits in two. Stage A is program identity and dedup, which
-is backend-independent and belongs upstream. Stage B is the pipeline object,
-which is backend-owned, and this package caches it.
-
-Both caches are keyed **exactly**, on the canonical serialization rather than a
-hash, so two different pipelines cannot collide and there is nothing to recheck.
-That is affordable because a recipe is a small POD block.
-
-Program identity is the **caller's to supply**, through a `PreparePipeline`
-`identity` option. Shader source is too large to serialize into a key on every
-call and this package has no dependency to hash it with. Without an identity a
-pipeline is prepared uncached, which is never wrong, only slower. Deriving one
-from the descriptor's `key` would be worse than no cache: `Main.pass0` is the
-most common pass name in the corpus and never dedupes across effects, so it
-would hand back another effect's pipeline.
-
-Everything is bound to a device generation and dropped on loss, recreation and
-destruction. Racing callers share one build rather than each creating a GPU
-object with one silently winning, and a failed build is not retained, so a
-transient device error does not make a key permanently unbuildable.
-
-## Planning a frame from recorded intents
-
-`PlanFrame` partitions the recorder's ordered intent stream into regions that
-WebGPU will accept. This is the look-ahead the divergence decision permits: the
-executor may plan far enough to form legal passes, provided observable Trinity
-ordering survives it.
-
-It is needed because a render pass has fixed attachments and several things
-Carbon does mid-pass are illegal inside one. Target/depth changes, compute,
-transfer work, and presentation cut regions. A viewport change after render
-work also cuts the current region: WebGPU could change it inside one open pass,
-but the current encoder configures each region once before its selections, so a
-conservative pass cut is the only way to preserve the recorded order.
-
-Viewport state is normalized into a frozen `{ viewport, scissor }` snapshot on
-each render region and persists across target, compute, and transfer boundaries.
-`TriViewport.minZ/maxZ` become WebGPU's `minDepth/maxDepth`. Trinity currently
-has no scissor intent, so `scissor` remains `null` and means the full target.
-Raw render-state assignments, standard-state blocks, and wireframe changes are
-rejected until the engine has a translator that can include them in the actual
-pipeline recipe; retaining those intents while drawing with the previous
-pipeline would be a silent state error.
-
-Clears become attachment load operations. A clear at the head of a region folds
-into its load ops for free; a clear arriving after work in the same region cuts
-a new one and folds into that. No explicit clear operation and no fullscreen
-clear draw is ever required, because cutting a region is always legal.
-
-Order is preserved exactly. Intents are never moved between regions, reordered,
-or merged across a boundary — two render regions separated by compute stay
-separate even though merging them would be cheaper.
-
-An intent type with no planning rule throws. Treating an unknown intent as
-harmless state is how something illegal ends up inside a pass.
-
-The plan is pure: intents in, a plan out, no device and no encoder. That keeps
-the part carrying the rules testable without a browser and leaves encoding
-mechanical.
-
-## Executing a planned frame
-
-`CjsWebgpuFrameExecutor` walks a plan's regions in order, opens the right kind
-of encoder for each, and submits once. Every judgement about what may share a
-pass already happened during planning, so this owns only encoder lifetime and
-region order.
-
-Two things are injected because they are policy rather than mechanism. Which
-prepared batch types belong to a render region is Trinity's meaning, and an
-engine deciding it would be inventing scene structure. Compute and transfer
-regions need resources this module does not own. Both arrive as hooks.
-
-A planned compute or transfer region with no handler **throws**. Skipping it
-would render a frame that looks right and is subtly wrong. A render region that
-resolves to no selections is different — that is a legitimate answer, and
-opening a pass to draw nothing is waste, so it is skipped. A plan that encodes
-nothing submits nothing rather than an empty command buffer.
-
-The canvas texture is acquired once per frame and shared by every region
-resolving to the backbuffer. A region targeting something else needs attachments
-this module does not own, so its descriptor is the caller's to supply.
+For the explicit-descriptor API, program identity/dedup belongs upstream;
+backend pipeline caching belongs here. `PreparePipeline` takes an explicit
+`identity`; omission means uncached preparation. A common descriptor name such
+as `Main.pass0` is not program identity.
+
+The [cache](../../../src/trinityal/webgpu/core/CjsWebgpuPipelineCache.js) uses
+exact canonical keys, not hash-only keys. Entries are generation-bound and
+cleared on loss, recreation and destruction. Concurrent callers share one
+build; failed builds are evicted rather than poisoning the key.
+
+<a id="planning-a-frame-from-recorded-intents"></a>
+<a id="executing-a-planned-frame"></a>
+
+## Current AL draw path
+
+Trinity calls an injected AL through `Tr2RenderContext.SetRenderContextAL`;
+without one it uses the headless stub. The WebGPU implementation is
+`CjsWebgpuRenderContextAL`. It is internal, not a public package-root export;
+repository composition uses the private build entry. The public descriptor API
+above is a separate supported surface, not an AL installation recipe.
+
+1. Trinity's `RenderBatchesInOrder` walks the finalized accumulator, applies
+   standard states, per-object constants, shader pass state and material data,
+   then calls `SubmitGeometry`. The AL receives binding and draw calls, not
+   batches to resolve later. Geometry descriptors are realized at first submit
+   through the context's suballocated buffers.
+2. AL setters retain bound program, render state, declaration, streams and
+   resources. Each draw's `EmitRenderPipelineState` resolves the accumulated
+   description, reuses a cached pipeline or creates one synchronously through
+   `createRenderPipeline`. Unsupported state can still refuse a draw; this
+   path is not evidence that every Carbon rendering feature is implemented.
+3. `CjsWebgpuResourceSetAL` resolves stage/register bindings for the linked
+   program at draw time. Constant buffers retain CPU shadows; the frame's
+   constant arena supplies upload regions and dynamic offsets. Texture resources
+   are realized on first bind. These are AL-owned objects, not a second batch
+   resolver supplied by the application.
+4. `BeginScene` starts the work queue, resets the constant arena and render
+   targets. The queue opens passes lazily and consumes render-pass hints.
+   The canvas view is acquired at the first pass and reused within the frame.
+5. `EndScene` closes the last pass, clears bound program/resource-set/vertex-layout
+   state, finishes and submits the command encoder, and releases the frame view.
+   It is synchronous; no asynchronous batch-preparation phase follows Trinity's
+   render-job execution.
+
+`PlanFrame`, `CjsWebgpuFrameExecutor` and `CjsWebgpuTrinityStepRecorder`
+were removed with the render-intent queue. Do not restore them to integrate a
+backend. Source owners:
+[Trinity context](../../../src/trinity/core/context/Tr2RenderContext.js),
+[WebGPU AL context](../../../src/trinityal/webgpu/CjsWebgpuRenderContextAL.js),
+[resource sets](../../../src/trinityal/webgpu/CjsWebgpuResourceSetAL.js) and
+[work queue](../../../src/trinityal/webgpu/core/CjsWebgpuWorkQueue.js).
 
 ## Attachments and the presentation surface
 
 `CjsWebgpuRenderTarget` owns canvas configuration, the depth and multisample
 attachments, their size, render-pass descriptors, and viewport and scissor. It
 does not own when a frame happens or which passes exist; those belong to the
-executor and to Trinity's steps.
+AL work queue and to Trinity's steps.
 
 Carbon's render context owns a swap chain and a depth-stencil surface. WebGPU's
 model is a pass descriptor with attachments fixed before the pass opens, so this
@@ -304,52 +242,9 @@ surfaces belonging to a device that is gone.
 Clearing is a load operation on an attachment, never a draw, which is what lets
 a later pass over the same target composite by loading instead.
 
-**Presentation is not a call here.** Carbon presents the previous frame at the
-top of the next tick; WebGPU has no present, and the browser presents a
-configured canvas after the submission that drew into its current texture. The
-engine-side tick wrapper therefore has a real presentation step on WebGL and
-nothing to do on WebGPU. That asymmetry is expected, not a missing port.
-
-At the next level it snapshots `TriRenderBatchMap` batch types in insertion
-order and prepares each accumulator. Batch-type meaning and render
-pass selection remain outside the dispatcher: `EncodeBatchType(...)` requires
-the caller to supply the compatible pass for the requested type. This avoids
-turning opaque, decal, transparent, or depth policy into shared device code.
-Every injected material, geometry, and binding resolver receives the same
-preparation context; supplied contexts are shallow-copied but are not frozen. The batch-map path supplies its numeric
-`batchType`, allowing application composition to select the matching effect
-technique without the dispatcher importing or interpreting `TriBatchType`.
-
-The dispatcher is internal and is not exported from the engine subpath. The
-browser harness exercises it through canonical runtime identities while keeping
-fixture construction at an explicit test-only adapter. Static and skinned Quad,
-glass, heat, detail, sails, oil, and decal families provide synthetic package,
-binding, and pixel gates. They retain explicit caller-owned batch-type and pass
-selection, do not load production EVE assets, and make no claim about production
-frequency or scheduling policy. Detailed corpus provenance belongs in the
-private organization documentation rather than the shipped engine contract.
-
-The internal `CjsWebgpuTrinityStepRecorder` proves the synchronous
-`Tr2RenderContext.SetStepExecutor(...)` seam separately. It delegates the
-step's begin, execute, and end hooks back to the GPU-free context, consumes
-`TakeIntents()` exactly once, and records immutable segments in observable
-order. Nested jobs are re-entrant: a child step flushes any parent intents
-emitted before the child, then the parent resumes after the child. WebGPU
-pipeline preparation, pass creation, encoding, and submission remain a later
-asynchronous phase; none run inside Trinity's synchronous `Run(...)`.
-
-The internal `CjsWebgpuTrinityPassEncoder` proves the synchronous encoding end
-of that split. A caller supplies an existing command encoder plus ordered
-render-pass descriptors and prepared batch-map selections. Multiple batch
-types may share one pass, and separately prepared maps may be selected when a
-different technique is required. Optional synchronous pass configuration can
-set viewport or other dynamic state. The encoder ends every pass it begins but
-does not own attachments, finish command buffers, submit work, or assign EVE
-meaning to a batch type.
-
-The contract consumes already-decoded pipeline data. Moving shader format
-readers between format and resource packages therefore does not change this
-boundary; only the injected reader or material resolver changes.
+The browser presents a configured canvas after submission. This does not
+remove Trinity's presentation verbs; the AL submission lifecycle is described
+above.
 
 ## Current non-goals
 
@@ -358,14 +253,12 @@ it consumes. It does not import `core`, which remains the composition root. The
 engine does not load GR2 or CMF geometry, resolve resource paths, extract scene
 state, choose production material or per-object values, translate complete
 Carbon render state, infer batch-type pass policy, or schedule a render loop.
-Render-job intents are recorded through the nominal Trinity executor contract
-and realized later by engine-owned planning and encoding.
-
-The public engine texture adapter uploads explicit pixel data as described under
-*Textures* above: uncompressed 8/16/32-bit and BC1–BC7 formats, mip chains, 2D,
-2D-array, cube and cube-array views. The standalone harness may still create
-harness-owned native resources when a shader contract requires a shape outside
-that adapter.
+Trinity executes render jobs and calls the AL directly; the backend does not
+consume a retained Trinity intent stream.
+
+The public texture adapter accepts the explicit inputs listed under
+[Textures](#textures). Harness-owned native resources may cover shapes outside
+that adapter; they do not extend its public contract.
 
 ## Related documentation
 

package/docs/trinityal/webgpu/reference/api.md

@@ -57,11 +57,11 @@ pipeline and one set of buffer bindings.
 Geometry resolution may additionally supply a validated `draw` override when
 the neutral batch carries an area range but no realized draw arguments.
 
-`CjsWebgpuTrinityStepRecorder` is another internal conformance component. It
-extends `CjsDirectTrinityStepExecutor`, is installed through
-`Tr2RenderContext.SetStepExecutor(...)`, preserves nested render-step intent
-order, and defers asynchronous WebGPU work until after the synchronous
-render-job run.
+The live Trinity integration instead uses the internal
+`CjsWebgpuRenderContextAL`; see the [AL draw path](../architecture.md#current-al-draw-path).
+Trinity applies batches and materials, then issues binding/draw calls to the AL.
+The former step recorder and render-intent replay path have been removed.
+The AL classes are not exported from this public package root.
 
 `CjsWebgpuTrinityPassEncoder` synchronously encodes caller-authored pass
 descriptors and prepared batch-map selections into an existing command

package/docs/trinityal/webgpu/reference/classes/README.md

@@ -21,7 +21,7 @@ WebGPU behind Carbon's abstraction layer: holds the bound geometry and program s
 Owns the encoder lifetime for one frame, opening a render pass lazily on the work that needs one and folding the declared pass hint into its attachments.
 
 - Export: Not exported
-- Source: `src/trinityal/webgpu/core/workQueue.js`
+- Source: `src/trinityal/webgpu/core/CjsWebgpuWorkQueue.js`
 - Visibility: Internal
 - Kind: Carbon
 
@@ -131,7 +131,7 @@ Immutable WebGPU-facing sampler binding descriptor.
 Per-render-pass record of bound pipeline and buffers, so a grouped run's later batches skip redundant sets.
 
 - Export: Not exported
-- Source: `src/trinityal/webgpu/core/batchGroups.js`
+- Source: `src/trinityal/webgpu/core/CjsWebgpuEncodeState.js`
 - Visibility: Internal
 - Kind: CarbonEngineJS
 
@@ -141,7 +141,7 @@ Per-render-pass record of bound pipeline and buffers, so a grouped run's later b
 Generation-bound cache of asynchronously built pipeline objects, keyed exactly rather than by hash.
 
 - Export: Not exported
-- Source: `src/trinityal/webgpu/core/pipelineCache.js`
+- Source: `src/trinityal/webgpu/core/CjsWebgpuPipelineCache.js`
 - Visibility: Internal
 - Kind: CarbonEngineJS
 
@@ -151,7 +151,7 @@ Generation-bound cache of asynchronously built pipeline objects, keyed exactly r
 Owns the presentation surface, depth and multisample attachments, pass descriptors, viewport and scissor.
 
 - Export: Not exported
-- Source: `src/trinityal/webgpu/core/renderTarget.js`
+- Source: `src/trinityal/webgpu/core/CjsWebgpuRenderTarget.js`
 - Visibility: Internal
 - Kind: CarbonEngineJS
 
@@ -161,7 +161,7 @@ Owns the presentation surface, depth and multisample attachments, pass descripto
 Engine-side adapter for canonical Trinity render batches.
 
 - Export: Not exported
-- Source: `src/trinityal/webgpu/core/trinityBatchDispatcher.js`
+- Source: `src/trinityal/webgpu/core/CjsWebgpuTrinityBatchDispatcher.js`
 - Visibility: Internal
 - Kind: CarbonEngineJS
 
@@ -171,7 +171,7 @@ Engine-side adapter for canonical Trinity render batches.
 Internal encoder for caller-owned WebGPU pass plans over prepared Trinity batch maps.
 
 - Export: Not exported
-- Source: `src/trinityal/webgpu/core/trinityPassEncoder.js`
+- Source: `src/trinityal/webgpu/core/CjsWebgpuTrinityPassEncoder.js`
 - Visibility: Internal
 - Kind: CarbonEngineJS
 
@@ -181,7 +181,7 @@ Internal encoder for caller-owned WebGPU pass plans over prepared Trinity batch
 Resolves a Trinity batch to a WebGPU pipeline, device geometry and the bindings the pipeline declares.
 
 - Export: Not exported
-- Source: `src/trinityal/webgpu/core/trinityBatchResolver.js`
+- Source: `src/trinityal/webgpu/core/CjsWebgpuTrinityBatchResolver.js`
 - Visibility: Internal
 - Kind: CarbonEngineJS
 
@@ -191,7 +191,7 @@ Resolves a Trinity batch to a WebGPU pipeline, device geometry and the bindings
 Realizes an authored texture path into a device texture, once per resource.
 
 - Export: Not exported
-- Source: `src/trinityal/webgpu/core/textureSource.js`
+- Source: `src/trinityal/webgpu/core/CjsWebgpuTextureSource.js`
 - Visibility: Internal
 - Kind: CarbonEngineJS
 
@@ -201,7 +201,7 @@ Realizes an authored texture path into a device texture, once per resource.
 Creates and shares device samplers, keyed on authored sampler state rather than on a binding name.
 
 - Export: Not exported
-- Source: `src/trinityal/webgpu/core/samplerSource.js`
+- Source: `src/trinityal/webgpu/core/CjsWebgpuSamplerSource.js`
 - Visibility: Internal
 - Kind: CarbonEngineJS
 
@@ -211,7 +211,7 @@ Creates and shares device samplers, keyed on authored sampler state rather than
 Supplies the packed per-frame constant bytes for a frame slot, which the scene owns rather than the batch.
 
 - Export: Not exported
-- Source: `src/trinityal/webgpu/core/perFrameSource.js`
+- Source: `src/trinityal/webgpu/core/CjsWebgpuPerFrameSource.js`
 - Visibility: Internal
 - Kind: CarbonEngineJS
 
@@ -251,7 +251,7 @@ A `Tr2ShaderAL` that compiles its bytecode, which here is WGSL text, into a `GPU
 A `Tr2ShaderProgramAL` holding validated stages and answering for their modules, since WebGPU has no link step.
 
 - Export: Not exported
-- Source: `src/trinityal/webgpu/CjsWebgpuShaderAL.js`
+- Source: `src/trinityal/webgpu/CjsWebgpuShaderProgramAL.js`
 - Visibility: Internal
 - Kind: Carbon
 
@@ -261,7 +261,7 @@ A `Tr2ShaderProgramAL` holding validated stages and answering for their modules,
 DX12's `PSODescription` for WebGPU: the pipeline state the abstraction layer's setters describe incrementally, resolved to one cached pipeline by a canonical key.
 
 - Export: Not exported
-- Source: `src/trinityal/webgpu/core/psoDescription.js`
+- Source: `src/trinityal/webgpu/core/CjsWebgpuPsoDescription.js`
 - Visibility: Internal
 - Kind: Carbon
 
@@ -281,7 +281,7 @@ A `Tr2ConstantBufferAL` that owns a CPU shadow and an upload token, as Metal's d
 Carbon's `ConstantBufferAllocator`: the per-frame constant arena of 2 MiB pages, reset at the start of every frame, that gives each draw its own snapshot of every constant buffer bound for it.
 
 - Export: Not exported
-- Source: `src/trinityal/webgpu/core/constantArena.js`
+- Source: `src/trinityal/webgpu/core/CjsWebgpuConstantArena.js`
 - Visibility: Internal
 - Kind: Carbon
 

package/format-notices/gr2/NOTICE

@@ -1,7 +1,8 @@
-carbonenginejs/format-gr2
-=========================
+GR2 / Granny reader - @carbonenginejs/runtime
+=============================================
 
-A pure-JavaScript reader for RAD Game Tools' Granny 3D (.gr2) file format.
+A pure-JavaScript reader for RAD Game Tools' Granny 3D (.gr2) file format,
+under `src/resource/formats/gr2`.
 Contains no RAD/Granny code and does not link granny2.dll. Section decompression
 is reimplemented from clean-room / open reverse-engineering efforts, listed below.
 
@@ -11,11 +12,16 @@ semantics remain copyright their original CarbonEngine authors.
 Fenris Creations (CCP Games) source material, tools, assets, shader behavior,
 and EVE-related data remain copyright their original holders.
 
-Current repository license: MIT. See LICENSE.
+Current repository license: MIT. See LICENSE.
+
+This reader was migrated from the former `carbonenginejs/format-gr2` package
+into `@carbonenginejs/runtime`; that repository now only forwards here. Paths
+below are the reader's CURRENT locations, so every claim can be checked against
+the file it names.
 
 The former EUPL-derived BitKnit implementation was replaced on 2026-07-24 by
-an original clean-room implementation written solely from this package's
-published format specification (docs/formats/bitknit2.md); no EUPL-derived
+an original clean-room implementation written solely from the published
+format specification (docs/resource/formats/bitknit2.md); no EUPL-derived
 code remains.
 
 Provenance and legal requirements
@@ -35,24 +41,24 @@ Games.
 Third-party algorithm provenance
 --------------------------------
 
-Oodle1 / Oodle0 section decompressor (src/codecs/oodle1.js)
+Oodle1 / Oodle0 section decompressor (src/resource/formats/gr2/core/oodle1.js)
   Ported from the open Granny2 decompressors:
     - nwn2mdk  "gr2_decompress"        (Boost Software License 1.0)
     - arves100/opengr2  "oodle1.c"     (MPL-2.0)   https://github.com/arves100/opengr2
   This is Granny's own legacy codec, not RAD's modern Oodle (Kraken/BitKnit families).
 
-BitKnit / BitKnit2 section decompressor (src/core/bitknit2.js)
+BitKnit / BitKnit2 section decompressor (src/resource/formats/gr2/core/bitknit2.js)
   Original CarbonEngineJS clean-room implementation (2026-07-24), written
-  solely from this package's published format specification
-  (docs/formats/bitknit2.md) by an isolated implementer, and validated
+  solely from the published format specification
+  (docs/resource/formats/bitknit2.md) by an isolated implementer, and validated
   byte-exact against the EVE .gr2 corpus. It replaced a prior port of
   neptuwunium/Knit (EUPL-1.2); no code from Knit, pybg3, ooz, or any other
   BitKnit implementation remains. See THIRD-PARTY-NOTICES.md.
 
-Granny curve decompression (src/curves/**, optional; enabled via decompressCurves)
+Granny curve decompression (src/resource/formats/gr2/core/curves.js, optional; enabled via decompressCurves)
   Adapted from cppctamber's granny extension for ccpwgl2 (src/core/reader/granny/curves).
 
-Container / relocation / type-tree reflection (src/container.js, src/reader.js)
+Container / relocation / type-tree reflection (src/resource/formats/gr2/core/container.js, src/resource/formats/gr2/core/reader.js)
   Original to this project, derived from the on-disk Granny GRN format layout
   (cross-referenced with the Granny SDK headers and the above projects' docs).