kuinetic 0.1.3 → 0.2.0

package/dist/types/effects/catalog/transforms.d.ts

@@ -0,0 +1,13 @@
+import type { Preset, Primitive } from '../../core/types.js';
+import type { Registry } from '../../core/registry.js';
+export declare const TRANSFORMS_PRIMITIVES: Primitive[];
+export declare const TRANSFORMS_PRESETS: Preset[];
+/**
+ * Register catalog section R (static transforms) into a registry.
+ *
+ * @param registry - Registry to populate.
+ * @returns The same registry, for chaining.
+ * @complexity O(n) time in registered primitives and presets; O(1) extra space.
+ * @overallScore 100
+ */
+export declare function registerTransforms(registry: Registry): Registry;

package/dist/types/effects/catalog/view-transitions.d.ts

@@ -0,0 +1,13 @@
+import type { Registry } from '../../core/registry.js';
+import type { Preset, Primitive } from '../../core/types.js';
+export declare const VIEW_TRANSITION_PRIMITIVES: Primitive[];
+export declare const VIEW_TRANSITION_PRESETS: Preset[];
+/**
+ * Register the View Transitions family (catalog section L).
+ *
+ * @param registry - Registry to populate.
+ * @returns The same registry, for chaining.
+ * @complexity O(n) time in registered primitives and presets.
+ * @overallScore 100
+ */
+export declare function registerViewTransitions(registry: Registry): Registry;

package/dist/types/effects/forms/primitives.d.ts

@@ -15,13 +15,24 @@ export declare const VALIDATE_CHECK_PRIMITIVE: Primitive;
 export declare function computeStrength(value: string): number;
 export declare const STRENGTH_METER_PRIMITIVE: Primitive;
 export declare const RANGE_FILL_PRIMITIVE: Primitive;
+export { nextStep, prevStep, clampStep, countSteps, delegateControls } from '../step-index.js';
+export type { ControlGroup } from '../step-index.js';
 /**
- * Advance a step index, wrapping back to 0 — pure, so the wrap rule is assertable without a DOM.
+ * The only member of the family that is not `reducedMotion: 'disable'`, and the difference is the
+ * whole widget.
  *
- * @complexity O(1) time and space.
- * @overallScore 100
+ * Under `disable` the animator never activates the instance, so the deferred setup never runs: no
+ * control listeners, no index published, no slide marked. A visitor who asked for reduced motion
+ * got a deck whose arrows and dots did nothing at all — not a calmer carousel, a broken one.
+ * Reduced motion is a request to suppress animation, never to withdraw function.
+ *
+ * Nothing is lost by shortening instead, because this primitive animates nothing itself. It writes
+ * `data-kui-step` / `--kui-step` on the container and `data-kui-step-state` / `--kui-offset` on the
+ * steps; every transition or animation keyed off those belongs to the page or to forms.css, which
+ * is exactly the layer base.css's `[data-kui-rm]` block reaches — including, since this changed,
+ * the shipped stepper segments' own 200ms fade. The index still moves and the right slide is still
+ * marked; the travel between them is what gets taken away.
  */
-export declare function nextStep(step: number, total: number): number;
 export declare const STEP_PROGRESS_PRIMITIVE: Primitive;
 export type SubmitStage = 'idle' | 'loading' | 'done';
 /**

package/dist/types/effects/gestures/index.d.ts

@@ -5,6 +5,59 @@ import type { Registry } from '../../core/registry.js';
  *
  * The drag family differs only in where a release goes: back to origin (elastic), onward with
  * momentum (throwable), or nowhere (plain drag). That is one primitive with two booleans.
+ *
+ * All thirteen declare `phase: 'state'`, and none declares `transitions` (nothing here renders
+ * through CSS transitions to derive it from — every primitive in this file is `renderer:
+ * 'javascript'`), so this is the whole story rather than a shortcut around it. `compile.ts`'s
+ * `phaseOf` treats an undeclared phase as a fact nothing is known about, which conflicts with
+ * everything including itself — before this, `data-kui="fade-up on:enter, drag"` hit that wall:
+ * both segments claim `translate`, `draggable`'s renderer disqualifies the additive rescue (only
+ * `css-keyframes` tracks qualify), no combo is registered for the pair, and the compiler silently
+ * kept only `fade-up` — an entrance plus a drag on one element, an entirely ordinary request,
+ * did nothing. Interaction-reveal's four presets (`masked-label-swap*`, `hover-intent`) shipped
+ * the identical gap hours earlier; this is the same bug in its second family, not a new one.
+ *
+ * The test throughout is *when does this effect hold the channel it claims*, not *is this a
+ * press*: `'state'` means "governed by a condition the visitor changes, released — or resting at
+ * a value it holds until changed again — once that condition is gone," which is exactly
+ * `entrance`'s counterpart (an entrance plays once and hands the channel to whatever the cascade
+ * says next; see `EffectPhase`'s doc comment). Every one of these primitives writes an inline
+ * style or attribute imperatively rather than through a CSS animation track, so there is no
+ * `to`-only or `from`-only keyframe to inspect — the fact instead is about *when the gesture
+ * runs*:
+ *
+ * - `draggable` (`drag`, `drag-x`, `drag-y`, `drag-inertia`, `throwable`, `elastic-pull`,
+ *   `rubber-band`, `snap-back`) writes `translate` only from `pointerdown` through however long
+ *   the release takes to resolve — instantly for the plain three, a spring settle for the
+ *   inertia pair, a spring return to zero for the elastic three (see `primitives.ts`'s `settle`).
+ *   The inertia pair is the one worth pausing on, because it keeps moving *after* the pointer
+ *   lifts: `drag-inertia`/`throwable` are not "done interacting" the instant `onEnd` fires, but
+ *   they are also not `idle` — `idle` in this catalog means an unbounded loop that never yields
+ *   the channel (`--kui-fx-<name>-iterations: infinite`), and a decelerating throw is bounded and
+ *   does stop. It is the same one continuous gesture instance settling on its own terms, not a
+ *   second trigger, so it is still `state` and not a fourth thing this enum has no room for.
+ *   Every member rests at whatever `translate` it ends on — dropped in place for the plain three,
+ *   carried by momentum for the inertia pair, snapped to zero for the elastic three — and holds
+ *   there via the same inline style until the next drag picks it up again. None of that is an
+ *   `entrance`: there is no hidden from-state and no `cloak`, just an idle rest value between
+ *   gestures.
+ * - `swipeable` (`swipe`, `swipe-x`) and `pressable` (`long-press`) claim the primitive-level
+ *   `'state'` *channel* (a bucket for "writes an attribute, not a CSS property" — see
+ *   `gestures/primitives.ts`'s `channels: ['state']` — a name that collides with this same-named
+ *   `EffectPhase` value only in spelling, not in meaning). `long-press` is the clean case: it
+ *   flips `data-kui-pressed` on the hold and back off on release, precisely the `:active`-shaped
+ *   "held only while the visitor is doing something" case the `state` phase doc describes.
+ *   `swipe`/`swipe-x` are a discrete, already-over gesture by the time `data-kui-swipe` is
+ *   written (`onSwipe` fires once, at recognition) rather than a continuous hold — but the same
+ *   family precedent already covers a discrete, dwell-triggered write: `hover-intent` (
+ *   `interaction-reveal.ts`) sets its class once, on a timer firing during a hover, and keeps it
+ *   until the pointer actually leaves, and that shipped `phase: 'state'`. A swipe's attribute is
+ *   the same shape — written once by an interaction, held until the same primitive changes it
+ *   again — and not an `entrance`, `exit`, or unbounded `idle`.
+ * - `magnetic` (`magnetic`, `magnetic-snap`) writes `translate` continuously while the pointer is
+ *   within `radius`, and springs back toward zero the moment it leaves — proximity rather than a
+ *   press, but still a condition the visitor's own movement drives and un-drives, the same
+ *   `state` shape as a `:hover` rule with a transition.
  */
 export declare const GESTURE_PRESETS: Preset[];
 /**

package/dist/types/effects/index.d.ts

@@ -2,10 +2,15 @@ import { Registry } from '../core/registry.js';
 export { PRIMITIVES, PRESETS, COMBOS, registerCore } from './catalog/core.js';
 export { registerGestures } from './gestures/index.js';
 export { registerLayout } from './layout/index.js';
+export { registerMotionPath } from './motion-path/index.js';
 export { registerScrollMechanics } from './scroll-mechanics/index.js';
 export { registerSvg } from './svg/index.js';
 export { registerThreeD } from './three-d/index.js';
+export { registerCarousel } from './carousel/index.js';
 export { registerCatalog } from './catalog/index.js';
+export { registerTween, TWEEN_PRESETS, TWEEN_PRIMITIVES } from './tween/index.js';
+export { registerViewTransitions } from './catalog/view-transitions.js';
+export { registerShowcase } from '../showcase/index.js';
 /**
  * A registry with the full catalog registered.
  *

package/dist/types/effects/layout/presets.d.ts

@@ -5,5 +5,40 @@ import type { Preset } from '../../core/types.js';
  * The four `flip-*` names are the same primitive: what differs is why the children moved, and the
  * engine neither knows nor needs to. They exist as separate names because authors think in terms
  * of "I filtered a list", not "I mutated a child list".
+ *
+ * Phase (see `EffectPhase`, `core/channels.ts`): eight of these nine are deliberately left
+ * unphased, and that was checked against the actual mechanism rather than assumed from "FLIP looks
+ * like an entrance."
+ *
+ * `flip-container` (the seven `flip-*`/`grid-to-list`/`masonry-reflow`/`expand-to-modal` names) and
+ * `auto-height` genuinely *do* release the channels they animate: `flip.ts`'s `runDeltas` and
+ * `primitives.ts`'s `animateHeight` both compile `fill: delay > 0 ? 'backwards' : 'none'` — never
+ * `'forwards'`/`'both'` — so once a reorder or a height tween finishes, the Web Animation's
+ * contribution is gone and the element's `translate`/`scale`/`height` reads whatever the DOM's own
+ * layout or the page's own stylesheet says next. Nothing here holds a rest value the way
+ * `gestures.ts`'s `draggable` does. That is exactly the `entrance` shape ("plays once from a
+ * displaced from-state, then yields the channel") — but it cannot be declared `entrance`, because
+ * that value's contract in this catalog is narrower than the English word: `test
+ * /composition-phase.test.ts` asserts, catalog-wide, that every `phase: 'entrance'` preset backs
+ * onto a real `@keyframes` block with no closing `to`/`100%` step, to prove the release is real.
+ * These primitives are `renderer: 'javascript'` and animate through ad hoc `Element.animate()`
+ * calls built at runtime — there is no `@keyframes kui-flip-reorder` (or `-accordion-height`) in
+ * any shipped stylesheet for that test to find, so declaring `entrance` here would fail an
+ * off-limits invariant rather than extend it. None of the other three values fit either: not
+ * `idle` (every run is bounded — `deltas.length === 0` even short-circuits to a no-op), not `state`
+ * (nothing is held between calls to persist), not `exit` (nothing departs; a reorder settles back
+ * into a normal, still-visible layout position). Left unphased, these eight keep conflicting with
+ * a same-channel neighbour exactly as they did before this change — a real gap, but the one the
+ * mechanism actually supports today rather than a value chosen to make the enum feel complete.
+ *
+ * `tab-indicator-slide` (`flip-indicator`) is the one exception, and the reason is a real
+ * difference in the primitive, not a different reading of the same one. `prepareIndicator` writes
+ * the indicator's landing spot with `ctx.style.set('translate', ...)` — a **persistent** inline
+ * style — before it ever calls `engine.play()`; the FLIP animation only smooths the visible trip
+ * between the old inline value and the new one, and hands back to that same persisted inline style
+ * on finish (fill: none resolves to identity, which is "no offset from the inline value already
+ * written"). So the rest state genuinely is held, between moves, by an inline write the same way
+ * `draggable`'s drop position is — the exact `state` shape `gestures/index.ts` established, just
+ * driven by "the followed target changed" instead of a pointer.
  */
 export declare const LAYOUT_PRESETS: Preset[];

package/dist/types/effects/motion-path/index.d.ts

@@ -0,0 +1,35 @@
+import type { Preset, Primitive } from '../../core/types.js';
+import type { Registry } from '../../core/registry.js';
+/**
+ * The one primitive. `perfClass: 'compositor'` is the shared default and is honest here:
+ * `offset-distance` is a transform-like property that Chromium animates off the main thread.
+ *
+ * `reducedMotion` is left at `cssPrimitive`'s `'shorten'`, which resolves to a 1ms animation — the
+ * element arrives at the end of its path with no motion to see, which is the right answer for a
+ * vestibular trigger and the same treatment `slide-out-up` and every other travel-and-stay effect
+ * already gets. `'disable'` would be worse, not better: it leaves the animation off entirely, so
+ * an entrance like `path-swoop` would sit permanently at its *start* — off to the lower left of
+ * where it belongs. `base.css` additionally drops `offset-path` under `disable` and in print, so
+ * a composed effect that forces that policy cannot strand a path-driven element off its mark.
+ */
+export declare const MOTION_PATH_PRIMITIVES: Primitive[];
+/**
+ * The named paths.
+ *
+ * §6.4 of the parity outline makes shipping these non-negotiable, and it is right to: a primitive
+ * that only works once the author has opened a vector editor is not a catalog entry, it is an API.
+ * Every name below animates on its own, with nothing but `data-kui="path-arc"`.
+ *
+ * The geometry is written to read at a glance — round numbers, control points that are obviously
+ * symmetrical — because these are the first thing anyone will copy and edit.
+ */
+export declare const MOTION_PATH_PRESETS: Preset[];
+/**
+ * Register the motion-path family.
+ *
+ * @param registry - Registry to populate.
+ * @returns The same registry, for chaining.
+ * @complexity O(n) time in the number of primitives and presets.
+ * @overallScore 100
+ */
+export declare function registerMotionPath(registry: Registry): Registry;

package/dist/types/effects/scroll-mechanics/params.d.ts

@@ -0,0 +1,23 @@
+import type { ParameterSchema } from '../../core/types.js';
+/**
+ * The parameter schemas shared across the scroll-mechanics primitives.
+ *
+ * Extracted from `primitives.ts`, which sits close enough to the 400-line cap that adding one
+ * parameter pushes it over. They belong together anyway: these are the knobs more than one
+ * primitive declares, and the whole point of declaring them once is that `pin` and `media-scrub`
+ * cannot drift apart on what a hold means.
+ */
+export declare const distanceParam: ParameterSchema;
+/**
+ * Shared by every primitive that has to hold still while its scroll range passes.
+ *
+ * `pin` and `media-scrub` were solving the same problem twice from opposite ends. The pin declared
+ * both of these and did the work; the scrub declared neither and left it to the page, which is why
+ * `demo/scroll.html` carried a `.scrub-stage` whose entire job was `height: 260vh` and a
+ * `.scrub-viewport` whose entire job was `position: sticky`. Two hand-written boxes to restate
+ * something the library already knew, because `distance:` was on the attribute the whole time.
+ *
+ * Declaring it once means the two cannot drift, and it is what lets a scrub become one attribute
+ * with no wrapper at all.
+ */
+export declare const stickyParams: ParameterSchema;

package/dist/types/effects/scroll-mechanics/presets.d.ts

@@ -2,5 +2,56 @@ import type { Preset } from '../../core/types.js';
 /**
  * Scroll-mechanics names. Eleven names over six primitives — the same alias-table shape the
  * entrance matrix uses, so adding a variant stays a data change.
+ *
+ * **Every name here declares `phase: 'idle'`.** This is the family the phase census flagged as
+ * hardest, because "when does this hold the channel" does not obviously map onto a visitor
+ * condition or a one-shot arrival the way an entrance or a gesture does — a scrub is driven by
+ * scroll position, which is continuous, not a boolean the way `:hover` or `[aria-expanded]` is.
+ * The question worth separating is *whether it changes* (yes, every frame) from *whether it ever
+ * hands the channel back* (no, never, for as long as the instance lives), and it is the second one
+ * `EffectPhase` actually asks.
+ *
+ * Every primitive in this file writes its claimed channel(s) **unconditionally from the moment it
+ * activates** — `preparePin`'s `installSticky` sets `position: sticky` inline the instant `prepare`
+ * runs, not the instant the element is actually in range; `prepareHorizontal`/`prepareMediaScrub`/
+ * `prepareProgress`/`prepareScrollSpy` all start writing on the very first scroll frame, which for a
+ * `load`-activated effect (their shared `defaultActivation`) is essentially immediately — and never
+ * releases it until `destroy()` tears the instance down. That is a structurally different shape from
+ * `state`: a `:hover`/drag/press effect writes *nothing at all* until the visitor's own action
+ * starts it, which is what lets an entrance's one-shot fill resolve first and hand the channel to a
+ * quiescent neighbour that has not spoken yet (`gestures/index.ts`'s `draggable` family is exactly
+ * this — silent until `pointerdown`). A scroll effect never has that silent stretch: it is live from
+ * the same instant an entrance would be trying to release into it, so treating them as taking turns
+ * (`state`'s exemption) would be describing a truce that doesn't exist. "Runs unbounded, so it never
+ * yields the channel at all" is `EffectPhase`'s own definition of `idle`, and `EffectInstance
+ * .continuous`'s doc (`core/types.ts`) already names this exact set — "a pin, a scroll progress
+ * track, a media scrub" — as the library's canonical unbounded, no-end effects. `idle` is that fact
+ * restated as a composition phase, not a new claim.
+ *
+ * `scroll-spy` earns the same label by the same test even though it writes an *attribute* rather
+ * than a style: `data-kui-active` moves between links continuously as sections cross the threshold,
+ * with no moment where nothing is marked active and the channel is free.
+ *
+ * `smooth-scroll-to` and `scroll-snap-x`/`-y` are not wrapped in `continuousSetup` — they set one
+ * declaration at `prepare` and are done, so the animator considers the *instance* finished
+ * immediately. That is orthogonal to the question here: the declaration they wrote
+ * (`scroll-behavior`, `scroll-snap-type`) stays applied inline for the instance's whole life exactly
+ * like the continuous ones, never conditionally, never released early. A permanently-held static
+ * write and a per-frame recomputed one both fail `state`'s test the same way.
+ *
+ * Declaring `idle` does not, in itself, open any new composition today — `INDEPENDENT_PHASES` in
+ * `core/channels.ts` only exempts `entrance|state` and `exit|state`, and `idle` pairs with nothing,
+ * itself included, which is the same outcome an undeclared phase already produced. What it changes
+ * is the meaning of that outcome: these thirteen collide with a channel-sharing neighbour because
+ * two effects are provably fighting over the same property at the same time (checked directly —
+ * `horizontal-scroll` and any `translate`-writing entrance both actively write `translate` from the
+ * moment the entrance would want to release, so there is no daylight to compose into), not because
+ * nothing was known about them. `test/catalog-phase-mechanics.test.ts` asserts both halves of that:
+ * the declaration is present, and a same-channel pair inside this family still correctly refuses.
+ *
+ * None of the eleven declares `transitions` — `phaseOf` (`core/compile.ts`) only ever *derives*
+ * `state` from that field, so a preset carrying both would be duplicate, driftable data, and every
+ * primitive here is `renderer: 'javascript'` with nothing rendered through a CSS `transition:` to
+ * begin with.
  */
 export declare const SCROLL_PRESETS: Preset[];

package/dist/types/effects/scroll-mechanics/section-index.d.ts

@@ -0,0 +1,47 @@
+import type { PrepareContext } from '../../core/effect-context.js';
+import type { ScrollFrame } from '../../core/scroll-scheduler.js';
+import type { Cleanup } from '../../core/types.js';
+/**
+ * Options for tracking the active section index as the scroller advances.
+ */
+export interface SectionIndexOptions {
+    el: Element;
+    sections: Element[];
+    ctx: PrepareContext;
+    offsetTop?: string;
+    onChange: (next: number, previous: number) => void;
+}
+export type SectionIndex = Cleanup & {
+    release: () => void;
+};
+/**
+ * `offset-top` resolved to pixels for one frame.
+ *
+ * Evaluated statically per frame using the scheduler's viewport metrics so viewport units
+ * like `50vh` update with resize.
+ *
+ * @complexity O(n) time in the authored value's length; O(1) space.
+ * @overallScore 100
+ */
+export declare function offsetTopPixels(authored: string, frame: ScrollFrame): number;
+/**
+ * The highest index whose content-relative top has reached the reference line.
+ *
+ * `-1` when none has — before the first section, or with no sections at all. Callers rely on this
+ * being the *only* thing that decides "active": one number, or none, never more than one.
+ *
+ * @complexity O(n) time in section count; O(1) space.
+ * @overallScore 100
+ */
+export declare function highestReachedIndex(tops: number[], scrollTop: number, line: number): number;
+/**
+ * Measure section tops once per resize epoch and report the highest reached section index on change.
+ *
+ * Shared measuring and scroll subscription half extracted from `prepareScrollSpyContainer`,
+ * reused by `scroll-spy` and `scroll-story`.
+ *
+ * @complexity O(n) time and space in section count, recomputed every frame — cheap arithmetic
+ *   against a rect cache, never a fresh layout read once per resize epoch has passed.
+ * @overallScore 100
+ */
+export declare function createSectionIndex(options: SectionIndexOptions): SectionIndex;

package/dist/types/effects/shared.d.ts

@@ -1,8 +1,168 @@
-import type { Activation, ParameterSchema, Primitive, ReducedMotionPolicy, Timeline } from '../core/types.js';
+import type { PrepareContext } from '../core/effect-context.js';
+import type { Activation, EffectParams, NamedActivation, ParameterSchema, Primitive, ReducedMotionPolicy, Timeline } from '../core/types.js';
+/**
+ * The one `delay` declaration, spread by every primitive that waits for a trigger before playing.
+ *
+ * Two spellings of an authored delay exist and they arrive by different routes. The positional
+ * one (`count-up 320ms 300ms`) rides alongside the parameter record as `params.timing` — see the
+ * design note in `core/js-effect-preparer.ts` for why timing is deliberately *not* merged into
+ * that record — while the named one (`count-up delay:300ms`) reaches a primitive only if its
+ * schema declares `delay`, and is otherwise dropped by `resolveParams` as an unknown parameter.
+ * So every primitive whose start moment is a trigger has to declare this, and declaring it is
+ * safe precisely because `0ms` is a true no-op: `readEffectParams` pre-fills every declared
+ * parameter, so a non-zero default would be indistinguishable from an authored value.
+ *
+ * Spread (`...TRIGGER_DELAY_PARAM`) rather than retyped so that rationale has one home.
+ *
+ * "Waits for a trigger" is wider than `defaultActivation: 'enter'`, which is all the structural
+ * guard in `test/js-effect-timing.test.ts` originally covered. A hover lift, an `aria-expanded`
+ * icon toggle and a FLIP reorder all default to `'load'` — they install listeners or an observer
+ * at load — yet each has a perfectly definite start moment later on (the pointer arrives, the
+ * attribute flips, the children move), and "start 200ms after that moment" is a coherent request
+ * for every one of them. `test/js-effect-timing-parity.test.ts` now guards both groups; its
+ * `TIMING_REFUSALS` table names the primitives that genuinely have no start moment and must *not*
+ * pick this up.
+ */
+export declare const TRIGGER_DELAY_PARAM: ParameterSchema;
+/** The three positional timing tokens of the grammar: `data-kui="fade-up 600ms 200ms linear"`. */
+export type TimingToken = 'duration' | 'delay' | 'ease';
+/** All three, in grammar order. Also the `honours` list of a primitive that supports the lot. */
+export declare const ALL_TIMING_TOKENS: readonly TimingToken[];
+/**
+ * What a JS-rendered primitive can actually *do* with authored timing.
+ *
+ * The problem this closes: the two spellings of a timing value fail differently, and one of them
+ * fails silently. `pin-section delay:300ms` reaches `readParams`, is not in the schema, and warns
+ * as an unknown parameter — the author is told. `pin-section 0ms 300ms` parses into
+ * `spec.delay`, is lifted out to `params.timing` (see `core/js-effect-preparer.ts`), and is then
+ * simply never read by a primitive that has no clock to shift. Nothing warns, nothing happens,
+ * and the page gives the author no way to find out which of those two it was.
+ *
+ * So a primitive that cannot honour a token has to say so, and it has to say so about the
+ * positional spelling too. Declaring the contract is how it does that.
+ */
+export interface TimingContract {
+    /**
+     * Tokens this primitive genuinely acts on. Anything omitted warns by name when authored.
+     * Omit the field entirely for a primitive that honours none of the three.
+     */
+    honours?: readonly TimingToken[];
+    /**
+     * Completes `"<id>" cannot honour <token>: <because>`. Write the *reason*, not the symptom —
+     * "it tracks pointer position continuously, so there is no start moment to delay" tells an
+     * author to stop looking for a spelling that works, where "unsupported" does not.
+     */
+    because: string;
+}
+/**
+ * How long an effect waits after its trigger before it starts, in milliseconds.
+ *
+ * The named form of the pattern `text.ts` spells out at three call sites —
+ * `params.timing.delayMs ?? params.ms('delay', 0)` — and the sibling of
+ * `core/js-params.ts`'s `effectDurationMs`. Two spellings, one intent: `split-flap 400ms 200ms`
+ * and `split-flap 400ms delay:200ms` mean the same thing, and the positional one is what `play()`
+ * emits, so it is the one that must not be the one dropped.
+ *
+ * It lives here rather than beside `effectDurationMs` only because `src/core/` is being edited in
+ * parallel; the two belong together and should be moved once that settles.
+ *
+ * @param fallback - Used when the author wrote neither spelling. Effectively always `0`.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function effectDelayMs(params: EffectParams, fallback?: number): number;
+/**
+ * The curve an effect runs on, preferring the positional token over the same-named parameter.
+ *
+ * The easing half of the same story. A primitive reading only `params.text('ease')` sees
+ * `flip-shuffle ease:linear` and not `flip-shuffle 400ms 0ms linear`, which is the identical
+ * request written the way the grammar puts it first.
+ *
+ * @param fallback - Used when the author wrote neither spelling.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function effectEasing(params: EffectParams, fallback?: string): string;
+/**
+ * Copy the honoured positional tokens onto the primitive's own namespaced custom properties.
+ *
+ * Only the `key:value` spelling reaches CSS on its own: `compile.buildPlan` runs `resolveParams`
+ * over `spec.params` for every effect, but `pushTrack` — which is where `spec.duration`/`.delay`/
+ * `.easing` are turned into declarations — runs for `css-keyframes` primitives only. So a
+ * stylesheet-driven JS primitive sees `lift duration:400ms` and not `lift 400ms`, which is the
+ * same value written the other way round.
+ *
+ * Written through the ledger and therefore restored on teardown, and written *after*
+ * `applyStylePlan` has already put any `key:value` overrides inline — so the positional spelling
+ * wins a collision, matching `effectDurationMs`'s `params.timing.durationMs ?? params.ms(...)`
+ * precedence rather than contradicting it.
+ *
+ * Takes the whole context rather than the ledger off it so that an unauthored effect never
+ * dereferences `ctx` at all. That is not fastidiousness: `test/three-d.test.ts` calls the
+ * state-driven presets' `prepare` with no element and no context, asserting that the default path
+ * reaches for neither, and a caller like `prepareCardToggle` runs this before it knows whether it
+ * has anything else to do.
+ *
+ * @complexity O(1) time and space — three tokens, fixed.
+ * @overallScore 100
+ */
+export declare function mirrorTimingToCss(id: string, honours: readonly TimingToken[], params: EffectParams, ctx: PrepareContext): void;
+/**
+ * Wrap a primitive's own `prepare` so authored timing it cannot act on warns instead of vanishing.
+ *
+ * For primitives that drive their own frames. The wrapped `prepare` still does all the work; this
+ * only adds the diagnostics, which is why it composes with `deferPrepare` rather than replacing it.
+ *
+ * @param id - The primitive's id, named in the warning.
+ * @param contract - What this primitive honours, and why it cannot honour the rest.
+ * @param prepare - The primitive's real setup.
+ * @complexity O(1) time and space beyond the wrapped call.
+ * @overallScore 100
+ */
+export declare function withTimingContract(id: string, contract: TimingContract, prepare: NonNullable<Primitive['prepare']>): NonNullable<Primitive['prepare']>;
+/**
+ * The `prepare` for a primitive whose motion is a stylesheet transition or keyframe rather than
+ * frames this library drives — the hover family, the icon toggles, the flip card.
+ *
+ * These used to be `prepare: () => inertInstance()`, registered purely so the name parses and
+ * `data-kui-fx` gets stamped. That was almost right: the *named* spelling of a timing parameter
+ * already reaches their CSS through `resolveParams`, so there was nothing for JS to do. The
+ * positional spelling had no route at all, which is the gap this closes — plus the warning for
+ * whichever tokens the shipped rule pins (a linear spin's `ease`, say).
+ *
+ * @param id - The primitive's id; also the namespace of the properties written.
+ * @param contract - Which tokens the stylesheet actually reads, and why it ignores the others.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function stylesheetTimingPrepare(id: string, contract: TimingContract): NonNullable<Primitive['prepare']>;
+/**
+ * "Accepts every timeline, is driven by none of them."
+ *
+ * A few primitives have no relationship to progress at all: `background-media` paints a backdrop,
+ * and the scroll-mechanics drivers read the scroll position themselves rather than being driven by
+ * an `animation-timeline`. None of them ever reads `Timeline`.
+ *
+ * They still have to *accept* one, because `compile.ts`'s `intersect` narrows a composed element's
+ * timeline support to what every primitive on it supports. Declaring the honest answer — `['time']`,
+ * or nothing — empties that intersection for `data-kui="background-media src:/hero.mp4, parallax"`
+ * with `timeline:view`, `style-plan.ts` then refuses the timeline, and the neighbour's scrub
+ * silently degrades to a one-shot. Nothing is wrong with either effect; the intersection is simply
+ * the wrong question to ask of a primitive that has no opinion.
+ *
+ * So the list stays exhaustive and this name is what makes it truthful. Written out inline it reads
+ * as a claim to support all four — the same lie in four places, each needing its own paragraph to
+ * walk back. Written as `supportedTimelines: TIMELINE_AGNOSTIC` it reads as what it is: an
+ * abstention, not a claim.
+ *
+ * One shared array instance, like `ENTRANCE_TIMELINES` in `catalog/core.ts`. Every consumer
+ * (`intersect`, `warnUnsupportedTimeline`) only reads it.
+ */
+export declare const TIMELINE_AGNOSTIC: Timeline[];
 export interface CssPrimitiveOptions {
     parameters?: ParameterSchema;
     timelines?: Timeline[];
-    activations?: Activation[];
+    activations?: NamedActivation[];
     defaultActivation?: Activation;
     reducedMotion?: ReducedMotionPolicy;
     perfClass?: Primitive['perfClass'];

package/dist/types/effects/step-index.d.ts

@@ -0,0 +1,121 @@
+import type { Cleanup, EffectParams } from '../core/types.js';
+import type { PrepareContext } from '../core/effect-context.js';
+import type { TargetScope } from '../core/target.js';
+export interface StepIndexOptions {
+    el: Element;
+    params: EffectParams;
+    ctx: PrepareContext;
+    scope: TargetScope;
+    resolveSteps: () => Iterable<Element>;
+    onRender?: (index: number, total: number) => void;
+    clickFallback?: boolean;
+    name?: string;
+}
+export interface StepIndex {
+    goTo(index: number): void;
+    next(): void;
+    prev(): void;
+    current(): number;
+    total(): number;
+    release(): void;
+}
+/**
+ * Advance a step index, wrapping back to 0 — pure, so the wrap rule is assertable without a DOM.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function nextStep(step: number, total: number): number;
+/**
+ * Step backwards, wrapping to the last index — the mirror of `nextStep`, and pure for the same
+ * reason: the wrap is the whole of the rule and it is worth asserting without a DOM.
+ *
+ * `+ total` before the modulo rather than a `< 0` branch: `-1 % 5` is `-1` in JS, not `4`, so the
+ * naive mirror of `nextStep` silently produces a negative index that marks nothing and reads as a
+ * dead control rather than an error.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function prevStep(step: number, total: number): number;
+/**
+ * Clamp an authored or computed index into range, wrapping the same way the steppers do.
+ *
+ * `jump:` takes its index from a control's position among its siblings, which is trustworthy —
+ * but `steps:` is authored separately, so a page with six dots and `steps:4` would otherwise set
+ * an index no step element has. Wrapping rather than clamping keeps one rule across all three
+ * controls instead of two.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function clampStep(step: number, total: number): number;
+/**
+ * How many steps there are, asked freshly on each call rather than fixed at setup.
+ *
+ * `steps:` used to be required and defaulted to 4, which is the wrong shape for a deck: the number
+ * is not a *choice* an author makes, it is a fact about how many slides they wrote, and stating it
+ * twice means a sixth slide that silently never gets reached. Counting instead makes `steps:` an
+ * override for the case the elements cannot answer — and asking per flip rather than once means a
+ * slide added after setup is picked up, matching `createStepMarker`, which already re-resolves per
+ * flip for exactly that reason.
+ *
+ * Counted per *parent*, taking the largest group, not as a flat total. `target:` routinely names
+ * two parallel groups — the slides and the dots that track them — and a flat count of a five-slide
+ * deck with five dots is ten. Per-parent is also precisely how the marker numbers them, so the
+ * count and the marking cannot disagree.
+ *
+ * Exported for `effects/carousel`, which drives an index over the same shape of markup and must
+ * count it the same way. A second implementation of "how many slides are there" is exactly the
+ * drift `createStepMarker` was extracted to end for the marking half.
+ *
+ * @complexity O(n) time and space in the matched elements.
+ * @overallScore 100
+ */
+export declare function countSteps(params: EffectParams, resolveSteps: () => Iterable<Element>): number;
+/** One named control group: the selector the author wrote, and what pressing a match does. */
+export interface ControlGroup {
+    selector: string;
+    /** @param position - The pressed control's place among its own group, in document order. */
+    run: (node: Element, position: number) => void;
+}
+/**
+ * Bind every named control group with a *single* delegated listener on the scope root.
+ *
+ * One listener per matched node was the obvious form and it had a hole with no warning attached:
+ * the nodes are matched once, at prepare time, so a dot rendered afterwards was inert forever. The
+ * arrows kept working — they ask `countSteps` for the total on every press, so they reached the new
+ * slide fine — which made the failure look like "the dots are broken" rather than "controls are
+ * bound once". Delegation removes the setup-time snapshot entirely: a control is whatever matches
+ * the selector at the moment of the press, which is the same rule `resolveSteps` and `countSteps`
+ * already follow, and it collapses teardown from N removals to one.
+ *
+ * The root is the *scope* root, not simply the host. Under the page scope `step-progress` has
+ * always resolved with, a control may legitimately sit outside the element it drives — arrows in a
+ * section header above the deck — and a listener on the host would never see those clicks.
+ *
+ * Exported for `effects/carousel` alongside `countSteps`: `next:`/`prev:`/`jump:` mean the same
+ * thing on a ring as they do on a bar, and every subtlety in the walk below (the `:scope` root, the
+ * per-press re-query, the `scope:self` containment) was found once and should not be found again.
+ *
+ * @returns The teardown for the one listener.
+ * @complexity O(g × (m + d)) per click — one scoped query and one ancestor walk per named group,
+ *   in that group's matches `m` and the pressed node's depth `d`; O(m) space for the largest group.
+ * @overallScore 100
+ */
+export declare function delegateControls(request: {
+    el: Element;
+    ctx: PrepareContext;
+    scope: TargetScope;
+    groups: ControlGroup[];
+}): Cleanup;
+/**
+ * Shared step index for click-driven steppers and showcase slideshows.
+ *
+ * Re-queries steps on every render so added or removed slides cannot leave stale marks. The
+ * optional render hook lets a widget mirror the selected index into ARIA without owning it twice.
+ *
+ * @complexity O(n) per render in the step and control groups; O(n) marker storage.
+ * @overallScore 100
+ */
+export declare function createStepIndex(options: StepIndexOptions): StepIndex;