@carbonenginejs/runtime-trinity 0.6.0 → 0.7.0

package/dist/trinityCore/rawData/TriPoolAllocator.js

@@ -0,0 +1,357 @@
+import { RawDataType, RawData } from './RawData.js';
+import { CjsPerObjectLayouts } from './CjsPerObjectLayouts.js';
+
+// Factory + arena for RawData constant-data payloads.
+//
+// Named for Carbon TriPoolAllocator (TriPoolAllocator.h/.cpp): the same job,
+// lifetime and per-frame Clear. Carbon bump-allocates with placement new and
+// wholesale Clear()s at EndRenderContext (Tr2Renderer.cpp:1072-1081), which is
+// exactly what Alloc/Reset do here. It also carries the struct-layout registry,
+// which C++ gets free from the type system via Allocate<T>().
+//
+// A pool is PER-ENGINE (one CjsLibrary = one live backend). Structs are
+// REGISTERED on the instance - registration resolves each struct's layout right
+// then, so a struct that cannot be laid out fails loud at registration, naming
+// it.
+//
+// TRINITY COMPUTES THE OFFSETS. This once required an engine-injected packer,
+// on the premise that the physical layout is BACKEND-SPECIFIC. That premise is
+// false for these buffers, verified 2026-07-28: every backend declares them as
+// a flat array of vec4 - WGSL `array<vec4<f32>, N>`, GLSL `vec4 cbN[N]`, or a
+// std140 block wrapping `vec4 data[N]` - and std140's stride for an array of
+// vec4 is 16 bytes, identical to tight C++ packing. The std140 rules that DO
+// diverge (vec3 padded to 16, scalar array stride) never engage, because there
+// are no struct members to pad: the translated shader indexes the flat array
+// and reassembles fields itself.
+//
+// Layouts resolve from two sources, in order:
+//
+//   1. CjsPerObjectLayouts, when the struct name is a Carbon struct. Those
+//      offsets are declared, not derived, because Carbon memcpy's the C++
+//      struct (EveSpaceObject2.cpp:1469-1483) and its members sit on float4
+//      boundaries - tight-packing a FLOAT member would drift from it.
+//   2. tight packing of the supplied def, for an ad-hoc struct the catalog
+//      does not carry.
+//
+// Offsets are FLOAT offsets relative to one instance's slot (the same offset
+// indexes the Float32 and Uint32 views).
+//
+// Allocation is an ARENA (bump), not a free-list:
+//   - Alloc(name) bumps a cursor and returns a view ("snip off what you need")
+//     into a RETAINED backing buffer - the buffer is NOT recreated per frame.
+//   - Reset() rewinds the cursor; every slot is freed at once, O(1); the
+//     chunks are kept and reused next frame.
+//   - There is no Unalloc: transient slots live until their batch dispatches,
+//     so Reset is the only free. Permanent per-object data is not Alloc'd - a
+//     static placeable constructs its own RawData and owns it across frames.
+//
+// Maps to Carbon: Alloc == accumulator.Allocate (Tr2Renderer::GetPoolAllocator,
+// reset per frame). No clear-on-Alloc, so an unwritten field shows the previous
+// tenant's bytes - that reproduces Carbon's "unwritten slots = allocator
+// garbage" (declared defaults are re-applied on Alloc; everything else is
+// write-what-you-rely-on).
+//
+// Design: PER-OBJECT-DATA-DESIGN-2026-07-24.md
+
+/** Declared catalog type -> the encoder kind that writes its bytes. */
+const CATALOG_ENCODINGS = {
+  [CjsPerObjectLayouts.Types.MATRIX4]: RawDataType.MATRIX,
+  [CjsPerObjectLayouts.Types.UINT32]: RawDataType.UINT,
+  [CjsPerObjectLayouts.Types.INT32]: RawDataType.INT
+};
+
+/**
+ * A catalog layout as a store field-def array.
+ *
+ * A default on an array field is repeated across every element: the store
+ * applies each default at a single offset, and Carbon's neutral for a slot
+ * (identity for an unused custom mask) applies to every slot, not just the
+ * first.
+ */
+function catalogDef(layout) {
+  const def = [];
+  for (const field of layout.fields.values()) {
+    let value = null;
+    if (field.default) {
+      value = field.count > 1 ? Array.from({
+        length: field.count
+      }, () => [...field.default]).flat() : [...field.default];
+    }
+    def.push({
+      name: field.name,
+      size: field.size,
+      elements: field.count,
+      encoding: CATALOG_ENCODINGS[field.type] ?? RawDataType.VECTOR,
+      default: value
+    });
+  }
+  return def;
+}
+
+/**
+ * Carbon's declared layout for a struct, or null when the catalog omits it.
+ */
+function catalogLayout(structName) {
+  const layout = CjsPerObjectLayouts.Get(structName);
+  if (!layout) {
+    return null;
+  }
+  const fields = {};
+  for (const field of layout.fields.values()) {
+    fields[field.name] = {
+      offset: field.offset,
+      size: field.size,
+      elements: field.count,
+      encoding: CATALOG_ENCODINGS[field.type] ?? RawDataType.VECTOR
+    };
+  }
+  return {
+    fields,
+    stride: layout.stride
+  };
+}
+
+/**
+ * Tight layout for an ad-hoc struct the catalog does not carry: fields in
+ * declared order, no padding.
+ */
+function tightLayout(normalized) {
+  const fields = {};
+  let offset = 0;
+  for (const field of normalized) {
+    fields[field.name] = {
+      offset,
+      size: field.size,
+      elements: field.elements,
+      encoding: field.encoding
+    };
+    offset += field.size * field.elements;
+  }
+  return {
+    fields,
+    stride: offset
+  };
+}
+
+/** Registers constant-data struct shapes and leases packed payloads from a per-engine arena. */
+class TriPoolAllocator {
+  /** Registered layouts: name -> { fields, stride, defaults }. */
+  #layouts = new Map();
+
+  /** Retained arena chunks (Float32) and their Uint32 aliases. */
+  #chunks = [];
+  #chunkAliases = [];
+
+  /** Floats per chunk; also the largest struct a single Alloc may request. */
+  #chunkFloats = 8192;
+  #chunkIndex = 0;
+  #cursor = 0;
+
+  /**
+   * @param {object} [options]
+   * @param {number} [options.chunkFloats] - arena chunk size in floats.
+   */
+  constructor(options = {}) {
+    if (Number.isInteger(options.chunkFloats) && options.chunkFloats > 0) {
+      this.#chunkFloats = options.chunkFloats;
+    }
+    this.#AddChunk();
+  }
+
+  /**
+   * Register several structs at once: { StructName: def, ... }. Each value is a
+   * field-def array (see RegisterStruct) or { def, stages } when the struct
+   * binds anywhere other than the default vertex-stage slot. Returns the store
+   * for chaining.
+   */
+  Register(structs) {
+    for (const name of Object.keys(structs)) {
+      const entry = structs[name];
+      if (Array.isArray(entry)) {
+        this.RegisterStruct(name, entry);
+      } else {
+        this.RegisterStruct(name, entry.def, {
+          stages: entry.stages
+        });
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Register one struct and RESOLVE its layout immediately. `def` is an array
+   * of field defs: { name, encoding, size, elements?, default? }, where `size`
+   * may instead be a defaults ARRAY whose length is the size. Omit `def`
+   * entirely for a Carbon struct and the catalog supplies it. Returns the store
+   * for chaining.
+   *
+   * `options.stages` declares which per-object constant slots the payload binds
+   * (default ["vs"]). This is Carbon-SEMANTIC knowledge - which
+   * FillAndSetConstants calls exist for the struct - so it travels with the def
+   * rather than the layout: ["vs"] a vertex-stage payload, ["ps"] a pixel payload (one
+   * half of a { vs, ps } record), ["vs", "ps"] the SAME bytes bound to both
+   * slots (sphere pin, lensflare). The engine reads it from GetLayout().stages.
+   */
+  RegisterStruct(name, def, options = {}) {
+    if (def === undefined) {
+      // No def supplied: take Carbon's, from the catalog.
+      const layout = CjsPerObjectLayouts.Get(name);
+      if (!layout) {
+        throw new Error(`TriPoolAllocator: struct "${name}" is not in CjsPerObjectLayouts - add it there, or pass a def explicitly`);
+      }
+      def = catalogDef(layout);
+      options = {
+        ...options,
+        stages: options.stages ?? layout.stages
+      };
+    }
+    const normalized = TriPoolAllocator.normalizeDef(def);
+    const stages = TriPoolAllocator.normalizeStages(name, options.stages);
+
+    // Carbon's declared offsets win: its members sit on float4 boundaries, so
+    // tight-packing them would drift the moment a struct carries a FLOAT.
+    const resolved = catalogLayout(name) ?? tightLayout(normalized);
+    if (resolved.stride > this.#chunkFloats) {
+      throw new Error(`TriPoolAllocator: struct "${name}" (${resolved.stride} floats) exceeds the chunk size (${this.#chunkFloats})`);
+    }
+    const defaults = [];
+    for (const field of normalized) {
+      if (field.default) {
+        const entry = resolved.fields[field.name];
+        if (entry) {
+          defaults.push({
+            offset: entry.offset,
+            values: field.default
+          });
+        }
+      }
+    }
+    this.#layouts.set(name, {
+      fields: resolved.fields,
+      stride: resolved.stride,
+      defaults,
+      stages
+    });
+    return this;
+  }
+
+  /** Whether a struct has been registered on this store. */
+  Has(name) {
+    return this.#layouts.has(name);
+  }
+
+  /**
+   * Lease a TRANSIENT payload for a registered struct. Bumps the arena and
+   * returns a RawData view over the next slot, with declared defaults applied.
+   * Valid until the next Reset().
+   */
+  Alloc(name) {
+    const layout = this.#layouts.get(name);
+    if (!layout) {
+      throw new Error(`TriPoolAllocator: struct "${name}" is not registered on this store (call Register/RegisterStruct first)`);
+    }
+    const stride = layout.stride;
+    if (this.#cursor + stride > this.#chunkFloats) {
+      this.#chunkIndex++;
+      this.#cursor = 0;
+      if (this.#chunkIndex >= this.#chunks.length) {
+        this.#AddChunk();
+      }
+    }
+    const start = this.#cursor;
+    this.#cursor += stride;
+    const floats = this.#chunks[this.#chunkIndex].subarray(start, start + stride);
+    const uints = this.#chunkAliases[this.#chunkIndex].subarray(start, start + stride);
+    for (const preset of layout.defaults) {
+      const values = preset.values;
+      for (let index = 0; index < values.length; index++) {
+        floats[preset.offset + index] = values[index];
+      }
+    }
+    return new RawData(layout, floats, uints, name);
+  }
+
+  /**
+   * Free every transient slot at once (frame end). Rewinds the arena cursor;
+   * the backing chunks are RETAINED and reused - nothing is reallocated.
+   */
+  Reset() {
+    this.#chunkIndex = 0;
+    this.#cursor = 0;
+  }
+
+  /**
+   * Appends a fresh arena chunk of chunkFloats floats plus a Uint32 alias view
+   * over the same bytes, so payload fields can be written as floats or raw bits.
+   */
+  #AddChunk() {
+    const chunk = new Float32Array(this.#chunkFloats);
+    this.#chunks.push(chunk);
+    this.#chunkAliases.push(new Uint32Array(chunk.buffer));
+  }
+
+  /** The field encoding kinds (packing directives). */
+  static Type = RawDataType;
+
+  /** The per-object binding slots a struct may declare via options.stages. */
+  static Stages = Object.freeze(["vs", "ps", "gs", "cs", "hs", "ds"]);
+
+  /**
+   * Validate a stages declaration: a non-empty array drawn from
+   * TriPoolAllocator.Stages, no duplicates. Defaults to ["vs"] (Carbon's most
+   * common single-payload binding). Returns a frozen copy.
+   */
+  static normalizeStages(structName, stages) {
+    if (stages === undefined || stages === null) {
+      return TriPoolAllocator.defaultStages;
+    }
+    if (!Array.isArray(stages) || !stages.length) {
+      throw new Error(`TriPoolAllocator: struct "${structName}" stages must be a non-empty array`);
+    }
+    for (const stage of stages) {
+      if (!TriPoolAllocator.Stages.includes(stage)) {
+        throw new Error(`TriPoolAllocator: struct "${structName}" has unknown stage "${stage}" (expected one of: ${TriPoolAllocator.Stages.join(", ")})`);
+      }
+    }
+    if (new Set(stages).size !== stages.length) {
+      throw new Error(`TriPoolAllocator: struct "${structName}" declares a duplicate stage`);
+    }
+    return Object.freeze([...stages]);
+  }
+  static defaultStages = Object.freeze(["vs"]);
+
+  /**
+   * Normalize a raw def: default elements to 1, resolve size-as-defaults-array,
+   * require a name and encoding. Physical offsets are NOT computed here - they
+   * are resolved at registration, from the catalog or by tight packing.
+   */
+  static normalizeDef(def) {
+    return def.map(field => {
+      if (!field.name) {
+        throw new Error("TriPoolAllocator: every struct field needs a name");
+      }
+      if (!field.encoding) {
+        throw new Error(`TriPoolAllocator: field "${field.name}" needs an encoding (TriPoolAllocator.Type.*)`);
+      }
+      let size = field.size;
+      let defaultValue = field.default ?? null;
+      if (Array.isArray(size)) {
+        defaultValue = size;
+        size = size.length;
+      }
+      if (!Number.isInteger(size) || size <= 0) {
+        throw new Error(`TriPoolAllocator: field "${field.name}" needs a positive integer size`);
+      }
+      return {
+        name: field.name,
+        elements: Number.isInteger(field.elements) && field.elements > 0 ? field.elements : 1,
+        size,
+        encoding: field.encoding,
+        default: defaultValue
+      };
+    });
+  }
+}
+
+export { TriPoolAllocator };
+//# sourceMappingURL=TriPoolAllocator.js.map

package/dist/trinityCore/rawData/TriPoolAllocator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TriPoolAllocator.js","sources":["../../../../src/trinityCore/rawData/TriPoolAllocator.js"],"sourcesContent":["// Factory + arena for RawData constant-data payloads.\n//\n// Named for Carbon TriPoolAllocator (TriPoolAllocator.h/.cpp): the same job,\n// lifetime and per-frame Clear. Carbon bump-allocates with placement new and\n// wholesale Clear()s at EndRenderContext (Tr2Renderer.cpp:1072-1081), which is\n// exactly what Alloc/Reset do here. It also carries the struct-layout registry,\n// which C++ gets free from the type system via Allocate<T>().\n//\n// A pool is PER-ENGINE (one CjsLibrary = one live backend). Structs are\n// REGISTERED on the instance - registration resolves each struct's layout right\n// then, so a struct that cannot be laid out fails loud at registration, naming\n// it.\n//\n// TRINITY COMPUTES THE OFFSETS. This once required an engine-injected packer,\n// on the premise that the physical layout is BACKEND-SPECIFIC. That premise is\n// false for these buffers, verified 2026-07-28: every backend declares them as\n// a flat array of vec4 - WGSL `array<vec4<f32>, N>`, GLSL `vec4 cbN[N]`, or a\n// std140 block wrapping `vec4 data[N]` - and std140's stride for an array of\n// vec4 is 16 bytes, identical to tight C++ packing. The std140 rules that DO\n// diverge (vec3 padded to 16, scalar array stride) never engage, because there\n// are no struct members to pad: the translated shader indexes the flat array\n// and reassembles fields itself.\n//\n// Layouts resolve from two sources, in order:\n//\n//   1. CjsPerObjectLayouts, when the struct name is a Carbon struct. Those\n//      offsets are declared, not derived, because Carbon memcpy's the C++\n//      struct (EveSpaceObject2.cpp:1469-1483) and its members sit on float4\n//      boundaries - tight-packing a FLOAT member would drift from it.\n//   2. tight packing of the supplied def, for an ad-hoc struct the catalog\n//      does not carry.\n//\n// Offsets are FLOAT offsets relative to one instance's slot (the same offset\n// indexes the Float32 and Uint32 views).\n//\n// Allocation is an ARENA (bump), not a free-list:\n//   - Alloc(name) bumps a cursor and returns a view (\"snip off what you need\")\n//     into a RETAINED backing buffer - the buffer is NOT recreated per frame.\n//   - Reset() rewinds the cursor; every slot is freed at once, O(1); the\n//     chunks are kept and reused next frame.\n//   - There is no Unalloc: transient slots live until their batch dispatches,\n//     so Reset is the only free. Permanent per-object data is not Alloc'd - a\n//     static placeable constructs its own RawData and owns it across frames.\n//\n// Maps to Carbon: Alloc == accumulator.Allocate (Tr2Renderer::GetPoolAllocator,\n// reset per frame). No clear-on-Alloc, so an unwritten field shows the previous\n// tenant's bytes - that reproduces Carbon's \"unwritten slots = allocator\n// garbage\" (declared defaults are re-applied on Alloc; everything else is\n// write-what-you-rely-on).\n//\n// Design: PER-OBJECT-DATA-DESIGN-2026-07-24.md\nimport { RawData, RawDataType } from \"./RawData.js\";\nimport { CjsPerObjectLayouts } from \"./CjsPerObjectLayouts.js\";\n\n\n/** Declared catalog type -> the encoder kind that writes its bytes. */\nconst CATALOG_ENCODINGS = {\n  [CjsPerObjectLayouts.Types.MATRIX4]: RawDataType.MATRIX,\n  [CjsPerObjectLayouts.Types.UINT32]: RawDataType.UINT,\n  [CjsPerObjectLayouts.Types.INT32]: RawDataType.INT\n};\n\n\n/**\n * A catalog layout as a store field-def array.\n *\n * A default on an array field is repeated across every element: the store\n * applies each default at a single offset, and Carbon's neutral for a slot\n * (identity for an unused custom mask) applies to every slot, not just the\n * first.\n */\nfunction catalogDef(layout)\n{\n  const def = [];\n\n  for (const field of layout.fields.values())\n  {\n    let value = null;\n\n    if (field.default)\n    {\n      value = field.count > 1\n        ? Array.from({ length: field.count }, () => [ ...field.default ]).flat()\n        : [ ...field.default ];\n    }\n\n    def.push({\n      name: field.name,\n      size: field.size,\n      elements: field.count,\n      encoding: CATALOG_ENCODINGS[field.type] ?? RawDataType.VECTOR,\n      default: value\n    });\n  }\n\n  return def;\n}\n\n\n/**\n * Carbon's declared layout for a struct, or null when the catalog omits it.\n */\nfunction catalogLayout(structName)\n{\n  const layout = CjsPerObjectLayouts.Get(structName);\n\n  if (!layout)\n  {\n    return null;\n  }\n\n  const fields = {};\n\n  for (const field of layout.fields.values())\n  {\n    fields[field.name] = {\n      offset: field.offset,\n      size: field.size,\n      elements: field.count,\n      encoding: CATALOG_ENCODINGS[field.type] ?? RawDataType.VECTOR\n    };\n  }\n\n  return { fields, stride: layout.stride };\n}\n\n\n/**\n * Tight layout for an ad-hoc struct the catalog does not carry: fields in\n * declared order, no padding.\n */\nfunction tightLayout(normalized)\n{\n  const fields = {};\n  let offset = 0;\n\n  for (const field of normalized)\n  {\n    fields[field.name] = {\n      offset,\n      size: field.size,\n      elements: field.elements,\n      encoding: field.encoding\n    };\n    offset += field.size * field.elements;\n  }\n\n  return { fields, stride: offset };\n}\n\n\n/** Registers constant-data struct shapes and leases packed payloads from a per-engine arena. */\nexport class TriPoolAllocator\n{\n  /** Registered layouts: name -> { fields, stride, defaults }. */\n  #layouts = new Map();\n\n  /** Retained arena chunks (Float32) and their Uint32 aliases. */\n  #chunks = [];\n\n  #chunkAliases = [];\n\n  /** Floats per chunk; also the largest struct a single Alloc may request. */\n  #chunkFloats = 8192;\n\n  #chunkIndex = 0;\n\n  #cursor = 0;\n\n  /**\n   * @param {object} [options]\n   * @param {number} [options.chunkFloats] - arena chunk size in floats.\n   */\n  constructor(options = {})\n  {\n    if (Number.isInteger(options.chunkFloats) && options.chunkFloats > 0)\n    {\n      this.#chunkFloats = options.chunkFloats;\n    }\n\n    this.#AddChunk();\n  }\n\n  /**\n   * Register several structs at once: { StructName: def, ... }. Each value is a\n   * field-def array (see RegisterStruct) or { def, stages } when the struct\n   * binds anywhere other than the default vertex-stage slot. Returns the store\n   * for chaining.\n   */\n  Register(structs)\n  {\n    for (const name of Object.keys(structs))\n    {\n      const entry = structs[name];\n\n      if (Array.isArray(entry))\n      {\n        this.RegisterStruct(name, entry);\n      }\n      else\n      {\n        this.RegisterStruct(name, entry.def, { stages: entry.stages });\n      }\n    }\n\n    return this;\n  }\n\n  /**\n   * Register one struct and RESOLVE its layout immediately. `def` is an array\n   * of field defs: { name, encoding, size, elements?, default? }, where `size`\n   * may instead be a defaults ARRAY whose length is the size. Omit `def`\n   * entirely for a Carbon struct and the catalog supplies it. Returns the store\n   * for chaining.\n   *\n   * `options.stages` declares which per-object constant slots the payload binds\n   * (default [\"vs\"]). This is Carbon-SEMANTIC knowledge - which\n   * FillAndSetConstants calls exist for the struct - so it travels with the def\n   * rather than the layout: [\"vs\"] a vertex-stage payload, [\"ps\"] a pixel payload (one\n   * half of a { vs, ps } record), [\"vs\", \"ps\"] the SAME bytes bound to both\n   * slots (sphere pin, lensflare). The engine reads it from GetLayout().stages.\n   */\n  RegisterStruct(name, def, options = {})\n  {\n    if (def === undefined)\n    {\n      // No def supplied: take Carbon's, from the catalog.\n      const layout = CjsPerObjectLayouts.Get(name);\n\n      if (!layout)\n      {\n        throw new Error(\n          `TriPoolAllocator: struct \"${name}\" is not in CjsPerObjectLayouts - add it there, or pass a def explicitly`\n        );\n      }\n\n      def = catalogDef(layout);\n      options = { ...options, stages: options.stages ?? layout.stages };\n    }\n\n    const normalized = TriPoolAllocator.normalizeDef(def);\n    const stages = TriPoolAllocator.normalizeStages(name, options.stages);\n\n    // Carbon's declared offsets win: its members sit on float4 boundaries, so\n    // tight-packing them would drift the moment a struct carries a FLOAT.\n    const resolved = catalogLayout(name) ?? tightLayout(normalized);\n\n    if (resolved.stride > this.#chunkFloats)\n    {\n      throw new Error(`TriPoolAllocator: struct \"${name}\" (${resolved.stride} floats) exceeds the chunk size (${this.#chunkFloats})`);\n    }\n\n    const defaults = [];\n\n    for (const field of normalized)\n    {\n      if (field.default)\n      {\n        const entry = resolved.fields[field.name];\n\n        if (entry)\n        {\n          defaults.push({ offset: entry.offset, values: field.default });\n        }\n      }\n    }\n\n    this.#layouts.set(name, { fields: resolved.fields, stride: resolved.stride, defaults, stages });\n\n    return this;\n  }\n\n  /** Whether a struct has been registered on this store. */\n  Has(name)\n  {\n    return this.#layouts.has(name);\n  }\n\n  /**\n   * Lease a TRANSIENT payload for a registered struct. Bumps the arena and\n   * returns a RawData view over the next slot, with declared defaults applied.\n   * Valid until the next Reset().\n   */\n  Alloc(name)\n  {\n    const layout = this.#layouts.get(name);\n\n    if (!layout)\n    {\n      throw new Error(`TriPoolAllocator: struct \"${name}\" is not registered on this store (call Register/RegisterStruct first)`);\n    }\n\n    const stride = layout.stride;\n\n    if (this.#cursor + stride > this.#chunkFloats)\n    {\n      this.#chunkIndex++;\n      this.#cursor = 0;\n\n      if (this.#chunkIndex >= this.#chunks.length)\n      {\n        this.#AddChunk();\n      }\n    }\n\n    const start = this.#cursor;\n    this.#cursor += stride;\n\n    const floats = this.#chunks[this.#chunkIndex].subarray(start, start + stride);\n    const uints = this.#chunkAliases[this.#chunkIndex].subarray(start, start + stride);\n\n    for (const preset of layout.defaults)\n    {\n      const values = preset.values;\n\n      for (let index = 0; index < values.length; index++)\n      {\n        floats[preset.offset + index] = values[index];\n      }\n    }\n\n    return new RawData(layout, floats, uints, name);\n  }\n\n  /**\n   * Free every transient slot at once (frame end). Rewinds the arena cursor;\n   * the backing chunks are RETAINED and reused - nothing is reallocated.\n   */\n  Reset()\n  {\n    this.#chunkIndex = 0;\n    this.#cursor = 0;\n  }\n\n  /**\n   * Appends a fresh arena chunk of chunkFloats floats plus a Uint32 alias view\n   * over the same bytes, so payload fields can be written as floats or raw bits.\n   */\n  #AddChunk()\n  {\n    const chunk = new Float32Array(this.#chunkFloats);\n    this.#chunks.push(chunk);\n    this.#chunkAliases.push(new Uint32Array(chunk.buffer));\n  }\n\n  /** The field encoding kinds (packing directives). */\n  static Type = RawDataType;\n\n  /** The per-object binding slots a struct may declare via options.stages. */\n  static Stages = Object.freeze([\"vs\", \"ps\", \"gs\", \"cs\", \"hs\", \"ds\"]);\n\n  /**\n   * Validate a stages declaration: a non-empty array drawn from\n   * TriPoolAllocator.Stages, no duplicates. Defaults to [\"vs\"] (Carbon's most\n   * common single-payload binding). Returns a frozen copy.\n   */\n  static normalizeStages(structName, stages)\n  {\n    if (stages === undefined || stages === null)\n    {\n      return TriPoolAllocator.defaultStages;\n    }\n\n    if (!Array.isArray(stages) || !stages.length)\n    {\n      throw new Error(`TriPoolAllocator: struct \"${structName}\" stages must be a non-empty array`);\n    }\n\n    for (const stage of stages)\n    {\n      if (!TriPoolAllocator.Stages.includes(stage))\n      {\n        throw new Error(`TriPoolAllocator: struct \"${structName}\" has unknown stage \"${stage}\" (expected one of: ${TriPoolAllocator.Stages.join(\", \")})`);\n      }\n    }\n\n    if (new Set(stages).size !== stages.length)\n    {\n      throw new Error(`TriPoolAllocator: struct \"${structName}\" declares a duplicate stage`);\n    }\n\n    return Object.freeze([...stages]);\n  }\n\n  static defaultStages = Object.freeze([\"vs\"]);\n\n  /**\n   * Normalize a raw def: default elements to 1, resolve size-as-defaults-array,\n   * require a name and encoding. Physical offsets are NOT computed here - they\n   * are resolved at registration, from the catalog or by tight packing.\n   */\n  static normalizeDef(def)\n  {\n    return def.map(field =>\n    {\n      if (!field.name)\n      {\n        throw new Error(\"TriPoolAllocator: every struct field needs a name\");\n      }\n\n      if (!field.encoding)\n      {\n        throw new Error(`TriPoolAllocator: field \"${field.name}\" needs an encoding (TriPoolAllocator.Type.*)`);\n      }\n\n      let size = field.size;\n      let defaultValue = field.default ?? null;\n\n      if (Array.isArray(size))\n      {\n        defaultValue = size;\n        size = size.length;\n      }\n\n      if (!Number.isInteger(size) || size <= 0)\n      {\n        throw new Error(`TriPoolAllocator: field \"${field.name}\" needs a positive integer size`);\n      }\n\n      return {\n        name: field.name,\n        elements: Number.isInteger(field.elements) && field.elements > 0 ? field.elements : 1,\n        size,\n        encoding: field.encoding,\n        default: defaultValue\n      };\n    });\n  }\n\n}\n"],"names":["CATALOG_ENCODINGS","CjsPerObjectLayouts","Types","MATRIX4","RawDataType","MATRIX","UINT32","UINT","INT32","INT","catalogDef","layout","def","field","fields","values","value","default","count","Array","from","length","flat","push","name","size","elements","encoding","type","VECTOR","catalogLayout","structName","Get","offset","stride","tightLayout","normalized","TriPoolAllocator","Map","constructor","options","Number","isInteger","chunkFloats","Register","structs","Object","keys","entry","isArray","RegisterStruct","stages","undefined","Error","normalizeDef","normalizeStages","resolved","defaults","set","Has","has","Alloc","get","start","floats","subarray","uints","preset","index","RawData","Reset","#AddChunk","chunk","Float32Array","Uint32Array","buffer","Type","Stages","freeze","defaultStages","stage","includes","join","Set","map","defaultValue"],"mappings":"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"}

package/dist/utilities/Range.js

@@ -3,6 +3,12 @@ import { CjsModel } from '@carbonenginejs/runtime-utils/model';
 import { type, carbon, impl } from '@carbonenginejs/runtime-utils/schema';
 
 let _initProto, _initClass, _init_isUniform, _init_extra_isUniform, _init_centerPoint, _init_extra_centerPoint, _init_minRangePoint, _init_extra_minRangePoint, _init_maxRangePoint, _init_extra_maxRangePoint;
+
+/**
+ * A center point with a lower and an upper range point, optionally kept
+ * symmetric about the center, and clamped for display against separate slider
+ * bounds.
+ */
 let _Range;
 class Range extends CjsModel {
   static {
@@ -59,6 +65,8 @@ class Range extends CjsModel {
     }
     this.#syncRangePoints();
   }
+
+  /** Returns the point both range points are measured from. */
   GetCenterPoint() {
     return this.centerPoint;
   }
@@ -67,21 +75,41 @@ class Range extends CjsModel {
   GetMinRangePoint() {
     return this.minRangePoint;
   }
+
+  /**
+   * Returns the upper range point after Carbon's clamp, which is a min against
+   * the slider maximum, not a max (Range.cpp:68-71).
+   */
   GetMaxRangePoint() {
     return this.maxRangePoint;
   }
+
+  /**
+   * Flips symmetric mode, and when turning it on collapses both sides to the
+   * smaller of the two distances from the center.
+   */
   ToggleIsUniform() {
     this.isUniform = !this.isUniform;
     if (this.isUniform) {
       this.FixUniformity();
     }
   }
+
+  /**
+   * Sets symmetric mode, fixing up the range points immediately when enabling
+   * it.
+   */
   SetIsUniform(value) {
     this.isUniform = value;
     if (this.isUniform) {
       this.FixUniformity();
     }
   }
+
+  /**
+   * Makes the range symmetric by adopting the smaller of the two distances from
+   * the center on both sides, so uniformity narrows rather than widens.
+   */
   FixUniformity() {
     const minRangeDelta = this.centerPoint - this.#minRange;
     const maxRangeDelta = this.#maxRange - this.centerPoint;
@@ -89,23 +117,48 @@ class Range extends CjsModel {
     this.SetMinRangePoint(this.centerPoint - newDelta);
     this.SetMaxRangePoint(this.centerPoint + newDelta);
   }
+
+  /**
+   * Reports whether the two range points are being kept symmetric about the
+   * center.
+   */
   GetIsUniform() {
     return this.isUniform;
   }
+
+  /**
+   * Sets the lower slider bound the exposed range points are clamped against,
+   * and re-clamps them.
+   */
   SetSliderMin(value) {
     this.#sliderRangeMin = value;
     this.#syncRangePoints();
   }
+
+  /**
+   * Sets the upper slider bound the exposed range points are clamped against,
+   * and re-clamps them.
+   */
   SetSliderMax(value) {
     this.#sliderRangeMax = value;
     this.#syncRangePoints();
   }
+
+  /** Returns the lower slider bound used when clamping the exposed range points. */
   GetSliderMin() {
     return this.#sliderRangeMin;
   }
+
+  /** Returns the upper slider bound used when clamping the exposed range points. */
   GetSliderMax() {
     return this.#sliderRangeMax;
   }
+
+  /**
+   * Recomputes the exposed minRangePoint and maxRangePoint from the internal
+   * range and the slider bounds; Carbon derives these on read (Range.cpp:63-71)
+   * and clamps both with min, which is reproduced here rather than corrected.
+   */
   #syncRangePoints() {
     this.minRangePoint = Math.min(this.#minRange, this.#sliderRangeMin);
     this.maxRangePoint = Math.min(this.#maxRange, this.#sliderRangeMax);

package/dist/utilities/Range.js.map

@@ -1 +1 @@
-{"version":3,"file":"Range.js","sources":["../../../src/utilities/Range.js"],"sourcesContent":["// Source: E:\\carbonengine\\trinity\\trinity\\Utilities\\Range.h\n// Source: E:\\carbonengine\\trinity\\trinity\\Utilities\\Range.cpp\n// Source: E:\\carbonengine\\trinity\\trinity\\Utilities\\Range_Blue.cpp\nimport { CjsModel } from \"@carbonenginejs/runtime-utils/model\";\nimport { carbon, impl, type } from \"@carbonenginejs/runtime-utils/schema\";\n\n\n@type.define({\n  className: \"Range\",\n  family: \"utilities\"\n})\nexport class Range extends CjsModel\n{\n  @type.boolean\n  isUniform = true;\n\n  @type.float32\n  centerPoint = 0;\n\n  @type.float32\n  minRangePoint = 0;\n\n  @type.float32\n  maxRangePoint = 0;\n\n  #minRange = 0;\n\n  #maxRange = 0;\n\n  #sliderRangeMin = 0;\n\n  #sliderRangeMax = 0;\n\n  /** Moves the range while preserving both distances from its center. */\n  @carbon.method\n  @impl.implemented\n  SetCenterPoint(value)\n  {\n    const delta = value - this.centerPoint;\n    this.centerPoint = value;\n    this.#minRange += delta;\n    this.#maxRange += delta;\n    this.#syncRangePoints();\n  }\n\n  /** Configures the symmetric range and its slider bounds. */\n  @carbon.method\n  @impl.implemented\n  Setup(rangeCenterPoint, rangeDeltaFromCenter, sliderMin, sliderMax)\n  {\n    this.centerPoint = rangeCenterPoint;\n    this.#minRange = this.centerPoint - rangeDeltaFromCenter;\n    this.#maxRange = this.centerPoint + rangeDeltaFromCenter;\n    this.#sliderRangeMin = sliderMin;\n    this.#sliderRangeMax = sliderMax;\n    this.#syncRangePoints();\n  }\n\n  /** Sets the lower range point and mirrors it when uniform. */\n  @carbon.method\n  @impl.implemented\n  SetMinRangePoint(value)\n  {\n    this.#minRange = Math.min(value, this.centerPoint);\n    if (this.isUniform)\n    {\n      this.#maxRange = this.centerPoint + (this.centerPoint - this.#minRange);\n    }\n    this.#syncRangePoints();\n  }\n\n  /** Sets the upper range point and mirrors it when uniform. */\n  @carbon.method\n  @impl.implemented\n  SetMaxRangePoint(value)\n  {\n    this.#maxRange = Math.max(value, this.centerPoint);\n    if (this.isUniform)\n    {\n      this.#minRange = this.centerPoint - (this.#maxRange - this.centerPoint);\n    }\n    this.#syncRangePoints();\n  }\n\n  @carbon.method\n  @impl.implemented\n  GetCenterPoint()\n  {\n    return this.centerPoint;\n  }\n\n  /** Preserves Carbon's exact lower-bound comparison behavior. */\n  @carbon.method\n  @impl.implemented\n  GetMinRangePoint()\n  {\n    return this.minRangePoint;\n  }\n\n  @carbon.method\n  @impl.implemented\n  GetMaxRangePoint()\n  {\n    return this.maxRangePoint;\n  }\n\n  @carbon.method\n  @impl.implemented\n  ToggleIsUniform()\n  {\n    this.isUniform = !this.isUniform;\n    if (this.isUniform)\n    {\n      this.FixUniformity();\n    }\n  }\n\n  @carbon.method\n  @impl.implemented\n  SetIsUniform(value)\n  {\n    this.isUniform = value;\n    if (this.isUniform)\n    {\n      this.FixUniformity();\n    }\n  }\n\n  FixUniformity()\n  {\n    const minRangeDelta = this.centerPoint - this.#minRange;\n    const maxRangeDelta = this.#maxRange - this.centerPoint;\n    const newDelta = Math.min(minRangeDelta, maxRangeDelta);\n    this.SetMinRangePoint(this.centerPoint - newDelta);\n    this.SetMaxRangePoint(this.centerPoint + newDelta);\n  }\n\n  @carbon.method\n  @impl.implemented\n  GetIsUniform()\n  {\n    return this.isUniform;\n  }\n\n  @carbon.method\n  @impl.implemented\n  SetSliderMin(value)\n  {\n    this.#sliderRangeMin = value;\n    this.#syncRangePoints();\n  }\n\n  @carbon.method\n  @impl.implemented\n  SetSliderMax(value)\n  {\n    this.#sliderRangeMax = value;\n    this.#syncRangePoints();\n  }\n\n  @carbon.method\n  @impl.implemented\n  GetSliderMin()\n  {\n    return this.#sliderRangeMin;\n  }\n\n  @carbon.method\n  @impl.implemented\n  GetSliderMax()\n  {\n    return this.#sliderRangeMax;\n  }\n\n  #syncRangePoints()\n  {\n    this.minRangePoint = Math.min(this.#minRange, this.#sliderRangeMin);\n    this.maxRangePoint = Math.min(this.#maxRange, this.#sliderRangeMax);\n  }\n}\n"],"names":["_Range","Range","CjsModel","e","_init_isUniform","_init_extra_isUniform","_init_centerPoint","_init_extra_centerPoint","_init_minRangePoint","_init_extra_minRangePoint","_init_maxRangePoint","_init_extra_maxRangePoint","_initProto","c","_initClass","_applyDecs","type","define","className","family","boolean","float32","carbon","method","impl","implemented","isUniform","centerPoint","minRangePoint","maxRangePoint","SetCenterPoint","value","delta","Setup","rangeCenterPoint","rangeDeltaFromCenter","sliderMin","sliderMax","SetMinRangePoint","Math","min","SetMaxRangePoint","max","GetCenterPoint","GetMinRangePoint","GetMaxRangePoint","ToggleIsUniform","FixUniformity","SetIsUniform","minRangeDelta","maxRangeDelta","newDelta","GetIsUniform","SetSliderMin","SetSliderMax","GetSliderMin","GetSliderMax","#syncRangePoints"],"mappings":"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"}
+{"version":3,"file":"Range.js","sources":["../../../src/utilities/Range.js"],"sourcesContent":["// Source: E:\\carbonengine\\trinity\\trinity\\Utilities\\Range.h\r\n// Source: E:\\carbonengine\\trinity\\trinity\\Utilities\\Range.cpp\r\n// Source: E:\\carbonengine\\trinity\\trinity\\Utilities\\Range_Blue.cpp\r\nimport { CjsModel } from \"@carbonenginejs/runtime-utils/model\";\r\nimport { carbon, impl, type } from \"@carbonenginejs/runtime-utils/schema\";\r\n\r\n\r\n/**\r\n * A center point with a lower and an upper range point, optionally kept\r\n * symmetric about the center, and clamped for display against separate slider\r\n * bounds.\r\n */\r\n@type.define({\r\n  className: \"Range\",\r\n  family: \"utilities\"\r\n})\r\nexport class Range extends CjsModel\r\n{\r\n  @type.boolean\r\n  isUniform = true;\r\n\r\n  @type.float32\r\n  centerPoint = 0;\r\n\r\n  @type.float32\r\n  minRangePoint = 0;\r\n\r\n  @type.float32\r\n  maxRangePoint = 0;\r\n\r\n  #minRange = 0;\r\n\r\n  #maxRange = 0;\r\n\r\n  #sliderRangeMin = 0;\r\n\r\n  #sliderRangeMax = 0;\r\n\r\n  /** Moves the range while preserving both distances from its center. */\r\n  @carbon.method\r\n  @impl.implemented\r\n  SetCenterPoint(value)\r\n  {\r\n    const delta = value - this.centerPoint;\r\n    this.centerPoint = value;\r\n    this.#minRange += delta;\r\n    this.#maxRange += delta;\r\n    this.#syncRangePoints();\r\n  }\r\n\r\n  /** Configures the symmetric range and its slider bounds. */\r\n  @carbon.method\r\n  @impl.implemented\r\n  Setup(rangeCenterPoint, rangeDeltaFromCenter, sliderMin, sliderMax)\r\n  {\r\n    this.centerPoint = rangeCenterPoint;\r\n    this.#minRange = this.centerPoint - rangeDeltaFromCenter;\r\n    this.#maxRange = this.centerPoint + rangeDeltaFromCenter;\r\n    this.#sliderRangeMin = sliderMin;\r\n    this.#sliderRangeMax = sliderMax;\r\n    this.#syncRangePoints();\r\n  }\r\n\r\n  /** Sets the lower range point and mirrors it when uniform. */\r\n  @carbon.method\r\n  @impl.implemented\r\n  SetMinRangePoint(value)\r\n  {\r\n    this.#minRange = Math.min(value, this.centerPoint);\r\n    if (this.isUniform)\r\n    {\r\n      this.#maxRange = this.centerPoint + (this.centerPoint - this.#minRange);\r\n    }\r\n    this.#syncRangePoints();\r\n  }\r\n\r\n  /** Sets the upper range point and mirrors it when uniform. */\r\n  @carbon.method\r\n  @impl.implemented\r\n  SetMaxRangePoint(value)\r\n  {\r\n    this.#maxRange = Math.max(value, this.centerPoint);\r\n    if (this.isUniform)\r\n    {\r\n      this.#minRange = this.centerPoint - (this.#maxRange - this.centerPoint);\r\n    }\r\n    this.#syncRangePoints();\r\n  }\r\n\r\n  /** Returns the point both range points are measured from. */\r\n  @carbon.method\r\n  @impl.implemented\r\n  GetCenterPoint()\r\n  {\r\n    return this.centerPoint;\r\n  }\r\n\r\n  /** Preserves Carbon's exact lower-bound comparison behavior. */\r\n  @carbon.method\r\n  @impl.implemented\r\n  GetMinRangePoint()\r\n  {\r\n    return this.minRangePoint;\r\n  }\r\n\r\n  /**\r\n   * Returns the upper range point after Carbon's clamp, which is a min against\r\n   * the slider maximum, not a max (Range.cpp:68-71).\r\n   */\r\n  @carbon.method\r\n  @impl.implemented\r\n  GetMaxRangePoint()\r\n  {\r\n    return this.maxRangePoint;\r\n  }\r\n\r\n  /**\r\n   * Flips symmetric mode, and when turning it on collapses both sides to the\r\n   * smaller of the two distances from the center.\r\n   */\r\n  @carbon.method\r\n  @impl.implemented\r\n  ToggleIsUniform()\r\n  {\r\n    this.isUniform = !this.isUniform;\r\n    if (this.isUniform)\r\n    {\r\n      this.FixUniformity();\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Sets symmetric mode, fixing up the range points immediately when enabling\r\n   * it.\r\n   */\r\n  @carbon.method\r\n  @impl.implemented\r\n  SetIsUniform(value)\r\n  {\r\n    this.isUniform = value;\r\n    if (this.isUniform)\r\n    {\r\n      this.FixUniformity();\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Makes the range symmetric by adopting the smaller of the two distances from\r\n   * the center on both sides, so uniformity narrows rather than widens.\r\n   */\r\n  FixUniformity()\r\n  {\r\n    const minRangeDelta = this.centerPoint - this.#minRange;\r\n    const maxRangeDelta = this.#maxRange - this.centerPoint;\r\n    const newDelta = Math.min(minRangeDelta, maxRangeDelta);\r\n    this.SetMinRangePoint(this.centerPoint - newDelta);\r\n    this.SetMaxRangePoint(this.centerPoint + newDelta);\r\n  }\r\n\r\n  /**\r\n   * Reports whether the two range points are being kept symmetric about the\r\n   * center.\r\n   */\r\n  @carbon.method\r\n  @impl.implemented\r\n  GetIsUniform()\r\n  {\r\n    return this.isUniform;\r\n  }\r\n\r\n  /**\r\n   * Sets the lower slider bound the exposed range points are clamped against,\r\n   * and re-clamps them.\r\n   */\r\n  @carbon.method\r\n  @impl.implemented\r\n  SetSliderMin(value)\r\n  {\r\n    this.#sliderRangeMin = value;\r\n    this.#syncRangePoints();\r\n  }\r\n\r\n  /**\r\n   * Sets the upper slider bound the exposed range points are clamped against,\r\n   * and re-clamps them.\r\n   */\r\n  @carbon.method\r\n  @impl.implemented\r\n  SetSliderMax(value)\r\n  {\r\n    this.#sliderRangeMax = value;\r\n    this.#syncRangePoints();\r\n  }\r\n\r\n  /** Returns the lower slider bound used when clamping the exposed range points. */\r\n  @carbon.method\r\n  @impl.implemented\r\n  GetSliderMin()\r\n  {\r\n    return this.#sliderRangeMin;\r\n  }\r\n\r\n  /** Returns the upper slider bound used when clamping the exposed range points. */\r\n  @carbon.method\r\n  @impl.implemented\r\n  GetSliderMax()\r\n  {\r\n    return this.#sliderRangeMax;\r\n  }\r\n\r\n  /**\r\n   * Recomputes the exposed minRangePoint and maxRangePoint from the internal\r\n   * range and the slider bounds; Carbon derives these on read (Range.cpp:63-71)\r\n   * and clamps both with min, which is reproduced here rather than corrected.\r\n   */\r\n  #syncRangePoints()\r\n  {\r\n    this.minRangePoint = Math.min(this.#minRange, this.#sliderRangeMin);\r\n    this.maxRangePoint = Math.min(this.#maxRange, this.#sliderRangeMax);\r\n  }\r\n}\r\n"],"names":["_Range","Range","CjsModel","e","_init_isUniform","_init_extra_isUniform","_init_centerPoint","_init_extra_centerPoint","_init_minRangePoint","_init_extra_minRangePoint","_init_maxRangePoint","_init_extra_maxRangePoint","_initProto","c","_initClass","_applyDecs","type","define","className","family","boolean","float32","carbon","method","impl","implemented","isUniform","centerPoint","minRangePoint","maxRangePoint","SetCenterPoint","value","delta","Setup","rangeCenterPoint","rangeDeltaFromCenter","sliderMin","sliderMax","SetMinRangePoint","Math","min","SetMaxRangePoint","max","GetCenterPoint","GetMinRangePoint","GetMaxRangePoint","ToggleIsUniform","FixUniformity","SetIsUniform","minRangeDelta","maxRangeDelta","newDelta","GetIsUniform","SetSliderMin","SetSliderMax","GetSliderMin","GetSliderMax","#syncRangePoints"],"mappings":"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"}

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.