@carbonenginejs/runtime-utils 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cppctamber / CarbonEngineJS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,23 @@
+carbonenginejs/runtime-utils
+============================
+
+A browser-safe foundation package for CarbonEngineJS projects. It contains
+neutral utilities; shared constant vocabularies; Carbon type, schema, model,
+document, and lifecycle primitives; and standalone math containers originally
+extracted from ccpwgl's `src/global/math` library.
+
+CarbonEngine and Fenris Creations (CCP Games) are named here for provenance,
+interoperability, and target-ecosystem context. This package contains no
+CarbonEngine or Fenris Creations (CCP Games) source files, tooling, proprietary
+documentation, shader source, or assets.
+
+Packed tangent-frame behavior is based on observed Fenris Creations
+(CCP Games) EVE/Carbon shader behavior and generated test vectors, not copied
+shader source.
+
+This package is not affiliated with or endorsed by CCP Games.
+
+CarbonEngineJS-facing code is copyright cppctamber / CarbonEngineJS
+contributors.
+
+Repository license: MIT. See LICENSE and THIRD-PARTY-NOTICES.md.

package/README.md

@@ -0,0 +1,56 @@
+# @carbonenginejs/runtime-utils
+
+Browser-safe foundations shared across CarbonEngineJS packages.
+
+The package owns:
+
+- neutral arrays, bytes, compression, JSON, lookup, paths, text, predicates,
+  and validation;
+- scalar, vector, quaternion, matrix, geometry, mesh, tangent, curve, and
+  noise math;
+- shared media, graphics, render-context, audio, shader, D3D, and WebGPU
+  constants;
+- Carbon type descriptors, schema metadata, models, lifecycle state,
+  documents, hydration, and dehydration.
+
+Browser clients remain in `@carbonenginejs/tools-browser`; Node automation
+remains in `@carbonenginejs/tools-core`.
+
+## Install
+
+```sh
+npm install @carbonenginejs/runtime-utils
+```
+
+## Quick start
+
+Prefer direct subpaths so unrelated families are not initialized:
+
+```js
+import { normalizePath } from "@carbonenginejs/runtime-utils/path";
+import { cross, normalize } from "@carbonenginejs/runtime-utils/vec3";
+import { PixelFormat } from "@carbonenginejs/runtime-utils/graphics";
+import { CjsSchema } from "@carbonenginejs/runtime-utils/schema";
+```
+
+Former core-math and runtime-const subpaths remain top-level, so migration is
+a package-name replacement. Carbon type and model primitives are available
+from `/types`, `/schema`, `/model`, `/document`, `/hydration`, and
+`/lifecycle`.
+
+The root export is intentionally limited to common neutral utilities, math,
+and non-conflicting constants. Import Carbon type/model/document families from
+their direct subpaths.
+
+## Documentation
+
+- [Package documentation](docs/README.md)
+- [Architecture and admission rules](docs/architecture.md)
+- [API reference](docs/reference/api.md)
+- [Foundation consolidation](docs/concepts/foundation-consolidation.md)
+- [Constant vocabulary notes](docs/const-kb.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE), [NOTICE](NOTICE), and
+[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,38 @@
+# Third-Party Notices
+
+## gl-matrix
+
+This package depends on `gl-matrix` and extends its vector, quaternion, and
+matrix containers with CarbonEngineJS helpers.
+
+- Project: <https://github.com/toji/gl-matrix>
+- License: MIT
+
+## ccpwgl math extraction
+
+Most container modules in `src` were extracted from ccpwgl's
+`src/global/math` library and converted to standalone ESM with package-local
+imports. The code remains MIT-licensed under the CarbonEngineJS/ccpwgl project
+license.
+
+## Mapbox earcut helper
+
+`src/geometry/helpers/earcut.js` is an embedded copy of an Earcut-style
+triangulation helper from the ccpwgl math tree.
+
+- Copyright: 2016, Mapbox
+- License: ISC
+- Local license copy: `src/geometry/helpers/LICENSE`
+
+## Three.js-derived geometry notes
+
+Some geometry helpers in the extracted ccpwgl math tree are marked as converted
+from Three.js-style algorithms. These are retained as source comments and should
+be reviewed before expanding the public geometry surface.
+
+## Fenris Creations / CCP Games tangent behavior
+
+`src/tangent.js` implements CarbonEngineJS/GR2 packed tangent-frame behavior
+derived from observed EVE/Carbon shader behavior and generated test vectors.
+No Fenris Creations (CCP Games) shader source, tools, or assets are included.
+

package/docs/README.md

@@ -0,0 +1,81 @@
+# Runtime utilities documentation
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-utils`
+Audience: Runtime authors, integrators, and maintainers
+Summary: Explains the consolidated shared runtime foundation and its public families.
+
+## Purpose
+
+`@carbonenginejs/runtime-utils` is the bottom shared layer of the
+CarbonEngineJS runtime dependency graph. It owns browser-safe primitives that
+are useful across runtime libraries and do not depend on another
+CarbonEngineJS package.
+
+The package is deliberately strict about what enters this layer so it can
+remain stable and low-changing after the Carbon-to-JavaScript conversion.
+
+## Use this package when
+
+Use `runtime-utils` when code:
+
+- is a general runtime primitive used by more than one package;
+- has stable behavior that can be described without domain policy;
+- is safe in browsers and does not import Node built-ins;
+- can remain independent of every other CarbonEngineJS package.
+
+Do not use it merely as a convenient home for code without an owner.
+Browser-facing demos, clients, inspectors, and usable application helpers
+belong in `@carbonenginejs/tools-browser`.
+
+## Where it fits
+
+The package has no organization dependencies. It uses `gl-matrix` for the math
+families; its subpaths remain side-effect-free and independently importable.
+
+```text
+runtime libraries       tools-browser
+        \                    /
+         \                  /
+          v                v
+             runtime-utils
+                  |
+                  v
+      Web-standard platform APIs
+```
+
+Runtime packages and `tools-browser` consume this foundation directly. Math,
+constant, type, schema, model, document, hydration, and lifecycle ownership is
+consolidated here.
+
+## Start here
+
+Use the root export when a library consumes several utility families:
+
+```js
+import {
+    encodeJson,
+    isPlainObject,
+    normalizePath
+} from "@carbonenginejs/runtime-utils";
+```
+
+Use a public subpath when a consumer needs one focused family:
+
+```js
+import { asUint8Array } from "@carbonenginejs/runtime-utils/bytes";
+```
+
+## Documentation map
+
+- [Architecture and admission rules](architecture.md) defines dependency
+  direction, ownership, and the test for adding code.
+- [Current API reference](reference/api.md) lists the implemented subpaths and
+  exports.
+- [Class reference](reference/classes/README.md) catalogs maintained Carbon
+  foundation classes.
+- [Foundation consolidation](concepts/foundation-consolidation.md) records the
+  implemented ownership move and remaining release/retirement work.
+
+The Carbon type/model/document guide is retained under
+[core-types/README.md](core-types/README.md) with updated package paths.

package/docs/architecture.md

@@ -0,0 +1,101 @@
+# Runtime utilities architecture
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-utils`
+Audience: Runtime authors and maintainers
+Summary: Defines the package dependency boundary, ownership rules, and stability expectations.
+
+## Purpose
+
+`runtime-utils` supplies the lowest reusable layer for CarbonEngineJS runtime
+libraries. Consumers can use it without introducing a dependency on another
+organization package or pulling browser and Node tool behavior into the
+runtime graph.
+
+## Dependency contract
+
+Organization-dependency-free means:
+
+- published source must not import another `@carbonenginejs/*` package;
+- public subpaths must remain safe to import independently;
+- published source must not import Node built-ins or reference Node-only
+  globals;
+- module evaluation must not perform environment-specific work.
+
+It does not mean that all third-party dependencies are prohibited. A focused,
+browser-safe dependency such as `gl-matrix` is acceptable when it supplies a
+foundation primitive, preserves independent subpaths, and does not introduce
+organization dependency cycles.
+
+## Dependency direction
+
+```text
+      runtime-* packages       tools-browser
+              \                    /
+               \                  /
+                v                v
+                   runtime-utils
+                         |
+                         v
+       third-party or Web-standard primitives
+```
+
+Dependencies point toward `runtime-utils`; `runtime-utils` never reaches back
+into a runtime, engine, format, browser tool, or Node tool package.
+
+## Admission rules
+
+Code belongs in `runtime-utils` only when all of these are true:
+
+1. More than one runtime-facing package needs the same primitive or contract.
+2. The behavior is useful without application, rendering, resource, or domain
+   policy.
+3. The implementation can satisfy the dependency contract above.
+4. Its public semantics are stable enough for broad reuse.
+5. Owning it here reduces duplicated foundation behavior rather than merely
+   shortening an import.
+
+Once the Carbon-to-JavaScript conversion and foundation consolidation finish,
+new responsibilities should be uncommon. Additions require a demonstrated
+cross-package need and a clear subpath owner.
+
+## Current ownership
+
+The implemented package currently owns:
+
+- neutral array, byte, text, JSON, lookup, and path mechanics;
+- shared `isSomething` predicates and small validation assertions;
+- browser-standard gzip decompression helpers;
+- scalar, vector, quaternion, matrix, geometry, mesh, tangent, noise, and curve
+  math;
+- shared media, graphics, render-context, audio, shader, D3D, and WebGPU
+  constants; and
+- Carbon type descriptors, schema metadata, models, lifecycle state,
+  documents, hydration, and dehydration.
+
+The [API reference](reference/api.md) is the exact current inventory.
+
+## Ownership elsewhere
+
+- Browser-facing demos, clients, remote readers, inspectors, integration
+  helpers, and usable reference implementations belong in
+  `@carbonenginejs/tools-browser`.
+- Node filesystems, caches, credentials, servers, command-line interfaces, and
+  build orchestration belong in `@carbonenginejs/tools-core`.
+- Runtime graph objects and domain readers belong in their owning
+  `runtime-*` package.
+- Backend objects and realization policy belong in `engine-*` packages.
+- Generated schemas, enums, and domain libraries remain generated artifacts
+  owned by their producer and consuming domain.
+
+## Consolidated foundation boundary
+
+The former math, constant, and Carbon type-system foundations now live under
+coherent `runtime-utils` subpaths. Former math and constant family suffixes
+remain available at the top level for mechanical migration, while `/math/*`
+and `/const/*` aliases group the same implementations.
+
+The root intentionally excludes type/model/document barrels so importing a
+neutral utility does not initialize registry and model families. See
+[Foundation consolidation](concepts/foundation-consolidation.md) for the
+layout and migration status.

package/docs/concepts/foundation-consolidation.md

@@ -0,0 +1,86 @@
+# Runtime foundation consolidation
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-utils` foundation boundary
+Audience: Runtime authors, integrators, and maintainers
+Summary: Records the consolidated math, constant, and type-system ownership and migration contract.
+
+## Purpose
+
+The approved organization direction is to make `runtime-utils` the single
+stable, browser-safe foundation commonly consumed by CarbonEngineJS runtime
+libraries.
+
+The surviving repository now contains the former utility, math, constant, and
+Carbon type-system implementations. Their inherited test suites run together,
+and every advertised package subpath is independently importable.
+
+## Current ownership
+
+`@carbonenginejs/runtime-utils` is the sole current source owner for neutral
+mechanics, math, shared constants, Carbon types, schema metadata, registries,
+models, documents, lifecycle, hydration, and dehydration.
+
+## Implemented layout
+
+The families move intact enough to preserve useful imports:
+
+| Moved family | `runtime-utils` family |
+| --- | --- |
+| Math | Existing top-level suffixes such as `./vec3`, plus `./math` and matching `./math/*` aliases |
+| Constants | Existing family suffixes such as `./graphics`, plus `./const` and matching `./const/*` aliases |
+| Carbon types/models | `./types`, `./schema`, `./model`, `./document`, `./hydration`, and `./lifecycle` |
+
+The root export may expose common mechanics and family namespaces. It must not
+introduce ambiguous duplicate names or require eager evaluation of every math,
+constant, schema, model, and document module.
+
+The package depends on `gl-matrix`. That is compatible with the boundary
+because `runtime-utils` prohibits organization dependencies, not focused
+browser-safe third-party foundations.
+
+## Shared predicates
+
+There is one curated `runtime-utils/is` surface:
+
+- predicates return literal booleans;
+- generally useful structural checks belong here;
+- vector and matrix checks join only with explicit math semantics;
+- domain checks remain with their domain package;
+- browser-specific checks remain in `tools-browser`;
+- established core predicate behavior wins wherever old names overlap.
+
+The goal is a useful shared predicate library, not a reduced compatibility
+snapshot.
+
+## Migration status
+
+Completed locally:
+
+1. current contracts and baselines were inventoried;
+2. unique utility APIs and the math, constant, and type/model families were
+   assembled in the surviving Git history;
+3. inherited contract suites and independent-subpath imports pass;
+4. generator output was updated before consumer source;
+5. active authored consumers and generated npm output were migrated.
+
+Remaining release work is to publish the consolidated package, refresh
+registry-resolved locks, verify clean installs, and retire the old package
+names after the active-reference audit reaches zero.
+
+No compatibility package is required by default. One should exist only for a
+verified external consumer that cannot migrate during the coordinated release.
+
+## Stability target
+
+After consolidation, `runtime-utils` should change infrequently. New
+responsibilities need a demonstrated cross-runtime use case, browser-safe
+semantics, no CarbonEngineJS dependencies, and a coherent public subpath.
+
+The result is a runtime foundation, not a general utility dumping ground.
+
+## Related documentation
+
+- [Package documentation](../README.md)
+- [Architecture and admission rules](../architecture.md)
+- [Current API reference](../reference/api.md)

package/docs/const-kb.md

@@ -0,0 +1,92 @@
+# 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:
+
+- `format-*` packages when emitting GPU-free semantic payloads.
+- `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.
+
+`runtime-utils` does 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.
+- WebGPU/WebGL resource creation.
+
+## Dependency Rule
+
+`runtime-utils` should stay dependency-light and pure JavaScript.
+
+Preferred direction:
+
+```text
+format-*          may emit matching strings, optionally 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
+```
+
+Format packages are allowed to remain standalone by 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 format package.
+
+Examples:
+
+- DDS magic numbers, header offsets, pixel format flags, caps bits, FOURCC
+  values, and DX10 header parsing belong to `format-dds`.
+- PNG chunk names and filter ids belong to `format-png`.
+- WAV RIFF chunk ids belong to `format-wav`.
+
+`runtime-utils` may still expose general constants that those formats reference,
+such as canonical `PixelFormat` strings or generic `DxgiFormat` numeric enum
+values. The parser-specific interpretation remains in the format package.
+
+## 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

@@ -0,0 +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.
+
+## TODO
+
+- [ ] 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.