tweakit 0.5.2 → 0.6.0

package/src/tweaks/controls/interval.ts

@@ -0,0 +1,104 @@
+// ── Interval / range slider — dual-handle [lo,hi]. Lazy.
+import { el, txt, clamp, roundToStep, stepPrecision, gridEnds, normalizeRange, rangeStep, overlapsText, wireHoverClass, onReady, onLive, registerControl, rubberBand, rubberRelease } from "../shared.js";
+import { dragGesture } from "../heavy.js";
+import type { OnChange } from "../shared.js";
+import type { Meta } from "../schema.js";
+import type { Control } from "../types.js";
+
+function createInterval(meta: Meta, onChange: OnChange): Control {
+  const label = meta.label;
+  const t0 = +(meta.value && meta.value[0]), t1 = +(meta.value && meta.value[1]);
+  const lo0 = Number.isFinite(t0) ? t0 : 0, hi0 = Number.isFinite(t1) ? t1 : 1;
+  // normalizeRange, the slider's guard: an absent or non-finite bound (data-min="abc") derives from the values, each end
+  // widening it, for the shorthand and the verbose form alike: [20, 80] spans 0–240, not 20–80 (which pinned both handles).
+  let { min, max, step } = normalizeRange(meta.min, meta.max, meta.step, [lo0, hi0], label);
+  [min, max] = gridEnds(min, max, step); // the slider's rule: no value past an off-grid bound
+  const decimals = stepPrecision(step);
+  const q = (v: number) => roundToStep(v, min, step);
+  let lo = 0, hi = 0;
+  const put = (a: number, b: number) => { lo = clamp(q(Math.min(a, b)), min, max); hi = clamp(q(Math.max(a, b)), min, max); }; // ordered, on the grid, in bounds
+  // Missing tuple entries fall back to the bounds: value:[5] gives [5, max], not [5, NaN].
+  put(Number.isFinite(t0) ? t0 : min, Number.isFinite(t1) ? t1 : max);
+
+  const wrap = el("div", "tw-slider-wrap");
+  const track = el("div", "tw-slider tw-interval");
+  const fill = el("div", "tw-slider-fill");
+  const hLo = el("div", "tw-slider-handle"), hHi = el("div", "tw-slider-handle");
+  const labelEl = txt("span", "tw-slider-label", label);
+  const valueEl = el("span", "tw-slider-value");
+  track.append(fill, hLo, hHi, labelEl, valueEl);
+  wrap.append(track);
+
+  ([["minimum", hLo], ["maximum", hHi]] as const).forEach(([lab, h]) => {
+    h.tabIndex = 0; h.setAttribute("role", "slider"); h.setAttribute("aria-label", `${label} ${lab}`);
+    h.setAttribute("aria-valuemin", String(min)); h.setAttribute("aria-valuemax", String(max));
+  });
+
+  const pctOf = (v: number) => ((v - min) / ((max - min) || 1)) * 100;
+  const handleLeft = (pct: number) => `clamp(5px, calc(${pct}% - 1.5px), calc(100% - 9px))`; // stay inset at the extremes, like the slider handle
+  const render = () => {
+    const a = pctOf(lo), b = pctOf(hi);
+    fill.style.left = a + "%"; fill.style.width = Math.max(0, b - a) + "%";
+    hLo.style.left = handleLeft(a); hHi.style.left = handleLeft(b);
+    valueEl.textContent = `${lo.toFixed(decimals)} – ${hi.toFixed(decimals)}`;
+    hLo.setAttribute("aria-valuenow", String(lo)); hHi.setAttribute("aria-valuenow", String(hi));
+    // Value-dodge (overlapsText), per handle: one sliding under the label or the readout yields so the text stays legible.
+    const trackW = wrap.offsetWidth;
+    if (trackW) {
+      // The label's room is what the dual readout leaves, measured: 12px label inset + 8px gap + the readout's right inset.
+      labelEl.style.maxWidth = Math.max(0, trackW - valueEl.offsetWidth - 12 - 8 - 10) + "px";
+      const dodges = (pct: number) => overlapsText(labelEl, valueEl, (pct / 100) * trackW - 1.5, 3);
+      hLo.classList.toggle("is-dodge", dodges(pctOf(lo)));
+      hHi.classList.toggle("is-dodge", dodges(pctOf(hi)));
+    }
+  };
+  render();
+
+  const emit = () => onChange([lo, hi]);
+  const setLo = (v: number) => { lo = clamp(Math.min(q(v), hi), min, max); render(); };
+  const setHi = (v: number) => { hi = clamp(Math.max(q(v), lo), min, max); render(); };
+
+  let rect: DOMRect | null = null, scale = 1, active: "lo" | "hi" | null = null;
+  // Divide out any ancestor CSS transform (rect is visual px, offsetWidth layout px), as the single slider does.
+  const valFromX = (x: number) => { const native = wrap.offsetWidth || rect.width; const p = clamp((x - rect.left) / scale / native, 0, 1); return clamp(min + p * (max - min), min, max); };
+  const grab = (x: number) => {
+    const v = valFromX(x);
+    if (!active) active = v < lo ? "lo" : v > hi ? "hi" : (Math.abs(v - lo) <= Math.abs(v - hi) ? "lo" : "hi");
+    active === "lo" ? setLo(v) : setHi(v); emit();
+  };
+  dragGesture(track, {
+    onDown: (e) => {
+      e.preventDefault();
+      rect = wrap.getBoundingClientRect(); scale = rect.width / (wrap.offsetWidth || rect.width);
+      track.style.transition = ""; // a re-press mid spring-home stretches 1:1
+      track.classList.add("is-active", "is-dragging"); active = null;
+      grab(e.clientX);
+      (active === "lo" ? hLo : hHi).focus({ focusVisible: false }); // preventDefault killed click-to-focus; focus without a ring
+    },
+    onMove: (e) => { grab(e.clientX); rubberBand(track, rect, e.clientX); },
+    onEnd: () => { rubberRelease(track); rect = null; active = null; track.classList.remove("is-active", "is-dragging"); },
+  });
+  wireHoverClass(track, render); // re-run the dodge with the real track width on hover
+  // Recompute once layout and fonts settle (a web-font swap shifts the widths the dodge measures) and on track-width change.
+  onReady(render);
+  onLive(track, [[window, "resize"], [window, "tw-reflow"]], render); // tw-reflow: a tab page revealing this re-measures it
+
+  // Home/End snap a handle to its neighbor-or-limit, so the two can't cross.
+  const page = (max - min) / 10 || step * 10; // PageUp/Down: a tenth of the range, as the slider jumps
+  const onKey = (which: "lo" | "hi") => (e: KeyboardEvent) => {
+    const nv = which === "lo" ? rangeStep(e, lo, step, min, hi, page) : rangeStep(e, hi, step, lo, max, page);
+    if (nv == null) return;
+    e.preventDefault(); which === "lo" ? setLo(nv) : setHi(nv); emit();
+  };
+  hLo.addEventListener("keydown", onKey("lo")); hHi.addEventListener("keydown", onKey("hi"));
+
+  return {
+    el: wrap,
+    set: (v: unknown) => { if (Array.isArray(v)) { const a = +v[0], b = +v[1]; if (!Number.isFinite(a) || !Number.isFinite(b)) return; put(a, b); render(); } },
+    get: () => [lo, hi],
+    range: [min, max],
+  };
+}
+
+registerControl("interval", createInterval);
+

package/src/tweaks/controls/monitor.ts

@@ -0,0 +1,105 @@
+// ── Monitor + FPS graph — live sparkline / readout. Lazy; registers both types.
+import { el, txt, clamp, blade, json, registerControl } from "../shared.js";
+import { fitCanvas, accentColor } from "../heavy.js";
+import type { Meta } from "../schema.js";
+
+// NaN means no sample yet: the pen lifts rather than drawing a false zero.
+const strokeSeries = (ctx: CanvasRenderingContext2D, node: Element, w: number, h: number, samples: number[], start: number, frac: (s: number) => number) => {
+  const N = samples.length;
+  ctx.clearRect(0, 0, w, h);
+  ctx.strokeStyle = accentColor(node);
+  ctx.lineWidth = 1.5; ctx.lineJoin = "round"; ctx.beginPath();
+  let pen = false;
+  for (let k = 0; k < N; k++) {
+    const s = samples[(start + k) % N];
+    if (Number.isNaN(s)) continue;
+    const x = (k / (N - 1)) * w, y = h - clamp(frac(s), 0, 1) * h;
+    pen ? ctx.lineTo(x, y) : (ctx.moveTo(x, y), pen = true);
+  }
+  ctx.stroke();
+};
+
+// Manual, not onLive: these blades idle through the built-but-not-mounted window, which onLive would read as gone.
+const watchReflow = (fn: () => void) => {
+  for (const t of ["resize", "tw-reflow"]) window.addEventListener(t, fn);
+  return () => { for (const t of ["resize", "tw-reflow"]) window.removeEventListener(t, fn); };
+};
+
+// ── Monitor — a number as a sparkline or a readout, a string as a buffer of the last few values; read on an interval
+// or, `perFrame` (the FPS graph), once per animation frame. ──
+function createMonitor(meta: Meta, perFrame = false) {
+  const get: (now?: number) => unknown = typeof meta.get === "function" ? meta.get : () => meta.value;
+  const interval = Math.max(30, Number.isFinite(+meta.interval) ? +meta.interval : 200); // NaN would make setInterval a 0 ms busy-poll
+  let probe: unknown; try { probe = get(); } catch {}
+  const isNum = typeof probe === "number";
+  const graph = meta.view === "graph" || (isNum && meta.graph !== false && meta.view !== "text" && meta.rows == null);
+
+  const wrap = el("div", "tw-fps tw-monitor");
+  const val = txt("span", "tw-fps-val", "—");
+  wrap.append(txt("span", "tw-fps-label", meta.label ?? "Monitor"), val);
+
+  let timer = 0, raf = 0, unwatch = () => {}, wasConnected = false;
+  // toFixed throws past 100; a missing value reads as a dash.
+  const decimals = Number.isFinite(+meta.decimals) ? Math.min(20, Math.max(0, Math.floor(+meta.decimals))) : 2;
+  const fmt = (v: unknown) => (v == null ? "—" : typeof v === "number" ? (Number.isInteger(v) || !Number.isFinite(v) ? String(v) : v.toFixed(decimals)) : typeof v === "object" ? json(v) : String(v));
+  // Also the blade's `destroy`: a panel torn down before it ever connected can never self-stop below.
+  const stop = () => { if (timer) clearInterval(timer); timer = 0; if (raf) cancelAnimationFrame(raf); raf = 0; unwatch(); };
+  // Never-mounted-yet idles the tick; only a mount-then-remove, or destroy(), stops it. The next frame is booked before
+  // the read, so a stop() inside the tick cancels it.
+  const poll = (fn: (v: unknown) => void) => {
+    const tick = (now?: number) => {
+      if (perFrame) raf = requestAnimationFrame(tick);
+      if (!wrap.isConnected) { if (wasConnected) stop(); return; }
+      wasConnected = true;
+      let v: unknown; try { v = get(now); } catch { return; }
+      fn(v);
+    };
+    if (perFrame) raf = requestAnimationFrame(tick); else timer = setInterval(tick, interval);
+  };
+
+  if (!graph && meta.rows) {
+    val.remove();
+    // A negative or NaN rows spun the trim loop forever.
+    const rows = Math.max(1, Math.floor(+meta.rows) || 1);
+    const buf = el("pre", "tw-monitor-buffer"); buf.style.setProperty("--tw-monitor-rows", rows);
+    wrap.append(buf);
+    const lines: string[] = [];
+    poll((v) => { lines.push(fmt(v)); while (lines.length > rows) lines.shift(); buf.textContent = lines.join("\n"); });
+    return blade(wrap, stop);
+  }
+  const readout = (v: unknown) => { val.textContent = fmt(v); };
+  if (!graph) { poll(readout); return blade(wrap, stop); }
+
+  const canvas = document.createElement("canvas"); canvas.className = "tw-fps-canvas";
+  wrap.append(canvas);
+  const ctx = canvas.getContext("2d");
+  // No 2D context (a headless DOM, a blocked canvas) degrades to the text readout.
+  if (!ctx) { poll(readout); return blade(wrap, stop); }
+  const N = 80, samples: number[] = new Array(N).fill(NaN);
+  let idx = 0, w = 0, h = 0;
+  const onResize = () => { [w, h] = fitCanvas(canvas, ctx, 2); };
+  unwatch = watchReflow(onResize);
+  const draw = () => {
+    if (!w) onResize(); // measured 0 while detached: fit on the first live draw
+    if (!w) return;
+    let lo = meta.min, hi = meta.max;
+    if (lo == null || hi == null) {
+      let mn = Infinity, mx = -Infinity;
+      for (const s of samples) if (Number.isFinite(s)) { if (s < mn) mn = s; if (s > mx) mx = s; } // an Infinity sample would blank the auto-range
+      if (mn === Infinity) { mn = 0; mx = 1; } else if (mn === mx) { mn -= 0.5; mx += 0.5; }
+      const pad = (mx - mn) * 0.1;
+      if (lo == null) lo = mn - pad; if (hi == null) hi = mx + pad;
+    }
+    const span = (hi - lo) || 1;
+    strokeSeries(ctx, wrap, w, h, samples, idx, (s) => (s - lo) / span);
+  };
+  poll((v) => { readout(v); if (typeof v === "number" && Number.isFinite(v)) { samples[idx] = v; idx = (idx + 1) % N; draw(); } }); // a non-finite sample shows in the readout, not the graph
+  return blade(wrap, stop);
+}
+
+// ── FPS graph — each frame's timestamp becomes the rate since the last (none on the first or for the probe), 0–120. ──
+const frameRate = () => { let last = 0; return (now?: number) => { if (!(now! > 0)) return undefined; const fps = last ? 1000 / (now! - last) : undefined; last = now!; return fps; }; };
+const createFps = (meta: Meta) => createMonitor({ ...meta, label: meta.label ?? "FPS", get: frameRate(), view: "graph", min: 0, max: 120, decimals: 0 }, true); // ??: an explicit "" label renders none
+
+registerControl("fpsgraph", createFps);
+registerControl("monitor", (meta: Meta) => createMonitor(meta)); // the registry passes (meta, onChange), not perFrame

package/src/tweaks/controls/motion.ts

@@ -0,0 +1,141 @@
+// ── Motion — a transition's timing: an easing curve with a duration, or a spring, in one popover over one value. The
+// value carries the CSS it resolves to — `duration` in ms and an `easing` string, cubic-bezier() or a sampled linear(). Lazy. ──
+import { el, txt, clamp, isObj, createSegmented, getControl, popover, registerControl, REDUCE_MOTION } from "../shared.js";
+import { numField, triggerRow, svgEl, springCurve, springRun, timeFromSpring, notice, SPRING_DUR } from "../heavy.js";
+import { KEYWORDS } from "../easing.js";
+import type { OnChange } from "../shared.js";
+import type { Meta } from "../schema.js";
+import type { Control, MotionValue, MotionInput } from "../types.js";
+
+type Mode = "easing" | "spring";
+type Curve = [number, number, number, number];
+interface SpringOut { stiffness: number; damping: number; mass: number; visualDuration?: number; bounce?: number }
+
+const DUR_DEF = 300, DUR_MAX = 10000, STAGE_PAD = 16; // ms; the stage's side padding (tweaks.css)
+const BOUNCE_MAX = 1; // Motion's whole range: its damping-ratio floor of 0.05 keeps a bounce of 1 settling
+const has = (x: unknown) => (typeof x === "number" ? Number.isFinite(x) : typeof x === "string" && x.trim() !== "" && Number.isFinite(+x)); // a number, or a numeric string — not `true`, `[]` or " "
+const curveOf = (c: unknown): Curve | null => {
+  if (typeof c === "string") { const k = c === "linear" ? [0, 0, 1, 1] : KEYWORDS[c]; return k ? (k.slice() as Curve) : null; } // the CSS keywords, linear's identity included; null-prototype, so "constructor" is not one
+  if (Array.isArray(c) && c.length === 4) { const m = c.map(Number); return m.every(Number.isFinite) ? (m as Curve) : null; }
+  return null;
+};
+const springKeys = (v: MotionInput) => has(v.stiffness) || has(v.damping) || has(v.mass) || has(v.visualDuration) || has(v.bounce);
+// Physics keys map to the visualDuration + bounce Motion would resolve to them (timeFromSpring). An explicit duration/bounce wins.
+const springTime = (v: MotionInput) => {
+  const out: { mode: "time"; visualDuration?: number; bounce?: number } = { mode: "time" };
+  if (has(v.stiffness)) { const k = +v.stiffness!, m = has(v.mass) ? +v.mass! : 1, t = timeFromSpring(k, has(v.damping) ? +v.damping! : 2 * Math.sqrt(k * m), m); out.visualDuration = t.visualDuration; if (has(v.damping)) out.bounce = clamp(t.bounce, -1, BOUNCE_MAX); }
+  if (has(v.visualDuration)) out.visualDuration = +v.visualDuration!;
+  if (has(v.bounce)) out.bounce = clamp(+v.bounce!, -1, BOUNCE_MAX);
+  return out;
+};
+// A stiffness and damping the host wrote, kept as written rather than resolved through the editor's time pair, which
+// rounds and clamps: unless a time pair rides along that isn't the one they resolve to (this control's own value back).
+const exactSpring = (v: MotionInput): SpringOut | null => {
+  if (!has(v.stiffness) || !has(v.damping)) return null;
+  const k = +v.stiffness!, d = +v.damping!, m = has(v.mass) ? +v.mass! : 1;
+  if (!(k > 0 && d >= 0 && m > 0)) return null;
+  const t = timeFromSpring(k, d, m), off = (a: unknown, b: number) => has(a) && Math.abs(+a! - b) > 1e-6 * Math.max(1, Math.abs(b));
+  return off(v.visualDuration, t.visualDuration) || off(v.bounce, t.bounce) ? null : { stiffness: k, damping: d, mass: m, ...t };
+};
+const modeOf = (v: MotionInput, keep: Mode): Mode => (v.mode === "spring" || v.mode === "easing" ? v.mode : springKeys(v) ? "spring" : curveOf(v.curve) ? "easing" : keep); // a curve that doesn't parse is no reason to switch
+
+function createMotion(meta: Meta, onChange: OnChange): Control {
+  const Bezier = getControl("cubicbezier"), Spring = getControl("spring");
+  if (!Bezier || !Spring) throw new Error("[tweaks] motion: the bezier and spring controls are not loaded");
+  const init: MotionInput = isObj(meta.value) ? meta.value : {};
+  let mode = modeOf(init, "easing");
+  let curve = curveOf(init.curve) ?? (KEYWORDS.ease.slice() as Curve), dur = has(init.duration) ? clamp(+init.duration!, 0, DUR_MAX) : DUR_DEF;
+
+  // ── Row — label, a mini curve, a summary. ──
+  const { root, trigger, right } = triggerRow("tw-motion", meta.label ?? "Motion"); // ??: an explicit "" label renders none
+  const chip = el("span", "tw-trigger-chip tw-motion-chip");
+  const chipSvg = svgEl("svg"); chipSvg.setAttribute("viewBox", "0 0 100 100"); chipSvg.setAttribute("preserveAspectRatio", "none");
+  const chipPath = svgEl("path"); chipSvg.append(chipPath); chip.append(chipSvg);
+  const valueEl = el("span", "tw-trigger-value");
+  right.append(chip, valueEl);
+
+  // ── Popover — the mode switch, the preview, one editor at a time. ──
+  const pop = el("div", "tw-color-pop tw-motion-pop"), body = el("div", "tw-motion-body"); pop.append(body);
+  const bezier = Bezier({ ...meta, type: "cubicbezier", label: "", value: curve.slice() } as Meta, (v) => { curve = v as Curve; update(); emit(); });
+  curve = bezier.get() as Curve; // as the editor fitted it, so no invalid cubic-bezier()
+  // Host-written physics the editor can't draw exactly: it shows the nearest, clamped here so it doesn't warn as well.
+  let exact: SpringOut | null = null, said = false;
+  const editorTime = (inp: MotionInput) => {
+    exact = exactSpring(inp);
+    if (!exact) return springTime(inp);
+    const vd = clamp(exact.visualDuration!, SPRING_DUR[0], SPRING_DUR[1]), z = exact.damping / (2 * Math.sqrt(exact.stiffness * exact.mass));
+    if ((vd !== exact.visualDuration || z < 0.05 || z > 20) && !said) { said = true; notice("springKept", [meta.key, exact.stiffness, exact.damping, exact.mass]); }
+    return { mode: "time" as const, visualDuration: vd, bounce: exact.bounce };
+  };
+  // Time mode only; its Mode row is hidden (tweaks.css). An edit there drops the kept physics.
+  const spring = Spring({ ...meta, type: "spring", label: "", value: editorTime(init) } as Meta, () => { exact = null; update(); emit(); });
+  const springNow = () => exact ?? (spring.get() as SpringOut);
+  const durFld = numField({ label: "Duration", value: dur, step: 10, min: 0, max: DUR_MAX, unit: "ms" }, (v) => { dur = clamp(v, 0, DUR_MAX); update(); emit(); });
+  dur = durFld.get(); // as the field snapped it
+  const easingPane = el("div", "tw-motion-pane"), springPane = el("div", "tw-motion-pane"), durRow = el("div", "tw-fields");
+  durRow.append(durFld.el); easingPane.append(bezier.el, durRow); springPane.append(spring.el);
+  const stage = el("div", "tw-motion-stage"), box = el("div", "tw-motion-box"); stage.append(box);
+  const modeSeg = createSegmented([{ value: "easing", label: "Easing" }, { value: "spring", label: "Spring" }], mode, (m: unknown) => { if ((m === "easing" || m === "spring") && m !== mode) { mode = m; showMode(); update(); emit(); } }, "Motion type");
+  const typeRow = el("div", "tw-row"); typeRow.append(txt("span", "tw-row-label", "Type"), modeSeg.el);
+  body.append(typeRow, easingPane, springPane, stage);
+  root.append(pop);
+
+  const value = (): MotionValue => {
+    if (mode === "easing") return { mode, curve: curve.slice() as Curve, duration: dur, easing: `cubic-bezier(${curve.join(", ")})` };
+    // The run lasts until the spring is at rest (the drawn curve stops at 2.2 s): springRun.
+    const s = springNow();
+    return { mode, ...s, ...springRun(s.stiffness, s.damping, s.mass) };
+  };
+  const emit = () => onChange(value());
+
+  // Web Animations, no frame loop to own. A click or an open flips direction and restarts; an edit lets a run in flight
+  // finish — a handle drag fires per pointer move, and restarting each strobed the box.
+  let far = false, anim: Animation | null = null;
+  const replay = (flip: boolean) => {
+    if (flip) far = !far; else if (anim && anim.playState === "running") return;
+    const v = value();
+    const travel = Math.max(0, stage.clientWidth - box.offsetWidth - 2 * STAGE_PAD); // measured now: the stage is 0 wide until the pop opens
+    const from = `translateX(${far ? 0 : travel}px)`, to = `translateX(${far ? travel : 0}px)`;
+    if (REDUCE_MOTION.matches || typeof box.animate !== "function") { box.style.transform = to; return; }
+    anim?.cancel();
+    const frames = [{ transform: from }, { transform: to }];
+    try { anim = box.animate(frames, { duration: v.duration, easing: v.easing, fill: "forwards" }); }
+    catch { anim = box.animate(frames, { duration: v.duration, fill: "forwards" }); } // no linear() support: a plain run rather than nothing
+  };
+  stage.addEventListener("click", () => replay(true));
+  stage.tabIndex = 0; stage.setAttribute("role", "button"); stage.setAttribute("aria-label", "Replay the motion");
+  stage.addEventListener("keydown", (e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); replay(true); } });
+
+  // The chip's mini curve, y up, scaled so an overshoot still fits.
+  const curvePath = () => {
+    let pts: [number, number][];
+    if (mode === "easing") { const [x1, y1, x2, y2] = curve; pts = []; for (let i = 0; i <= 24; i++) { const t = i / 24, u = 1 - t, a = 3 * u * u * t, b = 3 * u * t * t, c = t * t * t; pts.push([a * x1 + b * x2 + c, a * y1 + b * y2 + c]); } }
+    else { const s = springNow(); pts = springCurve(s.stiffness, s.damping, s.mass, 32).map((y, i) => [i / 31, y]); }
+    const hi = Math.max(1, ...pts.map((p) => p[1])), lo = Math.min(0, ...pts.map((p) => p[1]));
+    return pts.map(([x, y], i) => `${i ? "L" : "M"}${(10 + x * 80).toFixed(1)},${(90 - ((y - lo) / (hi - lo)) * 80).toFixed(1)}`).join(" ");
+  };
+  // The revealed editor built at 0×0 and onLive may have dropped its resize listener while the pop was detached, so
+  // re-point it at its own value, which redraws at real size.
+  const resync = () => { if (mode === "easing") bezier.set(curve.slice()); else spring.set(spring.get()); };
+  const showMode = () => { easingPane.style.display = mode === "easing" ? "" : "none"; springPane.style.display = mode === "spring" ? "" : "none"; resync(); };
+  // The summary shows the authored duration; a spring's emitted run (its settle) is longer.
+  const summary = () => (mode === "easing" ? `Easing · ${dur} ms` : `Spring · ${Math.round((springNow().visualDuration ?? 0) * 1000)} ms`);
+  const update = () => { chipPath.setAttribute("d", curvePath()); valueEl.textContent = summary(); replay(false); };
+
+  popover(root, trigger, pop, { fallbackH: 380, onOpen: () => { modeSeg.set(mode); resync(); replay(true); }, initialFocus: () => modeSeg.el.querySelector<HTMLElement>('[tabindex="0"]') }); // hidden until open: measure now; focus the checked option
+  showMode(); update();
+
+  // Set/restore: either mode's shape or a bare keyword; derived fields (easing, a spring's duration) are ignored.
+  const set = (v: unknown) => {
+    const inp: MotionInput | null = typeof v === "string" ? { curve: v } : Array.isArray(v) && v.length === 4 ? { curve: v as Curve } : isObj(v) ? v : null; // a bare 4-array is the bezier's own shape
+    if (!inp) return;
+    mode = modeOf(inp, mode);
+    const c = curveOf(inp.curve); if (c) { bezier.set(c.slice()); curve = bezier.get() as Curve; } // read back fitted
+    if (mode === "easing" && has(inp.duration)) { durFld.set(clamp(+inp.duration!, 0, DUR_MAX)); dur = durFld.get(); } // read back snapped
+    if (springKeys(inp)) spring.set(editorTime(inp));
+    modeSeg.set(mode); showMode(); update();
+  };
+  return { el: root, set, get: value, destroy: () => spring.destroy && spring.destroy() };
+}
+
+registerControl("motion", createMotion);

package/src/tweaks/controls/plot.ts

@@ -0,0 +1,220 @@
+// ── Plot — graph y=f(x) with a safe expression evaluator (compileExpr). Lazy.
+import { el, txt, clamp, onReady, onLive, quietFocus, registerControl } from "../shared.js";
+import { svgEl } from "../heavy.js";
+import type { OnChange, Built } from "../shared.js";
+import type { Meta } from "../schema.js";
+import type { Control } from "../types.js";
+
+/** A compiled expression: y for an x. */
+type Expr = (x: number) => number;
+/** The tokens the expression lexer emits. */
+type Tok = { t: "num"; v: number } | { t: "id" | "op"; v: string } | { t: "lp" | "rp" | "comma"; v?: undefined };
+
+// ── A safe expression evaluator: recursive descent, not eval/Function, so a typed formula does only arithmetic and
+// whitelisted Math calls. Null-prototype tables, so "constructor" can't parse as an identifier. ──
+const PLOT_FUNCS: Record<string, (...args: number[]) => number> = Object.assign(Object.create(null), {
+  sin: Math.sin, cos: Math.cos, tan: Math.tan, asin: Math.asin, acos: Math.acos,
+  atan: Math.atan, atan2: Math.atan2, sinh: Math.sinh, cosh: Math.cosh, tanh: Math.tanh,
+  sqrt: Math.sqrt, cbrt: Math.cbrt, abs: Math.abs, exp: Math.exp, log: Math.log, ln: Math.log,
+  log10: Math.log10, log2: Math.log2, floor: Math.floor, ceil: Math.ceil, round: Math.round,
+  sign: Math.sign, trunc: Math.trunc, min: Math.min, max: Math.max, pow: Math.pow, hypot: Math.hypot,
+  mod: (a: number, b: number) => a % b, clamp: (v: number, lo: number, hi: number) => Math.min(Math.max(v, lo), hi),
+});
+const PLOT_VARIADIC = ["min", "max", "hypot"]; // called empty these return a number (Infinity, 0), so a slip drew nothing and flagged nothing
+const PLOT_CONSTS: Record<string, number> = Object.assign(Object.create(null), { pi: Math.PI, e: Math.E, tau: Math.PI * 2, phi: (1 + Math.sqrt(5)) / 2 });
+/** The compiled expression, or null on any parse error. */
+export function compileExpr(src: unknown): Expr | null {
+  const r = parseExpr(src); return typeof r === "function" ? r : null;
+}
+/** The compiled expression, or why it doesn't parse; the reason names the fix where there is one ("write sin(…)"). */
+export function parseExpr(src: unknown): Expr | string {
+  if (typeof src !== "string" || !src.trim()) return "type an expression in x";
+  if (src.length > 512) return "too long: 512 characters at most"; // also bounds recursion depth, so no RangeError mid-parse
+  const s = src, toks: Tok[] = [];
+  // `5.` reads as 5, as `.5` reads as 0.5. An e is an exponent only with a digit right after it (and its sign): `2e+1` is
+  // 20, while `2e+x` is the constant, 2·e + x, as `2e` alone is 2·e. Scientific notation never has a name for its power.
+  const numRe = /(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/y, idRe = /[A-Za-z_]\w*/y;
+  let i = 0;
+  while (i < s.length) {
+    const ch = s[i];
+    if (ch === " " || ch === "\t" || ch === "\n") { i++; continue; }
+    if ((ch >= "0" && ch <= "9") || (ch === "." && s[i + 1] >= "0" && s[i + 1] <= "9")) {
+      numRe.lastIndex = i; const m = numRe.exec(s); if (!m || m.index !== i) return `unexpected "${ch}"`;
+      toks.push({ t: "num", v: parseFloat(m[0]) }); i = numRe.lastIndex; continue;
+    }
+    if ((ch >= "A" && ch <= "Z") || (ch >= "a" && ch <= "z") || ch === "_") {
+      idRe.lastIndex = i; const m = idRe.exec(s); toks.push({ t: "id", v: m[0] }); i = idRe.lastIndex; continue;
+    }
+    if (ch === "*" && s[i + 1] === "*") { toks.push({ t: "op", v: "^" }); i += 2; continue; }
+    if ("+-*/%^".includes(ch)) { toks.push({ t: "op", v: ch }); i++; continue; }
+    if (ch === "(") { toks.push({ t: "lp" }); i++; continue; }
+    if (ch === ")") { toks.push({ t: "rp" }); i++; continue; }
+    if (ch === ",") { toks.push({ t: "comma" }); i++; continue; }
+    return `unexpected "${ch}"`;
+  }
+  let p = 0, why = "";
+  const fail = (m: string): null => { why = why || m; return null; }; // the innermost reason wins; every caller unwinds on null
+  const peek = () => toks[p];
+  const eat = (t?: Tok["t"]) => { const tok = toks[p]; if (!tok || (t && tok.t !== t)) return null; p++; return tok; };
+  const add = (): Expr | null => {
+    let a = mul(); if (!a) return null;
+    while (peek() && peek().t === "op" && (peek().v === "+" || peek().v === "-")) {
+      const op = eat("op").v, b = mul(); if (!b) return null; const aa = a;
+      a = op === "+" ? (x) => aa(x) + b(x) : (x) => aa(x) - b(x);
+    }
+    return a;
+  };
+  const mul = (): Expr | null => {
+    let a = unary(); if (!a) return null;
+    for (let t = peek(); t; t = peek()) {
+      // `2x`, `2pi`, `3(x+1)`, `pi x`, `3x(x)`, `(x)(x)`, `sin(x)cos(x)`: a number, x, a constant or ")" directly before
+      // a name or "(" multiplies, as on paper. x and the constants are never functions, so `x(2)` is 2x; `xy` stays one
+      // (unknown) name, and a number after an operand (`2 3`, `(x)2`) asks for an operator. It binds as `*` does: `2x^2` is 2·x².
+      const prev = toks[p - 1].t, implied = (prev === "num" || prev === "id" || prev === "rp") && (t.t === "id" || t.t === "lp");
+      if (!implied && !(t.t === "op" && (t.v === "*" || t.v === "/" || t.v === "%"))) break;
+      const op = implied ? "*" : eat("op").v, b = unary(); if (!b) return null; const aa = a;
+      a = op === "*" ? (x) => aa(x) * b(x) : op === "/" ? (x) => aa(x) / b(x) : (x) => aa(x) % b(x);
+    }
+    return a;
+  };
+  const unary = (): Expr | null => {
+    if (peek() && peek().t === "op" && (peek().v === "-" || peek().v === "+")) {
+      const op = eat("op").v, a = unary(); if (!a) return null;
+      return op === "-" ? (x) => -a(x) : a;
+    }
+    return pow();
+  };
+  const pow = (): Expr | null => {
+    const a = atom(); if (!a) return null;
+    if (peek() && peek().t === "op" && peek().v === "^") { eat("op"); const b = unary(); if (!b) return null; return (x) => Math.pow(a(x), b(x)); }
+    return a;
+  };
+  const atom = (): Expr | null => {
+    const tok = peek(); if (!tok) return null;
+    if (tok.t === "num") { eat("num"); return () => tok.v; }
+    if (tok.t === "lp") { eat("lp"); const e = add(); if (!e || !eat("rp")) return null; return e; }
+    if (tok.t === "id") {
+      eat("id"); const name = tok.v.toLowerCase(), fn = PLOT_FUNCS[name];
+      if (peek() && peek().t === "lp" && (fn || (name !== "x" && !(name in PLOT_CONSTS)))) { // `x(2)`: a product, in mul()
+        if (!fn) return fail(`unknown function "${tok.v}"`);
+        eat("lp"); const argv: Expr[] = [];
+        if (peek() && peek().t !== "rp") { do { const a = add(); if (!a) return null; argv.push(a); } while (eat("comma")); }
+        if (!eat("rp")) return null;
+        if (!argv.length && PLOT_VARIADIC.includes(name)) return fail(`${name}() needs at least one value`);
+        return (x) => fn(...argv.map((a) => a(x)));
+      }
+      if (fn) {
+        // `sin x`, `cos 2x`: a one-argument function takes a bare x, constant or number-times-name, as a calculator does.
+        // Anything longer (`sin x^2`, `sin -x`, `sin 2 cos x`) reads two ways, so it asks for the parentheses instead of guessing.
+        const a = fn.length === 1 ? bare() : null, n = peek();
+        if (!a || (n && (n.t === "op" ? n.v === "^" : n.t !== "rp" && n.t !== "comma"))) return fail(`write ${name}(…)`);
+        return (x) => fn(a(x));
+      }
+      if (name === "x") return (x) => x;
+      if (name in PLOT_CONSTS) { const c = PLOT_CONSTS[name]; return () => c; }
+      return fail(`unknown name "${tok.v}"`); // an identifier that isn't x, a constant, or a known function
+    }
+    return null;
+  };
+  const named = (t: Tok) => t && t.t === "id" && !PLOT_FUNCS[t.v.toLowerCase()];
+  const bare = (): Expr | null => {
+    const t = peek();
+    if (t && t.t === "num") { eat("num"); if (!named(peek())) return () => t.v; const b = atom(); return b && ((x) => t.v * b(x)); }
+    return named(t) ? atom() : null;
+  };
+  const tree = add(), left = toks[p];
+  if (tree && !left) return tree;
+  if (why) return why;
+  // A parse that stopped short, or tokens left over: say where.
+  const last = toks[p - 1], unclosed = toks.slice(0, p).reduce((d, t) => d + (t.t === "lp" ? 1 : t.t === "rp" ? -1 : 0), 0);
+  if (!tree && last && last.t === "op") return `"${last.v}" needs a value on each side`;
+  if (!left) return unclosed > 0 ? 'missing ")"' : "not a valid expression";
+  return left.t === "num" ? `missing an operator before ${left.v}`
+    : left.t === "rp" ? (last && last.t === "lp" ? "nothing inside the parentheses" : 'unmatched ")"')
+    : left.t === "comma" ? '"," outside a function\'s parentheses'
+    : left.t === "op" ? `"${left.v}" needs a value on each side` : "not a valid expression";
+}
+
+// ── Plot — y = f(x) across a range with an editable expression, or a fixed `fn`. Y auto-ranges unless yMin/yMax are
+// given; the line breaks across asymptotes. ──
+function createPlot(meta: Meta, onChange: OnChange): Control {
+  // Non-finite bounds take the defaults, an inverted pair swaps, an equal pair pads out (÷0 drew nothing); a degenerate y-range falls back to auto.
+  let xMin = Number(meta.xMin ?? meta.min), xMax = Number(meta.xMax ?? meta.max); // min/max are the verbose form's aliases
+  if (!Number.isFinite(xMin)) xMin = -10;
+  if (!Number.isFinite(xMax)) xMax = 10;
+  if (xMax < xMin) { const t = xMin; xMin = xMax; xMax = t; }
+  if (xMax === xMin) { xMin -= 1; xMax += 1; }
+  const samples = Math.max(2, Math.min(4096, (meta.samples | 0) || 256)); // capped: 1e8 samples per keystroke froze the tab
+  const fixedY = Number.isFinite(meta.yMin) && Number.isFinite(meta.yMax) && +meta.yMax > +meta.yMin;
+  const fn = typeof meta.fn === "function" ? meta.fn : null;
+  const editable = meta.editable !== false && !fn;
+  let expr = meta.expr != null ? String(meta.expr) : fn ? "" : "sin(x)"; // a sine to start from
+  let compiled = fn || parseExpr(expr); // a string is the reason it doesn't parse
+
+  const root = el("div", "tw-plot");
+  if (meta.label) root.append(txt("div", "tw-plot-label", meta.label));
+  const graph = el("div", "tw-plot-graph");
+  const svg = svgEl("svg", "tw-plot-svg"); svg.setAttribute("preserveAspectRatio", "none");
+  const axisX = svgEl("line", "tw-plot-axis"), axisY = svgEl("line", "tw-plot-axis"), curve = svgEl("path", "tw-plot-curve");
+  svg.append(axisX, axisY, curve); graph.append(svg); root.append(graph);
+
+  let input: HTMLInputElement | null = null;
+  if (editable) {
+    const field = el("div", "tw-plot-field");
+    input = el("input", "tw-plot-input"); input.type = "text"; input.value = expr; input.spellcheck = false;
+    input.autocapitalize = "off"; quietFocus(input); /* click-to-edit stays ringless; Tab rings the field */ input.setAttribute("aria-label", `${meta.label || "Plot"} — expression in x`); input.setAttribute("aria-invalid", "false");
+    field.append(txt("span", "tw-plot-fx", "y ="), input); root.append(field); // txt, not el(…, html): el's third arg is innerHTML
+  }
+
+  const PAD = 6;
+  const draw = () => {
+    // Flag invalid before the size guard, so a hidden tab page still reports a bad expression.
+    const f = typeof compiled === "function" ? compiled : null, ok = !!f;
+    root.classList.toggle("is-invalid", editable && !ok);
+    if (input) { input.setAttribute("aria-invalid", ok ? "false" : "true"); input.title = ok ? "" : String(compiled); } // the title says why, and names the fix
+    const r = graph.getBoundingClientRect(), W = r.width, H = r.height; if (W < 2) return;
+    svg.setAttribute("viewBox", `0 0 ${W} ${H}`);
+    const ys: number[] = []; let yLo = Infinity, yHi = -Infinity;
+    if (ok) for (let k = 0; k < samples; k++) {
+      const x = xMin + (xMax - xMin) * (k / (samples - 1));
+      let y: number; try { y = f(x); } catch { y = NaN; }
+      ys.push(y);
+      if (Number.isFinite(y)) { if (y < yLo) yLo = y; if (y > yHi) yHi = y; }
+    }
+    let lo = meta.yMin, hi = meta.yMax;
+    if (!fixedY) {
+      if (!Number.isFinite(yLo) || yLo === yHi) { const c = Number.isFinite(yLo) ? yLo : 0; lo = c - 1; hi = c + 1; }
+      else { const pad = (yHi - yLo) * 0.12; lo = yLo - pad; hi = yHi + pad; }
+    }
+    const xPx = (x: number) => PAD + ((x - xMin) / (xMax - xMin)) * (W - 2 * PAD);
+    const yPx = (y: number) => (H - PAD) - ((y - lo) / (hi - lo)) * (H - 2 * PAD);
+    const axis = (ln: Built<SVGLineElement>, ax: number, ay: number, bx: number, by: number, show: boolean) => { ln.style.display = show ? "" : "none"; if (show) { ln.setAttribute("x1", ax); ln.setAttribute("y1", ay); ln.setAttribute("x2", bx); ln.setAttribute("y2", by); } };
+    axis(axisX, PAD, yPx(0), W - PAD, yPx(0), lo <= 0 && hi >= 0);
+    axis(axisY, xPx(0), PAD, xPx(0), H - PAD, xMin <= 0 && xMax >= 0);
+    let d = "", pen = false;
+    if (ok) for (let k = 0; k < samples; k++) {
+      const y = ys[k];
+      if (!Number.isFinite(y)) { pen = false; continue; }
+      const px = xPx(xMin + (xMax - xMin) * (k / (samples - 1))), py = clamp(yPx(y), -1e4, 1e4);
+      d += (pen ? "L" : "M") + px.toFixed(1) + "," + py.toFixed(1) + " "; pen = true;
+    }
+    curve.setAttribute("d", d);
+  };
+
+  if (editable) input.addEventListener("input", () => {
+    expr = input.value; compiled = parseExpr(expr); // a reason string on a parse error → draw flags is-invalid
+    draw(); onChange(expr);
+  });
+
+  onReady(draw);
+  onLive(root, [[window, "resize"], [window, "tw-reflow"]], draw); // tw-reflow: a tab page revealing this re-measures it
+
+  return {
+    el: root,
+    get: () => expr,
+    set: (v: unknown) => { if (v == null) return; expr = String(v); if (input) input.value = expr; if (!fn) compiled = parseExpr(expr); draw(); }, // an invalid expression flags, as typing does
+  };
+}
+
+registerControl("plot", createPlot);
+