@carbonenginejs/runtime-resource 0.8.0 → 0.9.0

package/docs/formats/README.md

@@ -0,0 +1,104 @@
+# Format subpaths
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource/formats`  
+Audience: Users and integrators  
+Summary: Maps every non-shader format subpath and records cross-format output conventions.
+
+## Import rule
+
+Concrete formats are never imported or registered by the package root. Each
+format is an explicit tree-shakeable subpath, registered by the caller:
+
+```js
+import { CjsResMan } from "@carbonenginejs/runtime-resource";
+import { CjsMp4Format } from "@carbonenginejs/runtime-resource/formats/mp4";
+
+const resMan = new CjsResMan().Register({
+  source,
+  formats: [ CjsMp4Format ]
+});
+
+const resource = resMan.GetResource("res:/video/intro.mp4");
+const video = await resource.Ready();
+```
+
+Formats return plain payload objects. Semantic resource classes apply them
+through `SetPayload()`, validate their own required fields, and throw
+`CJS_RESOURCE_PAYLOAD_INVALID` before replacing a previously valid payload.
+`GetPayload()`, `HasPayload()`, and `ReleasePayload()` manage transient CPU
+retention without introducing a parallel DTO class hierarchy.
+
+## Format map
+
+| Format | Class | Import |
+|---|---|---|
+| Black (`.black`) | `CjsBlackFormat` | `@carbonenginejs/runtime-resource/formats/black` |
+| Wwise soundbank (`.bnk`) | `CjsBnkFormat` | `@carbonenginejs/runtime-resource/formats/bnk` |
+| CMF (`.cmf`) | `CjsCmfFormat` | `@carbonenginejs/runtime-resource/formats/cmf` |
+| DDS (`.dds`) | `CjsDdsFormat` | `@carbonenginejs/runtime-resource/formats/dds` |
+| FBX (`.fbx`) | `CjsFbxFormat` | `@carbonenginejs/runtime-resource/formats/fbx` |
+| FLAC (`.flac`) | `CjsFlacFormat` | `@carbonenginejs/runtime-resource/formats/flac` |
+| GIF (`.gif`) | `CjsGifFormat` | `@carbonenginejs/runtime-resource/formats/gif` |
+| glTF (`.gltf`/`.glb`) | `CjsGltfFormat` | `@carbonenginejs/runtime-resource/formats/gltf` |
+| Granny GR2/GSF (`.gr2`/`.gsf`) | `CjsGr2Format` | `@carbonenginejs/runtime-resource/formats/gr2` |
+| JPEG (`.jpg`/`.jpeg`) | `CjsJpegFormat` | `@carbonenginejs/runtime-resource/formats/jpeg` |
+| MP3 (`.mp3`) | `CjsMp3Format` | `@carbonenginejs/runtime-resource/formats/mp3` |
+| MP4 (`.mp4`) | `CjsMp4Format` | `@carbonenginejs/runtime-resource/formats/mp4` |
+| OBJ (`.obj`) | `CjsObjFormat` | `@carbonenginejs/runtime-resource/formats/obj` |
+| Ogg (`.ogg`) | `CjsOggFormat` | `@carbonenginejs/runtime-resource/formats/ogg` |
+| PNG (`.png`) | `CjsPngFormat` | `@carbonenginejs/runtime-resource/formats/png` |
+| Red (`.red`) | `CjsRedFormat` | `@carbonenginejs/runtime-resource/formats/red` |
+| STL (`.stl`) | `CjsStlFormat` | `@carbonenginejs/runtime-resource/formats/stl` |
+| TGA (`.tga`) | `CjsTgaFormat` | `@carbonenginejs/runtime-resource/formats/tga` |
+| WAV (`.wav`) | `CjsWavFormat` | `@carbonenginejs/runtime-resource/formats/wav` |
+| WebM (`.webm`) | `CjsWebmFormat` | `@carbonenginejs/runtime-resource/formats/webm` |
+| WebP (`.webp`) | `CjsWebpFormat` | `@carbonenginejs/runtime-resource/formats/webp` |
+| Wwise media (`.wem`) | `CjsWemFormat` | `@carbonenginejs/runtime-resource/formats/wem` |
+| YAML (`.yaml`/`.yml`) | `CjsYamlFormat` | `@carbonenginejs/runtime-resource/formats/yaml` |
+
+Detailed pages: [Wwise soundbanks and media](wwise.md),
+[STL export](stl.md). Ownership history, retained snapshots, and donor
+licensing are recorded in [provenance.md](provenance.md).
+
+## Granny GR2/GSF
+
+`CjsGr2Format` reads `.gr2` geometry/skeleton/animation graphs and `.gsf`
+(GState) profiles with no native tooling: section decompression (None,
+Oodle1, and the clean-room BitKnit2 decoder), reflected type-tree walking,
+GR2 JSON emission, optional curve decompression, CCP packed tangent-frame
+unpacking, and caller-class hydration (`emit: "gr2"`/`"cmf"` with a
+`classes` map). It was migrated from `@carbonenginejs/format-gr2` after that
+package's 2026-07-24 MIT relicense; the frozen donor repository documents
+the reader API and JSON graph in detail, and this copy preserves its
+behavior and test surface.
+
+## Red output markers
+
+Red payload output reserves configurable type, ID, reference, and sequence
+values markers (`_type`, `_id`, `_reference`, and `_values` by default).
+Repeated or cyclic sequences use an ID-bearing values envelope; unique
+sequences remain arrays. Authored fields may not collide with active markers,
+so remap the marker options when those names are real data. Disabling the
+reference marker preserves actual JavaScript identity; cyclic output in that
+mode is intentionally not JSON-serializable.
+
+## DDS decoded fallback
+
+Decoded DDS fallback currently has a narrower contract than native DDS
+texture output. `emit: "rgba"` returns one canonical 2D surface decoded from
+the first DDS subresource; it does not preserve stored mip levels, cube
+faces, array layers, or volume slices. Consumers may use it for ordinary 2D
+fallback when the engine owns any required mip generation, but must not infer
+decoded multi-subresource support from a successful RGBA probe. A future
+richer decoded-texture contract must be introduced explicitly rather than
+overloading the current RGBA fields.
+
+The software path includes BC1-BC5 and BC7 as RGBA8, plus signed and unsigned
+BC6H as linear `Float32Array` RGBA without clamping HDR values. These block
+decoders are implemented in-project with no codec package.
+
+## Related documentation
+
+- [Queues, publication, and registration](../reference/queues.md)
+- [Format ownership and fork provenance](provenance.md)

package/{FORMAT-PROVENANCE.md → docs/formats/provenance.md}

@@ -1,155 +1,173 @@
-# Format ownership and fork provenance
-
-On 2026-07-13, the non-shader runtime format implementations below were copied
-once into `runtime-resource`. Their standalone repositories remain frozen with
-their existing APIs and names; they are not upstreams for the runtime copies.
-
-Copied paths were `src/` and the behavioral `test/` corpus. Package publishing
-scripts and CLIs were not copied. Exact donor license and notice files are kept
-under `format-notices/<format>/`.
-
-| Legacy package | Source revision/state | Runtime class | Runtime import |
-|---|---|---|---|
-| `format-black` | `9fcaaff9e5f28c90b628d8a10b7c79aff7913a90` | `CjsBlackFormat` | `@carbonenginejs/runtime-resource/formats/black` |
-| `format-cmf` | unborn working-tree snapshot | `CjsCmfFormat` | `@carbonenginejs/runtime-resource/formats/cmf` |
-| `format-dds` | `66fa149cd826e1114ad0be84479f89dee753ed76` | `CjsDdsFormat` | `@carbonenginejs/runtime-resource/formats/dds` |
-| `format-fbx` | `8d0fcc2fe44c8096b35e360a903bff30b49eb592` | `CjsFbxFormat` | `@carbonenginejs/runtime-resource/formats/fbx` |
-| `format-flac` | unborn working-tree snapshot | `CjsFlacFormat` | `@carbonenginejs/runtime-resource/formats/flac` |
-| `format-gif` | `5d831c5c0533a9579682f776274574289a520899` | `CjsGifFormat` | `@carbonenginejs/runtime-resource/formats/gif` |
-| `format-gltf` | `d0dadf920828bceec987c2a5fa1f161f81db28aa` | `CjsGltfFormat` | `@carbonenginejs/runtime-resource/formats/gltf` |
-| `format-jpeg` | `bed2253ea979bba27812420fa897987d82a91793` | `CjsJpegFormat` | `@carbonenginejs/runtime-resource/formats/jpeg` |
-| `format-mp3` | unborn working-tree snapshot | `CjsMp3Format` | `@carbonenginejs/runtime-resource/formats/mp3` |
-| `format-mp4` | `cffc5a57b115a99ed9e0947a6b9d3390ffc3581c` | `CjsMp4Format` | `@carbonenginejs/runtime-resource/formats/mp4` |
-| `format-obj` | `e5d3f9a1520c7855bd5b6edc1e2304a7b4e18176` | `CjsObjFormat` | `@carbonenginejs/runtime-resource/formats/obj` |
-| `format-ogg` | unborn working-tree snapshot | `CjsOggFormat` | `@carbonenginejs/runtime-resource/formats/ogg` |
-| `format-png` | `04dbb7c0f289043c3c32d9141ec3ef74aeeb1c43` | `CjsPngFormat` | `@carbonenginejs/runtime-resource/formats/png` |
-| `format-red` | `98beab6988111418d6e09827b92d27e08da4c05b` | `CjsRedFormat` | `@carbonenginejs/runtime-resource/formats/red` |
-| `format-stl` | `4858f9a37bf140a3c544fa30a13a6fcce015247b` | `CjsStlFormat` | `@carbonenginejs/runtime-resource/formats/stl` |
-| `format-tga` | `b0f9df263727057537b2279322e8cd088f366179` | `CjsTgaFormat` | `@carbonenginejs/runtime-resource/formats/tga` |
-| `format-wav` | unborn working-tree snapshot | `CjsWavFormat` | `@carbonenginejs/runtime-resource/formats/wav` |
-| `format-webm` | `459203ac293d0d53fff0e43494b7e47d8d4c92bd` | `CjsWebmFormat` | `@carbonenginejs/runtime-resource/formats/webm` |
-| `format-webp` | `19155e9cc7ae05845c23a3c259d3a586569eba40` | `CjsWebpFormat` | `@carbonenginejs/runtime-resource/formats/webp` |
-| `format-yaml` | `3d7e1d1cf9b7a936283d6050efe43a0a9fadb6a4` | `CjsYamlFormat` | `@carbonenginejs/runtime-resource/formats/yaml` |
-
-The unborn donors had no commit-addressable `HEAD`; this document deliberately
-records them as working-tree snapshots rather than inventing a revision. Their
-copied runtime files are the deterministic retained snapshot.
-
-## Black definition snapshot
-
-The Black reader uses the package-owned generated definition snapshot at
-`src/formats/black/core/black-schema-v1-2026-07-11.json`. The Red format exposes
-the same catalog for discovery, but its YAML reader currently accepts named
-fields without registry enforcement. The snapshot was copied from
-`format-carbon` revision `d2a3c67cf3d46e8ba78ca19e66558d868178ec24`
-with SHA-256
-`008ECB29E670EFC678B471A6EFF099600A29C2907912FC42B854995904604691`.
-
-This retained generated artifact keeps the published readers deterministic and
-browser-safe without a runtime dependency on a sibling checkout or an
-unpublished `format-carbon` export. `format-carbon` remains the build-time
-authority for future schema regeneration; an updated snapshot must record its
-new source revision and digest here.
-
-## Native additions
-
-Formats below were authored directly in `runtime-resource` and have no legacy
-donor package. Their `format-notices/<format>/` entries record third-party
-format attribution rather than fork provenance.
-
-| Format | Runtime class | Runtime import | Notes |
-|---|---|---|---|
-| Wwise soundbank (`.bnk`) | `CjsBnkFormat` | `@carbonenginejs/runtime-resource/formats/bnk` | Original code; chunk layout from public community documentation (ww2ogg, vgmstream, wwiser), no code copied. Also carries the SoundbanksInfo JSON helpers (`parseSoundbanksInfo`, `buildSoundbanksCatalog`, `joinSoundbanksInfo`) and `wwiseIdFromName` (FNV-1 32 of the lowercased name, verified against EVE bank/language ids). HIRC entries additionally decode version-stable typed fields (event action lists, action type/target, sound and music-track source ids), pinned by hexdump against bank generator version 150, and the `wwise` static namespace groups the domain toolkit (SoundbanksInfo helpers, id hash, `wwise.eventMediaFromBanks` event → media resolution over inspected banks — graph interpretation for consumers; never used by the resource lifecycle). |
-| Wwise media (`.wem`) | `CjsWemFormat` | `@carbonenginejs/runtime-resource/formats/wem` | Original code; container/codec-tag behavior from public community documentation (ww2ogg, vgmstream, wwiser), no code copied. Includes a Wwise-Vorbis→Ogg repacker (`emit: "ogg"`), an original reimplementation of the ww2ogg algorithm with inline granule computation (no revorb pass needed), and a PTADPCM/16-bit-PCM decoder (`emit: "pcm"` / `toPcm()`, AudioBuffer-ready float32; PTADPCM algorithm from community documentation, verified against EVE media). |
-
-## Post-fork additions inside copied formats
-
-- `formats/dds` gained original, dependency-free **BC6H and BC7 CPU decoders**
-  in `runtime-resource` 0.8.0 (2026-07-21). BC6H covers all fourteen modes,
-  signed and unsigned HDR, transformed endpoints, partition/anchor fixups,
-  interpolation, reserved opaque-black modes, and float RGBA output. BC7 covers
-  all eight modes,
-  two- and three-subset partitions, anchor fixups, P-bits, dual index streams,
-  channel rotation, edge blocks, and the reserved transparent mode. Fixed bit
-  layouts and tables follow the Khronos Data Format Specification and Microsoft
-  BC6H/BC7 documentation. Tests cover every mode and signed/unsigned fixtures;
-  BC7 was also checked against randomized valid-mode blocks and both decoders
-  were exercised on real EVE textures acquired through `tools-core`.
-- `formats/stl` received a writer hardening pass (2026-07-18) without changing
-  its donor origin: binary provenance headers now round-trip the caller's solid
-  name, shared triangle indices are validated as in-range safe integers, scaled
-  coordinates must remain finite, and binary coordinates must fit float32
-  instead of silently becoming infinities. Writer JSDoc and ASCII/binary
-  round-trip/error coverage were expanded in the runtime-owned copy.
-- `formats/cmf` gained a **binary CMF v1 writer** (2026-07-15,
-  `src/formats/cmf/core/writer.js`, `CjsCmfFormat.write`/`writeAsync` and
-  `Write`/`WriteAsync`): original code implementing CarbonEngine's
-  `cmf::BuildFile` behavior — tagged self-relative span flattening with leaf
-  chunk dedup, BufferView→section remapping in first-encounter order,
-  meshoptimizer vertex/index compression (index compression canonicalizes
-  triangle rotation, matching the engine's own writer test expectations), and
-  the post-crc32 file checksum. Verified by write→read roundtrips against the
-  runtime reader; `E:\carbonengine\mesh\{include,src}\cmf` was the behavioral
-  reference, no code copied. `writeShared`/`writeSharedAsync` plus
-  `core/pack.js` (channel interleaving, index packing, unique buffer-index
-  assignment) serialize shared geometry directly, enabling GR2/OBJ/glTF→CMF —
-  verified against real EVE `.gr2` models fetched via
-  `@carbonenginejs/tool-index` (positions exact, triangles equivalent).
-- `formats/cmf` also gained the **GR2 skeleton/animation converter**
-  (2026-07-15, `src/formats/cmf/core/gr2Anim.js`, applied automatically by
-  `writeShared`): GR2-shaped skeletons (root list or `models[].skeleton`)
-  convert to CMF bones/parents/rest transforms with inverse binds rebuilt
-  from the rest hierarchy; decoded Granny curves convert to CMF Step/Linear
-  channels — degree ≤ 1 exactly, degree 2 via adaptive de Boor resampling
-  with discontinuities snapped to one float32 ULP. Consumes only decoded
-  `{knots, controls}` data so the MIT runtime stays independent of the GR2
-  package. Validated on EVE ships (cde3_t3, gde3_t3, cfaux1_t1, mfaux1_t1:
-  3,377 channels ≤ 8.3e-4 positional / ≤ 0.14° rotational vs the GR2 runtime
-  sampler; 9 Granny curve formats) and characters (basicfemale: 132-bone
-  skeleton, exact skin weights).
-- `formats/ogg` gained a pure-JS **Ogg Vorbis PCM decoder** (2026-07-15,
-  `src/formats/ogg/core/{vorbis.js,imdct.js}`, `emit: "pcm"`/`"audio"`):
-  original code implementing the Vorbis I specification (floor 1, residues
-  0/1/2, square-polar coupling, FFT-based IMDCT, windowed overlap-add).
-  stb_vorbis (public domain) was consulted as a behavioral reference and is
-  the source of the spec's floor1 `inverse_db_table` constants; no licensed
-  code was copied. Validated bit-comparable to ffmpeg (max diff ~3e-8) and
-  vgmstream (±1 int16 LSB) across the EVE Vorbis corpus.
-
-## Wem packed-codebook snapshot
-
-The wem Ogg repacker ships a package-owned copy of the aoTuV 6.03 packed
-Vorbis codebook library at
-`src/formats/wem/core/packedCodebooksAotuv603.js` (base64 module). It was
-copied byte-identically from `packed_codebooks_aoTuV_603.bin` in the ww2ogg
-distribution (`github.com/hcs64/ww2ogg`), 74,387 bytes, SHA-256
-`00a93eab267d281401b1efd54e888a2e183299b9e6c446c48d09f701a89d9d27`, retrieved
-2026-07-15. The data is BSD-licensed (Xiph.org Foundation, Adam Gashlin);
-attribution and the full license terms are recorded in
-`format-notices/wem/NOTICE` and `format-notices/wem/LICENSE`. An updated
-snapshot must record its new source and digest here.
-
-## Deliberately not copied
-
-- `format-gr2` is the intended runtime-resource owner target, but its current
-  BitKnit-derived implementation is EUPL-1.2. It remains separate and active
-  until that code is replaced or an explicit distribution-license decision is
-  made. It has not been deprecated or relabeled as MIT.
-- `format-carbon` remains the schema emitter/generator and build-time schema
-  authority. Black consumes its published definitions; Red exposes the copied
-  catalog but does not yet enforce it while reading YAML fields.
-- `format-dxbc`, `format-hlsl`, `format-webgl`, and `format-webgpu` are active
-  shader work and were not copied, annotated, or otherwise modified by this
-  migration.
-
-## Typed-array ownership adjustments
-
-The runtime copies preserve caller byte objects by reference. During the fork,
-three avoidable source-buffer copies were changed to views:
-
-- CMF compressed sections use `Uint8Array.subarray`.
-- glTF GLB chunks use `Uint8Array.subarray`.
-- FBX raw binary property payloads use `Uint8Array.subarray`.
-
-Decoder output buffers and GIF per-frame snapshots still allocate because those
-values have independent semantic identity.
+# Format ownership and fork provenance
+
+Status: Stable  
+Scope: `@carbonenginejs/runtime-resource/formats`  
+Audience: Users, integrators, and maintainers  
+Summary: Records where each format implementation came from, retained snapshots and digests, and what was deliberately not copied.
+
+On 2026-07-13, the non-shader runtime format implementations below were copied
+once into `runtime-resource`. Their standalone repositories remain frozen with
+their existing APIs and names; they are not upstreams for the runtime copies.
+
+Copied paths were `src/` and the behavioral `test/` corpus. Package publishing
+scripts and CLIs were not copied. Exact donor license and notice files are kept
+under `format-notices/<format>/`.
+
+| Legacy package | Source revision/state | Runtime class | Runtime import |
+|---|---|---|---|
+| `format-black` | `9fcaaff9e5f28c90b628d8a10b7c79aff7913a90` | `CjsBlackFormat` | `@carbonenginejs/runtime-resource/formats/black` |
+| `format-cmf` | unborn working-tree snapshot | `CjsCmfFormat` | `@carbonenginejs/runtime-resource/formats/cmf` |
+| `format-dds` | `66fa149cd826e1114ad0be84479f89dee753ed76` | `CjsDdsFormat` | `@carbonenginejs/runtime-resource/formats/dds` |
+| `format-fbx` | `8d0fcc2fe44c8096b35e360a903bff30b49eb592` | `CjsFbxFormat` | `@carbonenginejs/runtime-resource/formats/fbx` |
+| `format-flac` | unborn working-tree snapshot | `CjsFlacFormat` | `@carbonenginejs/runtime-resource/formats/flac` |
+| `format-gif` | `5d831c5c0533a9579682f776274574289a520899` | `CjsGifFormat` | `@carbonenginejs/runtime-resource/formats/gif` |
+| `format-gltf` | `d0dadf920828bceec987c2a5fa1f161f81db28aa` | `CjsGltfFormat` | `@carbonenginejs/runtime-resource/formats/gltf` |
+| `format-jpeg` | `bed2253ea979bba27812420fa897987d82a91793` | `CjsJpegFormat` | `@carbonenginejs/runtime-resource/formats/jpeg` |
+| `format-mp3` | unborn working-tree snapshot | `CjsMp3Format` | `@carbonenginejs/runtime-resource/formats/mp3` |
+| `format-mp4` | `cffc5a57b115a99ed9e0947a6b9d3390ffc3581c` | `CjsMp4Format` | `@carbonenginejs/runtime-resource/formats/mp4` |
+| `format-obj` | `e5d3f9a1520c7855bd5b6edc1e2304a7b4e18176` | `CjsObjFormat` | `@carbonenginejs/runtime-resource/formats/obj` |
+| `format-ogg` | unborn working-tree snapshot | `CjsOggFormat` | `@carbonenginejs/runtime-resource/formats/ogg` |
+| `format-png` | `04dbb7c0f289043c3c32d9141ec3ef74aeeb1c43` | `CjsPngFormat` | `@carbonenginejs/runtime-resource/formats/png` |
+| `format-red` | `98beab6988111418d6e09827b92d27e08da4c05b` | `CjsRedFormat` | `@carbonenginejs/runtime-resource/formats/red` |
+| `format-stl` | `4858f9a37bf140a3c544fa30a13a6fcce015247b` | `CjsStlFormat` | `@carbonenginejs/runtime-resource/formats/stl` |
+| `format-tga` | `b0f9df263727057537b2279322e8cd088f366179` | `CjsTgaFormat` | `@carbonenginejs/runtime-resource/formats/tga` |
+| `format-wav` | unborn working-tree snapshot | `CjsWavFormat` | `@carbonenginejs/runtime-resource/formats/wav` |
+| `format-webm` | `459203ac293d0d53fff0e43494b7e47d8d4c92bd` | `CjsWebmFormat` | `@carbonenginejs/runtime-resource/formats/webm` |
+| `format-webp` | `19155e9cc7ae05845c23a3c259d3a586569eba40` | `CjsWebpFormat` | `@carbonenginejs/runtime-resource/formats/webp` |
+| `format-yaml` | `3d7e1d1cf9b7a936283d6050efe43a0a9fadb6a4` | `CjsYamlFormat` | `@carbonenginejs/runtime-resource/formats/yaml` |
+
+The unborn donors had no commit-addressable `HEAD`; this document deliberately
+records them as working-tree snapshots rather than inventing a revision. Their
+copied runtime files are the deterministic retained snapshot.
+
+On 2026-07-24, following `format-gr2`'s MIT relicense (its EUPL-derived
+BitKnit decoder was replaced by a clean-room implementation written from the
+published specification in that package's `docs/formats/bitknit2.md`), the
+GR2/GSF reader joined the runtime copies:
+
+| Legacy package | Source revision/state | Runtime class | Runtime import |
+|---|---|---|---|
+| `format-gr2` | `fa64607de7a3a96ed3b1aec5288bf71057642043` (v0.2.0, MIT) | `CjsGr2Format` | `@carbonenginejs/runtime-resource/formats/gr2` |
+
+The copied engine keeps its donor class name (`CjsFormatGr2`, re-exported)
+under `formats/gr2/core/`; `CjsGr2Format` is the runtime-authored contract
+wrapper. Donor license and notice files are kept under
+`format-notices/gr2/`.
+
+## Black definition snapshot
+
+The Black reader uses the package-owned generated definition snapshot at
+`src/formats/black/core/black-schema-v1-2026-07-11.json`. The Red format exposes
+the same catalog for discovery, but its YAML reader currently accepts named
+fields without registry enforcement. The snapshot was copied from
+`format-carbon` revision `d2a3c67cf3d46e8ba78ca19e66558d868178ec24`
+with SHA-256
+`008ECB29E670EFC678B471A6EFF099600A29C2907912FC42B854995904604691`.
+
+This retained generated artifact keeps the published readers deterministic and
+browser-safe without a runtime dependency on a sibling checkout or an
+unpublished `format-carbon` export. `format-carbon` remains the build-time
+authority for future schema regeneration; an updated snapshot must record its
+new source revision and digest here.
+
+## Native additions
+
+Formats below were authored directly in `runtime-resource` and have no legacy
+donor package. Their `format-notices/<format>/` entries record third-party
+format attribution rather than fork provenance.
+
+| Format | Runtime class | Runtime import | Notes |
+|---|---|---|---|
+| Wwise soundbank (`.bnk`) | `CjsBnkFormat` | `@carbonenginejs/runtime-resource/formats/bnk` | Original code; chunk layout from public community documentation (ww2ogg, vgmstream, wwiser), no code copied. Also carries the SoundbanksInfo JSON helpers (`parseSoundbanksInfo`, `buildSoundbanksCatalog`, `joinSoundbanksInfo`) and `wwiseIdFromName` (FNV-1 32 of the lowercased name, verified against EVE bank/language ids). HIRC entries additionally decode version-stable typed fields (event action lists, action type/target, sound and music-track source ids), pinned by hexdump against bank generator version 150, and the `wwise` static namespace groups the domain toolkit (SoundbanksInfo helpers, id hash, `wwise.eventMediaFromBanks` event → media resolution over inspected banks — graph interpretation for consumers; never used by the resource lifecycle). |
+| Wwise media (`.wem`) | `CjsWemFormat` | `@carbonenginejs/runtime-resource/formats/wem` | Original code; container/codec-tag behavior from public community documentation (ww2ogg, vgmstream, wwiser), no code copied. Includes a Wwise-Vorbis→Ogg repacker (`emit: "ogg"`), an original reimplementation of the ww2ogg algorithm with inline granule computation (no revorb pass needed), and a PTADPCM/16-bit-PCM decoder (`emit: "pcm"` / `toPcm()`, AudioBuffer-ready float32; PTADPCM algorithm from community documentation, verified against EVE media). |
+
+## Post-fork additions inside copied formats
+
+- `formats/dds` gained original, dependency-free **BC6H and BC7 CPU decoders**
+  in `runtime-resource` 0.8.0 (2026-07-21). BC6H covers all fourteen modes,
+  signed and unsigned HDR, transformed endpoints, partition/anchor fixups,
+  interpolation, reserved opaque-black modes, and float RGBA output. BC7 covers
+  all eight modes,
+  two- and three-subset partitions, anchor fixups, P-bits, dual index streams,
+  channel rotation, edge blocks, and the reserved transparent mode. Fixed bit
+  layouts and tables follow the Khronos Data Format Specification and Microsoft
+  BC6H/BC7 documentation. Tests cover every mode and signed/unsigned fixtures;
+  BC7 was also checked against randomized valid-mode blocks and both decoders
+  were exercised on real EVE textures acquired through `tools-core`.
+- `formats/stl` received a writer hardening pass (2026-07-18) without changing
+  its donor origin: binary provenance headers now round-trip the caller's solid
+  name, shared triangle indices are validated as in-range safe integers, scaled
+  coordinates must remain finite, and binary coordinates must fit float32
+  instead of silently becoming infinities. Writer JSDoc and ASCII/binary
+  round-trip/error coverage were expanded in the runtime-owned copy.
+- `formats/cmf` gained a **binary CMF v1 writer** (2026-07-15,
+  `src/formats/cmf/core/writer.js`, `CjsCmfFormat.write`/`writeAsync` and
+  `Write`/`WriteAsync`): original code implementing CarbonEngine's
+  `cmf::BuildFile` behavior — tagged self-relative span flattening with leaf
+  chunk dedup, BufferView→section remapping in first-encounter order,
+  meshoptimizer vertex/index compression (index compression canonicalizes
+  triangle rotation, matching the engine's own writer test expectations), and
+  the post-crc32 file checksum. Verified by write→read roundtrips against the
+  runtime reader; CarbonEngine's `mesh` CMF sources were the behavioral
+  reference, no code copied. `writeShared`/`writeSharedAsync` plus
+  `core/pack.js` (channel interleaving, index packing, unique buffer-index
+  assignment) serialize shared geometry directly, enabling GR2/OBJ/glTF→CMF —
+  verified against real EVE `.gr2` models fetched via
+  `@carbonenginejs/tool-index` (positions exact, triangles equivalent).
+- `formats/cmf` also gained the **GR2 skeleton/animation converter**
+  (2026-07-15, `src/formats/cmf/core/gr2Anim.js`, applied automatically by
+  `writeShared`): GR2-shaped skeletons (root list or `models[].skeleton`)
+  convert to CMF bones/parents/rest transforms with inverse binds rebuilt
+  from the rest hierarchy; decoded Granny curves convert to CMF Step/Linear
+  channels — degree ≤ 1 exactly, degree 2 via adaptive de Boor resampling
+  with discontinuities snapped to one float32 ULP. Consumes only decoded
+  `{knots, controls}` data so the MIT runtime stays independent of the GR2
+  package. Validated on EVE ships (cde3_t3, gde3_t3, cfaux1_t1, mfaux1_t1:
+  3,377 channels ≤ 8.3e-4 positional / ≤ 0.14° rotational vs the GR2 runtime
+  sampler; 9 Granny curve formats) and characters (basicfemale: 132-bone
+  skeleton, exact skin weights).
+- `formats/ogg` gained a pure-JS **Ogg Vorbis PCM decoder** (2026-07-15,
+  `src/formats/ogg/core/{vorbis.js,imdct.js}`, `emit: "pcm"`/`"audio"`):
+  original code implementing the Vorbis I specification (floor 1, residues
+  0/1/2, square-polar coupling, FFT-based IMDCT, windowed overlap-add).
+  stb_vorbis (public domain) was consulted as a behavioral reference and is
+  the source of the spec's floor1 `inverse_db_table` constants; no licensed
+  code was copied. Validated bit-comparable to ffmpeg (max diff ~3e-8) and
+  vgmstream (±1 int16 LSB) across the EVE Vorbis corpus.
+
+## Wem packed-codebook snapshot
+
+The wem Ogg repacker ships a package-owned copy of the aoTuV 6.03 packed
+Vorbis codebook library at
+`src/formats/wem/core/packedCodebooksAotuv603.js` (base64 module). It was
+copied byte-identically from `packed_codebooks_aoTuV_603.bin` in the ww2ogg
+distribution (`github.com/hcs64/ww2ogg`), 74,387 bytes, SHA-256
+`00a93eab267d281401b1efd54e888a2e183299b9e6c446c48d09f701a89d9d27`, retrieved
+2026-07-15. The data is BSD-licensed (Xiph.org Foundation, Adam Gashlin);
+attribution and the full license terms are recorded in
+`format-notices/wem/NOTICE` and `format-notices/wem/LICENSE`. An updated
+snapshot must record its new source and digest here.
+
+## Deliberately not copied
+
+- `format-gr2` migrated into `formats/gr2` on 2026-07-24 (see the dated
+  table above) after its EUPL constraint was resolved; its standalone
+  repository is now a frozen legacy distribution like the other donors.
+- `format-carbon` remains the schema emitter/generator and build-time schema
+  authority. Black consumes its published definitions; Red exposes the copied
+  catalog but does not yet enforce it while reading YAML fields.
+- `format-dxbc`, `format-hlsl`, `format-webgl`, and `format-webgpu` are active
+  shader work and were not copied, annotated, or otherwise modified by this
+  migration.
+
+## Typed-array ownership adjustments
+
+The runtime copies preserve caller byte objects by reference. During the fork,
+three avoidable source-buffer copies were changed to views:
+
+- CMF compressed sections use `Uint8Array.subarray`.
+- glTF GLB chunks use `Uint8Array.subarray`.
+- FBX raw binary property payloads use `Uint8Array.subarray`.
+
+Decoder output buffers and GIF per-frame snapshots still allocate because those
+values have independent semantic identity.

package/docs/formats/stl.md

@@ -0,0 +1,37 @@
+# STL export
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource/formats/stl`  
+Audience: Users and integrators  
+Summary: Defines the STL writer contract for shared geometry, including validation and watertight checking.
+
+## Contract
+
+`CjsStlFormat` writes shared geometry directly to binary or ASCII STL. The
+writer consumes `mesh.vertex.position` and triangular `mesh.indices[].faces`;
+multiple meshes and index groups are flattened in encounter order because STL
+does not carry portable scene, material, skin, or animation structure.
+
+```js
+import { CjsStlFormat } from "@carbonenginejs/runtime-resource/formats/stl";
+
+const bytes = CjsStlFormat.write(sharedGeometry, {
+  binary: true,
+  solidName: "ship_hull",
+  scale: 1000,
+  requireWatertight: true
+});
+```
+
+Writes do not mutate the shared input. Facet normals are recalculated from
+winding by default; set `recalculateNormals: false` to average valid vertex
+normals. Degenerate triangles are skipped by default. Index values must be
+safe integers within the position channel, and binary output rejects
+coordinates outside float32 range instead of silently emitting infinities.
+The `requireWatertight` option rejects open, non-manifold, inconsistently
+wound, or degenerate output.
+
+## Related documentation
+
+- [Format subpaths](README.md)
+- [Format ownership and fork provenance](provenance.md)

package/docs/formats/wwise.md

@@ -0,0 +1,44 @@
+# Wwise soundbanks and media
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource/formats/bnk`, `@carbonenginejs/runtime-resource/formats/wem`  
+Audience: Users and integrators  
+Summary: Defines the Wwise container inspection, event/media graph extraction, and WEM conversion contracts.
+
+## Scope
+
+`formats/bnk` and `formats/wem` cover Wwise container inspection, event/media
+graph extraction, embedded-member access, and the currently supported WEM
+conversion routes. They do not own AudioBuffer construction, playback, audio
+manager behavior, or decoded-backend retention.
+
+## Soundbank inspection
+
+`CjsBnkFormat.inspect()` decodes the chunk map, embedded media index, bank
+names, and the HIRC listing with version-stable typed fields (event action
+lists, action type/target, sound and music-track source ids; pinned against
+bank generator version 150). The Wwise-domain toolkit is grouped under the
+`CjsBnkFormat.wwise` static: the SoundbanksInfo catalog helpers, the FNV-1
+id hash, and event to media resolution:
+
+```js
+import { CjsBnkFormat } from "@carbonenginejs/runtime-resource/formats/bnk";
+import { CjsWemFormat } from "@carbonenginejs/runtime-resource/formats/wem";
+
+const inspections = bankByteArrays.map(bytes => CjsBnkFormat.inspect(bytes));
+const { eventMedia } = CjsBnkFormat.wwise.eventMediaFromBanks(inspections);
+// eventMedia: Map<eventObjectId, Set<wemId>> - banks may split events from
+// their target sounds, so pass every related bank to one call.
+
+const ogg = CjsWemFormat.toOgg(wemBytes);   // Wwise Vorbis -> Ogg (lossless)
+const pcm = CjsWemFormat.toPcm(wemBytes);   // PTADPCM / 16-bit PCM -> float32
+```
+
+The read/inspect path stays a pure container reader;
+`wwise.eventMediaFromBanks` is graph interpretation offered for consumers
+with their own engines — the resource lifecycle never calls it.
+
+## Related documentation
+
+- [Format subpaths](README.md)
+- [Format ownership and fork provenance](provenance.md)