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

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

@@ -1,7 +1,7 @@
 # Class catalog
 
 Status: Evolving  
-Scope: `@carbonenginejs/runtime/resource` classes
+Scope: `@carbonenginejs/runtime/resource` classes
 Audience: Users, maintainers, and automated readers  
 Summary: Indexes the one-sentence purpose descriptors for every maintained class in the package.
 
@@ -29,6 +29,8 @@ documentation check against the actual source tree.
   classes in the `src/resource` family tree.
 - [texture.md](texture.md): texture-array aggregation classes under
   `src/resource/texture`.
+- [video.md](video.md): the video player metadata, frame and decoder-boundary
+  classes ported from Carbon's videoplayer module.
 - [formats.md](formats.md): format entry classes and their internal reader
   machinery under `src/resource/formats`.
 - [dropped.md](dropped.md): retained native shapes under `src/resource/dropped` that

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

@@ -1,7 +1,7 @@
 # Dropped class catalog
 
 Status: Evolving  
-Scope: `@carbonenginejs/runtime/resource` classes under `src/resource/dropped`
+Scope: `@carbonenginejs/runtime/resource` classes under `src/resource/dropped`
 Audience: Users, maintainers, and automated readers  
 Summary: Provides one-sentence purpose descriptors for retained-only Carbon reference shapes that are never exported or bundled.
 
@@ -44,3 +44,23 @@ Retained-only reference shape mirroring Carbon's two-queue load/prepare fence he
 - Source: `src/resource/dropped/Tr2LoadPrepareFence.js`
 - Visibility: Internal
 - Kind: Faithful Carbon port
+
+<!-- class:FrameDeleter -->
+## `FrameDeleter`
+
+Carbon's unique_ptr frame deleter, which returns a finished video or audio frame to its pool or deletes it, dropped because JavaScript reclaims frames without that decision.
+
+- Export: None
+- Source: `src/resource/dropped/FrameDeleter.js`
+- Visibility: Internal
+- Kind: Faithful Carbon port
+
+<!-- class:FrameOwner -->
+## `FrameOwner`
+
+Carbon's frame-pool owner interface, whose one ReleaseFrame method gives a frame back to the decoder that made it, dropped because a JavaScript decoder that recycles buffers keeps its own free list.
+
+- Export: None
+- Source: `src/resource/dropped/FrameOwner.js`
+- Visibility: Internal
+- Kind: Faithful Carbon port

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

@@ -637,6 +637,28 @@ Exposes the verified inline modern cFSD layout for factions records through `get
 - Visibility: Public
 - Kind: CarbonEngineJS
 
+<!-- class:CjsFsd64SchemaFrontierGraphicIds -->
+## `CjsFsd64SchemaFrontierGraphicIds`
+
+Exposes the verified inline modern cFSD layout for EVE Frontier's graphic ids records through `getFsdSchema()`.
+
+- Export: `@carbonenginejs/runtime/resource/formats/fsd/64/readers`
+- Source: `src/resource/formats/fsd/64/readers/CjsFsd64SchemaFrontierGraphicIds.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+- Notes: A separate pinned layout, not a version of `CjsFsd64SchemaGraphicIds`: the record is 168 bytes rather than 160 and carries a presence word the EVE one does not have.
+
+<!-- class:CjsFsd64SchemaFrontierTypes -->
+## `CjsFsd64SchemaFrontierTypes`
+
+Exposes the verified inline modern cFSD layout for EVE Frontier's types records through `getFsdSchema()`.
+
+- Export: `@carbonenginejs/runtime/resource/formats/fsd/64/readers`
+- Source: `src/resource/formats/fsd/64/readers/CjsFsd64SchemaFrontierTypes.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+- Notes: A separate pinned layout, not a version of `CjsFsd64SchemaTypes`: the record is 136 bytes rather than 152, and it carries `tags` while dropping the fields Frontier has no use for.
+
 <!-- class:CjsFsd64SchemaGraphicIds -->
 ## `CjsFsd64SchemaGraphicIds`
 
@@ -1402,6 +1424,17 @@ Construction-bound decoder for the inert data subset of Python pickle protocol 0
 - Visibility: Internal
 - Kind: Internal implementation class
 
+<!-- class:CjsPickleProtocol4Reader -->
+## `CjsPickleProtocol4Reader`
+
+Construction-bound decoder for the inert data subset of Python pickle's binary protocols, 1 through 4.
+
+- Export: `None`
+- Source: `src/resource/formats/pickle/core/CjsPickleProtocol4Reader.js`
+- Visibility: Internal
+- Kind: Internal implementation class
+- Notes: Shares every refusal rule with `CjsPickleProtocol0Reader` through `pickleCommon`, and owns only how the binary protocols spell their opcodes.
+
 ### png
 
 <!-- class:CjsPngFormat -->

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/classes/video.md

@@ -0,0 +1,92 @@
+# Video class catalog
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime/resource` classes under `src/resource/video`
+Audience: Users, maintainers, and automated readers
+Summary: Provides one-sentence purpose descriptors for the video player's metadata, frame and decoder-boundary classes ported from Carbon's videoplayer module.
+
+Carbon decodes video with vendored libraries (libvpx through `VpxDecoder`,
+nestegg through `WebMParser`, Vorbis through `VorbisDecoder`), none of which is
+Carbon-authored and none of which a browser can link. The interfaces below are
+the boundary those decoders sit behind, so a browser decoder can take their
+place; the classes carrying frames and metadata are ported as they are.
+
+<!-- class:AudioMetadata -->
+## `AudioMetadata`
+
+What a container parser reports about an audio track: codec, channels, bits per sample, sample rate, and the codec's setup bytes, whose owning record Carbon nests and this port flattens to one typed array.
+
+- Export: `@carbonenginejs/runtime/resource`
+- Source: `src/resource/video/AudioMetadata.js`
+- Visibility: Public
+- Kind: Faithful Carbon port
+
+<!-- class:IAudioSink -->
+## `IAudioSink`
+
+Where decoded PCM goes, and the clock video follows when audio is present, leaving the concrete sink to whoever owns audio output.
+
+- Export: `@carbonenginejs/runtime/resource`
+- Source: `src/resource/video/IAudioSink.js`
+- Visibility: Public
+- Kind: Faithful Carbon port
+
+<!-- class:IEncodedFrame -->
+## `IEncodedFrame`
+
+One encoded audio or video packet as a container parser emits it, returning its bytes directly where Carbon uses out-parameters.
+
+- Export: `@carbonenginejs/runtime/resource`
+- Source: `src/resource/video/IEncodedFrame.js`
+- Visibility: Public
+- Kind: Faithful Carbon port
+
+<!-- class:IVideoContainerParser -->
+## `IVideoContainerParser`
+
+The boundary a container reader sits behind: track metadata, duration and download progress, seeking, and the encoded queues its decoders drain.
+
+- Export: `@carbonenginejs/runtime/resource`
+- Source: `src/resource/video/IVideoContainerParser.js`
+- Visibility: Public
+- Kind: Faithful Carbon port
+
+<!-- class:IVideoDecoder -->
+## `IVideoDecoder`
+
+The boundary a video decoder sits behind: the queue it publishes decoded frames to, the time before which undecoded frames may be dropped, and its error state.
+
+- Export: `@carbonenginejs/runtime/resource`
+- Source: `src/resource/video/IVideoDecoder.js`
+- Visibility: Public
+- Kind: Faithful Carbon port
+
+<!-- class:PcmFrame -->
+## `PcmFrame`
+
+One decoded audio frame with its presentation time and interleaved samples, held in a typed array where Carbon allocates them immediately after the struct.
+
+- Export: `@carbonenginejs/runtime/resource`
+- Source: `src/resource/video/PcmFrame.js`
+- Visibility: Public
+- Kind: Faithful Carbon port
+
+<!-- class:VideoFrame -->
+## `VideoFrame`
+
+One decoded frame with its size, presentation time, four-byte-per-pixel BGRA bytes and average colour, which the player pushes into a texture and onto its average-colour field.
+
+- Export: `@carbonenginejs/runtime/resource`
+- Source: `src/resource/video/VideoFrame.js`
+- Visibility: Public
+- Kind: Faithful Carbon port
+
+<!-- class:VideoMetadata -->
+## `VideoMetadata`
+
+What a container parser reports about a video track: codec, frame size, and whether it carries alpha.
+
+- Export: `@carbonenginejs/runtime/resource`
+- Source: `src/resource/video/VideoMetadata.js`
+- Visibility: Public
+- Kind: Faithful Carbon port

package/docs/resource/reference/events.md

@@ -1,13 +1,13 @@
 # Event emitter contract
 
 Status: Evolving  
-Scope: `@carbonenginejs/runtime/resource`
+Scope: `@carbonenginejs/runtime/resource`
 Audience: Users and integrators  
 Summary: Defines the `CjsEventEmitter` API surface used by resource managers and the memory rules that keep listeners from leaking graphs.
 
 ## Purpose
 
-`CjsEventEmitter` (from `global/model`) is a separate base class so
+`CjsEventEmitter` (from `global/model`) is a separate base class so
 non-model runtime services can emit events without extending `CjsModel`;
 `CjsResMan` uses that path. CarbonEngineJS exposes one small event-emitter API
 and avoids short generic names such as `On`, `Once`, `Off`, and `Emit` on
@@ -88,7 +88,7 @@ scene/resource graphs alive. The contract is therefore:
   entry; `target.OffEvent("*", null, source)` removes all of a source's
   records. An external party that no longer observes a target must call
   `OffEvent()`.
-- Payload release and manager-owned purge do not imply listener destruction.
+- Payload release and manager-owned purge do not imply listener destruction.
 - `OnEvent()` returns the emitter; it does not return unsubscribe closures,
   because those closures create another reference path.
 - Deterministic cleanup is the contract; `WeakRef`/`FinalizationRegistry` may
@@ -96,17 +96,18 @@ scene/resource graphs alive. The contract is therefore:
 
 Multiple listeners on the same event are allowed because each event bucket is
 a set of records. A raw `CjsEventEmitter` does not gain model-owned `dirty`
-or `rebuild` state. The target is "easy to debug, hard to leak": clear
+state. The target is "easy to debug, hard to leak": clear
 ownership of who subscribed, who unsubscribes, and which cleanup phase clears
 remaining listeners.
 
 ## Relationship to model dirty state
 
-`CjsModel`'s `MarkDirty` and `ClearDirty` concern model invalidation. `SetValues()` marks dirty
-only when field values change. Plain `MarkDirty()` requests broad invalidation,
-not rebuilding; deferred rebuild reasons use the independent
-`model.__state.rebuild` set. Resource lifecycle events remain separate,
-owned by resources and ResMan.
+`CjsModel`'s `MarkDirty` and `ClearDirty` concern values-transport settlement.
+Changed notified members are queued by `SetValues`; each class owns its actual
+rebuild actions, dirty latches and clearing rules. There is no generic
+`model.__state.rebuild` set. Resource lifecycle events remain separate, owned
+by resources and ResMan. See [model lifecycle](../../global/concepts/model-lifecycle.md)
+for the current batching and explicit-update compatibility behavior.
 
 ## Related documentation
 

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,35 @@ 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.
+
+Carbon's other procedural texture, `dynamic:/gradient_1d/<base64>`, is registered
+by `RegisterGradientTexture(resMan)` from `@carbonenginejs/runtime/trinity/core`.
+It lives in trinity because rasterizing its four scalar curves needs
+`Tr2CurveScalar`, which the resource layer may not import; the path carries a
+base64 header plus curve keys, and an unreadable one fails the texture the same
+way.
+
 ## Related documentation
 
 - [Resource lifecycle concepts](../concepts/resource-lifecycle.md)

package/docs/trinity/README.md

@@ -23,12 +23,12 @@ Use `@carbonenginejs/runtime/trinity` when code needs to:
 
 - hydrate or serialize Trinity and Eve graph objects;
 - update curves, controllers, cameras, scene objects, or effects on the CPU;
-- collect render batches and render-job intents for an engine to realize;
+- collect render batches and render-job intents;
 - inspect schema-decorated fields and enum choices; or
 - build a headless tool that must not depend on WebGL or WebGPU.
 
-Use an engine package when code needs device creation, shader realization,
-resource uploads, draw submission, presentation, or device-loss recovery.
+Backend implementations live in `src/trinityal`. The stub is one of them, which
+is what lets this package run with no GPU attached.
 
 ## Where it fits
 
@@ -48,8 +48,8 @@ schema and generated-class input, not a runtime dependency.
 `Tr2EffectRes`, canonical `Tr2Shader`/reflection records, portable hydration,
 permutation selection, and shader caching. Trinity owns the mutable
 `Tr2Effect`/`Tr2Material` facade, parameters, authored options, sampler
-overrides, and graph behavior. Engine packages own live backend objects and
-realize the combined renderer-neutral graph.
+overrides, and graph behavior. Backend layers implement the AL these
+classes call; attaching the stub is what makes a GPU-free run possible.
 
 Character GState behavior belongs to `@carbonenginejs/runtime/character`.
 Applications or `@carbonenginejs/runtime/core` compose these domains.