@texuli/core 0.4.0 → 0.6.0

package/dist/motion/animate.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Animate: the Web Animations wrapper every motion texel plays through
+ * (ADR-013). It clamps timing, applies the motion level and reduced motion,
+ * and commits the end state at once (no frames, `finished` resolves
+ * `"instant"`) whenever motion cannot or must not run: on the server, without
+ * the Web Animations API, on a detached element, at level `none`, under
+ * reduced motion, or with a zero duration.
+ *
+ * Animations use `fill: "none"` (`"backwards"` only while a delay holds the
+ * first frame), so no inline style outlives them; the final state belongs in
+ * classes, attributes or props.
+ */
+import { type MotionLevel, type ReducedMotionPolicy, type ReducedMotionSource } from './preferences.js';
+import { type SpringParams } from './spring.js';
+/** Keyframes in either Web Animations form. */
+export type MotionKeyframes = Keyframe[] | PropertyIndexedKeyframes;
+/** How a motion run ended. */
+export type MotionOutcome = 
+/** Every animation played to its end. */
+'finished'
+/** The end state was committed without frames (see {@link InstantReason}). */
+ | 'instant'
+/** `cancel()` stopped it. */
+ | 'cancelled'
+/** A newer run took over (a reversal, a new measure, a new transition). */
+ | 'interrupted';
+/** Why a run committed instantly. */
+export type InstantReason = 'server' | 'detached' | 'level-none' | 'reduced-motion' | 'no-properties' | 'zero-duration' | 'no-waapi' | 'error' | 'limit';
+/** Reduced motion: a fixed value, a live source, or omitted (read the element's window). */
+export type ReducedMotionInput = boolean | ReducedMotionSource | null | undefined;
+/** Timing and policy shared by every motion texel. */
+export type MotionTiming = {
+    /** Milliseconds, clamped to [0, 1000]; NaN or negative is 0 (instant). Default 200. */
+    duration?: number;
+    /** Milliseconds before the animation starts, clamped like `duration`. Default 0. */
+    delay?: number;
+    /** A CSS easing. Default `cubic-bezier(0.4, 0, 0.2, 1)` (the `standard` token). */
+    easing?: string;
+    /** Play on a spring instead: the duration is its settle time and the easing its `linear()` curve. */
+    spring?: Partial<SpringParams> & {
+        velocity?: number;
+    };
+    /** The already-resolved motion level (see `resolveMotionLevel`). Default `full`. */
+    level?: MotionLevel;
+    /** Reduced motion; omitted reads `prefers-reduced-motion` from the element's window. */
+    reducedMotion?: ReducedMotionInput;
+    /** `instant` (default) commits the end state; `fade` keeps an opacity-only 150 ms fade. */
+    reducedMotionPolicy?: ReducedMotionPolicy;
+};
+/** One running (or already settled) motion. */
+export type MotionRun = {
+    /** Resolves once with the outcome; never rejects. */
+    readonly finished: Promise<MotionOutcome>;
+    /** The live animations (empty when instant). */
+    readonly animations: readonly Animation[];
+    /** Why it committed instantly, or `null` when it animates. */
+    readonly instantReason: InstantReason | null;
+    /** Stop now; no style remains. Resolves `finished` with `"cancelled"`. */
+    cancel: () => void;
+    /** Jump to the end. Resolves `finished` with `"finished"`. */
+    finish: () => void;
+};
+export type AnimateOptions = MotionTiming & {
+    /** Called once with the outcome, before `finished` resolves. */
+    onFinish?: (outcome: MotionOutcome) => void;
+};
+/** Default duration (the `base` token) and easing (the `standard` token). */
+export declare const DEFAULT_MOTION_DURATION = 200;
+export declare const DEFAULT_MOTION_EASING = "cubic-bezier(0.4, 0, 0.2, 1)";
+/** Resolved, clamped plan for one animation. */
+export type ResolvedMotion = {
+    readonly instant: true;
+    readonly reason: InstantReason;
+} | {
+    readonly instant: false;
+    readonly keyframes: MotionKeyframes;
+    readonly duration: number;
+    readonly delay: number;
+    readonly easing: string;
+};
+/** Keyframes without movement or scale (what `subtle` plays). `null` when nothing is left. */
+export declare function withoutTravel(keyframes: MotionKeyframes): MotionKeyframes | null;
+/**
+ * Resolve keyframes and timing for one element: the level, reduced motion,
+ * clamping and the environment checks, without starting anything.
+ */
+export declare function resolveMotion(element: Element | null | undefined, keyframes: MotionKeyframes, timing?: MotionTiming): ResolvedMotion;
+/** Start a resolved plan; `null` when the browser refuses it (an invalid easing, say). */
+export declare function startAnimation(element: Element, plan: Extract<ResolvedMotion, {
+    instant: false;
+}>, extra?: {
+    endDelay?: number;
+}): Animation | null;
+/**
+ * Settle a set of animations as one run. With no animations the run is
+ * instant: `onFinish` fires synchronously and `finished` resolves `"instant"`.
+ */
+export declare function createRun(animations: readonly Animation[], onFinish?: (outcome: MotionOutcome) => void, instantReason?: InstantReason | null): MotionRun & {
+    interrupt: () => void;
+};
+/**
+ * Animate one element through the Web Animations API with the motion level
+ * and reduced motion applied.
+ *
+ * @example
+ * const run = animate(card, [{ opacity: 0 }, { opacity: 1 }], { duration: 150 });
+ * await run.finished; // "finished", or "instant" under reduced motion
+ */
+export declare function animate(element: Element | null | undefined, keyframes: MotionKeyframes, options?: AnimateOptions): MotionRun;

package/dist/motion/animate.js

@@ -0,0 +1,225 @@
+/**
+ * Animate: the Web Animations wrapper every motion texel plays through
+ * (ADR-013). It clamps timing, applies the motion level and reduced motion,
+ * and commits the end state at once (no frames, `finished` resolves
+ * `"instant"`) whenever motion cannot or must not run: on the server, without
+ * the Web Animations API, on a detached element, at level `none`, under
+ * reduced motion, or with a zero duration.
+ *
+ * Animations use `fill: "none"` (`"backwards"` only while a delay holds the
+ * first frame), so no inline style outlives them; the final state belongs in
+ * classes, attributes or props.
+ */
+import { getOwnerWindow } from "../env/index.js";
+import { prefersReducedMotion } from "../presence/presence.js";
+import { motionDuration, REDUCED_FADE_MS, } from "./preferences.js";
+import { springEasing } from "./spring.js";
+/** Default duration (the `base` token) and easing (the `standard` token). */
+export const DEFAULT_MOTION_DURATION = 200;
+export const DEFAULT_MOTION_EASING = 'cubic-bezier(0.4, 0, 0.2, 1)';
+const SPRING_FALLBACK_EASING = 'cubic-bezier(0.2, 0, 0, 1)';
+/** Properties that move or scale: dropped at level `subtle`. */
+const TRAVEL = new Set([
+    'transform',
+    'transformOrigin',
+    'translate',
+    'scale',
+    'rotate',
+    'offsetDistance',
+]);
+const META = new Set(['offset', 'easing', 'composite']);
+function filterKeyframes(keyframes, keep) {
+    let any = false;
+    if (Array.isArray(keyframes)) {
+        const out = keyframes.map((frame) => {
+            const next = {};
+            for (const [key, value] of Object.entries(frame ?? {})) {
+                if (META.has(key) || keep(key)) {
+                    next[key] = value;
+                    if (!META.has(key))
+                        any = true;
+                }
+            }
+            return next;
+        });
+        return any ? out : null;
+    }
+    if (!keyframes || typeof keyframes !== 'object')
+        return null;
+    const out = {};
+    for (const [key, value] of Object.entries(keyframes)) {
+        if (META.has(key) || keep(key)) {
+            out[key] = value;
+            if (!META.has(key))
+                any = true;
+        }
+    }
+    return any ? out : null;
+}
+/** Keyframes without movement or scale (what `subtle` plays). `null` when nothing is left. */
+export function withoutTravel(keyframes) {
+    return filterKeyframes(keyframes, (property) => !TRAVEL.has(property));
+}
+function opacityOnly(keyframes) {
+    return filterKeyframes(keyframes, (property) => property === 'opacity');
+}
+function readReduced(input, win) {
+    if (typeof input === 'boolean')
+        return input;
+    if (input && typeof input.get === 'function')
+        return input.get() === true;
+    return prefersReducedMotion(win ?? null, false);
+}
+function supportsLinear(win) {
+    try {
+        const css = win?.CSS;
+        return css?.supports?.('animation-timing-function', 'linear(0, 1)') === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve keyframes and timing for one element: the level, reduced motion,
+ * clamping and the environment checks, without starting anything.
+ */
+export function resolveMotion(element, keyframes, timing = {}) {
+    const win = element ? getOwnerWindow(element) : undefined;
+    if (!element || !win)
+        return { instant: true, reason: 'server' };
+    if (!element.isConnected)
+        return { instant: true, reason: 'detached' };
+    const level = timing.level ?? 'full';
+    if (level === 'none')
+        return { instant: true, reason: 'level-none' };
+    let frames = keyframes;
+    let duration;
+    let delay;
+    let easing = typeof timing.easing === 'string' && timing.easing ? timing.easing : DEFAULT_MOTION_EASING;
+    if (readReduced(timing.reducedMotion, win)) {
+        if (timing.reducedMotionPolicy !== 'fade')
+            return { instant: true, reason: 'reduced-motion' };
+        frames = opacityOnly(keyframes);
+        duration = REDUCED_FADE_MS;
+        delay = 0;
+        easing = 'linear';
+    }
+    else {
+        if (level === 'subtle')
+            frames = withoutTravel(keyframes);
+        if (timing.spring) {
+            const spring = springEasing(timing.spring, { velocity: timing.spring.velocity ?? 0 });
+            duration = motionDuration(spring.durationMs, level);
+            easing = supportsLinear(win) ? spring.easing : SPRING_FALLBACK_EASING;
+        }
+        else {
+            duration = motionDuration(timing.duration ?? DEFAULT_MOTION_DURATION, level);
+        }
+        delay = motionDuration(timing.delay ?? 0, level);
+    }
+    if (!frames)
+        return { instant: true, reason: 'no-properties' };
+    if (duration <= 0)
+        return { instant: true, reason: 'zero-duration' };
+    if (typeof element.animate !== 'function') {
+        return { instant: true, reason: 'no-waapi' };
+    }
+    return { instant: false, keyframes: frames, duration, delay, easing };
+}
+/** Start a resolved plan; `null` when the browser refuses it (an invalid easing, say). */
+export function startAnimation(element, plan, extra = {}) {
+    try {
+        const animation = element.animate(plan.keyframes, {
+            duration: plan.duration,
+            delay: plan.delay,
+            endDelay: extra.endDelay ?? 0,
+            easing: plan.easing,
+            fill: plan.delay > 0 ? 'backwards' : 'none',
+        });
+        // A cancelled animation rejects `finished`; never leave that unhandled.
+        animation?.finished?.catch(() => { });
+        return animation ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Settle a set of animations as one run. With no animations the run is
+ * instant: `onFinish` fires synchronously and `finished` resolves `"instant"`.
+ */
+export function createRun(animations, onFinish, instantReason = null) {
+    let settled = false;
+    let resolve = () => { };
+    const finished = new Promise((r) => {
+        resolve = r;
+    });
+    const settle = (outcome) => {
+        if (settled)
+            return;
+        settled = true;
+        onFinish?.(outcome);
+        resolve(outcome);
+    };
+    const stopAll = (outcome) => {
+        settle(outcome);
+        for (const animation of animations) {
+            try {
+                animation.cancel();
+            }
+            catch {
+                // A cancelled animation stays cancelled.
+            }
+        }
+    };
+    if (animations.length === 0) {
+        settle('instant');
+    }
+    else {
+        let remaining = animations.length;
+        for (const animation of animations) {
+            animation.finished.then(() => {
+                remaining -= 1;
+                if (remaining === 0)
+                    settle('finished');
+            }, () => settle('cancelled'));
+        }
+    }
+    return {
+        finished,
+        animations,
+        instantReason: animations.length === 0 ? (instantReason ?? 'zero-duration') : null,
+        cancel: () => stopAll('cancelled'),
+        interrupt: () => stopAll('interrupted'),
+        finish() {
+            if (settled)
+                return;
+            for (const animation of animations) {
+                try {
+                    animation.finish();
+                }
+                catch {
+                    // An animation that cannot finish is cancelled below.
+                    animation.cancel();
+                }
+            }
+            settle('finished');
+        },
+    };
+}
+/**
+ * Animate one element through the Web Animations API with the motion level
+ * and reduced motion applied.
+ *
+ * @example
+ * const run = animate(card, [{ opacity: 0 }, { opacity: 1 }], { duration: 150 });
+ * await run.finished; // "finished", or "instant" under reduced motion
+ */
+export function animate(element, keyframes, options = {}) {
+    const plan = resolveMotion(element, keyframes, options);
+    if (plan.instant || !element) {
+        return createRun([], options.onFinish, plan.instant ? plan.reason : 'server');
+    }
+    const animation = startAnimation(element, plan);
+    return createRun(animation ? [animation] : [], options.onFinish, animation ? null : 'error');
+}

package/dist/motion/flip.d.ts

@@ -0,0 +1,58 @@
+/**
+ * FLIP layout animation (ADR-013): measure (First), let the DOM change
+ * (Last), Invert with a transform, Play it back to identity.
+ *
+ * Reads and writes are batched: `measure` and `play` read every rectangle
+ * before they cancel or start any animation, so a list of any length lays out
+ * once per phase. A `measure` during a running play reads the in-flight
+ * (visual) positions, then interrupts the old run, so a re-reorder continues
+ * from where items are on screen.
+ *
+ * Deltas are measured in physical pixels, so reorders are correct in either
+ * direction; insert offsets are logical (`inline-start` follows `dir`).
+ * At level `subtle` moved items snap (no travel) and inserts only fade;
+ * at `none` or under reduced motion everything commits at once.
+ */
+import { type MotionKeyframes, type MotionOutcome, type MotionRun, type MotionTiming } from './animate.js';
+/** Items keyed by a stable id (a `Map` works). */
+export type FlipItems = Iterable<readonly [string, Element]>;
+/** Where an inserted item comes from: a fade, or a short slide from a logical side. */
+export type FlipEnter = false | 'fade' | 'inline-start' | 'inline-end' | 'block-start' | 'block-end' | MotionKeyframes;
+export type FlipOptions = MotionTiming & {
+    /** Animate size changes with a scale as well. Default `true`. */
+    scale?: boolean;
+    /** Inserted items (keys `measure` did not see). Default `"fade"`. */
+    enter?: FlipEnter;
+    /** Slide distance for a logical `enter`, in px (clamped to [0, 64]). Default 8. */
+    enterDistance?: number;
+    /** Above this many animated items the change commits at once. Default 500. */
+    maxItems?: number;
+    onFinish?: (outcome: MotionOutcome) => void;
+};
+export type FlipController = {
+    /** First: record where every item is now (interrupts a running play). */
+    measure: (items: FlipItems) => void;
+    /** Last, Invert, Play: animate each item from its measured box to its current one. */
+    play: (items: FlipItems) => MotionRun;
+    /** Cancel the running play. */
+    cancel: () => void;
+};
+type Box = {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+};
+/** The inverted transform from `first` to `last` (`null` when nothing moved). */
+export declare function flipTransform(first: Box, last: Box, scale?: boolean): string | null;
+/**
+ * Create a FLIP controller for one list (or any set of keyed elements).
+ *
+ * @example
+ * const flip = createFlip({ duration: 200 });
+ * flip.measure(itemsByKey);
+ * reorder(); // the DOM changes
+ * await flip.play(itemsByKey).finished;
+ */
+export declare function createFlip(options?: FlipOptions): FlipController;
+export {};

package/dist/motion/flip.js

@@ -0,0 +1,167 @@
+/**
+ * FLIP layout animation (ADR-013): measure (First), let the DOM change
+ * (Last), Invert with a transform, Play it back to identity.
+ *
+ * Reads and writes are batched: `measure` and `play` read every rectangle
+ * before they cancel or start any animation, so a list of any length lays out
+ * once per phase. A `measure` during a running play reads the in-flight
+ * (visual) positions, then interrupts the old run, so a re-reorder continues
+ * from where items are on screen.
+ *
+ * Deltas are measured in physical pixels, so reorders are correct in either
+ * direction; insert offsets are logical (`inline-start` follows `dir`).
+ * At level `subtle` moved items snap (no travel) and inserts only fade;
+ * at `none` or under reduced motion everything commits at once.
+ */
+import { getOwnerWindow } from "../env/index.js";
+import { createRun, resolveMotion, startAnimation, } from "./animate.js";
+const MAX_DELTA = 100_000;
+function boxOf(element) {
+    if (!element.isConnected || typeof element.getBoundingClientRect !== 'function')
+        return null;
+    const r = element.getBoundingClientRect();
+    const box = { left: r.left, top: r.top, width: r.width, height: r.height };
+    return Number.isFinite(box.left) &&
+        Number.isFinite(box.top) &&
+        Number.isFinite(box.width) &&
+        Number.isFinite(box.height)
+        ? box
+        : null;
+}
+function num(value) {
+    const clamped = Math.max(-MAX_DELTA, Math.min(MAX_DELTA, value));
+    const r = Math.round(clamped * 1000) / 1000;
+    return String(Object.is(r, -0) ? 0 : r);
+}
+/** The inverted transform from `first` to `last` (`null` when nothing moved). */
+export function flipTransform(first, last, scale = true) {
+    const dx = first.left - last.left;
+    const dy = first.top - last.top;
+    const sx = scale && last.width > 0 && first.width > 0 ? first.width / last.width : 1;
+    const sy = scale && last.height > 0 && first.height > 0 ? first.height / last.height : 1;
+    if (Math.abs(dx) < 0.5 &&
+        Math.abs(dy) < 0.5 &&
+        Math.abs(sx - 1) < 0.001 &&
+        Math.abs(sy - 1) < 0.001) {
+        return null;
+    }
+    const move = `translate(${num(dx)}px, ${num(dy)}px)`;
+    return sx === 1 && sy === 1 ? move : `${move} scale(${num(sx)}, ${num(sy)})`;
+}
+function isRtl(element) {
+    const win = getOwnerWindow(element);
+    try {
+        return win?.getComputedStyle(element).direction === 'rtl';
+    }
+    catch {
+        return false;
+    }
+}
+function enterFrames(enter, distance, rtl) {
+    if (enter === false)
+        return null;
+    if (typeof enter === 'object')
+        return enter;
+    if (enter === 'fade')
+        return [{ opacity: 0 }, { opacity: 1 }];
+    const sign = enter === 'inline-start' || enter === 'block-start' ? -1 : 1;
+    const inline = enter.startsWith('inline');
+    const px = num(sign * distance * (inline && rtl ? -1 : 1));
+    const from = inline ? `translate(${px}px, 0px)` : `translate(0px, ${px}px)`;
+    return [
+        { opacity: 0, transform: from },
+        { opacity: 1, transform: 'none' },
+    ];
+}
+/**
+ * Create a FLIP controller for one list (or any set of keyed elements).
+ *
+ * @example
+ * const flip = createFlip({ duration: 200 });
+ * flip.measure(itemsByKey);
+ * reorder(); // the DOM changes
+ * await flip.play(itemsByKey).finished;
+ */
+export function createFlip(options = {}) {
+    const scale = options.scale !== false;
+    const enter = options.enter ?? 'fade';
+    const distance = Math.max(0, Math.min(64, Number.isFinite(options.enterDistance) ? options.enterDistance : 8));
+    const maxItems = Math.max(0, Math.floor(Number.isFinite(options.maxItems) ? options.maxItems : 500));
+    let first = new Map();
+    let running = null;
+    function interrupt() {
+        running?.interrupt();
+        running = null;
+    }
+    return {
+        measure(items) {
+            // Read phase: every box (in-flight transforms included) before any write.
+            const next = new Map();
+            for (const [key, element] of items) {
+                const box = element ? boxOf(element) : null;
+                if (box)
+                    next.set(String(key), box);
+            }
+            first = next;
+            // Write phase: stop the old run so `play` reads the new layout untransformed.
+            interrupt();
+        },
+        play(items) {
+            interrupt();
+            const before = first;
+            first = new Map();
+            const jobs = [];
+            let rtl = null;
+            for (const [rawKey, element] of items) {
+                if (!element)
+                    continue;
+                const key = String(rawKey);
+                const last = boxOf(element);
+                if (!last)
+                    continue;
+                const from = before.get(key);
+                let frames;
+                if (from) {
+                    const transform = flipTransform(from, last, scale);
+                    frames = transform
+                        ? [
+                            { transform, transformOrigin: '0 0' },
+                            { transform: 'none', transformOrigin: '0 0' },
+                        ]
+                        : null;
+                }
+                else {
+                    if (rtl === null && typeof enter === 'string' && enter.startsWith('inline'))
+                        rtl = isRtl(element);
+                    frames = enterFrames(enter, distance, rtl === true);
+                }
+                if (frames)
+                    jobs.push({ element, frames, plan: resolveMotion(element, frames, options) });
+            }
+            if (jobs.length > maxItems) {
+                return createRun([], options.onFinish, 'limit');
+            }
+            // Write phase.
+            const animations = [];
+            let reason = null;
+            for (const job of jobs) {
+                if (job.plan.instant) {
+                    reason ??= job.plan.reason;
+                    continue;
+                }
+                const animation = startAnimation(job.element, job.plan);
+                if (animation)
+                    animations.push(animation);
+                else
+                    reason ??= 'error';
+            }
+            const run = createRun(animations, options.onFinish, reason ?? 'zero-duration');
+            running = animations.length > 0 ? run : null;
+            return run;
+        },
+        cancel() {
+            running?.cancel();
+            running = null;
+        },
+    };
+}

package/dist/motion/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @texuli/core/motion: the motion runtime (ADR-013). Web Animations with an
+ * owned spring solver, reduced motion instant by construction, and the
+ * `full` / `subtle` / `none` motion levels shared with the deck.
+ *
+ * Not re-exported from the `@texuli/core` root barrel: a component that does
+ * not animate pays nothing for it.
+ */
+export { type AnimateOptions, animate, createRun, DEFAULT_MOTION_DURATION, DEFAULT_MOTION_EASING, type InstantReason, type MotionKeyframes, type MotionOutcome, type MotionRun, type MotionTiming, type ReducedMotionInput, type ResolvedMotion, resolveMotion, startAnimation, withoutTravel, } from './animate.js';
+export { createFlip, type FlipController, type FlipEnter, type FlipItems, type FlipOptions, flipTransform, } from './flip.js';
+export { createReducedMotionSource, isMotionLevel, lowerMotionLevel, MAX_MOTION_MS, MOTION_LEVELS, type MotionLevel, type MotionLevelInput, motionDuration, REDUCED_FADE_MS, type ReducedMotionPolicy, type ReducedMotionSource, type ReducedMotionSourceOptions, resolveMotionLevel, SUBTLE_DURATION_SCALE, } from './preferences.js';
+export { createMotionPresence, type MotionPresence, type MotionPresenceOptions, } from './presence.js';
+export { MAX_STAGGER_SPAN, MAX_TIMELINE_STEPS, type ParallelGroup, parallel, type StaggerOptions, sequence, stagger, type Timeline, type TimelineEntry, type TimelineOptions, type TimelineStep, timeline, } from './sequence.js';
+export { createSharedElements, type ScopedViewTransitionOptions, type SharedElements, type SharedElementsOptions, startScopedViewTransition, } from './shared.js';
+export * from './spring.js';

package/dist/motion/index.js

@@ -0,0 +1,15 @@
+/**
+ * @texuli/core/motion: the motion runtime (ADR-013). Web Animations with an
+ * owned spring solver, reduced motion instant by construction, and the
+ * `full` / `subtle` / `none` motion levels shared with the deck.
+ *
+ * Not re-exported from the `@texuli/core` root barrel: a component that does
+ * not animate pays nothing for it.
+ */
+export { animate, createRun, DEFAULT_MOTION_DURATION, DEFAULT_MOTION_EASING, resolveMotion, startAnimation, withoutTravel, } from "./animate.js";
+export { createFlip, flipTransform, } from "./flip.js";
+export { createReducedMotionSource, isMotionLevel, lowerMotionLevel, MAX_MOTION_MS, MOTION_LEVELS, motionDuration, REDUCED_FADE_MS, resolveMotionLevel, SUBTLE_DURATION_SCALE, } from "./preferences.js";
+export { createMotionPresence, } from "./presence.js";
+export { MAX_STAGGER_SPAN, MAX_TIMELINE_STEPS, parallel, sequence, stagger, timeline, } from "./sequence.js";
+export { createSharedElements, startScopedViewTransition, } from "./shared.js";
+export * from "./spring.js";

package/dist/motion/preferences.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Motion preferences: the reduced-motion source and the motion-level
+ * resolver (ADR-013). Framework-free; no module-scope browser access.
+ */
+/** Motion levels shared with `@texuli/deck`: `subtle` shortens and drops travel, `none` is instant. */
+export declare const MOTION_LEVELS: readonly ["full", "subtle", "none"];
+export type MotionLevel = (typeof MOTION_LEVELS)[number];
+/** `subtle` multiplies every duration and offset by this factor (the deck's value). */
+export declare const SUBTLE_DURATION_SCALE = 0.6;
+/** Longest duration or delay any motion texel plays, in milliseconds. */
+export declare const MAX_MOTION_MS = 1000;
+/** Duration of the opt-in `fade` reduced-motion policy (the deck stage's slide fade). */
+export declare const REDUCED_FADE_MS = 150;
+/** What reduced motion does: commit the end state at once (default), or keep an opacity-only fade. */
+export type ReducedMotionPolicy = 'instant' | 'fade';
+/** A live view of `prefers-reduced-motion` with a host override. */
+export type ReducedMotionSource = {
+    /** Current value: the override when set, else the media query, else the SSR default. */
+    get: () => boolean;
+    /** Called with the new value whenever it changes; returns an unsubscribe function. */
+    subscribe: (listener: (reduced: boolean) => void) => () => void;
+    /** Force reduced motion on or off; `null` returns to the media query. */
+    setOverride: (value: boolean | null) => void;
+    /** Stop listening to the media query and drop every listener. */
+    dispose: () => void;
+};
+export type ReducedMotionSourceOptions = {
+    /** Window to read `matchMedia` from. Omit on the server. */
+    window?: Pick<Window, 'matchMedia'> | null;
+    /** Initial host override (`null` or omitted reads the media query). */
+    override?: boolean | null;
+    /** Value without a window. Default `false` (texels do not run on the server anyway). */
+    ssrDefault?: boolean;
+};
+/**
+ * Create a reduced-motion source. It reads `(prefers-reduced-motion: reduce)`
+ * from the given window, follows its `change` events, and lets the host
+ * override it (a settings toggle, a test, a print view).
+ */
+export declare function createReducedMotionSource(options?: ReducedMotionSourceOptions): ReducedMotionSource;
+/** Whether a value is one of {@link MOTION_LEVELS}. */
+export declare function isMotionLevel(value: unknown): value is MotionLevel;
+/** The lower of two levels (`none` < `subtle` < `full`); invalid values are ignored. */
+export declare function lowerMotionLevel(a: unknown, b: unknown): MotionLevel;
+export type MotionLevelInput = {
+    /** The host's level (an app setting); wins over everything below it. */
+    host?: unknown;
+    /** The blueprint's or deck's level. */
+    document?: unknown;
+    /** The component default. */
+    component?: unknown;
+    /** The viewer's preference: can only lower the result. */
+    viewer?: unknown;
+    /** Reduced motion lowers the result to `none` (the texels commit the end state at once). */
+    reducedMotion?: boolean;
+};
+/**
+ * Resolve the motion level: host, then blueprint or deck, then the component
+ * default, then `full`; the viewer's preference and reduced motion only lower
+ * it. Invalid values are skipped.
+ */
+export declare function resolveMotionLevel(input?: MotionLevelInput): MotionLevel;
+/**
+ * Clamp a duration or delay to [0, {@link MAX_MOTION_MS}] and scale it for the
+ * level: `subtle` × {@link SUBTLE_DURATION_SCALE}, `none` → 0. NaN and
+ * negative values are 0; Infinity is the maximum.
+ */
+export declare function motionDuration(ms: unknown, level?: MotionLevel): number;