@carbonenginejs/runtime-resource 0.11.1 → 0.12.1

package/docs/formats/wwise.md

@@ -16,20 +16,36 @@ manager behavior, or decoded-backend retention.
 
 `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:
+lists, action type/target, sound and music-track source ids). For bank
+generator version 150, recognized Event Actions additionally expose exact
+scope/mode, property and range bundles, delay/transition/probability values,
+fade and action flags, exceptions, and Play bank identities. The
+Wwise-domain toolkit is grouped under the `CjsBnkFormat.wwise` static: the
+SoundbanksInfo catalog helpers, the FNV-1 id hash, event-to-media resolution,
+typed Event Actions, and typed authored-SFX nodes:
 
 ```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 action = CjsBnkFormat.wwise.parseEventAction(actionPayload, {
+    bankVersion: 150
+});
 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 {
+    nodes,
+    nodeBases,
+    actorMixers,
+    attenuations,
+    events,
+    actions,
+    diagnostics
+} = CjsBnkFormat.wwise.sfxNodesFromBanks(inspections);
+
 const ogg = CjsWemFormat.toOgg(wemBytes);   // Wwise Vorbis -> Ogg (lossless)
 const pcm = CjsWemFormat.toPcm(wemBytes);   // PTADPCM / 16-bit PCM -> float32
 ```
@@ -38,6 +54,31 @@ 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.
 
+The undecoded-container ID scan used by `eventMediaFromBanks` is diagnostic
+reachability, not an authoritative playback program. Consumers requiring
+audible correctness should use the typed `sfxNodesFromBanks` graph and fail
+closed for unsupported events.
+
+Typed authored-SFX tail decoding is deliberately pinned to bank generator
+version 150. Recognized Event Actions are accepted only when the whole body
+is consumed; unknown, truncated, other-version, or trailing-byte bodies retain
+their shallow action type/target and raw payload, with `action: null`.
+`nodes` contains playable Sound, Random/Sequence, Switch/State, and Layer
+objects. The separate `nodeBases` map preserves common authored properties
+and positioning facts for playable nodes and Actor-Mixers.
+`actorMixers` contains HIRC type 7 hierarchy objects; they are inheritance
+parents, not playable parallel containers. `attenuations` contains raw HIRC
+type 14 cone data, signed curve-slot assignments, graph points, and RTPCs
+without assigning application meaning to a curve.
+
+Unsupported versions, failed exact-end anchors, ambiguities, NodeBase
+failures, and duplicate object identities are reported through `diagnostics`
+instead of being guessed. Consumers may resolve hierarchy and project
+runtime-specific metadata from these raw facts. In particular, this format
+layer does not infer a numeric maximum radius from an attenuation curve. Like
+`eventMediaFromBanks`, `sfxNodesFromBanks` is consumer-facing graph
+interpretation; the resource lifecycle never calls it.
+
 ## Related documentation
 
 - [Format subpaths](README.md)

package/docs/reference/classes/core.md

@@ -115,6 +115,86 @@ Internal base for construction-bound readers that are created for one source and
 - Visibility: Internal
 - Kind: Internal implementation class
 
+<!-- class:CjsFormatReadError -->
+## `CjsFormatReadError`
+
+Error raised when shared binary format bytes cannot be decoded safely.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/CjsFormatError.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class
+
+<!-- class:CjsFormatWriteError -->
+## `CjsFormatWriteError`
+
+Error raised when shared binary format bytes cannot be encoded safely.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/CjsFormatError.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class
+
+<!-- class:CjsByteReader -->
+## `CjsByteReader`
+
+Little-endian cursor over resource bytes, with optional string-table arena resolution.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/CjsByteReader.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class
+
+<!-- class:CjsByteWriter -->
+## `CjsByteWriter`
+
+Growable little-endian append cursor with reserve-and-patch support.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/CjsByteWriter.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class
+
+<!-- class:CjsStringTable -->
+## `CjsStringTable`
+
+Carbon's compiled-effect string table: a deduplicated blob arena whose offsets are assigned by a bytewise sort rather than by insertion order.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/CjsStringTable.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:CjsCarbonEffectBodyReader -->
+## `CjsCarbonEffectBodyReader`
+
+Plain byte cursor over one description blob, carrying the Carbon effect error class and message.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/carbonEffect/CjsCarbonEffectReader.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:CjsCarbonEffectReader -->
+## `CjsCarbonEffectReader`
+
+Reader for Carbon's compiled-effect container at version 15.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/carbonEffect/CjsCarbonEffectReader.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
+<!-- class:CjsCarbonEffectWriter -->
+## `CjsCarbonEffectWriter`
+
+Builder for a Carbon compiled-effect container.
+
+- Export: `@carbonenginejs/runtime-resource/format`
+- Source: `src/format/carbonEffect/CjsCarbonEffectWriter.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept
+
 <!-- class:CjsResourceProbe -->
 ## `CjsResourceProbe`
 

package/docs/reference/classes/formats.md

@@ -79,6 +79,26 @@ Little-endian byte cursor over HIRC payload bytes used to decode Wwise interacti
 - Visibility: Internal
 - Kind: Internal implementation class
 
+<!-- class:WwiseCursor -->
+## `WwiseCursor`
+
+Bounds-aware little-endian cursor used for exact Wwise v150 NodeBase, authored-SFX, and attenuation decoding.
+
+- Export: `None`
+- Source: `src/formats/bnk/core/nodeBase.js`
+- Visibility: Internal
+- Kind: Internal implementation class
+
+<!-- class:ActionCursor -->
+## `ActionCursor`
+
+Bounds-aware byte cursor used for exact Wwise v150 Event Action decoding.
+
+- Export: `None`
+- Source: `src/formats/bnk/core/eventAction.js`
+- Visibility: Internal
+- Kind: Internal implementation class
+
 ### cmf
 
 <!-- class:CjsCmfFormat -->
@@ -285,16 +305,6 @@ Runtime GR2/GSF format class that wraps the migrated `format-gr2` engine under c
 - Visibility: Public
 - Kind: Original CarbonEngineJS class
 
-<!-- class:CjsFormatGr2 -->
-## `CjsFormatGr2`
-
-Migrated GR2/GSF reader that parses Granny files with section decompression, reflected type-tree walking, JSON emission, curve decompression, and caller-class hydration through its core helper modules.
-
-- Export: `@carbonenginejs/runtime-resource/formats/gr2`
-- Source: `src/formats/gr2/core/CjsFormatGr2.js`
-- Visibility: Public
-- Kind: Original CarbonEngineJS class
-
 <!-- class:Decoder -->
 ## `Decoder`
 
@@ -843,33 +853,13 @@ WebGPU shader format profile that translates compiled Carbon effects into CEWGPU
 - Visibility: Public
 - Kind: Original CarbonEngineJS class
 
-<!-- class:CewgpuPackage -->
-## `CewgpuPackage`
-
-Reader for the flat CEWGPU container: chunk lookup, cached JSON decoding, and gated portable reflection and backend program access.
-
-- Export: `None`
-- Source: `src/formats/webgpu/core/cewgpu/CewgpuPackage.js`
-- Visibility: Internal
-- Kind: Internal implementation class
-
-<!-- class:CewgpuPackageBuilder -->
-## `CewgpuPackageBuilder`
-
-Builds a CEWGPU container from ordered, uniquely tagged chunks.
-
-- Export: `None`
-- Source: `src/formats/webgpu/core/cewgpu/CewgpuPackageBuilder.js`
-- Visibility: Internal
-- Kind: Internal implementation class
-
-<!-- class:WebgpuReader -->
-## `WebgpuReader`
+<!-- class:CewgpuContainer -->
+## `CewgpuContainer`
 
-Bounded little-endian byte cursor over CEWGPU container bytes.
+Reader over one WebGPU effect container.
 
 - Export: `None`
-- Source: `src/formats/webgpu/core/cewgpu/binary.js`
+- Source: `src/formats/webgpu/core/cewgpu/CewgpuContainer.js`
 - Visibility: Internal
 - Kind: Internal implementation class
 

package/docs/reference/events.md

@@ -34,6 +34,31 @@ wildcard listener dispatch, no `family.event` or ancestor routing, and no
 event payload history. Resource classes may emit their own state or domain
 events, but the emitter does not invent a resource lifecycle contract.
 
+## Resource lifecycle events
+
+`CjsResource.SetState()` supplies the resource-specific lifecycle contract. A
+state transition emits, in order:
+
+1. the lowercase state name with `(resource, ...details)`;
+2. `statechange` with `(resource, nextState, previousState)`; and
+3. `completed` with `(resource, ...details)` when the new state is
+   `prepared` or `failed`.
+
+`purged` is deliberately not completion. A purged handle may re-register and
+reload itself into the same identity, and listeners are not cleared by purge.
+A listener that remains registered for `completed` can therefore observe the
+initial outcome and a later purge/reload outcome.
+
+Raw `OnEvent()` and `OnceEvent()` never replay event history. The one
+state-aware registration helper is `CjsResource.OnCompleted(listener,
+source?)`: it calls the listener synchronously and stores nothing when the
+resource is already complete; otherwise it registers a persistent
+`completed` listener. This is the canonical check-then-subscribe operation for
+late consumers. A listener satisfied synchronously will not observe a later
+reload unless it explicitly subscribes again. Use `Ready()`/`GetObject()` when
+the caller needs a promise for the current load operation rather than a
+re-enterable lifecycle observer.
+
 ## Memory rules
 
 Event storage is the optional `events` member of the emitter's non-enumerable

package/docs/reference/motherlode-cache.md

@@ -27,6 +27,12 @@ create a hidden second resource; reset the affected identity
 (`Delete`/`Clear`) or create a new manager. A changed output contract must use
 a new tag such as `@cmf2`.
 
+Do not restore a hidden execution-plan identity through function fingerprints,
+arbitrary option serialization, `buildKey`, or `buildVersion`. Those details
+cannot create a second canonical resource behind the same public path/output
+promise. A materially different promised result requires an explicit output
+tag.
+
 ## Ownership and replacement
 
 `CjsResMan` resolves each normalized path and promised output to one canonical
@@ -117,10 +123,16 @@ resource.ReleasePayload()
 `CjsResMan` binds resource-facing `KeepAlive()`, `KeepPayloadAlive()`,
 `Lock()`, and `Unlock()` to the resource's canonical MotherLode key.
 `SetPayload()` renews both identity and payload activity when it publishes a
-non-null payload. `GetPayload()`, `HasPayload()`, `IsGood()`, and other
-queries are pure; reading the payload does not implicitly renew its lease.
-Detached and purged handles retain deterministic no-op liveness methods rather
-than silently starting work.
+non-null payload. `GetPayload()`, `HasPayload()`, `IsPrepared()`, and other
+state/payload queries are pure; reading the payload does not implicitly renew
+its lease. `IsGood()` is the deliberate exception: it calls `KeepAlive()`,
+renewing this handle and starting its bounded reload path when it is `PURGED`.
+It does not recursively traverse or renew child resources.
+
+A handle detached by ordinary ownership removal has no live MotherLode
+controller. A purged handle retains the reload hook needed to re-register and
+refill that exact handle, so `IsGood()`/`KeepAlive()` can recover it as
+described under [Ownership and replacement](#ownership-and-replacement).
 
 A released CPU payload retains only the small request needed to reconstruct
 that same path/output from its source and `sourceRevision`. The retained
@@ -249,10 +261,12 @@ operation is still active. Lock release is conditional on the same captured
 ownership generation, so stale work cannot decrement a newly rebound handle's
 lock. Scheduling and active-work protection do not fetch or reload data.
 
-Cache trimming and automatic inactivity sweeps retain the strict no-reload
-rule. Application retention defaults, automatic resource/payload byte
-estimation, separate CPU/adapter budgets, and purged-resource/device-loss
-recovery policy are future work; see the [roadmap](../roadmap.md).
+Cache trimming and automatic inactivity sweeps never fetch or reload as part
+of the sweep itself. A later `IsGood()`/`KeepAlive()` call may recover the
+purged handle through its bounded reload path. Application retention defaults,
+automatic resource/payload byte estimation, and separate CPU/adapter budgets
+remain future work; backend device-loss recovery belongs to the engine
+realization contract. See the [roadmap](../roadmap.md).
 
 ## Related documentation
 

package/docs/reference/workers.md

@@ -82,10 +82,10 @@ invent offset semantics.
 A clone-safe format opts in with a static worker declaration:
 
 ```js
-static worker = Object.freeze({
+static worker = {
   module: import.meta.url,
   exportName: "CjsExampleFormat"
-});
+};
 ```
 
 The worker dynamically imports that exact module and invokes its static
@@ -98,12 +98,12 @@ their class identity.
 A declaration may restrict clone-safe outputs:
 
 ```js
-static worker = Object.freeze({
+static worker = {
   module: import.meta.url,
   exportName: "CjsExampleFormat",
-  outputTypes: Object.freeze([ "json", "payload" ]),
+  outputTypes: [ "json", "payload" ],
   defaultOutput: "json"
-});
+};
 ```
 
 Format options containing functions, symbols, non-plain instances, cycles, or

package/docs/roadmap.md

@@ -3,9 +3,10 @@
 Status: Evolving  
 Scope: `@carbonenginejs/runtime-resource`  
 Audience: Integrators and maintainers  
-Summary: Records approved future direction and open design questions; nothing on this page is implemented.
+Summary: Records approved future direction, open design questions, and the current shader-format boundary needed to interpret that direction.
 
-Everything below is future work. Current behavior is documented in the
+Unless a section is explicitly marked **Current**, everything below is future
+work. Current behavior is documented in the
 [reference pages](reference/motherlode-cache.md); where this page and a
 reference page disagree, the reference page describes the shipped package.
 
@@ -23,16 +24,18 @@ resource preparation abstraction:
 - automatic resource/payload byte estimation and separate CPU/adapter
   budgets;
 - additional browser-source response types and configurable worker-pool
-  concurrency;
-- purged-resource/device-loss recovery policy (backend device-loss recovery
-  belongs to the engine's realization operation).
+  concurrency.
 
 ## Browser shader formats
 
-The HLSL, DXBC, WebGL, and WebGPU format packages are expected to migrate into
-runtime-resource as independently exported format entry points. HLSL and DXBC
-remain directly usable; WebGL and WebGPU may compose them to read DX11/DX12
-effect inputs and translate them in the browser.
+**Current:** HLSL, DXBC, WebGL, and WebGPU are consolidated into
+runtime-resource and exposed as independently importable
+`@carbonenginejs/runtime-resource/formats/<name>` entry points. HLSL and DXBC
+remain directly usable; WebGL and WebGPU compose them to read DX11/DX12 effect
+inputs and translate them.
+
+**Planned:** Browser delivery and fallback policy still needs a stable
+application-facing contract.
 
 Browser-targeted production modules must not import or require Node-only
 shader libraries. A format package may use local Node libraries as development
@@ -41,7 +44,7 @@ those libraries must not ship and must not be runtime dependencies.
 
 ccpwgl currently preserves an authored `.fx` path while `Tw2Device` maps it to
 a backend-specific remote namespace such as `effect.gles2` or `effect.webgl2`
-and appends the selected shader-model extension. The migrated resource/format
+and appends the selected shader-model extension. The resource/format
 contract must retain both use cases:
 
 - resolve and load a pretranslated backend artifact from a remote resource
@@ -52,32 +55,52 @@ The authored effect path should remain the stable identity. Backend profile,
 shader model, translated cache path, and translation capabilities are
 resolution facts rather than changes a caller must make to its source path.
 
-## Pre-adoption lifecycle API cleanup (approved, not implemented)
-
-No released consumer currently depends on the ccpwgl-compatible liveness
-names; the known ccpwgl format integrations are migration targets rather than
-a reason to preserve them. Before runtime-core or another public consumer
-adopts this contract, remove `KeepAlive()` and `KeepPayloadAlive()` instead
-of retaining or deprecating compatibility aliases.
-
-The public lifecycle should express caller intent directly:
-
-- `Ready()` obtains or reconstructs the CPU payload;
-- `AcquireLock()` returns a scoped hard-retention token;
-- `ReleasePayload()` explicitly drops the CPU payload; and
-- state queries remain pure.
-
-ResMan should update identity activity when a canonical resource is acquired
-and payload activity when it publishes or returns a ready payload. Those
-timestamps are cache-policy implementation details, not calls consumers
-should have to make. Cache admission and promotion must also be explicit
-manager operations: merely accessing a resource must not permanently move it
-from the byte-budget candidate set into an unbudgeted live set.
-
-Do not add `TouchIdentity()` or `TouchPayload()` to the initial public API
-unless a concrete soft-retention consumer appears. A consumer that needs a
-residency guarantee should acquire a lock; one that merely uses a resource
-should call `Ready()` and allow the configured cache policy to operate.
+## Format buffer ownership and destination reuse
+
+**Current:** The CMF, DDS, FBX, GIF, glTF, JPEG, MP3, MP4, Ogg, PNG, STL,
+TGA, WAV, WebM, and WebP byte normalizers preserve an existing `Uint8Array`.
+`ArrayBuffer` and other byte-addressable views are exposed through a
+`Uint8Array` view over the same backing storage rather than copied merely for
+input normalization. Decode operations that produce new pixel, sample,
+geometry, or decompression payloads currently allocate those result arrays
+internally. Resource payload references are shared read-only by default;
+[MotherLode retention](reference/motherlode-cache.md) defines the cases where
+a consumer must make an explicit copy.
+
+**Planned:** Known-size decode and transform operations should gain
+format-specific optional destination-array seams. Omitting the destination
+must preserve the convenient allocating call. Supplying a valid destination
+must fill and return that exact object. Each seam must:
+
+- require the correct typed-array kind and sufficient capacity before writing;
+- support non-zero-offset input and destination views;
+- leave input unchanged unless the operation explicitly documents an
+  in-place transform;
+- produce the same bytes and typed-array kind as the allocating form; and
+- behave deterministically when one destination is reused across sequential
+  calls.
+
+The first candidates are CMF decompression, FBX inflate and packed-array
+helpers, DDS block and uncompressed decoders, PNG row/RGBA decode, JPEG
+component and final RGBA output, TGA RGBA decode, GIF compositing canvas, WAV
+PCM decode, and glTF data-URI decode. Decoder workspaces such as JPEG
+coefficient blocks, cached lookup tables, CRC tables, and small fixed scratch
+arrays remain implementation-owned rather than becoming public output
+arguments.
+
+Some copies remain necessary: mutation of otherwise shared data,
+`ArrayBuffer` transfer/detachment, compacting a small retained range out of a
+large backing buffer, immutable frame history, and platform APIs that expose
+no destination seam. Those copies should stay explicit at the owning call
+site. This direction does not introduce a generic deep-copy operation for
+payload objects or typed-array bundles.
+
+## Scoped lock token
+
+**Planned:** add `AcquireLock()` as an async-safe wrapper around the current
+`Lock()`/`Unlock()` contract. Existing `KeepAlive()` and
+`KeepPayloadAlive()` behavior remains current package API; this roadmap does
+not propose removing it.
 
 Raw `Lock()` / `Unlock()` is easy to mis-pair across asynchronous success,
 failure, cancellation, and disposal. Prefer a JS-only acquired-lock API:
@@ -118,11 +141,8 @@ built from explicit tokens, not an implicit default on every loaded resource.
   buffers?
 - Should manually attached/dynamic resources default to locked, like ccpwgl's
   manual shader resources use `doNotPurge`?
-- What explicit `Reload()`/reconstruction API should restore purged resources
-  without introducing surprising browser or network work?
-- A resource-level `Purge()`/`Reload()` vocabulary remains future policy
-  work, as does whether `Unload()` should release engine adapter resources
-  and optionally CPU payloads.
+- Should a resource-level `Purge()` complement the existing automatic and
+  MotherLode-level eviction operations?
 
 ## Related documentation
 

package/format-notices/bnk/NOTICE

@@ -9,10 +9,11 @@ Wwise and the Wwise soundbank format are property of Audiokinetic Inc.
 
 This reader is original CarbonEngineJS code authored directly in
 runtime-resource; no legacy package was copied. The soundbank chunk layout,
-HIRC object field layouts, and the event-graph resolution exposed as
-`eventMediaFromBanks` were implemented from publicly documented community
-knowledge of the format (ww2ogg, vgmstream, wwiser documentation) and
-independently verified by hexdump against EVE Online soundbanks (bank
+HIRC object field layouts, the event-graph resolution exposed as
+`eventMediaFromBanks`, and the typed version-150 authored-SFX node tails
+exposed as `sfxNodesFromBanks` were implemented from publicly documented
+community knowledge of the format (ww2ogg, vgmstream, wwiser documentation)
+and independently verified by hexdump against EVE Online soundbanks (bank
 generator version 150); no code was copied from those projects and no
 Audiokinetic SDK material was used.
 Audiokinetic, CarbonEngine, and Fenris Creations (CCP Games) are mentioned for

package/format-notices/webgl/NOTICE

@@ -9,7 +9,7 @@ Contains no Microsoft, CarbonEngine, or Fenris Creations (CCP Games) code. The C
 four-byte-tagged chunk layout: `INFO`/`META`/`GLSL`/...) is a CarbonEngineJS
 invention, not a Microsoft, CarbonEngine, or Fenris Creations (CCP Games) one. The DXBC token-stream layout follows
 Microsoft's public d3d11TokenizedProgramFormat documentation (consumed here
-only through `@carbonenginejs/format-dxbc`'s public format; this package
+only through the sibling `formats/dxbc` public format; this format
 decodes no DXBC bytes itself). Unity Technologies' HLSLcc (MIT) was used as
 a behavioral reference while auditing the GLSL lowering rules this emitter
 implements; no HLSLcc source is included in this repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbonenginejs/runtime-resource",
-  "version": "0.11.1",
+  "version": "0.12.1",
   "description": "CarbonEngineJS resource lifecycle, cache, source, and object loading contracts.",
   "type": "module",
   "exports": {
@@ -12,6 +12,7 @@
     "./resource/shader": "./dist/resource/shader/index.js",
     "./resource/texture": "./dist/resource/texture/index.js",
     "./worker": "./dist/worker/CjsResManWorker.js",
+    "./format": "./dist/format/index.js",
     "./formats": "./dist/formats/index.js",
     "./formats/black": "./dist/formats/black/index.js",
     "./formats/black/schema": "./dist/formats/black/core/blackSchema.js",