@carbonenginejs/runtime-resource 0.8.0 → 0.9.1

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)

package/docs/reference/classes/README.md

@@ -0,0 +1,33 @@
+# Class catalog
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource` classes  
+Audience: Users, maintainers, and automated readers  
+Summary: Indexes the one-sentence purpose descriptors for every maintained class in the package.
+
+## Purpose
+
+Every maintained class carries exactly one catalog entry with a stable HTML
+marker, so a class can be located with an exact low-cost search:
+
+```sh
+rg 'class:CjsResMan' docs/reference/classes
+```
+
+Entries record a one-sentence responsibility plus Export, Source, Visibility,
+and Kind metadata. The catalog is an index, not a replacement for the API
+reference or source documentation, and it is validated by the shared
+documentation check against the actual source tree.
+
+## Catalog pages
+
+- [core.md](core.md): the resource manager, MotherLode cache, resource and
+  source classes, and the format/probe bases.
+- [resources.md](resources.md): the Carbon-shaped semantic resource and data
+  classes under `src/resources`.
+- [texture.md](texture.md): texture-array aggregation classes under
+  `src/texture`.
+- [formats.md](formats.md): format entry classes and their internal reader
+  machinery under `src/formats`.
+- [dropped.md](dropped.md): retained native shapes under `src/dropped` that
+  are documented but never exported or bundled.

package/docs/reference/classes/core.md

@@ -0,0 +1,106 @@
+# Core class catalog
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource` classes under `src/` and `src/format/`  
+Audience: Users, maintainers, and automated readers  
+Summary: Provides one-sentence purpose descriptors for the resource manager, registry, resource, source, and format/probe base classes.
+
+<!-- class:CjsMotherLode -->
+## `CjsMotherLode`
+
+Strong, deterministic resource registry that owns canonical path/variant identities and evicts entries only through explicit ownership removal, inactivity sweeps, or recorded-byte cache trimming, replacing Carbon's weak-live/strong-cache ownership transition.
+
+- Export: `@carbonenginejs/runtime-resource`
+- Source: `src/CjsMotherLode.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:CjsResMan -->
+## `CjsResMan`
+
+GPU-free resource manager that resolves paths through registered sources and formats, publishes canonical resources into a `CjsMotherLode` registry under exact-owner generation guards, and drives the main/background work queues, read-operation caching, reload staging, and automatic purge policy.
+
+- Export: `@carbonenginejs/runtime-resource`
+- Source: `src/CjsResMan.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:CjsResManWorkQueue -->
+## `CjsResManWorkQueue`
+
+Small FIFO executor used inside `CjsResMan` that tracks item ids, pause state, concurrency, cancellation, and sync/async completion while queue policy stays in the manager.
+
+- Export: None
+- Source: `src/CjsResManQueue.js`
+- Visibility: Internal
+- Kind: Internal implementation class
+
+<!-- class:CjsResource -->
+## `CjsResource`
+
+Base runtime resource handle that carries normalized path/extension/requirement identity, load state, and an attached CPU payload, with manager lifecycle callbacks supplied by `CjsResMan` after canonical insertion.
+
+- Export: `@carbonenginejs/runtime-resource`
+- Source: `src/CjsResource.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:CjsMemoryResourceSource -->
+## `CjsMemoryResourceSource`
+
+In-memory resource source that maps normalized resource paths to preset values and serves them to reads without any I/O.
+
+- Export: `@carbonenginejs/runtime-resource`
+- Source: `src/CjsResourceSource.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class
+
+<!-- class:CjsFetchResourceSource -->
+## `CjsFetchResourceSource`
+
+Resource source that resolves a normalized path against an optional base URL and reads response bytes through an injected fetch implementation.
+
+- Export: `@carbonenginejs/runtime-resource`
+- Source: `src/CjsResourceSource.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class
+
+<!-- class:CjsBlueReader -->
+## `CjsBlueReader`
+
+Shared output and hydration backend for Blue persistence readers that owns common payload/runtime targets, reference emission, hydration adapter phases, reports, finalization, and schema-descriptor helpers, while transports keep framing and member decoding.
+
+- Export: None
+- Source: `src/format/CjsBlueReader.js`
+- Visibility: Internal
+- Kind: Internal implementation class
+
+<!-- class:CjsFormat -->
+## `CjsFormat`
+
+Base class for format readers that defines the static `read`/`readAsync`/`isSupported`/`resolveType` contract and instance option handling that concrete format packages implement.
+
+- Export: `@carbonenginejs/runtime-resource`
+- Source: `src/format/CjsFormat.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class
+
+<!-- class:CjsReader -->
+## `CjsReader`
+
+Internal base for construction-bound readers that are created for one source and dropped after use, relying on garbage collection instead of explicit dispose/clear cleanup.
+
+- Export: None
+- Source: `src/format/CjsReader.js`
+- Visibility: Internal
+- Kind: Internal implementation class
+
+<!-- class:CjsResourceProbe -->
+## `CjsResourceProbe`
+
+Standard probe-report model that formats return from inspection, recording support status, content-verification state, confidence, preferred route, capability variants, warnings, and errors without choosing an engine or media backend.
+
+- Export: `@carbonenginejs/runtime-resource`
+- Source: `src/format/CjsResourceProbe.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class

package/docs/reference/classes/dropped.md

@@ -0,0 +1,46 @@
+# Dropped class catalog
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource` classes under `src/dropped`  
+Audience: Users, maintainers, and automated readers  
+Summary: Provides one-sentence purpose descriptors for retained-only Carbon reference shapes that are never exported or bundled.
+
+<!-- class:CmfVertexReader -->
+## `CmfVertexReader`
+
+Retained-only reference shape mirroring Carbon's CMF vertex-element pointer-lookup helper, superseded by the JavaScript CMF format's channel decoding.
+
+- Export: None
+- Source: `src/dropped/CmfVertexReader.js`
+- Visibility: Internal
+- Kind: Faithful Carbon port
+
+<!-- class:Tr2AsyncSave -->
+## `Tr2AsyncSave`
+
+Retained-only reference shape mirroring Carbon's abstract prepare/save callback base, superseded by promise-based format `Write`/`WriteAsync` operations and resource-level save-status compatibility methods.
+
+- Export: None
+- Source: `src/dropped/Tr2AsyncSave.js`
+- Visibility: Internal
+- Kind: Faithful Carbon port
+
+<!-- class:Tr2CmfContents -->
+## `Tr2CmfContents`
+
+Retained-only reference shape mirroring Carbon's native CMF section lifetime and decompression holder, superseded by `CjsCmfFormat`'s bounded section access and typed-array data.
+
+- Export: None
+- Source: `src/dropped/Tr2CmfContents.js`
+- Visibility: Internal
+- Kind: Faithful Carbon port
+
+<!-- class:Tr2LoadPrepareFence -->
+## `Tr2LoadPrepareFence`
+
+Retained-only reference shape mirroring Carbon's two-queue load/prepare fence helper, superseded by the snapshot-fence contract owned by `CjsResMan.Wait()`.
+
+- Export: None
+- Source: `src/dropped/Tr2LoadPrepareFence.js`
+- Visibility: Internal
+- Kind: Faithful Carbon port