@joewinke/jatui 0.27.1 → 0.28.0

package/CLAUDE.md

@@ -227,6 +227,43 @@ const rec = createAudioRecorder({
 // Methods: start() stop() pause() resume() cancel() reset() destroy()
 ```
 
+### Sound (first-class sibling of motion)
+
+One preferences store every app sound goes through. UI + notification sounds are **off by default** (opt-in); the `incoming-call` ringer is **opt-out** (plays out of the box, muted via `categories.calls`). Semantic names (`confirm`, `error`, `notify`, `message`, `send`, `toggle`, `tap`, `incoming-call`) map to bundled CC0 clips or a host's own file. Policy per category: background tab, quiet hours and the quiet/reduced-motion mode silence `ui`/`notifications`; calls always ring. Discipline doc: `docs/sound.md`.
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `SoundSettings` | Drop-in settings section over the store: master switch, volume, per-category rows (calls row + volume stay live when the master switch is off), quiet hours, preview buttons. | `preferences?`, `player?`, `categories?: SoundCategory[]`, `showQuietHours?`, `title?`, `class?` |
+
+```typescript
+import {
+  playSound,             // playSound('confirm') → SoundHandle { stop, playing, blocked } — never throws
+  getSoundPlayer,        // .register(name, src, spec?) · .play · .preload · .stopAll
+  getSoundPreferences,   // .get · .set(patch) · .setCategory · .reset · .subscribe (localStorage 'jatui-sound-prefs', cross-tab)
+  createSoundPreferences, createSoundPlayer,   // isolated instances (tests, demos)
+  decideSound,           // the pure policy, for custom players
+  SOUND_NAMES, SOUND_SPECS, SOUND_CATEGORIES
+} from "jatui"
+// handle.blocked: 'disabled' | 'category-muted' | 'hidden' | 'quiet-hours' | 'quiet' | 'silent'
+// { preview: true } bypasses every check but master volume — only behind a "test sound" button.
+// Legacy registerSound / isSoundEnabled / setSoundEnabled still exported and route through the store.
+```
+
+### Motion level
+
+Motion is a token layer (`styles/motion.css`: `--motion-glide`/`spring`/`standard` curves; `--motion-instant`/`fast`/`enter`/`move` durations). `data-motion="calm|standard|lively"` on `<html>` or any subtree rescales durations (×0.75/×1/×1.25) and travel (8/16/24px); `calm` also flattens springs and stops `.jatui-motion-ambient` (mark decorative loops with it). `prefers-reduced-motion` wins at every level. An unknown value resolves to `standard`. Scheme + rules: `docs/motion.md`.
+
+```typescript
+import {
+  motionFade, motionScale, motionSlide, glide,   // token-built transitions (use instead of svelte/transition fade/scale/slide/fly)
+  setMotionLevel,                                // setMotionLevel('calm') · setMotionLevel('lively', heroEl) · setMotionLevel(null)
+  createMotionLevelStore,                        // persisted store: $motion.level / .reduced / .effective
+  getMotionContext, motionDuration, motionEasing // read the level from JS
+} from "jatui"
+// Transition params: duration = token ('instant'|'fast'|'enter'|'move') or standard-level ms (scaled by the level);
+// easing = token ('glide'|'spring'|'standard') or fn; level pins it instead of reading the DOM.
+```
+
 ### PDF
 
 | Component | Purpose | Key Props |

package/dist/assets/sounds/README.md

@@ -28,20 +28,22 @@ Original pack: **Kenney Interface Sounds** — https://kenney.nl/assets/interfac
 
 ## Usage
 
-```typescript
-import { registerSound, play, setSoundEnabled, isSoundEnabled } from '$lib/utils/sound';
-import { successSound } from '$lib/assets/sounds/success';
-import { errorSound } from '$lib/assets/sounds/error';
-
-// Register on app init (after first user gesture)
-await registerSound('success', successSound);
-await registerSound('error', errorSound);
+Don't import these clips directly. Play them by **semantic name** through the
+sound player, which loads them lazily and applies the user's preferences
+(on/off, volume, categories, quiet hours). See `docs/sound.md`.
+
+| Semantic name | Clip |
+|---------------|------|
+| `confirm` | success |
+| `error` | error |
+| `notify`, `message` | notify |
+| `send` | send |
+| `toggle` | toggle |
+| `tap` | pop |
+| `incoming-call` | notify, replayed every 1.2 s (register a real ringer file instead) |
 
-// Play
-play('success');            // default volume 0.15
-play('error', { volume: 0.2 });
+```typescript
+import { playSound } from 'jatui';
 
-// Toggle
-setSoundEnabled(true);
-isSoundEnabled(); // → true
+playSound('confirm');
 ```

package/dist/index.d.ts

@@ -205,7 +205,10 @@ export { glide } from './transitions/glide';
 export type { GlideOrigin, GlideParams } from './transitions/glide';
 export { themeWipe } from './utils/themeWipe';
 export { viewTransition } from './utils/viewTransition';
-export { play as playSound, registerSound, isSoundEnabled, setSoundEnabled } from './utils/sound';
+export { MOTION_LEVELS, DEFAULT_MOTION_LEVEL, MOTION_LEVEL_ATTR, MOTION_DURATIONS, MOTION_LEVEL_SCALE, MOTION_LEVEL_TRAVEL, MOTION_EASING_POINTS, isMotionLevel, parseMotionLevel, prefersReducedMotion, resolveMotionLevel, motionContextFor, getMotionContext, motionDuration, effectiveEasing, setMotionLevel, cubicBezier, motionEasing, motionFade, motionScale, motionSlide, resolveMotionTiming, createMotionLevelStore } from './motion';
+export type { MotionLevel, MotionDurationToken, MotionEasingToken, MotionContext, EasingFn, MotionTransitionParams, MotionTransitionConfig, MotionFadeParams, MotionScaleParams, MotionSlideParams, ResolvedMotionTiming, MotionState, MotionLevelStore, MotionLevelStoreOptions } from './motion';
+export { registerSound, isSoundEnabled, setSoundEnabled } from './utils/sound';
+export * from './sound';
 export { copyText, readClipboardText } from './utils/clipboard';
 export { splitText } from './utils/splitText';
 export type { SplitBy, SplitTextOptions, SplitTextResult } from './utils/splitText';

package/dist/index.js

@@ -245,8 +245,16 @@ export { glide } from './transitions/glide';
 // View Transitions kit
 export { themeWipe } from './utils/themeWipe';
 export { viewTransition } from './utils/viewTransition';
-// Sound kit (functional feedback, opt-in)
-export { play as playSound, registerSound, isSoundEnabled, setSoundEnabled } from './utils/sound';
+// Motion level kit (jatui-j6833): data-motion="calm|standard|lively" scales
+// the --motion-* tokens per surface (styles/motion.css); these helpers,
+// transitions and the store read the same level. Scheme: docs/motion.md.
+export { MOTION_LEVELS, DEFAULT_MOTION_LEVEL, MOTION_LEVEL_ATTR, MOTION_DURATIONS, MOTION_LEVEL_SCALE, MOTION_LEVEL_TRAVEL, MOTION_EASING_POINTS, isMotionLevel, parseMotionLevel, prefersReducedMotion, resolveMotionLevel, motionContextFor, getMotionContext, motionDuration, effectiveEasing, setMotionLevel, cubicBezier, motionEasing, motionFade, motionScale, motionSlide, resolveMotionTiming, createMotionLevelStore } from './motion';
+// Sound kit (jatui-kf62q): one preferences store (off by default, master
+// volume, per-category mute, quiet hours, reduced-motion-aware), semantic
+// sound names, a pure policy and SoundSettings. Discipline: docs/sound.md.
+// playSound comes from ./sound; the legacy flag helpers route through it.
+export { registerSound, isSoundEnabled, setSoundEnabled } from './utils/sound';
+export * from './sound';
 // Clipboard (secure-context aware: execCommand fallback for plain-HTTP origins)
 export { copyText, readClipboardText } from './utils/clipboard';
 // Text utilities

package/dist/motion/easing.d.ts

@@ -0,0 +1,14 @@
+/**
+ * JS easing functions for the `--motion-*` curves, so Svelte transitions
+ * (which interpolate in JS and emit keyframes) move on the same curves the
+ * CSS tokens describe. No dependency: a small cubic-bezier solver.
+ */
+import { type MotionEasingToken } from './level';
+export type EasingFn = (t: number) => number;
+/**
+ * CSS `cubic-bezier(x1, y1, x2, y2)` as a function of progress t ∈ [0, 1].
+ * Newton–Raphson with a bisection fallback; y may overshoot [0, 1] (springs).
+ */
+export declare function cubicBezier(x1: number, y1: number, x2: number, y2: number): EasingFn;
+/** The JS easing for a `--motion-*` easing token. */
+export declare function motionEasing(token: MotionEasingToken): EasingFn;

package/dist/motion/easing.js

@@ -0,0 +1,67 @@
+/**
+ * JS easing functions for the `--motion-*` curves, so Svelte transitions
+ * (which interpolate in JS and emit keyframes) move on the same curves the
+ * CSS tokens describe. No dependency: a small cubic-bezier solver.
+ */
+import { MOTION_EASING_POINTS } from './level';
+/**
+ * CSS `cubic-bezier(x1, y1, x2, y2)` as a function of progress t ∈ [0, 1].
+ * Newton–Raphson with a bisection fallback; y may overshoot [0, 1] (springs).
+ */
+export function cubicBezier(x1, y1, x2, y2) {
+    const cx = 3 * x1;
+    const bx = 3 * (x2 - x1) - cx;
+    const ax = 1 - cx - bx;
+    const cy = 3 * y1;
+    const by = 3 * (y2 - y1) - cy;
+    const ay = 1 - cy - by;
+    const sampleX = (s) => ((ax * s + bx) * s + cx) * s;
+    const sampleY = (s) => ((ay * s + by) * s + cy) * s;
+    const slopeX = (s) => (3 * ax * s + 2 * bx) * s + cx;
+    function solveX(x) {
+        let s = x;
+        for (let i = 0; i < 8; i++) {
+            const err = sampleX(s) - x;
+            if (Math.abs(err) < 1e-6)
+                return s;
+            const d = slopeX(s);
+            if (Math.abs(d) < 1e-6)
+                break;
+            s -= err / d;
+        }
+        let lo = 0;
+        let hi = 1;
+        s = x;
+        while (lo < hi) {
+            const v = sampleX(s);
+            if (Math.abs(v - x) < 1e-6)
+                return s;
+            if (x > v)
+                lo = s;
+            else
+                hi = s;
+            s = (lo + hi) / 2;
+            if (hi - lo < 1e-7)
+                break;
+        }
+        return s;
+    }
+    return (t) => {
+        if (t <= 0)
+            return 0;
+        if (t >= 1)
+            return 1;
+        return sampleY(solveX(t));
+    };
+}
+const cache = new Map();
+/** The JS easing for a `--motion-*` easing token. */
+export function motionEasing(token) {
+    let fn = cache.get(token);
+    if (!fn) {
+        const [x1, y1, x2, y2] = MOTION_EASING_POINTS[token];
+        fn = cubicBezier(x1, y1, x2, y2);
+        cache.set(token, fn);
+    }
+    return fn;
+}

package/dist/motion/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * jatui motion kit — the motion level scheme, token easings, level-aware
+ * transitions and the scroll-reveal action, in one import.
+ * Scheme + level semantics: docs/motion.md.
+ */
+export { MOTION_LEVELS, DEFAULT_MOTION_LEVEL, MOTION_LEVEL_ATTR, MOTION_DURATIONS, MOTION_LEVEL_SCALE, MOTION_LEVEL_TRAVEL, MOTION_EASING_POINTS, isMotionLevel, parseMotionLevel, prefersReducedMotion, resolveMotionLevel, motionContextFor, getMotionContext, motionDuration, effectiveEasing, setMotionLevel } from './level';
+export type { MotionLevel, MotionDurationToken, MotionEasingToken, MotionContext } from './level';
+export { cubicBezier, motionEasing } from './easing';
+export type { EasingFn } from './easing';
+export { motionFade, motionScale, motionSlide, resolveMotionTiming } from './transitions';
+export type { MotionTransitionParams, MotionTransitionConfig, MotionFadeParams, MotionScaleParams, MotionSlideParams, ResolvedMotionTiming } from './transitions';
+export { createMotionLevelStore } from './store';
+export type { MotionState, MotionLevelStore, MotionLevelStoreOptions } from './store';
+export { glide } from '../transitions/glide';
+export type { GlideOrigin, GlideParams } from '../transitions/glide';
+export { reveal, REVEAL_HIDDEN_CLASS, REVEAL_BASE_CLASS } from '../actions/reveal';
+export type { RevealOptions, RevealVariant } from '../actions/reveal';

package/dist/motion/index.js

@@ -0,0 +1,11 @@
+/**
+ * jatui motion kit — the motion level scheme, token easings, level-aware
+ * transitions and the scroll-reveal action, in one import.
+ * Scheme + level semantics: docs/motion.md.
+ */
+export { MOTION_LEVELS, DEFAULT_MOTION_LEVEL, MOTION_LEVEL_ATTR, MOTION_DURATIONS, MOTION_LEVEL_SCALE, MOTION_LEVEL_TRAVEL, MOTION_EASING_POINTS, isMotionLevel, parseMotionLevel, prefersReducedMotion, resolveMotionLevel, motionContextFor, getMotionContext, motionDuration, effectiveEasing, setMotionLevel } from './level';
+export { cubicBezier, motionEasing } from './easing';
+export { motionFade, motionScale, motionSlide, resolveMotionTiming } from './transitions';
+export { createMotionLevelStore } from './store';
+export { glide } from '../transitions/glide';
+export { reveal, REVEAL_HIDDEN_CLASS, REVEAL_BASE_CLASS } from '../actions/reveal';

package/dist/motion/level.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Motion level — a per-surface dial for how much the UI moves.
+ *
+ * A host sets `data-motion="calm|standard|lively"` on `<html>` or on any
+ * subtree. `styles/motion.css` rescales the `--motion-*` duration and travel
+ * tokens under that attribute, and the JS side (transitions, `use:reveal`)
+ * reads the same level through `getMotionContext(node)` so CSS and JS motion
+ * agree. The nearest `[data-motion]` ancestor wins; no attribute = standard.
+ *
+ *   calm      durations × 0.75, travel 8px, springs flattened to glide,
+ *             ambient/decorative motion OFF. Dense tools, dashboards.
+ *   standard  the tokens as written. The default.
+ *   lively    durations × 1.25, travel 24px. Marketing, onboarding, empty
+ *             states — surfaces whose job is to feel alive.
+ *
+ * `prefers-reduced-motion: reduce` always wins over every level: durations
+ * and travel collapse to 0, springs and ambient motion are off. A level can
+ * never opt a reduced-motion user back into motion.
+ *
+ * The numbers here MUST match styles/motion.css — tests/unit/motionLevel.test.ts
+ * parses the stylesheet and fails on drift.
+ */
+export type MotionLevel = 'calm' | 'standard' | 'lively';
+/** Duration tokens, named after their `--motion-<name>` custom property. */
+export type MotionDurationToken = 'instant' | 'fast' | 'enter' | 'move';
+/** Easing tokens, named after their `--motion-<name>` custom property. */
+export type MotionEasingToken = 'glide' | 'spring' | 'standard';
+export declare const MOTION_LEVELS: readonly MotionLevel[];
+export declare const DEFAULT_MOTION_LEVEL: MotionLevel;
+/** The attribute a host sets on `<html>` or any subtree. */
+export declare const MOTION_LEVEL_ATTR = "data-motion";
+/** Standard-level durations in ms — the `--motion-*-base` tokens. */
+export declare const MOTION_DURATIONS: Readonly<Record<MotionDurationToken, number>>;
+/** Duration multiplier per level — `--motion-scale`. */
+export declare const MOTION_LEVEL_SCALE: Readonly<Record<MotionLevel, number>>;
+/** Entrance travel distance in px per level — `--motion-travel`. */
+export declare const MOTION_LEVEL_TRAVEL: Readonly<Record<MotionLevel, number>>;
+/** Cubic-bezier control points for the easing tokens (same as motion.css). */
+export declare const MOTION_EASING_POINTS: Readonly<Record<MotionEasingToken, readonly [number, number, number, number]>>;
+/** Everything a piece of motion needs to know about where it is running. */
+export interface MotionContext {
+    /** The level the surface asked for (nearest `[data-motion]`, else standard). */
+    level: MotionLevel;
+    /** `prefers-reduced-motion: reduce` — overrides the level when true. */
+    reduced: boolean;
+    /** Duration multiplier: the level's scale, or 0 when reduced. */
+    scale: number;
+    /** Travel distance in px: the level's travel, or 0 when reduced. */
+    travel: number;
+    /** Whether ambient/decorative motion may run (standard + lively, never reduced). */
+    ambient: boolean;
+    /** Whether spring (overshoot) easing may run (standard + lively, never reduced). */
+    spring: boolean;
+}
+export declare function isMotionLevel(value: unknown): value is MotionLevel;
+/** Coerce any attribute/storage value to a level; unknown values become the default. */
+export declare function parseMotionLevel(value: unknown, fallback?: MotionLevel): MotionLevel;
+/** True when the user asked the OS for reduced motion. SSR-safe (false). */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * The level in force for `node`: its nearest `[data-motion]` ancestor
+ * (inclusive), else `<html>`'s, else standard. A `[data-motion]` with an
+ * unknown value counts as standard rather than being skipped, so a typo
+ * fails visibly-safe instead of silently inheriting `lively` from above.
+ */
+export declare function resolveMotionLevel(node?: Element | null): MotionLevel;
+/** Build a context from a level + reduced flag (pure — no DOM). */
+export declare function motionContextFor(level: MotionLevel, reduced?: boolean): MotionContext;
+/** The motion context in force for `node` (or the document when omitted). */
+export declare function getMotionContext(node?: Element | null): MotionContext;
+/**
+ * A token duration (or a standard-level ms value) scaled for a context.
+ * Returns 0 under reduced motion.
+ *
+ *   motionDuration('enter', ctx)  // 200 standard, 150 calm, 250 lively
+ *   motionDuration(400, ctx)      // 300 calm
+ */
+export declare function motionDuration(token: MotionDurationToken | number, ctx: MotionContext): number;
+/**
+ * The easing token actually allowed in a context: spring degrades to glide
+ * wherever springs are off (calm, reduced). Other tokens pass through.
+ */
+export declare function effectiveEasing(token: MotionEasingToken, ctx: MotionContext): MotionEasingToken;
+/**
+ * Set the level on a surface (default `<html>`). Passing `null` removes the
+ * attribute so the surface inherits again. No-op without a DOM.
+ */
+export declare function setMotionLevel(level: MotionLevel | null, target?: Element | null): void;

package/dist/motion/level.js

@@ -0,0 +1,132 @@
+/**
+ * Motion level — a per-surface dial for how much the UI moves.
+ *
+ * A host sets `data-motion="calm|standard|lively"` on `<html>` or on any
+ * subtree. `styles/motion.css` rescales the `--motion-*` duration and travel
+ * tokens under that attribute, and the JS side (transitions, `use:reveal`)
+ * reads the same level through `getMotionContext(node)` so CSS and JS motion
+ * agree. The nearest `[data-motion]` ancestor wins; no attribute = standard.
+ *
+ *   calm      durations × 0.75, travel 8px, springs flattened to glide,
+ *             ambient/decorative motion OFF. Dense tools, dashboards.
+ *   standard  the tokens as written. The default.
+ *   lively    durations × 1.25, travel 24px. Marketing, onboarding, empty
+ *             states — surfaces whose job is to feel alive.
+ *
+ * `prefers-reduced-motion: reduce` always wins over every level: durations
+ * and travel collapse to 0, springs and ambient motion are off. A level can
+ * never opt a reduced-motion user back into motion.
+ *
+ * The numbers here MUST match styles/motion.css — tests/unit/motionLevel.test.ts
+ * parses the stylesheet and fails on drift.
+ */
+export const MOTION_LEVELS = ['calm', 'standard', 'lively'];
+export const DEFAULT_MOTION_LEVEL = 'standard';
+/** The attribute a host sets on `<html>` or any subtree. */
+export const MOTION_LEVEL_ATTR = 'data-motion';
+/** Standard-level durations in ms — the `--motion-*-base` tokens. */
+export const MOTION_DURATIONS = {
+    instant: 80,
+    fast: 150,
+    enter: 200,
+    move: 300
+};
+/** Duration multiplier per level — `--motion-scale`. */
+export const MOTION_LEVEL_SCALE = {
+    calm: 0.75,
+    standard: 1,
+    lively: 1.25
+};
+/** Entrance travel distance in px per level — `--motion-travel`. */
+export const MOTION_LEVEL_TRAVEL = {
+    calm: 8,
+    standard: 16,
+    lively: 24
+};
+/** Cubic-bezier control points for the easing tokens (same as motion.css). */
+export const MOTION_EASING_POINTS = {
+    glide: [0.16, 1, 0.3, 1],
+    spring: [0.34, 1.56, 0.64, 1],
+    standard: [0.2, 0, 0, 1]
+};
+export function isMotionLevel(value) {
+    return typeof value === 'string' && MOTION_LEVELS.includes(value);
+}
+/** Coerce any attribute/storage value to a level; unknown values become the default. */
+export function parseMotionLevel(value, fallback = DEFAULT_MOTION_LEVEL) {
+    if (typeof value !== 'string')
+        return fallback;
+    const v = value.trim().toLowerCase();
+    return isMotionLevel(v) ? v : fallback;
+}
+/** True when the user asked the OS for reduced motion. SSR-safe (false). */
+export function prefersReducedMotion() {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function')
+        return false;
+    try {
+        return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The level in force for `node`: its nearest `[data-motion]` ancestor
+ * (inclusive), else `<html>`'s, else standard. A `[data-motion]` with an
+ * unknown value counts as standard rather than being skipped, so a typo
+ * fails visibly-safe instead of silently inheriting `lively` from above.
+ */
+export function resolveMotionLevel(node) {
+    const el = (node ?? (typeof document !== 'undefined' ? document.documentElement : null));
+    if (!el || typeof el.closest !== 'function')
+        return DEFAULT_MOTION_LEVEL;
+    const host = el.closest(`[${MOTION_LEVEL_ATTR}]`);
+    return host ? parseMotionLevel(host.getAttribute(MOTION_LEVEL_ATTR)) : DEFAULT_MOTION_LEVEL;
+}
+/** Build a context from a level + reduced flag (pure — no DOM). */
+export function motionContextFor(level, reduced = false) {
+    const lively = level !== 'calm';
+    return {
+        level,
+        reduced,
+        scale: reduced ? 0 : MOTION_LEVEL_SCALE[level],
+        travel: reduced ? 0 : MOTION_LEVEL_TRAVEL[level],
+        ambient: !reduced && lively,
+        spring: !reduced && lively
+    };
+}
+/** The motion context in force for `node` (or the document when omitted). */
+export function getMotionContext(node) {
+    return motionContextFor(resolveMotionLevel(node), prefersReducedMotion());
+}
+/**
+ * A token duration (or a standard-level ms value) scaled for a context.
+ * Returns 0 under reduced motion.
+ *
+ *   motionDuration('enter', ctx)  // 200 standard, 150 calm, 250 lively
+ *   motionDuration(400, ctx)      // 300 calm
+ */
+export function motionDuration(token, ctx) {
+    const base = typeof token === 'number' ? token : MOTION_DURATIONS[token];
+    return Math.round(Math.max(0, base) * ctx.scale);
+}
+/**
+ * The easing token actually allowed in a context: spring degrades to glide
+ * wherever springs are off (calm, reduced). Other tokens pass through.
+ */
+export function effectiveEasing(token, ctx) {
+    return token === 'spring' && !ctx.spring ? 'glide' : token;
+}
+/**
+ * Set the level on a surface (default `<html>`). Passing `null` removes the
+ * attribute so the surface inherits again. No-op without a DOM.
+ */
+export function setMotionLevel(level, target) {
+    const el = target ?? (typeof document !== 'undefined' ? document.documentElement : null);
+    if (!el)
+        return;
+    if (level === null)
+        el.removeAttribute(MOTION_LEVEL_ATTR);
+    else
+        el.setAttribute(MOTION_LEVEL_ATTR, level);
+}

package/dist/motion/store.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Motion-level store — a Svelte store (subscribe contract, usable as
+ * `$motion`) that owns a surface's `data-motion` attribute, optionally
+ * persists the user's choice, and tracks `prefers-reduced-motion` live.
+ *
+ *   const motion = createMotionLevelStore({ storageKey: 'app.motion' })
+ *   motion.set('calm')                 // writes data-motion="calm" on <html>
+ *   $motion.level / $motion.reduced    // reactive in components
+ *   $motion.effective                  // 'reduced' when the OS asks, else level
+ *
+ * Plain store (no runes), so it works in .ts, in SSR (no DOM access until a
+ * method or subscriber needs it) and under node:test.
+ */
+import { type MotionLevel } from './level';
+export interface MotionState {
+    /** The level chosen for the surface. */
+    level: MotionLevel;
+    /** `prefers-reduced-motion: reduce` is on — every level yields to it. */
+    reduced: boolean;
+    /** What actually runs: 'reduced' when reduced, else the level. */
+    effective: MotionLevel | 'reduced';
+}
+export interface MotionLevelStoreOptions {
+    /** Element that carries `data-motion`. Default `document.documentElement`, resolved lazily. */
+    target?: Element | (() => Element | null) | null;
+    /** Persist the chosen level in localStorage under this key. Omit = no persistence. */
+    storageKey?: string;
+    /** Level when nothing is stored and the target has no attribute. Default 'standard'. */
+    initial?: MotionLevel;
+}
+export interface MotionLevelStore {
+    subscribe(run: (state: MotionState) => void): () => void;
+    /** Set the level (writes the attribute, persists when configured). */
+    set(level: MotionLevel): void;
+    /** Clear the stored choice and fall back to `initial`. */
+    reset(): void;
+    /** Current state, without subscribing. */
+    get(): MotionState;
+}
+export declare function createMotionLevelStore(options?: MotionLevelStoreOptions): MotionLevelStore;

package/dist/motion/store.js

@@ -0,0 +1,132 @@
+/**
+ * Motion-level store — a Svelte store (subscribe contract, usable as
+ * `$motion`) that owns a surface's `data-motion` attribute, optionally
+ * persists the user's choice, and tracks `prefers-reduced-motion` live.
+ *
+ *   const motion = createMotionLevelStore({ storageKey: 'app.motion' })
+ *   motion.set('calm')                 // writes data-motion="calm" on <html>
+ *   $motion.level / $motion.reduced    // reactive in components
+ *   $motion.effective                  // 'reduced' when the OS asks, else level
+ *
+ * Plain store (no runes), so it works in .ts, in SSR (no DOM access until a
+ * method or subscriber needs it) and under node:test.
+ */
+import { DEFAULT_MOTION_LEVEL, parseMotionLevel, prefersReducedMotion, resolveMotionLevel, setMotionLevel } from './level';
+function stateOf(level, reduced) {
+    return { level, reduced, effective: reduced ? 'reduced' : level };
+}
+function readStorage(key) {
+    if (!key)
+        return null;
+    try {
+        return typeof localStorage === 'undefined' ? null : localStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+function writeStorage(key, value) {
+    if (!key)
+        return;
+    try {
+        if (typeof localStorage === 'undefined')
+            return;
+        if (value === null)
+            localStorage.removeItem(key);
+        else
+            localStorage.setItem(key, value);
+    }
+    catch {
+        // storage blocked (private mode, quota) — the attribute still applies
+    }
+}
+export function createMotionLevelStore(options = {}) {
+    const { storageKey } = options;
+    const initial = options.initial ?? DEFAULT_MOTION_LEVEL;
+    const subscribers = new Set();
+    let state = null;
+    let stopMedia = null;
+    function target() {
+        const t = options.target;
+        if (typeof t === 'function')
+            return t();
+        if (t)
+            return t;
+        return typeof document !== 'undefined' ? document.documentElement : null;
+    }
+    function load() {
+        if (state)
+            return state;
+        const stored = readStorage(storageKey);
+        const el = target();
+        let level;
+        if (stored !== null) {
+            level = parseMotionLevel(stored, initial);
+            setMotionLevel(level, el);
+        }
+        else if (el?.hasAttribute?.('data-motion')) {
+            level = resolveMotionLevel(el);
+        }
+        else {
+            level = initial;
+        }
+        state = stateOf(level, prefersReducedMotion());
+        return state;
+    }
+    function emit(next) {
+        state = next;
+        for (const run of subscribers)
+            run(next);
+    }
+    function watchReducedMotion() {
+        if (stopMedia || typeof window === 'undefined' || typeof window.matchMedia !== 'function')
+            return;
+        let mql;
+        try {
+            mql = window.matchMedia('(prefers-reduced-motion: reduce)');
+        }
+        catch {
+            return;
+        }
+        const onChange = (e) => {
+            const cur = load();
+            if (cur.reduced !== e.matches)
+                emit(stateOf(cur.level, e.matches));
+        };
+        if (typeof mql.addEventListener === 'function') {
+            mql.addEventListener('change', onChange);
+            stopMedia = () => mql.removeEventListener('change', onChange);
+        }
+        else if (typeof mql.addListener === 'function') {
+            mql.addListener(onChange);
+            stopMedia = () => mql.removeListener(onChange);
+        }
+    }
+    return {
+        subscribe(run) {
+            subscribers.add(run);
+            if (subscribers.size === 1)
+                watchReducedMotion();
+            run(load());
+            return () => {
+                subscribers.delete(run);
+                if (subscribers.size === 0 && stopMedia) {
+                    stopMedia();
+                    stopMedia = null;
+                }
+            };
+        },
+        set(level) {
+            const next = parseMotionLevel(level, initial);
+            setMotionLevel(next, target());
+            writeStorage(storageKey, next);
+            emit(stateOf(next, load().reduced));
+        },
+        reset() {
+            writeStorage(storageKey, null);
+            setMotionLevel(initial, target());
+            emit(stateOf(initial, load().reduced));
+        },
+        get: load
+    };
+}