kuinetic 0.1.3 → 0.2.0

package/dist/types/core/breakpoints.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Viewport gates — the `above:` / `below:` keys in the `data-kui` grammar.
+ *
+ * The gap this closes: there was no way to say "fade-up on desktop, nothing on mobile". `matchMedia`
+ * appeared exactly once in the whole source (`capabilities.ts`, for `prefers-reduced-motion`), and
+ * GSAP's answer — `gsap.matchMedia()` — is a runtime that also has to tear an animation down when a
+ * breakpoint changes underneath it.
+ *
+ * **A breakpoint is a media query, so the gate is compiled into CSS rather than evaluated in JS.**
+ * `gatedAnimationName` wraps a track's keyframe ident in a `var()` whose custom property is
+ * declared `none` outside the gate and guaranteed-invalid inside it (see the `kui.tokens` block in
+ * `base.css`). The browser re-resolves that on every resize with no script running, so there is
+ * nothing to observe, nothing to tear down, and nothing to get out of sync — the whole class of
+ * problem `gsap.matchMedia()` exists to manage simply does not arise. The cost is that the
+ * vocabulary has to be *closed*: a static stylesheet cannot hold a width the author invents, so
+ * `above:900px` is refused and only the five names below are accepted.
+ *
+ * ## Why these five names
+ *
+ * They are Tailwind v4's default scale, unchanged. This repo already builds `demo/tailwind.css`
+ * from its own `tailwindcss` dependency and every demo page authors against `sm`/`md`/`lg`, so
+ * adopting that scale means the library is matching a scale the project already uses rather than
+ * inventing a sixth one it would then have to own forever. `rem` rather than `px` for the reason
+ * Tailwind moved: the breakpoints then track the visitor's root font size, so a reader who has
+ * scaled their text up crosses into the "narrow" treatment at the point their layout actually
+ * reflows.
+ *
+ * ## Why `above` is inclusive and `below` is not
+ *
+ * `above:md` is `width >= md` and `below:md` is `width < md`, so the pair tiles the axis with
+ * neither a gap nor an overlap: `data-kui="fade-up below:md, parallax above:md"` runs exactly one
+ * of the two at every possible viewport width, including at exactly 768px. Splitting the boundary
+ * any other way makes one width either run both effects or run none, which is the classic
+ * `min-width`/`max-width` off-by-one — and is why this does *not* spell itself `min:`/`max:`, since
+ * CSS's own `max-width` is inclusive and would reintroduce it.
+ *
+ * ## Why `min-width` and not the range syntax
+ *
+ * `(width >= 48rem)` is Media Queries 4 and reads better, but a browser that does not parse it
+ * drops the whole block — which here means `--kui-above-md` keeps its `none` default and every
+ * `above:` gate on the page is silently off forever. `(min-width: 48rem)` has no such cliff. The
+ * shipped stylesheet and this module must agree exactly, so both use the same spelling.
+ */
+/**
+ * The scale. Ordered narrowest to widest — `breakpointRank` depends on the declaration order, and
+ * `parse.ts` uses that ordering to refuse a band that can never match.
+ */
+export declare const BREAKPOINTS: {
+    readonly sm: "40rem";
+    readonly md: "48rem";
+    readonly lg: "64rem";
+    readonly xl: "80rem";
+    readonly '2xl': "96rem";
+};
+export type Breakpoint = keyof typeof BREAKPOINTS;
+/** In scale order, for `breakpointRank` and for naming the accepted values in a diagnostic. */
+export declare const BREAKPOINT_NAMES: Breakpoint[];
+/**
+ * A segment's condition, lifted onto the spec by `parse.ts`. Two independent axes:
+ *
+ * - `above`/`below` — the **viewport** condition, `data-kui="fade-up above:md"`. Compiled into
+ *   `:root`-scoped custom properties in `base.css` (see `gatedAnimationName`), so the browser
+ *   re-decides on every resize with no script involved.
+ * - `wide`/`narrow` — the **container** condition, `data-kui="fade-up wide:md"`, decided against
+ *   the element's nearest `data-kui-container` ancestor rather than the viewport. Neither axis
+ *   subsumes the other: `above:md` answers "is the window at least 768px", `wide:md` answers "is
+ *   the box I sit in at least 768px", and a component reused at more than one width on the same
+ *   page needs the second question. `wide`/`narrow` compile the same way `above`/`below` do
+ *   (`gatedAnimationName` wraps both axes), with one deliberate asymmetry in their CSS
+ *   defaults — see the `@container` block in `base.css` for why.
+ *
+ * All four keys may be present at once, each pair forming a band the same way: `above:md
+ * below:xl` runs only between the two, and `wide:md narrow:xl` does the same against the
+ * container. That falls out of the CSS for free — the `var()`s nest arbitrarily deep — so bands
+ * are supported rather than refused on either axis.
+ */
+export interface EffectGate {
+    above?: Breakpoint;
+    below?: Breakpoint;
+    wide?: Breakpoint;
+    narrow?: Breakpoint;
+}
+export type GateDirection = keyof EffectGate;
+/**
+ * The other direction on this one's axis — `above` pairs with `below`, `wide` pairs with `narrow`.
+ * Used wherever a check has to reason about a *band* rather than a single direction, so a new axis
+ * only ever needs an entry in {@link GATE_AXES} rather than a new branch at every call site.
+ *
+ * @complexity O(1) time (two axes, checked in a fixed order); O(1) space.
+ * @overallScore 100
+ */
+export declare function axisOf(direction: GateDirection): readonly [GateDirection, GateDirection];
+/**
+ * Whether a token names a breakpoint on the scale.
+ *
+ * `Object.hasOwn`, not `value in BREAKPOINTS` and not a truthiness test on the lookup: the value
+ * comes straight off an author-written attribute, so `above:constructor` and `above:__proto__`
+ * both resolve to an inherited value on `Object.prototype` and would be accepted as breakpoints.
+ * The same trap `parse.ts` documents on its `HOISTS` table.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function isBreakpoint(value: string): value is Breakpoint;
+/**
+ * Position on the scale, narrowest first.
+ *
+ * @complexity O(b) time in the scale's length — five; O(1) space.
+ * @overallScore 100
+ */
+export declare function breakpointRank(name: Breakpoint): number;
+/**
+ * The custom property one direction/breakpoint pair is switched by. Shared by both axes — `above`/
+ * `below` name a `@media`-declared switch, `wide`/`narrow` name an `@container`-declared one — the
+ * spelling is identical either way, so one function serves both rather than a `containerProperty`
+ * duplicate of it.
+ *
+ * This name is a contract with `src/css/base.css`, which declares all twenty (ten per axis).
+ * Changing the spelling here without changing it there compiles a `var()` that resolves to
+ * nothing, and a `var()` that resolves to nothing falls through to its fallback — so every gate
+ * would silently be *on* everywhere, which is the failure a reader would be least likely to
+ * notice. `test/breakpoints.test.ts` asserts the two agree.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function gateProperty(direction: GateDirection, breakpoint: Breakpoint): string;
+/**
+ * The media query one breakpoint is switched at. Deliberately only ever `min-width`: the `below`
+ * half is the *negation* of this same query rather than a `max-width` of its own, so the two halves
+ * cannot drift apart at the boundary. See the header note on inclusivity.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function breakpointQuery(breakpoint: Breakpoint): string;
+/**
+ * A track's `animation-name` value, gated.
+ *
+ * `kui-in-up` becomes `var(--kui-above-md, kui-in-up)`. Outside the gate that property holds
+ * `none`, so the track is a named-nothing entry in the composed `animation-name` list: its
+ * duration, delay, easing and fill-mode entries all still sit at the same index and are simply
+ * ignored, which is what keeps a *composed* element's parallel longhand lists aligned. Inside the
+ * gate the property is the guaranteed-invalid value and `var()` falls through to the real ident.
+ *
+ * A gated-off track leaves nothing behind: with no animation there is no `animation-fill-mode:
+ * both` holding a from-state, so the element paints at its ordinary rest state. That is the
+ * property that makes "nothing on mobile" safe — the zero-area presets that have historically
+ * stranded elements did so through a from-state that never got released, and there is no
+ * from-state here to release.
+ *
+ * A band nests the two, and the order matters only for readability: `above` outermost reads as
+ * "not wide enough → off; otherwise, too wide → off; otherwise run". `wide`/`narrow` nest the same
+ * way, innermost, so all four conditions the author wrote — viewport band and container band
+ * together — AND together through the same chain of `var()` fallbacks: any one of them resolving
+ * to `none` neutralises the whole expression, regardless of which axis it came from.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function gatedAnimationName(keyframes: string, gate: EffectGate | undefined): string;
+/**
+ * Whether a gate is currently satisfied — the JavaScript mirror of the CSS above.
+ *
+ * Needed *only* for JavaScript-rendered segments. A `css-keyframes` segment is gated by the
+ * compiled `var()` and never consults this; a JS-rendered one emits no `animation-name` at all, so
+ * there is nothing for a stylesheet to neutralise and the decision has to be made here. That is
+ * the whole of the JS fallback, and it is a stated limit rather than a hidden one: gating is free
+ * for the large majority of the catalog that compiles to keyframes, and costs one `matchMedia`
+ * read plus one `change` listener for the rest.
+ *
+ * **Fails open.** No `matchMedia` — a server render, a bare Node runtime, jsdom, which has none —
+ * means the effect runs. The alternative is an environment with no viewport deciding that every
+ * gated effect is off, which is a silent no-op, and "never a silent no-op" is the one promise the
+ * grammar makes everywhere else.
+ *
+ * Reads only the viewport axis (`above`/`below`). The container axis (`wide`/`narrow`) has no
+ * equivalent here on purpose — there is no `matchContainer()`, and building one is a
+ * `ResizeObserver` per container plus a re-entrancy-safe notify path for one attribute. A
+ * JavaScript-rendered primitive refuses a container gate at compile time instead of faking it (see
+ * `refuseContainerGate` in `compile.ts`), so a gate reaching this function has already had `wide`/
+ * `narrow` stripped if it ever had them — there is nothing left for this function to ignore.
+ *
+ * @param gate - The segment's condition; `undefined` is an ungated segment and always matches.
+ * @param win - Window to query. Injected rather than reached for, exactly as
+ *   `effects/catalog/interaction-shared.ts` injects it for its `(hover: hover)` probe.
+ * @complexity O(1) time and space — at most two media queries.
+ * @overallScore 100
+ */
+export declare function gateMatches(gate: EffectGate | undefined, win: Window | undefined): boolean;
+/**
+ * Whether two gates can ever be satisfied at the same time, on both axes at once.
+ *
+ * Read by `channels.ts`: two effects that are never live together cannot collide on a channel, so
+ * `fade-up below:md, parallax-y above:md` composes even though both own `translate`. Without this
+ * the compiler would refuse that pair — the exact list the gate exists to make expressible — and
+ * silently drop its second half at every width. `wide:md` and `above:md` are independent
+ * conditions — a wide container inside a narrow viewport is ordinary layout — so overlap requires
+ * agreement on **both** axes: two gates that are disjoint on either one alone can never be live
+ * together, however the other axis compares.
+ *
+ * Each direction is a half-open interval over the scale's *ranks*, which is exact because the only
+ * boundaries that exist are the five breakpoints themselves: `above:X`/`wide:X` starts at `rank(X)`
+ * and an absent upper bound starts below the narrowest name; `below:Y`/`narrow:Y` ends at `rank(Y)`
+ * and an absent lower bound runs past the widest. Half-open is what makes the boundary come out
+ * right — `[below:md)` ends exactly where `[above:md)` begins, so the two touch without
+ * overlapping, which is the same property that makes a complementary pair tile an axis.
+ *
+ * @complexity O(b) time in the scale's length; O(1) space.
+ * @overallScore 100
+ */
+export declare function gatesOverlap(a: EffectGate | undefined, b: EffectGate | undefined): boolean;
+/**
+ * Breakpoints a set of gates depends on, deduplicated. Empty for an ungated list.
+ *
+ * Only ever called on `EffectGate`s already filtered to JavaScript-rendered effects
+ * (`Animator.applyViewportGates`), and those never carry `wide`/`narrow` — `refuseContainerGate`
+ * in `compile.ts` strips both before a gate reaches `plan.jsEffects`. Reading only `above`/`below`
+ * here is therefore not a gap, it mirrors `gateMatches`'s own scope.
+ *
+ * @complexity O(g) time in the gate count; O(b) space, bounded by the scale's five names.
+ * @overallScore 100
+ */
+export declare function breakpointsIn(gates: readonly EffectGate[]): Breakpoint[];
+export interface GateWatcher {
+    /**
+     * Re-notify about `el` whenever one of `breakpoints` is crossed. An empty list unwatches, so a
+     * caller can pass whatever it computed without branching first.
+     */
+    watch(el: Element, breakpoints: readonly Breakpoint[]): void;
+    unwatch(el: Element): void;
+    destroy(): void;
+}
+/**
+ * Watch the breakpoints a page's JavaScript-rendered gates actually name.
+ *
+ * Only JS-rendered gates ever reach here (see `gateMatches`), so on a page whose gates are all on
+ * CSS effects — the common case — nothing is ever watched and no listener is ever bound. The cost
+ * of this feature is genuinely zero until a `pin-section below:md` asks for it.
+ *
+ * The reaction to a crossing is deliberately "tell the caller about the element" rather than
+ * anything cleverer: the animator already has exact teardown (`release`) and exact reinstall
+ * (`process`), both used on every attribute edit, so a breakpoint change reuses the path that is
+ * already exercised rather than inventing a second, partial one. That is also what makes the
+ * transition correct at the boundary — a JS effect that was running is destroyed through its own
+ * `EffectInstance.destroy()` and its style writes unwound by the ledger before the new plan is
+ * installed, so nothing is left half-applied.
+ *
+ * A single `Map` of element → breakpoints rather than a reverse index per breakpoint: the map only
+ * ever holds elements with a gated JS effect, so a linear scan on a crossing is a handful of
+ * entries, and a second index would be more state to keep consistent than the scan costs.
+ *
+ * @param win - Window to bind against; `undefined`, or one with no `matchMedia`, yields a watcher
+ *   that accepts every call and does nothing. Install-time gating still applies in that case; only
+ *   live re-evaluation is dropped.
+ * @param onChange - Called with each affected element when a watched breakpoint is crossed.
+ * @complexity O(1) per `watch`/`unwatch`; O(w) per crossing in the number of watched elements.
+ * @overallScore 100
+ */
+export declare function createGateWatcher(win: Window | undefined, onChange: (el: Element) => void): GateWatcher;

package/dist/types/core/bundles.d.ts

@@ -0,0 +1,71 @@
+import type { Registry } from './registry.js';
+import type { Reporter } from './reporter.js';
+import type { ParsedValue } from './types.js';
+/**
+ * Author-defined bundles for one animator root.
+ *
+ * A class rather than a closure for the same reason {@link Registry} is one: it is a table with a
+ * handful of operations on it, and the operations read better named than nested.
+ */
+export declare class BundleTable {
+    private readonly registry;
+    private readonly bundles;
+    /**
+     * @param registry - Consulted for name collisions only; a bundle never enters it.
+     */
+    constructor(registry: Registry);
+    /**
+     * Register every definition in a subtree, including the subtree root itself.
+     *
+     * @returns How many *new* names were registered, so the caller can decide whether anything it
+     *   already compiled deserves a second chance.
+     * @complexity O(n) time in the subtree's element count; O(d) space in definition count.
+     * @overallScore 100
+     */
+    collect(root: ParentNode, reporter: Reporter): number;
+    /**
+     * Rewrite bundle references into the segments they stand for.
+     *
+     * @returns A new `ParsedValue`; the argument is returned untouched when nothing is defined.
+     * @complexity O(s) time in the total segment count across the bundles reached; O(s) space.
+     * @overallScore 100
+     */
+    expand(parsed: ParsedValue): ParsedValue;
+    /**
+     * Register one definition element.
+     *
+     * @returns Whether this call added a name the table did not have.
+     * @complexity O(n) time in the body's length; O(e) space in its segment count.
+     * @overallScore 100
+     */
+    private define;
+    /**
+     * Refuse a name that cannot work, with the reason.
+     *
+     * @returns The diagnostic, or `undefined` when the name is usable.
+     * @complexity O(n) time in the name's length; O(1) space.
+     * @overallScore 100
+     */
+    private nameProblem;
+    /**
+     * Expand one comma list, recursing through bundles that name other bundles.
+     *
+     * @param trail - Bundle names currently being expanded, innermost last. Both the cycle guard and
+     *   its diagnostic read it, so it is a list rather than a set.
+     * @complexity O(s) time in the total segment count across the bundles reached; O(s) space.
+     * @overallScore 100
+     */
+    private expandList;
+    /**
+     * Name an unregistered effect that is one typo away from a bundle.
+     *
+     * `compile.ts` already reports every unknown name, with a suggestion drawn from the catalog — a
+     * misspelled *bundle* is invisible in that list, so this adds the one fact that message cannot
+     * carry. Only for names the registry does not know, or a real effect one edit away from a badly
+     * chosen bundle name would be reported as a mistake.
+     *
+     * @complexity O(b·n) time in bundle count and name length; O(n) space.
+     * @overallScore 100
+     */
+    private noteNearMiss;
+}

package/dist/types/core/callback.d.ts

@@ -0,0 +1,64 @@
+import type { Reporter } from './reporter.js';
+/**
+ * `func:` — a named global function, called when the element's effects finish.
+ *
+ * ## What this is, and what it is not
+ *
+ * It is **sugar for one line of DOM**, and it is implemented as literally that line:
+ *
+ * ```js
+ * el.addEventListener('kui:finish', window[name])
+ * ```
+ *
+ * Nothing here invents a new moment for a callback to fire at. `animator.ts` already dispatches
+ * `kui:finish` at exactly one place, and this module registers an ordinary listener for it — so
+ * `func:` cannot drift out of step with the event, because it *is* the event. That also means the
+ * function receives the same `LifecycleEvent` a hand-written listener receives, with `this` bound to
+ * the same element, so moving code between the two spellings is a copy-paste rather than a rewrite.
+ *
+ * It is **not** the recommended API. `addEventListener('kui:finish', fn)` works with bundlers and ES
+ * modules, allows several listeners on one element, and needs no global — and every project with a
+ * build step should use it. `func:` exists for the no-build site: a page with a `<script>` block, an
+ * attribute, and no module graph to hang a listener off. That audience is real, and telling them to
+ * "just import the library and add a listener" is telling them to adopt a toolchain to run one
+ * function.
+ *
+ * ## The one risk an integrator has to own
+ *
+ * `func:` turns an attribute value into a function call, so **whoever controls the attribute
+ * controls which global function runs**. On a hand-authored page that is the author, and there is no
+ * gap. On a page where `data-kui` is assembled from a CMS field, a URL parameter, or any other input
+ * an end user can influence, it is *them* — and a value they choose can invoke any function the page
+ * happens to have put on `window`, with the animated element as `this`.
+ *
+ * The lookup below is deliberately as narrow as it can be while still doing the job: an own-property
+ * read on the element's own window, a `typeof === 'function'` check before calling, no dotted path
+ * traversal, and no `eval`/`Function` anywhere — so the value can *name* a function but can never
+ * *be* one. That closes code injection. It does not, and cannot, close "call any function by name",
+ * because that is the feature. If `data-kui` on your site is ever built from untrusted input, use
+ * the event API for the callback and keep `func:` out of the template.
+ */
+/** Everything `bindCallback` needs, grouped so the call site reads as one request. */
+export interface CallbackRequest {
+    /** The host element. The one lifecycle events are dispatched on, and the callback's `this`. */
+    el: Element;
+    /** The authored `func:` value — a bare global name, unvalidated by `parse.ts`. */
+    name: string;
+    /** Diagnostic sink. Silent by default, exactly as it is for an unknown effect name. */
+    reporter: Reporter;
+    /** The instance's teardown signal, so the listener detaches with everything else. */
+    signal: AbortSignal;
+}
+/**
+ * Register an author's named global as a `kui:finish` listener on one element.
+ *
+ * The name is resolved **at fire time, not here**, and that is deliberate: a no-build page routinely
+ * defines its functions in a `<script>` that runs after the library has scanned, and resolving
+ * eagerly would reject every one of those with a warning that was wrong by the time it printed.
+ * The cost is that a typo stays silent until the animation completes — at which point it warns,
+ * naming the value, which is the same deal every other diagnostic in the grammar offers.
+ *
+ * @complexity O(1) time and space to register; O(1) per event beyond the author's own function.
+ * @overallScore 100
+ */
+export declare function bindCallback(request: CallbackRequest): void;

package/dist/types/core/capabilities.d.ts

@@ -14,6 +14,53 @@ export interface Capabilities {
     viewTransitions: boolean;
     intersectionObserver: boolean;
     reducedMotion: boolean;
+    /**
+     * CSS Motion Path — `offset-path`, and with it `offset-distance`/`offset-rotate`/`offset-anchor`.
+     *
+     * Probed with a `path()` value specifically, not with `offset-path` alone: Chrome shipped
+     * `offset-path: path()` years before it accepted a `<basic-shape>` there, so "does this property
+     * parse" and "does this property parse the thing we emit" are different questions, in the same
+     * way `view()` and `scroll()` are two probes above rather than one.
+     */
+    motionPath: boolean;
 }
+/**
+ * Build a `Capabilities` from only the fields a caller actually has an opinion about.
+ *
+ * `Capabilities` is a closed record of required booleans, so before this existed every object
+ * literal constructing one had to name every field. Adding `motionPath` was therefore O(number of
+ * construction sites) rather than O(1), and it broke three test harnesses in a single merge — none
+ * of which had any interest in motion paths, and all of which failed to compile purely for not
+ * mentioning one. Spreading a complete default makes a new field additive everywhere instead.
+ *
+ * Deliberately *not* used by `detect()`, even though `detect()` is a construction site too. Its
+ * literal is the detection logic: keeping it exhaustive is what makes the compiler demand a real
+ * probe for each new capability. Route it through here and adding a field would type-check the
+ * moment it was given a default, and ship as permanently `false` in every browser — the feature
+ * dead in production, with no test able to notice. So the two defaults differ on purpose: a
+ * caller stating a fixed environment gets "absent unless said otherwise", and production gets no
+ * constant default at all, because the honest answer there is always "go and probe it". Adding a
+ * capability still means editing one file — this one — in two adjacent places the compiler names.
+ *
+ * There is deliberately no `allCapabilities()` counterpart. A harness that wants a fully modern
+ * browser lists its `true`s, because the alternative is a test opting in to every capability
+ * invented after it was written.
+ *
+ * @param overrides - Fields this caller has actually decided; everything else comes back absent.
+ * @returns A fully-populated capability record.
+ * @complexity O(c) time and space in the number of capability fields — fixed and single-digit.
+ * @overallScore 100
+ */
+export declare function defaultCapabilities(overrides?: Partial<Capabilities>): Capabilities;
 export declare function detect(force?: boolean): Capabilities;
 export declare function resetCapabilities(): void;
+/**
+ * Diagnostics for composed channels this environment cannot render.
+ *
+ * @param channels - Channels the compiled effects write to (`CompiledPlan.channels`).
+ * @param capabilities - The environment's detected capabilities.
+ * @returns One message per unsupported channel; empty in a browser that supports them all.
+ * @complexity O(r) time in the requirement table's length — single digits; O(1) space per message.
+ * @overallScore 100
+ */
+export declare function unsupportedChannelWarnings(channels: readonly string[], capabilities: Capabilities): string[];

package/dist/types/core/channels.d.ts

@@ -1,4 +1,5 @@
-import type { Channel } from './types.js';
+import type { EffectGate } from './breakpoints.js';
+import type { Channel, DeliveryMechanism, EffectPhase } from './types.js';
 /**
  * Composition safety.
  *
@@ -9,17 +10,134 @@ import type { Channel } from './types.js';
  *
  * Hence channels. An effect declares the property groups it owns; a comma list is only safe to
  * compile when those sets are pairwise disjoint. See docs/design.md §4.
+ *
+ * "Pairwise disjoint" gained a second dimension when viewport gates arrived: two effects that can
+ * never be live at the same viewport width cannot collide however many channels they share. That
+ * is not a nicety — `fade-up below:md, parallax-y above:md` is the flagship case the gate exists
+ * for, both halves own `translate`, and without the width check the compiler would refuse the pair
+ * and drop the second half at every width.
+ *
+ * And a third: *when* each effect holds the channel. Disjointness in space and time are the same
+ * kind of exemption — `fade-up, lift` share `translate` and share every width, but an entrance and
+ * a hover state are not fighting over the property, they are taking turns with it. See
+ * {@link EffectPhase} for why that is a declared fact rather than a derived one, and
+ * {@link independentPhases} for which pairs qualify.
  */
 export interface ChannelClaim {
     name: string;
     channels: Channel[];
+    /** Viewport condition, if the segment carries one. Absent means "live at every width". */
+    gate?: EffectGate;
+    /**
+     * When this segment holds its channels, if that is known. Absent means unphased — the preset
+     * declares no phase and none could be derived — and an unphased claim collides with everything,
+     * itself included, which is exactly how every claim behaved before this field existed.
+     */
+    phase?: EffectPhase;
+    /**
+     * Whether the caller can put `animation-composition: add` on whatever this segment compiles to.
+     * Asked of the caller rather than worked out here because the answer is about the *renderer* —
+     * how many keyframe blocks the segment produces, and whether it produces any at all — which is
+     * `compile.ts`'s knowledge. What is additive about a *channel* stays here, in
+     * {@link CHANNEL_COMPOSITION}.
+     */
+    additive?: boolean;
+    /**
+     * How this segment's motion reaches the element, when that is something composition has to act on
+     * — see `types.ts`'s {@link DeliveryMechanism}. Read only by {@link deliveryClobbers}, never by
+     * {@link findConflicts}: it describes a fight over a *property* rather than over a channel.
+     */
+    delivery?: DeliveryMechanism;
+    /**
+     * Whether this segment writes `animation-name` to `element.style`. Asked of the caller for the
+     * same reason {@link additive} is — it is a fact about the renderer, which is `compile.ts`'s
+     * knowledge, not this module's.
+     */
+    inlineAnimation?: boolean;
 }
 export interface Conflict {
     channel: Channel;
     effects: [string, string];
 }
-/** Every pair of effects claiming the same channel. Empty array means the list composes. */
+/**
+ * Which channels may be composed by *adding* two animations' output rather than replacing it, and
+ * which must stay one-writer-only.
+ *
+ * Deliberately an allowlist with one member. `animation-composition: add` looks like a general
+ * answer to this whole problem and is not: addition in Web Animations L1 is defined per property
+ * type, and a property with no additive definition — anything discrete, and every value CSS
+ * resolves as a keyword — falls back toward replacement *silently*. Applying `add` across the
+ * board would convert a loud, detectable conflict into a quiet browser-dependent last-writer
+ * result, which is strictly worse than the drop it was meant to fix. The channel set includes
+ * `clip`, `background`, `text`, display-like channels and, through `Channel`'s open `string` arm,
+ * whatever a third-party primitive registers — none of which anyone has tested.
+ *
+ * So: `translate` is here because a translation is a vector with a well-defined sum and a neutral
+ * `0px 0px 0px`, and nothing else is here until someone measures it in a browser and adds it.
+ */
+export declare const CHANNEL_COMPOSITION: Partial<Record<Channel, 'add'>>;
+/** Whether every channel a claim writes can survive being made additive. */
+export declare function additiveChannels(channels: readonly Channel[]): boolean;
+/**
+ * Rescue a surviving clash by summing the claims that caused it instead of letting one replace the
+ * other.
+ *
+ * The last resort, and deliberately the narrowest of the three exemptions the detector offers — a
+ * gate says the two are never live together, a phase says they take turns, and this one admits they
+ * genuinely overlap and asks the browser to blend them.
+ *
+ * All-or-nothing over the whole contested set. A partly-additive list is the worst outcome
+ * available: the author is told nothing, and one of the two effects is quietly replaced anyway.
+ *
+ * @returns Indices of the claims to compile additively, or `undefined` when the rescue does not
+ *   apply and the caller should refuse the list.
+ * @complexity O(n * c) time in claims and their channels; O(n + c) space.
+ * @overallScore 100
+ */
+export declare function additiveResolution(claims: ChannelClaim[], conflicts: Conflict[]): Set<number> | undefined;
+/**
+ * Every pair of effects claiming the same channel at widths where both can be live, in phases where
+ * both can hold it. Empty array means the list composes.
+ *
+ * Each channel keeps a *list* of prior claimants rather than a single owner, and a claim is
+ * reported against the first one it actually overlaps. With no gates in play that first one is
+ * always the first claim, so the output is exactly what a single-owner map produced. With gates it
+ * is the difference between catching a real collision and inventing one: in `fade-up below:md,
+ * parallax-y above:md, slide-up above:md` the genuine clash is the second pair, and a map holding
+ * only `fade-up` would have compared both later effects against a segment neither can coexist with
+ * and waved the list through.
+ *
+ * @complexity O(n^2) worst case in same-channel claimants; a comma list is a handful of segments.
+ * @overallScore 100
+ */
 export declare function findConflicts(claims: ChannelClaim[]): Conflict[];
+/**
+ * Clashes over *how* each segment's motion is delivered, which {@link findConflicts} cannot see.
+ *
+ * That function asks which property groups two segments write, and for two compiled animation
+ * tracks it is the right question. It is the wrong one here. A preset whose motion is
+ * `[data-kui-fx~='icon-spin']:hover { animation: … }` in `src/css/interaction.css` loses the
+ * `animation` property to *any* composed neighbour that writes `animation-name` inline, because an
+ * inline declaration outranks an author rule outright. It does not matter that `icon-spin` writes
+ * `rotate` and `fade-up` writes `opacity`/`translate` — the two never shared a channel, the
+ * detector correctly reported nothing, and `fade-up, icon-spin` composed clean with the hover
+ * silently dead. 548 such pairs, measured, and pre-existing rather than introduced by the phase
+ * axis: see `types.ts`'s {@link DeliveryMechanism} and the 2026-09-08 catalog review.
+ *
+ * There is no rescue and deliberately none offered. A gate does not help, unlike in
+ * {@link findConflicts}: `gatedAnimationName` compiles an out-of-band track to
+ * `animation-name: var(--kui-above-md, kui-in-up)` and `base.css` declares that property `none`
+ * outside the gate — `none` is still an inline value, still outranks the stylesheet rule, and
+ * leaves the hover just as dead below the breakpoint as above it. Neither does
+ * {@link additiveResolution}: `animation-composition` blends two tracks that both run, and the
+ * whole failure here is a rule that never becomes active.
+ *
+ * @returns One sentence per clobbered claim, in the shape {@link describeConflicts} produces, or an
+ *   empty array when nothing in the list writes an inline animation.
+ * @complexity O(n) time in the claim count; O(n) space.
+ * @overallScore 100
+ */
+export declare function deliveryClobbers(claims: ChannelClaim[]): string[];
 export declare function describeConflicts(conflicts: Conflict[]): string;
 /** Union of all claimed channels, for debugging and perf accounting. */
 export declare function claimedChannels(claims: ChannelClaim[]): Channel[];

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

@@ -0,0 +1,47 @@
+/**
+ * Owned by phase 9a — the pre-JS cloak selector strings, pulled out of
+ * `scripts/generate-preset-css.mjs` so the generator can grow the comma-form handling 9a needs
+ * (`cloak: true`/`cloak:'.a, .b'`-style selector lists, per the owner decision) without hand-editing
+ * the bundled generator script directly.
+ *
+ * `~=` matches a whole whitespace-separated token, but a `data-kui` value's segments are
+ * comma-separated, not space-separated — `data-kui="text-reveal-mask,\nfade-up"` puts the comma
+ * straight up against the previous word, so the actual whitespace token is `text-reveal-mask,`, not
+ * `text-reveal-mask`. An author can glue that comma to either side (or both, mid-list), so each name
+ * or gate token needs one `[data-kui~=…]` per comma form, grouped in a single `:is()` so the cloak
+ * still matches whichever form the author wrote. `:is()` takes the specificity of its most specific
+ * argument; every form here has identical specificity, so the grouped selector keeps HEAD's
+ * specificity exactly. A browser old enough to reject `:is()` drops the whole rule and fails open —
+ * not cloaking is exactly today's (pre-9a) behaviour, same fail-open the bare-comma case already had.
+ */
+/**
+ * The four ways one `data-kui` token can sit relative to its neighbours' commas: alone, followed by
+ * a glued comma, preceded by one, or both (mid-list with no surrounding spaces).
+ *
+ * @param token - The preset name or gate token, as written in `data-kui`.
+ * @returns The four literal token forms, in `[data-kui~=…]` match order.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function cloakTokenForms(token: string): string[];
+/**
+ * The pre-JS cloak selector for one preset name — matched while `<html data-kui-cloak>` is still
+ * present, so an element carrying that preset stays hidden until the animator's own `data-kui-*`
+ * state attribute lands and the ordinary ready-gate rules take over.
+ *
+ * @param name - The preset name, as written in `data-kui`.
+ * @returns One selector line (no trailing comma or newline).
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function cloakSelector(name: string): string;
+/**
+ * The gate-release selector for one gate token (e.g. `above:md`) — the selector half of
+ * `gateReleaseRules`'s per-token block, without the trailing ` {` a caller appends itself.
+ *
+ * @param token - The gate token, as written in `data-kui`.
+ * @returns One selector line (no trailing ` {` or newline).
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function gateReleaseSelector(token: string): string;