@carbonenginejs/runtime-resource 0.9.0 → 0.9.2

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