armature

Additive release: new public APIs on Task and Cleanup. No breaking changes — ^0.3.0 consumers can adopt without code modifications.

Added

• Task.reset() — public method that returns a task to TaskIdle from any sticky state (TaskDone / TaskFailed). Supersedes any in-flight run via a generation token (state writes from older runs drop), cancels strategy-internal timers (debounce quiet timer, throttle cooldown / window), rejects coalesced callers from .latest / .debounce / .throttle(trailing) with TaskError, and clears the .once cache so the next call re-executes the fn. Silent no-op after dispose and from TaskIdle.
• autoReset: Duration? parameter on Store.createTask / Store.createVoidTask — schedules an automatic transition back to TaskIdle after the given duration in TaskDone / TaskFailed. The internal timer cancels and re-arms on every state transition, so a fresh call() while the timer is waiting starts a new lifecycle without flickering through TaskIdle. Cancelled in dispose() and on manual reset().
• Cleanup.subscribe(store, listener, {fireImmediately}) — sugar for cleanup.add(store.subscribe(listener, ...)).
• Cleanup.periodic(duration, callback) — wraps Timer.periodic and auto-cancels the timer on deactivation.
• Cleanup.listen(stream, onData, {onError, onDone, cancelOnError}) — wraps Stream.listen(...) and auto-cancels the subscription on deactivation.

Changed

• CleanupBag now extends Cleanup (was implements Cleanup) so the new sugar helpers are inherited. Late-add semantics on the sealed bag are preserved — sugar methods route through add().
• TaskError doc clarifies that the same error is also surfaced through pending futures when Task.reset() cancels coalesced callers (previously documented only for dispose).
• README and Store.createTask docstring gain a "Picking TError" guide (Exception / domain class / Never / Object) explaining which thrown values land in TaskFailed vs propagate.

Internal

• _latestRunId generalised into a cross-strategy _generation supersession token. Every async path (_executeFn / _runLatest / _fireDebounced / _fireThrottleTrailing) captures the token at entry and skips state writes / completer settles when the captured value no longer matches.
• Extracted _supersedeInFlight helper shared between dispose and reset for strategy-state teardown (timer cancel, completer rejection, queue / debounce / throttle buffer clear).

• FIX: per-container feature runtime — top-level createFeature(...) instances no longer carry mutable runtime state. Scope API, status store, cleanup bags, ownActive, toggle, and bound FeatureParentApi now live in a per-AppContainer FeatureRuntime. Two concurrent or sequentially-remounted containers backed by the same feature list hold independent runtime state.
• BREAKING (internal): Feature.internal getter replaced by Feature.config (immutable post-cascade); runtime state reached via container.runtimeOf(feature). Port handler maps moved off Port onto AppContainer.handlersOf / addPortHandler / removePortHandler; Port.addHandler / removeHandler / hasHandlerFor / handlerCount / handlerFeatureNames / handlers deleted. Port.check now takes container:. FeatureParentApi is per-container; FeatureHandlerContext / FeatureScopeApi gained an @internal container field. feature.storeOf<T>() now requires an AppContainer argument: feature.storeOf<T>(container).

Note: This release has breaking internal changes. User-facing API is unchanged; internal (@internal) paths have moved.

Fixed

• Per-container feature runtime — top-level final feature = createFeature(...) instances no longer carry mutable runtime state. Scope API, status store, cleanup bags, ownActive, toggle callable, and the bound FeatureParentApi now live in a new FeatureRuntime owned by each [AppContainer]. Two concurrent or sequentially-remounted containers backed by the same feature list hold independent runtime state — fixes a race where async dispose of one container corrupted another's stores, port handlers, and status subscriptions.

BREAKING (internal)

• Feature.internal getter replaced by Feature.config — exposes FeatureConfig (immutable after cascade): name, deps, factories, activation setup, onStart callback, port bindings. Runtime state is reached via container.runtimeOf(feature).
• Port._handlers removed — port handler registration lives on the container as container.handlersOf<THandler>(port) / container.addPortHandler(...) / container.removePortHandler(...). Ports themselves become stateless across containers (only _owner remains, set-once and stable).
• Port.addHandler / removeHandler / hasHandlerFor / handlerCount / handlerFeatureNames / handlers getter deleted.
• Port.check signature now takes container: AppContainer alongside applyingFeature: — the lookup of pre-registered handlers reads from the container's per-container map.
• FeatureParentApi is instantiated per-container via the new internal featureParentApiForContainer(...) helper; .of / .statusOf resolve through container.runtimeOf(feature).
• FeatureHandlerContext / FeatureScopeApi gain an @internal container field (set by the container during scope construction).
• feature.storeOf<T>() in test_utils.dart now takes an explicit AppContainer argument: feature.storeOf<T>(container).

Behavioural changes

• useStores throws FeatureResolutionError after any container has constructed the feature (previously: after _scopeApi was set on a single shared slot). Semantics are the same for the single-container case; multi-container now also guards.
• container.dispose() clears the per-container port handler map — no cross-container deregistration needed. Handlers are reinstalled on the next container.start() from each feature's recorded portBindings.

Note: This release has breaking changes.

• BREAKING FEAT(website): add interactive docs and examples site. (f30d28c1)