kuinetic 0.1.0

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

@@ -0,0 +1,14 @@
+export { createActivationBinder } from './activation.js';
+export type { ActivationBinder, ActivationBinderOptions } from './activation.js';
+export { Animator, createAnimator, ATTR } from './animator.js';
+export type { AnimatorOptions } from './animator.js';
+export { detect } from './capabilities.js';
+export type { Capabilities } from './capabilities.js';
+export { play, resolveTargets, toAttributeValue } from './play.js';
+export type { PlaybackHandle, PlayOptions, Target } from './play.js';
+export { Registry } from './registry.js';
+export type { ResolvedEffect } from './registry.js';
+export { collectingReporter, consoleReporter, silentReporter } from './reporter.js';
+export type { CollectingReporter, Reporter } from './reporter.js';
+export { CHANNEL, inertInstance } from './types.js';
+export type { Activation, Channel, Cleanup, EffectInstance, EffectParams, ParamSpec, ParameterSchema, PerfClass, PrepareContext, Preset, Primitive, ReducedMotionPolicy, Timeline, } from './types.js';

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

@@ -0,0 +1,98 @@
+import type { StyleLedger } from './owned-styles.js';
+import type { Cleanup, EffectInstance } from './types.js';
+/**
+ * Wrap a CSS-rendered effect.
+ *
+ * Gating is `animation-play-state` rather than a class toggle: `animation-fill-mode: both`
+ * already holds the from-state, so there is no flash between compilation and activation.
+ *
+ * Repeat activation of the same instance and a fresh instance's first activation both can meet a
+ * browser-level animation already sitting `finished`, but they need opposite responses. A second
+ * `activate()` on the same instance is a click-gated toggle (a card flip): reversing playback is
+ * the correct repeat — the property write only matters on the paused-to-running edge, so writing
+ * the same value again is a no-op the browser silently ignores, which is what made two-state
+ * effects look permanently stuck. A fresh instance's *first* activation meeting a `finished`
+ * animation instead means the browser never actually tore down the previous one (see
+ * `restartCssAnimation`) — replay wants that to run forward from the start, not reverse, so it
+ * gets the restart path instead of `.reverse()`.
+ *
+ * @param el - Element carrying the compiled animation.
+ * @param ledger - Ledger owning the play-state write.
+ * @param animationNames - Exact keyframe names emitted by the compiled plan.
+ * @returns A lifecycle handle over the element's owned CSS animations.
+ * @complexity O(a) per call in the number of running animations; O(1) space.
+ * @overallScore 100
+ */
+export declare function createCssInstance(el: Element, ledger: StyleLedger, animationNames: readonly string[]): EffectInstance;
+/**
+ * What a *finite* JS primitive's setup returns instead of a bare teardown.
+ *
+ * A continuous primitive — a drag handler, a pin, an ambient loop — has no end, so it returns a
+ * plain `Cleanup` and keeps the immediately-resolved `finished` every caller composing
+ * `Promise.all` over an element's instances already relies on. Only an effect that genuinely
+ * completes needs to say so, and only that effect pays for it.
+ */
+export interface TimedSetup {
+    cleanup: Cleanup;
+    /**
+     * Resolves when the effect's own work is done. A setup that loops forever should hand over a
+     * promise that never resolves — the same contract an `animation-iteration-count: infinite` CSS
+     * effect already has, since its `Animation.finished` never resolves either.
+     */
+    finished: Promise<void>;
+    /** Jump to the end state, for `EffectInstance.finish()`. */
+    finish?: () => void;
+}
+/** A deferred setup's return: a teardown, or a teardown plus the effect's own completion. */
+export type SetupResult = Cleanup | TimedSetup;
+/**
+ * Turn setup-that-also-starts into a properly gated instance.
+ *
+ * Most JS primitives are naturally written as "wire it up and go" — subscribe to the scheduler,
+ * attach listeners, write the first style. Deferring that whole body until `activate()` is what
+ * makes them obey `on:enter`, `on:click`, `manual`, and `reducedMotion: 'disable'` without each
+ * primitive having to implement gating itself.
+ *
+ * @param setup - Runs on activation; returns its own teardown, optionally with its completion.
+ * @returns An instance that does nothing until activated.
+ * @complexity O(1) beyond the setup itself.
+ * @overallScore 100
+ */
+export declare function deferredInstance(setup: () => SetupResult): EffectInstance;
+/**
+ * Wrap a `(el, params, ctx) => SetupResult`-shaped setup function as a deferred
+ * `Primitive['prepare']`.
+ *
+ * Every JS primitive's `prepare` is `deferredInstance(() => setup(...args))` — this names that
+ * composition once instead of re-deriving it at each of the library's fourteen call sites.
+ *
+ * @complexity O(1) time and space beyond the wrapped call.
+ * @overallScore 100
+ */
+export declare function deferPrepare<Args extends unknown[]>(setup: (...args: Args) => SetupResult): (...args: Args) => EffectInstance;
+export interface JsInstanceHooks {
+    /** Start the effect. Never called before the animator's gate opens. */
+    activate(): void;
+    cancel?(): void;
+    finish?(): void;
+    /** Release listeners, observers, subscriptions, and inserted nodes. */
+    destroy: Cleanup;
+    /**
+     * Resolve when the effect completes. Continuous effects may simply never resolve.
+     *
+     * Read on every access rather than captured once, so a setup that only learns its own completion
+     * at activation time can swap in a real promise — the animator and `play()` both read
+     * `finished` after `activate()`, never before.
+     */
+    finished?(): Promise<void>;
+}
+/**
+ * Build a JS-rendered instance from a primitive's hooks, filling in the optional operations.
+ *
+ * Keeps primitives free of lifecycle boilerplate while still guaranteeing the animator every
+ * operation it needs.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function createJsInstance(hooks: JsInstanceHooks): EffectInstance;

package/dist/types/core/js-effect-preparer.d.ts

@@ -0,0 +1,46 @@
+import type { Capabilities } from './capabilities.js';
+import type { CompiledPlan } from './compile.js';
+import type { StyleLedger } from './owned-styles.js';
+import type { Reporter } from './reporter.js';
+import type { ScrollRoot, ScrollScheduler } from './scroll-scheduler.js';
+import type { EffectInstance } from './types.js';
+/** Everything `JsEffectPreparer.prepare` needs, grouped so the call site reads as one request. */
+export interface PrepareJsEffectsRequest {
+    el: Element;
+    plan: CompiledPlan;
+    signal: AbortSignal;
+    ledger: StyleLedger;
+}
+/**
+ * Wires up an element's JS-rendered effects and hands each one the context it needs to run.
+ *
+ * Extracted from `Animator` as an injected collaborator — same shape as `binder` or `scheduler` —
+ * because this pair only ever reads already-injected environment collaborators
+ * (`scheduler`/`rootResolver`/`capabilities`/`reporter`/`respectReducedMotion`), never the
+ * animator's own lifecycle state.
+ */
+export interface JsEffectPreparer {
+    /**
+     * Run each JS-rendered effect's setup, isolating failures so one broken effect cannot abort the
+     * rest of the element.
+     *
+     * @returns Instances for every effect that initialised successfully.
+     * @complexity O(e) time in JS-rendered effects; O(e) space.
+     * @overallScore 100
+     */
+    prepare(request: PrepareJsEffectsRequest): EffectInstance[];
+}
+export interface JsEffectPreparerOptions {
+    scheduler: ScrollScheduler;
+    rootResolver: (el: Element) => ScrollRoot;
+    capabilities: Capabilities;
+    reporter: Reporter;
+    respectReducedMotion: boolean;
+}
+/**
+ * Build a `JsEffectPreparer` closed over one animator's collaborators.
+ *
+ * @complexity O(1) time and space beyond the closure it returns.
+ * @overallScore 100
+ */
+export declare function createJsEffectPreparer(options: JsEffectPreparerOptions): JsEffectPreparer;

package/dist/types/core/js-params.d.ts

@@ -0,0 +1,124 @@
+import type { EffectParams, EffectSpec, EffectTiming, ParameterSchema } from './types.js';
+/**
+ * Parameter access for JS-rendered primitives.
+ *
+ * `core/params.resolveParams` exists for the CSS path: it returns values keyed by *custom
+ * property* and deliberately omits defaults, because defaults belong in the stylesheet's `var()`
+ * fallback. A JS primitive needs the opposite shape — keyed by parameter name, defaults filled,
+ * and converted to numbers it can compute with. This module is that second reader. It reuses the
+ * same `validate` so untrusted author strings are screened once, by one implementation.
+ *
+ * See docs/v2-core-requests.md: `Animator.prepareJsEffects` currently hands `prepare` the raw,
+ * unvalidated `spec.params`, so every JS primitive must run this itself.
+ */
+/** Lengths resolve against the environment, so the environment is passed in rather than read. */
+export interface LengthBasis {
+    viewportWidth: number;
+    viewportHeight: number;
+    /** Basis for `%` values — what "100%" means for this particular parameter. */
+    percentBasis: number;
+    /** Basis for `em`; `rem` uses `rootFontSize`. */
+    fontSize: number;
+    rootFontSize: number;
+}
+/** A basis usable when a parameter is known to carry only absolute units. */
+export declare const ABSOLUTE_BASIS: LengthBasis;
+/**
+ * Validate authored parameters against a schema and fill in every declared default.
+ *
+ * Unlike the CSS path this returns *every* declared parameter, because a JS primitive branches on
+ * values it must always have. Rejected values fall back to the declared default and warn, so one
+ * bad attribute can never leave a primitive holding an unvalidated string.
+ *
+ * @param authored - Raw, untrusted values from the attribute.
+ * @param schema - The primitive's declared parameters.
+ * @param warn - Diagnostic sink, called once per rejected or unknown parameter.
+ * @returns Every declared parameter name mapped to a validated string value.
+ * @complexity O(p * n) time in parameter count and value length; O(p) space.
+ * @overallScore 100
+ */
+export declare function readParams(authored: Record<string, string>, schema: ParameterSchema, warn: (message: string) => void): Record<string, string>;
+/**
+ * Convert a validated CSS time to milliseconds.
+ *
+ * @param value - A value already accepted as `type: 'time'`, e.g. `400ms` or `1.5s`.
+ * @param fallback - Returned when the value is not a plain time (a `calc()`, for instance).
+ * @returns Milliseconds.
+ * @complexity O(n) time in value length; O(1) space.
+ * @overallScore 100
+ */
+export declare function toMilliseconds(value: string, fallback?: number): number;
+/**
+ * Convert a validated CSS length to pixels.
+ *
+ * Viewport- and percentage-relative units need context, which is why the basis is a parameter
+ * rather than something this module reads off `window`: the same helper then resolves a length
+ * against a nested scroll container as easily as against the viewport, and tests need no layout.
+ *
+ * `calc()` is intentionally not evaluated — a second CSS expression engine is not worth owning.
+ * Such values return the fallback, which is visible and debuggable rather than silently wrong.
+ *
+ * @param value - A value already accepted as `type: 'length'`.
+ * @param basis - Viewport, font, and percentage context.
+ * @param fallback - Returned for `calc()` and unrecognised units.
+ * @returns Pixels.
+ * @complexity O(n) time in value length; O(1) space.
+ * @overallScore 100
+ */
+export declare function toPixels(value: string, basis: LengthBasis, fallback?: number): number;
+/**
+ * Convert a validated numeric parameter.
+ *
+ * @param value - A value already accepted as `type: 'number'` or `type: 'percentage'`.
+ * @param fallback - Returned when the value is not a bare number or percentage.
+ * @returns The number; percentages are returned as a 0–1 ratio.
+ * @complexity O(n) time in value length; O(1) space.
+ * @overallScore 100
+ */
+export declare function toNumber(value: string, fallback?: number): number;
+/** Whether a keyword parameter is set to its enabling value. */
+export declare function isEnabled(value: string, enabling?: string): boolean;
+/**
+ * Read one effect segment's positional timing into the shape JS primitives consume.
+ *
+ * The CSS renderer hands these straight to `animation-duration`/`-delay`/`-timing-function`, where
+ * the browser does the screening. Nothing screened them on the JS path, so they are converted to
+ * numbers (and the easing validated) here instead of anywhere a primitive might forget.
+ *
+ * @param spec - The parsed effect segment.
+ * @param warn - Diagnostic sink, called once per rejected value.
+ * @complexity O(n) time in value length; O(1) space.
+ * @overallScore 100
+ */
+export declare function readEffectTiming(spec: Pick<EffectSpec, 'duration' | 'delay' | 'easing'>, warn: (message: string) => void): EffectTiming;
+/**
+ * How long an unstepped effect should run, preferring the segment's positional time over the
+ * same-named parameter.
+ *
+ * `count 3s` and `count duration:3s` are two spellings of one intent, and the positional one is
+ * what `play()` emits, so it cannot be the spelling that gets dropped. `stepMsFor` is the
+ * equivalent for effects whose authored duration divides across a tick count instead.
+ *
+ * @param fallback - The primitive's own default, used when the author wrote neither spelling.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function effectDurationMs(params: EffectParams, fallback: number): number;
+/**
+ * Wrap a validated record in the reader primitives consume.
+ *
+ * @param values - Output of `readParams`; every declared parameter is present.
+ * @param timing - Author timing for the segment; empty when none was written.
+ * @returns A reader with per-type accessors.
+ * @complexity O(1) per accessor call; O(1) space beyond the record.
+ * @overallScore 100
+ */
+export declare function createParams(values: Record<string, string>, timing?: EffectTiming): EffectParams;
+/**
+ * Validate authored parameters and wrap them in a reader — the single entry point the animator
+ * uses for JS-rendered effects.
+ *
+ * @complexity O(p * n) time in parameter count and value length; O(p) space.
+ * @overallScore 100
+ */
+export declare function readEffectParams(authored: Record<string, string>, schema: ParameterSchema, warn: (message: string) => void, timing?: EffectTiming): EffectParams;

package/dist/types/core/owned-styles.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Owned-write ledger.
+ *
+ * The runtime writes inline custom properties, animation longhands, and timeline properties, but
+ * previously tore down by removing three attributes. Recompiling `fade-up distance:80px` into
+ * `zoom-in` therefore left `--kui-distance` behind, and destroying an animator left every
+ * animation installed.
+ *
+ * A ledger records what this library wrote *and what was there before*, so teardown restores the
+ * consumer's own inline styles rather than deleting them. That distinction matters: several JS
+ * primitives were previously clearing author-set `translate` and `scroll-snap-align` values they
+ * did not own.
+ */
+export interface StyleLedger {
+    /** Write a property, remembering the value it replaced. */
+    set(property: string, value: string): void;
+    /** Record a property this ledger will restore, without writing anything yet. */
+    claim(property: string): void;
+    /** Restore every recorded property to the value it had before this ledger touched it. */
+    restore(): void;
+    /** Properties currently owned. Diagnostics and leak assertions. */
+    owned(): string[];
+}
+/**
+ * Create a ledger over one element's inline style.
+ *
+ * @param el - Element whose inline style is managed.
+ * @returns A ledger that can restore the element to its pre-effect inline state.
+ * @complexity O(1) per write; O(n) space and O(n) time to restore, in properties written.
+ * @overallScore 100
+ */
+export declare function createStyleLedger(el: Element): StyleLedger;
+export interface AttributeLedger {
+    set(name: string, value: string): void;
+    restore(): void;
+}
+/**
+ * The same discipline for attributes, so a library-stamped attribute never clobbers an authored
+ * one permanently.
+ *
+ * @complexity O(1) per write; O(n) to restore.
+ * @overallScore 100
+ */
+export declare function createAttributeLedger(el: Element): AttributeLedger;

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

@@ -0,0 +1,65 @@
+import type { ParamSpec, ParameterSchema, ResolvedParams } from './types.js';
+export interface ValidationResult {
+    value: string;
+    ok: boolean;
+    reason?: string;
+}
+/**
+ * Validate one authored parameter value against its declared type.
+ *
+ * @param raw - Author-supplied value, untrusted.
+ * @param spec - The parameter's declared type, default, and target custom property.
+ * @returns The accepted value, or the declared default with a reason when rejected. Never throws
+ *   and never returns an unvalidated string.
+ * @complexity O(n) time in value length; O(1) space.
+ * @overallScore 100
+ */
+export declare function validate(raw: string, spec: ParamSpec): ValidationResult;
+/**
+ * Whether an authored value stays on the page's own origin wherever a `src`-shaped `text`
+ * parameter is actually turned into a network request.
+ *
+ * `type: 'text'` is deliberately shape-free — see the module doc above — because it also carries
+ * CSS selectors and other non-URL strings that have no notion of "origin" at all. So this is not
+ * part of `validate()`: a `text` value that is a URL pattern (media-scrub's frame `src`) is safe
+ * to accept lexically, but a *consumer of that value* must call this before ever assigning it to
+ * something that fetches, such as `<img>.src`.
+ *
+ * The threat: `data-kui` content is not always authored by the site owner — a CMS field, a
+ * comment, anything not trusted the way hand-written markup is — so an unconstrained `src`
+ * pattern turns the visitor's own browser into a same-origin-cookie-free but still
+ * attacker-directed request tool: exfiltration via path/query, third-party tracking pixels, or
+ * probing hosts on the victim's internal network that are unreachable from outside it. A
+ * Content-Security-Policy would mitigate this, but the library should not depend on the consumer
+ * having one.
+ *
+ * Only relative and root-relative paths pass. That is narrower than "any same-origin URL": a
+ * fully-qualified `https://this-very-site/…` is rejected too, on purpose, because nothing this
+ * library ships needs one — a root-relative path reaches the same resource — and accepting it
+ * would mean re-deriving "is this really the page's own origin" from `location` inside what is
+ * otherwise pure string validation, with all the parsing edge cases (`this-site.com.evil.com`,
+ * userinfo tricks, IDN lookalikes) that comparison invites. Rejecting every scheme uniformly,
+ * regardless of which host follows it, has no such edge cases.
+ *
+ * @param value - Author-supplied value already accepted by {@link validate} as `type: 'text'`.
+ * @returns Whether every request this value can produce is confined to the page's own origin.
+ * @complexity O(n) time in value length; O(1) space.
+ * @overallScore 100
+ */
+export declare function isSameOriginPath(value: string): boolean;
+/**
+ * Resolve authored parameters against a schema.
+ *
+ * Only values the author explicitly supplied are returned. Defaults are deliberately excluded:
+ * they live in the CSS `var()` fallback. Writing them to `element.style` would give inline custom
+ * properties precedence over consumer stylesheets and break the promise that a site's own CSS
+ * wins without `!important`.
+ *
+ * @param authored - Raw parameter values from the attribute or options object.
+ * @param schema - The primitive's declared parameters.
+ * @param warn - Diagnostic sink; called once per rejected or unknown parameter.
+ * @returns Custom property names mapped to validated values.
+ * @complexity O(p * n) time in parameter count and value length; O(p) space.
+ * @overallScore 100
+ */
+export declare function resolveParams(authored: Record<string, string>, schema: ParameterSchema, warn: (message: string) => void): ResolvedParams;

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

@@ -0,0 +1,22 @@
+import type { ParsedValue } from './types.js';
+/**
+ * Split on a delimiter, ignoring delimiters nested inside parentheses or quotes.
+ *
+ * @param input - Raw attribute text.
+ * @param delimiter - `','` for effect segments, `' '` for tokens within a segment.
+ * @param warnings - Sink for a diagnostic when a quote or `(` is never closed. Optional so the
+ *   two-argument call every existing caller and test uses keeps working unchanged.
+ * @returns Trimmed, non-empty parts.
+ * @complexity O(n) time in input length; O(n) space for the parts.
+ * @overallScore 100
+ */
+export declare function splitTopLevel(input: string, delimiter: ',' | ' ', warnings?: string[]): string[];
+/**
+ * Parse a `data-kui` attribute value.
+ *
+ * @param input - Raw attribute text; empty or whitespace yields an empty spec list.
+ * @returns Effect specs plus any hoisted element-scoped settings and warnings.
+ * @complexity O(n) time in input length; O(e) space in the number of effect segments.
+ * @overallScore 100
+ */
+export declare function parse(input: string): ParsedValue;

package/dist/types/core/path-morph.d.ts

@@ -0,0 +1,83 @@
+/**
+ * SVG path interpolation.
+ *
+ * Two `d` strings cannot be interpolated directly: they differ in command type and count, and
+ * `1px` of `C` is not `1px` of `L`. The fix is normalisation — convert everything to absolute
+ * cubic segments, then split the longer path's segments until both have the same count. After
+ * that, morphing is per-number lerp.
+ *
+ * Scope is deliberately bounded. `M L H V C Z` are supported; `A S Q T` are not, and a path using
+ * them reports a reason rather than producing a plausible-looking wrong shape. Owning a complete
+ * SVG path engine is not worth it for two effect names.
+ */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** One cubic segment: start point, two controls, end point. */
+export interface Cubic {
+    from: Point;
+    c1: Point;
+    c2: Point;
+    to: Point;
+}
+export interface ParseResult {
+    segments: Cubic[];
+    /** Present when the path could not be normalised; the caller should warn and not morph. */
+    reason?: string;
+}
+/**
+ * Parse a path's `d` attribute into absolute cubic segments.
+ *
+ * @param d - The `d` attribute value.
+ * @returns Segments, or a `reason` when the path uses unsupported commands.
+ * @complexity O(n) time in the length of `d`; O(s) space in segment count.
+ * @overallScore 100
+ */
+export declare function parsePath(d: string): ParseResult;
+/**
+ * Split a cubic at `t` using de Casteljau, preserving the exact curve.
+ *
+ * Splitting rather than padding is what keeps a normalised path visually identical to the
+ * original — a duplicated zero-length segment would create a visible kink under interpolation.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function splitCubic(segment: Cubic, t: number): [Cubic, Cubic];
+/**
+ * Grow a segment list to `target` segments by repeatedly halving the longest one.
+ *
+ * @param segments - Source segments; not mutated.
+ * @param target - Desired count, which must be at least the source count.
+ * @returns A list of exactly `target` segments describing the same curve.
+ * @complexity O((target - n) * n) time; O(target) space. Both paths are parsed once per morph
+ *   setup, not per frame, so the quadratic term never reaches the frame budget.
+ * @overallScore 100
+ */
+export declare function normaliseCount(segments: Cubic[], target: number): Cubic[];
+/**
+ * Serialise cubic segments back to a `d` string.
+ *
+ * @complexity O(n) time and space in segment count.
+ * @overallScore 100
+ */
+export declare function toPathData(segments: Cubic[]): string;
+export interface Morph {
+    /** Path data at `t` in [0, 1]. */
+    at(t: number): string;
+    segmentCount: number;
+}
+/**
+ * Build an interpolator between two path strings.
+ *
+ * @param fromPath - Starting `d`.
+ * @param toPath - Ending `d`.
+ * @returns A morph, or a `reason` when either path cannot be normalised.
+ * @complexity O(n log n)-ish setup in segment count; O(n) per `at` call.
+ * @overallScore 100
+ */
+export declare function createMorph(fromPath: string, toPath: string): {
+    morph?: Morph;
+    reason?: string;
+};

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

@@ -0,0 +1,48 @@
+import type { Animator } from './animator.js';
+export type Target = string | Element | Iterable<Element>;
+export interface PlayOptions {
+    duration?: string | number;
+    delay?: string | number;
+    ease?: string;
+    stagger?: string | number;
+    /** Any effect parameter, e.g. `{ distance: '40px' }`. */
+    [param: string]: string | number | undefined;
+}
+/**
+ * A handle, not a bare promise. `finished` resolving and the animation being cancellable are
+ * different concerns, and a selection-level `.stop()` cannot express which run it stops.
+ */
+export interface PlaybackHandle {
+    readonly elements: Element[];
+    /** Resolves when every selected element finishes. Resolves (never rejects) on cancel. */
+    readonly finished: Promise<void>;
+    cancel(): void;
+    finish(): void;
+}
+export declare function resolveTargets(target: Target, root: ParentNode): Element[];
+/**
+ * Options object → the same attribute string an author would write. One execution path.
+ *
+ * @complexity O(n) time in the number of options; O(n) space for the parts.
+ * @overallScore 100
+ */
+export declare function toAttributeValue(effect: string, options?: PlayOptions): string;
+export interface PlayRequest {
+    animator: Animator;
+    root: ParentNode;
+    target: Target;
+    effect: string;
+}
+/**
+ * Play an effect on a selection, returning a handle rather than a bare promise.
+ *
+ * Options are compiled into the same attribute string an author would write, so the declarative
+ * and programmatic surfaces share one execution path instead of drifting apart.
+ *
+ * @param request - Animator, root, target selection, and effect name.
+ * @param options - Timing and effect parameters.
+ * @returns A handle exposing `finished`, `cancel`, and `finish`.
+ * @complexity O(n) time in the number of selected elements; O(n) space.
+ * @overallScore 100
+ */
+export declare function play(request: PlayRequest, options?: PlayOptions): PlaybackHandle;

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

@@ -0,0 +1,38 @@
+import type { Preset, Primitive } from './types.js';
+export interface ResolvedEffect {
+    preset: Preset;
+    primitive: Primitive;
+}
+/**
+ * Name → primitive alias table.
+ *
+ * The catalog's ~237 names come from 29 primitives; 48 of them are one primitive with different
+ * parameter defaults. Presets are therefore data rows, not code, and adding a name in a later
+ * release costs a table entry. See docs/catalog.md.
+ */
+export declare class Registry {
+    private primitives;
+    private presets;
+    /** Sorted-name key → preset that renders that combination as one tested keyframe. */
+    private combos;
+    registerPrimitive(primitive: Primitive): this;
+    registerPreset(preset: Preset): this;
+    registerPresets(presets: Preset[]): this;
+    registerPrimitives(primitives: Primitive[]): this;
+    /**
+     * Declare that a set of effect names has a purpose-built single-keyframe implementation.
+     * Checked before channel conflict analysis, so `fade-up` + `blur-in` can resolve to the
+     * tested `fade-blur-up` rather than being rejected for both writing `opacity`.
+     */
+    registerCombo(names: string[], presetName: string): this;
+    resolve(name: string): ResolvedEffect | undefined;
+    findCombo(names: string[]): ResolvedEffect | undefined;
+    has(name: string): boolean;
+    /** All registered effect names, for docs generation and dev-mode "did you mean" hints. */
+    names(): string[];
+    getPrimitive(id: string): Primitive | undefined;
+}
+/** Custom property a primitive's timing parameter writes to. */
+export declare function timingProperty(primitiveId: string, name: string): string;
+/** Levenshtein-lite suggestion for unknown effect names. Dev-mode ergonomics only. */
+export declare function suggest(name: string, candidates: string[]): string | undefined;

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

@@ -0,0 +1,35 @@
+/**
+ * Diagnostic sink.
+ *
+ * Injected rather than calling `console` directly so warnings are assertable in tests and
+ * silenceable in production without a build-time flag.
+ */
+export interface Reporter {
+    warn(message: string, subject?: unknown): void;
+}
+/**
+ * Reporter that writes to the console with a library prefix.
+ *
+ * @returns A reporter suitable for development builds.
+ * @complexity O(1) time, O(1) space.
+ * @overallScore 100
+ */
+export declare function consoleReporter(): Reporter;
+/**
+ * Reporter that discards everything. The production default.
+ *
+ * @complexity O(1) time, O(1) space.
+ * @overallScore 100
+ */
+export declare function silentReporter(): Reporter;
+export interface CollectingReporter extends Reporter {
+    readonly messages: string[];
+}
+/**
+ * Reporter that records messages for assertion.
+ *
+ * @returns A reporter whose `messages` array accumulates every warning in order.
+ * @complexity O(1) amortised per warning; O(n) space in the number of warnings.
+ * @overallScore 100
+ */
+export declare function collectingReporter(): CollectingReporter;