kuinetic 0.1.3 → 0.2.0

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

@@ -0,0 +1,248 @@
+import type { Preset, Primitive } from '../../core/types.js';
+/**
+ * The masked label swap: two stacked copies of a label in a clipped box, one sliding out as the
+ * other slides in.
+ *
+ * ### Markup
+ *
+ * ```html
+ * <button data-kui="masked-label-swap">
+ *   <span data-kui-swap="from">Download</span>
+ *   <span data-kui-swap="to">Get the file</span>
+ * </button>
+ * ```
+ *
+ * Both copies are real elements with real text, not `::before`/`content` — a pseudo-element's
+ * generated content cannot be selected, cannot be copied, cannot hold markup, and reaches assistive
+ * technology inconsistently. For an effect whose entire subject is a *label*, that is the wrong
+ * trade at any price, and it would also have burned one of the two contended pseudo boxes (see
+ * `border-draw`'s channel note in `interaction.ts`).
+ *
+ * `from`/`to` rather than document order, so the pair reads the way a keyframe does and so an icon
+ * or a `<span class="sr-only">` sitting between the two copies cannot silently reassign the roles.
+ *
+ * ### Why one effect covers two patterns
+ *
+ * The "old number slides out, upgraded number slides in" case is the same mechanism with numerals
+ * in the two parts, so it needs no name of its own. What it does need is the `-y` axis, which is
+ * why vertical is the unsuffixed default: a price or a count changing reads as a vertical roll,
+ * where a call-to-action changing its wording reads better horizontally.
+ *
+ * ### Channels
+ *
+ * `discrete` because the host rule pins `display: inline-grid` to stack the two copies in one grid
+ * cell — the same reason `split-flap`, `feedback-spin` and six others declare it (`display` is
+ * tracked as one physical property regardless of the value written into it).
+ *
+ * `label-swap` is the box token for the marked parts, exactly parallel to `group-dim`'s `group`:
+ * the properties this effect actually animates live on a *child* box, so filing them under
+ * `translate` would make the compiler refuse `data-kui="lift, masked-label-swap"` — a button that
+ * rises on hover while its label swaps — even though the two never touch the same box. Two
+ * `masked-label-swap*` names on one host *are* refused, correctly: they share this primitive, so
+ * they collide on every channel it declares, and they would fight over one `--kui-label-swap-dx`.
+ */
+export declare const LABEL_SWAP_PRIMITIVES: Primitive[];
+/**
+ * Three axes, three names, one primitive — so all three share the `--kui-label-swap-*` timing
+ * namespace, the schema, the reduced-motion policy and the channel claim, and differ only in the
+ * two offset custom properties their own selector sets in `interaction.css`.
+ *
+ * No `transitions` field. `Preset.transitions` describes properties a preset eases *on its own host
+ * box*, and the compiler spends them on the one `--kui-transition` property `base.css` applies to
+ * the element carrying `data-kui-fx` — which here is the clip box, which does not move. The parts'
+ * `translate` transition is authored directly on their own rule, the same way `group-dim`'s
+ * children's is, and it is safe there for the same reason: nothing but this primitive can write to
+ * `[data-kui-swap]`, because a second effect that did would be on the `label-swap` channel and
+ * refused at compile time before it got there.
+ *
+ * No `requiresOwnSubtree` either, and that is load-bearing rather than an omission — see
+ * `INHERITED_STATE` above for why these rules deliberately carry no combinator, and what `target:`
+ * buys once they do not.
+ */
+export declare const LABEL_SWAP_PRESETS: Preset[];
+/**
+ * Hover intent: nothing happens until the pointer has *rested* for a second, and leaving early
+ * cancels it outright.
+ *
+ * ```html
+ * <button data-kui="hover-intent" aria-describedby="t1">Archive
+ *   <span data-kui-hint id="t1" role="tooltip">Moves to Archive; nothing is deleted</span>
+ * </button>
+ * ```
+ *
+ * ### Why this is timing syntax and not a JavaScript primitive
+ *
+ * The question was live, and the answer turns on one fact about CSS transitions that is easy to
+ * assume wrongly: **a `transition-delay` is not a timer that fires regardless.** The transition's
+ * parameters are read from the element's *after-change* style, so when the pointer leaves before
+ * the delay elapses, the property reverts, the pending transition is cancelled before it ever
+ * started, and nothing at all was drawn. Cancel-on-early-leave — the half of hover intent that a
+ * plain delay supposedly cannot express — is native behaviour, not something a script has to
+ * supply. This file's `INHERITED_STATE` note explains the one extra step needed to get that
+ * asymmetric delay onto a *second* box.
+ *
+ * The claim that `delay:` "starts its clock on the trigger and never cancels" is true, but of the
+ * other tier: the library's own `on:hover` activation listens for `pointerenter`/`focusin` and has
+ * no un-trigger (`core/activation.ts`), so a JS-activated effect really does keep its appointment
+ * after the pointer has gone. That is a property of the activation, not of `delay:`, and the fix
+ * for it is not a new primitive here.
+ *
+ * So the only thing genuinely missing was something *to* delay: section I had twenty-five names
+ * that decorate the trigger and not one that reveals a companion, so `delay:` had nothing to be
+ * hover intent *about*. This preset is that missing subject, and it is thirty lines of stylesheet.
+ *
+ * A JavaScript primitive would be the right answer for a different feature — **trajectory** intent,
+ * the mega-menu heuristic that keeps a panel open while the pointer is moving *toward* it even
+ * though it has technically left. That needs pointer history and a predicted path; no amount of
+ * `transition-delay` expresses it, and it should be built when someone wants it rather than
+ * smuggled in as the implementation of this one.
+ *
+ * ### Channels
+ *
+ * `hint`, its own box token, for the reason `group-dim` gives for `group`: the properties animate a
+ * child box, so filing them under `opacity` would refuse `data-kui="fade-in, hover-intent"` — a
+ * card that fades itself in and reveals a hint on rest — even though the two never touch the same
+ * box.
+ *
+ * The hint is `pointer-events: none` in every state, deliberately. A revealed panel you can move
+ * the pointer *into* is a menu, not a hint: it needs the pointer to be able to leave the trigger
+ * without closing it, which is the trajectory problem above. Naming this one non-interactive keeps
+ * it honest about which of the two it is.
+ */
+export declare const HOVER_INTENT_PRIMITIVES: Primitive[];
+export declare const HOVER_INTENT_PRESETS: Preset[];
+/**
+ * A name tag springing out from an avatar on hover, and the same mechanism used to hover a word
+ * and pop out an image beside it — one composite, four placements, not two effects.
+ *
+ * ### Markup
+ *
+ * ```html
+ * <span data-kui="anchored-preview" class="avatar-wrap" tabindex="0">
+ *   <img class="avatar" src="jane.jpg" alt="">
+ *   <span data-kui-preview class="name-tag">Jane Doe</span>
+ * </span>
+ *
+ * <span data-kui="anchored-preview-right" tabindex="0">a word
+ *   <img data-kui-preview src="preview.jpg" alt="">
+ * </span>
+ * ```
+ *
+ * The trigger has to be its own focusable, hoverable element — an `<img>` cannot contain the
+ * preview, which is why the avatar case wraps both in a `<span tabindex="0">` rather than putting
+ * `data-kui` on the `<img>` itself. That is a real markup cost worth naming, and it is the same one
+ * `hover-intent`'s own doc comment already pays for a tooltip's trigger.
+ *
+ * ### Why not CSS anchor positioning
+ *
+ * This is the textbook use case `anchor()`/`position-anchor` was built for, and it was considered.
+ * The project's own planning notes record the owner dropping anchor positioning outright on
+ * 2026-08-26, for a reason that is decisive here specifically: it is the only one of the "four
+ * modern CSS techniques" listed there with a
+ * *harmful* fallback — an unsupported `anchor()` puts the element in the *wrong* place rather than
+ * a neutral one — and the two conditions set for reopening it (proof that an anchored position
+ * transitions rather than snaps when the anchor moves, and materially better support than the
+ * measured 84.12%) are both still open. So this reuses the mechanism `hover-intent` and
+ * `masked-label-swap` already ship instead: the trigger's state and geometry travel as *inherited
+ * custom properties*, computed once per placement and read by a genuinely generic standalone rule.
+ * 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
+ *
+ * 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`).
+ *
+ * `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.
+ *
+ * ### How placement reaches a standalone child rule without a combinator
+ *
+ * Each placement preset's own base rule (no state involved) sets two custom properties on
+ * *itself* — `--kui-anchored-preview-inset` (the four-value `inset` shorthand for that side) and
+ * `--kui-anchored-preview-travel` (the `translate` value combining the constant centering offset on
+ * the cross-axis with the spring distance on the main axis, sign and axis already resolved). Both
+ * are precomputed per placement so `[data-kui-preview]` itself stays fully generic: `position:
+ * 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.
+ *
+ * ### Channels
+ *
+ * `preview`, its own box token, for the reason `hint` and `label-swap` already state: the
+ * properties animate a child box, so filing them under `opacity`/`translate`/`scale` would refuse
+ * `data-kui="lift, anchored-preview"` — an avatar that lifts on hover while its name tag pops out —
+ * even though the two never touch the same box. No pseudo-element is used at all (the tag/image is
+ * real, selectable, copyable markup, the same reasoning `masked-label-swap`'s doc comment gives for
+ * its own two copies), so this effect has zero pseudo-element collision cost.
+ *
+ * The preview is `pointer-events: none` in every state, for the identical reason `hover-intent`'s
+ * hint is: a revealed panel the pointer can move *into* is a menu, which needs pointer-history
+ * "trajectory intent" rather than this mechanism, and should be built when someone wants it rather
+ * than smuggled in here.
+ */
+export declare const ANCHORED_PREVIEW_PRIMITIVES: Primitive[];
+export declare const ANCHORED_PREVIEW_PRESETS: Preset[];
+/**
+ * A search icon that grows into a full input field.
+ *
+ * ### Markup
+ *
+ * ```html
+ * <label data-kui="search-expand">
+ *   <svg aria-hidden="true">…</svg>
+ *   <input data-kui-search-field type="search" placeholder="Search…">
+ * </label>
+ * ```
+ *
+ * The host is a `<label>`, not a `<div>`, and that is load-bearing rather than a styling
+ * preference: clicking anywhere in a `<label>` — including the icon — natively focuses the
+ * `<input>` it contains, with no JavaScript and no matching `for`/`id` pair, which is what lets a
+ * collapsed, icon-only control still be a single click away from typing.
+ *
+ * ### Why this is not a FLIP job
+ *
+ * A reviewer ruled on this ahead of time (see this task's brief): a width/clip/intrinsic-size
+ * transition is sufficient unless the field genuinely *relocates* between two layouts, and this one
+ * does not — it grows in place. So the host's own `inline-size` is an ordinary, explicit-length CSS
+ * transition (`Preset.transitions`, never a bare stylesheet `transition:` — seeing one there is
+ * itself a failure `css-composition-invariants.test.ts`'s "transition channel" suite asserts
+ * against), not a measure-before/measure-after/invert-and-play choreography. Both `collapsed` and
+ * `width` are explicit lengths for the same reason `interpolate-size: allow-keywords` is not used
+ * here at all: the project's own planning notes record that technique as deliberately deferred
+ * pending Safari support, and reaching for it on a brand new effect would be an unsanctioned first
+ * use of something the owner has already decided to wait on.
+ *
+ * ### How the input's fade reaches a standalone child rule without a combinator
+ *
+ * The same `INHERITED_STATE` mechanism `hover-intent` and `anchored-preview` (above) use, for the
+ * identical reason: `[data-kui-fx~='search-expand'] input` would be a combinator after the fx
+ * compound, forcing `requiresOwnSubtree` and making `target:` a no-op — and unlike `group-dim`,
+ * there is no reason to want that here. So the host's `:focus-visible`/`:has(:focus-visible)`/
+ * `:hover`/`:has(input:not(:placeholder-shown))` rules set `--kui-search-expand-shown` (0/1) and
+ * `--kui-search-expand-lag` (0ms at rest, the authored delay once expanded — the same enter-only
+ * asymmetry every hover-intent-shaped rule in this file uses), and the marked field reads both from
+ * a *standalone* `[data-kui-search-field]` selector with no fx
+ * prefix at all.
+ *
+ * ### Channels
+ *
+ * Three, because this primitive owns three distinct boxes' worth of properties: `expand` for the
+ * host's own `inline-size` (a channel of its own, the same reasoning `skew`/`border` document —
+ * no existing channel names this physical property, and folding it into `layout` would couple this
+ * effect's fate to `header-shrink`'s unrelated `padding-block`/`font-size` claim); `discrete`
+ * because the host pins `display: inline-flex` unconditionally, the same reason `split-flap` and
+ * `masked-label-swap` declare it; and `search-field` for the inherited signals that feed the child
+ * input's `opacity`, the same reasoning `hint`/`label-swap` give for their own child-box channels.
+ */
+export declare const SEARCH_EXPAND_PRIMITIVES: Primitive[];
+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[];

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

@@ -3,7 +3,13 @@
  * `cursor-*` family) — kept separate from DOM/timer wiring so the position → transform arithmetic
  * is assertable without a browser, the same separation `text-shared.ts` uses for its state
  * machines.
+ *
+ * `HOVER_TRANSITIONS` at the bottom is an unrelated second concern sharing this file only because
+ * `interaction.ts` hit its own 400-line lint ceiling — the same reason `css-invariants.test.ts`
+ * split into `css-scan.ts`/`channel-properties.ts`, not a claim that a lookup table belongs beside
+ * pointer-tracking arithmetic.
  */
+import type { ParameterSchema, TransitionSegment } from '../../core/types.js';
 export interface TiltAngles {
     rotateX: number;
     rotateY: number;
@@ -54,3 +60,39 @@ export declare function parallaxOffset(point: LocalPoint, size: ElementSize, str
  * @overallScore 100
  */
 export declare function supportsFineHover(win: Window): boolean;
+/**
+ * Transition segments for the five hover-family presets whose motion is a bare host-rule
+ * `transition:` in `interaction.css` (`lift`, `pop`, `lift-shadow`, `border-draw`, `border-glow`).
+ * The other eight — `shine-sweep`, `split-flap`, `beam-border`, `underline-slide`,
+ * `underline-center`, `icon-wiggle`, `icon-spin`, `icon-bounce` — animate via a keyframed
+ * `animation:` on `:hover`/`:focus-visible`, or transition a pseudo-element (`::after`) rather than
+ * the host box `Preset.transitions` describes, so they declare none here.
+ *
+ * A lookup keyed by primitive id, not a parallel array, so a typo in one list can't silently pair
+ * the wrong segments with the wrong preset — `HOVER_PRESETS` (`interaction.ts`) still derives its
+ * name/primitive pair from `HOVER_PRIMITIVES` the same way it always has.
+ */
+export declare const HOVER_TRANSITIONS: Partial<Record<string, TransitionSegment[]>>;
+/**
+ * The hover names whose motion is a host-level `animation:` in `interaction.css` rather than a
+ * transition or a pseudo-element rule — `Preset.delivery`'s one declared value, applied by
+ * `HOVER_PRESETS`.
+ *
+ * Beside {@link HOVER_TRANSITIONS} because it is the same shape of fact about the same family: a
+ * per-name detail of how that name's CSS is written, which `HOVER_PRIMITIVES` cannot carry because
+ * one primitive backs names on both sides of it.
+ *
+ * Written out rather than derived, because there is nothing in the effect record to derive it from:
+ * `HOVER_TRANSITIONS` does not separate them (`shine-sweep`, `beam-border`, `underline-slide` and
+ * `underline-center` are absent from it too, and are safe — they animate a pseudo-element that
+ * inline style cannot reach), and neither does the channel list, the renderer, or the parameter
+ * set. The fact lives in the stylesheet, so the stylesheet is what audits it:
+ * `test/css-composition-invariants.test.ts` derives the true set from `src/css/*.css` with
+ * `extractHostAnimationBindings` and fails in both directions, which is what stops this drifting the
+ * first time a fifth hover keyframe is added.
+ */
+export declare const STYLESHEET_ANIMATED_HOVERS: string[];
+export declare const BEAM_PARAMS: ParameterSchema;
+export declare const SHINE_PARAMS: ParameterSchema;
+export declare const COLOR_PARAMS: Record<string, ParameterSchema>;
+export declare const BORDER_DRAW_PARAMS: ParameterSchema;

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 definition lives in `effects/shared.ts` — neutral ground for every CSS-keyframe category, not just `catalog/`. */
-export { cssPrimitive } from '../shared.js';
+/** 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, 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.
@@ -117,29 +140,39 @@ export declare function createStepRunner(win: Window, options: StepRunOptions):
  * wrapping the space itself, the same way `appendWordSpans` already leaves inter-word whitespace
  * unwrapped.
  *
+ * Per the CSS Text line-breaking spec, browsers insert a line-break opportunity between any two
+ * adjacent atomic inline-level boxes, even without whitespace between them — so a bare run of
+ * `.kui-split-item` spans could wrap mid-word. Each word's char-spans are nested inside a shared
+ * `.kui-split-word` wrapper (itself `display: inline-block`) so the only break opportunities left
+ * are between words, same as the source text.
+ *
  * @complexity O(n) time and space in grapheme count.
  * @overallScore 100
  */
 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.
  *
@@ -181,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;