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

package/dist/trinityal/webgpu/CjsWebgpuResourceSetAL.js.map

@@ -1 +1 @@
-{"version":3,"file":"CjsWebgpuResourceSetAL.js","sources":["../../../../src/trinityal/webgpu/CjsWebgpuResourceSetAL.js"],"sourcesContent":["// Source: trinity/trinityal/include/Tr2ResourceSetAL.h\r\n//   trinity/trinityal/metal/Tr2ResourceSetALMetal.mm\r\n//   trinity/trinityal/dx12/Tr2ResourceSetALDx12.cpp\r\n//\r\n// A `Tr2ResourceSetAL` for WebGPU: the description's textures, samplers and\r\n// buffers resolved against the program's bindings, ready to become bind groups.\r\n//\r\n// WHAT IT HOLDS AND WHAT IT DOES NOT. Carbon's description carries SRVs, UAVs\r\n// and samplers; constant buffers are NOT in it (`Tr2ResourceSetAL.h:57-65` has\r\n// no `SetConstantBuffer`) - they travel `SetConstants` and are bound beside the\r\n// set at the draw (DX12 root CBVs via `m_cbRegisters`, Metal's const-buffer\r\n// offset region). So this resolves every non-uniform slot of the program's\r\n// layout at Create, as Metal's `Create` fills its per-stage native arrays\r\n// (`Tr2ResourceSetALMetal.mm:57-279`), and the render context assembles each\r\n// `GPUBindGroup` from these entries plus the bound constant buffers when it\r\n// draws - a bind group being immutable, it can only exist once both halves are\r\n// known.\r\n//\r\n// UNFILLED SLOTS GET DUMMIES, AS METAL'S DO. Metal seeds its masks from the\r\n// program's requirements and fills what the description left empty with\r\n// `GetDummyTexture` / `GetDummySampler` (`:240-265`); DX12 substitutes null\r\n// views (`Tr2ResourceSetALDx12.cpp:145-146`). A WebGPU bind group with a hole\r\n// is a validation error, so the same substitution happens here.\r\n//\r\nimport { CjsSchema } from \"#schema\";\r\nimport { impl } from \"#schema\";\r\nimport { ALResult, Tr2ALMemoryType } from \"#trinityal\";\r\nimport { ShaderType } from \"#consts/render-context\";\r\n\r\n/** GPUShaderStage bits to the Carbon stage whose description slot answers. */\r\nconst STAGE_OF_VISIBILITY = Object.freeze([\r\n  [ 1, ShaderType.VERTEX_SHADER ],\r\n  [ 2, ShaderType.PIXEL_SHADER ],\r\n  [ 4, ShaderType.COMPUTE_SHADER ]\r\n]);\r\n\r\nlet nextResourceSetId = 1;\r\n\r\n\r\n/**\r\n * The description slot a binding reads, trying each stage it is visible to.\r\n *\r\n * A binding two stages share was merged by the container because both read\r\n * the same register; whichever stage the material filled answers.\r\n */\r\nfunction SlotFor(description, kind, binding)\r\n{\r\n  for (const [ bit, stage ] of STAGE_OF_VISIBILITY)\r\n  {\r\n    if ((binding.visibility & bit) === 0) continue;\r\n\r\n    const map = description.m_registerMap;\r\n    const slots = kind === \"srv\" ? map.srvs : kind === \"uav\" ? map.uavs : map.samplers;\r\n    const records = kind === \"srv\" ? description.m_srv : kind === \"uav\" ? description.m_uav : description.m_samplers;\r\n    const slot = records?.[slots[stage][binding.registerIndex]];\r\n    if (slot && slot.type !== 0) return slot;\r\n  }\r\n\r\n  return null;\r\n}\r\n\r\n\r\n/**\r\n * A `Tr2ResourceSetAL` holding the resolved bindings a draw's bind groups are\r\n * assembled from.\r\n */\r\nexport class CjsWebgpuResourceSetAL\r\n{\r\n  /** A process-unique identity, for the context's bind-group cache. Zero until Create. */\r\n  m_id = 0;\r\n\r\n  m_description = null;\r\n\r\n  m_program = null;\r\n\r\n  /** `\"group:binding\"` to the `GPUBindingResource` that fills it, non-uniform slots only. */\r\n  m_entries = new Map();\r\n\r\n  /**\r\n   * Resolves the description against the program.\r\n   *\r\n   * @param {object} description A `Tr2ResourceSetDescriptionAL`.\r\n   * @param {object} program The `CjsWebgpuShaderProgramAL` this set binds against.\r\n   * @param {object} renderContext The WebGPU render context AL.\r\n   * @returns {number} An `ALResult` value.\r\n   */\r\n  @impl.adapted\r\n  @impl.reason(\"WebGPU resolves native dense records into bind-group entries, validates the program map and fills missing resources with dummies. Descriptor heap views have no WebGPU representation and return E_FAIL.\")\r\n  Create(description, program, renderContext)\r\n  {\r\n    this.Destroy();\r\n\r\n    if (!renderContext || !renderContext.IsValid()) return ALResult.E_INVALIDARG;\r\n    if (!description) return ALResult.E_INVALIDARG;\r\n\r\n    // DX12 refuses a description whose register map is not the program's\r\n    // (`Tr2ResourceSetALDx12.cpp:78-81`); a program this backend did not link\r\n    // has no bindings to lay out against, which is the same refusal.\r\n    if (!program || typeof program.GetBindings !== \"function\" || !program.IsValid()) return ALResult.E_INVALIDARG;\r\n\r\n    if (!description.m_registerMap.equals(program.GetRegisterMap())) return ALResult.E_INVALIDARG;\r\n\r\n    if (description.m_srv?.some(record => record.type === 3)\r\n      || description.m_uav?.some(record => record.type === 3)\r\n      || description.m_samplers?.some(record => record.type === 2)) return ALResult.E_FAIL;\r\n\r\n    const entries = new Map();\r\n\r\n    for (const binding of program.GetBindings())\r\n    {\r\n      // Constant buffers are not the set's; see the head note.\r\n      if (binding.buffer && binding.buffer.type === \"uniform\") continue;\r\n\r\n      entries.set(`${binding.group}:${binding.binding}`, this._Resolve(description, binding, renderContext));\r\n    }\r\n\r\n    this.m_entries = entries;\r\n    this.m_description = description;\r\n    this.m_program = program;\r\n    this.m_id = nextResourceSetId;\r\n    nextResourceSetId += 1;\r\n\r\n    return ALResult.S_OK;\r\n  }\r\n\r\n  /** One slot's resource, or the dummy Metal would put there. */\r\n  @impl.adapted\r\n  @impl.reason(\"Resolves dense native records to WebGPU views and buffers; a pending resource or empty slot uses the context dummy, following Metal.\")\r\n  _Resolve(description, binding, renderContext)\r\n  {\r\n    if (binding.sampler)\r\n    {\r\n      const slot = SlotFor(description, \"sampler\", binding);\r\n      const state = slot?.type === 1 ? slot.sampler : null;\r\n      const sampler = state && typeof state.GetSampler === \"function\" ? state.GetSampler() : null;\r\n\r\n      return sampler ?? renderContext.GetDummySampler();\r\n    }\r\n\r\n    if (binding.texture)\r\n    {\r\n      const slot = SlotFor(description, \"srv\", binding);\r\n      const texture = slot?.type === 2 ? slot.texture : null;\r\n      const dimension = binding.texture.viewDimension ?? \"2d\";\r\n      const view = texture && typeof texture.GetDeviceTextureView === \"function\"\r\n        ? texture.GetDeviceTextureView(dimension, slot.colorSpace)\r\n        : null;\r\n\r\n      return view ?? renderContext.GetDummyTexture(dimension);\r\n    }\r\n\r\n    // A storage buffer: read-only ones are SRVs, writable ones UAVs.\r\n    const kind = binding.buffer && binding.buffer.type === \"storage\" ? \"uav\" : \"srv\";\r\n    const slot = SlotFor(description, kind, binding);\r\n    const resource = slot?.type === 1 ? slot.buffer : null;\r\n    const buffer = resource && typeof resource.GetDeviceBuffer === \"function\" ? resource.GetDeviceBuffer() : null;\r\n\r\n    return { buffer: buffer ?? renderContext.GetNullBuffer(binding.buffer?.minBindingSize ?? 16, \"STORAGE\") };\r\n  }\r\n\r\n  /** The resolved entries by `\"group:binding\"`. @returns {Map<string, object>} */\r\n  GetEntries()\r\n  {\r\n    return this.m_entries;\r\n  }\r\n\r\n  /** The `Tr2ResourceSetDescriptionAL` it was created from, or null. */\r\n  GetDescription()\r\n  {\r\n    return this.m_description;\r\n  }\r\n\r\n  /** The shader program whose bindings were resolved, or null. */\r\n  GetProgram()\r\n  {\r\n    return this.m_program;\r\n  }\r\n\r\n  /** Whether the set has been created and carries an identity. */\r\n  IsValid()\r\n  {\r\n    return this.m_id !== 0;\r\n  }\r\n\r\n  /** Drops the resolved entries, leaving the set invalid. */\r\n  Destroy()\r\n  {\r\n    this.m_entries = new Map();\r\n    this.m_description = null;\r\n    this.m_program = null;\r\n    this.m_id = 0;\r\n  }\r\n\r\n  /** Where the set lives, which is managed memory rather than the device. */\r\n  GetMemoryClass()\r\n  {\r\n    return Tr2ALMemoryType.AL_MEMORY_MANAGED;\r\n  }\r\n\r\n  /**\r\n   * Fills in a device-resource description.\r\n   *\r\n   * @param {object} description The description to fill.\r\n   * @returns {object} The description, filled.\r\n   */\r\n  Describe(description)\r\n  {\r\n    if (!description) return description;\r\n\r\n    description.memoryClass = this.GetMemoryClass();\r\n\r\n    return description;\r\n  }\r\n\r\n  /**\r\n   * Nothing here carries a label - the bind groups the context builds do.\r\n   *\r\n   * @returns {number} `S_OK`.\r\n   */\r\n  SetName(_name)\r\n  {\r\n    return ALResult.S_OK;\r\n  }\r\n}\r\n\r\n// DECLARED AS A CALL, NOT A DECORATOR, for the reason recorded in\r\n// Tr2BitmapDimensions.js: the layer is imported straight from source by its\r\n// tests and raw Node cannot parse decorator syntax.\r\n//\r\n// The donor is NAMED rather than left to be derived from this class's name.\r\n// Carbon calls every backend's class the same thing and carries the backend in\r\n// the FILE name, because only one backend compiles at a time; we ship them\r\n// together, so the backend moves onto the class name. That divergence is the\r\n// author's to declare, never a checker's to guess.\r\nCjsSchema.define(CjsWebgpuResourceSetAL, { className: \"CjsWebgpuResourceSetAL\", carbon: \"Tr2ResourceSetAL\" });\r\n"],"names":["STAGE_OF_VISIBILITY","Object","freeze","ShaderType","VERTEX_SHADER","PIXEL_SHADER","COMPUTE_SHADER","nextResourceSetId","SlotFor","description","kind","binding","bit","stage","visibility","map","m_registerMap","slots","srvs","uavs","samplers","records","m_srv","m_uav","m_samplers","slot","registerIndex","type","CjsWebgpuResourceSetAL","_initProto","_applyDecs","impl","adapted","reason","e","m_id","m_description","m_program","m_entries","Map","Create","program","renderContext","Destroy","IsValid","ALResult","E_INVALIDARG","GetBindings","equals","GetRegisterMap","some","record","E_FAIL","entries","buffer","set","group","_Resolve","S_OK","sampler","state","GetSampler","GetDummySampler","texture","dimension","viewDimension","view","GetDeviceTextureView","colorSpace","GetDummyTexture","resource","GetDeviceBuffer","GetNullBuffer","minBindingSize","GetEntries","GetDescription","GetProgram","GetMemoryClass","Tr2ALMemoryType","AL_MEMORY_MANAGED","Describe","memoryClass","SetName","_name","CjsSchema","define","className","carbon"],"mappings":"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"}
+{"version":3,"file":"CjsWebgpuResourceSetAL.js","sources":["../../../../src/trinityal/webgpu/CjsWebgpuResourceSetAL.js"],"sourcesContent":["// Source: trinity/trinityal/include/Tr2ResourceSetAL.h\r\n//   trinity/trinityal/metal/Tr2ResourceSetALMetal.mm\r\n//   trinity/trinityal/dx12/Tr2ResourceSetALDx12.cpp\r\n//\r\n// A `Tr2ResourceSetAL` for WebGPU: the description's textures, samplers and\r\n// buffers resolved against the program's bindings, ready to become bind groups.\r\n//\r\n// WHAT IT HOLDS AND WHAT IT DOES NOT. Carbon's description carries SRVs, UAVs\r\n// and samplers; constant buffers are NOT in it (`Tr2ResourceSetAL.h:57-65` has\r\n// no `SetConstantBuffer`) - they travel `SetConstants` and are bound beside the\r\n// set at the draw (DX12 root CBVs via `m_cbRegisters`, Metal's const-buffer\r\n// offset region). So this resolves every non-uniform slot of the program's\r\n// layout at Create, as Metal's `Create` fills its per-stage native arrays\r\n// (`Tr2ResourceSetALMetal.mm:57-279`), and the render context assembles each\r\n// `GPUBindGroup` from these entries plus the bound constant buffers when it\r\n// draws - a bind group being immutable, it can only exist once both halves are\r\n// known.\r\n//\r\n// UNFILLED SLOTS GET DUMMIES, AS METAL'S DO. Metal seeds its masks from the\r\n// program's requirements and fills what the description left empty with\r\n// `GetDummyTexture` / `GetDummySampler` (`:240-265`); DX12 substitutes null\r\n// views (`Tr2ResourceSetALDx12.cpp:145-146`). A WebGPU bind group with a hole\r\n// is a validation error, so the same substitution happens here.\r\n//\r\nimport { CjsSchema, impl } from \"#schema\";\r\nimport { ALResult, Tr2ALMemoryType } from \"#trinityal\";\r\nimport { ShaderType } from \"#consts/render-context\";\r\n\r\n/** GPUShaderStage bits to the Carbon stage whose description slot answers. */\r\nconst STAGE_OF_VISIBILITY = Object.freeze([\r\n  [ 1, ShaderType.VERTEX_SHADER ],\r\n  [ 2, ShaderType.PIXEL_SHADER ],\r\n  [ 4, ShaderType.COMPUTE_SHADER ]\r\n]);\r\n\r\nlet nextResourceSetId = 1;\r\n\r\n\r\n/**\r\n * The description slot a binding reads, trying each stage it is visible to.\r\n *\r\n * A binding two stages share was merged by the container because both read\r\n * the same register; whichever stage the material filled answers.\r\n */\r\nfunction SlotFor(description, kind, binding)\r\n{\r\n  for (const [ bit, stage ] of STAGE_OF_VISIBILITY)\r\n  {\r\n    if ((binding.visibility & bit) === 0) continue;\r\n\r\n    const map = description.m_registerMap;\r\n    const slots = kind === \"srv\" ? map.srvs : kind === \"uav\" ? map.uavs : map.samplers;\r\n    const records = kind === \"srv\" ? description.m_srv : kind === \"uav\" ? description.m_uav : description.m_samplers;\r\n    const slot = records?.[slots[stage][binding.registerIndex]];\r\n    if (slot && slot.type !== 0) return slot;\r\n  }\r\n\r\n  return null;\r\n}\r\n\r\n\r\n/**\r\n * A `Tr2ResourceSetAL` holding the resolved bindings a draw's bind groups are\r\n * assembled from.\r\n */\r\nexport class CjsWebgpuResourceSetAL\r\n{\r\n  /** A process-unique identity, for the context's bind-group cache. Zero until Create. */\r\n  m_id = 0;\r\n\r\n  m_description = null;\r\n\r\n  m_program = null;\r\n\r\n  /** `\"group:binding\"` to the `GPUBindingResource` that fills it, non-uniform slots only. */\r\n  m_entries = new Map();\r\n\r\n  /**\r\n   * Resolves the description against the program.\r\n   *\r\n   * @param {object} description A `Tr2ResourceSetDescriptionAL`.\r\n   * @param {object} program The `CjsWebgpuShaderProgramAL` this set binds against.\r\n   * @param {object} renderContext The WebGPU render context AL.\r\n   * @returns {number} An `ALResult` value.\r\n   */\r\n  @impl.adapted\r\n  @impl.reason(\"WebGPU resolves native dense records into bind-group entries, validates the program map and fills missing resources with dummies. Descriptor heap views have no WebGPU representation and return E_FAIL.\")\r\n  Create(description, program, renderContext)\r\n  {\r\n    this.Destroy();\r\n\r\n    if (!renderContext || !renderContext.IsValid()) return ALResult.E_INVALIDARG;\r\n    if (!description) return ALResult.E_INVALIDARG;\r\n\r\n    // DX12 refuses a description whose register map is not the program's\r\n    // (`Tr2ResourceSetALDx12.cpp:78-81`); a program this backend did not link\r\n    // has no bindings to lay out against, which is the same refusal.\r\n    if (!program || typeof program.GetBindings !== \"function\" || !program.IsValid()) return ALResult.E_INVALIDARG;\r\n\r\n    if (!description.m_registerMap.equals(program.GetRegisterMap())) return ALResult.E_INVALIDARG;\r\n\r\n    if (description.m_srv?.some(record => record.type === 3)\r\n      || description.m_uav?.some(record => record.type === 3)\r\n      || description.m_samplers?.some(record => record.type === 2)) return ALResult.E_FAIL;\r\n\r\n    const entries = new Map();\r\n\r\n    for (const binding of program.GetBindings())\r\n    {\r\n      // Constant buffers are not the set's; see the head note.\r\n      if (binding.buffer && binding.buffer.type === \"uniform\") continue;\r\n\r\n      entries.set(`${binding.group}:${binding.binding}`, this._Resolve(description, binding, renderContext));\r\n    }\r\n\r\n    this.m_entries = entries;\r\n    this.m_description = description;\r\n    this.m_program = program;\r\n    this.m_id = nextResourceSetId;\r\n    nextResourceSetId += 1;\r\n\r\n    return ALResult.S_OK;\r\n  }\r\n\r\n  /** One slot's resource, or the dummy Metal would put there. */\r\n  @impl.adapted\r\n  @impl.reason(\"Resolves dense native records to WebGPU views and buffers; a pending resource or empty slot uses the context dummy, following Metal.\")\r\n  _Resolve(description, binding, renderContext)\r\n  {\r\n    if (binding.sampler)\r\n    {\r\n      const slot = SlotFor(description, \"sampler\", binding);\r\n      const state = slot?.type === 1 ? slot.sampler : null;\r\n      const sampler = state && typeof state.GetSampler === \"function\" ? state.GetSampler() : null;\r\n\r\n      return sampler ?? renderContext.GetDummySampler();\r\n    }\r\n\r\n    if (binding.texture)\r\n    {\r\n      const slot = SlotFor(description, \"srv\", binding);\r\n      const texture = slot?.type === 2 ? slot.texture : null;\r\n      const dimension = binding.texture.viewDimension ?? \"2d\";\r\n      const view = texture && typeof texture.GetDeviceTextureView === \"function\"\r\n        ? texture.GetDeviceTextureView(dimension, slot.colorSpace)\r\n        : null;\r\n\r\n      return view ?? renderContext.GetDummyTexture(dimension);\r\n    }\r\n\r\n    // A storage buffer: read-only ones are SRVs, writable ones UAVs.\r\n    const kind = binding.buffer && binding.buffer.type === \"storage\" ? \"uav\" : \"srv\";\r\n    const slot = SlotFor(description, kind, binding);\r\n    const resource = slot?.type === 1 ? slot.buffer : null;\r\n    const buffer = resource && typeof resource.GetDeviceBuffer === \"function\" ? resource.GetDeviceBuffer() : null;\r\n\r\n    return { buffer: buffer ?? renderContext.GetNullBuffer(binding.buffer?.minBindingSize ?? 16, \"STORAGE\") };\r\n  }\r\n\r\n  /** The resolved entries by `\"group:binding\"`. @returns {Map<string, object>} */\r\n  GetEntries()\r\n  {\r\n    return this.m_entries;\r\n  }\r\n\r\n  /** The `Tr2ResourceSetDescriptionAL` it was created from, or null. */\r\n  GetDescription()\r\n  {\r\n    return this.m_description;\r\n  }\r\n\r\n  /** The shader program whose bindings were resolved, or null. */\r\n  GetProgram()\r\n  {\r\n    return this.m_program;\r\n  }\r\n\r\n  /** Whether the set has been created and carries an identity. */\r\n  IsValid()\r\n  {\r\n    return this.m_id !== 0;\r\n  }\r\n\r\n  /** Drops the resolved entries, leaving the set invalid. */\r\n  Destroy()\r\n  {\r\n    this.m_entries = new Map();\r\n    this.m_description = null;\r\n    this.m_program = null;\r\n    this.m_id = 0;\r\n  }\r\n\r\n  /** Where the set lives, which is managed memory rather than the device. */\r\n  GetMemoryClass()\r\n  {\r\n    return Tr2ALMemoryType.AL_MEMORY_MANAGED;\r\n  }\r\n\r\n  /**\r\n   * Fills in a device-resource description.\r\n   *\r\n   * @param {object} description The description to fill.\r\n   * @returns {object} The description, filled.\r\n   */\r\n  Describe(description)\r\n  {\r\n    if (!description) return description;\r\n\r\n    description.memoryClass = this.GetMemoryClass();\r\n\r\n    return description;\r\n  }\r\n\r\n  /**\r\n   * Nothing here carries a label - the bind groups the context builds do.\r\n   *\r\n   * @returns {number} `S_OK`.\r\n   */\r\n  SetName(_name)\r\n  {\r\n    return ALResult.S_OK;\r\n  }\r\n}\r\n\r\n// DECLARED AS A CALL, NOT A DECORATOR, for the reason recorded in\r\n// Tr2BitmapDimensions.js: the layer is imported straight from source by its\r\n// tests and raw Node cannot parse decorator syntax.\r\n//\r\n// The donor is NAMED rather than left to be derived from this class's name.\r\n// Carbon calls every backend's class the same thing and carries the backend in\r\n// the FILE name, because only one backend compiles at a time; we ship them\r\n// together, so the backend moves onto the class name. That divergence is the\r\n// author's to declare, never a checker's to guess.\r\nCjsSchema.define(CjsWebgpuResourceSetAL, { className: \"CjsWebgpuResourceSetAL\", carbon: \"Tr2ResourceSetAL\" });\r\n"],"names":["STAGE_OF_VISIBILITY","Object","freeze","ShaderType","VERTEX_SHADER","PIXEL_SHADER","COMPUTE_SHADER","nextResourceSetId","SlotFor","description","kind","binding","bit","stage","visibility","map","m_registerMap","slots","srvs","uavs","samplers","records","m_srv","m_uav","m_samplers","slot","registerIndex","type","CjsWebgpuResourceSetAL","_initProto","_applyDecs","impl","adapted","reason","e","m_id","m_description","m_program","m_entries","Map","Create","program","renderContext","Destroy","IsValid","ALResult","E_INVALIDARG","GetBindings","equals","GetRegisterMap","some","record","E_FAIL","entries","buffer","set","group","_Resolve","S_OK","sampler","state","GetSampler","GetDummySampler","texture","dimension","viewDimension","view","GetDeviceTextureView","colorSpace","GetDummyTexture","resource","GetDeviceBuffer","GetNullBuffer","minBindingSize","GetEntries","GetDescription","GetProgram","GetMemoryClass","Tr2ALMemoryType","AL_MEMORY_MANAGED","Describe","memoryClass","SetName","_name","CjsSchema","define","className","carbon"],"mappings":"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"}

package/docs/core/README.md

@@ -1,47 +1,47 @@
-# Package documentation
-
-Status: Evolving
+# Package documentation
+
+Status: Evolving
 Scope: `@carbonenginejs/runtime/core`
-Audience: Runtime integrators and maintainers
-Summary: Documentation home for the GPU-free composition root, service registry, and request-policy boundary.
-
-## Purpose
-
+Audience: Runtime integrators and maintainers
+Summary: Documentation home for the GPU-free composition root, service registry, and request-policy boundary.
+
+## Purpose
+
 `@carbonenginejs/runtime/core` provides `CjsLibrary`, a small composition
 boundary for caller-owned services and capabilities. Its dedicated service
 slots require the canonical `CjsResMan`, `EveSOF`, and `CjsAudioMan` identities.
-
-```js
+
+```js
 import CjsLibrary from "@carbonenginejs/runtime/core";
-
-const library = new CjsLibrary({
-    resourceManager,
-    spaceObjectFactory,
-    capabilities: { webgpu: true }
-});
-```
-
+
+const library = new CjsLibrary({
+    resourceManager,
+    spaceObjectFactory,
+    capabilities: { webgpu: true }
+});
+```
+
 The package also exposes browser platform and WebGPU adapter snapshots. Those
 probes report capabilities but do not create a `GPUDevice`.
-`CjsFrameDriver` executes one explicitly requested backend-neutral frame against
-exact Trinity context/jobs and an engine-supplied `CjsFrameLifecycle`.
-
-## Where it fits
-
-- Runtime packages supply resource, SOF, input, audio, and device services.
-- `CjsLibrary` composes those services and selects resource request behavior.
-- Concrete services retain ownership of loading, decoding, queues, backend
-  objects, and shutdown behavior.
-
+Carbon's frame body is not ported here; see
+[trinity architecture](../trinity/architecture.md) under *Frame contract*.
+
+## Where it fits
+
+- Runtime packages supply resource, SOF, input, audio, and device services.
+- `CjsLibrary` composes those services and selects resource request behavior.
+- Concrete services retain ownership of loading, decoding, queues, backend
+  objects, and shutdown behavior.
+
 The package does not parse formats, manage a resource cache, decode media,
 hydrate a scene graph, own presentation, or run a hidden frame loop.
-
-## Start here
-
-- [Architecture](architecture.md)
-- [Roadmap](roadmap.md)
-- [Composing a library](guides/composing-a-library.md)
-- [API reference](reference/api.md)
-- [Resource request policy](reference/resource-request-policy.md)
-- [Browser platform capabilities](reference/platform.md)
-- [Class catalog](reference/classes/README.md)
+
+## Start here
+
+- [Architecture](architecture.md)
+- [Roadmap](roadmap.md)
+- [Composing a library](guides/composing-a-library.md)
+- [API reference](reference/api.md)
+- [Resource request policy](reference/resource-request-policy.md)
+- [Browser platform capabilities](reference/platform.md)
+- [Class catalog](reference/classes/README.md)

package/docs/core/architecture.md

@@ -39,11 +39,12 @@ Caller-owned services are not disposed; there is no general shutdown protocol.
 
 ## Frame boundary
 
-`CjsFrameDriver` owns the backend-neutral order of one explicitly requested
-frame. Composition requires exact `Tr2RenderContext`, `Tr2RenderJobs`, and
-`CjsFrameLifecycle` instances once, then the hot path calls them directly.
-The lifecycle supplies pacing, GPU synchronization, viewport, profiling, and
-quad-index reservation; its base methods throw until an engine overrides them.
+Carbon's backend-neutral frame body is not ported. It belongs on the backend
+device (`TriDevice.cpp:1151-1187`, `:805-843`), and its order is recorded in
+[trinity architecture](../trinity/architecture.md) under *Frame contract*. Core
+previously hoisted it into composition as `CjsFrameDriver`, driven by an
+injected `CjsFrameLifecycle`; both were deleted on 2026-09-17, having no caller
+and no implementer.
 
 The driver passes its exact bracketed context to `Tr2RenderJobs.Run`. Cleanup
 attempts every opened closer even when jobs or an earlier closer fail.

package/docs/core/reference/api.md

@@ -9,7 +9,6 @@ Summary: Documents the composition library, service keys, lifecycle, registries,
 
 ```js
 import CjsLibrary, {
-    CjsFrameDriver,
     CjsLibrary as NamedLibrary,
     CjsServiceKey
 } from "@carbonenginejs/runtime/core";
@@ -18,15 +17,6 @@ import CjsLibrary, {
 The browser platform classes are also exported from the root, with
 `@carbonenginejs/runtime/core/platform` provided as the focused entry point.
 
-## `CjsFrameDriver`
-
-`new CjsFrameDriver({ renderContext, renderJobs, frameLifecycle })` requires
-exact `Tr2RenderContext`, `Tr2RenderJobs`, and `CjsFrameLifecycle` instances.
-`Tick(elapsed, animationTimeScale)` advances the frame clock with Carbon's
-hourly rebase. `Render(realTime, simTime)` executes one requested frame, passes
-the bound context to the jobs, and closes every opened bracket. It does not
-present or own an outer loop.
-
 ## `CjsServiceKey`
 
 The frozen map provides string keys `RESOURCE_MANAGER`,

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

@@ -1,86 +1,76 @@
-# Class catalog
-
-Status: Evolving
+# Class catalog
+
+Status: Evolving
 Scope: `@carbonenginejs/runtime/core` maintained classes
-Audience: Users, maintainers, and automated readers
-Summary: Provides one-sentence purpose descriptors for every maintained class in the core runtime package.
-
-<!-- class:CjsFrameDriver -->
-## `CjsFrameDriver`
+Audience: Users, maintainers, and automated readers
+Summary: Provides one-sentence purpose descriptors for every maintained class in the core runtime package.
+
+<!-- class:CjsLibrary -->
+## `CjsLibrary`
 
-Runs Carbon's backend-neutral frame body against exact runtime identities.
+GPU-free CarbonEngineJS composition root and runtime service registry.
 
 - Export: `@carbonenginejs/runtime/core`
-- Source: `src/core/CjsFrameDriver.js`
+- Source: `src/core/CjsLibrary.js`
 - Visibility: Public
 - Kind: CarbonEngineJS
 
-<!-- class:CjsLibrary -->
-## `CjsLibrary`
-
-GPU-free CarbonEngineJS composition root and runtime service registry.
-
-- Export: `@carbonenginejs/runtime/core`
-- Source: `src/core/CjsLibrary.js`
-- Visibility: Public
-- Kind: CarbonEngineJS
-
-<!-- class:CjsWebGLProbe -->
-## `CjsWebGLProbe`
-
-Privacy-safe WebGL2 capability snapshot, reported under its own keys rather than as the absence of WebGPU.
-
+<!-- class:CjsWebGLProbe -->
+## `CjsWebGLProbe`
+
+Privacy-safe WebGL2 capability snapshot, reported under its own keys rather than as the absence of WebGPU.
+
 - Export: `@carbonenginejs/runtime/core/platform`
 - Source: `src/core/platform/CjsWebGLProbe.js`
-- Visibility: Public
-- Kind: CarbonEngineJS
-
-<!-- class:Tr2DisplayMode -->
-## `Tr2DisplayMode`
-
-Current browser Screen snapshot; browsers do not expose a native mode list.
-
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:Tr2DisplayMode -->
+## `Tr2DisplayMode`
+
+Current browser Screen snapshot; browsers do not expose a native mode list.
+
 - Export: `@carbonenginejs/runtime/core/platform`
 - Source: `src/core/platform/Tr2DisplayMode.js`
-- Visibility: Public
-- Kind: Adapted Carbon concept
-
-<!-- class:Tr2PlatformInfo -->
-## `Tr2PlatformInfo`
-
-Browser feature report replacing Carbon's compile-time platform macros.
-
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2PlatformInfo -->
+## `Tr2PlatformInfo`
+
+Browser feature report replacing Carbon's compile-time platform macros.
+
 - Export: `@carbonenginejs/runtime/core/platform`
 - Source: `src/core/platform/Tr2PlatformInfo.js`
-- Visibility: Public
-- Kind: Adapted Carbon concept
-
-<!-- class:Tr2VideoAdapter -->
-## `Tr2VideoAdapter`
-
-Privacy-respecting browser snapshot of Carbon's `Tr2VideoAdapter`.
-
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2VideoAdapter -->
+## `Tr2VideoAdapter`
+
+Privacy-respecting browser snapshot of Carbon's `Tr2VideoAdapter`.
+
 - Export: `@carbonenginejs/runtime/core/platform`
 - Source: `src/core/platform/Tr2VideoAdapter.js`
-- Visibility: Public
-- Kind: Adapted Carbon concept
-
-<!-- class:Tr2VideoAdapters -->
-## `Tr2VideoAdapters`
-
-Browser adapter/display facade for Carbon's `Tr2VideoAdapters` surface.
-
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2VideoAdapters -->
+## `Tr2VideoAdapters`
+
+Browser adapter/display facade for Carbon's `Tr2VideoAdapters` surface.
+
 - Export: `@carbonenginejs/runtime/core/platform`
 - Source: `src/core/platform/Tr2VideoAdapters.js`
-- Visibility: Public
-- Kind: Adapted Carbon concept
-
-<!-- class:Tr2VideoDriver -->
-## `Tr2VideoDriver`
-
-Browser-visible subset of Carbon's `Tr2VideoDriver`.
-
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2VideoDriver -->
+## `Tr2VideoDriver`
+
+Browser-visible subset of Carbon's `Tr2VideoDriver`.
+
 - Export: `@carbonenginejs/runtime/core/platform`
 - Source: `src/core/platform/Tr2VideoDriver.js`
-- Visibility: Public
-- Kind: Adapted Carbon concept
+- Visibility: Public
+- Kind: Adapted Carbon concept

package/docs/global/architecture.md

@@ -86,9 +86,7 @@ calls required methods directly; repeated structural probes are not a contract.
 `CjsBackendCandidate` exposes only backend proof and is not a device or RHI
 superclass. `CjsConstantPayload` exposes terminal bytes and their dirty
 lifecycle; layout, packing, transpose, allocation, upload, and binding stay in
-their owning layers. `CjsFrameLifecycle` exposes only the required engine-facing
-steps within one requested frame; presentation and the outer tick stay with the
-engine.
+their owning layers.
 
 ## Ownership elsewhere
 

package/docs/global/blue-enums.md

@@ -0,0 +1,115 @@
+# Blue enum registry
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime/blue` enum registration and schema lookup
+Audience: Runtime authors and UI integrators
+Summary: Register domain-owned enums once and obtain Carbon-compatible value and bitmask names.
+
+## Registration
+
+```js
+import { blue } from "@carbonenginejs/runtime/blue";
+
+export const Mode = blue.enums.RegisterEnum("example.Widget.Mode", {
+    NONE: 0,
+    FIRST: 1,
+    SECOND: 2,
+    BOTH: 3
+});
+```
+
+Register a name-to-integer object from its owning module. Registration freezes
+and returns that same object. Numeric values may repeat as aliases; names must
+be nonnumeric strings. Values must be signed or unsigned 32-bit integers.
+Qualified names distinguish domains and nested owners while preserving native
+type and member names. Importing Blue does not import or register every domain.
+
+The optional third argument accepts `members` (ordered `{ name, value,
+description }` records), `source`, `family`, `line`, and native `exposure` flags.
+Listed members must match the object; any unlisted members follow in object
+declaration order. The registry copies metadata and makes it read-only.
+Exposure flags are provenance: they do not create Python-style module exports.
+The public `EnumRegistrationType` object retains Carbon's
+`ENUM_REG_VALUES_ON_MODULE` and `ENUM_REG_ENUM_OBJECT_ON_MODULE` names and values.
+
+Native chooser labels need not match enum identifiers. Supply `chooser` as an
+ordered array of `{ name, value, description }` to preserve the exact native
+selection. Its values must occur in the enum, but its names can differ and it
+may omit sentinels. This array is authoritative for name/bitmask lookup; entries
+omitted from it are not appended. An explicit empty chooser has no matches.
+Without a chooser, lookup uses the ordered enum members instead.
+`exposedName` and `chooserSource` retain native exposure identity and provenance;
+they do not register extra aliases.
+
+Registering the same object, name and metadata again is harmless. Conflicting
+names, a second canonical name for one object, and invalid input throw
+`TypeError` before publication. Conflicts do not freeze the rejected object.
+This deliberately replaces the old CjsSchema last-registration-wins behavior.
+
+## Lookup
+
+| Method | Result |
+|---|---|
+| `GetEnum(name)` | The registered named-value object. |
+| `GetEnumInfo(name)` | Name, type object, ordered members and provenance. |
+| `GetEnumName(values)` | Canonical registered name, or `null`. |
+| `HasEnum(name)` | Whether the name is registered. |
+| `GetNameFromValue(name, value)` | All exact chooser aliases joined with `" | "` (enum members when no chooser is supplied). |
+| `GetNameFromBitmask(name, mask)` | First exact entry, otherwise all contained nonzero entries joined with `" | "`. |
+
+Bitmask lookup preserves Carbon's behavior: aliases and contained composites
+are included, and unknown remaining bits do not invalidate known matches.
+Zero matches only an explicit zero entry. A missing enum throws `ReferenceError`;
+a value or mask with no matching entry throws `RangeError`. Integer arguments
+outside the supported range, fractions, strings and BigInt throw `TypeError`.
+Signed and unsigned spellings of the same 32-bit pattern compare equally.
+
+## Schema integration
+
+`@type.enum("example.Widget.Mode")` records the qualified name and resolves it
+when field/schema metadata is requested. Register before resolution. A missing
+registration throws, but can be registered and resolved later; failed resolution
+is not cached. Names containing a dot select registry resolution exclusively.
+
+Existing short-name annotations continue to resolve declaring/inherited class
+statics. Those statics can alias the registered object. `CjsSchema.defineEnum`,
+`getEnum` and `getEnumName` use the same registry; no second enum table exists.
+All 16 SOF-owned enum types in the field inventory now use this path across
+28 fields. The four additional SOF fields using shared ReflectionMode/Tr2Lod
+constants now use `trinity.EntityComponents.ReflectionMode` and `trinity.Tr2Lod`.
+Nine Trinity reflection/LOD fields also use these shared registrations.
+Eight particle fields use `trinity.Tr2ParticleElementDeclarationName.Type`
+and `trinity.Tr2ParticleElementData.BufferType`. DeclarationName owns Type;
+its declaration and generator consumers reference the same enum object.
+Consumers explicitly import the shared registration module; constants remain
+dependency-free and importing Blue alone does not register these domain types. Independently declared banner Usage, pattern
+ProjectionType and DisplayQualityModifier types have separate registry identities,
+including where Carbon reuses a chooser between types. Schema metadata keeps
+the native identifier map in `enum.members` and exposes the separate ordered
+UI choices in `enum.chooser`. For example, the blink constant remains
+`TYPE_BLINK`, while its native chooser name is `"Blink"`; logo's `TYPE_MAX`
+remains a constant but is not offered by the chooser.
+The model values transport also accepts member names and exports enum names
+for qualified fields, preserving its existing first-alias serialization policy.
+That serialization policy is distinct from Blue's diagnostic alias joining.
+
+## Carbon attribution
+
+`CjsBlueEnumRegistry` combines the enum portion of `BlueRegistration`, the
+storage and registration work of `EnumRegistration<T>`/`EnumTypeRegistration`,
+and `PyBlueEnumObject` (exposed as `blue.BlueEnum`). Ordinary JS module execution
+replaces static registrar constructors. Plain read-only objects and registry
+methods replace Python extension objects; C++ templates and Python allocation
+machinery are not recreated.
+
+This deliberately combines two native views: `GetEnum` returns C++ identifiers
+for JS code, while name lookup and chooser metadata preserve Blue's exposed
+names. It does not claim that Python BlueEnum's attributes use C++ spellings.
+
+Source disposition records retain each eliminated helper's native identity.
+Other BlueRegistration responsibilities and VarChooser uses are not replaced.
+The core imports no schema or service modules. CjsSchema installs its adapted
+method attribution after schema initialization, avoiding a bootstrap cycle.
+
+No resource manager or composition initialization is required for registration.
+Enum definitions stay with their domain; this API does not relocate constants.