kuinetic 0.1.0

package/dist/types/core/scroll-scheduler.d.ts

@@ -0,0 +1,153 @@
+import type { Cleanup } from './types.js';
+/**
+ * Shared scroll orchestration.
+ *
+ * "Zero scroll listeners" is a property of *native timeline* effects and does not survive contact
+ * with pinning, scrubbing, or spying — those need the scroll position as a number. The correct
+ * architecture is the one docs/design.md §13 names: one passive listener per scroll root that
+ * marks a shared scheduler dirty, and exactly one rAF callback per dirtied frame. An
+ * always-running rAF loop is the thing being avoided, not the listener.
+ *
+ * Every collaborator is injected. The frame source, the scroll roots, and the scrollability test
+ * are all parameters, so the whole module is drivable from tests with no layout, no timers, and
+ * no real scrolling.
+ */
+/** What a scroll root reports each frame. One read per root, shared by all its subscribers. */
+export interface ScrollMetrics {
+    scrollTop: number;
+    scrollLeft: number;
+    /** Visible size of the root's scrollport. */
+    viewportWidth: number;
+    viewportHeight: number;
+    /**
+     * Position of the scrollport itself in the viewport. Zero for the window.
+     *
+     * Without this, a subscriber measuring an element with `getBoundingClientRect` — which is
+     * viewport-relative — and subtracting a nested scroller's `scrollTop` — which is local to that
+     * scroller — mixes two coordinate systems, and every nested progress value is wrong by the
+     * scroller's own offset.
+     */
+    viewportTop: number;
+    viewportLeft: number;
+}
+/**
+ * A scrollable context. The window is one; any `overflow: auto` element is another.
+ *
+ * `key` identifies the root for deduplication: two effects inside the same scroller must share a
+ * listener, or a page with 200 pinned elements installs 200 listeners.
+ */
+export interface ScrollRoot {
+    key: string;
+    metrics(): ScrollMetrics;
+    /** Attach a passive scroll listener. Returns its own removal. */
+    onScroll(handler: () => void): Cleanup;
+    /** Attach a resize listener. Resize invalidates cached measurements, so it bumps the epoch. */
+    onResize(handler: () => void): Cleanup;
+}
+export interface ScrollFrame {
+    metrics: ScrollMetrics;
+    /**
+     * Increments whenever something invalidated cached geometry. Subscribers cache measurements
+     * against this number instead of re-measuring every frame, which is what keeps a scroll frame
+     * off the layout path.
+     */
+    epoch: number;
+}
+export type ScrollSubscriber = (frame: ScrollFrame) => void;
+export interface SchedulerDeps {
+    requestFrame(callback: () => void): number;
+    cancelFrame(handle: number): void;
+}
+export interface ScrollScheduler {
+    /**
+     * Receive a frame whenever `root` scrolls or resizes, plus one immediately-scheduled frame so a
+     * subscriber never has to wait for user input to reach its initial state.
+     */
+    subscribe(root: ScrollRoot, onFrame: ScrollSubscriber): Cleanup;
+    /** Bump the epoch and schedule a frame, for layout changes the scheduler cannot observe. */
+    invalidate(): void;
+    /** Live root count. Diagnostics and leak assertions. */
+    rootCount(): number;
+    destroy(): void;
+}
+/**
+ * Create a scroll scheduler.
+ *
+ * @param deps - Frame source. Defaults to `requestAnimationFrame`, falling back to a timer where
+ *   rAF does not exist (jsdom, workers).
+ * @returns A scheduler that runs at most one frame per dirtying event.
+ * @complexity O(s) time per frame in subscribers of dirtied roots; O(r + s) space.
+ * @overallScore 100
+ */
+export declare function createScrollScheduler(deps?: SchedulerDeps): ScrollScheduler;
+/**
+ * The window as a scroll root.
+ *
+ * @param win - Window to observe. Passed in so iframes, test doubles, and multiple documents work.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function windowScrollRoot(win: Window): ScrollRoot;
+/**
+ * An `overflow: auto` element as a scroll root.
+ *
+ * Nested scroll containers are a first-class case, not an edge case: a pinned element inside a
+ * modal or a horizontally scrolled track must track *its* scroller, not the page.
+ *
+ * @param el - The scrolling element.
+ * @param win - Window used for resize notification; element resize alone does not cover viewport
+ *   changes that alter the element's own box.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function elementScrollRoot(el: Element, win: Window): ScrollRoot;
+export interface RootResolverOptions {
+    win: Window;
+    /** Injected so the overflow test is fakeable; the default reads computed style. */
+    isScrollable?: (el: Element) => boolean;
+}
+/**
+ * Find the scroll root that actually moves a given element.
+ *
+ * @param options - Window plus an optional scrollability predicate.
+ * @returns A resolver returning the nearest scrollable ancestor, or the window root.
+ * @complexity O(d) time in DOM depth per call; O(1) space.
+ * @overallScore 100
+ */
+export declare function createRootResolver(options: RootResolverOptions): (el: Element) => ScrollRoot;
+/**
+ * Clamp to the unit interval.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function clamp01(value: number): number;
+/**
+ * Progress of `position` through the range `[start, end]`, clamped.
+ *
+ * A zero-length range is the degenerate case that matters: an element shorter than its own pin
+ * distance, or a track no wider than its viewport. Returning 0 rather than `Infinity`/`NaN` keeps
+ * every downstream write finite.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function progressBetween(start: number, end: number, position: number): number;
+export interface MeasureCache<T> {
+    /** Measured value for this epoch, re-measuring only when the epoch moved. */
+    read(epoch: number): T;
+    clear(): void;
+}
+/**
+ * Memoise a measurement against the scheduler's epoch.
+ *
+ * This is what makes a scroll frame cheap: geometry is read once per resize, not once per frame.
+ * Getting this wrong is the difference between a pinned page that scrolls at 60fps and one that
+ * forces a full layout on every wheel tick.
+ *
+ * @param measure - The layout-reading function to memoise.
+ * @returns A cache keyed on epoch.
+ * @complexity O(1) amortised per read; O(1) space.
+ * @overallScore 100
+ */
+export declare function createMeasureCache<T>(measure: () => T): MeasureCache<T>;

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

@@ -0,0 +1,83 @@
+/**
+ * Spring integration.
+ *
+ * Gestures need physics rather than easing curves: when a user throws an element, the animation
+ * has to start at whatever velocity their finger had, and no duration-plus-easing formulation can
+ * express that. A spring is the smallest model that can — it takes an initial velocity and
+ * settles on its own.
+ *
+ * The integrator is a pure function of `(state, target, config, dt)`, so the whole model is
+ * assertable without timers, rAF, or a DOM.
+ */
+export interface SpringConfig {
+    /** Higher pulls harder toward the target. */
+    stiffness: number;
+    /** Higher removes energy faster. Critical damping is `2 * sqrt(stiffness * mass)`. */
+    damping: number;
+    mass: number;
+    /** Settled when both velocity and displacement fall below these. */
+    restVelocity: number;
+    restDisplacement: number;
+}
+export interface SpringState {
+    value: number;
+    velocity: number;
+}
+export declare const DEFAULT_SPRING: SpringConfig;
+/**
+ * Advance a spring toward `target`.
+ *
+ * @param state - Current value and velocity.
+ * @param target - Value the spring is pulling toward.
+ * @param config - Stiffness, damping, mass, and rest thresholds.
+ * @param dt - Elapsed seconds since the last step.
+ * @returns The new state; input is not mutated.
+ * @complexity O(dt / SUBSTEP) time, bounded by MAX_STEP; O(1) space.
+ * @overallScore 100
+ */
+export declare function stepSpring(state: SpringState, target: number, config: SpringConfig, dt: number): SpringState;
+/**
+ * Whether a spring has settled.
+ *
+ * Both conditions are required: a spring passing through its target at speed has zero
+ * displacement but is nowhere near done.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function isSettled(state: SpringState, target: number, config: SpringConfig): boolean;
+export interface SpringDeps {
+    requestFrame(callback: (time: number) => void): number;
+    cancelFrame(handle: number): void;
+    now(): number;
+    warn?(message: string): void;
+}
+export interface SpringRunner {
+    /** Retarget without losing velocity — an interrupted spring stays continuous. */
+    to(target: number, velocity?: number): void;
+    /** Adopt a position and velocity directly, e.g. from a drag in progress. */
+    set(value: number, velocity?: number): void;
+    current(): SpringState;
+    stop(): void;
+}
+/**
+ * Drive a spring with a frame loop, calling `onChange` with each new value.
+ *
+ * The loop runs only while the spring is moving and stops itself on settle — an always-running
+ * rAF is exactly what the rest of this library avoids.
+ *
+ * @param config - Spring constants.
+ * @param onChange - Receives each integrated value, plus `true` on the final settled frame.
+ * @param deps - Frame source and clock; injected so tests can step time by hand.
+ * @returns A runner exposing retarget, adopt, read, and stop.
+ * @complexity O(1) per frame; O(1) space.
+ * @overallScore 100
+ */
+export declare function createSpringRunner(config: SpringConfig, onChange: (value: number, settled: boolean) => void, deps: SpringDeps): SpringRunner;
+/**
+ * Frame source defaults, kept at the construction boundary so no logic below reads a global.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function defaultSpringDeps(): SpringDeps;

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

@@ -0,0 +1,19 @@
+/**
+ * Index the animated children of one stagger group.
+ *
+ * Only the index is written; the offset arithmetic stays in the CSS `calc()` so the browser
+ * applies it, rather than JS recomputing a delay per element.
+ *
+ * @param group - Element carrying `data-kui-stagger`.
+ * @complexity O(n) time in the number of children; O(1) extra space.
+ * @overallScore 100
+ */
+export declare function indexStaggerGroup(group: Element): void;
+/**
+ * Index every stagger group in a subtree, including the root itself.
+ *
+ * @param root - Subtree to search.
+ * @complexity O(n) time in the number of elements in the subtree; O(g) space in group count.
+ * @overallScore 100
+ */
+export declare function applyStagger(root: ParentNode): void;

package/dist/types/core/style-plan.d.ts

@@ -0,0 +1,56 @@
+import type { Capabilities } from './capabilities.js';
+import type { CompiledPlan } from './compile.js';
+import type { ElementConfig } from './element-config.js';
+import type { AttributeLedger, StyleLedger } from './owned-styles.js';
+import type { Activation } from './types.js';
+/**
+ * How the animation is started.
+ *
+ * - `native-timeline` — a scroll/view timeline drives progress; nothing to start.
+ * - `immediate` — runs as soon as it is applied.
+ * - `deferred` — held at its from-state until an activation fires.
+ */
+export type Gate = 'native-timeline' | 'immediate' | 'deferred';
+export interface StylePlan {
+    /** Custom properties and animation longhands to write, in application order. */
+    properties: Record<string, string>;
+    /** Attributes to stamp. */
+    attributes: Record<string, string>;
+    gate: Gate;
+    /** Activation to bind; `null` when the gate does not need one. */
+    activation: Activation | null;
+}
+export interface StylePlanInput {
+    plan: CompiledPlan;
+    config: ElementConfig;
+    capabilities: Capabilities;
+    /** Whether the reduced-motion preference should be honoured. */
+    respectReducedMotion: boolean;
+}
+/**
+ * Decide every style write for one element — a pure function returning a description of the
+ * writes rather than performing them.
+ *
+ * This is the decision half of the decision/effect split: it can be asserted with plain objects
+ * and no DOM, which is what keeps `applyStylePlan` trivial enough to need no branching tests.
+ *
+ * @param input - Compiled effects, element configuration, and the environment's capabilities.
+ * @returns The properties, attributes, gate, and activation to apply.
+ * @complexity O(n) time in the number of compiled declarations; O(n) space for the result.
+ * @overallScore 100
+ */
+export declare function planStyles(input: StylePlanInput): StylePlan;
+/**
+ * Write a style plan to an element. The effect half of the split — deliberately branch-free.
+ *
+ * @param el - Target element.
+ * @param plan - Description produced by `planStyles`.
+ * @complexity O(n) time in the number of properties and attributes; O(1) extra space.
+ * @overallScore 100
+ */
+export declare function applyStylePlan(request: {
+    el: Element;
+    plan: StylePlan;
+    ledger: StyleLedger;
+    attributes: AttributeLedger;
+}): void;

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

@@ -0,0 +1,239 @@
+/**
+ * Core type model.
+ *
+ * The four questions that the earlier `Tier` enum wrongly collapsed into one axis are kept
+ * orthogonal here:
+ *   - `renderer`           — who produces the frame
+ *   - `Activation`         — what starts it
+ *   - `Timeline`           — what drives progress
+ *   - `prepare`            — whether DOM surgery is required first
+ * A `css-keyframes` effect can still need observer activation; a `prepare`d effect (split-text)
+ * can render through CSS afterwards. See docs/design.md §6.
+ */
+/**
+ * A CSS property group an effect writes to. Two effects may only be composed in one
+ * `data-kui` list when their channel sets are disjoint — see `core/channels.ts`.
+ *
+ * `translate` / `rotate` / `scale` are separate channels because they are independent CSS
+ * properties in modern browsers. Under the old `transform` shorthand they would all have
+ * collided and this composition model would be impossible.
+ */
+export declare const CHANNEL: {
+    readonly opacity: "opacity";
+    readonly translate: "translate";
+    readonly scale: "scale";
+    readonly rotate: "rotate";
+    readonly filter: "filter";
+    readonly clip: "clip";
+    readonly background: "background";
+    readonly color: "color";
+    readonly stroke: "stroke";
+    readonly text: "text";
+};
+/**
+ * A CSS property group an effect writes to. Two effects may only be composed in one `data-kui`
+ * list when their channel sets are disjoint — see `core/channels.ts`.
+ *
+ * `translate` / `rotate` / `scale` are separate channels because they are independent CSS
+ * properties in modern browsers. Under the old `transform` shorthand they would all collide and
+ * this composition model would be impossible.
+ *
+ * The open `string` arm is deliberate: third-party primitives register their own channels, so
+ * the union documents the built-ins without closing the set.
+ */
+export type Channel = (typeof CHANNEL)[keyof typeof CHANNEL] | (string & {});
+/** What starts the animation. Distinct from — and never a substitute for — a Timeline. */
+export type Activation = 'load' | 'enter' | 'hover' | 'focus' | 'click' | 'manual';
+/**
+ * What drives progress.
+ *
+ * `time` runs a clock. `view` / `scroll` map progress continuously to scroll position and so
+ * *reverse when the user scrolls back*, which a time-based reveal does not. These are different
+ * animation models, not fallbacks for each other. See docs/design.md §5.
+ */
+export type Timeline = 'time' | 'view' | 'scroll' | 'pointer';
+export type Renderer = 'css-keyframes' | 'waapi' | 'javascript';
+/** Governs the performance budget a primitive is held to in tests. */
+export type PerfClass = 'compositor' | 'paint' | 'layout' | 'continuous' | 'dom-transform';
+/**
+ * Per-effect reduced-motion policy. A blanket `1ms` override is wrong: it does not meaningfully
+ * reduce parallax, pinning, flashing or continuous ambient motion.
+ */
+export type ReducedMotionPolicy = 'shorten' | 'crossfade' | 'disable';
+export type ParamType = 'length' | 'time' | 'number' | 'percentage' | 'angle' | 'color' | 'easing' | 'keyword'
+/**
+ * Free text — a CSS selector, a URL pattern. Consumed only by JS primitives and **never
+ * written to a stylesheet**, which is what makes accepting arbitrary characters safe here.
+ * `resolveParams` drops these on the CSS path; `readParams` keeps them for `prepare`.
+ */
+ | 'text';
+export interface ParamSpec {
+    type: ParamType;
+    /** Used as the `var()` fallback in CSS. Never written to element.style — see design.md §7. */
+    default: string;
+    /** Custom property this parameter feeds, e.g. `--kui-reveal-distance`. */
+    cssProperty: string;
+    /** For `keyword` params. */
+    values?: readonly string[];
+    /** Require a numeric parameter to convert to a finite JavaScript number. */
+    finite?: boolean;
+    /** Inclusive lower bound for numeric parameters. */
+    minimum?: number;
+    /** Inclusive upper bound for numeric parameters. */
+    maximum?: number;
+    /** Require a numeric parameter to have no fractional part. */
+    integer?: boolean;
+}
+export type ParameterSchema = Record<string, ParamSpec>;
+import type { PrepareContext } from './effect-context.js';
+import type { AttributeLedger, StyleLedger } from './owned-styles.js';
+export type { PrepareContext };
+export type Cleanup = () => void;
+/**
+ * Renderer-neutral lifecycle handle.
+ *
+ * CSS-rendered and JS-rendered effects expose the same five operations, so the animator can gate,
+ * cancel, and await either one without knowing which it holds. That uniformity is the whole point:
+ * every contract the library advertises — activation, reduced motion, `play().finished`,
+ * cancellation — is enforced here rather than re-implemented per renderer.
+ */
+export interface EffectInstance {
+    /** Start. Called by the animator once its gate opens, never by `prepare`. */
+    activate(): void;
+    /** Stop where it is, leaving the element mid-effect. */
+    cancel(): void;
+    /** Jump to the end state immediately. */
+    finish(): void;
+    /** Resolves when the effect completes. Resolves — never rejects — on cancel. */
+    readonly finished: Promise<void>;
+    /** Release every listener, observer, subscription, and inserted node. */
+    destroy(): void;
+}
+/**
+ * An instance that does nothing, for effects with no work to do in the current environment.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function inertInstance(destroy?: Cleanup): EffectInstance;
+/**
+ * Author timing for one effect segment — the positional `2s 1s linear` of `data-kui`.
+ *
+ * Separate from `EffectParams` because it is not a parameter: it is not declared in any
+ * `ParameterSchema`, it means the same thing for every effect, and the CSS renderer already reads
+ * it straight off the `EffectSpec` in `compile.pushTrack`. A JS-rendered primitive gets the same
+ * three values here rather than having to declare look-alike parameters of its own.
+ *
+ * Every field is optional and `undefined` means *the author named none* — a primitive must be able
+ * to tell that apart from an explicit `0ms` so its own default still applies.
+ */
+export interface EffectTiming {
+    /** Total time the whole effect should take, in milliseconds. */
+    durationMs?: number;
+    /** Time before the effect starts, in milliseconds. */
+    delayMs?: number;
+    /** Validated CSS easing keyword or function. */
+    easing?: string;
+}
+/**
+ * Validated parameter reader handed to JS-rendered primitives.
+ *
+ * A reader rather than a plain record for three reasons: every declared parameter is guaranteed
+ * present (so no `| undefined` at every call site), unit conversion lives in one place instead of
+ * being re-derived per primitive, and it is structurally distinct from `ResolvedParams`.
+ *
+ * That last point is not cosmetic. `prepare` previously declared `ResolvedParams` while the
+ * animator passed raw author strings; both were `Record<string, string>`, so TypeScript accepted
+ * a call that bypassed all validation. Two different shapes make that class of mistake impossible.
+ */
+export interface EffectParams {
+    /** Validated string value. */
+    text(name: string, fallback?: string): string;
+    /** Milliseconds, from a `time` parameter. */
+    ms(name: string, fallback?: number): number;
+    /** Bare number, or a percentage as a 0–1 ratio. */
+    num(name: string, fallback?: number): number;
+    /** Whether a keyword parameter equals `value` (default `'true'`). */
+    is(name: string, value?: string): boolean;
+    /**
+     * Author timing for this effect segment. Time-driven primitives should honour it; the many that
+     * are driven by a pointer or the scroll position instead can ignore it entirely.
+     */
+    readonly timing: EffectTiming;
+}
+/**
+ * A primitive is an implementation. Presets are names that point at a primitive with different
+ * default parameters — 48 of the entrance/exit names come from one primitive.
+ */
+export interface Primitive {
+    id: string;
+    renderer: Renderer;
+    channels: Channel[];
+    parameters: ParameterSchema;
+    supportedTimelines: Timeline[];
+    supportedActivations: Activation[];
+    /**
+     * Activation used when the author specifies none.
+     *
+     * `enter` is right for an entrance reveal and wrong for behaviour: a drag handler, a FLIP
+     * container, or a hover morph that only wires itself up once scrolled into view is broken, not
+     * lazy. Defaults to `enter` when unset.
+     */
+    defaultActivation?: Activation;
+    perfClass: PerfClass;
+    reducedMotion: ReducedMotionPolicy;
+    /**
+     * JS-side setup. Returns a lifecycle handle, **not** a teardown function.
+     *
+     * `prepare` must only wire things up — it must not start anything. The animator decides when
+     * (or whether) to call `activate()`, which is what makes `on:enter`, `on:click`, `manual`, and
+     * `reducedMotion: 'disable'` apply to JS-rendered effects at all. Returning a bare `Cleanup`
+     * previously meant every JS effect started at install time and no declared activation or
+     * reduced-motion policy was ever enforced.
+     *
+     * `params` are validated and defaulted — never raw author input.
+     */
+    prepare?(el: Element, params: EffectParams, ctx: PrepareContext): EffectInstance;
+}
+export interface Preset {
+    name: string;
+    primitive: string;
+    /** Parameter overrides that differentiate this name from its primitive's defaults. */
+    params?: Record<string, string>;
+    /** CSS `@keyframes` name this preset animates, when renderer is `css-keyframes`. */
+    keyframes?: string;
+}
+export type ResolvedParams = Record<string, string>;
+/** One effect segment parsed out of a `data-kui` value. */
+export interface EffectSpec {
+    name: string;
+    duration?: string;
+    delay?: string;
+    easing?: string;
+    params: Record<string, string>;
+}
+/** The full parse of one element's `data-kui` attribute. */
+export interface ParsedValue {
+    specs: EffectSpec[];
+    /** Hoisted from reserved `on:` / `timeline:` / `threshold:` keys. Element-scoped. */
+    activation?: Activation;
+    timeline?: string;
+    threshold?: string;
+    warnings: string[];
+}
+/** Runtime truth. Attributes are for CSS and debugging; they make a poor state machine. */
+export interface InstanceState {
+    /** Whole-configuration identity, not just `data-kui` — see `fingerprintOf`. */
+    fingerprint: string;
+    specs: EffectSpec[];
+    activation: Activation;
+    timeline: Timeline;
+    /** One handle per renderer in play; the animator gates them uniformly. */
+    instances: EffectInstance[];
+    /** Inline properties this element's effects wrote, and what they replaced. */
+    ledger: StyleLedger;
+    attributes: AttributeLedger;
+    /** Aborted on release, detaching bindings and primitive listeners. */
+    controller: AbortController;
+    status: 'pending' | 'ready' | 'running' | 'finished' | 'failed';
+}

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

@@ -0,0 +1,18 @@
+import type { Preset, Primitive } from '../../core/types.js';
+import type { Registry } from '../../core/registry.js';
+/**
+ * Continuous ambient motion never shortens to 1ms under reduced motion — a 1ms aurora is
+ * meaningless, so every primitive here declares `reducedMotion: 'disable'` and starts on
+ * `load` rather than waiting on a scroll-triggered `enter`.
+ */
+export declare const AMBIENT_PRIMITIVES: Primitive[];
+export declare const AMBIENT_PRESETS: Preset[];
+/**
+ * Register catalog section J (ambient backgrounds) into a registry.
+ *
+ * @param registry - Registry to populate.
+ * @returns The same registry, for chaining.
+ * @complexity O(n) time in registered primitives and presets; O(1) extra space.
+ * @overallScore 100
+ */
+export declare function registerAmbient(registry: Registry): Registry;

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

@@ -0,0 +1,19 @@
+import type { Preset, Primitive } from '../../core/types.js';
+import type { Registry } from '../../core/registry.js';
+export declare const PRIMITIVES: Primitive[];
+export declare const PRESETS: Preset[];
+/**
+ * Combinations with a purpose-built single keyframe. Checked before channel analysis, so
+ * `fade-up, blur-in` resolves here instead of being rejected for both writing opacity.
+ */
+export declare const COMBOS: Array<[string[], string]>;
+/**
+ * Register the v1 catalog: entrance/exit, scroll reveal, and parallax primitives, presets, and
+ * combos.
+ *
+ * @param registry - Registry to populate.
+ * @returns The same registry, for chaining.
+ * @complexity O(n) time in the number of primitives, presets, and combos.
+ * @overallScore 100
+ */
+export declare function registerCore(registry: Registry): Registry;

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

@@ -0,0 +1,21 @@
+import type { Preset, Primitive } from '../../core/types.js';
+import type { Registry } from '../../core/registry.js';
+/**
+ * Feedback & status effects (catalog section K). Loading indicators default to `load` and
+ * `reducedMotion: 'disable'` — an infinite loop shortened to 1ms strobes rather than stopping,
+ * which is worse than not reducing it at all. One-shot reactions (toast, shake, pop, burst) keep
+ * the default `shorten` policy and default to whichever activation their real usage implies:
+ * `click` for effects that react to the element the user just clicked, `manual` for effects an
+ * application triggers from its own state (a toast appearing, a field failing validation).
+ */
+export declare const FEEDBACK_PRIMITIVES: Primitive[];
+export declare const FEEDBACK_PRESETS: Preset[];
+/**
+ * Register catalog section K (feedback & status) into a registry.
+ *
+ * @param registry - Registry to populate.
+ * @returns The same registry, for chaining.
+ * @complexity O(n) time in registered primitives and presets; O(1) extra space.
+ * @overallScore 100
+ */
+export declare function registerFeedback(registry: Registry): Registry;

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

@@ -0,0 +1,21 @@
+import type { Registry } from '../../core/registry.js';
+export { AMBIENT_PRESETS, AMBIENT_PRIMITIVES } from './ambient.js';
+export { FEEDBACK_PRESETS, FEEDBACK_PRIMITIVES } from './feedback.js';
+export { INTERACTION_PRESETS, INTERACTION_PRIMITIVES } from './interaction.js';
+export { MEDIA_PRESETS, MEDIA_PRIMITIVES } from './media.js';
+export { NUMBERS_PRESETS, NUMBERS_PRIMITIVES } from './numbers.js';
+export { TEXT_PRESETS, TEXT_PRIMITIVES } from './text.js';
+/**
+ * Register the CSS-oriented catalog sections.
+ *
+ * Delegates to each section's own `register*` function — the same shape every other top-level
+ * category (`registerGestures`, `registerThreeD`, ...) uses — instead of re-registering their
+ * constants inline, so this aggregator and each section's own registration path can never drift
+ * apart from each other.
+ *
+ * @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 registerCatalog(registry: Registry): Registry;