@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/src/recipes/text-roll/create-text-roll.ts

@@ -0,0 +1,137 @@
+import { gsap, SplitText, registerMotion } from '../../core/gsap';
+import { entrances } from '../../core/reduced';
+import { TIMING } from '../../core/timing';
+import { inert, warnOnce, type Instance } from '../../core/types';
+import { shows, thresholds } from '../../core/visible';
+
+/*
+ * Siena's slot title: every letter is a little reel — its face and a copy
+ * under it scroll up one height per turn, 8–14 turns picked at random, in a
+ * paused timeline. play() pushes all those timelines from 0 to 1 in 2 s
+ * (expo.out, 40 ms apart in random order), so the letters spin fast and settle
+ * one by one on the same letter. Optionally it plays again every 6 s while
+ * visible and the page is not scrolling (it waits 1 s of calm).
+ */
+
+export interface TextRollOptions {
+  duration?: number;
+  stagger?: number;
+  /** [min, max] repeats of each letter's turn (Siena: 8–14). */
+  turns?: readonly [number, number];
+  /** 'load' (default) after `delay`; 'scroll' when it shows; 'hover'; 'manual'. */
+  trigger?: 'load' | 'scroll' | 'hover' | 'manual';
+  delay?: number;
+  /** Replay every n ms while visible and not scrolling (Siena: 6000). 0: off. */
+  interval?: number;
+}
+
+export interface TextRollInstance extends Instance {
+  play(): void;
+  readonly timelines: gsap.core.Timeline[];
+}
+
+export function createTextRoll(el: HTMLElement | null, options: TextRollOptions = {}): TextRollInstance {
+  if (!el) {
+    warnOnce('text-roll: missing element');
+    return inert({ play() {}, timelines: [] });
+  }
+  const t = TIMING.textRoll;
+  const { duration = t.duration, stagger = t.stagger, turns = t.turns, trigger = 'load', delay = 0, interval = 0 } = options;
+  if (!entrances()) {
+    el.dataset.mkReady = '';
+    return {
+      play() {},
+      timelines: [],
+      destroy() {
+        delete el.dataset.mkReady;
+      },
+    };
+  }
+  registerMotion();
+  const split = SplitText.create(el, { type: 'words,chars', wordsClass: 'mk-roll-word', charsClass: 'mk-roll-char', aria: 'auto' });
+  const timelines = (split.chars as HTMLElement[]).map((char) => {
+    const letter = char.textContent ?? '';
+    const face = document.createElement('span');
+    face.className = 'mk-roll-face';
+    face.textContent = letter;
+    const copy = face.cloneNode(true);
+    char.replaceChildren(face, copy);
+    const timeline = gsap.timeline({ paused: true });
+    timeline.to([face, copy], { yPercent: '-=100', repeat: gsap.utils.random(turns[0], turns[1], 1), ease: 'none', duration: 1 });
+    return timeline;
+  });
+
+  let envelope: gsap.core.Tween | null = null;
+  const play = () => {
+    envelope?.kill();
+    envelope = gsap.to(timelines, {
+      progress: 1,
+      duration,
+      ease: 'expo.out',
+      stagger: { each: stagger, ease: 'none', from: 'random' },
+      onComplete: () => {
+        gsap.set(timelines, { progress: 0 });
+      },
+    });
+  };
+
+  const cleanups: Array<() => void> = [];
+  let visible = true;
+  let scrolling = false;
+  if (interval > 0 || trigger === 'scroll') {
+    if (typeof IntersectionObserver === 'function') {
+      visible = false;
+      let played = false;
+      const observer = new IntersectionObserver(
+        ([entry]) => {
+          visible = Boolean(entry?.isIntersecting);
+          if (entry && shows(entry, 0.5) && trigger === 'scroll' && !played) {
+            played = true;
+            play();
+          }
+        },
+        { threshold: thresholds(0.5) },
+      );
+      observer.observe(el);
+      cleanups.push(() => observer.disconnect());
+    }
+  }
+  if (interval > 0) {
+    let quiet: ReturnType<typeof setTimeout> | undefined;
+    const onScroll = () => {
+      scrolling = true;
+      clearTimeout(quiet);
+      quiet = setTimeout(() => (scrolling = false), t.quietMs);
+    };
+    addEventListener('scroll', onScroll, { passive: true });
+    const timer = setInterval(() => {
+      if (visible && !scrolling) play();
+    }, interval);
+    cleanups.push(() => {
+      removeEventListener('scroll', onScroll);
+      clearInterval(timer);
+      clearTimeout(quiet);
+    });
+  }
+  if (trigger === 'hover') {
+    el.addEventListener('pointerenter', play);
+    cleanups.push(() => el.removeEventListener('pointerenter', play));
+  }
+  if (trigger === 'load') {
+    const call = gsap.delayedCall(delay, play);
+    cleanups.push(() => call.kill());
+  }
+  el.dataset.mkReady = '';
+
+  return {
+    play,
+    timelines,
+    destroy() {
+      for (const cleanup of cleanups.splice(0)) cleanup();
+      envelope?.kill();
+      timelines.forEach((timeline) => timeline.kill());
+      split.revert();
+      delete el.dataset.mkReady;
+    },
+  };
+}

package/src/recipes/text-roll/text-roll.css

@@ -0,0 +1,21 @@
+/* text-roll — Siena's slot title: each letter is a reel (its face and a copy below), clipped to one line. */
+.mk-roll-word {
+  white-space: nowrap;
+}
+
+.mk-roll-char {
+  position: relative;
+  display: inline-block;
+  overflow: clip;
+  vertical-align: top;
+}
+
+.mk-roll-face {
+  display: block;
+}
+
+.mk-roll-face + .mk-roll-face {
+  position: absolute;
+  top: 100%;
+  left: 0;
+}

package/src/recipes/ticket-menu/README.md

@@ -0,0 +1,24 @@
+# ticket-menu
+
+Menú boleto de Siena sobre menu: recorte, filas escalonadas, teclado y foco.
+
+```html
+<button data-mk-open="sections">Secciones</button>
+<dialog id="sections" class="mk-dialog mk-menu" data-mk="ticket-menu" aria-label="Secciones">
+  <button data-mk-item>Archivo</button><button data-mk-item>Contacto</button>
+</dialog>
+```
+
+```ts
+import { createTicketMenu } from '@yewdiel21/motion-kit';
+import { useTicketMenu } from '@yewdiel21/motion-kit/react';
+import '@yewdiel21/motion-kit/css';
+const instance = createTicketMenu(root);
+instance.destroy();
+```
+
+`createTicketMenu(dialog, MenuOptions)` reutiliza el motor de menú. También `<mk-menu ticket>` y `<Menu.Root ticket>`. Apertura por clip-path .9 s; filas desde yPercent 150, 1.1 s, stagger .02. `open(origin?)`, `close()`, `toggle()`, `items`, `isOpen`. Origen: Siena `siena.menu.expand` y `siena.menu.details`; adaptación de sus grid rows a un diálogo local.
+
+Vanilla declarativo: `autoInit(root)`. React: `useTicketMenu(ref, options, deps)` devuelve una ref a la instancia; se destruye al desmontar. Con movimiento reducido no se ejecuta movimiento decorativo. `destroy()` restaura atributos y estilos y quita listeners, observers y nodos generados.
+
+Desde 0.8.0. Parámetros investigados en `REA - Dousan OFFFICE Siena/`; implementación propia, sin código ni assets de esos sitios.

package/src/recipes/ticket-menu/create-ticket-menu.ts

@@ -0,0 +1,6 @@
+import { createMenu, type MenuInstance, type MenuOptions } from '../../components/menu/engine';
+
+export type TicketMenuOptions = Omit<MenuOptions, 'ticket'>;
+export type TicketMenuInstance = MenuInstance;
+export const createTicketMenu = (root: HTMLElement | null, options: TicketMenuOptions = {}): TicketMenuInstance =>
+  createMenu(root, { ...options, ticket: true });

package/src/recipes/words/README.md

@@ -0,0 +1,43 @@
+# words
+
+Cada palabra (o letra) crece desde la base con rebote: `scaleY 0 → 1`, 100 ms entre palabras (60 ms entre letras).
+
+Origen: spencergabor.com — titulares del Hero.
+
+## Vanilla / Astro
+
+```html
+<h2 data-mk="words">Selected <span class="muted">work.</span></h2>
+<span data-mk="fit-text words" data-mk-by="chars" data-mk-trigger="load">Portfolio</span>
+```
+
+Con `autoInit()` (de `@yewdiel21/motion-kit/auto`) las opciones van como `data-mk-<opción>` en kebab-case. Sin `autoInit`: `createWords(el, opciones)`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLHeadingElement>(null);
+const words = useWords(ref, { trigger: 'scroll' });
+// cambio de idioma: words.current?.replace(() => (ref.current!.textContent = t('title')))
+```
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `by` | `'words'` | 'words' o 'chars' |
+| `trigger` | `'scroll'` | 'scroll' (al entrar en pantalla), 'load' o 'manual' |
+| `start` | `'top 88%'` | Inicio del ScrollTrigger |
+| `duration` | `.8` | Segundos |
+| `stagger` | `.1 / .06` | Entre palabras / letras |
+| `delay` | `0` | Segundos (0.2 por defecto con `load`) |
+
+## Controles
+
+`reveal(delay?)`, `replace(mutate)`, `destroy()`
+
+## CSS
+
+Los titulares (`h1`–`h6`) reciben `aria-label` y las piezas `aria-hidden`; otros elementos se leen tal cual. Si el elemento no está renderizado al crear (dentro de un `<dialog>` cerrado), se divide al llamar `reveal()`.
+
+Con `prefers-reduced-motion: reduce` la receta deja el contenido en su estado final, sin animar.

package/src/recipes/words/create-words.ts

@@ -0,0 +1,114 @@
+import { gsap, ELASTIC, ScrollTrigger, SplitText, registerMotion } from '../../core/gsap';
+import { entrances } from '../../core/reduced';
+import { inert, warnOnce, type Instance } from '../../core/types';
+
+/*
+ * spencergabor.com headlines: every word (or letter) grows from its baseline,
+ * scaleY 0 → 1 and 25 % up → 0, elastic, 100 ms apart (60 ms for letters).
+ */
+
+export interface WordsOptions {
+  by?: 'words' | 'chars';
+  /** 'scroll' plays when the element enters the viewport; 'load' plays now; 'manual' waits for reveal(). */
+  trigger?: 'scroll' | 'load' | 'manual';
+  /** ScrollTrigger start for trigger 'scroll'. */
+  start?: string;
+  duration?: number;
+  stagger?: number;
+  delay?: number;
+}
+
+export interface WordsInstance extends Instance {
+  /** Play the entrance (splits first if needed). */
+  reveal(delay?: number): void;
+  /** Change the text (e.g. language switch) and replay the entrance. */
+  replace(mutate: () => void): void;
+}
+
+const HIDDEN = { scaleY: 0, yPercent: 25 };
+
+export function createWords(el: HTMLElement | null, options: WordsOptions = {}): WordsInstance {
+  if (!el) {
+    warnOnce('words: missing element');
+    return inert({ reveal() {}, replace(mutate: () => void) { mutate(); } });
+  }
+  const letters = options.by === 'chars';
+  const o = {
+    trigger: 'scroll' as const,
+    start: 'top 88%',
+    duration: 0.8,
+    stagger: letters ? 0.06 : 0.1,
+    delay: 0,
+    ...options,
+  };
+
+  registerMotion();
+  let split: SplitText | null = null;
+  let scroll: ScrollTrigger | null = null;
+  let destroyed = false;
+
+  const units = () => (split ? ((letters ? split.chars : split.words) as HTMLElement[]) : []);
+  // SplitText needs rendered text: a closed <dialog> or display:none parent loses word spaces.
+  const rendered = () => el.getClientRects().length > 0;
+
+  const prepare = () => {
+    split = SplitText.create(el, {
+      type: letters ? 'chars' : 'words',
+      charsClass: 'mk-w',
+      wordsClass: 'mk-w',
+      // Headings get an aria-label; inline elements stay readable as they are.
+      aria: /^H[1-6]$/.test(el.tagName) ? 'auto' : 'none',
+      smartWrap: letters,
+    });
+    const list = units();
+    if (list.length) gsap.set(list, { transformOrigin: '50% 100%', ...HIDDEN });
+  };
+
+  const release = () => {
+    if (!split) return;
+    gsap.killTweensOf(units());
+    split.revert();
+    split = null;
+  };
+
+  function reveal(delay = o.delay) {
+    if (destroyed) return;
+    scroll?.kill();
+    scroll = null;
+    if (!entrances()) return;
+    if (!split) prepare();
+    const list = units();
+    if (!list.length) return;
+    gsap.killTweensOf(list);
+    gsap.fromTo(list, HIDDEN, { scaleY: 1, yPercent: 0, duration: o.duration, ease: ELASTIC, stagger: o.stagger, delay });
+  }
+
+  function replace(mutate: () => void) {
+    release();
+    mutate();
+    if (entrances() && rendered()) {
+      prepare();
+      reveal(0);
+    }
+  }
+
+  if (entrances() && rendered()) prepare();
+  el.dataset.mkReady = '';
+
+  if (o.trigger === 'load') reveal(o.delay || 0.2);
+  else if (o.trigger === 'scroll' && entrances()) {
+    scroll = ScrollTrigger.create({ trigger: el, start: o.start, end: 'max', once: true, onEnter: () => reveal() });
+  }
+
+  return {
+    reveal,
+    replace,
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      scroll?.kill();
+      release();
+      delete el.dataset.mkReady;
+    },
+  };
+}

package/src/theme/css-format.ts

@@ -0,0 +1,32 @@
+import { ROLES, type Role } from './presets';
+
+export type Palette = Record<Role, string>;
+export interface ThemePalettes {
+  light: Palette;
+  dark: Palette;
+}
+
+function block(selectors: string[], scheme: 'light' | 'dark', palette: Palette, indent = '') {
+  const lines = [`${indent}${selectors.join(`,\n${indent}`)} {`, `${indent}  color-scheme: ${scheme};`];
+  for (const role of ROLES) lines.push(`${indent}  --md-sys-color-${role}: ${palette[role]};`);
+  lines.push(`${indent}}`);
+  return lines.join('\n');
+}
+
+/**
+ * A theme's stylesheet: light on `[data-mk-theme="<id>"]`, dark when the element
+ * or an ancestor has `data-mk-mode="dark"`, and dark under the system's dark
+ * scheme unless the page forces light. Same format as css/themes/*.css
+ * (scripts/import-themes.mjs keeps a copy of this function; a test checks they agree).
+ */
+export function themeCss(id: string, { light, dark }: ThemePalettes): string {
+  const self = `[data-mk-theme="${id}"]`;
+  return [
+    block([self], 'light', light),
+    block([`${self}[data-mk-mode="dark"]`, `[data-mk-mode="dark"] ${self}`], 'dark', dark),
+    '@media (prefers-color-scheme: dark) {',
+    block([`:root:not([data-mk-mode="light"])${self}`, `:root:not([data-mk-mode="light"]) ${self}`], 'dark', dark, '  '),
+    '}',
+    '',
+  ].join('\n');
+}

package/src/theme/generate.ts

@@ -0,0 +1,72 @@
+import {
+  Hct,
+  MaterialDynamicColors,
+  SchemeContent,
+  SchemeExpressive,
+  SchemeFidelity,
+  SchemeMonochrome,
+  SchemeNeutral,
+  SchemeTonalSpot,
+  SchemeVibrant,
+  argbFromHex,
+  hexFromArgb,
+} from '@material/material-color-utilities';
+import { ROLES, type Role } from './presets';
+import { themeCss, type Palette, type ThemePalettes } from './css-format';
+import { registerTheme, setTheme } from './theme';
+
+/*
+ * Material 3 palettes from any colour, in the same 37 roles as Stepbro's themes.
+ * Needs the optional peer @material/material-color-utilities ^0.3.0
+ * (0.4.0 publishes ESM imports without extensions that Node cannot load).
+ */
+
+export type ThemeVariant = 'tonal-spot' | 'vibrant' | 'expressive' | 'neutral' | 'content' | 'fidelity' | 'monochrome';
+
+export interface GenerateOptions {
+  variant?: ThemeVariant;
+  /** -1 (reduced) … 0 (standard) … 1 (high). */
+  contrast?: number;
+}
+
+const SCHEMES = {
+  'tonal-spot': SchemeTonalSpot,
+  vibrant: SchemeVibrant,
+  expressive: SchemeExpressive,
+  neutral: SchemeNeutral,
+  content: SchemeContent,
+  fidelity: SchemeFidelity,
+  monochrome: SchemeMonochrome,
+} as const;
+
+const camel = (role: string) => role.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+type Dynamic = { getArgb(scheme: unknown): number };
+
+export function generateTheme(seed: string, { variant = 'tonal-spot', contrast = 0 }: GenerateOptions = {}): ThemePalettes {
+  if (!/^#?[0-9a-f]{6}$/i.test(seed)) throw new Error(`generateTheme: seed must be a #rrggbb colour (got "${seed}")`);
+  const Scheme = SCHEMES[variant];
+  if (!Scheme) throw new Error(`generateTheme: unknown variant "${variant}"`);
+  const source = Hct.fromInt(argbFromHex(seed.startsWith('#') ? seed : `#${seed}`));
+  const palette = (dark: boolean): Palette => {
+    const scheme = new Scheme(source, dark, contrast);
+    const colors = MaterialDynamicColors as unknown as Record<string, Dynamic>;
+    return Object.fromEntries(ROLES.map((role) => [role, hexFromArgb(colors[camel(role)].getArgb(scheme))])) as Record<Role, string>;
+  };
+  return { light: palette(false), dark: palette(true) };
+}
+
+export { themeCss };
+
+/** Generate a theme from `seed`, inject it as a <style>, register and select it. */
+export function applyTheme(seed: string, { id = 'custom', ...options }: GenerateOptions & { id?: string } = {}) {
+  const css = themeCss(id, generateTheme(seed, options));
+  let style = document.querySelector<HTMLStyleElement>(`style[data-mk-theme-style="${id}"]`);
+  if (!style) {
+    style = document.createElement('style');
+    style.dataset.mkThemeStyle = id;
+    document.head.append(style);
+  }
+  style.textContent = css;
+  registerTheme(id);
+  return setTheme(id);
+}

package/src/theme/index.ts

@@ -0,0 +1,15 @@
+export {
+  initTheme,
+  setTheme,
+  setMode,
+  getTheme,
+  registerTheme,
+  themeHeadScript,
+  MK_THEME_HEAD_SCRIPT,
+  THEME_EVENT,
+  type ThemeMode,
+  type ThemeState,
+  type InitThemeOptions,
+} from './theme';
+export { THEMES, ROLES, DEFAULT_THEME, type ThemeId, type ThemePreset, type Role } from './presets';
+export { themeCss, type Palette, type ThemePalettes } from './css-format';

package/src/theme/presets.ts

@@ -0,0 +1,79 @@
+// Generated by scripts/import-themes.mjs from the Stepbro replication kit; do not edit.
+
+/** The 37 Material 3 colour roles every theme defines (`--md-sys-color-<role>`). */
+export const ROLES = [
+  'background',
+  'on-background',
+  'surface',
+  'surface-dim',
+  'surface-bright',
+  'surface-container-lowest',
+  'surface-container-low',
+  'surface-container',
+  'surface-container-high',
+  'surface-container-highest',
+  'on-surface',
+  'surface-variant',
+  'on-surface-variant',
+  'inverse-surface',
+  'inverse-on-surface',
+  'outline',
+  'outline-variant',
+  'shadow',
+  'scrim',
+  'surface-tint',
+  'primary',
+  'on-primary',
+  'primary-container',
+  'on-primary-container',
+  'inverse-primary',
+  'secondary',
+  'on-secondary',
+  'secondary-container',
+  'on-secondary-container',
+  'tertiary',
+  'on-tertiary',
+  'tertiary-container',
+  'on-tertiary-container',
+  'error',
+  'on-error',
+  'error-container',
+  'on-error-container',
+] as const;
+export type Role = (typeof ROLES)[number];
+
+export interface ThemePreset {
+  readonly id: string;
+  readonly name: string;
+  /** Hidden from Stepbro's own picker (kept in its code). */
+  readonly hidden: boolean;
+  /** Modes with their own palette. OLED is dark-only and uses Black in light mode. */
+  readonly modes: readonly ('light' | 'dark')[];
+  /** Representative colour (dark surface-tint): swatch and generator seed. */
+  readonly seed: string;
+}
+
+export const THEMES = [
+  { id: 'black', name: 'Black', hidden: true, modes: ['light', 'dark'], seed: '#b4c7ed' },
+  { id: 'blue', name: 'Blue', hidden: false, modes: ['light', 'dark'], seed: '#b3c5ff' },
+  { id: 'purple', name: 'Purple', hidden: false, modes: ['light', 'dark'], seed: '#d2bcff' },
+  { id: 'neogreen', name: 'Neogreen', hidden: false, modes: ['light', 'dark'], seed: '#00e563' },
+  { id: 'green', name: 'Green', hidden: true, modes: ['light', 'dark'], seed: '#53e081' },
+  { id: 'red', name: 'Red', hidden: false, modes: ['light', 'dark'], seed: '#ffb4ac' },
+  { id: 'orange', name: 'Orange', hidden: true, modes: ['light', 'dark'], seed: '#ffc988' },
+  { id: 'pink', name: 'Pink', hidden: false, modes: ['light', 'dark'], seed: '#f7acff' },
+  { id: 'pastel-pink', name: 'Pastel Pink', hidden: false, modes: ['light', 'dark'], seed: '#ffcee8' },
+  { id: 'brown', name: 'Brown', hidden: false, modes: ['light', 'dark'], seed: '#ffb783' },
+  { id: 'super-blue', name: 'Super Blue', hidden: false, modes: ['light', 'dark'], seed: '#bcc2ff' },
+  { id: 'cold-blue', name: 'Cold Blue', hidden: true, modes: ['light', 'dark'], seed: '#87ceff' },
+  { id: 'modern-1', name: 'Modern', hidden: true, modes: ['light', 'dark'], seed: '#b3c5ff' },
+  { id: 'gray', name: 'Gray', hidden: false, modes: ['light', 'dark'], seed: '#c6c6c6' },
+  { id: 'oled', name: 'Oled', hidden: false, modes: ['dark'], seed: '#9fb8e4' },
+  { id: 'funny', name: 'Funny', hidden: true, modes: ['light', 'dark'], seed: '#22d3ee' },
+  { id: 'new', name: 'New', hidden: true, modes: ['light', 'dark'], seed: '#c4a68d' },
+  { id: 'new2', name: 'New 2', hidden: true, modes: ['light', 'dark'], seed: '#a3ffb7' },
+  { id: 'black-green', name: 'Black Green', hidden: true, modes: ['light', 'dark'], seed: '#a0d499' },
+] as const satisfies readonly ThemePreset[];
+
+export type ThemeId = (typeof THEMES)[number]['id'];
+export const DEFAULT_THEME: ThemeId = 'neogreen';

package/src/theme/theme.ts

@@ -0,0 +1,119 @@
+import { DEFAULT_THEME, THEMES, type ThemeId } from './presets';
+import { warnOnce } from '../core/types';
+
+/*
+ * Theme and mode on <html data-mk-theme="neogreen" data-mk-mode="system|light|dark">,
+ * remembered in localStorage (Stepbro stores the palette per app and follows the
+ * system for light/dark unless told otherwise). Nothing runs at import time.
+ */
+
+export type ThemeMode = 'light' | 'dark' | 'system';
+export interface ThemeState {
+  id: string;
+  mode: ThemeMode;
+  /** The mode actually shown (system resolved through prefers-color-scheme). */
+  resolved: 'light' | 'dark';
+}
+
+export interface InitThemeOptions {
+  /** Theme when nothing is stored or set on the root. Default: neogreen. */
+  default?: ThemeId | (string & {});
+  mode?: ThemeMode;
+  storageKey?: string;
+  root?: HTMLElement;
+}
+
+export const THEME_EVENT = 'mk:theme';
+const MODES: ThemeMode[] = ['light', 'dark', 'system'];
+const known = new Set<string>(THEMES.map((theme) => theme.id));
+const settings = { storageKey: 'mk-theme', root: null as HTMLElement | null };
+let watching = false;
+
+/** Accept an extra theme id in setTheme (generated or project themes). */
+export function registerTheme(id: string) {
+  known.add(id);
+}
+
+const rootOf = () => settings.root ?? document.documentElement;
+const systemDark = () => typeof matchMedia === 'function' && matchMedia('(prefers-color-scheme: dark)').matches;
+
+function read(): Partial<Pick<ThemeState, 'id' | 'mode'>> | null {
+  try {
+    const raw = localStorage.getItem(settings.storageKey);
+    return raw ? (JSON.parse(raw) as Partial<ThemeState>) : null;
+  } catch {
+    return null;
+  }
+}
+
+function write(state: Pick<ThemeState, 'id' | 'mode'>) {
+  try {
+    localStorage.setItem(settings.storageKey, JSON.stringify({ id: state.id, mode: state.mode }));
+  } catch {
+    // Private mode or blocked storage: the choice simply isn't remembered.
+  }
+}
+
+export function getTheme(): ThemeState {
+  const root = rootOf();
+  const id = root.getAttribute('data-mk-theme') ?? DEFAULT_THEME;
+  const attr = root.getAttribute('data-mk-mode') as ThemeMode | null;
+  const mode = attr && MODES.includes(attr) ? attr : 'system';
+  return { id, mode, resolved: mode === 'system' ? (systemDark() ? 'dark' : 'light') : mode };
+}
+
+function apply(id: string, mode: ThemeMode, persist: boolean) {
+  const root = rootOf();
+  root.setAttribute('data-mk-theme', id);
+  root.setAttribute('data-mk-mode', mode);
+  if (persist) write({ id, mode });
+  const state = getTheme();
+  document.dispatchEvent(new CustomEvent<ThemeState>(THEME_EVENT, { detail: state }));
+  return state;
+}
+
+/** Apply the stored (or default) theme and mode. Call once on startup. */
+export function initTheme(options: InitThemeOptions = {}): ThemeState {
+  if (options.storageKey) settings.storageKey = options.storageKey;
+  if (options.root) settings.root = options.root;
+  const root = rootOf();
+  const stored = read();
+  const id = stored?.id ?? root.getAttribute('data-mk-theme') ?? options.default ?? DEFAULT_THEME;
+  const storedMode = stored?.mode && MODES.includes(stored.mode) ? stored.mode : null;
+  const mode = storedMode ?? (root.getAttribute('data-mk-mode') as ThemeMode | null) ?? options.mode ?? 'system';
+  if (!watching && typeof matchMedia === 'function') {
+    watching = true;
+    // In system mode the resolved scheme follows the OS; tell listeners when it flips.
+    matchMedia('(prefers-color-scheme: dark)').addEventListener?.('change', () => {
+      if (getTheme().mode === 'system') document.dispatchEvent(new CustomEvent<ThemeState>(THEME_EVENT, { detail: getTheme() }));
+    });
+  }
+  return apply(id, MODES.includes(mode) ? mode : 'system', false);
+}
+
+export function setTheme(id: ThemeId | (string & {})): ThemeState {
+  if (!known.has(id)) {
+    warnOnce(`setTheme: unknown theme "${id}" (register it with registerTheme or applyTheme)`);
+    return getTheme();
+  }
+  return apply(id, getTheme().mode, true);
+}
+
+export function setMode(mode: ThemeMode): ThemeState {
+  if (!MODES.includes(mode)) {
+    warnOnce(`setMode: unknown mode "${mode}"`);
+    return getTheme();
+  }
+  return apply(getTheme().id, mode, true);
+}
+
+/** Inline script for <head>: applies the stored choice before the first paint (no flash). */
+export function themeHeadScript({ storageKey = 'mk-theme', default: fallback = DEFAULT_THEME, mode = 'system' }: Omit<InitThemeOptions, 'root'> = {}) {
+  return (
+    `(function(){var r=document.documentElement,s=null;try{s=JSON.parse(localStorage.getItem(${JSON.stringify(storageKey)})||'null')}catch(e){}` +
+    `r.setAttribute('data-mk-theme',(s&&s.id)||r.getAttribute('data-mk-theme')||${JSON.stringify(fallback)});` +
+    `r.setAttribute('data-mk-mode',(s&&s.mode)||r.getAttribute('data-mk-mode')||${JSON.stringify(mode)})})();`
+  );
+}
+
+export const MK_THEME_HEAD_SCRIPT = themeHeadScript();