@carbonenginejs/runtime-resource 0.12.1 → 0.13.0

package/docs/reference/classes/texture.md

@@ -1,26 +1,26 @@
-# Texture class catalog
-
-Status: Evolving  
-Scope: `@carbonenginejs/runtime-resource` classes under `src/resource/texture`
-Audience: Users, maintainers, and automated readers  
-Summary: Provides one-sentence purpose descriptors for the texture-array aggregation classes in src/resource/texture.
-
-<!-- class:CjsTextureArrayRes -->
-## `CjsTextureArrayRes`
-
-Mutable runtime aggregate resource for an ordered texture-array request that coalesces per-layer path changes and invalidations so a resource manager or engine scheduler can prepare the corresponding immutable texture-array payload on a later frame.
-
-- Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resource/texture/CjsTextureArrayRes.js`
-- Visibility: Public
-- Kind: Original CarbonEngineJS class
-
-<!-- class:CjsTextureArrayResParameterProxy -->
-## `CjsTextureArrayResParameterProxy`
-
-`CjsTextureArrayRes`-owned parameter facade for one array layer that mirrors the public path API while delegating storage, invalidation, readiness, and adapter ownership to its parent, carrying no shader metadata or backend objects itself.
-
-- Export: `@carbonenginejs/runtime-resource`
-- Source: `src/resource/texture/CjsTextureArrayResParameterProxy.js`
-- Visibility: Public
-- Kind: Original CarbonEngineJS class
+# Texture class catalog
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource` classes under `src/resource/texture`
+Audience: Users, maintainers, and automated readers  
+Summary: Provides one-sentence purpose descriptors for the texture-array aggregation classes in src/resource/texture.
+
+<!-- class:CjsTextureArrayRes -->
+## `CjsTextureArrayRes`
+
+Mutable runtime aggregate resource for an ordered texture-array request that coalesces per-layer path changes and invalidations so a resource manager or engine scheduler can prepare the corresponding immutable texture-array payload on a later frame.
+
+- Export: `@carbonenginejs/runtime-resource`
+- Source: `src/resource/texture/CjsTextureArrayRes.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class
+
+<!-- class:CjsTextureArrayResParameterProxy -->
+## `CjsTextureArrayResParameterProxy`
+
+`CjsTextureArrayRes`-owned parameter facade for one array layer that mirrors the public path API while delegating storage, invalidation, readiness, and adapter ownership to its parent, carrying no shader metadata or backend objects itself.
+
+- Export: `@carbonenginejs/runtime-resource`
+- Source: `src/resource/texture/CjsTextureArrayResParameterProxy.js`
+- Visibility: Public
+- Kind: Original CarbonEngineJS class

package/docs/reference/events.md

@@ -1,117 +1,117 @@
-# Event emitter contract
-
-Status: Evolving  
-Scope: `@carbonenginejs/runtime-resource`  
-Audience: Users and integrators  
-Summary: Defines the `CjsEventEmitter` API surface used by resource managers and the memory rules that keep listeners from leaking graphs.
-
-## Purpose
-
-`CjsEventEmitter` (from `runtime-utils/model`) is a separate base class so
-non-model runtime services can emit events without extending `CjsModel`;
-`CjsResMan` uses that path. CarbonEngineJS exposes one small event-emitter API
-and avoids short generic names such as `On`, `Once`, `Off`, and `Emit` on
-Carbon-shaped classes. There is no separate resource notification/callback
-compatibility layer beside events, and no listener scopes, subscription
-handles, or owner-side `ListenTo()` helpers.
-
-## API
-
-- `AddEvents(events)`
-- `OnEvent(eventName, listener, source?)`
-- `OnceEvent(eventName, listener, source?)`
-- `OffEvent(eventName = "*", listener?, source?)`
-- `EmitEvent(eventName, ...args)`
-- `HasEvent(eventName = "*", listener?, source?)`
-- `ClearEvent(eventName = "*")`
-- `GetEventNames()` and `GetEventListenerCount(eventName = "*")`
-
-The optional `source` is the callback's `this` value and an explicit matching
-identity for removal. Mutating event methods return the emitter for chaining.
-Event names are normalized to lowercase and dispatched by exact match.
-Wildcard names are accepted only by lookup and cleanup methods; there is no
-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
-`__state` object:
-
-```text
-emitter.__state (non-enumerable, allocated only when some subsystem needs it)
-  events -> eventName -> Set<listenerRecord>
-
-listenerRecord
-  emitter
-  eventName
-  listener
-  source
-  once
-```
-
-The event map is created only when the first listener is registered and
-deleted when the last record is removed. That does not make listeners weak:
-as long as an emitter is reachable, its event map strongly references
-listener functions and sources, and those listeners can keep whole
-scene/resource graphs alive. The contract is therefore:
-
-- `OnceEvent()` removes the listener on first dispatch, even if the callback
-  throws.
-- `OffEvent(eventName, listener, source)` removes the exact listener/source
-  entry; `target.OffEvent("*", null, source)` removes all of a source's
-  records. An external party that no longer observes a target must call
-  `OffEvent()`.
-- `Unload()` and `Purge()` are resource state/cache operations, not an
-  implied listener-destruction lifecycle.
-- `OnEvent()` returns the emitter; it does not return unsubscribe closures,
-  because those closures create another reference path.
-- Deterministic cleanup is the contract; `WeakRef`/`FinalizationRegistry` may
-  help diagnostics but are not a lifecycle mechanism.
-
-Multiple listeners on the same event are allowed because each event bucket is
-a set of records. A raw `CjsEventEmitter` does not gain model-owned `dirty`
-or `rebuild` state. The target is "easy to debug, hard to leak": clear
-ownership of who subscribed, who unsubscribes, and which cleanup phase clears
-remaining listeners.
-
-## Relationship to model dirty state
-
-`CjsModel` has dirty-state helpers (`MarkDirty`, `ClearDirty`, `ConsumeDirty`,
-`GetDirtyNotifications`) for model invalidation. `SetValues()` compares
-incoming values with the current field values and only marks dirty when a
-value actually changes. A plain `MarkDirty()` means broad dirty invalidation;
-it does not request a rebuild, and deferred rebuild reasons belong to the
-independent `model.__state.rebuild` set. That model machinery is not a
-resource lifecycle event system; resource lifecycle events remain a
-resource/resman concern.
-
-## Related documentation
-
-- [MotherLode identity, cache, and retention](motherlode-cache.md)
+# Event emitter contract
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource`  
+Audience: Users and integrators  
+Summary: Defines the `CjsEventEmitter` API surface used by resource managers and the memory rules that keep listeners from leaking graphs.
+
+## Purpose
+
+`CjsEventEmitter` (from `runtime-utils/model`) is a separate base class so
+non-model runtime services can emit events without extending `CjsModel`;
+`CjsResMan` uses that path. CarbonEngineJS exposes one small event-emitter API
+and avoids short generic names such as `On`, `Once`, `Off`, and `Emit` on
+Carbon-shaped classes. There is no separate resource notification/callback
+compatibility layer beside events, and no listener scopes, subscription
+handles, or owner-side `ListenTo()` helpers.
+
+## API
+
+- `AddEvents(events)`
+- `OnEvent(eventName, listener, source?)`
+- `OnceEvent(eventName, listener, source?)`
+- `OffEvent(eventName = "*", listener?, source?)`
+- `EmitEvent(eventName, ...args)`
+- `HasEvent(eventName = "*", listener?, source?)`
+- `ClearEvent(eventName = "*")`
+- `GetEventNames()` and `GetEventListenerCount(eventName = "*")`
+
+The optional `source` is the callback's `this` value and an explicit matching
+identity for removal. Mutating event methods return the emitter for chaining.
+Event names are normalized to lowercase and dispatched by exact match.
+Wildcard names are accepted only by lookup and cleanup methods; there is no
+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
+`__state` object:
+
+```text
+emitter.__state (non-enumerable, allocated only when some subsystem needs it)
+  events -> eventName -> Set<listenerRecord>
+
+listenerRecord
+  emitter
+  eventName
+  listener
+  source
+  once
+```
+
+The event map is created only when the first listener is registered and
+deleted when the last record is removed. That does not make listeners weak:
+as long as an emitter is reachable, its event map strongly references
+listener functions and sources, and those listeners can keep whole
+scene/resource graphs alive. The contract is therefore:
+
+- `OnceEvent()` removes the listener on first dispatch, even if the callback
+  throws.
+- `OffEvent(eventName, listener, source)` removes the exact listener/source
+  entry; `target.OffEvent("*", null, source)` removes all of a source's
+  records. An external party that no longer observes a target must call
+  `OffEvent()`.
+- `Unload()` and `Purge()` are resource state/cache operations, not an
+  implied listener-destruction lifecycle.
+- `OnEvent()` returns the emitter; it does not return unsubscribe closures,
+  because those closures create another reference path.
+- Deterministic cleanup is the contract; `WeakRef`/`FinalizationRegistry` may
+  help diagnostics but are not a lifecycle mechanism.
+
+Multiple listeners on the same event are allowed because each event bucket is
+a set of records. A raw `CjsEventEmitter` does not gain model-owned `dirty`
+or `rebuild` state. The target is "easy to debug, hard to leak": clear
+ownership of who subscribed, who unsubscribes, and which cleanup phase clears
+remaining listeners.
+
+## Relationship to model dirty state
+
+`CjsModel` has dirty-state helpers (`MarkDirty`, `ClearDirty`, `ConsumeDirty`,
+`GetDirtyNotifications`) for model invalidation. `SetValues()` compares
+incoming values with the current field values and only marks dirty when a
+value actually changes. A plain `MarkDirty()` means broad dirty invalidation;
+it does not request a rebuild, and deferred rebuild reasons belong to the
+independent `model.__state.rebuild` set. That model machinery is not a
+resource lifecycle event system; resource lifecycle events remain a
+resource/resman concern.
+
+## Related documentation
+
+- [MotherLode identity, cache, and retention](motherlode-cache.md)