kuinetic 0.1.3 → 0.2.0

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

@@ -1,4 +1,3 @@
-import type { PrepareContext } from '../core/effect-context.js';
 import type { Cleanup } from '../core/types.js';
 /**
  * Marking the children of a stepped effect, shared by every primitive that has an index.
@@ -25,42 +24,23 @@ import type { Cleanup } from '../core/types.js';
  */
 /** The attribute this module owns. Never write it from anywhere else. */
 export declare const STEP_STATE_ATTR = "data-kui-step-state";
-export type StepState = 'before' | 'active' | 'after';
 /**
- * Classify a selector as unusable, dangerously broad, or fine.
- *
- * `matches` against the two roots catches every selector that reaches the whole document — `*`,
- * `html`, `body` and compounds like `*, a` with one rule and no bespoke parser — while leaving a
- * deliberately scoped wildcard such as `.spy-nav > *` working, which a syntactic ban on `*` would
- * not. `matches` throws on invalid syntax exactly as `querySelectorAll` does, so the same call
- * still answers the validity question.
+ * The ring place, as a selectable attribute beside the `--kui-offset` custom property.
  *
- * @complexity O(1) time and space.
- * @overallScore 100
+ * Also owned here, and written to the same elements. See `createStepMarker` for why both forms
+ * exist: the number does arithmetic a selector cannot, the attribute selects what arithmetic
+ * cannot — and hiding a slide properly (`visibility`, not `opacity`) needs a keyword.
  */
-export declare function selectorBreadth(selector: string, doc: Document): 'invalid' | 'document-wide' | 'ok';
+export declare const STEP_OFFSET_ATTR = "data-kui-step-offset";
+export type StepState = 'before' | 'active' | 'after';
 /**
- * Resolve a `target:` selector once at setup, rejecting both the unusable and the over-broad.
- *
- * Two distinct failures, one warning channel. An invalid selector thrown from inside the shared
- * scheduler's frame callback would skip every other subscriber on that root, not just this one. An
- * over-broad one is worse for being silent: `target:*` is perfectly valid syntax, so a syntax-only
- * check passed it straight through to stamp an attribute onto every element in the document, on
- * every frame.
- *
- * Rejecting rather than silently narrowing is the honest response, because there is no narrower
- * selector that could be meant. A selector reaching `<html>` or `<body>` is not naming a set of
- * steps or a nav link, it is naming the page, and guessing which of its thousands of descendants
- * the author meant would be worse than saying so.
- *
- * @param selector - The authored `target:` value; empty is the no-op default, not an error.
- * @param ctx - Prepare context, for `doc` and the warning channel.
- * @param effect - Effect name, so the warning says which attribute to go and fix.
- * @returns The selector, or `''` when it must be ignored.
- * @complexity O(1) time and space; `matches` walks the selector, not the document.
- * @overallScore 100
+ * `target:`/`scope:` resolution — `resolveTarget`, `queryScoped`, `TargetScope`, `SCOPE_PARAM`,
+ * `scopeParam` — moved to `core/target.ts`. `core/compile.ts` and `core/animator.ts` need the same
+ * resolution for the *universal* `target:` (any effect, not just the handful of primitives that
+ * used to be the only place this grammar existed — see `compile.ts`'s `liftTarget` for who those
+ * are today), and `core` must not depend on `effects`. Import from `../core/target.js` here as
+ * everywhere else; this module keeps only the step-index-specific half.
  */
-export declare function resolveTarget(selector: string, ctx: PrepareContext, effect: string): string;
 /**
  * A set of step elements plus the ledgers that let their original attributes survive teardown.
  *
@@ -83,11 +63,39 @@ export interface StepMarker {
  * the index actually changing — while frames are not.
  *
  * @param resolve - Produces the current step elements, in document order.
+ * @param warn - Optional diagnostic sink, called at most once per marker. Callers prefix their own
+ *   effect name, the way every other warning in this library names the attribute to go and fix.
  * @returns A marker; call `restore` from the primitive's teardown.
  * @complexity O(n) per `mark` in the number of step elements; O(n) space in elements ever touched.
  * @overallScore 100
  */
-export declare function createStepMarker(resolve: () => Iterable<Element>): StepMarker;
+export declare function createStepMarker(resolve: () => Iterable<Element>, warn?: (message: string) => void): StepMarker;
+/**
+ * Where one step sits relative to the live one, as a signed number of places *around a ring*.
+ *
+ * `before`/`active`/`after` is a three-way split, which is all a progress bar needs and not enough
+ * for a deck: it says slide 5 is "before" slide 1 but not that it is one place behind it, and one
+ * place is the whole difference between a carousel that loops and one that rewinds. Driving the
+ * track off the container's single `--kui-step` means the wrap from the last slide to the first
+ * runs the track back across every slide in between — the snap-back that reads as "it jumped to
+ * the beginning" rather than "it carried on".
+ *
+ * Published per element instead, each slide can place itself: at index 0 of five, the last slide
+ * reads `-1` and sits to the *left* of the live one, so stepping onto it moves one place forward
+ * like every other step. Nothing is cloned and nothing is reordered — the ends of the strip simply
+ * stop existing, because there is no strip, only positions on a ring.
+ *
+ * Signed and shortest-path: the far half of the ring counts backwards, so `+3` of five becomes
+ * `-2`. An even count has no midpoint to split, and the exact half goes positive by convention.
+ *
+ * @param position - The element's index within its own parent group.
+ * @param index - The live step.
+ * @param size - How many steps are in that group.
+ * @returns Places from the live step, negative for behind it.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function circularOffset(position: number, index: number, size: number): number;
 /**
  * Where one step sits relative to the live one.
  *

package/dist/types/effects/svg/icon-parts.d.ts

@@ -0,0 +1,23 @@
+import type { Primitive } from '../../core/types.js';
+/**
+ * Wrap an icon-toggle-family `prepare` so a host with no `.kui-bar` children gets
+ * `data-kui-part="bar"` on its positional bars.
+ *
+ * Stamps eagerly, before calling `inner`: `stylesheetTimingPrepare` (the only `inner` this ever
+ * wraps today) runs at install, not activation — only *its* inner mirroring is deferred — and the
+ * stamp has to be in place at the same moment, or `icon-parts.css`'s `[data-kui-part='bar']` rules
+ * have nothing to select yet when the browser's next paint reads them. Restored on `ctx.signal`
+ * abort, which fires when the instance releases (mirrors `flip-parts.ts`'s (7a) attribute-ledger
+ * cleanup one primitive over) — never on `reset()`/`destroy()` directly, since `PrepareContext`
+ * hands `prepare` nothing else that fires on every teardown path.
+ *
+ * A host that already wrote its own `.kui-bar` markup is untouched: `findBars` never runs, so
+ * nothing here can clash with class-based CSS an author is already relying on.
+ *
+ * @param inner - The primitive's own `prepare`, unwrapped.
+ * @returns A `prepare` of the same shape, with the part-stamping layered in.
+ * @complexity O(n) time in the host's children, beyond whatever `inner` itself costs; O(n)
+ *   additional space held past `prepare` for the bars' ledgers, until `ctx.signal` aborts.
+ * @overallScore 100
+ */
+export declare function withIconParts(inner: NonNullable<Primitive['prepare']>): NonNullable<Primitive['prepare']>;

package/dist/types/effects/three-d/flip-parts.d.ts

@@ -0,0 +1,46 @@
+import type { Cleanup, EffectParams, PrepareContext } from '../../core/types.js';
+/**
+ * Phase 7a — the flip card's structural parts (owner decision E): `data-kui-part="front"`/`"back"`
+ * on an unclassed card's two faces, and the toggle control — an authored `.kui-flip-control`, an
+ * authored `button[aria-pressed]` (stamped so `flip-card-parts.css` reaches it, but never wired,
+ * since the author already owns its click handler), or a control this module injects and wires
+ * itself: `<button type="button" class="kui-flip-control" data-kui-part="control injected"
+ * aria-pressed="false">Flip card</button>` (the `quiet` token joins it for a hover trigger, so
+ * `flip-card-parts.css` can hide it until `:focus-visible` — the pointer path already has one).
+ *
+ * Classes win throughout: a card the author already marked up with `.kui-face-front`/`-back`/
+ * `.kui-flip-control` gets no redundant attribute next to a class its own CSS may already select.
+ */
+/** What {@link prepareFlipParts} resolved for one flip card. */
+export interface FlipParts {
+    /** The card's toggle control, whether authored or injected. `resolveControl`'s injected branch
+     *  always succeeds, so this is never absent. */
+    control: Element;
+    /** Undo every attribute stamp and remove every injected node. */
+    cleanup: Cleanup;
+}
+/**
+ * Matches whichever control {@link prepareFlipParts} resolved for a card, whichever of the three
+ * branches produced it — an authored `.kui-flip-control`, an authored `button[aria-pressed]`
+ * (stamped `data-kui-part="control"`), or the injected fallback (both class and stamp). `three-d/
+ * index.ts`'s deferred `prepareCardToggle` re-finds the control through this selector rather than
+ * calling {@link prepareFlipParts} a second time — target:-everywhere reconcile R-7 moved the one
+ * call that stamps/injects to prepare time, before `prepareCardToggle` (deferred to activation)
+ * ever runs, so by the time it looks, the control this selector matches already exists.
+ */
+export declare const CONTROL_SELECTOR: string;
+/**
+ * Resolve (and stamp/inject) a flip card's structural parts.
+ *
+ * @param el - The flip card element.
+ * @param params - The effect's authored parameters; only `trigger` is read, to decide whether an
+ *   injected control starts quiet (hidden until `:focus-visible`) — a hover trigger already has a
+ *   pointer path, so the injected control is a keyboard fallback rather than the primary control.
+ * @param ctx - The prepare-time context; only `doc` is read, so an injected button is built
+ *   through the same document the rest of this codebase's primitives use rather than a global.
+ * @returns The card's control and a cleanup that undoes every stamp and removes the injected node.
+ * @complexity O(c) time in the card's direct children; O(1) additional space per stamped/injected
+ *   node.
+ * @overallScore 100
+ */
+export declare function prepareFlipParts(el: Element, params: EffectParams, ctx: PrepareContext): FlipParts;

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

@@ -0,0 +1,57 @@
+import type { Registry } from '../../core/registry.js';
+import type { Preset, Primitive } from '../../core/types.js';
+export declare const TWEEN_PRIMITIVES: Primitive[];
+/**
+ * Two names, no parameter defaults of their own.
+ *
+ * `tween-from` cloaks and `tween` does not, which is the same rule every other name in the catalog
+ * follows: a `from` tween's start state is installed by the runtime, so between first paint and
+ * `start()` the element is painted at its *rest* state and then jumps back to animate — the flash
+ * `Preset.cloak` exists to remove. A `to` tween starts at the rest state by construction, so there
+ * is nothing to hide and cloaking it would blank an element that was always meant to be visible.
+ *
+ * **Neither declares `phase`, and that is deliberate — checked against the actual stylesheet, not
+ * assumed from "generic effect, therefore unknowable".**
+ *
+ * `tween` (the `to` direction) is knowable and the answer is still "no phase fits". Every block in
+ * `kui-tween-to-*` (`src/css/tween.css`) declares an explicit `to` — `translate: var(--kui-tween-x,
+ * 0) ...`, not a missing endpoint — so, per D1's correction #5, `animation-fill-mode: both` pins that
+ * exact authored value on the channel forever once the animation finishes; it never resolves against
+ * whatever the cascade underneath would otherwise say. That is precisely the shape `EffectPhase`'s
+ * own doc calls out as the trap: fifteen of the catalog's fifty-four `cloak: true` entrances close
+ * their block the same way and are *deliberately* left unphased rather than marked `entrance`,
+ * because `entrance` specifically means "plays once and releases the channel". `tween` is that same
+ * closed shape by construction — every property group's `to` block closes, with no exception — so it
+ * belongs in that same deliberately-unphased set on the same grounds, not because nothing is known.
+ * It is not `state` either (nothing gates it behind a visitor condition — it runs the moment it
+ * activates), not `idle` (it is a bounded, one-shot animation, not an unbounded loop), and not `exit`
+ * (it does not start at rest and depart; it moves *to* an arbitrary authored value).
+ *
+ * `tween-from` is where "cannot be known statically" is the literal, checked reason, not a hedge.
+ * Its two-point blocks (`kui-tween-from-*`) are the mirror of `tween`'s — `from` is explicit and `to`
+ * is missing, so a plain `tween-from y:40` *does* release: it is structurally identical to an open
+ * entrance like `fade-up`, and would be a defensible `phase: 'entrance'` on its own. But
+ * `waypoints.ts`'s `waypointKeyframes` compiles a **different, fully-explicit block** the moment any
+ * key in the group is authored as a list — `tween-from x:'0,100,40'` renders through
+ * `kui-tween-keys3-translate`, whose own comment in `tween.css` says it plainly: "unlike everything
+ * above they are fully explicit from 0% to 100%... there is no implicit half left for the browser to
+ * fill from computed style." That block does **not** release, for the same fill-forever reason
+ * `tween`'s `to` blocks do not. So whether this preset's one instance releases its channel depends on
+ * whether the *author* wrote a single value or a list for at least one key in the group — a fact
+ * about the spec, not about the preset, and exactly the shape D1 was killed over (`repeat:` turning
+ * a finite entrance into a loop at author time, invisible to a preset-level field). Declaring
+ * `phase: 'entrance'` here would be right for `tween-from y:40` and silently wrong for `tween-from
+ * y:'0,40'` on the very same element — the "wrong phase is worse than none" case this project was
+ * warned about, so it stays undeclared and collides with everything, exactly as before this field
+ * existed. See `test/catalog-phase-mechanics.test.ts` for what stays checked instead.
+ */
+export declare const TWEEN_PRESETS: Preset[];
+/**
+ * Register the generic tween.
+ *
+ * @param registry - Registry to populate.
+ * @returns The same registry, for chaining.
+ * @complexity O(1) time and space — two primitives, two presets.
+ * @overallScore 100
+ */
+export declare function registerTween(registry: Registry): Registry;

package/dist/types/effects/tween/properties.d.ts

@@ -0,0 +1,107 @@
+import type { Channel, ParamSpec, ParameterSchema } from '../../core/types.js';
+/**
+ * The generic tween's vocabulary: which property names an author may put in a `key:value` slot,
+ * what each one means, and which keyframe block renders it.
+ *
+ * **Why this is an allowlist and not a passthrough.** `tween <name>:<value>` is the one place in
+ * the library where an author names a *CSS property* rather than choosing from a primitive's
+ * declared parameters, so the obvious implementation — write whatever they typed into whatever
+ * they typed — is also the one that breaks two invariants at once. It breaks composition, because
+ * `core/channels.ts` decides whether two effects may share an element from their declared channel
+ * sets and an open-ended property list has no channel; and it breaks the parameter contract in
+ * `core/params.ts`, which exists precisely because author strings end up in a stylesheet. An
+ * allowlist keeps every tweenable property on a known channel with a known value grammar, and
+ * costs only that a property nobody listed here cannot be tweened until someone adds a row.
+ *
+ * **Why the rows are grouped.** CSS writes `translate` as one property, not three; a keyframe that
+ * sets it sets every axis. So the unit of rendering is the *group* — one `@keyframes` block per
+ * group, one animation track per group the author actually touched — and not the individual key.
+ * See `src/css/tween.css`, where each group's block is written out, including what the identity
+ * fallbacks mean for an axis the author did not name.
+ */
+/** One rendering unit: a single CSS property (or filter list) written by one keyframe block. */
+export type TweenGroup = 'translate' | 'rotate' | 'scale' | 'opacity' | 'filter' | 'color' | 'background';
+/**
+ * Declared in rendering order rather than derived from `TWEEN_PROPERTIES`'s key order, so
+ * `tween opacity:0 x:100` and `tween x:100 opacity:0` compile to the same track order. Two
+ * spellings of one animation producing two different `animation-name` lists would make every
+ * assertion about a compiled plan depend on the order the author happened to type in.
+ */
+export declare const TWEEN_GROUP_ORDER: readonly TweenGroup[];
+/**
+ * The channel each group claims — the honest answer to "what does this spec collide with".
+ *
+ * These are the existing catalog channels, not new ones: a tween writing `translate` must collide
+ * with `fade-up` for the same reason two entrances do, and giving the tween a private channel name
+ * would let exactly that pair compose into one effect silently overwriting the other.
+ */
+export declare const TWEEN_GROUP_CHANNELS: Record<TweenGroup, Channel>;
+interface TweenProperty {
+    group: TweenGroup;
+    spec: ParamSpec;
+}
+/**
+ * Author key → what it animates.
+ *
+ * Deliberately absent, and each for a reason worth writing down rather than rediscovering:
+ *
+ * - **`rotate-x` / `rotate-y`.** The CSS `rotate` property takes one axis at a time, so they could
+ *   not share the rotate group with `rotate` anyway; and rotating a flat box about x or y without a
+ *   `perspective()` reads as a vertical squash, not a turn. Perspective only exists inside the
+ *   `transform` shorthand, which is a different channel entirely (`CHANNEL.skew` — see
+ *   `core/types.ts`) and already has an effect family of its own in `flip-in-x`/`flip-in-y`.
+ * - **`width` / `height` / `top` / `left`.** Animatable, and every one of them animates layout.
+ *   The tween declares `perfClass: 'paint'`; admitting these would make that a lie for the whole
+ *   effect rather than for the one attribute that used them, and the library has never offered a
+ *   layout-animating primitive without saying so.
+ * - **`skew`.** Same `transform`-shorthand problem as 3D rotation, and skew has no property of its
+ *   own to write — `CHANNEL.skew` documents exactly this.
+ */
+export declare const TWEEN_PROPERTIES: Readonly<Record<string, TweenProperty>>;
+/**
+ * The tween's parameter schema, declared statically even though which keys *matter* varies per
+ * attribute.
+ *
+ * Every key is always declared, so an author who mistypes one gets `resolveParams`' ordinary
+ * `unknown parameter "opactiy" (known: ...)` warning listing the whole vocabulary, exactly as they
+ * would on any other effect. Declaring only the keys a given attribute used would have produced a
+ * "known:" list containing nothing but the author's own typo-free keys, which is the least useful
+ * form that message could take.
+ */
+export declare const TWEEN_SCHEMA: ParameterSchema;
+/**
+ * `BARE_NUMBER` and {@link decimalNumber} used to live here. They moved to `core/params.ts` when
+ * the `'number|percentage'` union landed and the core needed the same lexical decimal shift to
+ * turn `opacity:80%` into `0.8` — one implementation, so the two paths cannot drift into
+ * disagreeing about what `50%` means.
+ */
+/**
+ * Give a bare number the unit its property implies — `x:100` is `100px`, `rotate:45` is `45deg`.
+ *
+ * `core/params.ts` requires a unit on every `length`, and should keep doing so: a unitless
+ * `distance:24` on `fade-up` is a mistake worth naming, because the parameter is ambiguous between
+ * `px` and `%` and the author simply left the unit off. `angle` is not in that position and
+ * `params.ts` now coerces it there too, which makes this function's angle branch a no-op for
+ * anything that reaches validation — it is kept because it runs first and keeps the tween's own
+ * `rotate:45` identical to its `x:100`. A tween property is different for `length`. `x:100` is the
+ * syntax this feature was specified around, it is what every other animation library accepts, and
+ * "100 what" has exactly one sensible answer per property. So the coercion lives here, scoped to
+ * the tween's own keys, rather than loosening validation for the other 255 effects.
+ *
+ * Number-valued properties also accept percentages, expressed as decimal ratios for the core
+ * validator. Length percentages retain their units. Other values pass through unchanged: `2rem`
+ * and a quoted `calc(...)` still have to earn their acceptance in `params.ts`.
+ *
+ * @complexity O(n) time in value length; O(1) space.
+ * @overallScore 100
+ */
+export declare function withImpliedUnit(raw: string, type: ParamSpec['type']): string;
+/**
+ * A shared param type is intentionally broader than some CSS slots: percentages are lengths for
+ * x/y, but not z or blur, and a negative blur invalidates the entire filter list. Check these
+ * slot-specific constraints on scalar values and waypoints alike. CSS-wide keywords are also
+ * unsafe here: `--kui-tween-color: inherit` inherits the custom property, not the element's color.
+ * All other values still go through the core validator; this never opens a second CSS escape path.
+ */
+export declare function tweenValue(key: string, raw: string, warn: (message: string) => void, label?: string): string | undefined;
+export {};

package/dist/types/effects/tween/waypoints.d.ts

@@ -0,0 +1,106 @@
+import type { ParameterSchema } from '../../core/types.js';
+import type { TweenGroup } from './properties.js';
+/**
+ * Multi-waypoint tweening — `tween x:'0,100,40'`, a value list instead of a value.
+ *
+ * `tween`/`tween-from` animate between exactly two states: wherever the element is, and where the
+ * author said. That is `gsap.to()`/`gsap.from()`, and it is where the catalog stopped — nothing in
+ * it smooths a property through *several* states, which is the shape of most real choreography (out,
+ * over, settle) and of every keyframe array in Motion, GSAP and WAAPI.
+ *
+ * **The whole feature is still static CSS.** A list of N values selects an N-step `@keyframes` block
+ * from `src/css/tween.css`, and each step reads its own custom property. Nothing is generated at
+ * runtime, nothing is interpolated in JavaScript, and the result is an ordinary compositor-run CSS
+ * animation exactly as the two-point tween already was — see the outline's §2.3, and `tween.css`'s
+ * own header for what the blocks look like.
+ *
+ * **Why a value list rather than a waypoint list.** The alternative shape is per-waypoint objects —
+ * `at:'x:0 y:0' at:'x:100 y:-60'` — and the grammar cannot hold it: a `key:value` slot appears once
+ * per spec, so repeating one is a duplicate-parameter warning. Property-major is also what Motion
+ * and WAAPI use (`animate(el, { x: [0, 100, 40] })`), and it keeps the vocabulary identical to the
+ * two-point tween's: an author who knows `x:100` knows `x:'0,100,40'`.
+ *
+ * **Even spacing across the duration.** Also GSAP's own default for a bare keyframe array. A
+ * per-step position would need the *percentage* in the keyframe selector to vary, and a keyframe
+ * selector cannot be a `var()` — it is the one part of a keyframe block that has to be literal. An
+ * author who wants an uneven rhythm can repeat a value to hold it for a step.
+ */
+/**
+ * The most waypoints one property may name.
+ *
+ * A budget rather than a limit of the technique: every count needs its own `@keyframes` block per
+ * property group, because the step percentages are literal, so the shipped stylesheet grows with
+ * this number. Five states keeps this static vocabulary bounded. Longer choreography needs another keyframe
+ * definition; two effects on the same property cannot bypass this budget by composing.
+ */
+export declare const MAX_WAYPOINTS = 5;
+/**
+ * One property group's waypoint shape, as read off the attribute.
+ *
+ * `count` is the group's, not the key's: a keyframe block has one step count, so every key in the
+ * group renders at the same steps whatever each of them individually wrote.
+ */
+export interface GroupWaypoints {
+    count: number;
+    /** Author key → its values, already padded to `count` and unit-normalised. */
+    keys: Map<string, string[]>;
+}
+/**
+ * Read one authored value as a waypoint list, or as the single value it is.
+ *
+ * Commas inside functions and strings are data. Unlike the core tokenizer, this scanner must
+ * retain empty items: dropping the middle of `0,,100` changes both the count and the rhythm,
+ * while dropping every item of `,,` used to make the first-value lookup throw. Empty values now
+ * reach ordinary parameter validation at their authored index and use the CSS fallback.
+ *
+ * @returns The values in order. One entry means the author wrote a plain value, and every caller
+ *   treats that as the two-point tween it has always been.
+ * @complexity O(n) time and space in the value's length.
+ * @overallScore 100
+ */
+export declare function readWaypoints(raw: string): string[];
+/**
+ * Collect the waypoint lists an attribute wrote, bucketed by the group that renders them.
+ *
+ * @param authored - Author key → raw value, for tween properties only.
+ * @returns One entry per group that named at least one list. Groups whose keys are all plain values
+ *   are absent, and keep the two-point blocks they have always used.
+ * @complexity O(n) time and space in the number of values across the attribute.
+ * @overallScore 100
+ */
+export declare function collectWaypoints(authored: [string, string[]][], warn: (message: string) => void): Map<TweenGroup, GroupWaypoints>;
+/**
+ * Expand a group's lists into one parameter per waypoint, with a spec for each.
+ *
+ * The key is `x[2]`, not `x-2`, and the brackets are load-bearing: these keys are synthesised by
+ * the library and can never be authored, so when one of them appears in a `resolveParams`
+ * diagnostic — `parameter "x[2]": expected a length` — the author can see both which key and which
+ * waypoint without the message having to explain itself, and can tell at a glance that it is not a
+ * name they were supposed to have written.
+ *
+ * The custom property is `--kui-tween-<key>-<n>`, which is what `tween.css`'s step reads, with the
+ * plain `--kui-tween-<key>` as its fallback. That fallback is the whole broadcast rule: a key that
+ * wrote a single value (`tween x:'0,100,40' y:20`) sets only the plain property, so every step of
+ * the block reads the same `y` and it holds — no JavaScript, no per-step duplication of a value the
+ * author wrote once.
+ *
+ * @param waypoints - One group's padded lists.
+ * @param params - Sink for the expanded values, keyed as above.
+ * @param schema - Sink for the specs those values are validated against.
+ * @complexity O(n) time and space in the group's total number of values.
+ * @overallScore 100
+ */
+export declare function expandWaypoints(waypoints: GroupWaypoints, params: Record<string, string>, schema: ParameterSchema, warn: (message: string) => void): void;
+/**
+ * The keyframe block a group with waypoints renders through.
+ *
+ * One block per (group, count), all of them fully explicit from 0% to 100% — so unlike the
+ * two-point blocks there is no `to`-only and `from`-only pair, and `tween` and `tween-from` share
+ * them. That falls out of what a list *is*: an author who writes every state has written the first
+ * one too, so there is no implicit half left for the browser to fill from the element's computed
+ * style.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function waypointKeyframes(group: TweenGroup, count: number): string;

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

@@ -0,0 +1,4 @@
+import type { Preset, Primitive } from '../core/types.js';
+export declare const COMPARE_AXIS_ATTR = "data-kui-compare-axis";
+export declare const COMPARE_PRIMITIVE: Primitive;
+export declare const COMPARE_PRESETS: Preset[];

package/dist/types/showcase/device-frame.d.ts

@@ -0,0 +1,3 @@
+import type { Preset, Primitive } from '../core/types.js';
+export declare const DEVICE_FRAME_PRIMITIVE: Primitive;
+export declare const DEVICE_FRAME_PRESETS: Preset[];

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

@@ -0,0 +1,3 @@
+import type { Preset, Primitive } from '../core/types.js';
+export declare const HOTSPOTS_PRIMITIVE: Primitive;
+export declare const HOTSPOTS_PRESETS: Preset[];

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

@@ -0,0 +1,30 @@
+import type { Animator } from '../core/animator.js';
+import type { Registry } from '../core/registry.js';
+import type { Preset, Primitive } from '../core/types.js';
+/**
+ * The showcase module: pre-built presentation widgets — a dialog, an ARIA carousel, image
+ * hotspots — the one part of this library that owns UI behaviour rather than only motion.
+ * `docs/design.md` §14's amendment is the boundary this module operates under; every widget's own
+ * file (`device-frame.ts`, `lightbox.ts`, …) argues its own case for why it needs the exception.
+ *
+ * This is the *only* file anything outside `src/showcase/` may import from — see
+ * `only-effects-barrel-imports-showcase` in `.dependency-cruiser.cjs`. That is what makes the
+ * later split into a standalone `kuinetic.showcase.js` a build-config change and not a source
+ * change: every showcase file keeps importing from inside `src/showcase/`, and the one line that
+ * moves is `src/effects/index.ts`'s call to {@link registerShowcase}.
+ */
+export declare const SHOWCASE_PRIMITIVES: Primitive[];
+export declare const SHOWCASE_PRESETS: Preset[];
+/**
+ * Register every showcase widget onto a `Registry`, an `Animator`, or anything shaped like either.
+ *
+ * The shape check — not `instanceof` — is what lets this same function serve as both the in-core
+ * call `src/effects/index.ts` makes today and the `boot({ register })` callback a split
+ * `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.
+ *
+ * @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.
+ */
+export declare function registerShowcase(target: unknown): Registry | Animator;

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

@@ -0,0 +1,3 @@
+import type { Preset, Primitive } from '../core/types.js';
+export declare const LIGHTBOX_PRIMITIVE: Primitive;
+export declare const LIGHTBOX_PRESETS: Preset[];

package/dist/types/showcase/media-source.d.ts

@@ -0,0 +1,13 @@
+/** A safe, supported video URL and its preferred frame shape. */
+export interface MediaSource {
+    kind: 'youtube' | 'vimeo' | 'file';
+    embedUrl: string;
+    aspect: 'wide' | 'tall';
+}
+/**
+ * Resolve a real link into a supported player source. Unknown hosts and non-web schemes keep
+ * their normal link behavior; no attacker-controlled URL is handed to an iframe.
+ * @complexity O(n) in the URL length; O(1) extra space.
+ * @overallScore 100
+ */
+export declare function resolveMediaSource(href: string): MediaSource | null;

package/dist/types/showcase/modal-shell.d.ts

@@ -0,0 +1,22 @@
+export interface ModalContent {
+    node: HTMLElement;
+    label: string;
+    duration: number;
+    scale: string;
+    ease: string;
+    reducedMotion: boolean;
+    onKey?: (event: KeyboardEvent) => void;
+    onClose?: () => void;
+}
+export interface ModalShell {
+    open(content: ModalContent): void;
+    dismiss(): void;
+    release(): void;
+}
+/**
+ * Share one lazily built modal per document across image and video widgets. The final live
+ * instance removes it, including an in-flight close timer and any scroll lock.
+ * @complexity O(1) per operation; O(1) shared DOM per document.
+ * @overallScore 100
+ */
+export declare function acquireModalShell(doc: Document): ModalShell;

package/dist/types/showcase/scroll-story.d.ts

@@ -0,0 +1,4 @@
+import type { Preset, Primitive } from '../core/types.js';
+export declare const STORY_SIDE_ATTR = "data-kui-story-side";
+export declare const SCROLL_STORY_PRIMITIVE: Primitive;
+export declare const SCROLL_STORY_PRESETS: Preset[];

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

@@ -0,0 +1,47 @@
+import type { Channel, ParameterSchema, PerfClass, Primitive } from '../core/types.js';
+/**
+ * The one shape every showcase widget shares.
+ *
+ * `src/showcase/` builds UI components the effect catalog deliberately stays out of (a dialog, an
+ * ARIA carousel, a native popover) — see `docs/design.md` §14's amendment. Every one of them is
+ * built the same way for the same reasons, so this bakes the shared answers in once rather than
+ * repeating them per widget:
+ *
+ * - `renderer: 'javascript'` — nothing here compiles to a `@keyframes` block; the DOM the widget
+ *   builds and the states it toggles are the whole effect.
+ * - `supportedTimelines: ['time']` — a widget runs on a clock, never on scroll/view/pointer
+ *   progress. Narrower than `TIMELINE_AGNOSTIC` (`effects/shared.ts`), which abstains for
+ *   primitives that never read a `Timeline` at all; a widget primitive *could* be asked for one and
+ *   the honest answer is "only time makes sense here".
+ * - `supportedActivations: ['load']`, `defaultActivation: 'load'` — a widget must be wired up
+ *   before a keyboard user tabs to it or a crawler indexes it, not when it happens to scroll into
+ *   view. `on:enter`'s lazy-install story is right for a decorative reveal and wrong for a control.
+ * - `reducedMotion: 'shorten'`, never `'disable'` — `'disable'` means the animator never calls
+ *   `activate()` at all (`src/effects/forms/primitives.ts`'s doc on the same trap), which would
+ *   leave the widget entirely unbuilt for a reduced-motion visitor. Motion is removed in CSS
+ *   instead; the widget itself still has to exist.
+ * - `perfClass` is the one field every widget answers differently (a dialog's `backdrop-filter`
+ *   is `'paint'`, a native-popover positioning read is `'layout'`, a synchronous attribute stamp is
+ *   `'layout'` too), so it is a parameter rather than baked in.
+ *
+ * `prepare` is taken pre-built — already run through `deferPrepare` and, where the widget has
+ * nothing to time, `withTimingContract` — rather than assembled here, because the timing contract
+ * (which of `duration`/`delay`/`ease` a widget honours, and why not the rest) genuinely differs per
+ * widget and baking one reason in would misdescribe the others. Same division of labour
+ * `src/effects/navigation/index.ts`'s `navPrimitive` already uses for its own small family.
+ *
+ * @param id - Primitive id, also the preset name for every showcase widget shipped so far.
+ * @param spec - The three fields every widget answers differently: `channels` (CSS property
+ *   groups this widget's CSS claims, see `core/channels.ts`), `parameters` (the widget's parameter
+ *   schema), and `perfClass` (this widget's honest performance-budget class). Grouped into one
+ *   object rather than three positional params so this factory stays under the four-parameter
+ *   lint ceiling (`eslint.config.js`'s `max-params`) alongside `prepare`.
+ * @param prepare - Fully wrapped setup: `withTimingContract(...)`-and/or-`deferPrepare(...)`.
+ * @returns A complete `Primitive`.
+ * @complexity O(1) time and space.
+ */
+export declare function widgetPrimitive(id: string, spec: {
+    channels: Channel[];
+    parameters: ParameterSchema;
+    perfClass: PerfClass;
+}, prepare: NonNullable<Primitive['prepare']>): Primitive;

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

@@ -0,0 +1,3 @@
+import type { Preset, Primitive } from '../core/types.js';
+export declare const SLIDESHOW_PRIMITIVE: Primitive;
+export declare const SLIDESHOW_PRESETS: Preset[];

package/dist/types/showcase/slow-mo.d.ts

@@ -0,0 +1,5 @@
+import type { Preset, Primitive } from '../core/types.js';
+/** A host-only speed control for Web Animations and CSS motion in its subtree. */
+export declare const SLOW_MO_PRIMITIVE: Primitive;
+/** The showcase name for the speed-control primitive. */
+export declare const SLOW_MO_PRESETS: Preset[];