kuinetic 0.1.4 → 0.2.0

package/dist/types/core/unquoted-selectors.d.ts

@@ -0,0 +1,53 @@
+import type { EffectSpec } from './types.js';
+import type { Registry } from './registry.js';
+/**
+ * Owned by phase 9b — catching the classic `target:` typo: `pop target:.a, .b` reads as three
+ * effect segments (`pop`, `.a`, `.b`), not one effect with a two-part selector, because a comma
+ * separates *segments* everywhere else in the grammar and `target:` is the one place a selector
+ * can legitimately contain one. An author who forgets the quotes (`target:'.a, .b'`) gets a stray
+ * segment named `.a` that is not a registered effect and looks exactly like a selector — this
+ * module finds that shape and 9b's diagnostics surface it via `data-kui-unmatched`.
+ */
+/** One stray segment that looks like a continuation of the previous segment's `target:` selector. */
+export interface UnquotedSelector {
+    /** The previous segment's `target:` value, as authored. */
+    previous: string;
+    /** The stray segment's name — the text between commas that isn't a registered effect. */
+    segment: string;
+}
+/**
+ * Find segments whose first token is not a registered effect name, that look like a selector
+ * fragment (start with `.`, `#`, `[`, `*`, `:`, or contain `>`, `~`, `+`), and whose *previous*
+ * segment carries a `target:` token — the shape an unquoted, comma-containing selector leaves
+ * behind once `parse.ts` has already split it on the comma.
+ *
+ * Pure: it only reads `specs` and `registry`, and never changes how anything is parsed or
+ * compiled — the fix is a warning, not a silent re-join, because re-joining would have to guess
+ * where the selector was supposed to end.
+ *
+ * Known limitation: only catches a stray segment whose *first token* looks like a selector.
+ * `pop target:.a, li > a` splits into a stray segment `li > a` whose first token is `li` — a
+ * plausible effect name — so it is not flagged, even though `>` later in the segment is still a
+ * combinator. Detecting that shape would mean scanning every segment for a `target:`-less
+ * combinator, not just the one right after a `target:`-bearing segment, which is out of scope
+ * here: this pass only looks at the segment immediately following one that carries `target:`.
+ *
+ * @param specs - The document's parsed effect segments, in authored order. Pre-lift: `target:`
+ *   still lives in `spec.params.target` rather than having been pulled onto a separate field.
+ * @param registry - Where a segment's first token is looked up to decide if it names a real
+ *   effect.
+ * @returns Every suspect segment found, in authored order.
+ * @complexity O(n) time in `specs.length`, each iteration doing an O(1) registry lookup; O(f)
+ *   space in the number of findings.
+ * @overallScore 100
+ */
+export declare function findUnquotedSelectors(specs: EffectSpec[], registry: Registry): UnquotedSelector[];
+/**
+ * Render one {@link UnquotedSelector} finding as a warning string, naming both halves of the fix:
+ * quote the previous segment's selector so the whole comma list is one `target:` value.
+ *
+ * @param found - One finding from {@link findUnquotedSelectors}.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function unquotedSelectorWarning(found: UnquotedSelector): string;

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

@@ -0,0 +1,80 @@
+import type { PrepareContext } from '../../core/effect-context.js';
+import type { Cleanup } from '../../core/types.js';
+export interface RingDragRequest {
+    el: Element;
+    ctx: PrepareContext;
+    /** `grab:false` still installs the keyboard half — that is accessibility, not decoration. */
+    enabled: boolean;
+    /** Pointer pixels per place on the ring. */
+    travelPx: number;
+    /** How many places the ring has *now*; asked per gesture, never captured. */
+    total(): number;
+    /** The ring's current continuous position, in places. */
+    positionOf(): number;
+    /** Move the ring to a continuous position and re-render. */
+    moveTo(position: number): void;
+    /** Publish or clear the dragging state the stylesheet suspends its transition on. */
+    setDragging(dragging: boolean): void;
+}
+/**
+ * Where a release coasts to, before snapping.
+ *
+ * Velocity is in pixels per second and the ring is measured in places, so the projection is
+ * `velocity / travel * seconds` — one conversion, in one place, in the unit the index uses.
+ *
+ * Capped, and the cap is not politeness. Uncapped, a hard flick on a phone (velocities of several
+ * thousand pixels per second are ordinary) projects a dozen places, and a ring that spins a dozen
+ * cards from one flick has stopped being a control and become a slot machine: the visitor cannot
+ * predict where it lands, so they cannot aim, so they flick again. Four places is far enough that a
+ * deliberate throw clearly differs from a nudge and close enough that the destination stays
+ * legible.
+ *
+ * Pure and exported so both halves — the conversion and the cap — are assertable without a pointer.
+ *
+ * @param position - Where the ring is at release, in places.
+ * @param velocityPxPerSec - Signed pointer velocity along the drag axis.
+ * @param travelPx - Pixels per place.
+ * @returns The un-snapped position the ring is heading for.
+ * @complexity O(1) time and space.
+ */
+export declare function projectRelease(position: number, velocityPxPerSec: number, travelPx: number): number;
+/**
+ * Which place a released ring settles on.
+ *
+ * Separate from {@link projectRelease} because they answer different questions and only one of them
+ * has an opinion: projection is physics, snapping is the contract that a ring always comes to rest
+ * facing a card. Splitting them is also what makes "a flick of exactly half a place still commits"
+ * testable without synthesising a gesture.
+ *
+ * `+ 0` is not decoration. `Math.round(-0.4)` is `-0`, and a ring settled at "minus place zero" is
+ * not a place — it is the same place spelled in a way that half of JavaScript disagrees with
+ * itself about. `-0 === 0` is true, so most arithmetic hides it; `Object.is(-0, 0)` is false, which
+ * is what `toBe` compares with, and `[-0].toString()` and `JSON.stringify(-0)` disagree with each
+ * other too. Adding zero normalises the sign at the one place a negative zero can be produced,
+ * rather than leaving every caller and every serialisation to find out for itself.
+ *
+ * @param projected - The coasting destination, in places.
+ * @returns The nearest whole place, never negative zero.
+ * @complexity O(1) time and space.
+ */
+export declare function snapTo(projected: number): number;
+/**
+ * Bring a settled position onto `[0, total)`.
+ *
+ * A ring has no ends, so nothing about the geometry needs this — `--kui-offset` is computed modulo
+ * the count and `render` rebases the published position on the live step every time. What needs it
+ * is arithmetic hygiene over a long session: `position` accumulates every drag ever made, and a
+ * number in the millions loses the fractional precision the sub-step rotation is carried in. Doing
+ * it at rest rather than mid-drag keeps the drag itself monotonic, so a gesture never jumps because
+ * it happened to cross the seam.
+ *
+ * @complexity O(1) time and space.
+ */
+export declare function wrapPlace(place: number, total: number): number;
+/**
+ * Install the grab and the keyboard on a ring.
+ *
+ * @returns Teardown for every listener and attribute this installs.
+ * @complexity O(1) per pointer event and per key; O(1) space.
+ */
+export declare function createRingDrag(request: RingDragRequest): Cleanup;

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

@@ -0,0 +1,149 @@
+import type { Preset, Primitive } from '../../core/types.js';
+import type { Registry } from '../../core/registry.js';
+/**
+ * Whether a slot at this ring angle has its own plane turned away from the camera.
+ *
+ * Pure and exported so the rule is assertable without a DOM or a layout. The angle is the slot's
+ * signed place on the ring in degrees, already including the live-step drift.
+ *
+ * `>=` rather than `>` at exactly a quarter turn: a slot edge-on to the camera has zero projected
+ * width, so it can only ever swallow a click that was aimed at something else. Calling it "back" is
+ * the answer that costs nothing and removes the boundary case from the hit-testing question.
+ *
+ * @param angleDeg - Signed degrees from the camera-facing position.
+ * @returns `'back'` when the slot's face points away, `'front'` otherwise.
+ * @complexity O(1) time and space.
+ */
+export declare function faceAt(angleDeg: number): 'front' | 'back';
+/**
+ * Bring an angle onto `(-180, 180]`, the range where "how far from facing me" is a magnitude.
+ *
+ * Without it a slot at `+350deg` — which is 10 degrees from front — reads as further from the
+ * camera than one at `+100deg`, and the whole back half of a large ring is mislabelled.
+ *
+ * @complexity O(1) time and space.
+ */
+export declare function normaliseDegrees(angleDeg: number): number;
+/**
+ * Where the ring's continuous position rounds to, and how far past it the ring currently sits.
+ *
+ * The pair the stylesheet needs and the reason both tokens are published rather than one: the
+ * integer decides which slot is *live* (and therefore what `--kui-offset` means for every other
+ * slot), and the remainder is the sub-step rotation on top of it. Re-snapping the integer whenever
+ * the remainder passes a half step is what keeps the remainder inside ±0.5, so the ring never has
+ * to travel back across the whole strip to wrap from the last slide to the first — the same
+ * property `circularOffset` gives the discrete case.
+ *
+ * @param position - Continuous ring position, in places. May be negative or beyond the count.
+ * @param total - How many places the ring has.
+ * @returns The live integer step, wrapped into range, and the signed remainder in `[-0.5, 0.5)`.
+ * @complexity O(1) time and space.
+ */
+export declare function snapPosition(position: number, total: number): {
+    step: number;
+    drift: number;
+};
+/**
+ * An authored `<angle>` as a number of degrees.
+ *
+ * `params.ts` accepts every CSS angle unit and normalises only the bare/`d` spellings to `deg`, so
+ * a value reaching here can legitimately be `0.05turn` or `1.2rad`. The stylesheet does not care —
+ * it hands the token straight to `rotateY()` — but this file computes with it (to decide which
+ * slots face away), and a `Number('0.05turn')` is `NaN`.
+ *
+ * Falls back rather than throwing on an unrecognised unit for the reason every reader in this
+ * library does: the value has already been validated, so an unfamiliar spelling here means this
+ * function is behind `params.ts`, and a ring that spreads over the default arc is a better answer
+ * than one that throws during `prepare`.
+ *
+ * @param value - A validated CSS angle.
+ * @param fallbackDeg - Used when the unit is not one this function converts.
+ * @returns Degrees.
+ * @complexity O(n) time in value length; O(1) space.
+ */
+export declare function degreesOf(value: string, fallbackDeg: number): number;
+/**
+ * The ring primitive.
+ *
+ * `renderer: 'javascript'` and two channels together are the honest declaration: this file paints
+ * nothing itself — it publishes numbers — but `carousel.css` does, and both of the things it writes
+ * have to be declared or the conflict detector waves through a composition that silently loses one
+ * effect's output.
+ *
+ * `skew` is this catalog's name for "claims the whole `transform` shorthand" (see `CHANNEL.skew` in
+ * `core/types.ts`), which `carousel.css` writes on the elements this effect drives. The shorthand is
+ * unavoidable here: three-dimensional placement needs `rotateX`/`rotateY`/`translateZ` composed in a
+ * fixed order, and `rotate:`/`translate:` as individual properties are applied in the order the spec
+ * fixes, which is the reverse of the one this geometry needs.
+ *
+ * `discrete` is `display`, and it is here for exactly the reason `card-toggle` declares it
+ * (`effects/three-d/index.ts`): the unconditional host rule pins `display: grid` so every slot
+ * starts from the same cell instead of flowing down the page as block siblings. That has nothing to
+ * do with `catalog/discrete.ts`'s show/hide use of the same property, but `display` is tracked as
+ * one channel whatever value is written into it — the point of the channel model is the physical
+ * property, not the intent — so a ring composed with an `@starting-style` open/close effect is now
+ * correctly reported as a collision rather than quietly letting one of the two win.
+ *
+ * `reducedMotion: 'shorten'`, not `'disable'`, for exactly the reason `step-progress` carries the
+ * same note: under `disable` the animator never activates the instance, so no index is published,
+ * no slot is marked, and the arrows do nothing. A visitor who asked for less motion would get a
+ * dead widget rather than a calm one. Reduced motion suppresses the *travel* between places — which
+ * `base.css`'s policy layer already does to the transition `carousel.css` declares — never the
+ * function.
+ */
+export declare const SPATIAL_RING_PRIMITIVE: Primitive;
+export declare const CAROUSEL_PRIMITIVES: Primitive[];
+/**
+ * Convex and concave are two names, not one parameter with two values.
+ *
+ * They are one sign in the maths — `translateZ(+r)` puts the camera outside the ring,
+ * `translateZ(-r)` puts it at the centre — and everything else about them differs. Outside, the far
+ * half of the ring is content: smaller, dimmer, and part of the composition, and a full 360-degree
+ * spread is right. Inside, the far half is *behind your head*, so a full spread hides most of the
+ * deck and the sensible default is a slice; the cards nearest the edges of that slice are the ones
+ * that need culling; and "next" moves the world past a fixed viewer rather than turning an object
+ * in front of one.
+ *
+ * A `curve:` keyword would have made all of that one name's problem to explain, with half its
+ * documentation prefixed by "unless". Two names each get their own defaults, their own rules in
+ * `carousel.css`, and their own paragraph.
+ *
+ * `requiresOwnSubtree` on all of them: every rule in `carousel.css` past the host rule reaches the
+ * slots, so a `target:` that relocated `data-kui-fx` onto one slot would leave those selectors
+ * looking for grandchildren nobody authored. (The primitive declares a `target` parameter of its
+ * own, so `compile.ts` never consults the flag — but `test/css-requires-own-subtree.test.ts`
+ * re-derives the reaching set from the stylesheet and does, and the fact it records is true.)
+ *
+ * `phase: 'idle'` on all of them too, and for the same reason `target` does not change the answer:
+ * `channelsFor`/`findConflicts` (`core/channels.ts`) reason about the channels *this preset
+ * declares* on the host it is authored on (`CHANNEL.skew` and `'discrete'`, from
+ * `SPATIAL_RING_PRIMITIVE`), not about which element in the subtree physically paints them — the
+ * compiler has no notion of "the primitive's own target moved the real work three nodes down," and
+ * does not need one here, because `requiresOwnSubtree` already keeps this preset off of anything
+ * `target:` could relocate.
+ *
+ * The phase question itself is the same one `scroll-mechanics/presets.ts` answers at length:
+ * `prepareSpatialRing` calls `render()` unconditionally during `prepare` — before any drag, before
+ * any control click — which stamps `data-kui-step`/`--kui-step-position`/the per-slot face
+ * attributes immediately, and the primitive's `defaultActivation` is `'load'`. So, like the scroll
+ * primitives and unlike `gestures/index.ts`'s `draggable` (silent until `pointerdown`), a ring never
+ * has a quiescent stretch for an entrance to release into — it claims `skew`/`discrete` from the
+ * first frame and holds them, drag or no drag, until `destroy()`. That is `EffectPhase`'s `idle`:
+ * "runs unbounded, so it never yields the channel at all." It buys nothing new by itself —
+ * `INDEPENDENT_PHASES` exempts only `entrance|state` and `exit|state`, so `idle` still collides with
+ * everything including another `idle`, which is correct: `carousel-3d, flip-in-x` really would fight
+ * over the `transform` shorthand (`CHANNEL.skew`) for the ring's whole lifetime, and there is no
+ * turn-taking to model. It replaces "nothing is known" with the actual, checked fact.
+ *
+ * None of the four declares `transitions`: nothing here renders through a CSS `transition:` on the
+ * host box for `phaseOf` to derive `state` from — the ring is `renderer: 'javascript'` throughout.
+ */
+export declare const CAROUSEL_PRESETS: Preset[];
+/**
+ * Register the spatial carousel.
+ *
+ * @param registry - Registry to populate.
+ * @returns The same registry, for chaining.
+ * @complexity O(n) time in the number of primitives and presets.
+ */
+export declare function registerCarousel(registry: Registry): Registry;

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

@@ -0,0 +1,13 @@
+import type { Preset, Primitive } from '../../core/types.js';
+import type { Registry } from '../../core/registry.js';
+export declare const DISCRETE_PRIMITIVES: Primitive[];
+export declare const DISCRETE_PRESETS: Preset[];
+/**
+ * Register the `@starting-style` discrete-open catalog (section J).
+ *
+ * @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 registerDiscrete(registry: Registry): Registry;

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

@@ -0,0 +1,24 @@
+import type { Preset, Primitive } from '../../core/types.js';
+import type { Registry } from '../../core/registry.js';
+export declare const PROXIMITY_FIELD_PRIMITIVES: Primitive[];
+export declare const PROXIMITY_FIELD_PRESETS: Preset[];
+export declare const PROXIMITY_GLOW_PRIMITIVES: Primitive[];
+export declare const PROXIMITY_GLOW_PRESETS: Preset[];
+/** Both halves of the family, for `registerInteractionProximity` below. */
+export declare const INTERACTION_PROXIMITY_PRIMITIVES: Primitive[];
+export declare const INTERACTION_PROXIMITY_PRESETS: Preset[];
+/**
+ * Register the cross-element pointer-proximity family.
+ *
+ * A standalone top-level registration called directly from `catalog/index.ts`, the same shape
+ * `registerInteraction`'s own doc comment describes for `registerGestures`/`registerThreeD` —
+ * deliberately not folded into `interaction.ts`'s `INTERACTION_PRIMITIVES`/`_PRESETS`, which sits on
+ * that file's own 400-line lint ceiling and is being edited by another session concurrently with
+ * this one.
+ *
+ * @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 registerInteractionProximity(registry: Registry): Registry;

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;