@carbonenginejs/runtime-utils 0.1.0 → 0.1.2

package/README.md

@@ -5,7 +5,7 @@ Browser-safe foundations shared across CarbonEngineJS packages.
 The package owns:
 
 - neutral arrays, bytes, compression, JSON, lookup, paths, text, predicates,
-  and validation;
+  validation, and structured operational errors;
 - scalar, vector, quaternion, matrix, geometry, mesh, tangent, curve, and
   noise math;
 - shared media, graphics, render-context, audio, shader, D3D, and WebGPU
@@ -13,8 +13,9 @@ The package owns:
 - 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`.
+Browser-client ownership is planned for `@carbonenginejs/tools-browser`; that
+package is not currently released. Node automation belongs in
+`@carbonenginejs/tools-core`.
 
 ## Install
 
@@ -28,15 +29,28 @@ Prefer direct subpaths so unrelated families are not initialized:
 
 ```js
 import { normalizePath } from "@carbonenginejs/runtime-utils/path";
+import { CjsError } from "@carbonenginejs/runtime-utils/errors";
 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`.
+Former package imports map as follows:
+
+- `@carbonenginejs/core-math` becomes
+  `@carbonenginejs/runtime-utils/math`;
+- `@carbonenginejs/core-math/<subpath>` becomes
+  `@carbonenginejs/runtime-utils/<subpath>`;
+- `@carbonenginejs/runtime-const` becomes
+  `@carbonenginejs/runtime-utils/const`;
+- `@carbonenginejs/runtime-const/<subpath>` becomes
+  `@carbonenginejs/runtime-utils/<subpath>`;
+- `@carbonenginejs/core-types/<subpath>` becomes the matching
+  `@carbonenginejs/runtime-utils/<subpath>`; replace former root imports with
+  the direct type/model/document subpaths they use.
+
+Carbon type and model primitives use `/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

package/THIRD-PARTY-NOTICES.md

@@ -15,6 +15,10 @@ Most container modules in `src` were extracted from ccpwgl's
 imports. The code remains MIT-licensed under the CarbonEngineJS/ccpwgl project
 license.
 
+- Project: <https://github.com/cppctamber/ccpwgl2>
+- Copyright: 2020 ccpgames rawrafox cppctamber
+- License: MIT; terms reproduced below
+
 ## Mapbox earcut helper
 
 `src/geometry/helpers/earcut.js` is an embedded copy of an Earcut-style
@@ -24,11 +28,14 @@ triangulation helper from the ccpwgl math tree.
 - License: ISC
 - Local license copy: `src/geometry/helpers/LICENSE`
 
-## Three.js-derived geometry notes
+## Three.js-derived geometry helpers
+
+Math and geometry helpers in the extracted ccpwgl tree retain source comments
+attributing conversions to Three.js authors.
 
-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.
+- Project: <https://github.com/mrdoob/three.js>
+- Copyright: 2010-2026 three.js authors
+- License: MIT; terms reproduced below
 
 ## Fenris Creations / CCP Games tangent behavior
 
@@ -36,3 +43,22 @@ be reviewed before expanding the public geometry surface.
 derived from observed EVE/Carbon shader behavior and generated test vectors.
 No Fenris Creations (CCP Games) shader source, tools, or assets are included.
 
+## MIT terms for ccpwgl and Three.js material
+
+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 notices 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/docs/README.md

@@ -25,16 +25,19 @@ Use `runtime-utils` when code:
 - 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`.
+Browser-facing demos, clients, inspectors, and usable application helpers have
+the planned owner `@carbonenginejs/tools-browser`; that package is not
+currently released.
 
 ## 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.
+The `/errors` family supplies coded operational failures without defining
+logging, transport, HTTP, or retry policy.
 
 ```text
-runtime libraries       tools-browser
+runtime libraries       tools-browser (planned; unreleased)
         \                    /
          \                  /
           v                v
@@ -44,9 +47,9 @@ runtime libraries       tools-browser
       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.
+Runtime packages consume this foundation directly. The planned, unreleased
+`tools-browser` package will do the same. Math, constant, type, schema, model,
+document, hydration, and lifecycle ownership is consolidated here.
 
 ## Start here
 
@@ -75,7 +78,7 @@ import { asUint8Array } from "@carbonenginejs/runtime-utils/bytes";
 - [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.
+  implemented ownership move and consumer migration map.
 
 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

@@ -30,7 +30,7 @@ organization dependency cycles.
 ## Dependency direction
 
 ```text
-      runtime-* packages       tools-browser
+      runtime-* packages       tools-browser (planned; unreleased)
               \                    /
                \                  /
                 v                v
@@ -55,15 +55,16 @@ Code belongs in `runtime-utils` only when all of these are true:
 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.
+With foundation consolidation complete, 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;
+- structured operational errors without logging or transport policy;
 - shared `isSomething` predicates and small validation assertions;
 - browser-standard gzip decompression helpers;
 - scalar, vector, quaternion, matrix, geometry, mesh, tangent, noise, and curve
@@ -78,8 +79,8 @@ 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`.
+  helpers, and usable reference implementations have the planned owner
+  `@carbonenginejs/tools-browser`, which is not currently released.
 - 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

package/docs/concepts/foundation-consolidation.md

@@ -7,9 +7,8 @@ Summary: Records the consolidated math, constant, and type-system ownership and
 
 ## Purpose
 
-The approved organization direction is to make `runtime-utils` the single
-stable, browser-safe foundation commonly consumed by CarbonEngineJS runtime
-libraries.
+`runtime-utils` is 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,
@@ -23,7 +22,7 @@ models, documents, lifecycle, hydration, and dehydration.
 
 ## Implemented layout
 
-The families move intact enough to preserve useful imports:
+The moved families map directly enough to preserve useful imports:
 
 | Moved family | `runtime-utils` family |
 | --- | --- |
@@ -47,29 +46,29 @@ There is one curated `runtime-utils/is` surface:
 - 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`;
+- browser-specific checks remain outside this package; their planned,
+  unreleased owner is `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
+## Migration map
 
-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.
+| Former import | Current import |
+| --- | --- |
+| `@carbonenginejs/core-math` | `@carbonenginejs/runtime-utils/math` |
+| `@carbonenginejs/core-math/<subpath>` | `@carbonenginejs/runtime-utils/<subpath>` |
+| `@carbonenginejs/runtime-const` | `@carbonenginejs/runtime-utils/const` |
+| `@carbonenginejs/runtime-const/<subpath>` | `@carbonenginejs/runtime-utils/<subpath>` |
+| `@carbonenginejs/core-types/<subpath>` | The matching `@carbonenginejs/runtime-utils/<subpath>` |
+| `@carbonenginejs/core-types` | The direct runtime-utils type/model/document subpaths used by the consumer |
+
+The former package names are predecessor identities, not compatibility
+packages; maintained source lives here. The one deliberate API correction is
+scalar Hermite interpolation:
+use `cubicHermite` or `cubicHermiteDerivative` with argument order
+`(startValue, startTangent, endValue, endTangent, amount)`.
 
 ## Stability target
 

package/docs/const-kb.md

@@ -11,7 +11,9 @@ Summary: Defines ownership and dependency rules for shared constant vocabularies
 
 This package provides stable constants that can be shared by:
 
-- `format-*` packages when emitting GPU-free semantic payloads.
+- `runtime-resource/formats/*` readers when emitting GPU-free semantic
+  payloads.
+- maintained standalone shader-format packages.
 - `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
@@ -26,13 +28,14 @@ This package provides stable constants that can be shared by:
 - 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:
+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.
+- class hydration or runtime object population, which are separate
+  runtime-utils families.
 - WebGPU/WebGL resource creation.
 
 ## Dependency Rule
@@ -42,14 +45,15 @@ This package provides stable constants that can be shared by:
 Preferred direction:
 
 ```text
-format-*          may emit matching strings, optionally import runtime-utils
+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
 ```
 
-Format packages are allowed to remain standalone by emitting plain strings that
-match this package's constants.
+Maintained shader format packages may remain standalone while emitting plain
+strings that match this package's constants.
 
 ## Initial Domains
 
@@ -62,18 +66,21 @@ match this package's constants.
 
 ## Format-Specific Constants
 
-Container-specific constants live with their format package.
+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 `format-dds`.
-- PNG chunk names and filter ids belong to `format-png`.
-- WAV RIFF chunk ids belong to `format-wav`.
+  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. The parser-specific interpretation remains in the format package.
+values. Parser-specific interpretation remains in the maintained reader.
 
 ## Payload Example
 

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

@@ -12,7 +12,7 @@ No missing decorator primitive is currently confirmed. `@type`, `@io`,
 `CjsModel.SetValues` adds declared `@io.flag`/`@io.rebuild` consequences at
 write time.
 
-## TODO
+## Open work
 
 - [ ] Decide how a concrete Blue class declares an inherited Carbon method
   without adding a forwarding wrapper. `CjsSchema.decorateMethod` can already

package/docs/reference/api.md

@@ -35,12 +35,13 @@ import { encodeUtf8 } from "@carbonenginejs/runtime-utils/text";
 | [`./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` |
+| [`./errors`](../../src/errors/index.js) | Represents coded operational failures and Web-compatible cancellation without logging or transport policy. | `CjsError`, `CjsCancellationError`, `CJS_OPERATION_CANCELLED` |
 | [`./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` |
+| [`./path`](../../src/path.js) | Normalizes generic and case-insensitive resource paths without filesystem access or dot-segment resolution. | `normalizePath`, `normalizeResourcePath`, `getResourceExtension`, `normalizeResourceExtension` |
 | [`./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` |
 
@@ -56,6 +57,47 @@ available. `render-context` stays out of the root because its numeric
 Carbon foundation families use `./types`, `./schema`, `./model`,
 `./document`, `./hydration`, and `./lifecycle`.
 
+## Operational error contract
+
+`CjsError` represents an operation that failed after valid input reached a
+runtime boundary. Package owners define their own stable uppercase `CJS_*`
+codes; this family does not maintain a central code registry.
+
+```js
+import { CjsError } from "@carbonenginejs/runtime-utils/errors";
+
+throw new CjsError(
+    "CJS_EXAMPLE_PROVIDER_FAILED",
+    "The example provider could not resolve the requested item.",
+    {
+        cause,
+        details: {
+            itemId,
+            provider
+        }
+    }
+);
+```
+
+The optional `cause` retains its original identity. Optional `details` must be
+a plain record containing JSON-safe values; the constructor clones and deeply
+freezes it. It does not redact details, so callers must exclude credentials,
+private payloads, and other sensitive values.
+
+Use native `TypeError`, `RangeError`, and `SyntaxError` for programmer-contract
+violations. An expected `Find*` miss may return `null`; use a coded operational
+error when acquisition, provider, state, or resolution work actually fails.
+Native `AggregateError` remains the aggregate mechanism.
+
+`CjsCancellationError` has stable code `CJS_OPERATION_CANCELLED`, uses the
+Web-compatible name `AbortError`, and accepts the same cause/details options.
+`CjsCancellationError.is(error)` also recognizes platform abort errors.
+`CjsError.hasCode(error, code)` works with both `CjsError` and legacy errors
+that expose a stable `code`.
+
+These classes do not log, serialize, choose HTTP status, prescribe retries, or
+translate errors for user interfaces.
+
 ## Environment contract
 
 The source uses standard ECMAScript and browser APIs. Compression requires

package/docs/reference/classes/README.md

@@ -5,6 +5,26 @@ Scope: `@carbonenginejs/runtime-utils` class exports
 Audience: Runtime authors and integrators
 Summary: Catalogs maintained named classes in the consolidated runtime foundation.
 
+<!-- class:CjsError -->
+## `CjsError`
+
+Represents one structured operational failure with a stable CarbonEngineJS code.
+
+- Export: `@carbonenginejs/runtime-utils/errors`
+- Source: `src/errors/CjsError.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:CjsCancellationError -->
+## `CjsCancellationError`
+
+Represents one cancelled operation using Web-compatible abort identity.
+
+- Export: `@carbonenginejs/runtime-utils/errors`
+- Source: `src/errors/CjsError.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
 <!-- class:CjsCarbonDocument -->
 ## `CjsCarbonDocument`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbonenginejs/runtime-utils",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Browser-safe shared utilities, math, constants, Carbon types, schemas, documents, and runtime model primitives.",
   "type": "module",
   "main": "src/index.js",
@@ -10,6 +10,7 @@
     "./bytes": "./src/bytes.js",
     "./compression": "./src/compression.js",
     "./const": "./src/constants/index.js",
+    "./const/trinity": "./src/constants/trinity.js",
     "./const/media": "./src/media/index.js",
     "./const/graphics": "./src/graphics/index.js",
     "./const/render-context": "./src/renderContext/index.js",
@@ -25,6 +26,7 @@
     "./d3d": "./src/d3d/index.js",
     "./webgpu": "./src/webgpu/index.js",
     "./document": "./src/document/index.js",
+    "./errors": "./src/errors/index.js",
     "./hydration": "./src/document/hydrationAdapter.js",
     "./lifecycle": "./src/lifecycle/index.js",
     "./schema": "./src/schema/index.js",
@@ -33,6 +35,7 @@
     "./is": "./src/is.js",
     "./json": "./src/json.js",
     "./lookup": "./src/lookup.js",
+    "./object": "./src/object.js",
     "./math": "./src/math/index.js",
     "./math/scalar": "./src/math/scalar.js",
     "./math/num": "./src/num.js",
@@ -99,6 +102,7 @@
     "constants",
     "schema",
     "types",
+    "errors",
     "geometry",
     "tangent",
     "browser"
@@ -128,5 +132,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "overrides": {
+    "brace-expansion": "^5.0.8"
   }
 }

package/src/constants/index.js

@@ -4,3 +4,4 @@ export * from "../audio/index.js";
 export * from "../shader/index.js";
 export * from "../d3d/index.js";
 export * from "../webgpu/index.js";
+export * from "./trinity.js";

package/src/constants/trinity.js

@@ -0,0 +1,13 @@
+// Source: trinity/trinity/Resources/Tr2LodResource.h
+
+/**
+ * Shared Trinity level-of-detail values.
+ */
+export const Tr2Lod = Object.freeze({
+    TR2_LOD_UNSPECIFIED: -1,
+    TR2_LOD_LOW: 0,
+    TR2_LOD_MEDIUM: 1,
+    TR2_LOD_HIGH: 2,
+    TR2_LOD_ULTRA: 3,
+    TR2_LOD_COUNT: 4
+});