@texuli/core 0.4.0 → 0.6.0

package/dist/motion/preferences.js

@@ -0,0 +1,111 @@
+/**
+ * Motion preferences: the reduced-motion source and the motion-level
+ * resolver (ADR-013). Framework-free; no module-scope browser access.
+ */
+import { REDUCED_MOTION_QUERY } from "../presence/presence.js";
+/** Motion levels shared with `@texuli/deck`: `subtle` shortens and drops travel, `none` is instant. */
+export const MOTION_LEVELS = ['full', 'subtle', 'none'];
+/** `subtle` multiplies every duration and offset by this factor (the deck's value). */
+export const SUBTLE_DURATION_SCALE = 0.6;
+/** Longest duration or delay any motion texel plays, in milliseconds. */
+export const MAX_MOTION_MS = 1000;
+/** Duration of the opt-in `fade` reduced-motion policy (the deck stage's slide fade). */
+export const REDUCED_FADE_MS = 150;
+/**
+ * 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 function createReducedMotionSource(options = {}) {
+    const ssrDefault = options.ssrDefault === true;
+    let override = typeof options.override === 'boolean' ? options.override : null;
+    const listeners = new Set();
+    let query = null;
+    const win = options.window;
+    if (win && typeof win.matchMedia === 'function') {
+        try {
+            query = win.matchMedia(REDUCED_MOTION_QUERY);
+        }
+        catch {
+            query = null;
+        }
+    }
+    let last = read();
+    function read() {
+        if (override !== null)
+            return override;
+        if (query)
+            return query.matches === true;
+        return ssrDefault;
+    }
+    function notify() {
+        const next = read();
+        if (next === last)
+            return;
+        last = next;
+        for (const listener of [...listeners])
+            listener(next);
+    }
+    const onChange = () => notify();
+    if (query?.addEventListener)
+        query.addEventListener('change', onChange);
+    else
+        query?.addListener?.(onChange);
+    return {
+        get: read,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        setOverride(value) {
+            override = typeof value === 'boolean' ? value : null;
+            notify();
+        },
+        dispose() {
+            if (query?.removeEventListener)
+                query.removeEventListener('change', onChange);
+            else
+                query?.removeListener?.(onChange);
+            query = null;
+            listeners.clear();
+        },
+    };
+}
+/** Whether a value is one of {@link MOTION_LEVELS}. */
+export function isMotionLevel(value) {
+    return typeof value === 'string' && MOTION_LEVELS.includes(value);
+}
+const RANK = { full: 2, subtle: 1, none: 0 };
+/** The lower of two levels (`none` < `subtle` < `full`); invalid values are ignored. */
+export function lowerMotionLevel(a, b) {
+    const left = isMotionLevel(a) ? a : 'full';
+    const right = isMotionLevel(b) ? b : 'full';
+    return RANK[left] <= RANK[right] ? left : right;
+}
+/**
+ * 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 function resolveMotionLevel(input = {}) {
+    const chosen = isMotionLevel(input.host)
+        ? input.host
+        : isMotionLevel(input.document)
+            ? input.document
+            : isMotionLevel(input.component)
+                ? input.component
+                : 'full';
+    const level = lowerMotionLevel(chosen, input.viewer);
+    return input.reducedMotion === true ? 'none' : level;
+}
+/**
+ * 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 function motionDuration(ms, level = 'full') {
+    if (typeof ms !== 'number' || Number.isNaN(ms) || ms <= 0 || level === 'none')
+        return 0;
+    const clamped = Math.min(MAX_MOTION_MS, ms);
+    return Math.round(level === 'subtle' ? clamped * SUBTLE_DURATION_SCALE : clamped);
+}

package/dist/motion/presence.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Motion presence: enter and exit animations with interruptible reversal
+ * (ADR-013), on the `@texuli/core/presence` vocabulary (`PresenceSnapshot`,
+ * `data-state`).
+ *
+ * The core presence waits for CSS `transitionend` / `animationend`; Web
+ * Animations fire neither, and an unrelated CSS transition on the node would
+ * end the exit early, so this machine drives the same snapshot from its own
+ * animations instead. Toggling mid-flight reverses the running animation from
+ * where it is (no jump) and resolves the earlier transition `"interrupted"`.
+ *
+ * Nothing animates on the server or on hydration: the first attached node
+ * with `present: true` shows at once unless `appear` is set.
+ */
+import { type PresenceSnapshot } from '../presence/presence.js';
+import { type MotionKeyframes, type MotionOutcome, type MotionTiming } from './animate.js';
+export type MotionPresenceOptions = MotionTiming & {
+    /** Initial intent. Default `false`. */
+    present?: boolean;
+    /** Play the enter animation for a node that is present on first attach. Default `false`. */
+    appear?: boolean;
+    /** Keep the node mounted after exit (`data-state` still closes). Default `false`. */
+    forceMount?: boolean;
+    /** Enter keyframes (hidden → shown). Default a fade in. */
+    enter?: MotionKeyframes;
+    /** Exit keyframes (shown → hidden). Default the reverse of `enter`. */
+    exit?: MotionKeyframes;
+    /** Timing overrides for the exit (merged over the shared timing). */
+    exitTiming?: MotionTiming;
+    /** Snapshot changed. */
+    onSnapshot?: (snapshot: PresenceSnapshot) => void;
+    /** The enter path began (the node should be mounted). */
+    onEnter?: (snapshot: PresenceSnapshot) => void;
+    /** The enter animation ended (or committed instantly). */
+    onEnterComplete?: (snapshot: PresenceSnapshot) => void;
+    /** The exit ended; unmount when `snapshot.mounted` is false. */
+    onExitComplete?: (snapshot: PresenceSnapshot) => void;
+};
+export type MotionPresence = {
+    getSnapshot: () => PresenceSnapshot;
+    /** Drive the intent; resolves when this transition settles. */
+    setPresent: (present: boolean) => Promise<MotionOutcome>;
+    /** Attach (or detach with `null`) the animated element after it mounts. */
+    setNode: (node: Element | null) => void;
+    /** The current transition's outcome (resolved `"instant"` when idle). */
+    readonly finished: Promise<MotionOutcome>;
+    /** Cancel any animation and stop; pending transitions resolve `"cancelled"`. */
+    dispose: () => void;
+};
+/**
+ * Create a motion presence controller.
+ *
+ * @example
+ * const presence = createMotionPresence({
+ *   enter: [{ opacity: 0, transform: 'scale(0.96)' }, { opacity: 1, transform: 'none' }],
+ *   onExitComplete: (s) => { if (!s.mounted) unmount(); },
+ * });
+ * presence.setNode(panel);
+ * await presence.setPresent(false); // "finished", or "instant" under reduced motion
+ */
+export declare function createMotionPresence(options?: MotionPresenceOptions): MotionPresence;

package/dist/motion/presence.js

@@ -0,0 +1,231 @@
+/**
+ * Motion presence: enter and exit animations with interruptible reversal
+ * (ADR-013), on the `@texuli/core/presence` vocabulary (`PresenceSnapshot`,
+ * `data-state`).
+ *
+ * The core presence waits for CSS `transitionend` / `animationend`; Web
+ * Animations fire neither, and an unrelated CSS transition on the node would
+ * end the exit early, so this machine drives the same snapshot from its own
+ * animations instead. Toggling mid-flight reverses the running animation from
+ * where it is (no jump) and resolves the earlier transition `"interrupted"`.
+ *
+ * Nothing animates on the server or on hydration: the first attached node
+ * with `present: true` shows at once unless `appear` is set.
+ */
+import { PRESENCE_STATE_ATTR, } from "../presence/presence.js";
+import { resolveMotion, startAnimation, } from "./animate.js";
+const DEFAULT_ENTER = [{ opacity: 0 }, { opacity: 1 }];
+function reverseFrames(frames) {
+    if (Array.isArray(frames)) {
+        return [...frames].reverse().map((frame) => {
+            const { offset, ...rest } = frame;
+            return typeof offset === 'number' ? { ...rest, offset: 1 - offset } : rest;
+        });
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(frames)) {
+        out[key] = Array.isArray(value) ? [...value].reverse() : value;
+    }
+    return out;
+}
+/**
+ * Create a motion presence controller.
+ *
+ * @example
+ * const presence = createMotionPresence({
+ *   enter: [{ opacity: 0, transform: 'scale(0.96)' }, { opacity: 1, transform: 'none' }],
+ *   onExitComplete: (s) => { if (!s.mounted) unmount(); },
+ * });
+ * presence.setNode(panel);
+ * await presence.setPresent(false); // "finished", or "instant" under reduced motion
+ */
+export function createMotionPresence(options = {}) {
+    const forceMount = options.forceMount === true;
+    const enterFrames = options.enter ?? DEFAULT_ENTER;
+    const exitFrames = options.exit ?? reverseFrames(enterFrames);
+    const timing = options;
+    const exitTiming = { ...options, ...options.exitTiming };
+    let present = options.present === true;
+    let mounted = present || forceMount;
+    let state = present ? 'open' : 'closed';
+    let exiting = false;
+    let node = null;
+    let pendingEnter = present && options.appear === true;
+    let animation = null;
+    let direction = null;
+    let disposed = false;
+    let settle = null;
+    let finished = Promise.resolve('instant');
+    const snapshot = () => ({ present, mounted, state, exiting });
+    const writeAttr = () => {
+        node?.setAttribute(PRESENCE_STATE_ATTR, state);
+    };
+    const emit = () => options.onSnapshot?.(snapshot());
+    function begin() {
+        settle?.('interrupted');
+        let resolve = () => { };
+        finished = new Promise((r) => {
+            resolve = r;
+        });
+        let done = false;
+        settle = (outcome) => {
+            if (done)
+                return;
+            done = true;
+            settle = null;
+            resolve(outcome);
+        };
+        return finished;
+    }
+    function dropAnimation() {
+        const current = animation;
+        animation = null;
+        direction = null;
+        if (current) {
+            current.onfinish = null;
+            try {
+                current.cancel();
+            }
+            catch {
+                // Already gone.
+            }
+        }
+    }
+    function complete(dir, outcome) {
+        animation = null;
+        direction = null;
+        if (dir === 'exit') {
+            exiting = false;
+            state = 'closed';
+            if (!forceMount)
+                mounted = false;
+            writeAttr();
+            const s = snapshot();
+            options.onSnapshot?.(s);
+            options.onExitComplete?.(s);
+        }
+        else {
+            options.onEnterComplete?.(snapshot());
+        }
+        settle?.(outcome);
+    }
+    function play(dir) {
+        const target = node;
+        const plan = resolveMotion(target, dir === 'enter' ? enterFrames : exitFrames, dir === 'enter' ? timing : exitTiming);
+        const started = !plan.instant && target ? startAnimation(target, plan) : null;
+        if (!started) {
+            complete(dir, 'instant');
+            return;
+        }
+        animation = started;
+        direction = dir;
+        started.onfinish = () => {
+            if (animation !== started || direction === null)
+                return;
+            complete(direction, 'finished');
+        };
+    }
+    /** Reverse the running animation in place; false when there is none to reverse. */
+    function reverseTo(dir) {
+        const current = animation;
+        if (!current || direction === dir || typeof current.reverse !== 'function')
+            return false;
+        try {
+            current.reverse();
+        }
+        catch {
+            return false;
+        }
+        direction = dir;
+        return true;
+    }
+    return {
+        getSnapshot: snapshot,
+        get finished() {
+            return finished;
+        },
+        setPresent(next) {
+            if (disposed)
+                return Promise.resolve('cancelled');
+            if (next) {
+                if (present && state === 'open' && !exiting)
+                    return finished;
+                present = true;
+                exiting = false;
+                mounted = true;
+                state = 'open';
+                writeAttr();
+                const result = begin();
+                emit();
+                options.onEnter?.(snapshot());
+                if (reverseTo('enter'))
+                    return result;
+                dropAnimation();
+                if (node)
+                    play('enter');
+                else
+                    pendingEnter = true;
+                return result;
+            }
+            present = false;
+            if (!mounted || (state === 'closed' && !exiting)) {
+                state = 'closed';
+                writeAttr();
+                return finished;
+            }
+            if (exiting)
+                return finished;
+            pendingEnter = false;
+            exiting = true;
+            state = 'closed';
+            writeAttr();
+            const result = begin();
+            emit();
+            if (reverseTo('exit'))
+                return result;
+            dropAnimation();
+            if (node)
+                play('exit');
+            else
+                complete('exit', 'instant');
+            return result;
+        },
+        setNode(next) {
+            if (disposed || next === node)
+                return;
+            if (animation) {
+                // The animated element changed: its animation cannot continue elsewhere.
+                const dir = direction ?? 'enter';
+                dropAnimation();
+                node = next;
+                writeAttr();
+                if (next)
+                    play(dir);
+                else
+                    complete(dir, 'instant');
+                return;
+            }
+            node = next;
+            writeAttr();
+            if (!next) {
+                if (exiting)
+                    complete('exit', 'instant');
+                return;
+            }
+            if (pendingEnter && present) {
+                pendingEnter = false;
+                if (!settle)
+                    begin();
+                play('enter');
+            }
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            dropAnimation();
+            settle?.('cancelled');
+            node = null;
+        },
+    };
+}

package/dist/motion/sequence.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Sequences and timelines (ADR-013): declared steps played as Web Animations
+ * on one shared clock.
+ *
+ * Top-level entries run one after another; a `parallel(...)` group runs its
+ * steps together (the group lasts as long as its longest step). Each step may
+ * add an `at` offset inside its slot, which is how `stagger` spreads a list.
+ * Every animation gets the same total length (`delay` + `duration` +
+ * `endDelay`), so `seek`, `pause` and `reverse` keep the steps aligned.
+ *
+ * Under reduced motion, at level `none`, without the Web Animations API or on
+ * the server, the timeline commits at once: `finished` resolves `"instant"`
+ * and `onFinish` fires once; play, pause, seek and reverse do nothing.
+ */
+import { type InstantReason, type MotionKeyframes, type MotionOutcome, type MotionTiming } from './animate.js';
+/** One animated step. */
+export type TimelineStep = {
+    readonly target: Element | null | undefined;
+    readonly keyframes: MotionKeyframes;
+    /** Milliseconds (clamped to [0, 1000]). Default: the timeline's `duration`. */
+    readonly duration?: number;
+    readonly easing?: string;
+    /** Extra offset inside the step's slot, in ms (clamped to [0, 1000]). */
+    readonly at?: number;
+};
+/** A group whose steps run together. */
+export type ParallelGroup = {
+    readonly parallel: readonly TimelineStep[];
+};
+export type TimelineEntry = TimelineStep | ParallelGroup;
+export type TimelineOptions = MotionTiming & {
+    /** Start playing at once. `timeline` defaults to `false`, `sequence` to `true`. */
+    autoplay?: boolean;
+    onFinish?: (outcome: MotionOutcome) => void;
+};
+export type Timeline = {
+    /** Total length in ms after the level is applied (0 when instant). */
+    readonly duration: number;
+    readonly finished: Promise<MotionOutcome>;
+    readonly instantReason: InstantReason | null;
+    readonly animations: readonly Animation[];
+    play: () => void;
+    pause: () => void;
+    /** Move every step to `ms` on the shared clock (clamped to [0, duration]). */
+    seek: (ms: number) => void;
+    /** Play backwards from the current time. */
+    reverse: () => void;
+    cancel: () => void;
+    finish: () => void;
+};
+/** Most steps one timeline animates; past it the timeline commits at once. */
+export declare const MAX_TIMELINE_STEPS = 500;
+/** Longest stagger spread, in ms: a long list compresses its per-item offset to fit. */
+export declare const MAX_STAGGER_SPAN = 1000;
+/** Group steps to run in parallel. */
+export declare function parallel(...steps: TimelineStep[]): ParallelGroup;
+export type StaggerOptions = {
+    /** Which item starts first. Default `"start"`. */
+    from?: 'start' | 'end' | 'center' | number;
+};
+/**
+ * Offsets in ms for `count` items `each` ms apart, spread from `from`. The
+ * whole spread is held to {@link MAX_STAGGER_SPAN} (a long list staggers
+ * faster instead of taking longer). `count` is clamped to [0, 10000].
+ */
+export declare function stagger(count: number, each: number, options?: StaggerOptions): number[];
+/** Build a timeline, paused until `play()` unless `autoplay` is true. */
+export declare function timeline(entries: readonly TimelineEntry[], options?: TimelineOptions): Timeline;
+/** Play steps now (a timeline that autoplays unless `autoplay: false`). */
+export declare function sequence(entries: readonly TimelineEntry[], options?: TimelineOptions): Timeline;

package/dist/motion/sequence.js

@@ -0,0 +1,159 @@
+/**
+ * Sequences and timelines (ADR-013): declared steps played as Web Animations
+ * on one shared clock.
+ *
+ * Top-level entries run one after another; a `parallel(...)` group runs its
+ * steps together (the group lasts as long as its longest step). Each step may
+ * add an `at` offset inside its slot, which is how `stagger` spreads a list.
+ * Every animation gets the same total length (`delay` + `duration` +
+ * `endDelay`), so `seek`, `pause` and `reverse` keep the steps aligned.
+ *
+ * Under reduced motion, at level `none`, without the Web Animations API or on
+ * the server, the timeline commits at once: `finished` resolves `"instant"`
+ * and `onFinish` fires once; play, pause, seek and reverse do nothing.
+ */
+import { createRun, resolveMotion, startAnimation, } from "./animate.js";
+import { MAX_MOTION_MS, motionDuration } from "./preferences.js";
+/** Most steps one timeline animates; past it the timeline commits at once. */
+export const MAX_TIMELINE_STEPS = 500;
+/** Longest stagger spread, in ms: a long list compresses its per-item offset to fit. */
+export const MAX_STAGGER_SPAN = MAX_MOTION_MS;
+/** Group steps to run in parallel. */
+export function parallel(...steps) {
+    return { parallel: steps };
+}
+/**
+ * Offsets in ms for `count` items `each` ms apart, spread from `from`. The
+ * whole spread is held to {@link MAX_STAGGER_SPAN} (a long list staggers
+ * faster instead of taking longer). `count` is clamped to [0, 10000].
+ */
+export function stagger(count, each, options = {}) {
+    const n = Math.max(0, Math.min(10_000, Math.floor(Number.isFinite(count) ? count : 0)));
+    if (n === 0)
+        return [];
+    const origin = options.from === 'end'
+        ? n - 1
+        : options.from === 'center'
+            ? (n - 1) / 2
+            : typeof options.from === 'number' && Number.isFinite(options.from)
+                ? Math.max(0, Math.min(n - 1, Math.floor(options.from)))
+                : 0;
+    const reach = Math.max(origin, n - 1 - origin);
+    const step = Number.isFinite(each) && each > 0 ? each : 0;
+    const per = reach > 0 ? Math.min(step, MAX_STAGGER_SPAN / reach) : 0;
+    return Array.from({ length: n }, (_, i) => Math.round(Math.abs(i - origin) * per * 100) / 100);
+}
+function planOf(step, options) {
+    return resolveMotion(step?.target, step?.keyframes ?? [], {
+        ...options,
+        duration: step?.duration ?? options.duration ?? 200,
+        easing: step?.easing ?? options.easing,
+        delay: 0,
+    });
+}
+/** Resolve every step, then lay the slots out with the resolved durations. */
+function schedule(entries, options) {
+    const level = options.level ?? 'full';
+    const out = [];
+    let cursor = 0;
+    const slot = (step, base) => {
+        const plan = planOf(step, options);
+        const at = motionDuration(step?.at ?? 0, level);
+        out.push({ step, start: base + at, plan });
+        return at + (plan.instant ? 0 : plan.duration);
+    };
+    for (const entry of entries) {
+        if (!entry)
+            continue;
+        if ('parallel' in entry) {
+            let longest = 0;
+            for (const step of entry.parallel ?? []) {
+                if (out.length >= MAX_TIMELINE_STEPS)
+                    return null;
+                longest = Math.max(longest, slot(step, cursor));
+            }
+            cursor += longest;
+        }
+        else {
+            if (out.length >= MAX_TIMELINE_STEPS)
+                return null;
+            cursor += slot(entry, cursor);
+        }
+    }
+    return out;
+}
+function build(entries, options, autoplay) {
+    const instant = (reason) => {
+        const run = createRun([], options.onFinish, reason);
+        return {
+            duration: 0,
+            finished: run.finished,
+            instantReason: run.instantReason,
+            animations: [],
+            play() { },
+            pause() { },
+            seek() { },
+            reverse() { },
+            cancel() { },
+            finish() { },
+        };
+    };
+    const scheduled = schedule(Array.isArray(entries) ? entries : [], options);
+    if (!scheduled)
+        return instant('limit');
+    const live = scheduled.filter((p) => !p.plan.instant);
+    if (live.length === 0) {
+        const first = scheduled.find((p) => p.plan.instant)?.plan;
+        return instant(first?.instant ? first.reason : 'zero-duration');
+    }
+    const total = Math.max(...live.map((p) => p.start + (p.plan.instant ? 0 : p.plan.duration)));
+    const animations = [];
+    for (const { step, start, plan } of live) {
+        if (plan.instant || !step.target)
+            continue;
+        const animation = startAnimation(step.target, { ...plan, delay: start }, { endDelay: Math.max(0, total - start - plan.duration) });
+        if (!animation)
+            continue;
+        if (!autoplay)
+            animation.pause();
+        animations.push(animation);
+    }
+    if (animations.length === 0)
+        return instant('error');
+    const run = createRun(animations, options.onFinish);
+    const each = (fn) => () => {
+        for (const a of animations) {
+            try {
+                fn(a);
+            }
+            catch {
+                // A finished or cancelled animation ignores the command.
+            }
+        }
+    };
+    return {
+        duration: total,
+        finished: run.finished,
+        instantReason: null,
+        animations,
+        play: each((a) => a.play()),
+        pause: each((a) => a.pause()),
+        reverse: each((a) => a.reverse()),
+        seek(ms) {
+            const t = Number.isFinite(ms) ? Math.max(0, Math.min(total, ms)) : 0;
+            each((a) => {
+                a.currentTime = t;
+            })();
+        },
+        cancel: run.cancel,
+        finish: run.finish,
+    };
+}
+/** Build a timeline, paused until `play()` unless `autoplay` is true. */
+export function timeline(entries, options = {}) {
+    return build(entries, options, options.autoplay === true);
+}
+/** Play steps now (a timeline that autoplays unless `autoplay: false`). */
+export function sequence(entries, options = {}) {
+    return build(entries, options, options.autoplay !== false);
+}

package/dist/motion/shared.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared-element transitions (ADR-013): a keyed snapshot of one element's box
+ * before a state change, played onto the element that represents the same
+ * thing after it (a thumbnail and its lightbox, a card and its detail view).
+ *
+ * The fallback everywhere is FLIP: the new element moves and scales from the
+ * captured box; when the old element is still on the page the two cross-fade.
+ * {@link startScopedViewTransition} uses an element-scoped View Transition
+ * when the browser has one and otherwise just applies the update.
+ */
+import { type MotionOutcome, type MotionRun, type MotionTiming } from './animate.js';
+export type SharedElementsOptions = MotionTiming & {
+    /** Snapshots kept at most; the oldest is dropped past it. Default 256 (clamped to [1, 4096]). */
+    maxEntries?: number;
+    onFinish?: (outcome: MotionOutcome) => void;
+};
+export type SharedElements = {
+    /** Record where `element` is now under `key`. False when it cannot be measured (detached, SSR). */
+    capture: (key: string, element: Element) => boolean;
+    /** Animate `element` from the box captured under `key`, then forget the snapshot. */
+    play: (key: string, element: Element) => MotionRun;
+    has: (key: string) => boolean;
+    release: (key: string) => void;
+    clear: () => void;
+    /** How many snapshots are held. */
+    readonly size: number;
+};
+/**
+ * Create a registry of keyed snapshots.
+ *
+ * @example
+ * const shared = createSharedElements({ duration: 250 });
+ * shared.capture('photo-3', thumbnail);
+ * openLightbox();                      // the DOM changes
+ * shared.play('photo-3', lightboxImage);
+ */
+export declare function createSharedElements(options?: SharedElementsOptions): SharedElements;
+export type ScopedViewTransitionOptions = Pick<MotionTiming, 'level' | 'reducedMotion'>;
+/**
+ * Run `update` inside an element-scoped View Transition when the browser
+ * offers `element.startViewTransition`; otherwise (no support, the server,
+ * level `none`, reduced motion) apply it at once. Resolves `"finished"` after
+ * the transition, `"instant"` when the update was applied directly.
+ */
+export declare function startScopedViewTransition(scope: Element | null | undefined, update: () => void | Promise<void>, options?: ScopedViewTransitionOptions): Promise<MotionOutcome>;