@carbonenginejs/runtime-utils 0.1.1 → 0.1.3

package/docs/const-kb.md

@@ -1,99 +1,97 @@
-# Runtime Const Knowledge Base
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-utils` constant families
-Audience: Runtime authors and maintainers
-Summary: Defines ownership and dependency rules for shared constant vocabularies.
-
-`runtime-utils` owns shared vocabulary and numeric constants for CarbonEngineJS.
-
-## Purpose
-
+# Runtime Const Knowledge Base
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-utils` constant families
+Audience: Runtime authors and maintainers
+Summary: Defines ownership and dependency rules for shared constant vocabularies.
+
+`runtime-utils` owns shared vocabulary and numeric constants for CarbonEngineJS.
+
+## Purpose
+
 This package provides stable constants that can be shared by:
 
 - `runtime-resource/formats/*` readers when emitting GPU-free semantic
-  payloads.
-- maintained standalone shader-format packages.
+  payloads, including the DXBC, HLSL, WebGL, and WebGPU subpaths.
 - `runtime-resource` when interpreting payloads and resource intent.
 - `engine-*` packages when mapping payloads to backend APIs.
-- tools and tests that need canonical media, graphics, audio, shader, D3D, or
-  backend names.
-
-## Boundaries
-
-`runtime-utils` owns:
-
-- canonical string tokens, such as pixel formats and color spaces.
-- small helpers for normalization and classification.
-- numeric mirrors of external enums where useful, such as DXGI/D3D values.
-- mapping tables between shared constants and backend constants.
-
-The constant families do not own:
-
-- resource lifecycle, cache, source reads, or loader dispatch.
-- format parsing or byte decoding.
-- format-container internals such as DDS header offsets, FOURCC parsing,
-  PNG chunk handling, WAV chunk layouts, or MP4 box parsing.
-- class hydration or runtime object population, which are separate
-  runtime-utils families.
-- WebGPU/WebGL resource creation.
-
-## Dependency Rule
-
-`runtime-utils` should stay dependency-light and pure JavaScript.
-
-Preferred direction:
-
+- tools and tests that need canonical media, graphics, audio, shader, D3D, or
+  backend names.
+
+## Boundaries
+
+`runtime-utils` owns:
+
+- canonical string tokens, such as pixel formats and color spaces.
+- small helpers for normalization and classification.
+- numeric mirrors of external enums where useful, such as DXGI/D3D values.
+- mapping tables between shared constants and backend constants.
+
+The constant families do not own:
+
+- resource lifecycle, cache, source reads, or loader dispatch.
+- format parsing or byte decoding.
+- format-container internals such as DDS header offsets, FOURCC parsing,
+  PNG chunk handling, WAV chunk layouts, or MP4 box parsing.
+- class hydration or runtime object population, which are separate
+  runtime-utils families.
+- WebGPU/WebGL resource creation.
+
+## Dependency Rule
+
+`runtime-utils` should stay dependency-light and pure JavaScript.
+
+Preferred direction:
+
 ```text
 runtime-resource/formats/*  may emit matching strings, imports runtime-utils
-shader format-*             may emit matching strings, import runtime-utils
 runtime-resource  may import/re-export runtime-utils
 engine-*          imports runtime-utils for backend mapping
 runtime-utils     imports no runtime-resource or engine packages
 ```
 
-Maintained shader format packages may remain standalone while emitting plain
-strings that match this package's constants.
-
-## Initial Domains
-
-- media and payload types
-- graphics pixel formats, color spaces, texture dimensions
-- audio sample formats and channel layouts
-- shader stages and shader models
-- D3D/DXGI enum mirrors
-- WebGPU mapping helpers
-
-## Format-Specific Constants
-
-Container-specific constants live with their maintained reader.
-
-Examples:
-
-- DDS magic numbers, header offsets, pixel format flags, caps bits, FOURCC
-  values, and DX10 header parsing belong to
-  `@carbonenginejs/runtime-resource/formats/dds`.
-- PNG chunk names and filter ids belong to
-  `@carbonenginejs/runtime-resource/formats/png`.
-- WAV RIFF chunk ids belong to
-  `@carbonenginejs/runtime-resource/formats/wav`.
-
-`runtime-utils` may still expose general constants that those formats reference,
-such as canonical `PixelFormat` strings or generic `DxgiFormat` numeric enum
-values. Parser-specific interpretation remains in the maintained reader.
-
-## Payload Example
-
-```js
-{
-    payloadType: "texture",
-    sourceFormat: "dds",
-    pixelFormat: "bc7-rgba-unorm",
-    colorSpace: "srgb",
-    dimension: "2d",
-    isCompressed: true
-}
-```
-
-The payload is still GPU-free. Engine packages decide whether and how to create
-backend resources from it.
+Shader formats are maintained as runtime-resource subpaths. Retired standalone
+format package names are provenance labels, not current dependency owners.
+
+## Initial Domains
+
+- media and payload types
+- graphics pixel formats, color spaces, texture dimensions
+- audio sample formats and channel layouts
+- shader stages and shader models
+- D3D/DXGI enum mirrors
+- WebGPU mapping helpers
+
+## Format-Specific Constants
+
+Container-specific constants live with their maintained reader.
+
+Examples:
+
+- DDS magic numbers, header offsets, pixel format flags, caps bits, FOURCC
+  values, and DX10 header parsing belong to
+  `@carbonenginejs/runtime-resource/formats/dds`.
+- PNG chunk names and filter ids belong to
+  `@carbonenginejs/runtime-resource/formats/png`.
+- WAV RIFF chunk ids belong to
+  `@carbonenginejs/runtime-resource/formats/wav`.
+
+`runtime-utils` may still expose general constants that those formats reference,
+such as canonical `PixelFormat` strings or generic `DxgiFormat` numeric enum
+values. Parser-specific interpretation remains in the maintained reader.
+
+## Payload Example
+
+```js
+{
+    payloadType: "texture",
+    sourceFormat: "dds",
+    pixelFormat: "bc7-rgba-unorm",
+    colorSpace: "srgb",
+    dimension: "2d",
+    isCompressed: true
+}
+```
+
+The payload is still GPU-free. Engine packages decide whether and how to create
+backend resources from it.

package/docs/core-types/DECORATOR-TODOS.md

@@ -1,25 +1,25 @@
-# Runtime-utils decorator TODOs
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-utils/schema`
-Audience: Schema authors and maintainers
-Summary: Records reviewed decorator gaps that remain outside the current schema contract.
-
-## Confirmed status
-
-No missing decorator primitive is currently confirmed. `@type`, `@io`,
-`@schema`, `@carbon`, and `@impl` provide the required metadata surface, and
-`CjsModel.SetValues` adds declared `@io.flag`/`@io.rebuild` consequences at
-write time.
-
-## Open work
-
-- [ ] Decide how a concrete Blue class declares an inherited Carbon method
-  without adding a forwarding wrapper. `CjsSchema.decorateMethod` can already
-  register the inherited implementation on an exact constructor; add a new
-  declarative form only if the package-wide checker requires one.
-- [ ] Keep tests proving that `@io.flag` and `@io.rebuild` tokens are added by
-  changed-field writes and are never cleared by generic settle logic.
-- [ ] Do not add proposed semantic aliases such as `type.position` or
-  `type.worldTransform` as part of missing-decorator cleanup; those remain a
-  separate API decision.
+# Runtime-utils decorator TODOs
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-utils/schema`
+Audience: Schema authors and maintainers
+Summary: Records reviewed decorator gaps that remain outside the current schema contract.
+
+## Confirmed status
+
+No missing decorator primitive is currently confirmed. `@type`, `@io`,
+`@schema`, `@carbon`, and `@impl` provide the required metadata surface, and
+`CjsModel.SetValues` adds declared `@io.flag`/`@io.rebuild` consequences at
+write time.
+
+## Open work
+
+- [ ] Decide how a concrete Blue class declares an inherited Carbon method
+  without adding a forwarding wrapper. `CjsSchema.decorateMethod` can already
+  register the inherited implementation on an exact constructor; add a new
+  declarative form only if the package-wide checker requires one.
+- [ ] Keep tests proving that `@io.flag` and `@io.rebuild` tokens are added by
+  changed-field writes and are never cleared by generic settle logic.
+- [ ] Do not add proposed semantic aliases such as `type.position` or
+  `type.worldTransform` as part of missing-decorator cleanup; those remain a
+  separate API decision.