@carbonenginejs/runtime-resource 0.8.0 → 0.9.1

package/docs/formats/README.md

@@ -0,0 +1,105 @@
+# 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: [Granny GR2 and GSF](gr2.md),
+[Wwise soundbanks and media](wwise.md), and [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, preserving its behavior and test
+surface; [gr2.md](gr2.md) documents the reader API, output modes, graph
+shape, and hydration contract.
+
+## 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/docs/formats/gr2.md

@@ -0,0 +1,161 @@
+# Granny GR2 and GSF
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource/formats/gr2`  
+Audience: Users and integrators  
+Summary: Defines the pure-JavaScript GR2/GSF reader, its output modes, conversion options, graph shape, and class-hydration boundary.
+
+## Purpose
+
+`CjsGr2Format` reads Granny 3D `.gr2` geometry, skeleton, animation, and
+morph-target data, plus Granny State `.gsf` profiles. It runs in Node and the
+browser without `granny2.dll`, native addons, a GPU, or private assets.
+
+The reader owns Granny container parsing, reflected type-tree walking, section
+decompression, JSON projection, optional curve and vertex-channel conversion,
+GSF projection, and caller-class hydration. Resource caching and publication
+remain with `CjsResMan`; GPU realization remains with engine packages.
+
+Supported section compression is None, Oodle1, and the in-project clean-room
+BitKnit2 decoder. Licensing and migration history are recorded in
+[format provenance](provenance.md).
+
+## Import and basic use
+
+Import the runtime-resource wrapper from its explicit format subpath:
+
+```js
+import { CjsGr2Format } from "@carbonenginejs/runtime-resource/formats/gr2";
+
+const graph = CjsGr2Format.read(bytes);
+const summary = CjsGr2Format.inspect(bytes);
+const asynchronousGraph = await CjsGr2Format.readAsync(bytes);
+```
+
+The wrapper exposes the normal runtime-resource format metadata and
+`isSupported(bytes)` magic probe. It also exports the migrated
+`CjsFormatGr2` reader engine for compatibility, but new consumers should use
+`CjsGr2Format`.
+
+Register it with `CjsResMan` when GR2/GSF should participate in ordinary
+resource loading:
+
+```js
+import { CjsResMan } from "@carbonenginejs/runtime-resource";
+import { CjsGr2Format } from "@carbonenginejs/runtime-resource/formats/gr2";
+
+const resMan = new CjsResMan().Register({
+  source,
+  formats: [ CjsGr2Format ]
+});
+
+const resource = resMan.GetResource("res:/model/ship.gr2");
+const graph = await resource.Ready();
+```
+
+Concrete formats are not imported or registered by the package root.
+
+## Output modes
+
+`emit` selects the representation:
+
+| Value | Result |
+|---|---|
+| `"json"` | Default stable GR2 graph with plain objects |
+| `"gr2Json"` | Explicit alias for the JSON graph |
+| `"gr2"` | GR2 graph hydrated with caller-supplied classes |
+| `"cmf"` | CMF-shaped graph hydrated with caller-supplied classes |
+| `"raw"` | Low-level reflected `granny_file_info` result |
+
+`"gr2"` and `"cmf"` require a non-empty `classes` map. Classes may also be
+supplied with `"json"`/`"gr2Json"` to hydrate selected JSON nodes while
+leaving omitted nodes as plain objects.
+
+## Conversion options
+
+| Option | Default | Effect |
+|---|---:|---|
+| `decompressCurves` | `false` | Adds decoded `knots`, `controls`, and `dimension` to supported compressed animation curves while retaining the raw curve fields |
+| `unpackTangents` | `false` | Converts packed CCP tangent frames into separate normal, tangent, and binormal channels |
+| `rebuildMissingNormals` | `false` | Generates absent normals from positions and triangle indices |
+| `rebuildMissingTangents` | `false` | Generates absent tangents from positions, normals, UVs, and triangle indices |
+| `rebuildMissingBiNormals` | `false` | Generates absent binormals from normals and tangents |
+| `classes` | `{}` | Maps supported graph node keys to constructors |
+
+Tangent unpacking and missing-channel rebuild options may be functions when a
+caller needs per-mesh policy. Rebuild options fill absent data; they do not
+repair authored channels that are present but incorrect.
+
+A reusable reader profile can hold these defaults:
+
+```js
+const reader = new CjsGr2Format({
+  decompressCurves: true,
+  unpackTangents: true
+});
+
+const first = reader.Read(firstBytes);
+const second = reader.Read(secondBytes);
+```
+
+## JSON graph and hydration
+
+The default graph has this general shape:
+
+```text
+Root
+|-- grannyFileFormatRevision, grannyFileSource
+|-- meshes
+|   |-- boneBindings, morphTargets
+|   |-- vertex: flat numeric channels
+|   `-- indices: triangle index groups
+|-- models
+|   `-- skeleton -> bones
+`-- animations
+    `-- trackGroups -> transformTracks -> curves
+```
+
+Vertex channels include positions, normals, tangents, binormals, UVs, blend
+indices, and blend weights when available. `IndexGroup.faces` is a flat array
+of triangle indices. Sparse morph targets carry `vertexIndices`; native and
+annotation-set morph targets share the same projected shape.
+
+For each registered class key, hydration constructs the class without
+arguments and calls:
+
+```js
+new Class().SetValues(nodeFields);
+```
+
+Constructors must therefore support zero-argument construction and
+`SetValues(values)`. Supported GR2 and CMF keys are exposed through
+`CjsGr2Format.CLASS_KEYS`; use `SetClass`, `SetClasses`, `GetClass`, and
+`HasClass` on reusable reader instances.
+
+`ToJSON(value)` and static `toJSON(value)` convert hydrated output into a
+JSON-compatible value. They do not write a binary `.gr2` file or return JSON
+text.
+
+## Granny State
+
+GSF uses the ordinary Granny container with a GState root schema. The reader
+provides dedicated classification, projection, and inspection:
+
+```js
+if (CjsGr2Format.isGsf(bytes)) {
+  const state = CjsGr2Format.readGsf(bytes);
+  const dependencies = CjsGr2Format.inspectGsf(bytes);
+}
+```
+
+The stable GSF projection contains container revision data, model and
+retarget hints, the state machine, animation slots and sets, referenced
+relative `.gr2` files, token count, editor data, and extended data.
+`readGsfAsync` provides the equivalent promise-facing entry point.
+
+## Related documentation
+
+- [Format subpaths](README.md)
+- [Architecture and boundaries](../architecture.md)
+- [Resource lifecycle](../concepts/resource-lifecycle.md)
+- [Format ownership and 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.