kuinetic 0.1.4 → 0.2.0

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

@@ -1,9 +1,91 @@
 import type { Registry, ResolvedEffect } from './registry.js';
-import type { Activation, Channel, EffectSpec, ParsedValue, ReducedMotionPolicy, Timeline } from './types.js';
+import type { SequenceStep } from './sequence.js';
+import type { TargetScope } from './target.js';
+import type { Activation, Channel, EffectSpec, EffectVariant, NamedActivation, ParameterSchema, ParsedValue, ReducedMotionPolicy, SegmentHoists, Timeline } from './types.js';
 export interface Entry {
     spec: EffectSpec;
     resolved: ResolvedEffect;
+    /**
+     * Per-spec refinement from `primitive.variantFor`, computed once in `resolveEntries` and carried
+     * on the entry so nothing downstream has to call it a second time. Absent for every primitive
+     * that is fully described without seeing an attribute, which is all but the generic tween.
+     */
+    variant?: EffectVariant;
+    /**
+     * Concrete milliseconds an `at:` position resolved to, for JS-rendered entries only.
+     *
+     * A CSS-rendered entry needs no such field: its position is a symbolic `calc()` the browser
+     * evaluates, which is both more accurate and re-evaluated when a stylesheet moves one of the
+     * durations underneath it (see `core/sequence.ts`). A JS-rendered one has no `animation-delay`
+     * to write to and needs a number, so the sequencer's numeric mirror is carried here and applied
+     * by `js-effect-preparer.ts` over whatever `readEffectTiming` read off the spec.
+     *
+     * Absent when the segment carries no `at:`, and when the position was refused — in both cases the
+     * effect keeps its own authored delay. There is no third case: a sequenced step always carries a
+     * real number, because the sequencer refuses a duration it cannot read rather than passing an
+     * unknown along.
+     */
+    sequencedDelayMs?: number;
+    /**
+     * Where the sequencer placed this segment, resolved once for the whole authored comma list
+     * before {@link compileTargets} partitions it by target — see that function's own comment for
+     * why the order matters. Always present once an entry leaves `compileTargets`; absent only on an
+     * `Entry` a test builds by hand without going through it.
+     */
+    step?: SequenceStep;
+    /**
+     * Selector this entry retargets to, lifted out of `spec.params` by `resolveEntries` for any
+     * primitive that does not declare a `target` parameter of its own. Undefined means "compiles on
+     * the host", which is every entry today and every entry whose primitive owns `target:` itself
+     * (see `liftTarget`'s comment for the current set — they read the key from `spec.params`,
+     * unchanged).
+     */
+    target?: string;
+    /** Which tree {@link target} is searched in. Only meaningful when `target` is set. */
+    scope?: TargetScope;
+    /**
+     * `animation-composition` for every track this entry compiles, when the composition resolver had
+     * to make it additive to let a same-channel neighbour survive — see {@link resolveComposition}.
+     *
+     * Absent means the CSS initial value, `replace`, which is what every entry compiled before this
+     * existed and what all but the handful of additively-resolved ones still compile to.
+     * `declarations.ts` omits the declaration entirely when no track sets it, the same way it already
+     * omits an all-`normal` `animation-direction`.
+     */
+    composite?: 'add';
 }
+/**
+ * Channels one entry actually writes — the primitive's declaration, widened by any variant.
+ *
+ * Read by conflict detection *and* by the plan's channel union, which must agree: a `tween x:100`
+ * that is checked for collisions on `translate` but reports no channel to `style-plan.ts` would
+ * compose correctly and then skip the individual-transform fallback that same channel exists to
+ * trigger.
+ *
+ * @complexity O(c) time and space in the entry's channel count.
+ * @overallScore 100
+ */
+export declare function channelsFor(entry: Entry): Channel[];
+/**
+ * Authored parameter values in force for one entry — `spec.params`, or a variant's normalisation
+ * of them. Exported because the JS-effect path reads them too, and the two must not disagree about
+ * what the author wrote.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function authoredParams(entry: Entry): Record<string, string>;
+/**
+ * The parameter specs one entry's values are validated against — the primitive's declaration,
+ * extended by any its variant synthesised for keys the primitive could not declare statically.
+ *
+ * Merged rather than replaced: see `EffectVariant.schema`. The primitive's own specs stay in force,
+ * so a variant can add parameters but never relax one.
+ *
+ * @complexity O(p) time and space in the schema size, and only when a variant declares one.
+ * @overallScore 100
+ */
+export declare function schemaFor(entry: Entry): ParameterSchema;
 export interface CompiledPlan {
     /** Effect names to stamp into `data-kui-fx` for CSS hooks and debugging. */
     fxNames: string[];
@@ -11,6 +93,18 @@ export interface CompiledPlan {
     vars: Record<string, string>;
     /** Longhand animation declarations, compiled as parallel lists so effects compose. */
     declarations: Record<string, string>;
+    /**
+     * The bare `@keyframes` idents behind those declarations, one per track, in the same order.
+     *
+     * Carried separately because `animation-name` is no longer a list of idents that can be recovered
+     * by splitting it: a gated segment compiles to `var(--kui-above-md, kui-in-up)` (see
+     * `core/breakpoints.ts`), and `String.split(',')` shreds that into `var(--kui-above-md` and
+     * `kui-in-up)`. `animator.ts` hands this list to `createCssInstance`, which matches it against
+     * `getAnimations()` to decide which handles it owns — so a re-parse that produced `kui-in-up)`
+     * would own nothing, settle its completion promise immediately, and strand `data-kui-state` on
+     * `finished` while the animation was still visibly running.
+     */
+    keyframeNames: string[];
     /** Effects whose renderer needs JS setup. */
     jsEffects: Entry[];
     /** Names that are not registered. Must NOT be stamped, or the element is never rescanned. */
@@ -20,7 +114,7 @@ export interface CompiledPlan {
     /** Activation preferred by the composed primitives when the author named none. */
     defaultActivation?: Activation;
     /** Activations every composed primitive supports, for enforcement by the animator. */
-    supportedActivations: Activation[];
+    supportedActivations: NamedActivation[];
     /**
      * Timelines every composed primitive supports. Empty means none — `style-plan.ts` must not
      * apply a native `view()`/`scroll()` timeline the author's effect doesn't declare support for,
@@ -30,6 +124,19 @@ export interface CompiledPlan {
     supportedTimelines: Timeline[];
     /** Union of channels every composed effect writes to, so callers can react to what actually moves. */
     channels: Channel[];
+    /**
+     * Merged `transition` shorthand value for the composed effects' declared {@link TransitionSegment}s,
+     * or absent when none of them transitions anything. Consumed by the one
+     * `:where([data-kui-fx])` rule in `base.css` through the ledger, the same way `vars`/`declarations`
+     * are.
+     *
+     * Deliberately NOT folded into `declarations`: `style-plan.ts` reads that field's emptiness as
+     * "this element has a CSS animation" and would gate every one of these ten presets — all
+     * `renderer: 'javascript'` — behind `animation-play-state: paused`, pausing an animation that
+     * does not exist. Deliberately NOT folded into `vars` either: that field means "author parameter
+     * overrides", and several tests assert its exact contents with `toEqual`.
+     */
+    transition?: string;
     warnings: string[];
 }
 /**
@@ -47,3 +154,101 @@ export interface CompiledPlan {
  * @overallScore 100
  */
 export declare function compile(parsed: ParsedValue, registry: Registry, timeline: Timeline): CompiledPlan;
+/**
+ * One `target:`-partitioned group of a compiled `data-kui` attribute — the plan for the segments
+ * that share one `(scope, selector)` pair, plus which pair that is.
+ *
+ * `selector: ''` is the host: the element the attribute is authored on, always present, always
+ * `CompiledDocument.targets[0]`. Every other entry names a `target:` a primitive did not claim for
+ * itself — see `Entry.target`'s own comment for which primitives those are.
+ */
+export interface CompiledTarget {
+    /** `''` for the host group. */
+    selector: string;
+    scope: TargetScope;
+    /**
+     * Segment-scoped hoists merged across this group's own member entries, or absent when none of
+     * them carried one — see `SegmentHoists` and `scopeHoists`. Not yet consumed at runtime (that is
+     * Phase 2's job, via `element-config.ts`'s `resolveGroupConfig`); documented here as the shape a
+     * derived host's own `ElementConfig` will be built from.
+     */
+    hoists?: SegmentHoists;
+    /** This group's lifted specs (target/scope stripped, hoists kept), authored order — what a
+     *  multi-group union recompiles from (2b `compileUnion`). */
+    specs: EffectSpec[];
+    plan: CompiledPlan;
+}
+/**
+ * The full compilation of one authored `data-kui` value, before it is narrowed to a single plan.
+ *
+ * `warnings` here are the ones about the authored comma list as a whole rather than about any one
+ * target group: unknown effect names, the `at:` sequencer's own diagnostics, a refused container
+ * gate, a retarget the preset would not survive, and the hoisted `rm:`'s one-way-ratchet refusal.
+ * A group's own composition/parameter warnings live on `CompiledTarget.plan.warnings` instead,
+ * exactly where they always have.
+ *
+ * The two lists are disjoint, and that is load-bearing rather than tidy: `animator.ts` reports this
+ * one and then every group's, so a warning reachable through both would be printed twice — which is
+ * exactly what a shared array reference used to do to all of them.
+ */
+export interface CompiledDocument {
+    targets: CompiledTarget[];
+    warnings: string[];
+    /** 9b: stray segments that look like an unquoted selector list — surfaced by 5b in
+     *  `data-kui-unmatched`. */
+    suspectSelectors?: string[];
+}
+/**
+ * Compile a parsed `data-kui` value into one plan per `target:`/`scope:` group.
+ *
+ * The host group (selector `''`) is always present and always first, whether or not the author
+ * targeted anything — `install` in `animator.ts` loops every group the same way, and a page that
+ * never uses `target:` compiles to exactly the one group it always has.
+ *
+ * A fixed order, not to be reshuffled:
+ *
+ * 1. **Resolve and lift**, once, over the whole authored list (`resolveEntries`). Every entry gets
+ *    a primitive; every entry whose primitive does not own `target:` itself gets `.target`/`.scope`
+ *    pulled off its params here, before anything downstream can see them.
+ * 2. **Sanitize container gates** (`refuseContainerGate`), before composition sees them — see that
+ *    function's own comment for why a stripped gate must not still count as "these can never
+ *    collide".
+ * 3. **Sequence**, once, over the whole *unpartitioned* list. `at:` positions a segment against its
+ *    neighbours in the authored comma list — `fade-up target:h1, slide-left target:p at:-200ms` is
+ *    one author's clearly-linked pair, and partitioning first would make them neighbourless.
+ * 4. **Partition, then compose and build, per group.** Channel conflicts are only real within a
+ *    group — two effects that land on different elements cannot collide — so `findConflicts`
+ *    (inside `resolveComposition`) has to run after the split, not before it.
+ *
+ * @param parsed - Output of `parse`.
+ * @param registry - Effect catalog to resolve names against.
+ * @param timeline - Element-scoped timeline, used to warn on unsupported combinations.
+ * @complexity O(e * p) time in composed effects and their parameters; O(e) space.
+ * @overallScore 100
+ */
+export declare function compileTargets(parsed: ParsedValue, registry: Registry, timeline: Timeline): CompiledDocument;
+/**
+ * Fold a targeted segment's provisional hoists (`spec.hoists`, from `parse.ts`) back onto the
+ * element-wide `ParsedValue` for any spec whose primitive is not itself a `target:`-declaring one
+ * (or is unknown) — see `types.ts`'s `SegmentHoists`.
+ *
+ * `parseSegment` cannot know, at parse time, whether a targeted segment's own primitive declares
+ * a `target` parameter — that requires the registry, which only `compile.ts` has. A segment whose
+ * primitive *does* declare `target` (the nine listed on `liftTarget`'s comment) never becomes a
+ * group at all: `target:` there means "this primitive's own participants", so its hoists were
+ * always meant to be element-wide, same as before this feature existed. An unknown name is folded
+ * the same way, for the same reason `resolveEntries` already treats it as staying on the host:
+ * there is no group to scope anything to.
+ *
+ * Called from `animator.ts`'s `process()`, right after `bundles.expand` and before
+ * `resolveConfig` — `resolveConfig` reads `parsed.activation`/`timeline`/etc. and must see the
+ * folded answer, not a value still sitting on a declaring spec's `hoists`.
+ *
+ * @param parsed - Output of `parse`/`bundles.expand`.
+ * @param registry - Effect catalog, needed to tell a declaring primitive from a retargeting one.
+ * @returns `parsed` unchanged (by reference) when nothing needed folding — the identity path for
+ *   every attribute with no `target:` at all — or a new `ParsedValue` with the fold applied.
+ * @complexity O(s * k) time in spec count and the nine hoist keys; O(s) space.
+ * @overallScore 100
+ */
+export declare function scopeHoists(parsed: ParsedValue, registry: Registry): ParsedValue;

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

@@ -0,0 +1,218 @@
+import type { Animator } from './animator.js';
+import type { StyleLedger } from './owned-styles.js';
+import type { Target } from './play.js';
+import type { Activation, InstanceControl, PlaybackState, Timeline } from './types.js';
+/**
+ * Control backed by the real `Animation` objects a compiled CSS effect produces.
+ *
+ * @param animations - Reader for the element's *owned* animation handles. A reader rather than an
+ *   array because the set changes: `instances.ts` restarts an animation by rewriting
+ *   `animation-name`, which replaces the handles wholesale, and a captured array would then be
+ *   driving objects the element no longer has.
+ * @param ledger - The instance's style ledger, so a play-state write unwinds on teardown.
+ * @complexity O(a) per call in owned animations; O(1) space.
+ * @overallScore 100
+ */
+export declare function createCssControl(animations: () => Animation[], ledger: StyleLedger): InstanceControl;
+/**
+ * A handle over one selection's playheads.
+ *
+ * Every mutator returns the handle so calls chain — `control('.hero').timeScale(0.25).seek(0.5)`
+ * reads the way the equivalent GSAP line does. Chaining is the reason these are methods rather
+ * than settable properties.
+ */
+export interface ControlHandle {
+    /** The elements this handle resolved to, in document order. */
+    readonly elements: Element[];
+    /**
+     * Effect names in the selection whose playhead no control call can reach — JavaScript-rendered
+     * effects, and anything driven by scroll rather than a clock.
+     *
+     * Readable so a caller can branch on it rather than discovering the gap by watching nothing
+     * happen. Every entry has also already been reported through the animator's reporter.
+     *
+     * "Playhead" is the operative word, and it is `pause`, `play`, `seek`, `timeScale` and `progress`
+     * that it governs. `reverse()` is the one method here that is not a playhead call — it asks the
+     * animator which way the element is travelling — so it answers to the animator's directional test
+     * instead, and a scroll-driven element is refused for its own reason rather than this one.
+     */
+    readonly uncontrolled: string[];
+    pause(): ControlHandle;
+    play(): ControlHandle;
+    /**
+     * Play the selection backwards, ending at the from-state each element started from.
+     *
+     * Idempotent: calling it twice is one exit, not an exit and an entrance, on exactly the rule that
+     * makes two `pointerleave`s in a row one exit. It is also *recorded* — the animator knows the
+     * element is travelling backwards, so a subsequent paired-activation exit does not start a second
+     * reverse, and the element settles at `data-kui-state="ready"` with a `kui:reverse-finish`.
+     *
+     * To travel forwards again, activate the element (`play()`, `kui.activate()`, or the entrance
+     * half of its activation): the animator turns a reversing playhead around rather than restarting
+     * it. `play()` on this handle is the narrower thing its name says elsewhere in this file — the
+     * counterpart to `pause()` — and does not change direction.
+     */
+    reverse(): ControlHandle;
+    /** Move every playhead to `progress` (0..1). Values outside the range are clamped. */
+    seek(progress: number): ControlHandle;
+    /** Multiply playback speed. `1` is authored speed; a negative value runs backwards. */
+    timeScale(rate: number): ControlHandle;
+    /**
+     * Position of the *least* advanced element in the selection, 0..1.
+     *
+     * The minimum rather than the maximum or the first, so `progress === 1` means every element is
+     * done — the reading an author actually gates on. `0` for a selection with nothing controllable.
+     */
+    readonly progress: number;
+    readonly state: PlaybackState;
+}
+export interface ControlRequest {
+    animator: Animator;
+    root: ParentNode;
+    target: Target;
+}
+/**
+ * Build a control handle for a selection.
+ *
+ * Warnings are emitted once here, at construction, rather than on each call: an author who asks
+ * for control over an effect that has none should be told immediately, including when they only
+ * meant to *read* `progress` — and repeating the same sentence on every frame of a `seek` loop
+ * would bury it. The default reporter is silent, exactly as it is for an unknown effect name or an
+ * unsupported activation; `consoleReporter()` makes all of them loud together, which is the
+ * existing contract rather than a new one invented here.
+ *
+ * @param request - Animator, root, and target selection. Mirrors `play`'s request shape.
+ * @returns A handle whose mutators chain.
+ * @complexity O(n) time in selected elements and their instances; O(n) space.
+ * @overallScore 100
+ */
+export declare function control(request: ControlRequest): ControlHandle;
+/**
+ * Lifecycle events.
+ *
+ * Before this module the library dispatched nothing at all — an author could start an animation
+ * from an attribute and then had no way whatsoever to learn that it had finished. Every escape
+ * hatch on offer (poll `data-kui-state`, race a `setTimeout` against the authored duration, wrap
+ * the element and watch it with a `MutationObserver`) is worse than the thing it replaces, and the
+ * last one is actively broken here — see the `MutationObserver` trap in
+ * `docs/implementation-outline-gsap-parity.md` §4.5.
+ *
+ * A `CustomEvent` on the animated element is the one answer that does not cost the author a
+ * library import. `addEventListener('kui:finish', ...)` is plain DOM, works from a framework's
+ * template, works from another script that has never heard of this library, and — because these
+ * bubble — works from one delegated listener on `document` for a whole page of animations. That is
+ * the same bet the attribute grammar makes: the author writes no library-specific JavaScript.
+ */
+/**
+ * Event names, in one place so the namespace is a single rename before publish — the same
+ * discipline `attrs.ts` applies to attribute names, and for the same reason.
+ *
+ * `kui:` rather than `kui-`: a colon cannot appear in an HTML `on*` content attribute, so there is
+ * no chance of an author writing `onkui-finish="..."` in markup, discovering it silently does
+ * nothing, and blaming the library. It also reads unambiguously as a namespace separator and
+ * cannot collide with any current or future native event name, which a bare `kui-` prefix cannot
+ * promise.
+ */
+export declare const KUI_EVENT: {
+    /** The element's effects have started. Fires once per activation. */
+    readonly start: "kui:start";
+    /** Every finite effect on the element has completed. */
+    readonly finish: "kui:finish";
+    /**
+     * The element has finished playing *backwards* and is sitting at its from-state again.
+     *
+     * A separate name rather than a second `kui:finish` with a different `reason`, because the
+     * commonest thing an author does with `kui:finish` is chain the next reveal off it, and a
+     * listener that has to remember to re-check `event.detail.reason` before doing so is a trap
+     * rather than an API — the one time they forget, a hover-out plays the next section in. Filtering
+     * by *name* is what `addEventListener` is for, and it is what a delegated document-level listener
+     * can do without reading the detail at all.
+     *
+     * The exit half of a paired activation (`data-kui-on="pointerenter/pointerleave"`) settles here,
+     * and so does a programmatic `control(el).reverse()`. Before this existed, a completed reverse
+     * dispatched nothing whatsoever, which left "the element is back where it started" the one
+     * lifecycle moment an author could only discover by polling `data-kui-state`.
+     */
+    readonly reverseFinish: "kui:reverse-finish";
+    /** The element's effects were torn down or cancelled before completing. */
+    readonly cancel: "kui:cancel";
+};
+export type LifecycleEventType = (typeof KUI_EVENT)[keyof typeof KUI_EVENT];
+/**
+ * Why the event fired.
+ *
+ * Carried because the *same* event name legitimately arrives from more than one route, and an
+ * author chaining animations needs to tell them apart. `finish` in particular fires both when an
+ * animation genuinely ran to its end and when reduced motion meant it never ran at all — see
+ * `'reduced-motion'` below.
+ */
+export type LifecycleReason = 
+/** `start`: an activation fired and at least one instance began. */
+'activated'
+/** `finish`: every finite instance resolved. */
+ | 'complete'
+/**
+ * `reverse-finish`: every finite instance finished running backwards, so the element is back at
+ * the from-state it was in before it was ever activated — `data-kui-state` reads `ready` again.
+ *
+ * One reason on one event name today, unlike `finish`, which carries two. It is carried anyway
+ * because the two routes into a reverse (a paired activation's exit half, and a programmatic
+ * `control().reverse()`) are already distinguishable from `detail.activation`, and a listener
+ * that branches on `reason` for every other lifecycle event should not have to special-case this
+ * one for having none.
+ */
+ | 'reversed'
+/**
+ * `finish`: the effect declared `reducedMotion: 'disable'` and the visitor asked for reduced
+ * motion, so it was never started and the element is already at its final state.
+ *
+ * This is the one case where `finish` arrives with no preceding `start`, and it is deliberate.
+ * The alternative — staying silent — strands every author who uses these events to chain work,
+ * because their second step would simply never run for the visitors who most need the page to
+ * stay usable. Firing a synthetic `start` first would be the worse lie: nothing started.
+ */
+ | 'reduced-motion'
+/** `cancel`: the element's effects were torn down — `reset()`, `destroy()`, or DOM removal. */
+ | 'reset'
+/** `cancel`: an explicit `cancel()` on the element or on a `play()` handle. */
+ | 'cancelled';
+/**
+ * What every lifecycle event carries.
+ *
+ * `effects` is the same normalized name list `data-kui-fx` holds, so a delegated listener can tell
+ * *which* effect just finished without re-reading the element's attributes — which matters
+ * precisely because delegation is the case this is for: one listener on `document` seeing events
+ * from hundreds of elements needs the identity in the event, not in a DOM read per event.
+ */
+export interface LifecycleDetail {
+    /** Normalized effect names — the contents of `data-kui-fx`. */
+    effects: string[];
+    activation: Activation;
+    timeline: Timeline;
+    reason: LifecycleReason;
+    /** Set when the event fires on a derived match: its host. */
+    host?: Element;
+}
+/** A lifecycle event, narrowed so `event.detail` is typed at the listener. */
+export type LifecycleEvent = CustomEvent<LifecycleDetail>;
+/**
+ * Dispatch one lifecycle event on the animated element.
+ *
+ * `bubbles` is required by the design (delegation is the point) and `composed` follows from it: an
+ * animated element inside a shadow root whose event stopped at the shadow boundary would be
+ * invisible to exactly the document-level listener this exists to serve. Not `cancelable` — there
+ * is nothing for a listener to prevent; by the time any of these fire the decision has been made.
+ *
+ * The constructor is taken from the element's own window rather than the global one, so an
+ * animator driving a document in an `<iframe>` dispatches an event that element's own listeners
+ * recognise via `instanceof`. Falling back to the global keeps a jsdom-style environment working
+ * where `ownerDocument.defaultView` can be null, and the `typeof` guard keeps this module import-
+ * safe in a DOM-less process, the same rule `capabilities.ts` and `animator.ts` already follow.
+ *
+ * @param el - The animated element. The event's target and the element authors listen on.
+ * @param type - One of `KUI_EVENT`.
+ * @param detail - Identity and reason, readable as `event.detail`.
+ * @complexity O(n) time in the number of listeners on the propagation path; O(1) space.
+ * @overallScore 100
+ */
+export declare function emitLifecycle(el: Element, type: LifecycleEventType, detail: LifecycleDetail): void;

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

@@ -0,0 +1,128 @@
+import type { Entry } from './compile.js';
+import type { SequenceStep } from './sequence.js';
+import type { Timeline } from './types.js';
+/**
+ * The CSS-emission half of the compiler: how one resolved entry becomes longhand declarations.
+ *
+ * `compile.ts` decides *what* animates — which effects resolve, which `target:` group they belong
+ * to, whether they may compose, what the reduced-motion policy is. This file decides *how that is
+ * spelled in CSS*: the parallel `animation-*` value lists that let composed effects share one
+ * declaration, and the merged `transition` shorthand that does the same job for the ten presets
+ * that transition rather than keyframe. Nothing here reads a registry, a parse tree, or a target
+ * group; nothing in `compile.ts` writes a CSS value string any more.
+ *
+ * The `Entry` import is deliberately type-only, so the module graph edge exists at type level and
+ * nowhere at runtime — `.dependency-cruiser.cjs` resolves the graph with `tsPreCompilationDeps:
+ * false` precisely because `import type` is erased by `verbatimModuleSyntax` and a mutual type
+ * reference is not an initialisation-order hazard. `Entry` stays in `compile.ts` because that is
+ * where entries are built and where every other consumer already imports it from.
+ */
+export interface AnimationTracks {
+    /** What is written to `animation-name` — an ident, or a `var()` around one when gated. */
+    names: string[];
+    /** The ident inside it, for `CompiledPlan.keyframeNames`. Same length, same order. */
+    keyframes: string[];
+    durations: string[];
+    /**
+     * Where each track *starts*, as an unwrapped `calc()` sum. Left unwrapped because
+     * {@link declarationsFor} is what finalizes it: on a pin timeline it folds the scrub head into
+     * the same expression, and `calc(calc(a + b) - c)` buries the arithmetic an author has to read
+     * in a devtools panel.
+     */
+    delays: string[];
+    /**
+     * Where each track *ends* — its start plus its whole playback — as an unwrapped sum.
+     *
+     * Read only to size the pin scrub head, which has to span the element's longest track rather
+     * than each track's own playback. Accumulated for every timeline because it costs one string
+     * concatenation and knowing the timeline here would buy nothing else.
+     */
+    ends: string[];
+    easings: string[];
+    iterationCounts: string[];
+    /**
+     * One `animation-direction` per track. Almost always every entry is `normal`, which is the CSS
+     * initial value — see {@link declarationsFor} for why that case emits no declaration at all.
+     */
+    directions: string[];
+    /**
+     * One `animation-composition` per track — `replace` for all but the few the composition resolver
+     * had to sum, and handled exactly like {@link directions}: an all-`replace` list is the CSS
+     * initial value and emits no declaration at all.
+     *
+     * Per track and not per element for the reason `iterationCounts` is: CSS repeats a shorter value
+     * list to match the longest one across every `animation-*` longhand in the group, so a single
+     * `add` written for one effect would be handed to every neighbour composed beside it — including
+     * the ones whose keyframes write `opacity`, where adding to the underlying 1 deletes the fade.
+     */
+    compositions: string[];
+}
+/**
+ * A fresh accumulator for one plan's worth of tracks.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function emptyTracks(): AnimationTracks;
+/**
+ * Append one effect to the parallel animation lists, as one track per keyframe block it compiles.
+ *
+ * Separate rules cannot both contribute an `animation` declaration — the cascade discards one —
+ * so composition is expressed as parallel longhand value lists on a single declaration.
+ *
+ * Usually one block, so usually one track. A variant naming several (`keyframesFor`) gets the same
+ * timing repeated across all of them, which is the point: `tween x:100 opacity:0 800ms` is *one*
+ * effect the author gave one duration, rendered as two tracks only because CSS has no way to write
+ * two unrelated properties from one keyframe without also writing everything in between.
+ *
+ * @param step - Where the sequencer placed this segment. For a segment with no `at:` this is the
+ *   segment's own delay, so the compiled output is unchanged from before sequencing existed.
+ * @complexity O(k) time in the entry's keyframe count; O(k) space in the tracks.
+ * @overallScore 100
+ */
+export declare function pushTrack(tracks: AnimationTracks, entry: Entry, step: SequenceStep): void;
+/**
+ * Append one entry's declared {@link TransitionSegment}s to the element's merged transition list.
+ *
+ * Reuses `durationExpression`/`easingValue` — the same two functions `pushTrack` resolves an
+ * `animation-duration`/`-timing-function` through — so `data-kui="lift 400ms"` reaches a
+ * transitioned property and a keyframed one through one code path that cannot disagree with
+ * itself. The delay is a per-*preset* custom-property slot (`--kui-tx-delay-<name>`) rather than a
+ * shared `animation-delay`-style list: the CSS state rule (`:hover`, `[aria-expanded]`) that
+ * actually triggers the transition writes that slot directly (see `interaction.css`), and distinct
+ * property names per preset are what let two composed presets carry independent delays without a
+ * second clobber one level down.
+ *
+ * Mutates `segments`/`owners` rather than returning a value, the same accumulator shape `pushTrack`
+ * already uses for `tracks` — a per-entry return would need concatenating at every call site for no
+ * benefit, since every caller already owns one shared list for the whole composed entry set.
+ *
+ * @param segments - Accumulator of `"property duration easing delay"` strings, mutated in place.
+ * @param owners - property → the preset name that most recently claimed it, mutated in place, kept
+ *   only to name both presets in the duplicate-property warning below.
+ * @param entry - The composed entry to read `preset.transitions` from.
+ * @param warnings - Diagnostic sink. Two presets transitioning the same property compose — the
+ *   channel model does not forbid it, and CSS resolves the shorthand's last occurrence
+ *   deterministically — but the author is owed a name for which one wins.
+ * @complexity O(t) time and space in the preset's declared transition segment count.
+ * @overallScore 100
+ */
+export declare function pushTransitions(segments: string[], owners: Map<string, string>, entry: Entry, warnings: string[]): void;
+/**
+ * Collapse the parallel track lists into the `animation-*` longhands they compile to.
+ *
+ * Six of them unconditionally, and `animation-direction` only when some track actually alternates.
+ * That last one is not tidiness: `normal` is the CSS initial value, so emitting a list of them
+ * would be a no-op declaration written onto every animated element on every page for the sake of
+ * the rare one that uses `yoyo:`. Omitting it is what keeps an attribute written before `yoyo:`
+ * existed compiling byte-for-byte identically. When it *is* emitted it carries one value per
+ * track, the full length — a shorter list would be repeated by the browser to match
+ * `animation-name` and would silently alternate a neighbour that never asked to.
+ *
+ * The delays arrive unwrapped and are finalized here, because the pin scrub head is the one term
+ * in them that cannot be computed per track — see {@link pinnedDelays}.
+ *
+ * @complexity O(t) time and space in the track count.
+ * @overallScore 100
+ */
+export declare function declarationsFor(tracks: AnimationTracks, timeline: Timeline): Record<string, string>;

package/dist/types/core/derived/aggregate.d.ts

@@ -0,0 +1,43 @@
+import type { CompiledTarget } from '../compile.js';
+import type { AnimatorPort, DerivedInstallContext } from './types.js';
+/**
+ * Recompute an aggregate host's `data-kui-state` from its derived matches' own states (D-A):
+ * `'running'` (+ host `kui:start`('activated')) when any derived match is running; `'finished'`
+ * (+ host `kui:finish`('complete', or `'reduced-motion'` if the host never ran any match; no event
+ * at all if every match was cancelled)) once every match has settled to `'finished'`/`'failed'`;
+ * back to `'ready'` (no event) if every match has been reset to `'ready'`. Idempotent, and a no-op
+ * for any host whose own state is not `aggregate: true`, or that `port.stateOf` does not (yet)
+ * know about.
+ *
+ * Checked in this order because the cases overlap: "any running" must win over "all failed" (a
+ * mix of running and failed is still running), and "all failed" must win over "all finished |
+ * failed" (a `failed`-only host reports `'failed'`, never a `kui:finish`). Any other mix — some
+ * settled, some still `ready` — leaves the host exactly where it was, per D-A: an aggregate host
+ * stays `running` until its last off-screen match finishes, however long that takes.
+ *
+ * @param port - The animator's narrow window.
+ * @param host - The candidate aggregate host.
+ * @complexity O(m) time in the host's derived match count; O(1) space.
+ * @overallScore 100
+ */
+export declare function syncAggregate(port: AnimatorPort, host: Element): void;
+/**
+ * Compile one union group for a match claimed by two or more `target:` groups of the same host, so
+ * `resolveComposition`'s conflict detection runs over the combined spec list exactly as it would
+ * for a hand-written comma list on that element — a match must never see two groups' effects as
+ * unrelated just because they arrived through different selectors. Cached in `port.book.unions`,
+ * keyed by the sorted, `\u0001`-joined `${scope} ${selector}` list, so a second match claimed by
+ * the same group combination reuses the compile. Folds the host's own `rm:` policy in (a union
+ * belongs to no single authored segment to read it from). Reports its own warnings once per host,
+ * not once per match.
+ *
+ * @param port - The animator's narrow window.
+ * @param context - The host's derived-install context — what the union recompiles the timeline
+ *   against.
+ * @param targets - Every group claiming the match, in authored group order.
+ * @returns The compiled union target.
+ * @complexity O(e * p) time in the combined spec/parameter count on a cache miss, O(1) on a hit;
+ *   O(e) space for the freshly compiled target.
+ * @overallScore 100
+ */
+export declare function compileUnion(port: AnimatorPort, context: DerivedInstallContext, targets: CompiledTarget[]): CompiledTarget;

package/dist/types/core/derived/book.d.ts

@@ -0,0 +1,30 @@
+import type { DerivedBook } from './types.js';
+/**
+ * A fresh, empty derived-host book for one `Animator`.
+ *
+ * All WeakMaps, so a removed element takes its own entries with it rather than leaking for the
+ * animator's lifetime — the same discipline `animator.ts`'s own `states`/`currentRun`/`settleArmed`
+ * already follow.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function createDerivedBook(): DerivedBook;
+/**
+ * A host's derived matches as a fresh array, in document order.
+ *
+ * A copy rather than the live `Set`, so a caller may release matches while iterating without the
+ * iteration itself observing the mutation.
+ *
+ * @returns `[]` for a host with no derived matches (or that is not a host at all).
+ * @complexity O(n) time and space in the host's derived match count.
+ * @overallScore 100
+ */
+export declare function derivedOf(book: DerivedBook, el: Element): Element[];
+/**
+ * The host that installed a derived match, if `el` is one.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function hostOf(book: DerivedBook, el: Element): Element | undefined;