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

package/docs/resource/architecture.md

@@ -1,116 +1,156 @@
-# Architecture and boundaries
-
-Status: Evolving  
+# Architecture and boundaries
+
+Status: Evolving  
 Scope: `@carbonenginejs/runtime/resource`
-Audience: Users and integrators  
-Summary: Defines the GPU-free boundary this package owns and how engine and runtime packages relate to it.
-
-## The GPU-free split
-
-The `resource` layer owns the GPU-free half of the Carbon resource lifecycle:
-
-```text
-EMPTY -> REQUESTED/LOADING -> LOADED
-```
-
-Engine adapters own device realization:
-
-```text
-LOADED -> PREPARING -> PREPARED
-```
-
-The package selects and runs registered readers, hydrates or returns the
-promised CPU outcome, and stores lifecycle state, cache entries, and loaded
-payloads. For compiled effects it independently validates complete permutation
-topology and the Carbon v15 container records it read itself, selects a
-permutation, and hydrates a canonical device-free `Tr2Shader` graph. It never
-creates WebGL/WebGPU textures, buffers, shader modules, pipelines, or bind
-groups, and it never inspects backend capability.
-A realization failure destroys its candidate and returns the resource to
-`LOADED` without discarding the valid CPU payload.
-
-This deliberately differs from Carbon and ccpwgl, whose resource classes live
-inside an engine that can prepare GPU objects directly. Keeping the
-format/resource layer reusable means stopping before GPU work; see
-[resource lifecycle concepts](concepts/resource-lifecycle.md) for the
-historical mapping.
-
-## What the package owns
-
-- `CjsResource` state and Carbon-style resource methods.
-- `CjsMotherLode` canonical identity, explicit replacement results, activity
-  and lock metadata, deterministic payload/adapter cleanup, and cache stats.
-- `CjsResMan` extension-selected resource/object handlers, semantic resource
-  overrides, ordered and legacy registered-format selection,
-  concurrency-limited source loading, staged prepare queues, layered
-  source/read/resource deduplication, object loader dispatch, and prefetch.
-- Main-thread and browser-worker resource execution strategies, including
-  transferable fetch results and declared worker-safe CPU readers.
-- `CjsTextureArrayRes` and `CjsTextureArrayResParameterProxy` for material-facing,
-  frame-coalesced texture-array inputs.
-- `CjsAudioBufferRes` for physical audio-byte ownership and `CjsAudioRes` for
-  complete or windowed individually addressable audio files.
+Audience: Users and integrators  
+Summary: Defines the resource lifecycle this package owns and how it reaches the graphics abstraction layer.
+
+## The resource lifecycle
+
+The `resource` layer owns the whole Carbon resource lifecycle, load and
+prepare both:
+
+```text
+EMPTY -> REQUESTED/LOADING -> LOADED -> PREPARING -> PREPARED
+```
+
+Carbon does the same. A resource prepares itself: `BlueAsyncRes` carries the
+`m_isPrepared` flag (`blue/include/BlueAsyncRes.h:87-166`) and the concrete
+resource implements `OnPrepareResources` (`TriTextureRes.h:124`,
+`TriGeometryRes.h:353`, `Tr2EffectRes.h:53`). There is no layer between the
+resource and the device in Carbon, and there is none here.
+
+The package selects and runs registered readers, hydrates or returns the
+promised CPU outcome, and stores lifecycle state, cache entries, and loaded
+payloads. For compiled effects it independently validates complete permutation
+topology and the Carbon v15 container records it read itself, selects a
+permutation, and hydrates a canonical `Tr2Shader` graph.
+A prepare failure destroys its candidate and returns the resource to
+`LOADED` without discarding the valid CPU payload.
+
+GPU work goes through the abstraction layer in `src/trinityal`, exactly as
+Carbon's resources call its AL. Headlessness is what the stub backend is for:
+running without a device means selecting the stub, never hollowing a resource
+class out. A resource method left empty so that something else can do its work
+is a gap to be closed, not a boundary.
+
+The divergences that remain are the ones the browser forces: adapter
+acquisition, `mapAsync`, shader-module and pipeline creation, `fetch`, and
+image and video decode are asynchronous where Carbon's are not. Each carries
+its own `@impl.reason` at the site. "An engine owns this" is not one of them.
+
+## What the package owns
+
+- `CjsResource` state and Carbon-style resource methods.
+- `CjsMotherLode` canonical identity, explicit replacement results, activity
+  and lock metadata, deterministic payload/adapter cleanup, and cache stats.
+- `CjsResMan` extension-selected resource/object handlers, semantic resource
+  overrides, ordered and legacy registered-format selection,
+  concurrency-limited source loading, staged prepare queues, layered
+  source/read/resource deduplication, object loader dispatch, and prefetch.
+- Main-thread and browser-worker resource execution strategies, including
+  transferable fetch results and declared worker-safe CPU readers.
+- `CjsTextureArrayRes` and `CjsTextureArrayResParameterProxy` for material-facing,
+  frame-coalesced texture-array inputs.
+- `CjsAudioBufferRes` for physical audio-byte ownership and `CjsAudioRes` for
+  complete or windowed individually addressable audio files.
 - Raw `CjsEventEmitter` (from `global/model`) for manager/runtime events
-  without requiring `CjsModel` inheritance.
-- Resource-path normalization and URL resolution, including prefix bases and
-  an injectable complete resolver, with fetch execution delegated to a
-  URL-only provider.
-- Resource-specific geometry traversal and payload adaptation, composed with
-  shared vector, matrix, bounds, sphere, ray, and mesh math from
+  without requiring `CjsModel` inheritance.
+- Resource-path normalization and URL resolution, including prefix bases and
+  an injectable complete resolver, with fetch execution delegated to a
+  URL-only provider.
+- Resource-specific geometry traversal and payload adaptation, composed with
+  shared vector, matrix, bounds, sphere, ray, and mesh math from
   the shared `global` layer rather than maintaining another math implementation here.
-- Plain reader/converter payload objects with focused shared validators.
-- Canonical Carbon resource classes that validate and hold CPU payloads
-  privately: `TriTextureRes`, `TriGeometryRes`, `Tr2EffectRes`, `Tr2ImageRes`,
-  `TriGrannyRes`, `Tr2GrannyStateRes`, and `Tr2LightProfileRes`.
-- Canonical device-free shader/reflection classes: `Tr2Shader`, its effect,
-  technique, pass, stage, constant, resource, sampler, annotation, and library
-  records; Carbon-binary hydration; permutation selection; and per-index caching.
-- `Tr2TexturePipeline` CPU-only texture steps and `Tr2TextureLodManager`
-  membership.
-- Opaque engine-owned subobject slots for backend adapters.
-- Format implementations as explicit tree-shakeable subpaths under
-  `@carbonenginejs/runtime/resource/formats/<name>`.
-- Acquisition-free FSD byte validation, schema decoding, and approved dataset
-  readers under `formats/fsd`. The format keeps separate `32` and `64`
-  implementation directories: legacy headerless FSD is identified explicitly
-  but is not yet decoded, while modern cFSD uses the 64-bit implementation.
-
-## What the package does not own
-
-- WebGL/WebGPU realization, allocations, upload accounting, device budgets,
-  capability limits, and device-loss recovery (engine packages).
-- Shader binary decoding, backend translation, and package serialization live
+- Plain reader/converter payload objects with focused shared validators.
+- Canonical Carbon resource classes that validate and hold CPU payloads
+  privately: `TriTextureRes`, `TriGeometryRes`, `Tr2EffectRes`, `Tr2ImageRes`,
+  `TriGrannyRes`, `Tr2GrannyStateRes`, and `Tr2LightProfileRes`.
+- Canonical device-free shader/reflection classes: `Tr2Shader`, its effect,
+  technique, pass, stage, constant, resource, sampler, annotation, and library
+  records; Carbon-binary hydration; permutation selection; and per-index caching.
+- `Tr2TexturePipeline` CPU-only texture steps and `Tr2TextureLodManager`
+  membership.
+- Opaque engine-owned subobject slots for backend adapters.
+- Format implementations as explicit tree-shakeable subpaths under
+  `@carbonenginejs/runtime/resource/formats/<name>`.
+- Acquisition-free FSD byte validation, schema decoding, and approved dataset
+  readers under `formats/fsd`. The format keeps separate `32` and `64`
+  implementation directories: legacy headerless FSD is identified explicitly
+  but is not yet decoded, while modern cFSD uses the 64-bit implementation.
+
+## What the package does not own
+
+- Backend allocation, upload accounting, device budgets, capability limits,
+  and device-loss recovery. These belong to the abstraction layer in
+  `src/trinityal/<backend>`, which resource classes call; Carbon's resources
+  call its AL the same way.
+- Shader binary decoding, backend translation, and package serialization live
   in the explicit `@carbonenginejs/runtime/resource/formats/{hlsl,dxbc,webgl,webgpu}` subpaths.
-  Backend shader objects remain in engine packages.
-- AudioBuffer construction, playback, or audio manager behavior.
-- Audio-library document construction, enrichment, media-ID interpretation,
-  and delivery-route selection.
-
-## Package relationships
-
+  Backend shader objects are allocated by the abstraction layer.
+- AudioBuffer construction, playback, or audio manager behavior.
+- Audio-library document construction, enrichment, media-ID interpretation,
+  and delivery-route selection.
+
+## Package relationships
+
 - The `core` layer may configure and expose a `CjsResMan`, but does not own its
-  implementation.
-- The `trinity` and `sof` layers may request GPU-free objects and
-  resources without selecting an engine. Trinity owns the mutable
-  `Tr2Effect`/`Tr2Material` facade, parameters, options, and sampler overrides;
-  it consumes the resource-owned shader graph.
-- The `trinityal/webgpu` layer and any future WebGL engine layer consume loaded resources and own
-  all backend allocations, preparation, replacement, and destruction.
-
+  implementation.
+- The `trinity` and `sof` layers may request resources directly, as Carbon's
+  do. With the stub backend selected they run headless. Trinity owns the mutable
+  `Tr2Effect`/`Tr2Material` facade, parameters, options, and sampler overrides;
+  it consumes the resource-owned shader graph.
+
+### What Trinity needs from this layer
+
+One thing: somewhere to ask for a res file. Not an adapter, not an injected
+seam.
+
+Carbon settles this across a repository boundary, which is a stronger test than
+ours. `blue` and `trinity` are separate repositories, and `trinity` takes
+exactly one header from the manager's: `IBlueResMan.h`, through `StdAfx.h:54`.
+It then calls the global `BeResMan` (`IBlueResMan.h:135`) at 94 sites, for
+example `BeResMan->GetResource( profilePath, L"lp", lightProfile )`
+(`EveBannerSet.cpp:63`, `EveHazeSet.cpp:52`, `EvePlaneSet.cpp:40`), and holds
+the result as an ordinary member. No indirection is introduced for the
+crossing.
+
+The resource CLASSES are not what crosses. In Carbon they live with their
+consumer - `TriGeometryRes`, `TriTextureRes`, `Tr2EffectRes` and
+`Tr2LightProfileRes` are all in `trinity/trinity/Resources/`, while `blue` owns
+only the manager and the async base (`BlueResMan`, `BlueAsyncRes`,
+`IBlueResource`). Carbon's audio repository goes further and never involves the
+manager at all, reading its own bytes through a Wwise IO hook.
+
+We arrange this differently: the manager and the resource classes are one layer
+here, below `trinity`. `layers.json` lets `trinity` import `resource`, so a
+Trinity class may hold a `TriGeometryRes` exactly as Carbon's does - these are
+small records, and holding one is not a layering event. `Tr2Mesh` and
+`Tr2TexturedPointLight` already work this way, through `CjsResMan.GetGlobal()`,
+which is the `BeResMan` pattern.
+
+So a Trinity class that needs a resource asks the manager for it. "An adapter
+supplies it" and "the seam is injected" describe neither Carbon nor this
+package, and where they appear they mark work that was never done rather than a
+boundary being kept.
+- The `trinityal/<backend>` layers own backend allocation, replacement, and
+  destruction. Preparation is the resource's own, through `OnPrepareResources`;
+  the backend supplies the objects it allocates.
+
 Concrete formats require [explicit imports and registration](formats/README.md).
 [Worker-safe formats](reference/workers.md) also declare their exact module;
 the package root imports and registers neither.
-
-Extension routes are manager-local configuration. They bind an extension to a
-handler plus one format or an ordered format chain. The handler's
-`ResourceHandlerMode` declaration determines whether path-only `Fetch()`
-returns the stable resource or the constructed object. The route snapshot is
-captured by the canonical handle, so later registration changes affect only a
-new identity after explicit deletion or clearing. Target construction and
-dynamic identification run after any worker decode on the main thread.
-
-## Source layout
-
+
+Extension routes are manager-local configuration. They bind an extension to a
+handler plus one format or an ordered format chain. The handler's
+`ResourceHandlerMode` declaration determines whether path-only `Fetch()`
+returns the stable resource or the constructed object. The route snapshot is
+captured by the canonical handle, so later registration changes affect only a
+new identity after explicit deletion or clearing. Target construction and
+dynamic identification run after any worker decode on the main thread.
+
+## Source layout
+
 Resource source is directly importable ESM without decorator syntax. Classes
 that need schema metadata install it through `CjsSchema.define`; removing the
 syntax does not remove their identity, fields or model behavior. Source-focused
@@ -120,10 +160,10 @@ This does not change other layers' decorator/build requirements. Published
 output remains built ESM in `npm/dist`.
 
 Resource owners and their direct Carbon data records live under
-`src/resource`, grouped as `audio`, `geometry`, `geometry/granny`, `shader`,
-and `texture`; worker execution and its message protocol live under `src/resource/worker`.
-Reviewed, unresolved active ports live under `src/resource/generated` and are exposed
-only through the explicit `./generated` package subpath until promotion. Native
-shapes that JavaScript replaces or does not use are retained only under
-`src/resource/dropped`, with their disposition documented there, and are never exported
-or bundled.
+`src/resource`, grouped as `audio`, `geometry`, `geometry/granny`, `shader`,
+and `texture`; worker execution and its message protocol live under `src/resource/worker`.
+Reviewed, unresolved active ports live under `src/resource/generated` and are exposed
+only through the explicit `./generated` package subpath until promotion. Native
+shapes that JavaScript replaces or does not use are retained only under
+`src/resource/dropped`, with their disposition documented there, and are never exported
+or bundled.

package/docs/resource/concepts/resource-lifecycle.md

@@ -1,7 +1,7 @@
 # Resource lifecycle
 
 Status: Evolving  
-Scope: `@carbonenginejs/runtime/resource`
+Scope: `@carbonenginejs/runtime/resource`
 Audience: Users and integrators  
 Summary: Explains resource states, the load/prepare split, and how a resource request flows from path to published CPU payload.
 
@@ -28,21 +28,26 @@ Additional terminal or cleanup states include `ERROR`, `UNLOADED`, and
 - The concrete resource calls `OnPrepared()` after prepare work succeeds.
 
 Some ccpwgl concrete `Prepare()` implementations also create WebGL objects.
-That is a historical engine/runtime coupling, not the boundary CarbonEngineJS
-keeps; see [architecture](../architecture.md).
+Carbon's do the same, through `OnPrepareResources` (`TriTextureRes.h:124`,
+`TriGeometryRes.h:353`, `Tr2EffectRes.h:53`), and so may ours; see
+[architecture](../architecture.md).
 
 ## CarbonEngineJS states
 
 ```text
-EMPTY -> REQUESTED/LOADING -> LOADED          (resource layer)
-LOADED -> PREPARING -> PREPARED               (engine adapters)
+EMPTY -> REQUESTED/LOADING -> LOADED -> PREPARING -> PREPARED
 ```
 
+The whole line belongs to the resource layer. Backend allocation inside
+`PREPARING` is delegated to the abstraction layer, as Carbon delegates it to
+its own AL.
+
 - `EMPTY`: resource identity exists, but no payload has been read.
 - `REQUESTED`: the resource is waiting on a queued or shared source load.
 - `LOADING`: source bytes are available and CPU reader/format work is active.
 - `LOADED`: CPU payload or hydrated object graph exists.
-- `PREPARING`: an engine adapter is realizing backend-owned resources.
+- `PREPARING`: the resource is preparing itself, allocating whatever backend
+  objects it needs through the abstraction layer.
 - `PREPARED`: preparation completed successfully and the resource is usable.
 - `FAILED`: CPU loading, conversion, validation, or publication failed before
   a valid payload was published.
@@ -56,8 +61,9 @@ LOADED -> PREPARING -> PREPARED               (engine adapters)
 per source/path and limits active source operations with
 `maxConcurrentLoads`. After bytes arrive, object construction is split into
 separate main-queue items (`reader/format conversion -> publish`). Publication
-moves the resource to `LOADED`, then stops. ResMan never performs backend
-realization or marks the resource `PREPARED`/`GOOD`. See
+moves the resource to `PREPARED`: the published value is already the reader or
+converter outcome, so no CPU preparation remains. A route that hydrates a `Target` builds a new object for each
+caller from the retained decoded values, as Carbon's `LoadObject` does. See
 [reference/queues.md](../reference/queues.md) for the queue contract and
 [reference/motherlode-cache.md](../reference/motherlode-cache.md) for
 identity, retention, and release behavior.
@@ -162,14 +168,14 @@ Application / runtime object
              the built CjsResource/object
 ```
 
-Device realization is a separate continuation selected outside ResMan. It can
-run again after adapter eviction or device loss while the CPU payload remains
+Preparation is a separate phase from loading, as it is in Carbon, and it can
+run again after eviction or device loss while the CPU payload remains
 resident:
 
 ```text
 CjsResource LOADED
         |
-        | selected engine adapter
+        | OnPrepareResources
         v
 PREPARING
         |
@@ -212,10 +218,10 @@ device memory are different budgets. Retention therefore distinguishes:
   typed arrays;
 - adapter payload: WebGL/WebGPU textures, buffers, shader modules, pipelines.
 
-Identity and lightweight metadata remain resident while CPU and adapter
-payloads release independently. Engine adapters own adapter-resource destruction;
-the resource layer supplies lifecycle hooks and opaque adapter slots. See
-[reference/motherlode-cache.md](../reference/motherlode-cache.md).
+Identity and lightweight metadata remain resident while CPU and adapter
+payloads release independently. Engine adapters own adapter-resource destruction;
+the resource layer supplies lifecycle hooks and opaque adapter slots. See
+[reference/motherlode-cache.md](../reference/motherlode-cache.md).
 
 ## Related documentation
 

package/docs/resource/formats/geometry-interchange.md

@@ -25,6 +25,51 @@ particular, it does not require normalized skin-weight sums or finite mesh
 bounds and UV densities. Destination writers may impose stricter requirements
 when their target format needs them.
 
+## glTF import contract
+
+`CjsGltfFormat` defaults to `emit: "shared"`; `emit: "cmf"` uses the same
+canonical CMF builder. JSON and `gltfJson` are explicit projections, not the
+conversion boundary.
+
+- **Vertex channels:** glTF `TANGENT` is XYZ plus handedness, not an EVE packed
+  tangent frame. Import produces separate tangent and binormal vectors from
+  the matching normal and handedness; a tangent without a matching normal channel is
+  rejected. Invalid direction vectors use the exporter's fixed fallbacks.
+  Indexed UV/color channels retain their usage indices and three/four-component
+  color width. Optional tangent packing is applied independently to every LOD.
+- **Skinning:** `JOINTS_0` stays relative to the mesh's palette. Positive-weight
+  indices must address that palette; zero-weight indices become zero. Skins
+  sharing `skin.skeleton` share the full skeleton, including unused bones;
+  skins without it remain separate. `inverseBindMatrices` must be FLOAT MAT4,
+  one per joint, and map by joint-node identity without transpose. Conflicting
+  matrices for a shared bone reject; an absent accessor means identity.
+- **Morphs:** CMF buffers are absolute. Deltas are added to each LOD's own base;
+  omitted components copy that base, and authored absolute targets stay
+  absolute. Non-empty morph declarations include Position and are subsets of
+  the base declaration. Displacement is measured against the base and aggregated
+  across LODs. Weight animations become scalar MorphTarget channels:
+  `FooShape` maps to `Foo`. Carbon's exporter omits original target names, so
+  unnamed exported targets become `target_n`, not reconstructed original names.
+- **Animation:** missing TRS channels stay absent. Explicit one-key identity
+  channels retain `preserveIdentity`, since they may override a non-identity
+  rest pose. Track groups follow shared skeleton identity rather than duplicating
+  channels per mesh. Matrix decomposition is checked by recomposition; rotation
+  and reflected scale survive, but shear is rejected.
+- **Scene and LOD:** when scenes exist, import uses mesh nodes reachable from
+  the default scene and reconstructs lower LODs through `MSFT_lod.ids`.
+  Coverage `[c0, c1, ..., sentinel]` becomes thresholds
+  `[0xffffffff, round(c0 * 2048), round(c1 * 2048), ...]`, strictly descending;
+  the sentinel creates no LOD. Export-clamped thresholds above 2048 are not
+  recoverable. LODs must agree on topology, declaration, material-area count,
+  joint palette, and morph declarations/names.
+- **Topology:** non-indexed POINTS become PointList without an index buffer;
+  strips and fans are triangulated. CMF construction fills UV densities through
+  the highest TexCoord usage index, leaving missing usage indices zero.
+
+Carbon's exporter loses source declarations, packed-frame storage, bounds,
+metadata, morph names and some LOD information. Round trips are comparisons of
+representable geometry/animation semantics, not byte-exact recovery.
+
 ## FBX compatibility modes
 
 FBX reads accept `compatibility: "source" | "carbon"`. The default is
@@ -94,6 +139,11 @@ subdivision limit, not silent reinterpretation of cubic controls.
 
 The following inputs remain hard errors rather than lossy conversions:
 
+- glTF `JOINTS_n`/`WEIGHTS_n` above zero, pending an explicit influence-reduction
+  policy;
+- indexed glTF POINTS, pending coordinated unindexing of base and morph channels;
+- non-identity glTF mesh-node transforms, pending a complete bake through
+  geometry, morphs, bounds, directions and skinning;
 - multiple or weighted FBX animation layers and FBX cubic tangent semantics;
   Carbon delegates these to `ufbx_bake_anim`, and the runtime has no equivalent
   evaluator;