kuinetic 0.2.1 → 0.2.3

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

@@ -1,5 +1,6 @@
 import type { Preset, Primitive } from '../../core/types.js';
 import type { Registry } from '../../core/registry.js';
+export { snapPosition } from './deck.js';
 /**
  * Whether a slot at this ring angle has its own plane turned away from the camera.
  *
@@ -24,25 +25,6 @@ export declare function faceAt(angleDeg: number): 'front' | 'back';
  * @complexity O(1) time and space.
  */
 export declare function normaliseDegrees(angleDeg: number): number;
-/**
- * Where the ring's continuous position rounds to, and how far past it the ring currently sits.
- *
- * The pair the stylesheet needs and the reason both tokens are published rather than one: the
- * integer decides which slot is *live* (and therefore what `--kui-offset` means for every other
- * slot), and the remainder is the sub-step rotation on top of it. Re-snapping the integer whenever
- * the remainder passes a half step is what keeps the remainder inside ±0.5, so the ring never has
- * to travel back across the whole strip to wrap from the last slide to the first — the same
- * property `circularOffset` gives the discrete case.
- *
- * @param position - Continuous ring position, in places. May be negative or beyond the count.
- * @param total - How many places the ring has.
- * @returns The live integer step, wrapped into range, and the signed remainder in `[-0.5, 0.5)`.
- * @complexity O(1) time and space.
- */
-export declare function snapPosition(position: number, total: number): {
-    step: number;
-    drift: number;
-};
 /**
  * An authored `<angle>` as a number of degrees.
  *
@@ -65,8 +47,9 @@ export declare function degreesOf(value: string, fallbackDeg: number): number;
 /**
  * The ring primitive.
  *
- * `renderer: 'javascript'` and two channels together are the honest declaration: this file paints
- * nothing itself — it publishes numbers — but `carousel.css` does, and both of the things it writes
+ * `renderer: 'javascript'` and its channels together are the honest declaration: this file paints
+ * nothing itself — it publishes numbers (and the `data-kui-step` index, its third channel) — but
+ * `carousel.css` does, and both of the things that stylesheet writes
  * have to be declared or the conflict detector waves through a composition that silently loses one
  * effect's output.
  *
@@ -116,7 +99,7 @@ export declare const CAROUSEL_PRIMITIVES: Primitive[];
  *
  * `phase: 'idle'` on all of them too, and for the same reason `target` does not change the answer:
  * `channelsFor`/`findConflicts` (`core/channels.ts`) reason about the channels *this preset
- * declares* on the host it is authored on (`CHANNEL.skew` and `'discrete'`, from
+ * declares* on the host it is authored on (`CHANNEL.skew`, `'discrete'` and `data-kui-step`, from
  * `SPATIAL_RING_PRIMITIVE`), not about which element in the subtree physically paints them — the
  * compiler has no notion of "the primitive's own target moved the real work three nodes down," and
  * does not need one here, because `requiresOwnSubtree` already keeps this preset off of anything
@@ -135,7 +118,7 @@ export declare const CAROUSEL_PRIMITIVES: Primitive[];
  * over the `transform` shorthand (`CHANNEL.skew`) for the ring's whole lifetime, and there is no
  * turn-taking to model. It replaces "nothing is known" with the actual, checked fact.
  *
- * None of the four declares `transitions`: nothing here renders through a CSS `transition:` on the
+ * None of them declares `transitions`: nothing here renders through a CSS `transition:` on the
  * host box for `phaseOf` to derive `state` from — the ring is `renderer: 'javascript'` throughout.
  */
 export declare const CAROUSEL_PRESETS: Preset[];

package/dist/types/effects/carousel/stack.d.ts

@@ -0,0 +1,77 @@
+import type { Preset, Primitive } from '../../core/types.js';
+import type { Face } from './deck.js';
+/**
+ * A deck of cards receding diagonally into depth — the front card large and sharp, each one behind
+ * it stepped up and to the side, smaller, softer and fainter — that cycles forward: the front card
+ * leaves toward the viewer and the next one comes up to take its place.
+ *
+ * ## Why a primitive of its own, sharing the ring's deck
+ *
+ * The *index* is the ring's exactly: N slots, a live one, a signed place for every other, a real-
+ * valued position a drag moves between two places, `next:`/`prev:`/`jump:`, the keyboard, `spin:`
+ * and `autoplay:`. All of that is `deck.ts`, shared, so the two can never disagree about where a
+ * deck is. What differs is not a parameter of the ring's shape but a different shape:
+ *
+ * - **It is linear, not circular.** A ring spaces its slots by `arc / count` and has no front or
+ *   back in the index; a stack has a front, and the slots behind it are *further*, not *around*.
+ *   Not one of the ring's seven geometry parameters (`tilt`, `arc`, `radius`, `gap`, `perspective`,
+ *   `facing`, `plane`) means anything for it, and none of its six means anything for a ring.
+ * - **It paints more channels.** Receding cards blur and fade, so a stack writes `filter` and
+ *   `opacity` on its slots as well as `transform`. Declaring those on the ring primitive would have
+ *   made every existing `carousel-3d` start colliding with any opacity or filter effect composed
+ *   beside it — a behaviour change to four shipped names in order to add a fifth.
+ *
+ * So: one deck, two primitives, each declaring only its own geometry and its own channels.
+ *
+ * ## Which cards are showing
+ *
+ * The marker publishes circular offsets (`-N/2 … N/2`), which suits a ring. A stack reads them
+ * shifted — `mod(offset + 1, N) - 1`, in `carousel.css` — onto `-1 … N-2`: the live card at 0,
+ * `depth` cards visible behind it, and exactly one place *in front*, for the card that has just
+ * left. The wrap from the front to the back therefore happens between `-1` (faded out in front)
+ * and `N-2` (faded out behind), so a card being recycled never crosses the visible stack. With
+ * fewer than `depth + 3` cards the back slot is still visible when it arrives, and the recycled card
+ * fades in there as it lands, which is the honest limit of a short deck.
+ */
+/**
+ * Whether a slot at this stack place is showing: in front of the fade-out behind the last visible
+ * card, and not yet gone out past the viewer.
+ *
+ * Pure and exported so the boundaries are assertable without a DOM. Mirrors the opacity ramp in
+ * `carousel.css`: a card that has left is gone by half a place in front, and the back of the stack
+ * fades out over the one place past `depth`.
+ *
+ * @param offset - The slot's circular offset, as the marker published it.
+ * @param drift - The deck's sub-step position past the live place.
+ * @param count - The deck's size.
+ * @param depth - How many cards show behind the front one.
+ * @returns `'front'` while any of the card shows, `'back'` once none of it does.
+ * @complexity O(1) time and space.
+ */
+export declare function stackFace(offset: number, drift: number, count: number, depth: number): Face;
+/**
+ * A circular offset re-read as a place in the stack: `0` in front, `1…N-2` behind, `-1` just left.
+ *
+ * The JavaScript twin of `carousel.css`'s `mod(offset + 1, N) - 1`; the two must agree, and this is
+ * the one the tests pin.
+ *
+ * @complexity O(1) time and space.
+ */
+export declare function stackPlace(offset: number, count: number): number;
+/**
+ * The stack primitive.
+ *
+ * `skew` for the `transform` shorthand (the scale and the diagonal step compose in one function
+ * list), `opacity` and `filter` for the recession, `discrete` for the host's `display: grid` — the
+ * same reasoning `SPATIAL_RING_PRIMITIVE` gives for its own pair, widened by what a stack paints.
+ * `reducedMotion: 'shorten'` for the same reason as the ring: the deck must keep working, and the
+ * policy layer already shortens the transition, while `deck.ts` starts any auto-motion paused.
+ */
+export declare const SPATIAL_STACK_PRIMITIVE: Primitive;
+/**
+ * `carousel-stack` — the family name first, the shape second, as `carousel-fade`/`carousel-slide`/
+ * `carousel-3d` already read. One name: the diagonal's direction is two signed lengths (`shift:`,
+ * `rise:`), so a left-hand or downward stack is a parameter, not a catalogue entry. `requiresOwnSubtree`
+ * and `phase: 'idle'` for the reasons `CAROUSEL_PRESETS` gives for the ring.
+ */
+export declare const STACK_PRESETS: Preset[];

package/dist/types/effects/catalog/interaction-reveal.d.ts

@@ -1,4 +1,57 @@
 import type { Preset, Primitive } from '../../core/types.js';
+/**
+ * ### `PLACEMENT` — `place:top|bottom|auto`, and the one piece of JavaScript it costs
+ *
+ * `label-swap`'s and `anchored-preview`'s doc comments both record why a placement *keyword* was
+ * once refused: CSS cannot branch on a custom property's value without `@container style()`, so
+ * the word has to be read by script. That is still true, and this is the script — kept to the one
+ * job CSS genuinely cannot do, so the geometry itself stays in the stylesheet.
+ *
+ * The script never writes a length. It stamps the *resolved side* as an attribute on the host
+ * (`data-kui-hint-place` / `data-kui-preview-place`), and `interaction.css` keys the geometry on
+ * `[data-kui-fx][data-kui-…-place='…']`: a compound on the host itself, no combinator, so the
+ * `INHERITED_STATE` contract above holds. The `[data-kui-fx]`
+ * half lifts the rule to two attributes of specificity, which is what lets an explicit side beat
+ * an `anchored-preview-left` preset rule regardless of source order.
+ *
+ * A fixed side is stamped once at activation. Measuring happens only when the part is about to be
+ * seen: on `pointerenter`/`focusin`, the two events that precede every state the stylesheet reveals
+ * on (`:hover`, `:focus-visible`, and the coarse-pointer `:active`, which a touch `pointerenter`
+ * also precedes). While shown, a passive capture-phase `scroll` and a `resize` listener re-measure
+ * at most once per frame, because the reader can scroll a hovered trigger into the viewport edge;
+ * both are removed the moment neither hover nor focus remains. Nothing runs per frame while the
+ * part is hidden. `auto` measures which side; every side, fixed or not, measures `SHIFT` below.
+ *
+ * The flip is along the preferred side's own axis only — top↔bottom, left↔right. Moving a
+ * left-anchored preview to the top is a different layout, not a correction of this one.
+ */
+type Side = 'top' | 'bottom' | 'left' | 'right';
+/**
+ * Pick the side a part should sit on, given the room around its trigger.
+ *
+ * The preferred side wins whenever the part fits there. When it does not, the opposite side is
+ * taken only if it has *more* room — not merely if it fits — so a part too big for either side
+ * lands where the least of it is clipped rather than flipping to a side that clips more.
+ *
+ * @param preferred - The side to try first.
+ * @param room - Free space, in CSS px, between each edge of the trigger and the viewport.
+ * @param extent - How far the part reaches from the trigger along its axis, gap included.
+ * @complexity O(1) time and space.
+ */
+export declare function chooseSide(preferred: Side, room: Record<Side, number>, extent: number): Side;
+/**
+ * How far to move a span on one axis so it sits inside `[margin, viewport - margin]`.
+ *
+ * A span longer than that room cannot fit either way, so it is aligned to the start edge — the
+ * reading edge, where its first words are.
+ *
+ * @param start - The span's start coordinate in the viewport, unshifted, in CSS px.
+ * @param size - Its length on the same axis.
+ * @param viewport - The viewport's length on that axis.
+ * @returns The signed offset to add, `0` when it already fits.
+ * @complexity O(1) time and space.
+ */
+export declare function shiftWithin(start: number, size: number, viewport: number, margin?: number): number;
 /**
  * The masked label swap: two stacked copies of a label in a clipped box, one sliding out as the
  * other slides in.
@@ -148,15 +201,15 @@ export declare const HOVER_INTENT_PRESETS: Preset[];
  * That mechanism needs no feature detection and no fallback branch, because it already works in
  * every browser the rest of the catalog does.
  *
- * ### Why four preset names and not a `placement:` parameter
+ * ### Four preset names, and a `place:` parameter behind them
  *
- * The same reasoning `label-swap`'s own doc comment gives for its axis: CSS cannot branch on a
- * custom property's *value* without `@container style()`, which is not portable enough to build a
- * shipped effect on. A `placement:` keyword would have to be read by JavaScript, turning a pure
- * stylesheet effect into a JS one for the sake of one word. Four preset names cost nothing extra —
- * they share this one primitive's schema, timing namespace, reduced-motion policy and channel
- * claim — and it is how the rest of the catalog already spells "one mechanism, several fixed
- * shapes" (`masked-label-swap-x`/`-diagonal`, `card-flip-x`/`-y`, `flip-in-x`/`-y`).
+ * The four names came first, for the reasoning `label-swap`'s own doc comment gives for its axis:
+ * CSS cannot branch on a custom property's *value*, so a placement keyword has to be read by
+ * JavaScript. `place:auto` — flip to whichever side fits the viewport — is a measurement CSS cannot
+ * make at all, so that JavaScript now exists (`PLACEMENT`, above), and the names became four
+ * spellings of `place:` (each preset carries its side in `params`). They stay because they are how
+ * the rest of the catalog spells "one mechanism, several fixed shapes" (`masked-label-swap-x`,
+ * `card-flip-y`), and because the stylesheet still places them before any script has run.
  *
  * `anchored-preview` (no suffix) is `top`, matching `hover-intent`'s own default placement for the
  * same reason: a name tag or a tooltip reads naturally above its trigger unless told otherwise.
@@ -171,7 +224,13 @@ export declare const HOVER_INTENT_PRESETS: Preset[];
  * absolute; inset: var(--kui-anchored-preview-inset); translate: var(--kui-anchored-preview-travel)`
  * and nothing placement-specific. No rule anywhere carries a combinator after an fx compound, so
  * `anchored-preview` never enters the reaching-selector set `css-requires-own-subtree.test.ts`
- * derives, needs no `requiresOwnSubtree`, and `target:` relocates all four cleanly.
+ * derives and needs no `requiresOwnSubtree`.
+ *
+ * ### `target:` names the preview
+ *
+ * `data-kui="anchored-preview-bottom target:.preview-img"` needs no `data-kui-preview` in the
+ * markup: the effect stays on the trigger and the library stamps the marker on the match, then
+ * takes it off again on teardown — see `claimPart`.
  *
  * ### Channels
  *
@@ -246,3 +305,4 @@ export declare const SEARCH_EXPAND_PRESETS: Preset[];
 /** All four reveal-shaped families, for `interaction.ts`'s catalog-wide exports. */
 export declare const REVEAL_PRIMITIVES: Primitive[];
 export declare const REVEAL_PRESETS: Preset[];
+export {};

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

@@ -15,8 +15,7 @@ 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';
+export { nextStep, prevStep, clampStep, countSteps } from '../step-index.js';
 /**
  * The only member of the family that is not `reducedMotion: 'disable'`, and the difference is the
  * whole widget.

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

@@ -41,10 +41,9 @@ import type { Registry } from '../../core/registry.js';
  *   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
+ * - `swipeable` (`swipe`, `swipe-x`, `swipe-y`) and `pressable` (`long-press`) write an attribute,
+ *   not a CSS property, and their *channel* names it (`attributeChannel` in `core/types.ts`) —
+ *   which is unrelated to this `state` *phase*. `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

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

@@ -1,4 +1,5 @@
 import type { PrepareContext } from '../core/effect-context.js';
+import type { TimingContract, TimingToken } from '../core/timing-contract.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.
@@ -24,36 +25,8 @@ import type { Activation, EffectParams, NamedActivation, ParameterSchema, Primit
  * 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;
-}
+export { ALL_TIMING_TOKENS } from '../core/timing-contract.js';
+export type { TimingContract, TimingToken } from '../core/timing-contract.js';
 /**
  * How long an effect waits after its trigger before it starts, in milliseconds.
  *

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

@@ -1,15 +1,29 @@
 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;
+    /**
+     * The steps, already scoped by the caller's `scope:`. Controls take no scope — see
+     * `core/target.ts`'s `queryControls`.
+     */
     resolveSteps: () => Iterable<Element>;
     onRender?: (index: number, total: number) => void;
     clickFallback?: boolean;
     name?: string;
+    /**
+     * Further control groups bound through the same delegated listener as `next:`/`prev:`/`jump:` —
+     * a deck's `pause:` (`auto-motion.ts`). Like the three, naming one retires the click-the-container
+     * fallback: a pause button inside the deck would otherwise also advance it on every press.
+     */
+    controls?: readonly ControlGroup[];
+    /**
+     * Called before a *person* moves the index — a named control or the container click — and never
+     * for `goTo`/`next`/`prev` called from code. How a deck's autoplay yields to the visitor without
+     * mistaking its own timer for one.
+     */
+    onInput?: () => void;
 }
 export interface StepIndex {
     goTo(index: number): void;
@@ -80,7 +94,28 @@ export interface ControlGroup {
     run: (node: Element, position: number) => void;
 }
 /**
- * Bind every named control group with a *single* delegated listener on the scope root.
+ * Read one control parameter into a group, or `null` when it is not authored or not usable.
+ *
+ * The one place a control selector is resolved, for every deck: `next:`/`prev:`/`jump:` on the
+ * step deck and the spatial decks, and `pause:` (`auto-motion.ts`). Where it is then *searched* is
+ * {@link queryControls}' rule — inside the host first, the page only when nothing inside matches —
+ * and deliberately not `scope:`, which is the steps' alone (see that function for why).
+ *
+ * Registered even when nothing matches yet, with a warning: a control the page renders after setup
+ * is still reached, because {@link delegateControls} re-queries on every press.
+ *
+ * @param label - The effect name an author would recognise, for the warning.
+ * @complexity O(n) in one setup query's matches; O(1) space beyond the group.
+ * @overallScore 100
+ */
+export declare function bindControl(request: {
+    el: Element;
+    ctx: PrepareContext;
+    params: EffectParams;
+    label: string;
+}, param: string, run: ControlGroup['run']): ControlGroup | null;
+/**
+ * Bind every named control group with a *single* delegated listener.
  *
  * 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
@@ -90,23 +125,26 @@ export interface ControlGroup {
  * 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.
+ * Two listeners, each owning half the presses. A control may sit outside the element it drives —
+ * arrows in a section header, one pause button for a band of rings — which {@link queryControls}
+ * reaches by falling back to the page, so the document listens for presses *outside* the host. The
+ * host listens for presses inside itself, which keeps a detached or shadow-hosted deck working and
+ * bounds the walk below at the host: with no control inside, a wrapper *around* the deck that
+ * matches `next:` is a page match, and an unbounded walk from a press on a slide would climb into
+ * it and step the deck on every press. Each press is handled by exactly one of the two.
  *
  * 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.
+ * per-press re-query, the containment at the host) 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,
+ * @returns The teardown for both listeners.
+ * @complexity O(g × (m + d)) per click — at most two queries 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;
 /**

package/dist/types/effects/swipe-event.d.ts

@@ -0,0 +1,75 @@
+import type { Cleanup } from '../core/types.js';
+import type { Direction } from '../core/gesture.js';
+/**
+ * How a swipe reaches a deck it does not sit on.
+ *
+ * A swipe either shares the deck's element (`data-kui="swipe-y, carousel"` — the two write
+ * different attributes, so the channel check lets them compose) or sits on a wrapper around it.
+ * Either way the last step — "a left flick means next" — was left to every page, as a
+ * `MutationObserver` on `data-kui-swipe` that each one wrote slightly differently.
+ *
+ * ## Why an event from the swipe, heard by the deck
+ *
+ * The two alternatives both put the knowledge in the wrong place:
+ *
+ * - **The swipe steps the deck.** `swipeable` would have to find decks below it and call into
+ *   their index, which makes the gesture primitive know what a carousel is, and makes every future
+ *   stepper (a tab set, a gallery) an edit to the gesture module.
+ * - **A deck parameter naming its swipe** (`swipe:'.shell'`). A second selector to keep in sync
+ *   with markup that already says it — the deck is *inside* the swipe — and a deck and its wrapper
+ *   cannot drift apart if nothing names the other.
+ *
+ * An event inverts it cleanly: the swipe announces "left, here" and knows nothing about decks; a
+ * deck listens and decides whether the swipe was about it. It bubbles, so a page can still hear it
+ * without a `MutationObserver`, and the attribute stays exactly as it was for CSS.
+ *
+ * The deck listens on its document rather than on an ancestor because it cannot know which ancestor
+ * will be the swipe, and because the two start in either order — a listener on the document is
+ * already there whichever element's effect prepares first.
+ */
+/** The event a swipe dispatches on its own element. `detail.direction` is the flick. */
+export declare const SWIPE_EVENT = "kui:swipe";
+/** The payload of {@link SWIPE_EVENT}. */
+export interface SwipeDetail {
+    direction: Direction;
+}
+/**
+ * Announce a recognised swipe from `el`.
+ *
+ * Built with the element's own realm's `CustomEvent`, so a deck in an iframe hears a swipe
+ * dispatched there.
+ *
+ * @complexity O(depth) for the bubble; O(1) space.
+ */
+export declare function announceSwipe(win: Window, el: Element, direction: Direction): void;
+/**
+ * Which way a swipe moves a deck: the content follows the finger, as on any native pager.
+ *
+ * A flick left or up drags the next slide in (`1`); right or down brings the previous one back
+ * (`-1`). Pure and exported so the mapping is assertable without a gesture.
+ *
+ * @complexity O(1) time and space.
+ */
+export declare function swipeStep(direction: Direction): 1 | -1;
+/**
+ * Whether a swipe announced by `source` is about the deck `el`.
+ *
+ * It is when the swipe is on the deck itself, or contains it with no other deck between them. The
+ * self case is checked first because the walk below starts at the deck's parent and so would never
+ * meet a swipe on the deck: it would climb to the root and refuse at any outer deck. The second half is
+ * what keeps a swipe on a page of decks-within-decks from stepping every level at once: an inner
+ * deck (a gallery inside one slide of an outer one) is reached by its outer deck first, and the
+ * outer deck is the one the wrapper was put around. A deck is recognised by `data-kui-step`, the
+ * attribute every stepper in this library publishes on its own host.
+ *
+ * @complexity O(d) in the depth between the deck and the swipe; O(1) space.
+ */
+export declare function swipeReaches(source: Element, el: Element): boolean;
+/**
+ * Step a deck whenever a swipe around it is announced.
+ *
+ * @param step - Called with `1` for next and `-1` for previous.
+ * @returns Removes the listener.
+ * @complexity O(1) to install; O(d) per swipe (see {@link swipeReaches}).
+ */
+export declare function stepOnSwipe(doc: Document, el: Element, step: (direction: 1 | -1) => void): Cleanup;

package/dist/types/index.d.ts

@@ -1,5 +1,7 @@
 import { Animator } from './core/animator.js';
 import type { AnimatorOptions } from './core/animator.js';
+import type { DescribedStep, EffectDescription, ElementDescription, ParamNotes } from './core/describe.js';
+import type { Registry } from './core/registry.js';
 export * from './core/index.js';
 export { COMBOS, PRESETS, PRIMITIVES, createRegistry } from './effects/index.js';
 /**
@@ -14,3 +16,27 @@ export { COMBOS, PRESETS, PRIMITIVES, createRegistry } from './effects/index.js'
  */
 export declare function kuinetic(options?: AnimatorOptions): Animator;
 export default kuinetic;
+export interface DescribeOptions {
+    /** Defaults to the bundled catalog. Pass `window.__kuinetic.registry` to include tier effects. */
+    registry?: Registry;
+    /** The plain-words table from the separate notes entry (`kuineticNotes.PARAM_NOTES`). */
+    notes?: ParamNotes;
+}
+/**
+ * Every parameter a reader could write for one effect name — see `core/describe.ts`.
+ *
+ *   kuinetic.describe('hover-intent', { notes: kuineticNotes.PARAM_NOTES })
+ *
+ * @returns `undefined` when the name is not registered.
+ */
+export declare function describe(name: string, options?: DescribeOptions): EffectDescription | undefined;
+/**
+ * {@link describe} for every step of a whole `data-kui` value, parsed exactly as the runtime
+ * parses it: `describeSteps('fade-up 600ms, lift')`. Each step also says what it `written`.
+ */
+export declare function describeSteps(value: string, options?: DescribeOptions): DescribedStep[];
+/**
+ * {@link describeSteps}, plus the reserved keys (`on:`, `timeline:`, `at:` …) and which of the
+ * element-wide ones this value sets: `describeElement('fade-up on:click, lift')`.
+ */
+export declare function describeElement(value: string, options?: DescribeOptions): ElementDescription;

package/dist/types/notes/catalog-core.d.ts

@@ -0,0 +1,3 @@
+import type { ParamNotes } from '../core/describe.js';
+/** `effects/catalog/core.ts` and `effects/catalog/feedback.ts` (entrance, scroll-linked and feedback effects). */
+export declare const CATALOG_CORE_NOTES: ParamNotes;

package/dist/types/notes/catalog.d.ts

@@ -0,0 +1,3 @@
+import type { ParamNotes } from '../core/describe.js';
+/** `effects/catalog/ambient.ts`, `media.ts`, `materials.ts`, `transforms.ts`, `view-transitions.ts`. */
+export declare const CATALOG_NOTES: ParamNotes;

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

@@ -0,0 +1,13 @@
+import type { ParamNotes } from '../core/describe.js';
+/**
+ * The plain-words note for every parameter in the bundled catalog, read by `describe()`.
+ *
+ * A separate entry (`kuinetic/notes`, and `kuinetic.notes.js` for a script tag) rather than a
+ * field on each `ParamSpec`, because this is prose only documentation pages read: inline, it would
+ * ship to every visitor of every site using the library. It imports types only, so it carries no
+ * runtime code either.
+ *
+ * Kept in step with the registry by `test/param-notes.test.ts`: every registered parameter must
+ * resolve a note, and every key here must name a parameter that exists.
+ */
+export declare const PARAM_NOTES: ParamNotes;

package/dist/types/notes/interaction-reveal.d.ts

@@ -0,0 +1,3 @@
+import type { ParamNotes } from '../core/describe.js';
+/** `effects/catalog/interaction-reveal.ts`. */
+export declare const INTERACTION_REVEAL_NOTES: ParamNotes;

package/dist/types/notes/interaction.d.ts

@@ -0,0 +1,6 @@
+import type { ParamNotes } from '../core/describe.js';
+/**
+ * `effects/catalog/interaction.ts`, `interaction-reveal.ts` (all but hover-intent, noted in
+ * `notes/interaction-reveal.ts`), `interaction-states.ts` and `interaction-proximity.ts`.
+ */
+export declare const INTERACTION_NOTES: ParamNotes;

package/dist/types/notes/keys.d.ts

@@ -0,0 +1,7 @@
+import type { ParamNotes } from '../core/describe.js';
+/**
+ * The reserved `data-kui` keys — the ones the parser keeps for itself rather than handing to an
+ * effect. Keyed `'data-kui.<key>'` (`KEY_NOTE_OWNER` in `core/describe.ts`), so no effect name can
+ * shadow them. The first block applies to the whole element; the second to the step it is in.
+ */
+export declare const KEY_NOTES: ParamNotes;

package/dist/types/notes/mechanics.d.ts

@@ -0,0 +1,7 @@
+import type { ParamNotes } from '../core/describe.js';
+/**
+ * `effects/layout/primitives.ts`, `effects/three-d/index.ts`, `effects/gestures/primitives.ts`,
+ * `effects/svg/index.ts`, `effects/motion-path/index.ts`, `effects/tween/*` and the `blur`, `scale`,
+ * `rotate`, `skew`, `progress` primitives in `effects/catalog/core.ts`.
+ */
+export declare const MECHANICS_NOTES: ParamNotes;

package/dist/types/notes/scroll-nav-forms.d.ts

@@ -0,0 +1,6 @@
+import type { ParamNotes } from '../core/describe.js';
+/**
+ * `effects/navigation/index.ts`, `effects/scroll-mechanics/primitives.ts` (+ `scroll-spy.ts`,
+ * `params.ts`), `effects/forms/primitives.ts`.
+ */
+export declare const SCROLL_NAV_FORMS_NOTES: ParamNotes;

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

@@ -0,0 +1,6 @@
+import type { ParamNotes } from '../core/describe.js';
+/**
+ * Parameters that mean the same thing on every primitive that declares them. A primitive whose
+ * `duration` means something else (one cycle of a loop, say) overrides it under its own key.
+ */
+export declare const SHARED_NOTES: ParamNotes;

package/dist/types/notes/showcase.d.ts

@@ -0,0 +1,7 @@
+import type { ParamNotes } from '../core/describe.js';
+/**
+ * `showcase/*` (compare, device-frame, hotspots, lightbox, scroll-story, slideshow, slow-mo) and
+ * the step decks in `effects/carousel/*` and `effects/step-index.ts` (spatial-ring, spatial-stack,
+ * step-progress).
+ */
+export declare const SHOWCASE_NOTES: ParamNotes;

package/dist/types/notes/text.d.ts

@@ -0,0 +1,3 @@
+import type { ParamNotes } from '../core/describe.js';
+/** `effects/catalog/text.ts`, `effects/catalog/numbers.ts`, `effects/catalog/discrete.ts` (this batch's families). */
+export declare const TEXT_NOTES: ParamNotes;

package/dist/types/showcase/compare.d.ts

@@ -1,4 +1,13 @@
 import type { Preset, Primitive } from '../core/types.js';
 export declare const COMPARE_AXIS_ATTR = "data-kui-compare-axis";
+/** Stamped only on a frame of three or more media: the number of dividers. Absent for a pair. */
+export declare const COMPARE_DIVIDERS_ATTR = "data-kui-compare-dividers";
+/** Below this a sweep is a flicker between the two images, not a comparison. */
+export declare const MIN_SWEEP_MS = 250;
+/**
+ * The longest step one frame may take. A tab returning from the background hands the next frame a
+ * gap of however long it was hidden; integrating that whole gap would jump the divider.
+ */
+export declare const MAX_FRAME_MS = 100;
 export declare const COMPARE_PRIMITIVE: Primitive;
 export declare const COMPARE_PRESETS: Preset[];

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

@@ -23,6 +23,9 @@ export declare const SHOWCASE_PRESETS: Preset[];
  * `kuinetic.showcase.js` tag will hand a page's existing animator tomorrow. See
  * `src/core/register-into.ts`'s docblock for why identity cannot survive that split and shape can.
  *
+ * Also provides the deck viewer (`core/deck-viewer.ts`), the one capability decks in `src/effects/`
+ * reach in this module without importing it.
+ *
  * @param target - The registry, the animator, or a host exposing one as `.registry`.
  * @returns `target`, so callers can chain.
  * @complexity O(n) time in showcase primitives plus presets; O(1) extra space.