@carbonenginejs/runtime-resource 0.12.1 → 0.13.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 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.
+MIT License
+
+Copyright (c) 2026 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

@@ -1,32 +1,32 @@
-carbonenginejs/runtime-resource
-================================
-
-Copyright (c) 2026 CarbonEngineJS contributors.
-
-This package owns CarbonEngineJS resource lifecycle, format selection,
-canonical GPU-free shader/reflection models, and the non-shader format
-implementations listed under `format-notices/`.
-
-CarbonEngine source material, format names, class names, and schema semantics
-remain copyright their original CarbonEngine authors. Fenris Creations
-(CCP Games) source material, tools, assets, shader behavior, and EVE-related
-data remain copyright their original holders. These names are used for
-interoperability and provenance context. This project is not affiliated with
-or endorsed by CCP Games.
-
-The copied format implementations retain their original MIT license and NOTICE
-files under `format-notices/<format>/`. Those notices include third-party
-dependency and behavioral-reference attribution, including meshoptimizer,
-yaml, and black-reader-js.
-
-The bundled Black definition JSON is a generated CarbonEngineJS schema artifact
-copied from `format-carbon` revision
-`d2a3c67cf3d46e8ba78ca19e66558d868178ec24`. Its exact digest and retention
-purpose are recorded in `docs/formats/provenance.md`; no CarbonEngine source file or
-game asset is embedded in that generated definition snapshot.
-
-The GR2/GSF implementation is included under `formats/gr2`, migrated from
-`format-gr2` after its former EUPL-derived BitKnit2 decoder was replaced by a
-validated clean-room implementation and the package was relicensed MIT. Its
-retained license, provenance, and third-party notices live under
-`format-notices/gr2/` and `docs/formats/provenance.md`.
+carbonenginejs/runtime-resource
+================================
+
+Copyright (c) 2026 CarbonEngineJS contributors.
+
+This package owns CarbonEngineJS resource lifecycle, format selection,
+canonical GPU-free shader/reflection models, and the non-shader format
+implementations listed under `format-notices/`.
+
+CarbonEngine source material, format names, class names, and schema semantics
+remain copyright their original CarbonEngine authors. Fenris Creations
+(CCP Games) source material, tools, assets, shader behavior, and EVE-related
+data remain copyright their original holders. These names are used for
+interoperability and provenance context. This project is not affiliated with
+or endorsed by CCP Games.
+
+The copied format implementations retain their original MIT license and NOTICE
+files under `format-notices/<format>/`. Those notices include third-party
+dependency and behavioral-reference attribution, including meshoptimizer,
+yaml, and black-reader-js.
+
+The bundled Black definition JSON is a generated CarbonEngineJS schema artifact
+copied from `format-carbon` revision
+`d2a3c67cf3d46e8ba78ca19e66558d868178ec24`. Its exact digest and retention
+purpose are recorded in `docs/formats/provenance.md`; no CarbonEngine source file or
+game asset is embedded in that generated definition snapshot.
+
+The GR2/GSF implementation is included under `formats/gr2`, migrated from
+`format-gr2` after its former EUPL-derived BitKnit2 decoder was replaced by a
+validated clean-room implementation and the package was relicensed MIT. Its
+retained license, provenance, and third-party notices live under
+`format-notices/gr2/` and `docs/formats/provenance.md`.

package/README.md

@@ -1,108 +1,129 @@
-# @carbonenginejs/runtime-resource
-
-CarbonEngineJS resource lifecycle, cache, format selection, source, and object
-loading contracts — the GPU-free resource layer.
-
-Use this package when you need Carbon-shaped resource loading (`res:/` paths,
-requirement/emit selection, `Ready()`/`GetObject()`), canonical GPU-free shader
-reflection, or one of the bundled format readers without choosing a GPU
-backend. It sits between format/resource providers and the engines that
-realize prepared resources. It owns neither WebGL/WebGPU realization nor the
-standalone shader parser/compiler packages.
-
-## Install
-
-```sh
-npm install @carbonenginejs/runtime-resource
-```
-
-## Quick start
-
-Concrete formats are explicit tree-shakeable subpaths, never imported by the
-package root:
-
-```js
-import {
-  CjsResMan,
-  CjsResManFetchProvider
-} from "@carbonenginejs/runtime-resource";
-import { CjsMp4Format } from "@carbonenginejs/runtime-resource/formats/mp4";
-
-const resMan = new CjsResMan().Register({
-  paths: {
-    res: "https://cdn.example.invalid/resources/"
-  },
-  source: new CjsResManFetchProvider(),
-  formats: [ CjsMp4Format ]
-});
-
-const resource = resMan.GetResource("res:/video/intro.mp4");
-const video = await resource.Ready();
-```
-
-Browser consumers use worker-backed fetch and declared worker-safe format
-readers by default, with deterministic main-thread fallback; see
-[browser worker execution](docs/reference/workers.md).
-
-Raw audio resource ownership is available from an explicit subpath:
-
-```js
-import {
-  CjsAudioBufferRes,
-  CjsAudioRes
-} from "@carbonenginejs/runtime-resource/resource/audio";
-```
-
-`CjsAudioRes` always represents one addressable audio file. Its backing may be
-a complete loose file, an individually served response, or a window within a
-shared `CjsAudioBufferRes` bank payload.
-
-Canonical effect-resource and shader reflection classes are available from:
-
-```js
-import {
-  Tr2EffectRes,
-  Tr2Shader
-} from "@carbonenginejs/runtime-resource/resource/shader";
-```
-
-`Tr2EffectRes` fail-closed validates complete permutation topology and portable
-reflection, selects a package permutation, and hydrates it into a cached,
-device-free `Tr2Shader`. Engines add programs, layouts, bindings, and other GPU
-state.
-
-## Documentation
-
-- [Package documentation](docs/README.md)
-- [Architecture and boundaries](docs/architecture.md)
-- [Resource lifecycle concepts](docs/concepts/resource-lifecycle.md)
-- [Browser worker execution](docs/reference/workers.md)
-- [Audio resource classes](docs/reference/classes/audio.md)
-- [Resource and shader-reflection classes](docs/reference/classes/resources.md)
-- [Format subpaths](docs/formats/README.md)
-- [Format ownership and fork provenance](docs/formats/provenance.md)
-
-## Development
-
-Non-interactive baseline checks run from the repository root:
-
-```sh
-npm install
-npm run lint
-npm run check
-npm test
-```
-
-`npm run check` builds the consumer package and proves that decorator metadata
-matches between authoring source and built output. `npm test` additionally
-runs the complete GPU-free unit suite; it requires no private assets,
-credentials, network access, browser, or GPU after dependencies are installed.
-
-## License
-
-MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE). CarbonEngine and Fenris
-Creations (CCP Games) are named for interoperability and provenance context;
-copied-reader ownership, licenses, and retained snapshots are recorded in
-[docs/formats/provenance.md](docs/formats/provenance.md). This project is not
-affiliated with, endorsed by, or sponsored by CCP Games or CCP ehf. EVE
-Online and related marks remain the property of their respective owners.
+# @carbonenginejs/runtime-resource
+
+CarbonEngineJS resource lifecycle, cache, format selection, source, and object
+loading contracts — the GPU-free resource layer.
+
+Use this package when you need Carbon-shaped resource loading (`res:/` paths,
+requirement/emit selection, `Ready()`/`GetObject()`), canonical GPU-free shader
+reflection, or one of the bundled format readers without choosing a GPU
+backend. It sits between format/resource providers and the engines that
+realize prepared resources. It owns neither WebGL/WebGPU realization nor the
+standalone shader parser/compiler packages.
+
+## Install
+
+```sh
+npm install @carbonenginejs/runtime-resource
+```
+
+## Quick start
+
+Concrete formats are explicit tree-shakeable subpaths, never imported by the
+package root:
+
+```js
+import {
+  CjsResMan,
+  CjsResManFetchProvider
+} from "@carbonenginejs/runtime-resource";
+import { CjsMp4Format } from "@carbonenginejs/runtime-resource/formats/mp4";
+
+const resMan = new CjsResMan().Register({
+  paths: {
+    res: "https://cdn.example.invalid/resources/"
+  },
+  source: new CjsResManFetchProvider(),
+  formats: [ CjsMp4Format ]
+});
+
+const resource = resMan.GetResource("res:/video/intro.mp4");
+const video = await resource.Ready();
+```
+
+Extensions can also choose the resource/object handler and an ordered reader
+route explicitly. This is useful for Carbon object streams, where either file
+suffix may contain Black bytes or Red/YAML text:
+
+```js
+import { CjsLoadingObject } from "@carbonenginejs/runtime-resource";
+import { CjsBlackFormat } from "@carbonenginejs/runtime-resource/formats/black";
+import { CjsRedFormat } from "@carbonenginejs/runtime-resource/formats/red";
+
+resMan.RegisterExtension("red", CjsLoadingObject, [
+  CjsBlackFormat,
+  CjsRedFormat
+]);
+resMan.RegisterExtension("black", CjsLoadingObject, [
+  CjsBlackFormat,
+  CjsRedFormat
+]);
+
+const object = await resMan.Fetch("res:/definition/example.red");
+```
+
+Browser consumers use worker-backed fetch and declared worker-safe format
+readers by default, with deterministic main-thread fallback; see
+[browser worker execution](docs/reference/workers.md).
+
+Raw audio resource ownership is available from an explicit subpath:
+
+```js
+import {
+  CjsAudioBufferRes,
+  CjsAudioRes
+} from "@carbonenginejs/runtime-resource/resource/audio";
+```
+
+`CjsAudioRes` always represents one addressable audio file. Its backing may be
+a complete loose file, an individually served response, or a window within a
+shared `CjsAudioBufferRes` bank payload.
+
+Canonical effect-resource and shader reflection classes are available from:
+
+```js
+import {
+  Tr2EffectRes,
+  Tr2Shader
+} from "@carbonenginejs/runtime-resource/resource/shader";
+```
+
+`Tr2EffectRes` fail-closed validates complete permutation topology and portable
+reflection, selects a package permutation, and hydrates it into a cached,
+device-free `Tr2Shader`. Engines add programs, layouts, bindings, and other GPU
+state.
+
+## Documentation
+
+- [Package documentation](docs/README.md)
+- [Architecture and boundaries](docs/architecture.md)
+- [Resource lifecycle concepts](docs/concepts/resource-lifecycle.md)
+- [Browser worker execution](docs/reference/workers.md)
+- [Audio resource classes](docs/reference/classes/audio.md)
+- [Resource and shader-reflection classes](docs/reference/classes/resources.md)
+- [Format subpaths](docs/formats/README.md)
+- [Format ownership and fork provenance](docs/formats/provenance.md)
+
+## Development
+
+Non-interactive baseline checks run from the repository root:
+
+```sh
+npm install
+npm run lint
+npm run check
+npm test
+```
+
+`npm run check` builds the consumer package and proves that decorator metadata
+matches between authoring source and built output. `npm test` additionally
+runs the complete GPU-free unit suite; it requires no private assets,
+credentials, network access, browser, or GPU after dependencies are installed.
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE). CarbonEngine and Fenris
+Creations (CCP Games) are named for interoperability and provenance context;
+copied-reader ownership, licenses, and retained snapshots are recorded in
+[docs/formats/provenance.md](docs/formats/provenance.md). This project is not
+affiliated with, endorsed by, or sponsored by CCP Games or CCP ehf. EVE
+Online and related marks remain the property of their respective owners.