kuinetic 0.1.4 → 0.2.0

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

@@ -0,0 +1,68 @@
+import type { Preset, Primitive } from '../../core/types.js';
+/**
+ * The press state. One primitive, one preset today — the split is the composability the name
+ * promises.
+ *
+ * A future `glass-press`, `press-tilt`, or a brand's own pressed treatment is a second `Preset`
+ * row on this same primitive plus its own selector in `interaction.css`: it inherits the
+ * `--kui-press-duration/-delay/-ease` namespace (those are keyed on the *primitive* id by
+ * `registry.ts`'s `namespaceTiming`), the parameter schema, the reduced-motion policy, and the
+ * channel claim, and adds only the declarations that differ. That is the same
+ * one-primitive-many-names shape the rest of the catalog uses — 130 of the catalog's names are
+ * aliases of this kind — and it is why `press` is the primitive rather than `press-depth`.
+ *
+ * ### Channels: `scale` and `shadow`, and specifically not `translate`
+ *
+ * A channel claim is not documentation, it is a veto: `compile.ts`'s `resolveComposition` *drops*
+ * every effect after the first when two claims overlap, so an over-broad claim silently deletes
+ * an effect an author wrote. `translate` is the claim this primitive could plausibly have made and
+ * must not: `lift` owns `translate` and `data-kui="lift, press-depth"` — raise on hover, sink on
+ * press — is the single most useful pairing this effect has. Claiming `translate` would make the
+ * compiler refuse it and drop the press entirely.
+ *
+ * That is not a loophole; the sink genuinely does not need `translate`. A press reads as depth
+ * through the scale and through the shadow collapsing toward the surface, which is how the two
+ * dominant design systems build the same state. What it costs is real and worth naming:
+ * `lift-shadow` and `border-glow` both own `shadow`, so composing either with `press-depth` is
+ * refused. That refusal is correct rather than incidental — all three write `box-shadow` on the
+ * same box in overlapping states, and whichever rule came later in `interaction.css` would win the
+ * whole property.
+ */
+export declare const PRESS_PRIMITIVES: Primitive[];
+export declare const PRESS_PRESETS: Preset[];
+/**
+ * Collective hover: the container recedes, except for the member you are pointing at.
+ *
+ * ### Why the name is `group-dim`
+ *
+ * The effect goes on the *container* — `data-kui="group-dim"` on the `<ul>`, the grid, the row —
+ * and reads whatever children are already there, so a page using it writes no structural CSS of
+ * its own. A name has to be true on the element it is written on, and that rules out the obvious
+ * `siblings-dim`/`dim-siblings` spelling: written on a `<ul>`, "siblings" names the `<ul>`'s own
+ * siblings, which are the one set of elements this effect never touches. `group-dim` names the
+ * container's contents, which is what actually dims.
+ *
+ * `group-` is also a prefix with room in it. This is the first collective effect in the catalog,
+ * and a `group-blur` or `group-desaturate` is the same mechanism with a different property; they
+ * would share this primitive's channel and read as one family in the catalog's group column.
+ *
+ * ### Channels: `group`, a channel of its own
+ *
+ * Every other channel in the model names properties on the element `data-kui-fx` sits on. This one
+ * paints its *children's* `opacity`, which is a different box, and filing it under `opacity` would
+ * make the compiler refuse `data-kui="fade-in, group-dim"` — a container that fades itself in and
+ * dims its children on hover — even though the two never touch the same box. Declaring the box set
+ * the effect actually owns is what keeps the veto pointed at the real collision: a second
+ * `group-*` effect on the same container.
+ *
+ * `requiresOwnSubtree` follows directly and is not optional. `target:` relocates `data-kui-fx` onto
+ * whatever a selector matches, and a rule that reaches `> *` compiles to silence when it lands on
+ * an element with a different shape beneath it. `compile.ts`'s `liftTarget` refuses to relocate a
+ * preset that declares this, and `css-requires-own-subtree.test.ts` re-derives the true set from
+ * the shipped stylesheets rather than trusting the flag.
+ */
+export declare const GROUP_PRIMITIVES: Primitive[];
+export declare const GROUP_PRESETS: Preset[];
+/** Both state families, for `interaction.ts`'s catalog-wide exports. */
+export declare const STATE_PRIMITIVES: Primitive[];
+export declare const STATE_PRESETS: Preset[];

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

@@ -0,0 +1,67 @@
+import type { Preset, Primitive } from '../../core/types.js';
+import type { Registry } from '../../core/registry.js';
+export declare const MATERIALS_PRIMITIVES: Primitive[];
+/**
+ * The preset name and the primitive id are both `glass` — the same string in two different
+ * namespaces, which `registry.ts` keeps as separate maps (`resolve()` looks the authored name up
+ * in `presets`, then follows `preset.primitive` into `primitives`), so there is no collision to
+ * worry about. Plenty of the catalog already does this (`fade-open`, `cursor-follow`,
+ * `rotate-static`, and more) — a preset sharing its primitive's id is the common case, not the
+ * exception.
+ *
+ * Keeping them as two rows rather than one still buys composability: a distinctly-named preset —
+ * someone's own house style, say — is a second `Preset` row here plus its own selector in
+ * `glass.css`, inheriting the parameter schema, the channel claim, the reduced-motion policy and
+ * the perf class rather than restating them. `blur:` and `tint:` already cover the
+ * heavier-blur / different-tint variations that used to motivate that point, so those are
+ * `glass blur:32px` or `glass tint:navy`, not a second name — but the mechanism is still here for
+ * a preset that genuinely needs one. Same one-primitive-many-names shape the rest of the catalog
+ * uses, and the reason `press` — not `press-depth` — is the primitive next door.
+ *
+ * No `transitions` field. `Preset.transitions` describes properties this preset eases on its own
+ * host box, and nothing here eases: the surface is painted once and does not change. A composed
+ * `press-depth` brings its own `scale`/`box-shadow` segments, which is exactly the division of
+ * labour this family is built around.
+ *
+ * ### No `phase` field either, and this one took real thought
+ *
+ * None of the four {@link EffectPhase} values (`core/types.ts`) is honest about what `glass` does,
+ * and forcing one on would be worse than the unphased default it falls back to:
+ *
+ * - **Not `entrance`/`exit`.** Both describe a one-shot animation that starts from a hidden or
+ *   displaced state and *releases* the channel the moment it finishes — that release is what makes
+ *   `fade-up, lift` safe (see `channels.ts`'s `INDEPENDENT_PHASES`). `glass` never plays anything
+ *   and never releases `background`/`backdrop`: `prepareGlass` above is a no-op, and the CSS rule
+ *   in `glass.css` is an unconditional declaration with no keyframe at all. There is no from-state
+ *   to hide and nothing to hand back to the cascade.
+ * - **Not `idle`.** `idle` is specifically an *unbounded animation loop* — a running clock that
+ *   never yields, tracked in CSS as `--kui-fx-<name>-iterations: infinite` (see `ambient-tint`'s
+ *   presets in `ambient.ts`, which also claim `background` and are exactly this). `glass` has no
+ *   clock and no iteration count; it is not looping, it simply is.
+ * - **Not `state`.** `state` means the channel is held by a condition the *visitor* changes
+ *   (`:hover`, `[aria-expanded]`) and released once that condition goes away. `glass`'s hold is
+ *   unconditional from the moment it activates (`defaultActivation: 'load'`) and never releases —
+ *   there is no visitor action that ends it.
+ *
+ * So `glass` holds `background`/`backdrop` exactly the way `idle` does — forever, with no turn to
+ * hand off — without being an animation, which is the one fact every {@link EffectPhase} value
+ * assumes. Declaring `idle` anyway was the tempting shortcut, since it happens to be inert against
+ * today's `INDEPENDENT_PHASES` table (`idle` is not a member of either exempted pair, so it would
+ * conflict with everything exactly as unphased does) — but "inert today" is not the same as
+ * "true", and a false claim sitting on the record is exactly what costs someone a real bug the day
+ * that table grows a third exemption. Leaving `phase` undeclared is the honest answer *and* the
+ * correct one operationally: an unphased claim conflicts with any other claimant on
+ * `background`/`backdrop`, which is exactly right, because anything else painting on that channel
+ * *forever* — another material, an `idle` ambient loop like `scanline` — is a genuine, permanent
+ * fight over the same property, not two effects taking turns. See
+ * `test/catalog-phase-materials.test.ts` for the compiled proof.
+ */
+export declare const MATERIALS_PRESETS: Preset[];
+/**
+ * Register catalog section S (materials) 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.
+ */
+export declare function registerMaterials(registry: Registry): Registry;

package/dist/types/effects/catalog/media-shared.d.ts

@@ -35,9 +35,10 @@ export declare function slatOrder(index: number, count: number, from: SlatFrom):
  * Resolve the authored `angle:` to degrees, falling back to whatever `axis:` names.
  *
  * `angle:` is the general parameter and `axis:` the two-keyword shorthand that predates it, so an
- * authored angle wins and an absent one reads the axis. Both `45` and `45deg` are accepted, as are
+ * authored angle wins and an absent one reads the axis. `45`, `45d` and `45deg` are accepted, as are
  * `turn` and `rad`, because an author who writes an angle should not have to remember which of the
- * three this particular parameter takes.
+ * three this particular parameter takes. `core/params.ts` takes the same three spellings for every
+ * other `type: 'angle'` parameter.
  *
  * Normalised to `[0, 180)`: a band at 200° is the same set of bands as one at 20°, only numbered
  * from the other end, and collapsing that here means the geometry below never has to think about

package/dist/types/effects/catalog/numbers-shared.d.ts

@@ -10,8 +10,10 @@ export interface CountLayers {
     /** `aria-hidden` node the ticking display writes to on every frame. */
     decorative: HTMLElement;
     /**
-     * Visually-hidden twin. The caller must write this exactly once, on completion — never
-     * mid-tick — so a screen reader is told the final value and nothing in between.
+     * Visually-hidden twin. Holds the final value from the moment it is installed and never
+     * changes again — the number is content, not a status update, so there is nothing to announce
+     * mid-count (design.md §12's "no aria-live spam from counters"). The caller writes it once, at
+     * install, from the same `to`/`format` the tween itself will settle on.
      */
     srOnly: HTMLElement;
     /**
@@ -23,12 +25,13 @@ export interface CountLayers {
 }
 /**
  * Replace an element's content with an `aria-hidden` ticking display plus a visually-hidden twin,
- * both empty until the caller populates them, so a counter's mid-flight text is never read aloud
- * and its `aria-live` region changes exactly once.
+ * both empty until the caller populates them. The decorative layer is free to tick every frame;
+ * the SR-only twin is meant to be written once, with the counter's final value, and never touched
+ * again — a counter is content, not a live status, so it carries no `aria-live`.
  *
  * @param el - Element whose content is being taken over. Assumed to hold no meaningful children.
  * @param doc - Document to create nodes in, rather than the ambient global.
- * @returns The decorative node to tick, the SR-only node to finalize once, and a cleanup.
+ * @returns The decorative node to tick, the SR-only node to populate once, and a cleanup.
  * @complexity O(1) time and space.
  * @overallScore 100
  */

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

@@ -1,2 +1,2 @@
 /** Re-exported for same-directory catalog siblings; the canonical definitions live in `effects/shared.ts` — neutral ground for every effect category, not just `catalog/`. */
-export { cssPrimitive, TIMELINE_AGNOSTIC, TRIGGER_DELAY_PARAM } from '../shared.js';
+export { cssPrimitive, TIMELINE_AGNOSTIC, TRIGGER_DELAY_PARAM, withTimingContract, } from '../shared.js';

package/dist/types/effects/catalog/text-shared.d.ts

@@ -1,9 +1,30 @@
-import type { Cleanup, EffectParams } from '../../core/types.js';
+import type { Cleanup, EffectParams, EffectSpec, EffectVariant, ParameterSchema } from '../../core/types.js';
 /** How `split-text` breaks a string into decorative pieces. */
 export type SplitUnit = 'chars' | 'words' | 'lines';
+/**
+ * Selector for the elements a content-mutating text/number effect must never remove from the DOM:
+ * a link, a form control, anything focusable or already interactive. Every primitive that takes
+ * over an element's text (`installSplitLayers`, `installCountLayers`, `word-cycler`) flattens
+ * markup into plain text or a captured-and-replaced subtree, and a link caught inside that is gone
+ * from the page for as long as the effect runs — for a one-shot effect that never settles back,
+ * permanently. Losing a link costs SEO; losing a focusable control is worse, because it costs a
+ * keyboard user access to it.
+ */
+export declare const INTERACTIVE_DESCENDANT = "a[href], button, input, select, textarea, [tabindex], [contenteditable], details, summary, iframe, audio[controls], video[controls]";
+/**
+ * Whether `el` contains an interactive descendant a content-mutating effect would otherwise
+ * remove or flatten.
+ *
+ * @param el - Host element the effect is about to take over.
+ * @complexity O(n) time in descendant count (native `querySelector`); O(1) space.
+ * @overallScore 100
+ */
+export declare function hasInteractiveDescendant(el: Element): boolean;
 export interface SplitLayers {
     /** `aria-hidden` container the caller populates with decorative markup or text. */
     decorative: HTMLElement;
+    /** The accessible reading copy while the decorative pieces are animating. */
+    srOnly: HTMLElement;
     /** The element's text at the moment splitting began, trimmed for display. */
     originalText: string;
     /**
@@ -19,7 +40,9 @@ export interface SplitLayers {
  * screen reader ever seeing an incomplete or garbled read of the content.
  *
  * @param el - Element whose text is being taken over. Assumed to hold plain text (no children) —
- *   every DOM-surgery primitive in this module shares that constraint.
+ *   every DOM-surgery primitive in this module shares that constraint. Callers are expected to
+ *   have already checked {@link hasInteractiveDescendant} and bailed out if it is true; this
+ *   function itself does not guard, so a caller that skips the check still flattens a link.
  * @param doc - Document to create nodes in, rather than the ambient global, so callers can point
  *   this at a test document.
  * @returns The decorative layer to populate, the captured text, and a cleanup.
@@ -128,24 +151,28 @@ export declare function createStepRunner(win: Window, options: StepRunOptions):
  */
 export declare function appendCharSpans(container: Element, doc: Document, text: string): HTMLElement[];
 /**
- * Split text into one span per word, leaving the whitespace and punctuation between them as plain
- * text nodes so natural line-wrapping and spacing survive untouched.
+ * Split text into animated words. Opening punctuation joins the next word; other punctuation
+ * joins the preceding word. A punctuation run without a word gets its own item. Only whitespace
+ * stays outside the items, preserving natural wrapping and spacing.
  *
  * @complexity O(n) time and space in segment count.
  * @overallScore 100
  */
 export declare function appendWordSpans(container: Element, doc: Document, text: string): HTMLElement[];
 /**
- * Split text into one span per visual line.
- *
- * Lines are not a text property — they only exist after wrapping — so this measures word spans
- * already laid out in the live DOM, then regroups their nodes (words and the whitespace between
- * them) into per-line containers.
- *
+ * Split text into measured visual lines.
  * @complexity O(n) time and space in word-span count.
  * @overallScore 100
  */
 export declare function appendLineSpans(container: Element, doc: Document, text: string): HTMLElement[];
+/**
+ * Put existing words and whitespace back into natural flow, measure, and wrap the new lines.
+ * The offsetTop reads in wrapMeasuredLines finish before it writes any line wrappers.
+ *
+ * @complexity O(n) time and space in word-span count.
+ * @overallScore 100
+ */
+export declare function rewrapLineSpans(container: Element, doc: Document): HTMLElement[];
 /**
  * Split text by the requested unit.
  *
@@ -187,3 +214,52 @@ export declare const SCRAMBLE_CHARSETS: Record<string, string>;
  * @overallScore 100
  */
 export declare function scrambledFrame(graphemes: string[], resolved: number, charset: string, random: () => number): string;
+/**
+ * The generic variable-font axis: `data-kui="var-axis axis:GRAD from:0 to:150"`.
+ *
+ * `var-weight`/`var-width`/`var-slant` cover the three axes CSS gave a high-level property to.
+ * Everything else a real type system exposes — Fraunces' `SOFT` and `WONK`, Recursive's `CASL`,
+ * `MONO` and `CRSV`, Roboto Flex's `GRAD` and `XOPQ`, `opsz` on almost everything modern — has no
+ * property of its own and can only be reached through `font-variation-settings`. Three hardcoded
+ * names cannot grow to meet that; a tag parameter can.
+ *
+ * `from`/`to` are deliberately unbounded numbers. Axis ranges are a property of the *font*, not of
+ * CSS — `wght` is 1–1000, `opsz` is typically 8–144, `GRAD` runs −200 to 150, `CASL` is 0–1 — so
+ * any `minimum`/`maximum` this schema could state would be wrong for most axes and would reject
+ * legitimate values. The renderer already handles the out-of-range case correctly: CSS Fonts 4
+ * clamps an axis value to the range the font declares, so an over-large `to:` reads as "all the way
+ * to that axis's maximum" rather than as a broken declaration.
+ *
+ * The defaults are weight-shaped (100 → 900) because `wght` is far and away the most common axis
+ * and a bare `data-kui="var-axis"` should do something recognisable. On a font with no `wght` axis
+ * that is a no-op, which is also what an unsupported axis should look like.
+ */
+export declare const varAxisParams: ParameterSchema;
+/**
+ * Turn an authored `axis:GRAD` into the quoted CSS string the keyframe needs, and into a schema
+ * that accepts exactly that one value.
+ *
+ * This is the whole reason `var-axis` can be generic while every parameter in the library is
+ * validated against a closed grammar. `ParamSpec` has no "four-character font tag" type, and the
+ * types that *are* open (`text`) are dropped before the stylesheet precisely because they are open
+ * — so a tag cannot reach CSS as an ordinary parameter at all. What `variantFor` adds is the
+ * ability to decide the grammar *per spec*: the tag is checked against {@link AXIS_TAG} here, then
+ * declared as the sole legal keyword, so `resolveParams` still runs its full escape screen over a
+ * value it can only accept if it is identical to the one already vetted. Two independent gates, and
+ * neither is loosened — this narrows the accepted set to one string rather than widening it.
+ *
+ * The `tween` primitive uses the same mechanism for the same class of reason: one authored key
+ * (`x:'0,100,40'`) expanding into parameters the primitive could not have declared statically. See
+ * `EffectVariant.schema` in `core/types.ts`.
+ *
+ * A rejected tag is *dropped*, not substituted. Rewriting it to the default would animate the
+ * wrong axis under a name the author did not write, which is the silent-wrong-behaviour outcome
+ * this codebase treats as worse than doing nothing; dropping it leaves the `var()` fallback in
+ * force and the warning is the only account of what happened.
+ *
+ * @param spec - The authored spec, untouched — `compile` recompiles the same value on every rescan.
+ * @param warn - Diagnostic sink, so a mistyped tag is named rather than silently ignored.
+ * @returns A variant carrying the quoted tag and its one-value schema, or an empty refinement.
+ * @complexity O(p) time and space in the spec's parameter count, for the copy.
+ */
+export declare function varAxisVariant(spec: EffectSpec, warn: (message: string) => void): EffectVariant;

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[];