@carbonenginejs/runtime-utils 0.1.0

package/docs/core-types/README.md

@@ -0,0 +1,203 @@
+# @carbonenginejs/runtime-utils
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-utils` Carbon type and model families
+Audience: Runtime authors and integrators
+Summary: Explains Carbon type descriptors, schemas, models, lifecycle state, documents, and hydration.
+
+Shared CarbonEngineJS type, schema, document, hydration, and runtime model
+helpers.
+
+This package is the common contract for packages that read, write, or generate
+CarbonEngineJS data. Format packages can stop at plain JSON or a neutral
+`CjsCarbonDocument`; runtime packages can opt into registered classes and
+`CjsModel` when they want live objects.
+
+## Install
+
+```sh
+npm install @carbonenginejs/runtime-utils
+```
+
+## What It Owns
+
+- `document`: neutral `CjsCarbonDocument`, class/struct registries, hydration,
+  and dehydration.
+- `hydration`: adapter seam for construction, value application, and finalize
+  behavior.
+- `schema`: decorators, class/field/method metadata, the direct
+  name-to-constructor map, enum registration, Carbon-method provenance, and
+  component metadata helpers.
+- `types`: Carbon type descriptors, defaults, coercion, cloning, and export
+  helpers.
+- `model`: `CjsModel`, `CjsEventEmitter`, model dirty state, traversal helpers,
+  and source-record utilities.
+
+Generated enums and generated class catalogs should live in schema or generated
+runtime packages, not in this foundational package.
+
+## Hydration Contract
+
+`runtime-utils` does not impose a runtime lifecycle on callers. The hydrator only
+guarantees ordering:
+
+1. `construct`
+2. `applyValues`
+3. `finalize`
+
+The default behavior is intentionally minimal: construction through
+`CjsSchema.GetConstructor(name)`, `Object.assign` for values, and no finalize
+step. Callers opt into stricter population rules by supplying an adapter.
+
+Use `createLifecycleAdapter()` when your runtime classes follow a
+`SetValues`-style contract. `Initialize` is optional; disable it explicitly
+when a project only wants `SetValues`.
+
+## Usage
+
+### Hydrate a neutral document into runtime classes
+
+```js
+import {
+  CjsCarbonDocument,
+  CjsClassRegistry,
+  CjsDocumentHydrator
+} from "@carbonenginejs/runtime-utils/document";
+import { createLifecycleAdapter } from "@carbonenginejs/runtime-utils/hydration";
+import { CjsModel } from "@carbonenginejs/runtime-utils/model";
+import { CjsSchema } from "@carbonenginejs/runtime-utils/schema";
+
+class DemoNode extends CjsModel
+{
+  position = [0, 0, 0];
+}
+
+CjsSchema.define(DemoNode, {
+  className: "DemoNode",
+  alias: "LegacyDemoNode",
+  fields: [{
+    name: "position",
+    type: { kind: "vec3" },
+    io: {
+      read: true,
+      write: true,
+      persist: true,
+      notify: true
+    }
+  }]
+});
+
+const document = CjsCarbonDocument.create({
+  format: "example",
+  roots: [{ ref: { $ref: 1 } }],
+  nodes: [{
+    id: 1,
+    kind: "DemoNode",
+    fields: { position: [1, 2, 3] }
+  }]
+});
+
+const registry = CjsClassRegistry.fromMaps({
+  constructors: { DemoNode }
+});
+
+const adapter = createLifecycleAdapter({ initialize: false });
+const { root } = CjsDocumentHydrator.hydrate(document, { registry, adapter });
+```
+
+`CjsSchema` stores constructors in one direct name-to-constructor map.
+`CjsSchema.define` registers the explicit `className` and each alias as keys;
+manual code can use `CjsSchema.SetConstructor(name, Constructor)`. A supplied
+scoped registry replaces the default constructor lookup and must implement
+`GetConstructor(name)`.
+
+### Model references, value structs, and raw inline values
+
+Use `type.model("ClassName")` for reference-shaped fields that hydrate through
+the registered `CjsModel` constructor map. Legacy `type.objectRef` remains
+supported while runtime packages migrate.
+
+Use `type.struct("ClassName")` for a registered model with value semantics. If
+the owner constructor installs a struct instance, `SetValues` populates that
+instance in place instead of storing the incoming model by reference. This
+keeps constructor-owned identity and mutable math buffers stable.
+
+Opaque native payloads must not trigger model construction. Use
+`type.rawStruct("NativeType")`; it records the canonical `rawStruct`
+descriptor and keeps plain object values non-constructing.
+
+### Work with schema-backed runtime models directly
+
+```js
+const node = DemoNode.from({ position: [1, 2, 3] });
+
+node.OnEvent("modified", (_target, payload) => {
+  console.log([...payload.properties]);
+});
+
+node.SetValues({ position: [4, 5, 6] });
+node.Merge([{ position: [7, 8, 9] }, { position: [10, 11, 12] }]);
+
+const copy = new DemoNode();
+CjsModel.copy(copy, node, { markDirty: false });
+const plain = node.GetValues();
+```
+
+`CjsModel` is evented, tracks dirty/update state explicitly, and uses schema
+metadata as its field contract. Every model class requires an explicit, stable
+`CjsSchema` `className`; runtime type identity never falls back to
+`Constructor.name`, which is not stable under minification.
+
+`Merge`/`merge` accept an ordered array of raw value bags or model instances,
+deep-merge them, and apply the final bag through one `CjsModel.set` update cycle.
+They return the same changed-set, boolean, or `false` result as `SetValues`.
+`Copy`/`copy` instead require an instantiated
+`CjsModel` source and forward the supplied `SetValues` options.
+
+### Hide inherited schema fields
+
+Carbon Blue surfaces are defined per class, so a real JavaScript subclass may
+persist fewer fields than its parent. Use the class-level
+`schema.hideInherited()` decorator to remove named inherited fields from only
+that class's schema surface:
+
+```js
+import { schema, type } from "@carbonenginejs/runtime-utils/schema";
+
+@type.define({ className: "ExampleBucket", family: "example" })
+@schema.hideInherited(["distribution", "descriptor", "offset"])
+export class ExampleBucket extends ExamplePlacement
+{
+}
+```
+
+Hidden fields are omitted from schema introspection, `GetValues`, document
+dehydration, and every export option. `SetValues` and document hydration
+silently ignore them, matching `SetValues`' existing unknown-field behavior.
+The JavaScript properties, accessors, inheritance, and `instanceof` behavior
+are unchanged.
+
+Hides pass to descendants and may be extended by another
+`schema.hideInherited()` decorator. There is deliberately no unhide operation.
+Naming a field that the parent schema does not expose throws during class
+registration.
+
+Each model owns one non-enumerable `__state` object. Model-owned
+`__state.dirty` tracks broad, property, and notification invalidation;
+`__state.rebuild` is an independent `Set` of deferred work; and
+`__state.updating` plus `__state.suppressEvents` coordinate update processing.
+The event emitter adds `__state.events` only while listeners exist. A lifecycle
+manager may install `__state.lifecycle` with `initializeLifecycleState()`;
+without it, the object remains ordinarily alive and unmanaged. Dirty
+consumption and clearing do not modify rebuild or lifecycle state.
+
+## Subpaths
+
+```js
+import { CjsCarbonDocument, CjsDocumentHydrator } from "@carbonenginejs/runtime-utils/document";
+import { createLifecycleAdapter } from "@carbonenginejs/runtime-utils/hydration";
+import { CjsLifecycleState } from "@carbonenginejs/runtime-utils/lifecycle";
+import { CjsSchema, type, io, carbon, components } from "@carbonenginejs/runtime-utils/schema";
+import { CjsModel, CjsEventEmitter, CjsModelState } from "@carbonenginejs/runtime-utils/model";
+import { CARBON_TYPE, normalizeCarbonValue } from "@carbonenginejs/runtime-utils/types";
+```

package/docs/reference/api.md

@@ -0,0 +1,70 @@
+# Runtime utilities API
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-utils` version 0.1
+Audience: Library users and runtime authors
+Summary: Lists the consolidated public API families and utility primitives.
+
+## Import contract
+
+The package root re-exports neutral utilities, math namespaces, and
+non-conflicting constants. Type, schema, model, document, hydration, and
+lifecycle APIs remain direct-subpath only.
+
+```js
+import {
+    asUint8Array,
+    encodeJson,
+    isArrayLike,
+    normalizePath
+} from "@carbonenginejs/runtime-utils";
+```
+
+Every documented subpath can also be imported independently. Subpath imports
+make a narrow dependency explicit:
+
+```js
+import { encodeUtf8 } from "@carbonenginejs/runtime-utils/text";
+```
+
+## Current exports
+
+| Subpath | Purpose | Exports |
+| --- | --- | --- |
+| `.` | Neutral utilities, math namespaces/scalars, and non-conflicting constants. | Common root surface. |
+| [`./arrays`](../../src/arrays.js) | Normalizes nullable values and mutates writable array-like targets. | `toArray`, `copyArrayLike`, `fillArrayLike` |
+| [`./bytes`](../../src/bytes.js) | Creates byte views, owned copies, exact buffers, and prefix checks. | `asUint8Array`, `copyBytes`, `toArrayBuffer`, `hasBytePrefix` |
+| [`./compression`](../../src/compression.js) | Detects and decompresses gzip through Web-standard streams. | `isGzip`, `decompressBytes`, `decompressGzip`, `decompressGzipIfNeeded` |
+| [`./is`](../../src/is.js) | Provides shared literal-boolean value predicates. | `isTypedArray`, `isArrayLike`, `isFunction`, `isNullish`, `isObject`, `isObjectLike`, `isPlainObject`, `isPromiseLike` |
+| [`./json`](../../src/json.js) | Encodes and decodes JSON with explicit UTF-8 behavior. | `encodeJson`, `decodeJson` |
+| [`./lookup`](../../src/lookup.js) | Supplies stable string ordering and duplicate-safe map construction. | `compareCodeUnits`, `sortStrings`, `indexBy` |
+| [`./math`](../../src/math/index.js) | Aggregates scalar and container math. | Scalar exports plus math namespaces. |
+| [`./math/scalar`](../../src/math/scalar.js) | Supplies scalar limits, interpolation, angle conversion, wrapping, and smooth steps. | `defaultEpsilon`, `tau`, `clamp`, `saturate`, `lerp`, `approximatelyEqual`, `degreesToRadians`, `radiansToDegrees`, `wrapDegrees`, `wrapRadians`, `cubicHermite`, `cubicHermiteDerivative`, `smoothStep`, `smootherStep` |
+| [`./path`](../../src/path.js) | Normalizes slash direction without filesystem access or dot-segment resolution. | `normalizePath` |
+| [`./text`](../../src/text.js) | Encodes and decodes UTF-8 through Web-standard codecs. | `encodeUtf8`, `decodeUtf8` |
+| [`./validation`](../../src/validation.js) | Provides small labelled assertions for shared input contracts. | `isPlainObject`, `assertPlainObject`, `assertNonEmptyString`, `assertSupportedVersion` |
+
+Math containers retain top-level subpaths such as `./num`, `./vec2`, `./vec3`,
+`./vec4`, `./quat`, `./mat3`, `./mat4`, `./geometry`, `./mesh`, and
+`./tangent`. Matching `./math/*` aliases are also exported.
+
+Constant families use `./media`, `./graphics`, `./render-context`, `./audio`,
+`./shader`, `./d3d`, and `./webgpu`; matching `./const/*` aliases are
+available. `render-context` stays out of the root because its numeric
+`PixelFormat` intentionally differs from graphics' string vocabulary.
+
+Carbon foundation families use `./types`, `./schema`, `./model`,
+`./document`, `./hydration`, and `./lifecycle`.
+
+## Environment contract
+
+The source uses standard ECMAScript and browser APIs. Compression requires
+`DecompressionStream` and `Response`; text helpers require `TextEncoder` and
+`TextDecoder`. When an API is unavailable, the relevant helper reports an
+explicit unsupported-environment error rather than importing a Node fallback.
+
+## Detailed family references
+
+See the package README, the retained
+[Carbon type/model guide](../core-types/README.md), and the source-backed
+subpath tests for the complete per-family surface.

package/docs/reference/classes/README.md

@@ -0,0 +1,115 @@
+# Runtime-utils class reference
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-utils` class exports
+Audience: Runtime authors and integrators
+Summary: Catalogs maintained named classes in the consolidated runtime foundation.
+
+<!-- class:CjsCarbonDocument -->
+## `CjsCarbonDocument`
+
+Represents one neutral Carbon document graph for hydration and dehydration.
+
+- Export: `@carbonenginejs/runtime-utils/document`
+- Source: `src/document/CjsCarbonDocument.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:CjsClassRegistry -->
+## `CjsClassRegistry`
+
+Maps serialized Carbon class names to explicit runtime constructors.
+
+- Export: `@carbonenginejs/runtime-utils/document`
+- Source: `src/document/CjsClassRegistry.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:CjsDocumentDehydrator -->
+## `CjsDocumentDehydrator`
+
+Converts runtime object graphs into neutral Carbon documents.
+
+- Export: `@carbonenginejs/runtime-utils/document`
+- Source: `src/document/CjsDocumentDehydrator.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:CjsDocumentHydrator -->
+## `CjsDocumentHydrator`
+
+Constructs runtime object graphs from neutral Carbon documents.
+
+- Export: `@carbonenginejs/runtime-utils/document`
+- Source: `src/document/CjsDocumentHydrator.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:CjsStructRegistry -->
+## `CjsStructRegistry`
+
+Maps serialized Carbon struct names to explicit constructors and layouts.
+
+- Export: `@carbonenginejs/runtime-utils/document`
+- Source: `src/document/CjsStructRegistry.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:CjsLifecycleState -->
+## `CjsLifecycleState`
+
+Inspectable lifecycle state shared by participating runtime objects.
+
+- Export: `@carbonenginejs/runtime-utils/lifecycle`
+- Source: `src/lifecycle/CjsLifecycleState.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:CjsEventEmitter -->
+## `CjsEventEmitter`
+
+Minimal event emitter with lowercase exact-name dispatch.
+
+- Export: `@carbonenginejs/runtime-utils/model`
+- Source: `src/model/CjsEventEmitter.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:CjsModel -->
+## `CjsModel`
+
+Shared base for schema-backed CarbonEngineJS runtime classes.
+
+- Export: `@carbonenginejs/runtime-utils/model`
+- Source: `src/model/CjsModel.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:CjsPendingReference -->
+## `CjsPendingReference`
+
+Represents one unresolved model reference during a single import operation.
+
+- Source: `src/model/CjsModel.js`
+- Visibility: Internal
+- Kind: CarbonEngineJS
+
+<!-- class:CjsModelState -->
+## `CjsModelState`
+
+Per-model runtime state.
+
+- Export: `@carbonenginejs/runtime-utils/model`
+- Source: `src/model/CjsModelState.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:CjsSchema -->
+## `CjsSchema`
+
+Reusable schema/decorator metadata surface.
+
+- Export: `@carbonenginejs/runtime-utils/schema`
+- Source: `src/schema/CjsSchema.js`
+- Visibility: Public
+- Kind: CarbonEngineJS

package/package.json

@@ -0,0 +1,132 @@
+{
+  "name": "@carbonenginejs/runtime-utils",
+  "version": "0.1.0",
+  "description": "Browser-safe shared utilities, math, constants, Carbon types, schemas, documents, and runtime model primitives.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./arrays": "./src/arrays.js",
+    "./bytes": "./src/bytes.js",
+    "./compression": "./src/compression.js",
+    "./const": "./src/constants/index.js",
+    "./const/media": "./src/media/index.js",
+    "./const/graphics": "./src/graphics/index.js",
+    "./const/render-context": "./src/renderContext/index.js",
+    "./const/audio": "./src/audio/index.js",
+    "./const/shader": "./src/shader/index.js",
+    "./const/d3d": "./src/d3d/index.js",
+    "./const/webgpu": "./src/webgpu/index.js",
+    "./media": "./src/media/index.js",
+    "./graphics": "./src/graphics/index.js",
+    "./render-context": "./src/renderContext/index.js",
+    "./audio": "./src/audio/index.js",
+    "./shader": "./src/shader/index.js",
+    "./d3d": "./src/d3d/index.js",
+    "./webgpu": "./src/webgpu/index.js",
+    "./document": "./src/document/index.js",
+    "./hydration": "./src/document/hydrationAdapter.js",
+    "./lifecycle": "./src/lifecycle/index.js",
+    "./schema": "./src/schema/index.js",
+    "./types": "./src/types/index.js",
+    "./model": "./src/model/index.js",
+    "./is": "./src/is.js",
+    "./json": "./src/json.js",
+    "./lookup": "./src/lookup.js",
+    "./math": "./src/math/index.js",
+    "./math/scalar": "./src/math/scalar.js",
+    "./math/num": "./src/num.js",
+    "./math/vec2": "./src/vec2.js",
+    "./math/vec3": "./src/vec3.js",
+    "./math/vec4": "./src/vec4.js",
+    "./math/quat": "./src/quat.js",
+    "./math/mat3": "./src/mat3.js",
+    "./math/mat4": "./src/mat4.js",
+    "./math/box3": "./src/box3.js",
+    "./math/tri3": "./src/tri3.js",
+    "./math/lne3": "./src/lne3.js",
+    "./math/pln": "./src/pln.js",
+    "./math/ray3": "./src/ray3.js",
+    "./math/sph3": "./src/sph3.js",
+    "./math/pool": "./src/pool.js",
+    "./math/utils": "./src/utils.js",
+    "./math/noise": "./src/noise.js",
+    "./math/curve": "./src/curve.js",
+    "./math/vertex": "./src/vertex.js",
+    "./math/mesh": "./src/mesh.js",
+    "./math/tangent": "./src/tangent.js",
+    "./math/geometry": "./src/geometry/index.js",
+    "./num": "./src/num.js",
+    "./vec2": "./src/vec2.js",
+    "./vec3": "./src/vec3.js",
+    "./vec4": "./src/vec4.js",
+    "./quat": "./src/quat.js",
+    "./mat3": "./src/mat3.js",
+    "./mat4": "./src/mat4.js",
+    "./box3": "./src/box3.js",
+    "./tri3": "./src/tri3.js",
+    "./lne3": "./src/lne3.js",
+    "./pln": "./src/pln.js",
+    "./ray3": "./src/ray3.js",
+    "./sph3": "./src/sph3.js",
+    "./pool": "./src/pool.js",
+    "./utils": "./src/utils.js",
+    "./noise": "./src/noise.js",
+    "./curve": "./src/curve.js",
+    "./vertex": "./src/vertex.js",
+    "./mesh": "./src/mesh.js",
+    "./tangent": "./src/tangent.js",
+    "./geometry": "./src/geometry/index.js",
+    "./path": "./src/path.js",
+    "./text": "./src/text.js",
+    "./validation": "./src/validation.js"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint --ext .js,.mjs src test",
+    "lint:fix": "eslint --fix --ext .js,.mjs src test",
+    "check": "npm run lint && npm test"
+  },
+  "keywords": [
+    "carbonenginejs",
+    "runtime",
+    "utilities",
+    "gl-matrix",
+    "constants",
+    "schema",
+    "types",
+    "geometry",
+    "tangent",
+    "browser"
+  ],
+  "files": [
+    "src",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "gl-matrix": "^3.4.4"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carbonenginejs/runtime-utils.git"
+  },
+  "homepage": "https://github.com/carbonenginejs/runtime-utils#readme",
+  "bugs": {
+    "url": "https://github.com/carbonenginejs/runtime-utils/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/arrays.js

@@ -0,0 +1,5 @@
+export {
+    toArray,
+    copyArrayLike,
+    fillArrayLike
+} from "./utils.js";

package/src/audio/audioFormats.js

@@ -0,0 +1,34 @@
+/**
+ * Canonical audio sample format tokens.
+ */
+export const AudioSampleFormat = Object.freeze({
+    UNKNOWN: "unknown",
+    U8: "u8",
+    S16: "s16",
+    S24: "s24",
+    S32: "s32",
+    F32: "f32",
+    F64: "f64"
+});
+
+/**
+ * Canonical audio channel layout tokens.
+ */
+export const AudioChannelLayout = Object.freeze({
+    UNKNOWN: "unknown",
+    MONO: "mono",
+    STEREO: "stereo",
+    SURROUND_5_1: "5.1",
+    SURROUND_7_1: "7.1"
+});
+
+/**
+ * Normalize an audio sample format token.
+ *
+ * @param {string} format Audio sample format token.
+ * @returns {string} Canonical lowercase token.
+ */
+export function normalizeAudioSampleFormat(format)
+{
+    return format ? String(format).trim().toLowerCase() : AudioSampleFormat.UNKNOWN;
+}

package/src/audio/index.js

@@ -0,0 +1 @@
+export * from "./audioFormats.js";