kuinetic 0.1.4 → 0.2.0

package/dist/types/core/animator.d.ts

@@ -1,6 +1,7 @@
 import type { ActivationBinder } from './activation.js';
 import { ATTR } from './attrs.js';
 import type { Capabilities } from './capabilities.js';
+import type { ControlHandle } from './control.js';
 import type { DomWatcher } from './dom-watcher.js';
 import type { JsEffectPreparer } from './js-effect-preparer.js';
 import type { ScrollRoot, ScrollScheduler } from './scroll-scheduler.js';
@@ -36,18 +37,22 @@ export interface AnimatorOptions {
     /** Watch for DOM insertions and attribute changes. Off by default. */
     observe?: boolean;
 }
-/**
- * Scans a document for authored effects and installs them.
- *
- * Every collaborator — registry, capabilities, reporter, activation binder — is injected, so no
- * behaviour depends on module state or globals. The class itself only orchestrates: parsing,
- * compilation, and style decisions all live in pure modules it calls.
- */
 export declare class Animator {
     readonly registry: Registry;
     readonly capabilities: Capabilities;
+    /**
+     * Public alongside `registry` and `capabilities`, and for the same reason: `control()` is a free
+     * function in its own module (mirroring `play()`), and an author-facing diagnostic it emits has
+     * to reach the same sink every other diagnostic on this animator does. Routing it through a
+     * second, private channel would mean `consoleReporter()` silenced half the library's warnings.
+     */
+    readonly reporter: Reporter;
     private readonly root;
-    private readonly reporter;
+    /**
+     * Author-defined bundles found in this animator's root. Per-animator, not per-module: two
+     * animators on two roots must not see each other's definitions.
+     */
+    private readonly bundles;
     private readonly binder;
     private readonly scheduler;
     private readonly rootResolver;
@@ -58,9 +63,57 @@ export declare class Animator {
     private readonly states;
     /** Iterable lifecycle index; the WeakMap remains the fast state lookup. */
     private readonly liveElements;
+    /**
+     * Which run is current for one element's `InstanceState`, so a completion that resolves after
+     * being superseded can tell it is stale even when `status` and `direction` do not say so.
+     *
+     * `state.direction` cannot serve as that identifier on its own — it only ever holds `'forward'`
+     * or `'reverse'`, so an element whose activation flips back and forth (a hover-driven card flip,
+     * `pointerenter`/`pointerleave` firing repeatedly) revisits the same direction many times over
+     * its life. A cancelled run's completion settling late would then match a much later run headed
+     * the same way, by coincidence rather than by being the same run. Keyed on `InstanceState` rather
+     * than `Element` so a `release()`-then-reinstall — a fresh state object — starts with no
+     * history, the same reason `settleWhen` already re-checks `this.states.get(el) !== state`.
+     */
+    private readonly currentRun;
+    /**
+     * Whether the element's current run has a settle gate that will eventually write its final
+     * status, or whether nothing is ever going to report on it.
+     *
+     * `settleWhen` declines to arm a gate when every instance it was handed is `continuous` — see
+     * the reasoning there, which is right: a pin that is still pinned should read `running`. But
+     * "nobody will ever write this status" was left as an unrecorded fact known only inside that
+     * one early return, and `cancel()` had no way to ask. So a cancelled pin kept `status =
+     * 'running'` for the rest of the element's life and `activate()`'s own `running` guard locked it
+     * out of every future activation. Measured on `<div data-kui="pin-section">`, the documented
+     * form: cancel left `data-kui-state="running"`, and the next `activate()` emitted no `kui:start`
+     * at all.
+     *
+     * Recorded here rather than re-derived in `cancel()` from `state.instances`, because the two
+     * would not be asking the same question. `settleWhen` decides on the instances that actually
+     * *started* this run; an instance whose setup threw is excluded there, and by cancel time it is
+     * indistinguishable from a timed one (`continuous` reads from the setup result, which a failed
+     * or torn-down instance no longer has). The gate's own answer is the only one that matches the
+     * gate's own behaviour.
+     *
+     * Keyed on `InstanceState` for the same reason `currentRun` is: a `release()`-then-reinstall
+     * mints a fresh state object, which must start with no history.
+     */
+    private readonly settleArmed;
     /** Built lazily by `watch()` when not injected, so nothing observes until `start()` needs it. */
     private domWatcher;
+    /**
+     * Built lazily by `watchGates()`, and only for an element carrying a viewport gate on a
+     * JavaScript-rendered effect — see `applyViewportGates` for why that is the only case that needs
+     * one. Stays `undefined` on a page whose gates are all on CSS-rendered effects, which binds no
+     * `MediaQueryList` listener anywhere.
+     */
+    private gateWatcher;
     private started;
+    /** This animator's derived-host bookkeeping — see `DerivedBook`. */
+    private readonly book;
+    /** The narrow window the `derived/*` modules get onto this animator — see `AnimatorPort`. */
+    private readonly port;
     constructor(options?: AnimatorOptions);
     /**
      * Explicit entry point. Importing the library never touches the document, which keeps SSR,
@@ -76,11 +129,28 @@ export declare class Animator {
      * `querySelectorAll` excludes the root, but an inserted subtree very often carries the
      * attribute on its top node — skipping it silently drops those animations.
      *
+     * Two passes, and the order is the feature. Every `data-kui-define` in the subtree is registered
+     * before any element in it is compiled, so a `<template>` at the bottom of the document is
+     * already known to the card at the top that names it. Making forward references work by
+     * construction rather than by handling is the point — see `core/bundles.ts`.
+     *
      * @param root - Subtree to scan. Defaults to the animator's root.
      * @complexity O(n) time in the subtree size; O(1) extra space.
      * @overallScore 100
      */
     scan(root?: ParentNode): this;
+    /**
+     * Recompile every element that stalled on a name the library did not know.
+     *
+     * `pending` is stamped for any unresolved name, not only an undefined bundle, so this can retry
+     * an element that will fail again. That is deliberate: the alternative is an index of which
+     * element is waiting on which name, and the cost of being wrong here is one wasted compile on a
+     * page that already has a warning about it.
+     *
+     * @complexity O(p) time in the number of pending elements.
+     * @overallScore 100
+     */
+    private retryPending;
     /**
      * Compile and install one element's effects, recompiling if its attribute changed.
      *
@@ -89,6 +159,19 @@ export declare class Animator {
      * @overallScore 100
      */
     process(el: Element): void;
+    /**
+     * Report everything a finished compile has to say about one element.
+     *
+     * Three sources, one place. The third is separate from the plan's own warnings because `compile`
+     * is pure and environment-free by design — it is handed a registry and a timeline, never the
+     * browser it is running in. "This browser cannot render that channel" is only answerable here,
+     * where the detected capabilities live, and `targets[0]`'s channel union is the merged one, so it
+     * runs once per element rather than once per `target:` group.
+     *
+     * @complexity O(w) time in the total warning count; O(1) space.
+     * @overallScore 100
+     */
+    private reportCompiled;
     /**
      * Apply a compiled plan and bind its activation.
      *
@@ -97,16 +180,148 @@ export declare class Animator {
      */
     /**
      * Choose the activation, letting a primitive's preference fill in only when the author named
-     * none, and warning when an authored activation is not one the effect supports.
+     * none, and reporting whatever looks wrong about one the author did name.
      *
      * Declared capability metadata was previously never checked anywhere, which made
-     * `supportedActivations` documentation rather than a contract.
+     * `supportedActivations` documentation rather than a contract. The checks themselves live in
+     * `activation.ts`'s diagnostics half — they grew a good deal when the list opened, and they
+     * decide nothing, so keeping them here would have made this class the place where "which
+     * activation" and "is that a real event" were the same paragraph.
      *
      * @complexity O(a) time in supported activations; O(1) space.
      * @overallScore 100
      */
     private resolveActivation;
+    /**
+     * Resolve the viewport gates (`above:` / `below:`) on this element's JavaScript-rendered effects.
+     *
+     * CSS-rendered segments are deliberately absent from this method. Their gate is compiled into the
+     * `animation-name` declaration as a `var()` the browser re-resolves on every resize with no
+     * script involved (see `core/breakpoints.ts`), which is the entire reason this feature does not
+     * need the teardown machinery `gsap.matchMedia()` is built around. A JavaScript-rendered effect
+     * has no `animation-name` for a stylesheet to neutralise, so it is the one case that has to be
+     * decided here — and, having been decided once, has to be re-decided when the viewport crosses
+     * the breakpoint it was decided at.
+     *
+     * @complexity O(e) time in JS-rendered effects; O(b) space, bounded by the scale's five names.
+     * @overallScore 100
+     */
+    private applyViewportGates;
+    /**
+     * Arm live re-evaluation for one element, building the watcher on first use.
+     *
+     * Lazy so that a page with no JavaScript-rendered gate — which is most pages, since the catalog
+     * is overwhelmingly `css-keyframes` — binds no `MediaQueryList` listener at all.
+     *
+     * @complexity O(b) time in the element's breakpoints; O(1) amortised space.
+     * @overallScore 100
+     */
+    private watchGates;
+    /**
+     * Rebuild one element because the viewport crossed a breakpoint its JS effects depend on.
+     *
+     * `release` then `process`, rather than a partial update, and rather than `process` alone:
+     * `process` short-circuits on an unchanged fingerprint, and the fingerprint is a hash of
+     * *attributes*, which have not changed — the viewport has. Releasing first is also what makes the
+     * transition safe mid-animation: it aborts the activation binding, runs each JS effect's own
+     * `destroy()`, and unwinds both ledgers, so the element is back at the author's own markup before
+     * the new plan touches it. That is the same path an attribute edit takes, so there is one
+     * teardown implementation rather than two.
+     *
+     * There is deliberately no "is this element still live?" guard. Every path that stops tracking an
+     * element goes through `release`, and `release` unwatches — so an element that reaches here is
+     * one the watcher still holds, which is one `release` has not run on, which is one that is live.
+     * A guard would be unreachable code pretending to be caution, the same call `positioned()` in
+     * `compile.ts` makes about its own missing branch.
+     *
+     * @complexity O(e) time in the element's composed effects; O(1) space.
+     * @overallScore 100
+     */
+    private regate;
+    /** Route a document with any non-empty-selector group through the derived-host path; `true`
+     *  when it did (a derived install's own `document` never carries one, so this cannot recurse). */
+    private installedAsHost;
     private install;
+    /**
+     * Install a zero-instance aggregate host: a `target:` host with no own (empty-selector) group,
+     * whose status mirrors its derived matches' instead of running any effect of its own
+     * (`syncAggregate`). Called by 2a's `installWithTargets` after every claimed match has already
+     * been installed, which is what D-E's stamping order requires — the host's own `data-kui-state`
+     * must never appear before its matches'.
+     *
+     * @complexity O(g) time in the document's group count; O(1) space.
+     * @overallScore 100
+     */
+    private installAggregate;
+    /**
+     * Apply one `target:` group's compiled plan to every element its selector resolved to.
+     *
+     * Its own `planStyles` call, not the element-wide one `install` already made: `declarations` are
+     * per group, so `fade-up target:h2, pin` writes different properties to the `h2` than to the host
+     * even though both share one gate, one activation and one reduced-motion policy (which is exactly
+     * what `elementHasCssAnimation` carries in from the caller).
+     *
+     * `group.target.selector` is always `''` here — `installedAsHost` diverts any document carrying a
+     * real `target:` group to `installWithTargets` before `install` (this method's only caller) ever
+     * runs, so `matches` is always the host's own single-element `[el]` (target:-everywhere reconcile
+     * R-8 removed the in-place relocation path this method used to also handle, along with the
+     * `indexTargetGroup` call it made only for a real group — `restageTargets`, in
+     * `core/derived/install.ts`, is the one that indexes a real target group's stagger keys now).
+     *
+     * @complexity O(m * p) time in the group's matches and the plan's properties; O(p) space.
+     * @overallScore 100
+     */
+    private installGroup;
+    /**
+     * Write one group's plan onto one of its matched elements, and register the instances that plan
+     * produced there.
+     *
+     * Every write goes through `context.ledgers`, never `match.style`/`match.setAttribute` directly:
+     * under `scope:page` a match need not be a descendant of the host at all, so the ledger set is
+     * the only thing that knows to unwind it on `release()`.
+     *
+     * @complexity O(p) time in the plan's property count; O(1) space beyond the instances pushed.
+     * @overallScore 100
+     */
+    private installMatch;
+    /**
+     * Wire an authored `func:` to this element's completion.
+     *
+     * Registered as an ordinary `kui:finish` listener rather than called from a dispatch site, so it
+     * can never fire at a moment the event does not — the key is sugar for that listener, and is
+     * implemented as literally that listener. It detaches with every other binding on
+     * `controller.abort()`.
+     *
+     * Called from `install` *before* `openGate`, and the order is load-bearing: the one `kui:finish`
+     * an element can receive during install is the synchronous `reduced-motion` one, and the visitor
+     * who asked for reduced motion is the last one whose chained step should silently be dropped.
+     *
+     * See `callback.ts` for the lookup rules, and for why this key must never be built from
+     * untrusted input.
+     *
+     * @complexity O(1) time and space.
+     * @overallScore 100
+     */
+    private bindAuthorCallback;
+    /**
+     * Validate and resolve one `CompiledTarget`'s selector against the live document.
+     *
+     * `resolveTarget`'s document-wide/invalid rejection — the same rule the six built-in
+     * `target:`-declaring primitives apply inside their own `prepare` — has to run again here for
+     * every *other* primitive: a CSS-rendered retargeted effect never calls `prepare` at all, so
+     * compile-to-install time is the only point at which this element has a real `Document` to
+     * validate the selector against. `compileTargets` itself is pure and DOM-free by design and
+     * cannot do this check.
+     *
+     * @param el - The host. The search root under `'self'`, and the only "match" for the host group
+     *   (`target.selector === ''`), which is never queried at all.
+     * @returns The matches, in document order. Empty when the selector was invalid, too broad, or
+     *   simply matched nothing — every case already warned by name.
+     * @complexity O(1) for the host group; O(n) in document size otherwise, the query itself being
+     *   the DOM's.
+     * @overallScore 100
+     */
+    private resolveGroupMatches;
     /**
      * Decide whether, and when, the effects on this element are allowed to start.
      *
@@ -119,6 +334,41 @@ export declare class Animator {
      * @overallScore 100
      */
     private openGate;
+    /**
+     * Whether the visitor's own reduced-motion preference disables this plan outright, rather than
+     * merely shortening or crossfading it.
+     *
+     * Pulled out of `openGate` so that method's own branching stays about *what to do*, not about
+     * the two-part question of whether the policy applies at all.
+     *
+     * @complexity O(1) time and space.
+     * @overallScore 100
+     */
+    private reducedMotionDisables;
+    /**
+     * Report every way an authored `actions:` cannot do what it says, once, at bind time.
+     *
+     * At bind time rather than per crossing, and that is the whole reason this is a separate method:
+     * a crossing fires on every scroll pass, and a diagnostic repeated on each one is a diagnostic
+     * nobody reads. It is the same discipline `control.ts` applies — warn once at construction, even
+     * for a caller who only meant to read.
+     *
+     * @complexity O(1) time and space.
+     * @overallScore 100
+     */
+    private warnAboutCrossings;
+    /**
+     * Do whatever this element's `actions:` names for the crossing that just happened.
+     *
+     * A pure dispatch, and deliberately nothing more. `toggle-actions.ts` owns what each verb means,
+     * `activation.ts` owns which crossing it was, and this method's only contribution is the two
+     * things neither of them can reach: the element's own directional transitions, and its instances'
+     * playheads. If anything resembling animation logic ever appears here, it is in the wrong file.
+     *
+     * @complexity O(n) time in the element's instances; O(n) space.
+     * @overallScore 100
+     */
+    private applyCrossing;
     /**
      * Start a deferred animation.
      *
@@ -135,6 +385,180 @@ export declare class Animator {
      * @overallScore 100
      */
     activate(el: Element): void;
+    /** The per-element half of {@link activate} — see that method's own doc comment. */
+    private activateOne;
+    /**
+     * Play an element's effects back out.
+     *
+     * The exit half of a paired activation — `data-kui-on="pointerenter/pointerleave"`,
+     * `data-kui-on="enter/leave"` — routed through one method for the same reason `activate` is: it
+     * is the single place an effect ever runs backwards, so what an exit means does not have to be
+     * re-decided per activation.
+     *
+     * **CSS-rendered effects reverse; JS-rendered ones do not, and say so.** A CSS effect has a real
+     * `Animation` handle whose playback rate can simply be negated, landing on the from-state that
+     * `animation-fill-mode: both` is already holding. A JS-rendered effect has no playhead at all —
+     * `getAnimations()` returns `[]` for it (see `play.ts`) — and there is no honest general shim
+     * for "half a `split-flap`, backwards". Rather than invent one that misbehaves differently per
+     * primitive, an instance that cannot reverse is named in a warning; the author learns their
+     * pointerleave does nothing *here* instead of discovering it in a browser. On an element
+     * composing both renderers the CSS half still reverses and the warning names what did not.
+     *
+     * @param el - Element whose effects should play out.
+     * @complexity O(n) time in the number of instances; O(1) space.
+     * @overallScore 100
+     */
+    deactivate(el: Element): void;
+    /**
+     * Turn an element's playhead around and settle it back at the from-state it started from.
+     *
+     * The single owner of `state.direction === 'reverse'`, and it exists as its own method because
+     * for a while there were two owners and neither knew about the other. `deactivate()` — the exit
+     * half of a paired activation — flipped the direction and re-armed the settle gate;
+     * `control(el).reverse()` reached straight past the state machine into the raw `Animation`
+     * handles through `InstanceControl.reverse`. Both moved the same playheads, only one of them said
+     * so, and an animator that believed a reversing element was still travelling forwards got three
+     * things wrong at once: a later `deactivate()` sailed through its "an exit already in flight must
+     * not restart" guard and began a *second* reverse; `activate()` could never turn the playhead
+     * around, because it looks for `'reverse'` and never saw it; and the forward `settleWhen` left
+     * over from the entrance stayed pending until it stamped `data-kui-state="finished"` onto an
+     * element sitting at its from-state.
+     *
+     * So the transition lives here and both entry points call it. What `deactivate()` keeps is only
+     * what is true of an *activation* exit specifically. A programmatic reverse is not one — an
+     * author calling `control().reverse()` has not had a pointer leave anything — so it inherits
+     * none of that, and in particular is not told that the effects it cannot reach make "the exit
+     * half of this activation" do nothing. `control.ts` has already named those for it.
+     *
+     * Resuming forward travel is `activate()`'s job, not a second method here: an element left in
+     * `'reverse'` is turned around by `turnAround`, which is reachable from every route that
+     * activates — a pointer coming back, `play()`, `kui.activate()`.
+     *
+     * @param el - Element whose effects should run backwards. Unknown elements are ignored, exactly
+     *   as they are by `activate` and `deactivate`.
+     * @complexity O(n) time in the number of instances; O(1) space.
+     * @overallScore 100
+     */
+    reverseFrom(el: Element): void;
+    /** The per-element half of {@link reverseFrom} — see that method's own doc comment. */
+    private reverseOne;
+    /**
+     * Resume forward playback on an element whose exit is still in flight.
+     *
+     * Separate from `activate`'s main path because none of that path applies: the instances are
+     * already started, the activation is already spent, and the state is already `running`. All that
+     * changes is the direction of travel.
+     *
+     * @complexity O(n) time in the number of instances; O(1) space.
+     * @overallScore 100
+     */
+    private turnAround;
+    /**
+     * Write an element's final state once the instances driving it have finished.
+     *
+     * The reported state has to become truthful eventually, or `data-kui-state` codifies a lie that
+     * tests then assert against. It also has to stay truthful when a run is superseded mid-flight: a
+     * reverse that is turned around leaves its own `finished` promise pending, and letting that
+     * promise write `ready` over the forward run that replaced it is how an element ends up claiming
+     * it is back at its from-state while visibly finishing its entrance. Capturing the direction at
+     * the time of the call and re-checking it on resolution is what makes the stale promise a no-op
+     * in the ordinary case — turned-around and reversed-again runs, which is why that comment and
+     * check are kept even though `run` below also covers them.
+     *
+     * `run` is the check `direction` cannot be: `direction` only ever holds two values, so a run
+     * that flips back and forth several times (a hover-driven card flip, `pointerenter`/
+     * `pointerleave` firing repeatedly) revisits the same direction repeatedly, and a stale run's
+     * belated completion could otherwise be mistaken for a much later one simply travelling the same
+     * way. `beginRun` mints one identity per run; only the run that is still current when its own
+     * promise resolves gets to report anything.
+     *
+     * @param target - The element, its state, and this run's identity — see {@link SettleTarget}.
+     * @param instances - The instances this particular run started; a run only waits on its own.
+     * @param next - State to report when they are all done.
+     * @complexity O(n) time in the instances; O(n) space for the pending promises.
+     * @overallScore 100
+     */
+    private settleWhen;
+    /**
+     * Mark the start of a new run — a forward activation, a reversal, or a turnaround out of one —
+     * and clear the mark a previous run's cancellation left behind.
+     *
+     * The two things a fresh run does are bound together deliberately: `cancelled` describes *this*
+     * run, not the element for life, so every place that begins one must also disown whatever the
+     * run before it was marked with, or that run's cancellation would silently apply to a completion
+     * it had nothing to do with — see `InstanceState.cancelled`'s own doc comment for the contract
+     * this keeps. Doing both here, in one call, is what stops a caller resetting one without the
+     * other; three call sites each remembering to write two lines in the right order was exactly
+     * this bug's shape the first time.
+     *
+     * @returns This run's identity, to be threaded through to the `settleWhen` call that will
+     *   eventually report on it.
+     * @complexity O(1) time, O(1) space.
+     * @overallScore 100
+     */
+    private beginRun;
+    /**
+     * Dispatch one lifecycle event for an element, filling in the identity every listener needs.
+     *
+     * Centralised here rather than inside each instance because the animator is the only place that
+     * knows the *element's* lifecycle — an element composing three effects starts once and finishes
+     * once, not three times, and only this class sees all three instances at the same moment.
+     *
+     * @complexity O(n) time in listeners on the propagation path; O(1) space.
+     * @overallScore 100
+     */
+    private emit;
+    /**
+     * Write one element's status, through its own ledger, with no aggregate sync.
+     *
+     * The one place `status`/`data-kui-state` are written together, so every call site that used to
+     * write both fields by hand now shares one line to drift out of sync in. `el` is unused today —
+     * kept because 2b's tests and a future per-element hook both key on it, and because every other
+     * write in this file takes the element it writes to as its first argument.
+     *
+     * @complexity O(1) time and space.
+     * @overallScore 100
+     */
+    private writeStatus;
+    /**
+     * Let a derived state's host re-derive its aggregate status (D-A).
+     *
+     * Called after the derived element's own event, so listeners see the match's event before the
+     * host's — the same order a nested DOM structure would deliver them in were the host merely
+     * listening for its children's events instead of deriving its own status from them.
+     *
+     * @complexity O(1) time and space, delegating to {@link syncAggregate}.
+     * @overallScore 100
+     */
+    private syncHost;
+    /**
+     * Stop one element's effects where they are, leaving it mid-animation.
+     *
+     * The counterpart to `activate()`, and the reason it exists rather than callers reaching into
+     * `stateOf(el).instances` themselves (which is what `play()`'s handle used to do): cancellation
+     * has an observable consequence — `kui:cancel`, and the suppression of the `kui:finish` that
+     * would otherwise follow it — and that consequence has to be applied wherever cancellation
+     * happens, not only where it happens to be convenient.
+     *
+     * @param el - Element whose effects should stop.
+     * @complexity O(n) time in the element's instances; O(1) space.
+     * @overallScore 100
+     */
+    cancel(el: Element): void;
+    /** The per-element half of {@link cancel} — see that method's own doc comment. */
+    private cancelOne;
+    /**
+     * Runtime control over a selection's playheads — pause, resume, reverse, seek, re-speed.
+     *
+     * Selection-shaped rather than single-element, so it matches `play()` and so one call covers a
+     * staggered group. `control.ts` builds a per-element handle underneath and the returned handle
+     * composes them.
+     *
+     * @param target - Selector, element, or iterable of elements.
+     * @complexity O(n) time in selected elements and their instances; O(n) space.
+     * @overallScore 100
+     */
+    control(target: Target): ControlHandle;
     /**
      * Activate one instance, isolating a throw from its (possibly deferred) setup.
      *
@@ -161,6 +585,10 @@ export declare class Animator {
      */
     uncloak(): void;
     stateOf(el: Element): InstanceState | undefined;
+    /** The derived matches a host's `target:` groups installed, in document order. `[]` otherwise. */
+    derivedOf(el: Element): Element[];
+    /** The host that installed a derived match, else `undefined`. */
+    hostOf(el: Element): Element | undefined;
     /**
      * Tear an element's effects down so the next `process()` reinstalls from scratch.
      *
@@ -195,8 +623,15 @@ export declare class Animator {
      * method's only caller — is itself typed `(el: Element) => void`, so there is no runtime case
      * where `node` is a `Document`/`DocumentFragment` to guard against.
      *
+     * `restageAfterRemoval` runs over every candidate visited, not only the ones actually released:
+     * a removed stagger member is exactly the case this closes, and whether it was "live" by
+     * `liveElements`' definition is a question `GROUP_OF_CHILD` (in `stagger.ts`) answers on its own
+     * terms. Without it, removing one item from a staggered group left every later sibling holding
+     * the rank an index computed for a group one element larger — the stale-after-*edit* half of the
+     * same defect `3d57ff7` already closed for an attribute change, left open for a removal.
+     *
      * @complexity O(s) time in the removed subtree's element count; O(1) per candidate via the
-     * `liveElements` Set lookup.
+     * `liveElements` Set lookup, plus stagger re-ranking bounded by the surviving groups' own sizes.
      * @overallScore 100
      */
     private releaseTree;

package/dist/types/core/attrs.d.ts

@@ -2,6 +2,11 @@
 export declare const ATTR: {
     /** Authored. The rich grammar. */
     readonly source: "data-kui";
+    /**
+     * Authored. Names the composition in this element's {@link source} so other elements can reuse
+     * it by name. An element carrying it is a definition — data, never animated. See `core/bundles.ts`.
+     */
+    readonly define: "data-kui-define";
     /** Library-owned and unstable: normalized effect names, for CSS hooks and debugging. */
     readonly normalized: "data-kui-fx";
     readonly state: "data-kui-state";
@@ -12,4 +17,8 @@ export declare const ATTR: {
     readonly cloak: "data-kui-cloak";
     /** Reduced-motion policy, stamped from the primitive so the CSS layer can act on it. */
     readonly rm: "data-kui-rm";
+    /** Library-owned: comma list of `target:` selectors on this host that matched nothing (D). */
+    readonly unmatched: "data-kui-unmatched";
+    /** Library-owned: a structural role the library assigned to a child (`front`,`back`,`control`,`bar`). */
+    readonly part: "data-kui-part";
 };