@leavepulse/ui 0.69.0 → 0.70.1

package/src/components/quota.ts

@@ -0,0 +1,111 @@
+import { CHART_PALETTE } from "./chart"
+import { formatBytes } from "./format"
+import { capacityThresholds, toneAt, type MeterTone } from "./meter"
+
+/*
+ * The arithmetic behind LpQuota, kept free of Vue so it can be tested and so an
+ * app that only needs "how much is left, and how worried should I be" can ask
+ * it directly.
+ */
+
+/** One part of what is used, for a stacked bar ("Images 12 GB, Backups 30 GB"). */
+export interface QuotaPart {
+  label: string
+  value: number
+  /** Any CSS colour. Unset parts take the chart palette in order, like LpChart's series (minus danger). */
+  color?: string
+}
+
+/**
+ * How amounts are written. `"bytes"` scales to the largest whole unit (1 536 →
+ * 1.5 KB) in binary steps, the way storage limits are sold and shown; any
+ * other string is a plain suffix ("seats", "req/min"); a function says it its
+ * own way.
+ */
+export type QuotaUnit = "bytes" | string | ((value: number) => string)
+
+export interface QuotaState {
+  /** Share of the limit used, 0–1 and beyond: 1.25 is a quarter over. */
+  ratio: number
+  /** What is left; zero once over. */
+  remaining: number
+  /** By how much the limit is exceeded; zero within it. */
+  over: number
+  /** False when there is no limit to measure against (unset, zero, Infinity). */
+  limited: boolean
+  tone: MeterTone
+}
+
+/**
+ * Where a quota stands. Thresholds are shares of the limit, read on the same
+ * capacity scale (and with the same defaults) as LpProgress's `auto` tone and
+ * LpGauge, so a quota and a gauge of one disk turn red together; anything past
+ * the limit is danger whatever they say, because "over" is the one state a
+ * quota must never paint as merely amber.
+ */
+export function quotaState(
+  used: number,
+  limit: number | null | undefined,
+  warnAt = 0.8,
+  dangerAt = 0.9,
+): QuotaState {
+  const safeUsed = Number.isFinite(used) ? Math.max(0, used) : 0
+  const limited = limit != null && Number.isFinite(limit) && limit > 0
+  if (!limited) return { ratio: 0, remaining: Infinity, over: 0, limited, tone: "ok" }
+  const ratio = safeUsed / limit
+  const tone = ratio > 1 ? "danger" : toneAt(ratio, capacityThresholds(0, 1, warnAt, dangerAt))
+  return {
+    ratio,
+    remaining: Math.max(0, limit - safeUsed),
+    over: Math.max(0, safeUsed - limit),
+    limited,
+    tone,
+  }
+}
+
+/**
+ * An amount in its unit, locale-aware. Bytes go through `formatBytes`, whose
+ * unit names come from Intl, so a Russian app reads "1,5 ГБ" without a
+ * translation table of its own.
+ */
+export function formatAmount(value: number, unit?: QuotaUnit, locale?: string): string {
+  if (typeof unit === "function") return unit(value)
+  if (unit === "bytes") return formatBytes(Math.max(0, value), locale)
+  const number = new Intl.NumberFormat(locale, { maximumFractionDigits: value < 10 ? 1 : 0 }).format(value)
+  return unit ? `${number} ${unit}` : number
+}
+
+/*
+ * Parts are categories, not verdicts, so the palette leaves out danger: a red
+ * "Backups" slice would read as an alarm about backups.
+ */
+const PART_PALETTE = CHART_PALETTE.filter((c) => !c.includes("danger"))
+
+export interface QuotaSegment extends QuotaPart {
+  color: string
+  /** Share of the bar's width, 0–1. */
+  share: number
+}
+
+/**
+ * The parts laid out along the bar. Within the limit the bar's width IS the
+ * limit, so a part's share is its value over the limit and the rest of the
+ * track is what remains. Over it, the bar stretches to hold everything used and
+ * the limit becomes a mark partway along (`limitAt`), so the overflow reads as
+ * the part of the bar beyond the line rather than as a bar that simply stopped
+ * at full.
+ */
+export function quotaSegments(
+  parts: readonly QuotaPart[],
+  limit: number | null | undefined,
+): { segments: QuotaSegment[]; limitAt: number | null } {
+  const total = parts.reduce((sum, p) => sum + Math.max(0, p.value), 0)
+  const limited = limit != null && Number.isFinite(limit) && limit > 0
+  const scale = limited ? Math.max(limit, total) : total
+  const segments = parts.map((p, i) => ({
+    ...p,
+    color: p.color ?? PART_PALETTE[i % PART_PALETTE.length],
+    share: scale > 0 ? Math.max(0, p.value) / scale : 0,
+  }))
+  return { segments, limitAt: limited && total > limit ? limit / total : null }
+}

package/src/components/relativeTime.ts

@@ -0,0 +1,118 @@
+import { toEpoch } from "./timeSpan"
+
+/*
+ * "3 min ago" / "in 2 h": the wording, and when it next changes.
+ *
+ * Pure, so it can be tested without a clock and so a non-Vue caller (a toast,
+ * a log line) can say a date the same way LpRelativeTime does.
+ */
+
+export type RelativeUnit = "second" | "minute" | "hour" | "day" | "week" | "month" | "year"
+
+const SECOND = 1000
+const MINUTE = 60 * SECOND
+const HOUR = 60 * MINUTE
+const DAY = 24 * HOUR
+const WEEK = 7 * DAY
+const MONTH = 30.4375 * DAY
+const YEAR = 365.25 * DAY
+
+/*
+ * Each unit holds until the next one reads better. The cut-offs sit before the
+ * full next unit on purpose: "50 minutes ago" is fussier than "1 hour ago",
+ * and nobody says "6 days ago" about a date that was a week ago.
+ */
+const SCALE: { unit: RelativeUnit; ms: number; until: number }[] = [
+  { unit: "second", ms: SECOND, until: 45 * SECOND },
+  { unit: "minute", ms: MINUTE, until: 45 * MINUTE },
+  { unit: "hour", ms: HOUR, until: 22 * HOUR },
+  { unit: "day", ms: DAY, until: 6.5 * DAY },
+  { unit: "week", ms: WEEK, until: 26 * DAY },
+  { unit: "month", ms: MONTH, until: 320 * DAY },
+  { unit: "year", ms: YEAR, until: Infinity },
+]
+
+export interface RelativeTimeOptions {
+  locale?: string
+  /** Intl's width: `long` "3 minutes ago", `short` "3 min. ago", `narrow` "3m ago". */
+  style?: Intl.RelativeTimeFormatStyle
+  /**
+   * Under this many ms either side of now, say "now" instead of counting
+   * seconds. Counting seconds is churn nobody reads; a countdown that needs
+   * them wants a timer, not this.
+   */
+  nowWithin?: number
+}
+
+export interface RelativeTime {
+  text: string
+  unit: RelativeUnit
+  /** Signed: negative is the past. */
+  value: number
+  /**
+   * Milliseconds until `text` would read differently. A ticker sleeps this
+   * long instead of waking every second for a date three weeks away.
+   */
+  refreshIn: number
+}
+
+const formatters = new Map<string, Intl.RelativeTimeFormat>()
+function formatterFor(locale: string | undefined, style: Intl.RelativeTimeFormatStyle) {
+  const key = `${locale ?? ""}|${style}`
+  let f = formatters.get(key)
+  if (!f) {
+    f = new Intl.RelativeTimeFormat(locale, { numeric: "auto", style })
+    formatters.set(key, f)
+  }
+  return f
+}
+
+/** Never sleep longer than this: a laptop waking from sleep should not show "2 h ago" for an hour. */
+const MAX_REFRESH = HOUR
+const MIN_REFRESH = SECOND
+
+export function formatRelativeTime(
+  date: Date | string | number,
+  now: number = Date.now(),
+  options: RelativeTimeOptions = {},
+): RelativeTime {
+  const { locale, style = "long", nowWithin = 45 * SECOND } = options
+  const at = toEpoch(date)
+  const fmt = formatterFor(locale, style)
+  if (!Number.isFinite(at)) return { text: "", unit: "second", value: 0, refreshIn: MAX_REFRESH }
+
+  const diff = at - now
+  const abs = Math.abs(diff)
+
+  if (abs < nowWithin) {
+    // "now" holds until the date is `nowWithin` away on the far side; a future
+    // date crossing into the past stays "now" all the way through.
+    const refreshIn = diff >= 0 ? diff + nowWithin : nowWithin - abs
+    return { text: fmt.format(0, "second"), unit: "second", value: 0, refreshIn: clampRefresh(refreshIn) }
+  }
+
+  const index = SCALE.findIndex((s) => abs < s.until)
+  const step = SCALE[index]
+  const count = Math.max(1, Math.round(abs / step.ms))
+  const value = diff < 0 ? -count : count
+
+  /*
+   * The next moment the rounded count changes. In the past the distance only
+   * grows, so that is the next half-unit boundary above it; in the future it
+   * only shrinks, so the next one below. Crossing into another unit happens on
+   * a boundary of the smaller unit, so this also catches "45 min" → "1 hour".
+   */
+  const units = abs / step.ms
+  const boundary = diff < 0 ? (Math.floor(units + 0.5) + 0.5) * step.ms : (Math.ceil(units - 0.5) - 0.5) * step.ms
+  // A unit change can also come before the next rounding step: a past date
+  // grows into the next unit at this one's `until`, a future one shrinks into
+  // the previous unit at that one's.
+  const unitChange = diff < 0 ? step.until - abs : index > 0 ? abs - SCALE[index - 1].until : Infinity
+  const refreshIn = Math.min(diff < 0 ? boundary - abs : abs - boundary, unitChange)
+
+  return { text: fmt.format(value, step.unit), unit: step.unit, value, refreshIn: clampRefresh(refreshIn) }
+}
+
+function clampRefresh(ms: number): number {
+  return Math.min(MAX_REFRESH, Math.max(MIN_REFRESH, Math.ceil(ms)))
+}

package/src/components/reveal.ts

@@ -0,0 +1,56 @@
+/*
+ * Keyframes and timing for LpRevealOnScroll, kept apart from the component so
+ * they can be tested without a DOM.
+ */
+
+export type RevealPreset = "fade" | "rise" | "blur" | "scale"
+export type RevealDirection = "up" | "down" | "left" | "right"
+
+/**
+ * The hidden state an entrance starts from; the end state is always "as laid
+ * out", so the keyframes only describe where the content comes FROM.
+ *
+ * `direction` is the way the content travels: `up` starts below and rises.
+ * Every preset fades — motion without a fade reads as a layout jump.
+ */
+export function revealFrom(
+  preset: RevealPreset,
+  direction: RevealDirection,
+  distance: number,
+): Keyframe {
+  const offset = (d: number) =>
+    ({
+      up: `translate3d(0, ${d}px, 0)`,
+      down: `translate3d(0, ${-d}px, 0)`,
+      left: `translate3d(${d}px, 0, 0)`,
+      right: `translate3d(${-d}px, 0, 0)`,
+    })[direction]
+  switch (preset) {
+    case "fade":
+      return { opacity: 0 }
+    case "rise":
+      return { opacity: 0, transform: offset(distance) }
+    case "blur":
+      // A short travel with the blur: blur alone looks like a focus problem.
+      return { opacity: 0, filter: "blur(8px)", transform: offset(distance / 2) }
+    case "scale":
+      return { opacity: 0, transform: "scale(0.94)" }
+  }
+}
+
+/** The resting state matching `revealFrom`'s properties. */
+export function revealTo(from: Keyframe): Keyframe {
+  const to: Keyframe = { opacity: 1 }
+  if ("transform" in from) to.transform = "none"
+  if ("filter" in from) to.filter = "blur(0px)"
+  return to
+}
+
+/**
+ * Delay of the `index`-th child. The steps stop growing after `cap` children:
+ * a list of eighty would otherwise take seconds to finish arriving, and the
+ * last rows would still be invisible when the user starts reading them.
+ */
+export function staggerDelay(index: number, delay: number, stagger: number, cap = 10): number {
+  return delay + Math.min(Math.max(0, index), cap) * Math.max(0, stagger)
+}

package/src/components/scramble.ts

@@ -0,0 +1,138 @@
+/*
+ * Frame generation for the "decrypt" effect (LpScramble, useScramble).
+ *
+ * Kept pure and clock-free so it can be tested frame by frame: a plan says WHEN
+ * each position settles, and a frame is the text at a given moment. The caller
+ * owns time and randomness — the composable feeds `performance.now()` and
+ * `Math.random`, a test feeds fixed numbers and a seeded generator and gets the
+ * same frames every run.
+ */
+
+/** Random number in [0, 1). Injected so frames are reproducible under test. */
+export type Random = () => number
+
+/** Glyphs a position cycles through before it settles. Upper case and digits read as "code". */
+export const SCRAMBLE_GLYPHS = "ABCDEFGHJKLMNPQRSTUVWXYZ0123456789#%&*+=?@$"
+
+export interface ScrambleOptions {
+  /** Total travel time in ms, from the first glyph to the last position settling. */
+  duration: number
+  /**
+   * `sequential` settles left to right, which reads as decoding; `together`
+   * holds every position until near the end and lands them in a short burst,
+   * which reads as a lock opening.
+   */
+  order?: "sequential" | "together"
+  /** Glyph pool. */
+  glyphs?: string
+  /**
+   * Characters that never scramble: a space or a dash in a key keeps the
+   * grouping visible while the rest churns, so the reader sees the shape of
+   * what is coming.
+   */
+  keep?: (char: string) => boolean
+}
+
+export interface ScrambleCell {
+  /** The character settled into, or "" for a position the new value no longer has. */
+  final: string
+  /** The character shown before the run started (sizes a position the value is losing). */
+  initial: string
+  /** Ms from the start of the run when this position shows `final`. */
+  settleAt: number
+  /** Never churns (see `keep`). */
+  fixed: boolean
+}
+
+export interface ScrambleFrameCell {
+  /** What to draw now. */
+  char: string
+  /** The character that gives the position its width: the final one, or the old one while it is leaving. */
+  sizer: string
+  settled: boolean
+}
+
+const defaultKeep = (char: string) => /\s/.test(char)
+
+/**
+ * Splits into user-perceived characters, so an emoji or an accented letter is
+ * one position rather than two halves that scramble separately.
+ */
+export function graphemes(text: string): string[] {
+  const Segmenter = (Intl as { Segmenter?: typeof Intl.Segmenter }).Segmenter
+  if (Segmenter) return Array.from(new Segmenter(undefined, { granularity: "grapheme" }).segment(text), (s) => s.segment)
+  return Array.from(text)
+}
+
+/**
+ * When each position stops churning (all of them start at once).
+ *
+ * `sequential`: positions start together and settle on a ramp across the last
+ * 70% of the run, so the left of the value is readable while the right still
+ * moves. `together`: every position settles within the last 15%, with a
+ * little random spread so they do not land as one flat click.
+ */
+export function planScramble(from: string, to: string, options: ScrambleOptions, random: Random = Math.random): ScrambleCell[] {
+  const keep = options.keep ?? defaultKeep
+  const a = graphemes(from)
+  const b = graphemes(to)
+  const length = Math.max(a.length, b.length)
+  const duration = Math.max(0, options.duration)
+  const cells: ScrambleCell[] = []
+  for (let i = 0; i < length; i++) {
+    const final = b[i] ?? ""
+    const initial = a[i] ?? ""
+    let settleAt: number
+    if (options.order === "together") settleAt = duration * (0.85 + 0.15 * random())
+    else settleAt = length === 1 ? duration : duration * (0.3 + (0.7 * i) / (length - 1))
+    // A kept character (a space in a grouped key) stays put when it is there
+    // before and after, so the grouping holds while the rest churns.
+    const fixed = final !== "" && keep(final) && (initial === final || initial === "")
+    cells.push({ final, initial, settleAt: fixed ? 0 : settleAt, fixed })
+  }
+  return cells
+}
+
+/** A glyph from the pool. */
+export function randomGlyph(random: Random, glyphs: string = SCRAMBLE_GLYPHS): string {
+  const pool = graphemes(glyphs)
+  return pool[Math.min(pool.length - 1, Math.floor(random() * pool.length))] ?? ""
+}
+
+/**
+ * The text at `elapsed` ms into the run. A churning position draws a fresh
+ * random glyph each call; the caller decides how often to call (the glyph
+ * re-roll rate), not this.
+ */
+export function scrambleFrame(
+  cells: ScrambleCell[],
+  elapsed: number,
+  random: Random = Math.random,
+  glyphs: string = SCRAMBLE_GLYPHS,
+): ScrambleFrameCell[] {
+  return cells.map((cell) => {
+    const sizer = cell.final || cell.initial
+    if (cell.fixed || elapsed >= cell.settleAt) return { char: cell.final, sizer: cell.final, settled: true }
+    return { char: randomGlyph(random, glyphs), sizer, settled: false }
+  })
+}
+
+/** The cells of a value at rest, for the first paint and for reduced motion. */
+export function settledCells(text: string): ScrambleFrameCell[] {
+  return graphemes(text).map((char) => ({ char, sizer: char, settled: true }))
+}
+
+/**
+ * A small seeded generator (mulberry32), for tests and for a scramble that
+ * should look the same every time it plays (a demo, a screenshot).
+ */
+export function seededRandom(seed: number): Random {
+  let state = seed >>> 0
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0
+    let t = state
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}

package/src/components/shaderBackdrop.ts

@@ -0,0 +1,208 @@
+/*
+ * The looks LpShaderBackdrop can draw, and the small decisions around them
+ * that are worth testing without a GPU.
+ *
+ * Every look is a fragment shader over one full-screen triangle, fed the same
+ * uniforms: size, time, pixel ratio, intensity, and five theme colours read
+ * from the kit's tokens (surface, brand, accent, action, ink). A look never
+ * names a colour of its own, so it follows any theme, light or dark.
+ *
+ * Every look also has a CSS fallback built from the same tokens through
+ * `var()`, shown where WebGL is missing, too slow, or unwanted (reduced
+ * motion). It is a still that resembles the look, so a page reads the same
+ * with or without the GPU, and it is also what shows under the canvas while
+ * the first frame is being drawn.
+ *
+ * The shaders are WebGL 1 / GLSL ES 1.00 and deliberately cheap: a handful of
+ * sines and exponentials per pixel, no loops over octaves, no textures. The
+ * kit runs inside WebKitGTK, where WebGL may be software-rendered; the soft
+ * looks are drawn at half resolution for the same reason.
+ */
+
+export type ShaderPreset = "aurora" | "silk" | "grain" | "dots"
+
+export interface PresetDef {
+  /** Body of the fragment shader, after the shared header. */
+  fragment: string
+  /** Rendering resolution relative to CSS pixels × pixel ratio. Soft looks lose nothing at half. */
+  scale: number
+  /** CSS `background` of the still that stands in for the look. */
+  fallback: string
+}
+
+export const VERTEX_SHADER = `
+attribute vec2 p;
+void main() { gl_Position = vec4(p, 0.0, 1.0); }
+`
+
+/* Uniforms every look receives. u_bg..u_ink are the theme, in 0–1 sRGB. */
+export const FRAGMENT_HEADER = `
+precision mediump float;
+uniform vec2 u_res;
+uniform float u_time;
+uniform float u_px;
+uniform float u_k;
+uniform vec3 u_bg;
+uniform vec3 u_brand;
+uniform vec3 u_accent;
+uniform vec3 u_action;
+uniform vec3 u_ink;
+`
+
+const mix = (token: string, share: number) => `color-mix(in oklab, var(--color-${token}) ${share}%, transparent)`
+
+/*
+ * Film grain for the CSS still: SVG turbulence, rendered once by the engine
+ * as an image. Grey, at low opacity, so it textures any surface colour.
+ */
+const NOISE =
+  "url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 0.5 0 0 0 0 0.5 0 0 0 0 0.5 0 0 0 0.35 0'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E\")"
+
+export const PRESETS: Record<ShaderPreset, PresetDef> = {
+  /*
+   * Curtains of light across the upper part: each band has a sharp upper
+   * edge and a long fall-off below it, waves sideways, and is striated by
+   * fine vertical rays that drift.
+   */
+  aurora: {
+    scale: 0.5,
+    fragment: `
+float band(vec2 uv, float x, float off, float sp) {
+  float y = 0.66 + off + 0.09 * sin(x * 1.9 + u_time * sp + off * 9.0) + 0.04 * sin(x * 4.7 - u_time * sp * 1.7 + off * 4.0);
+  float d = uv.y - y;
+  float body = exp(-d * d * (d > 0.0 ? 160.0 : 22.0));
+  float rays = 0.86 + 0.14 * sin(x * 70.0 + 6.0 * sin(x * 2.3 + u_time * 0.4));
+  return body * rays;
+}
+void main() {
+  vec2 uv = gl_FragCoord.xy / u_res;
+  float x = gl_FragCoord.x / u_res.y;
+  vec3 col = u_bg;
+  col = mix(col, u_brand, band(uv, x, 0.0, 0.35) * 0.7 * u_k);
+  col = mix(col, u_accent, band(uv, x, -0.18, 0.27) * 0.45 * u_k);
+  col = mix(col, u_action, band(uv, x, 0.12, 0.43) * 0.45 * u_k);
+  gl_FragColor = vec4(col, 1.0);
+}`,
+    fallback: [
+      `radial-gradient(70% 38% at 30% 28%, ${mix("brand", 42)}, transparent 70%)`,
+      `radial-gradient(55% 30% at 72% 44%, ${mix("accent", 30)}, transparent 70%)`,
+      `radial-gradient(50% 26% at 55% 18%, ${mix("action", 26)}, transparent 70%)`,
+    ].join(", "),
+  },
+
+  /*
+   * A sheet of fabric: diagonal folds that slowly ripple, the brand colour
+   * in the body and a narrow highlight running along each crest.
+   */
+  silk: {
+    scale: 0.5,
+    fragment: `
+void main() {
+  vec2 uv = gl_FragCoord.xy / u_res;
+  vec2 p = (gl_FragCoord.xy - 0.5 * u_res) / u_res.y * 2.2;
+  float t = u_time * 0.6;
+  float f = p.x * 0.9 + p.y * 0.5 + 0.6 * sin(p.y * 1.7 + t) + 0.35 * sin(p.x * 2.3 - t * 0.8 + p.y);
+  float fold = sin(f * 3.4);
+  float sheen = pow(0.5 + 0.5 * fold, 6.0);
+  vec3 tint = mix(u_brand, u_accent, clamp(uv.x * 0.7 + 0.15 * sin(t * 0.5), 0.0, 1.0));
+  vec3 col = mix(u_bg, tint, (0.22 + 0.14 * fold) * u_k);
+  col += sheen * mix(u_brand, vec3(1.0), 0.4) * 0.28 * u_k;
+  gl_FragColor = vec4(col, 1.0);
+}`,
+    fallback: [
+      `linear-gradient(115deg, transparent 12%, ${mix("brand", 30)} 30%, transparent 46%, ${mix("accent", 22)} 64%, transparent 80%)`,
+      `linear-gradient(160deg, ${mix("brand", 16)}, transparent 70%)`,
+    ].join(", "),
+  },
+
+  /*
+   * Two soft colour pools drifting over the surface, under moving film
+   * grain. The grain is per device pixel and refreshes a dozen-odd times a
+   * second, like film, rather than every frame, which would read as static.
+   */
+  grain: {
+    scale: 1,
+    fragment: `
+float hash(vec2 q) { return fract(sin(dot(q, vec2(12.9898, 78.233))) * 43758.5453); }
+void main() {
+  vec2 uv = gl_FragCoord.xy / u_res;
+  float aspect = u_res.x / u_res.y;
+  vec2 p = vec2(uv.x * aspect, uv.y);
+  float t = u_time * 0.25;
+  vec2 a = vec2((0.3 + 0.2 * sin(t)) * aspect, 0.7 + 0.15 * cos(t * 1.3));
+  vec2 b = vec2((0.75 + 0.15 * cos(t * 0.8)) * aspect, 0.3 + 0.2 * sin(t * 1.1));
+  float da = exp(-dot(p - a, p - a) * 3.0);
+  float db = exp(-dot(p - b, p - b) * 4.0);
+  vec3 col = mix(u_bg, u_brand, da * 0.6 * u_k);
+  col = mix(col, u_accent, db * 0.5 * u_k);
+  col = mix(col, u_action, (1.0 - uv.y) * 0.12 * u_k);
+  vec2 cell = floor(gl_FragCoord.xy / max(1.0, u_px));
+  float g = hash(cell + vec2(floor(u_time * 14.0) * 17.31, 0.0)) - 0.5;
+  col += g * 0.09;
+  gl_FragColor = vec4(col, 1.0);
+}`,
+    fallback: [
+      NOISE,
+      `radial-gradient(55% 55% at 28% 30%, ${mix("brand", 40)}, transparent 70%)`,
+      `radial-gradient(50% 50% at 76% 72%, ${mix("accent", 32)}, transparent 70%)`,
+      `linear-gradient(to top, ${mix("action", 10)}, transparent 60%)`,
+    ].join(", "),
+  },
+
+  /*
+   * A dot grid with a slow ripple travelling out from the middle: dots on
+   * the crest swell and take the brand colour, the rest stay small and quiet.
+   */
+  dots: {
+    scale: 1,
+    fragment: `
+void main() {
+  float cell = 22.0 * u_px;
+  vec2 g = gl_FragCoord.xy / cell;
+  vec2 id = floor(g);
+  vec2 f = fract(g) - 0.5;
+  float dist = length(id + 0.5 - 0.5 * u_res / cell);
+  float wave = pow(0.5 + 0.5 * sin(dist * 0.5 - u_time * 1.6), 3.0);
+  float r = 0.08 + 0.07 * wave * u_k;
+  float aa = 1.0 / cell;
+  float dotMask = 1.0 - smoothstep(r - aa, r + aa, length(f));
+  vec3 rest = mix(u_bg, u_ink, 0.2);
+  vec3 col = mix(u_bg, u_brand, wave * 0.03 * u_k);
+  col = mix(col, mix(rest, u_brand, wave * u_k), dotMask);
+  gl_FragColor = vec4(col, 1.0);
+}`,
+    fallback: [
+      `radial-gradient(circle, ${mix("ink", 22)} 1.5px, transparent 2.2px) center / 22px 22px`,
+      `radial-gradient(45% 45% at 50% 50%, ${mix("brand", 16)}, transparent 75%)`,
+    ].join(", "),
+  },
+}
+
+export const PRESET_NAMES = Object.keys(PRESETS) as ShaderPreset[]
+
+/** Whether enough time has passed for the next frame at `fps`. Frames land on the display's beat, so allow a little early. */
+export function frameDue(now: number, last: number, fps: number): boolean {
+  return now - last >= 1000 / Math.max(1, fps) - 2
+}
+
+/*
+ * Whether the engine is failing to keep up. Judged on the median interval
+ * between drawn frames, not the mean: a single hitch (a tab switch the
+ * visibility event missed, a GC) must not cost the backdrop its motion.
+ * Too slow means the frames come at under half the asked rate and slower
+ * than about 12 a second: a choppy aurora is worse than a still one.
+ */
+export function tooSlow(intervals: readonly number[], fps: number): boolean {
+  if (intervals.length < 20) return false
+  const sorted = [...intervals].sort((a, b) => a - b)
+  const median = sorted[Math.floor(sorted.length / 2)]
+  return median > Math.max((2 * 1000) / Math.max(1, fps), 80)
+}
+
+/** A colour in 0–1 sRGB channels, as a shader takes it. */
+export type Vec3 = [number, number, number]
+
+/** Move `from` toward `to` by share `k` (0–1): theme changes blend over a few frames instead of snapping. */
+export function approach(from: Vec3, to: Vec3, k: number): Vec3 {
+  return [from[0] + (to[0] - from[0]) * k, from[1] + (to[1] - from[1]) * k, from[2] + (to[2] - from[2]) * k]
+}

package/src/components/slider.ts

@@ -0,0 +1,30 @@
+import { onBeforeUnmount, ref } from "vue"
+
+/*
+ * A slider whose value is changed from outside (a reset, a preset, data
+ * arriving) glides its thumb and range to the new place instead of jumping;
+ * while the user drags, they follow the pointer with no delay, since an
+ * eased thumb trailing the finger reads as lag. reka places both with inline
+ * `left`/`right`, so the transition goes on those.
+ */
+export const SLIDER_GLIDE =
+  "[&_[style*=left]]:transition-[left,right] [&_[style*=left]]:duration-(--duration-medium) [&_[style*=left]]:ease-(--ease-emphasized) data-[dragging]:[&_[style*=left]]:transition-none motion-reduce:[&_[style*=left]]:transition-none"
+
+export function useSliderDrag() {
+  const dragging = ref(false)
+  let view: Window | null = null
+  const end = () => {
+    dragging.value = false
+    view?.removeEventListener("pointerup", end)
+    view?.removeEventListener("pointercancel", end)
+    view = null
+  }
+  function onPointerDown(event: PointerEvent) {
+    dragging.value = true
+    view = (event.currentTarget as Element).ownerDocument.defaultView
+    view?.addEventListener("pointerup", end)
+    view?.addEventListener("pointercancel", end)
+  }
+  onBeforeUnmount(end)
+  return { dragging, onPointerDown }
+}

package/src/components/slotText.ts

@@ -0,0 +1,13 @@
+import { Text, type Slot, type VNode } from "vue"
+
+/*
+ * A slot's words when it holds nothing but text, else null. Components that
+ * animate a change of what they say (a badge rolling to a new status, an alert
+ * swapping its message) need to know when the words changed; anything richer
+ * (an icon, markup) is shown as given and only its box eases.
+ */
+export function slotText(slot: Slot | undefined): string | null {
+  const nodes: VNode[] = slot?.() ?? []
+  if (!nodes.length || !nodes.every((node) => node.type === Text)) return null
+  return nodes.map((node) => String(node.children ?? "")).join("").trim() || null
+}