@carbonenginejs/runtime-trinity 0.5.0 → 0.7.0

package/docs/README.md

@@ -0,0 +1,88 @@
+# Runtime Trinity documentation
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-trinity`
+Audience: Runtime authors, engine authors, integrators, and maintainers
+Summary: Explains the GPU-free Trinity graph, its public entry points, and its ownership boundaries.
+
+## Purpose
+
+`@carbonenginejs/runtime-trinity` owns serializable Carbon Trinity and Eve
+object graphs together with portable CPU-side behavior. Applications can
+hydrate, inspect, update, and collect renderer-neutral work from those graphs
+without creating a canvas, graphics context, or GPU device.
+
+The source contains generated schema intake and maintained implementations.
+Classes leave `src/generated` before their first substantive manual source
+change and move into readable source-area directories. A promoted class may
+remain explicitly incomplete while its bounded portable behavior is reviewed.
+The parity audit can expose additional inherited or interface obligations
+after promotion; current exceptions remain explicit in the
+implementation-status reference.
+
+## Use this package when
+
+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;
+- 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.
+
+## Where it fits
+
+```text
+@carbonenginejs/tools-core -- reviewed source --> @carbonenginejs/runtime-trinity
+@carbonenginejs/runtime-trinity -- depends on --> runtime-utils + runtime-resource
+
+@carbonenginejs/runtime-resource -- decoded values --> application composition
+@carbonenginejs/runtime-trinity -- graph and intents --> application composition
+application composition --> @carbonenginejs/engine-webgpu or host engine
+```
+
+`@carbonenginejs/runtime-utils` provides the shared model, schema, constants,
+and math foundation. `@carbonenginejs/tools-core` is a build-time producer of
+schema and generated-class input, not a runtime dependency.
+`@carbonenginejs/runtime-resource` owns decoded geometry and texture values,
+`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.
+
+Character GState behavior belongs to `@carbonenginejs/runtime-character`.
+Applications or `@carbonenginejs/runtime-core` compose these domains.
+
+## Start here
+
+```js
+import { EveCamera } from "@carbonenginejs/runtime-trinity/eve";
+
+const camera = new EveCamera();
+camera.translationFromParent = 100;
+camera.Update(0, 16 / 9);
+
+const view = camera.GetViewMatrix();
+```
+
+Import a focused public subpath when the consumer only needs one source
+family. The root entry aggregates the complete public runtime.
+
+## Documentation map
+
+- [Architecture and ownership boundaries](architecture.md)
+- [Current API](reference/api.md)
+- [Main semantic extraction](reference/main-semantic-extraction.md)
+- [Eve runtime behavior](concepts/eve-runtime-behavior.md)
+- [Generated-class lifecycle](concepts/generated-class-lifecycle.md)
+- [Implementation status and audits](reference/implementation-status.md)
+- [Eve runtime classes](reference/classes/eve-runtime.md)
+- [Trinity core classes](reference/classes/trinity-core.md)
+
+A complete class-purpose catalog is planned after generated classes carry
+reviewed descriptor metadata and the shared documentation checker supports the
+package's deliberate dropped-class quarantine.

package/docs/architecture.md

@@ -0,0 +1,162 @@
+# Runtime Trinity architecture
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-trinity`
+Audience: Runtime authors, engine authors, and maintainers
+Summary: Defines Trinity graph ownership and the boundary between portable state and backend realization.
+
+## Purpose
+
+`@carbonenginejs/runtime-trinity` preserves Carbon's serializable object graph and portable
+runtime behavior while keeping graphics-device work outside the package.
+Trinity classes can therefore be registered, hydrated, inspected, updated, and
+serialized in browsers, workers, Node.js tools, and test hosts.
+
+## Composition and data flow
+
+```text
+@carbonenginejs/tools-core -- reviewed source --> @carbonenginejs/runtime-trinity
+@carbonenginejs/runtime-trinity -- depends on --> runtime-utils + runtime-resource
+
+@carbonenginejs/runtime-resource -- decoded values --> application composition
+@carbonenginejs/runtime-trinity -- graph and intents --> application composition
+application composition --> host WebGL engine
+application composition --> @carbonenginejs/engine-webgpu
+```
+
+Runtime dependencies point from `@carbonenginejs/runtime-trinity` to
+`@carbonenginejs/runtime-utils` and `@carbonenginejs/runtime-resource`.
+Schema scanning and source emission flow from `@carbonenginejs/tools-core`
+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.
+
+`TriDevice`, render contexts, targets, authored shader options, effect/material
+facades, parameters, buffers, and presentation records remain Trinity graph
+classes. Canonical `Tr2EffectRes`, `Tr2Shader`, and immutable reflection records
+are resource-owned. Serialized identity never makes either package the owner of
+live backend handles.
+
+## Ownership elsewhere
+
+- `@carbonenginejs/runtime-utils` owns shared models, schema decorators, math,
+  constants, and general runtime primitives.
+- `@carbonenginejs/runtime-resource` owns resource acquisition, decoding,
+  reusable CPU resource representations, compiled-effect selection/cache, and
+  the canonical device-free `Tr2Shader` reflection graph.
+- `@carbonenginejs/runtime-character` owns character GState behavior.
+- `@carbonenginejs/tools-core` owns source scanning, schema compilation, and
+  generated-class emission.
+- WebGL and WebGPU engines own devices, contexts, uploads, bindings, pipelines,
+  draw or dispatch encoding, presentation, synchronization, and loss recovery.
+- Applications or `@carbonenginejs/runtime-core` choose and compose engines and
+  domain runtimes.
+
+## Render-job contract
+
+`TriRenderJob` and `Tr2RenderJobs` preserve ordered step execution, resumable
+in-progress cursors, nested result mapping, recurring and chained scheduling,
+and deterministic target/depth stack cleanup.
+
+`Run(realTime, simTime, executor)` receives an injected executor. A WebGL
+executor may perform work immediately while a WebGPU executor may encode pass
+boundaries, but both preserve the observable step order and yield boundary.
+Nested jobs receive the same executor identity. `TriRenderJob` and
+`TriRenderStep` expose their status and result vocabularies as class statics.
+The default `Tr2RenderContext` is a GPU-free intent and diagnostic surface.
+
+## Render-batch contract
+
+`Tr2RenderBatch`, `TriRenderBatchAccumulator`, and `TriRenderBatchMap` collect,
+sort, group, and expose neutral CPU data. Geometry references, effect keys,
+per-object values, render modes, and draw arguments describe work; they are
+not live GPU resources.
+
+`CjsBatchManager` is the current GPU-free orchestrator. It registers producer
+types, invokes injected `Realize` and `Build` hooks, collects renderables,
+finalizes accumulators, and observes shared rebuild tokens. The backend
+realizers supplied through those hooks remain engine-owned.
+
+## Per-frame and per-object data
+
+Trinity can expose per-object values proven by graph state, including world
+transforms and maintained Eve per-object records. It does not invent missing
+renderer state.
+
+The active engine supplies complete per-frame values such as previous
+matrices, shadow state, resolution, jitter, presentation policy, and other
+backend-owned semantics before serialization or upload.
+
+### Constant-data ownership
+
+Trinity owns the constant-data layout outright: field names, element counts, an
+encoding kind per field, and the byte offsets. There is ONE layout and no
+per-engine packing, because these buffers are not backend-specific — every
+backend declares them as a flat array of `vec4`, and std140's stride for an
+array of `vec4` matches tight C++ packing. A struct the catalog does not cover
+fails at registration rather than at draw time. An engine that genuinely needs
+different memory transforms it downstream.
+
+`RawDataStore` leases payloads from a per-engine arena; `RawData` is the
+write-mostly view over one slice. Values are written through the encoding
+(matrices transposed, integers bit-cast), never read back, and the arena is
+rewound rather than freed per payload. Declared defaults are re-applied on
+lease; an unwritten field otherwise retains the previous tenant's bytes, which
+preserves the source engine's own contract that a fill writes every field it
+relies on.
+
+A renderable returns whichever shape its constant data actually has:
+
+- one payload, when a single buffer is bound;
+- a `{ vs, ps }` record, when the vertex and pixel stages take DIFFERENT
+  payloads and are therefore two separate buffers;
+- `null`, when the renderable cannot produce one — no geometry, or no
+  accumulator to lease from.
+
+The record itself belongs to one of Carbon's two tiers, chosen statically by
+class rather than by a runtime branch. A TRANSIENT record is leased from the
+frame arena and dies at reset. A PERSISTENT record is a member the owner keeps
+across frames, because it fills the record during update and reads it back
+afterwards; `EveSpaceObject2` is the reference case, and `Invalidate` marks it
+for re-upload once per frame.
+
+A struct declares the stages it binds to, so one payload bound to several
+stages stays one payload rather than being duplicated per stage. The batch
+pipeline threads whichever shape it receives without inspecting it.
+
+## Post-process graph
+
+`Tr2PostProcess2` and `Tr2PostProcessAttributes` own device-free activation,
+quality gates, lookup-table ordering, volume blending, and authored effect
+records. Engines independently realize temporary textures, exposure state,
+history, compute or fragment passes, readback, and loss recovery while
+preserving observable graph order.
+
+## Constraints
+
+- Package evaluation must not create a canvas, graphics context, audio
+  context, network request, or filesystem dependency.
+- Persisted schema fields must not hold live backend handles.
+- A generated class is generator-owned schema intake. It is promoted before
+  its first substantive manual source change, even when review leaves explicit
+  implementation gaps.
+- Backend-specific behavior must be injected through a narrow capability or
+  remain with the owning engine.
+
+## Related documentation
+
+- [Package documentation](README.md)
+- [Current API](reference/api.md)
+- [Main semantic extraction](reference/main-semantic-extraction.md)
+- [Eve runtime behavior](concepts/eve-runtime-behavior.md)
+- [Generated-class lifecycle](concepts/generated-class-lifecycle.md)
+- [Implementation status and audits](reference/implementation-status.md)

package/docs/concepts/eve-runtime-behavior.md

@@ -0,0 +1,86 @@
+# Eve runtime behavior
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-trinity/eve`
+Audience: Runtime authors, engine authors, and integrators
+Summary: Describes maintained CPU behavior for Eve combat effects, morph state, and distributions.
+
+## Purpose
+
+The maintained Eve tree implements portable object-graph behavior without
+claiming renderer, resource-loader, or character-runtime ownership. These
+contracts let engines consume faithful CPU state through explicit seams.
+
+## Turrets and missiles
+
+`EveMobile` maps authored `locator_*` transforms and optional animated bone
+transforms into `EveTurretSet` instances. Turret sets own portable state
+changes, paired turret and damage-locator selection, looping-fire checks,
+tracking fades, muzzle transforms, target updates, firing effects, and
+controller forwarding.
+
+`EveSpaceObject2` supplies damage locators, miss positions, radius,
+impact-material data, and the shield-ellipsoid collision surface consumed by
+turrets and missiles.
+
+`EveTransform`, `EveMissile`, and `EveMissileWarhead` own CPU transforms,
+launch, eject, and tracking state, fixed-seed Perlin path offsets, target
+switching, impacts, explosion callbacks, particles, visibility, and dynamic
+MIRV bounds. Per-object records expose the world transform and missile size;
+an engine packs and uploads those logical values.
+
+`EveEffectRoot2` and `EveRootTransform` own detached effect placement,
+controller and curve propagation, targetable-sphere behavior, child update and
+renderable traversal, and authored effect level of detail.
+
+Native pose realization, geometry loading, quad submission, device buffers,
+and shader upload remain outside this package. A data-only generated child
+does not gain invented rendering behavior merely because a maintained root
+traverses it.
+
+## Animation and morph state
+
+Character GState ownership belongs to
+`@carbonenginejs/runtime-character`. `Tr2GStateAnimation` and
+`Tr2GStateParameter` are not Trinity exports.
+
+The generic `Tr2GrannyAnimation` graph remains in Trinity for non-character
+skinned geometry. Its updater samples legacy scalar vector tracks and modern
+morph channels, composes layers in native lexical order, exposes a detached
+morph snapshot, and applies `GrannyBoneOffset` corrections after animation
+sampling and before world-transform composition.
+
+`Tr2GrannyStateRes` remains owned by
+`@carbonenginejs/runtime-resource`.
+
+`Tr2Mesh` owns LOD-0 indexed morph-weight state, including manual weights and
+baked flags. `EveChildMesh` rebuilds its CPU morph records during asynchronous
+updates. Exact-name animation values override mesh weights; values below
+`0.001` remain inactive; active runtime and baked records are partitioned
+before an engine uploads or evaluates them.
+
+Trinity prepares morph records but does not perform GPU deformation or baking.
+
+## Distribution contract
+
+The Eve distribution family is browser-portable CPU behavior. Locator,
+parent-locator, and volume placement generators build the initial placement
+pool. Spawn and lifetime modifiers transform those records. Burst, interval,
+controller, sphere, plane, and snake spawners drive the shared
+`IEveDistributionRulesParent` contract.
+
+Carbon's mutable `uint32_t&` placement counter is represented by one explicit
+`{ value }` object.
+
+Sphere, ellipsoid, and box volumes expose point generation and change
+callbacks without creating renderer resources. Parent-locator generation uses
+`EveSpaceObject2.GetLocatorsForSet`; volume generation uses
+`IEveVolume.GeneratePointsInVolume`. These paths do not probe alternate method
+names or infer renderer capabilities.
+
+## Related documentation
+
+- [Architecture and ownership boundaries](../architecture.md)
+- [Current API](../reference/api.md)
+- [Main semantic extraction](../reference/main-semantic-extraction.md)
+- [Implementation status and audits](../reference/implementation-status.md)

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

@@ -0,0 +1,116 @@
+# Generated-class lifecycle
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-trinity` generated and maintained classes
+Audience: Runtime authors, schema-tool authors, and maintainers
+Summary: Defines how schema intake becomes reviewed runtime-trinity source.
+
+## Purpose
+
+Generated classes establish Carbon-compatible identity, inheritance, fields,
+decorators, and exposed method obligations. They are review input rather than
+the permanent home of manually maintained runtime behavior.
+
+The lifecycle keeps generated output reproducible while giving every manually
+edited class a stable, human-readable source tree.
+
+## Current lifecycle
+
+1. `@carbonenginejs/tools-core` scans Carbon declarations and compiles the
+   reviewed schema.
+2. The class emitter produces schema-shaped JavaScript in its tooling-owned
+   output corpus.
+3. Reviewed generated source is copied into `runtime-trinity/src/generated`;
+   the runtime does not depend on the tooling workspace.
+4. Runtime work verifies portable behavior against the public source,
+   interfaces, schema, and tests.
+5. Before the first substantive manual source change, the complete class moves
+   into the maintained source area that owns its responsibility.
+6. Manual implementation and review continue in that maintained home.
+   Unresolved obligations remain explicit with `@impl.notImplemented`.
+7. The maintained barrel exports the promoted class and the generated copy is
+   removed.
+8. Generation records that a hand-maintained source exists instead of
+   recreating a competing class.
+
+Inspection, tests outside the class, and unchanged emitter output do not
+trigger promotion. Manual behavior, source-corrected defaults or fields,
+inheritance changes, decorator corrections, runtime-specific dependencies,
+and class-owned enum work do.
+
+The parity audit remains active after promotion because later schema or
+interface-contract improvements can reveal additional obligations. A promoted
+class with a newly visible gap stays in its maintained home; the gap is made
+explicit and completed there instead of recreating a generated duplicate.
+
+Examples of maintained homes include:
+
+- `src/eve/camera` for camera state;
+- `src/eve/attachment/decal` for space-object decals;
+- `src/eve/child/behaviors/lifecycle` and `tunnels` for cohesive behaviors;
+- `src/eve/effect/multiEffect` for multi-effect graphs; and
+- `src/trinityCore/binding` for dynamic and value binding classes.
+
+## Enum ownership
+
+An enum associated with one Carbon class normally becomes a named frozen
+static on that canonical owner, for example `Owner.EnumType.MEMBER`. A
+serialized integer field uses `@schema.enum("EnumType")` so inspectors and
+user interfaces resolve the class static and discover its accepted
+vocabulary.
+
+Ownerless vocabulary used only inside this package remains beside its
+maintained family. Genuinely shared cross-package vocabulary belongs in
+`@carbonenginejs/runtime-utils`, which allows runtime and graphics packages to
+share the identity without importing one another. A standalone generated enum
+file alone is not evidence that the enum should move to runtime-utils.
+
+## Generated source
+
+Generated source may include explicit `@impl.notImplemented` methods. These
+markers preserve known obligations and allow the implementation-gap audit to
+report them. Generated code must not silently invent device, resource,
+filesystem, or native behavior.
+
+Generated output is deterministic and should not be hand-edited as a
+substitute for changing its owning schema or emitter. Runtime-specific
+implementations belong in the maintained tree before the manual edit is made.
+
+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.
+
+The generated provenance banner is not an ownership lock. Durable protection
+comes from maintained and dropped skip sets, staging-first generation,
+duplicate-class checks, and comparison of installed generated source with
+fresh output. Newly promoted files replace the generated banner with a
+hand-maintained provenance header and exact Carbon source paths.
+
+## Dropped quarantine
+
+`src/dropped` is separate from `src/generated`. It contains deliberately
+quarantined source with a file-specific disposition and is excluded from the
+normal implementation and parity ownership surface.
+
+A dropped class is not treated as an incomplete generated class and is not a
+supported public implementation. Its disposition records why this package
+owns the identity, why it is rejected as a runtime model, its replacement, and
+the condition for revival. Dropped files are not imported, exported,
+registered, or implemented in place.
+
+## Planned class descriptors
+
+The schema emitter is planned to carry a reviewed purpose, visibility, kind,
+source path, and public export for each generated class. That metadata will
+produce deterministic class-purpose catalogs without guessing responsibility
+from a class name.
+
+The catalog becomes part of the documentation validation gate after the
+shared checker can exclude the deliberate dropped quarantine.
+
+## Related documentation
+
+- [Architecture and ownership boundaries](../architecture.md)
+- [Current API](../reference/api.md)
+- [Implementation status and audits](../reference/implementation-status.md)

package/docs/reference/api.md

@@ -0,0 +1,76 @@
+# Runtime Trinity API
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-trinity`
+Audience: Runtime authors, engine authors, and integrators
+Summary: Lists the current public subpaths and their owned source families.
+
+## Contract
+
+All public entries are ECMAScript modules. Importing them creates no graphics
+device or backend context. The root entry aggregates the complete runtime;
+focused subpaths allow consumers to state a narrower dependency.
+
+The root entry also contains the maintained `sprite2d` family. There is no
+focused `./sprite2d` package export in the current manifest.
+
+## Current subpaths
+
+| Import | Purpose |
+| --- | --- |
+| `@carbonenginejs/runtime-trinity` | Complete public Trinity and Eve runtime surface. |
+| `@carbonenginejs/runtime-trinity/controllers` | Controller actions, variables, state machines, and expression behavior. |
+| `@carbonenginejs/runtime-trinity/curves` | Scalar, vector, quaternion, event, sequencer, and animation curve families. |
+| `@carbonenginejs/runtime-trinity/eve` | Maintained Eve cameras, scenes, objects, attachments, effects, behaviors, and UI graph classes. |
+| `@carbonenginejs/runtime-trinity/generated` | Aggregate generated schema-intake classes that have not been promoted. |
+| `@carbonenginejs/runtime-trinity/generated/*` | Generated family barrel selected by package export pattern. |
+| `@carbonenginejs/runtime-trinity/generated/*.js` | Exact generated module selected by package export pattern. |
+| `@carbonenginejs/runtime-trinity/particle` | Maintained CPU particle data, emitters, forces, constraints, and systems. |
+| `@carbonenginejs/runtime-trinity/postProcess` | Device-free post-process graph and attribute models. |
+| `@carbonenginejs/runtime-trinity/renderJob` | Ordered render-job and render-step graph classes. |
+| `@carbonenginejs/runtime-trinity/shader` | Mutable effect/material facade, parameters, options, sampler overrides, shader buffers, and identity-preserving compatibility reexports of resource-owned reflection classes. |
+| `@carbonenginejs/runtime-trinity/trinityCore` | Core Trinity resources, batches, views, projections, bindings, and graph records. |
+| `@carbonenginejs/runtime-trinity/ui` | Maintained Trinity UI graph classes. |
+| `@carbonenginejs/runtime-trinity/utilities` | Package-specific portable runtime helpers. |
+
+Promoted classes are exported through their maintained family and no longer
+remain under `generated`. For example:
+
+```js
+import { EveCamera } from "@carbonenginejs/runtime-trinity/eve";
+import {
+    Tr2DynamicBinding,
+    TriValueBinding
+} from "@carbonenginejs/runtime-trinity/trinityCore";
+```
+
+## Schema and enum metadata
+
+Runtime classes use `@type.define` for Carbon class identity and field
+decorators from `@carbonenginejs/runtime-utils/schema`. Enum-backed integer
+fields use `@schema.enum` so metadata consumers can present the maintained enum
+vocabulary. Class-associated enums normally live as named frozen statics on
+their canonical class. Ownerless single-package vocabulary remains with its
+family; only genuinely shared cross-package vocabulary belongs in
+`@carbonenginejs/runtime-utils`.
+
+Public methods that implement Carbon exposure use `@carbon.method`. The parity
+audit checks promoted classes for omitted and present-but-unexposed methods.
+
+## Constraints
+
+- Generated wildcard subpaths are intake surfaces and can change when a class
+  is promoted to its maintained family.
+- A graph class describing a device or buffer does not expose a live backend
+  object.
+- Resource and engine capabilities are supplied by their owning packages.
+- Explicit implementation gaps remain visible rather than receiving guessed
+  behavior.
+
+## Related documentation
+
+- [Architecture and ownership boundaries](../architecture.md)
+- [Main semantic extraction](main-semantic-extraction.md)
+- [Eve runtime behavior](../concepts/eve-runtime-behavior.md)
+- [Generated-class lifecycle](../concepts/generated-class-lifecycle.md)
+- [Implementation status and audits](implementation-status.md)

package/docs/reference/classes/eve-runtime.md

@@ -0,0 +1,106 @@
+# Eve runtime classes
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-trinity/eve`
+Audience: Users and integrators
+Summary: Catalogs promoted Eve runtime classes with renderer-neutral behavior.
+
+<!-- class:EvePlanet -->
+## `EvePlanet`
+
+Represents a planet scene object with CPU-side visibility state for its depth-only child mesh.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/spaceObject/planet/EvePlanet.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveLensflare -->
+## `EveLensflare`
+
+Represents a lens-flare graph with CPU-side visibility and controller state.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/effect/lensflare/EveLensflare.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveLineSet -->
+## `EveLineSet`
+
+Stores editable tactical line records before renderer submission.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/ui/lines/EveLineSet.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveTacticalTrails -->
+## `EveTacticalTrails`
+
+Tracks tactical trail objects without requiring a graphics device.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/ui/tacticalOverlay/EveTacticalTrails.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveComponentCollection -->
+## `EveComponentCollection`
+
+Stores entities belonging to one Eve component type.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/scene/components/EveComponentCollection.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveComponentRegistry -->
+## `EveComponentRegistry`
+
+Indexes Eve entities and their component collections for scene processing.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/scene/components/EveComponentRegistry.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveShip2 -->
+## `EveShip2`
+
+A ship space object: booster drive, speed state, and ship shader data.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/spaceObject/EveShip2.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveSpherePin -->
+## `EveSpherePin`
+
+A UI sphere pin: authored SRT placement plus the pin constant record.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/ui/EveSpherePin.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveChildBulletStorm -->
+## `EveChildBulletStorm`
+
+Locator-driven bullet-storm child: instances, target blobs, and the clip-sphere state machine.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/child/EveChildBulletStorm.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:IEveSpaceObject2ParentData -->
+## `IEveSpaceObject2ParentData`
+
+The per-frame parent state a space object hands to its attachments.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/spaceObject/IEveSpaceObject2ParentData.js`
+- Visibility: Public
+- Kind: CarbonEngine

package/docs/reference/classes/trinity-core.md

@@ -0,0 +1,26 @@
+# Trinity core classes
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-trinity/trinityCore`
+Audience: Engine authors and integrators
+Summary: Catalogs the GPU-free constant-data classes an engine binds when it realizes the Trinity graph.
+
+<!-- class:RawData -->
+## `RawData`
+
+A packed constant-data slice bound to a resolved layout.
+
+- Export: `@carbonenginejs/runtime-trinity/trinityCore`
+- Source: `src/trinityCore/rawData/RawData.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:RawDataStore -->
+## `RawDataStore`
+
+Registers constant-data struct shapes and leases packed payloads from a per-engine arena.
+
+- Export: `@carbonenginejs/runtime-trinity/trinityCore`
+- Source: `src/trinityCore/rawData/RawDataStore.js`
+- Visibility: Public
+- Kind: CarbonEngineJS