@kitlangton/knobs 0.1.0 → 0.2.0

package/dist/index.js

@@ -497,7 +497,15 @@ function choice(value, options, meta) {
   }, meta);
 }
 function action(label, meta) {
-  return withMeta({ kind: "action", ...meta?.run ? { run: meta.run } : {} }, { ...meta, ...label !== void 0 ? { label } : {} });
+  let { shortcut, global, rebind, run, ...rest } = meta ?? {}, key = shortcutOf({ ...shortcut ? { shortcut } : {}, ...global ? { global } : {} }), combo = key ? normalizeCombo(key.key) : "";
+  if (key && !combo)
+    throw Error("An action's shortcut must name a key.");
+  return withMeta({
+    kind: "action",
+    ...run ? { run } : {},
+    ...key ? { shortcut: combo, scope: key.scope } : {},
+    ...rebind ? { rebind: !0 } : {}
+  }, { ...rest, ...label !== void 0 ? { label } : {} });
 }
 function flatSpring(parts = {}, meta = {}) {
   let id = meta.id ?? meta.label ?? `spring-${++springIds}`, half = (part, input, fallback) => {
@@ -523,7 +531,7 @@ function flatSpring(parts = {}, meta = {}) {
 }
 var springIds = 0;
 function toggle(value, meta) {
-  return withMeta({ kind: "toggle", value }, meta);
+  return withMeta({ kind: "toggle", value }, { ...meta, random: meta?.random ?? !1 });
 }
 function spring(value = {}, meta) {
   let field = { kind: "spring", value: { duration: 0.5, bounce: 0 } };
@@ -666,13 +674,19 @@ function curve(points, options = {}) {
     ...presets && Object.keys(presets).length ? { presets } : {}
   }, options);
 }
-function toolbarShortcut(item) {
-  let s = item.shortcut;
+function shortcutOf(o) {
+  let s = o.shortcut;
   if (!s)
     return;
   if (typeof s === "string")
-    return { key: s, scope: item.global ? "page" : "panel" };
-  return s.key ? { key: s.key, scope: s.scope ?? (item.global ? "page" : "panel") } : void 0;
+    return { key: s, scope: o.global ? "page" : "panel" };
+  return s.key ? { key: s.key, scope: s.scope ?? (o.global ? "page" : "panel") } : void 0;
+}
+function toolbarShortcut(item) {
+  return shortcutOf(item);
+}
+function actionShortcut(field) {
+  return field.shortcut ? { key: field.shortcut, scope: field.scope ?? "panel" } : void 0;
 }
 function toolbar(items, meta) {
   if (!items.length)
@@ -910,6 +924,139 @@ function springCss(value) {
   let { omega, zeta } = springMotion(value), { easing, ms } = springEasing(omega, zeta);
   return { easing, duration: ms };
 }
+// src/core/random.ts
+var lattice = (min, max, step, r) => min + Math.floor(r * (Math.floor((max - min) / step + 0.000000001) + 1)) * step, between2 = (min, max, r) => min + (max - min) * r;
+function pick(field, random) {
+  let r = () => Math.max(0, Math.min(1 - Number.EPSILON, random()));
+  switch (field.kind) {
+    case "knob":
+      return lattice(field.min, field.max, field.step, r());
+    case "choice":
+      return field.options[Math.floor(r() * field.options.length)];
+    case "toggle":
+      return r() >= 0.5;
+    case "spring":
+      return { duration: between2(0.2, 0.9, r()), bounce: between2(0, 0.45, r()) };
+    case "color": {
+      let l = between2(0.5, 0.85, r()), h = between2(0, 360, r());
+      return { l, c: between2(0.25, 0.85, r()) * maxChroma(l, h), h };
+    }
+    case "point":
+      return {
+        x: lattice(field.min.x, field.max.x, field.step.x, r()),
+        y: lattice(field.min.y, field.max.y, field.step.y, r())
+      };
+    case "easing": {
+      let curves = Object.values(EASINGS);
+      return curves[Math.floor(r() * curves.length)];
+    }
+    case "vec": {
+      let axis = () => lattice(field.min, field.max, field.step, r());
+      return field.axes === 3 ? { x: axis(), y: axis(), z: axis() } : { x: axis(), y: axis() };
+    }
+    case "range":
+      return [
+        lattice(field.min, field.max, field.step, r()),
+        lattice(field.min, field.max, field.step, r())
+      ];
+    case "angle": {
+      let top = field.wrap ? field.max - field.step : field.max;
+      return lattice(field.min, Math.max(field.min, top), field.step, r());
+    }
+    case "seed":
+      return lattice(field.min, field.max, 1, r());
+    case "keybind":
+      return field.value;
+    case "gradient":
+      return randomStops(field.value.length, r);
+    case "curve":
+      return randomPoints(field.range, r);
+  }
+}
+var AROUND = {
+  spread: 0.35,
+  switch: 0.3,
+  hue: 20,
+  lightness: 0.06,
+  chroma: 0.15
+};
+function near(v, min, max, step, r, reach = max - min) {
+  let span = max - min;
+  if (!(span > 0))
+    return v;
+  let width = Math.min(span, reach * AROUND.spread), lo = Math.max(min, Math.min(max - width, v - width / 2)), top = Math.floor(span / step + 0.000000001), a = Math.max(0, Math.ceil((lo - min) / step - 0.000000001)), b = Math.min(top, Math.floor((lo + width - min) / step + 0.000000001)), n = b < a ? Math.round((v - min) / step) : a + Math.floor(r * (b - a + 1));
+  return Number((min + Math.max(0, Math.min(top, n)) * step).toPrecision(14));
+}
+var unit = (r) => r * 2 - 1;
+function around(field, base, random) {
+  let r = () => Math.max(0, Math.min(1 - Number.EPSILON, random()));
+  switch (field.kind) {
+    case "knob":
+      return near(base, field.min, field.max, field.step, r());
+    case "choice": {
+      if (field.options.length < 2 || r() >= AROUND.switch)
+        return base;
+      let rest = field.options.filter((o) => o !== base);
+      return rest[Math.floor(r() * rest.length)];
+    }
+    case "toggle":
+      return r() < AROUND.switch ? !base : base;
+    case "spring": {
+      let s = base, d = SPRING.duration, b = SPRING.bounce;
+      return {
+        duration: near(s.duration, d.min, d.max, d.step, r(), 0.7),
+        bounce: near(s.bounce, b.min, b.max, b.step, r(), 0.45)
+      };
+    }
+    case "color": {
+      let c = parseColor(base) ?? { l: 0.7, c: 0.1, h: 0 }, max0 = maxChroma(c.l, c.h), rel = max0 > 0.0001 ? Math.min(1, Math.max(0, c.c / max0)) : 0.5, h = (c.h + unit(r()) * AROUND.hue + 360) % 360, l = Math.min(1, Math.max(0, c.l + unit(r()) * AROUND.lightness)), k = Math.min(1, Math.max(0, rel + unit(r()) * AROUND.chroma));
+      return { l, c: k * maxChroma(l, h), h };
+    }
+    case "point": {
+      let p = base;
+      return {
+        x: near(p.x, field.min.x, field.max.x, field.step.x, r()),
+        y: near(p.y, field.min.y, field.max.y, field.step.y, r())
+      };
+    }
+    case "easing":
+      return base.map((v, i) => {
+        let [lo, hi] = i % 2 === 0 ? [0, 1] : EASING_Y;
+        return near(v, lo, hi, 0.001, r());
+      });
+    case "vec": {
+      let v = base, axis = (n) => near(n, field.min, field.max, field.step, r());
+      return field.axes === 3 ? { x: axis(v.x), y: axis(v.y), z: axis(v.z ?? 0) } : { x: axis(v.x), y: axis(v.y) };
+    }
+    case "range": {
+      let [a, b] = base;
+      return [
+        near(a, field.min, field.max, field.step, r()),
+        near(b, field.min, field.max, field.step, r())
+      ];
+    }
+    case "angle": {
+      let v = base;
+      if (!field.wrap)
+        return near(v, field.min, field.max, field.step, r());
+      let span = field.max - field.min;
+      return v + unit(r()) * span * (AROUND.spread / 2);
+    }
+    case "gradient":
+      return mutateStops(base, r, [AROUND.hue / 2, AROUND.hue], [AROUND.lightness / 2, AROUND.lightness]);
+    case "curve":
+      return mutatePoints(base, field.range, r, [
+        AROUND.spread / 2,
+        AROUND.spread
+      ]);
+    case "seed":
+    case "keybind":
+      return pick(field, random);
+  }
+}
+function randomValues(schema, random = Math.random) {
+  return normalize(schema, Object.fromEntries(Object.entries(schema).flatMap(([key, field]) => hasValue(field) ? [[key, pick(field, random)]] : [])));
+}
 // src/core/code.ts
 var literal = (value) => Array.isArray(value) ? `[${value.map(literal).join(", ")}]` : typeof value === "object" && value !== null ? `{ ${Object.entries(value).map(([k, v]) => `${k}: ${literal(v)}`).join(", ")} }` : JSON.stringify(value);
 function formatCode(values, format = "ts") {
@@ -933,12 +1080,12 @@ var MUTATE = {
   chroma: 0.02,
   lightness: [0.015, 0.045],
   bezier: [0.03, 0.06]
-}, between2 = (min, max, r) => min + (max - min) * r, signed2 = (random) => random() < 0.5 ? -1 : 1;
+}, between3 = (min, max, r) => min + (max - min) * r, signed2 = (random) => random() < 0.5 ? -1 : 1;
 function nudge(v, min, max, step, random, reach = max - min) {
   let span = max - min;
   if (!(span > 0))
     return v;
-  let sign = signed2(random), by = reach * between2(MUTATE.min, MUTATE.max, random()), next = v + sign * by;
+  let sign = signed2(random), by = reach * between3(MUTATE.min, MUTATE.max, random()), next = v + sign * by;
   if (next > max || next < min)
     next = v - sign * by;
   let top = Math.floor(span / step + 0.000000001), at = (n) => Number((min + n * step).toPrecision(14)), steps = Math.max(0, Math.min(top, Math.round((next - min) / step)));
@@ -967,12 +1114,12 @@ function shift(field, value, random) {
       };
     }
     case "color": {
-      let c = parseColor(value) ?? { l: 0.7, c: 0.1, h: 0 }, max0 = maxChroma(c.l, c.h), rel0 = max0 > 0.0001 ? Math.min(1, Math.max(0, c.c / max0)) : 0.5, h = (c.h + signed2(random) * between2(MUTATE.hue[0], MUTATE.hue[1], random()) + 360) % 360, l = Math.min(1, Math.max(0, c.l + signed2(random) * between2(MUTATE.lightness[0], MUTATE.lightness[1], random())));
+      let c = parseColor(value) ?? { l: 0.7, c: 0.1, h: 0 }, max0 = maxChroma(c.l, c.h), rel0 = max0 > 0.0001 ? Math.min(1, Math.max(0, c.c / max0)) : 0.5, h = (c.h + signed2(random) * between3(MUTATE.hue[0], MUTATE.hue[1], random()) + 360) % 360, l = Math.min(1, Math.max(0, c.l + signed2(random) * between3(MUTATE.lightness[0], MUTATE.lightness[1], random())));
       return { l, c: nudge(rel0, 0, 1, 0.01, random) * maxChroma(l, h), h };
     }
     case "easing":
       return value.map((v, i) => {
-        let [lo, hi] = i % 2 === 0 ? [0, 1] : EASING_Y, next = v + signed2(random) * between2(MUTATE.bezier[0], MUTATE.bezier[1], random());
+        let [lo, hi] = i % 2 === 0 ? [0, 1] : EASING_Y, next = v + signed2(random) * between3(MUTATE.bezier[0], MUTATE.bezier[1], random());
         return Math.min(hi, Math.max(lo, next));
       });
     case "choice": {
@@ -998,7 +1145,7 @@ function shift(field, value, random) {
       if (!field.wrap)
         return nudge(v, field.min, field.max, field.step, random);
       let span = field.max - field.min;
-      return v + signed2(random) * span * between2(MUTATE.min, MUTATE.max, random());
+      return v + signed2(random) * span * between3(MUTATE.min, MUTATE.max, random());
     }
     case "seed":
       return nudge(value, field.min, field.max, 1, random);
@@ -1040,59 +1187,6 @@ function mutateValues(schema, current, keys = valueKeys(schema), random = Math.r
   return out;
 }
 
-// src/core/random.ts
-var lattice = (min, max, step, r) => min + Math.floor(r * (Math.floor((max - min) / step + 0.000000001) + 1)) * step, between3 = (min, max, r) => min + (max - min) * r;
-function pick(field, random) {
-  let r = () => Math.max(0, Math.min(1 - Number.EPSILON, random()));
-  switch (field.kind) {
-    case "knob":
-      return lattice(field.min, field.max, field.step, r());
-    case "choice":
-      return field.options[Math.floor(r() * field.options.length)];
-    case "toggle":
-      return r() >= 0.5;
-    case "spring":
-      return { duration: between3(0.2, 0.9, r()), bounce: between3(0, 0.45, r()) };
-    case "color": {
-      let l = between3(0.5, 0.85, r()), h = between3(0, 360, r());
-      return { l, c: between3(0.25, 0.85, r()) * maxChroma(l, h), h };
-    }
-    case "point":
-      return {
-        x: lattice(field.min.x, field.max.x, field.step.x, r()),
-        y: lattice(field.min.y, field.max.y, field.step.y, r())
-      };
-    case "easing": {
-      let curves = Object.values(EASINGS);
-      return curves[Math.floor(r() * curves.length)];
-    }
-    case "vec": {
-      let axis = () => lattice(field.min, field.max, field.step, r());
-      return field.axes === 3 ? { x: axis(), y: axis(), z: axis() } : { x: axis(), y: axis() };
-    }
-    case "range":
-      return [
-        lattice(field.min, field.max, field.step, r()),
-        lattice(field.min, field.max, field.step, r())
-      ];
-    case "angle": {
-      let top = field.wrap ? field.max - field.step : field.max;
-      return lattice(field.min, Math.max(field.min, top), field.step, r());
-    }
-    case "seed":
-      return lattice(field.min, field.max, 1, r());
-    case "keybind":
-      return field.value;
-    case "gradient":
-      return randomStops(field.value.length, r);
-    case "curve":
-      return randomPoints(field.range, r);
-  }
-}
-function randomValues(schema, random = Math.random) {
-  return normalize(schema, Object.fromEntries(Object.entries(schema).flatMap(([key, field]) => hasValue(field) ? [[key, pick(field, random)]] : [])));
-}
-
 // src/core/internal.ts
 var RESHAPE = Symbol.for("knobs.reshape"), RESET_KEYS = Symbol.for("knobs.resetKeys"), REFRESHES = Symbol.for("knobs.refreshes");
 
@@ -1290,12 +1384,28 @@ function createVariants(schema, id, key, storage, get, set, notify, enabled) {
       });
       return persist([...list, variant]), variant;
     },
-    load(id) {
+    load(id, options) {
       read();
       let variant = list.find((v) => v.id === id);
       if (!variant)
         throw Error(`Unknown variant: ${id}`);
-      set(variant.values);
+      set(variant.values, id, Boolean(options?.coalesce));
+    },
+    rename(id, name) {
+      if (read(), name.length > 100)
+        throw Error("Variant names must be at most 100 characters.");
+      let at = list.findIndex((v) => v.id === id);
+      if (at < 0)
+        throw Error(`Unknown variant: ${id}`);
+      let was = list[at], trimmed = name.trim();
+      if ((was.name ?? "") === trimmed)
+        return;
+      let next = [...list];
+      next[at] = Object.freeze({
+        id: was.id,
+        ...trimmed ? { name: trimmed } : {},
+        values: was.values
+      }), persist(next);
     },
     remove(id) {
       read(), persist(list.filter((v) => v.id !== id));
@@ -1335,7 +1445,7 @@ function defineControls(id, input, options = {}) {
   let schema = Object.freeze({ ...input }), locked = normalize(schema, {}), actions = Object.freeze([...options.actions ?? []]), theme = options.theme ?? "dark", density = options.density ?? "default", renderer = options.renderer ?? "auto", enabled = () => Boolean(options.ship) && (typeof options.enabled === "function" ? options.enabled() : options.enabled ?? (Boolean(options.ship) || typeof location < "u" && ["localhost", "127.0.0.1", "[::1]"].includes(location.hostname))), storage = () => options.storage === void 0 ? browserStorage() : options.storage, persistMode = options.persist ?? "all", valueStorage = () => persistMode === "all" ? storage() : null, variantStorage = () => persistMode === "none" ? null : storage(), draw = options.random ?? Math.random, hostHistory = options.history, unsubscribeHistory, listeners = /* @__PURE__ */ new Set, refreshes = 0, notify = () => {
     for (let cb of [...listeners])
       cb();
-  }, mixed = /* @__PURE__ */ new Set, current = locked, read = !1, error = null, locks = /* @__PURE__ */ new Set, comparing = null, landing = !1, echo = Math.max(0, options.echo ?? 0), grabbed = /* @__PURE__ */ new Set, changedAt = /* @__PURE__ */ new Map, sent = /* @__PURE__ */ new Map, pending = /* @__PURE__ */ new Map, echoTimer, now = () => typeof performance < "u" ? performance.now() : Date.now(), isHeld = (key) => grabbed.has(key) || echo > 0 && now() - (changedAt.get(key) ?? -1 / 0) < echo, past = [], future = [], HISTORY = 100, stateKey = storageKey(id, "state"), buildPresets = () => Object.freeze(Object.fromEntries([
+  }, mixed = /* @__PURE__ */ new Set, current = locked, read = !1, error = null, locks = /* @__PURE__ */ new Set, bindings = /* @__PURE__ */ new Map, comparing = null, landing = !1, echo = Math.max(0, options.echo ?? 0), grabbed = /* @__PURE__ */ new Set, changedAt = /* @__PURE__ */ new Map, sent = /* @__PURE__ */ new Map, pending = /* @__PURE__ */ new Map, echoTimer, now = () => typeof performance < "u" ? performance.now() : Date.now(), isHeld = (key) => grabbed.has(key) || echo > 0 && now() - (changedAt.get(key) ?? -1 / 0) < echo, NO_BASE = Object.freeze({ preset: null, groups: Object.freeze({}) }), base = NO_BASE, past = [], future = [], HISTORY = 100, stateKey = storageKey(id, "state"), buildPresets = () => Object.freeze(Object.fromEntries([
     ["default", locked],
     ...Object.entries(options.presets ?? {}).map(([id, patch]) => {
       if (id === "default" || id === "custom")
@@ -1375,6 +1485,9 @@ function defineControls(id, input, options = {}) {
           if (data?.version === 1) {
             if (current = normalize(schema, data.values), Array.isArray(data.locks))
               locks = new Set(data.locks.filter((k) => typeof k === "string" && Object.hasOwn(schema, k)));
+            if (data.bindings && typeof data.bindings === "object")
+              bindings = new Map(Object.entries(data.bindings).flatMap(([id, combo]) => typeof combo === "string" && bindable(id) ? [[id, normalizeCombo(combo)]] : []));
+            base = readBase(data.base);
           }
         }
       } catch (cause) {
@@ -1393,7 +1506,9 @@ function defineControls(id, input, options = {}) {
       valueStorage()?.setItem(stateKey, JSON.stringify({
         version: 1,
         values: current,
-        ...locks.size ? { locks: [...locks] } : {}
+        ...locks.size ? { locks: [...locks] } : {},
+        ...bindings.size ? { bindings: Object.fromEntries(bindings) } : {},
+        ...base !== NO_BASE ? { base } : {}
       })), error = null;
     } catch (cause) {
       error = String(cause);
@@ -1402,6 +1517,74 @@ function defineControls(id, input, options = {}) {
   function commit(next) {
     current = next, persist(), notify();
   }
+  let makeBase = (preset, groups) => preset === null && Object.keys(groups).length === 0 ? NO_BASE : Object.freeze({ preset, groups: Object.freeze({ ...groups }) }), sameBase = (a, b) => a === b || a.preset?.kind === b.preset?.kind && a.preset?.id === b.preset?.id && Object.keys(a.groups).length === Object.keys(b.groups).length && Object.entries(a.groups).every(([g, i]) => b.groups[g] === i);
+  function validBase(b) {
+    let preset = b.preset?.kind === "preset" && !(b.preset.id !== "default" && Object.hasOwn(presets, b.preset.id)) ? null : b.preset, groups = Object.fromEntries(Object.entries(b.groups).filter(([g, i]) => groupPresets[g]?.[i] !== void 0)), next = makeBase(preset, groups);
+    return sameBase(next, b) ? b : next;
+  }
+  function readBase(raw) {
+    if (!raw || typeof raw !== "object")
+      return NO_BASE;
+    let { preset, groups } = raw, ref = preset && typeof preset === "object" && (preset.kind === "preset" || preset.kind === "variant") && typeof preset.id === "string" ? Object.freeze({ kind: preset.kind, id: preset.id }) : null, byGroup = groups && typeof groups === "object" ? Object.fromEntries(Object.entries(groups).filter((e) => Number.isInteger(e[1]))) : {};
+    return validBase(makeBase(ref, byGroup));
+  }
+  function activeBase() {
+    load();
+    let ref = base.preset;
+    if (ref?.kind === "variant" && !variants.list().some((v) => v.id === ref.id))
+      base = makeBase(null, base.groups);
+    return base;
+  }
+  let hasBase = () => activeBase() !== NO_BASE, baseCache;
+  function baseValues() {
+    if (!enabled())
+      return locked;
+    let b = activeBase();
+    if (b === NO_BASE)
+      return locked;
+    let list = b.preset?.kind === "variant" ? variants.list() : null, c = baseCache;
+    if (c && c.base === b && c.schema === schema && c.presets === presets && c.groupPresets === groupPresets && c.variants === list)
+      return c.values;
+    let out = locked, ref = b.preset;
+    if (ref?.kind === "preset" && Object.hasOwn(presets, ref.id))
+      out = presets[ref.id];
+    else if (ref?.kind === "variant") {
+      let found = list?.find((v) => v.id === ref.id);
+      if (found)
+        out = normalize(schema, found.values);
+    }
+    let groups = Object.entries(b.groups);
+    if (groups.length) {
+      out = { ...out };
+      for (let [g, i] of groups)
+        Object.assign(out, groupPresets[g]?.[i]?.values);
+    }
+    let values = Object.freeze(out);
+    return baseCache = { base: b, schema, presets, groupPresets, variants: list, values }, values;
+  }
+  let covered = (key) => {
+    let b = activeBase();
+    if (b.preset)
+      return !0;
+    let group = schema[key]?.group;
+    return group !== void 0 && Object.hasOwn(b.groups, group);
+  };
+  function declaredShortcut(id) {
+    let slash = id.indexOf("/"), key = slash < 0 ? id : id.slice(0, slash), field = Object.hasOwn(schema, key) ? schema[key] : void 0;
+    if (field?.kind === "action" && slash < 0)
+      return { found: !0, ...field.shortcut ? { combo: field.shortcut } : {} };
+    if (field?.kind === "toolbar" && slash >= 0) {
+      let item = field.items.find((i) => (i.id ?? i.label) === id.slice(slash + 1));
+      if (!item)
+        return { found: !1 };
+      let key = toolbarShortcut(item)?.key;
+      return { found: !0, ...key ? { combo: normalizeCombo(key) } : {} };
+    }
+    return { found: !1 };
+  }
+  function bindable(id) {
+    return declaredShortcut(id).found;
+  }
   let fieldKeys = () => valueKeys(schema), valueField = (k) => {
     let field = Object.hasOwn(schema, k) ? schema[k] : void 0;
     return field && hasValue(field) ? field : void 0;
@@ -1464,10 +1647,13 @@ function defineControls(id, input, options = {}) {
       pending.delete(k);
   };
   function set(patch, setOpts) {
+    write(patch, setOpts);
+  }
+  function write(patch, setOpts, nextBase) {
     if (!enabled())
       return;
     release();
-    let previous = load(), forced = mixed.size ? Object.keys(patch).filter((k) => mixed.has(k) && valueField(k)) : [];
+    let previous = load(), was = activeBase(), moves = nextBase !== void 0 && !sameBase(nextBase, was), forced = mixed.size ? Object.keys(patch).filter((k) => mixed.has(k) && valueField(k)) : [];
     for (let k of forced)
       mixed.delete(k);
     let applied = applyPatch(previous, previous, patch) ?? {
@@ -1477,9 +1663,10 @@ function defineControls(id, input, options = {}) {
     for (let k of forced)
       if (!(k in diff))
         diff[k] = next[k];
-    if (Object.keys(diff).length === 0)
+    let changed = Object.keys(diff).length > 0;
+    if (!changed && !moves)
       return;
-    if (next === previous) {
+    if (next === previous && !moves) {
       notify(), options.onChange?.(diff, next, {
         source: setOpts?.source ?? "local",
         ...setOpts?.key ? { key: setOpts.key } : {}
@@ -1487,16 +1674,27 @@ function defineControls(id, input, options = {}) {
       return;
     }
     if (!setOpts?.coalesce || past.length === 0) {
-      if (past.push(previous), past.length > HISTORY)
+      if (past.push({ values: previous, base: was }), past.length > HISTORY)
         past.shift();
     }
-    future.length = 0, markChanged(diff), commit(next), options.onChange?.(diff, next, {
+    if (future.length = 0, moves)
+      base = nextBase;
+    if (markChanged(diff), commit(next), !changed)
+      return;
+    options.onChange?.(diff, next, {
       source: setOpts?.source ?? "local",
       ...setOpts?.coalesce ? { coalesce: !0 } : {},
       ...setOpts?.key ? { key: setOpts.key } : {},
-      ...setOpts?.group ? { group: setOpts.group } : {}
+      ...setOpts?.group ? { group: setOpts.group } : {},
+      ...setOpts?.base ? { base: !0 } : {}
     });
   }
+  function step(to, source) {
+    let before = load(), left = { values: before, base: activeBase() }, diff = changes(before, to.values);
+    if (base = validBase(to.base), markChanged(diff), commit(to.values), Object.keys(diff).length)
+      options.onChange?.(diff, to.values, { source });
+    return left;
+  }
   function place(values, replace, land) {
     let previous = load(), applied = applyPatch(replace ? locked : previous, previous, values);
     if (!applied)
@@ -1604,7 +1802,7 @@ function defineControls(id, input, options = {}) {
       schema = Object.freeze({ ...next });
     if (changed) {
       let previous = load();
-      schema = Object.freeze({ ...next }), locked = normalize(schema, {}), presets = buildPresets(), groupPresets = buildGroupPresets();
+      schema = Object.freeze({ ...next }), locked = normalize(schema, {}), presets = buildPresets(), groupPresets = buildGroupPresets(), base = validBase(base);
       for (let k of [...locks])
         if (!valueField(k))
           locks.delete(k);
@@ -1639,7 +1837,30 @@ function defineControls(id, input, options = {}) {
     listen(cb) {
       return readoutListeners.add(cb), () => readoutListeners.delete(cb);
     }
-  }, controls = {
+  }, variants = createVariants(() => schema, id, storageKey(id, "variants"), variantStorage, get, (v, variant, coalesce) => write(v, { source: "variant", coalesce }, makeBase(Object.freeze({ kind: "variant", id: variant }), {})), notify, enabled), resettable = (keys) => (keys ?? fieldKeys()).filter((k) => valueField(k) && !blocked(k));
+  function offBase(keys) {
+    if (!hasBase())
+      return !1;
+    let cur = load(), b = baseValues();
+    return keys.some((k) => !same(cur[k], b[k]));
+  }
+  function toBase(keys, meta) {
+    let b = baseValues(), patch = Object.fromEntries(keys.map((k) => [k, b[k]]));
+    write(patch, { source: "reset", base: !0, ...meta });
+  }
+  function toDefaults(keys, nextBase) {
+    let patch = {};
+    for (let k of keys)
+      patch[k] = locked[k];
+    write(patch, { source: "reset" }, nextBase);
+    let resetKeys = options[RESET_KEYS];
+    if (resetKeys)
+      resetKeys(Object.keys(patch));
+    else
+      for (let key of Object.keys(patch))
+        options.onReset?.({ key });
+  }
+  let controls = {
     id,
     get schema() {
       return schema;
@@ -1741,8 +1962,7 @@ function defineControls(id, input, options = {}) {
       let previous = past.pop();
       if (!previous)
         return;
-      let before = load(), diff = changes(before, previous);
-      future.push(before), markChanged(diff), commit(previous), options.onChange?.(diff, previous, { source: "undo" });
+      future.push(step(previous, "undo"));
     },
     redo() {
       if (release(), hostHistory)
@@ -1750,8 +1970,7 @@ function defineControls(id, input, options = {}) {
       let next = future.pop();
       if (!next)
         return;
-      let before = load(), diff = changes(before, next);
-      past.push(before), markChanged(diff), commit(next), options.onChange?.(diff, next, { source: "redo" });
+      past.push(step(next, "redo"));
     },
     getServerSnapshot: () => locked,
     subscribe(cb) {
@@ -1765,22 +1984,15 @@ function defineControls(id, input, options = {}) {
     reset(keys) {
       if (!enabled())
         return;
+      let open = resettable(keys);
+      if (offBase(open))
+        return toBase(open, {});
       let skipped = fieldKeys().some(blocked);
       if (!keys && !skipped) {
-        set(locked, { source: "reset" }), options.onReset?.({});
+        write(locked, { source: "reset" }, NO_BASE), options.onReset?.({});
         return;
       }
-      let patch = {};
-      for (let k of keys ?? fieldKeys())
-        if (valueField(k) && !blocked(k))
-          patch[k] = locked[k];
-      set(patch, { source: "reset" });
-      let resetKeys = options[RESET_KEYS];
-      if (resetKeys)
-        resetKeys(Object.keys(patch));
-      else
-        for (let key of Object.keys(patch))
-          options.onReset?.({ key });
+      toDefaults(open, keys ? void 0 : NO_BASE);
     },
     resetKey(key) {
       if (!enabled())
@@ -1789,24 +2001,40 @@ function defineControls(id, input, options = {}) {
         throw Error(`Unknown control key: ${key}`);
       if (blocked(key))
         return;
+      if (offBase([key]))
+        return toBase([key], { key });
       set({ [key]: locked[key] }, { source: "reset", key }), options.onReset?.({ key });
     },
     resetGroup(group) {
       if (!enabled())
         return;
-      let keys = Object.keys(schema).filter((k) => schema[k].group === group && hasValue(schema[k])), open = keys.filter((k) => !blocked(k));
+      let keys = Object.keys(schema).filter((k) => schema[k].group === group && hasValue(schema[k])), open = keys.filter((k) => !blocked(k)), b = activeBase(), index = b.groups[group];
+      if (offBase(open)) {
+        toBase(open, { group });
+        let preset = index === void 0 ? void 0 : groupPresets[group]?.[index];
+        if (preset && index !== void 0)
+          options.onPreset?.({ group, index, name: preset.name });
+        return;
+      }
+      let { [group]: _, ...others } = b.groups, forget = index === void 0 ? void 0 : makeBase(b.preset, others);
       if (open.length < keys.length)
-        return controls.reset(open);
+        return toDefaults(open, forget);
       let patch = {};
       for (let k of keys)
         patch[k] = locked[k];
-      set(patch, { source: "reset", group }), options.onReset?.({ group });
+      write(patch, { source: "reset", group }, forget), options.onReset?.({ group });
     },
     isModified(key) {
-      let cur = get();
+      let cur = get(), b = baseValues();
       if (key !== void 0)
-        return !same(cur[key], locked[key]);
-      return !equal(cur, locked);
+        return !same(cur[key], b[key]);
+      return !equal(cur, b);
+    },
+    canReset(keys) {
+      if (!enabled())
+        return !1;
+      let cur = get(), b = baseValues();
+      return resettable(keys).some((k) => !same(cur[k], b[k]) || !same(cur[k], locked[k])) || !keys && hasBase();
     },
     modified() {
       let cur = get(), out = {};
@@ -1821,8 +2049,17 @@ function defineControls(id, input, options = {}) {
       let chosen = pool(keys);
       if (chosen.length === 0)
         return;
-      let sub = Object.fromEntries(chosen.map((k) => [k, schema[k]]));
-      set(randomValues(sub, draw), { source: "randomize" });
+      if (!hasBase()) {
+        let sub = Object.fromEntries(chosen.map((k) => [k, schema[k]]));
+        set(randomValues(sub, draw), { source: "randomize" });
+        return;
+      }
+      let b = baseValues(), patch = {};
+      for (let k of chosen) {
+        let field = valueField(k);
+        patch[k] = covered(k) ? around(field, b[k], draw) : pick(field, draw);
+      }
+      set(patch, { source: "randomize" });
     },
     mutate(keys) {
       if (!enabled())
@@ -1858,6 +2095,33 @@ function defineControls(id, input, options = {}) {
         return !1;
       return load(), locks.has(key);
     },
+    shortcut(key, item) {
+      let id = item === void 0 ? key : `${key}/${item}`, declared = declaredShortcut(id);
+      if (!declared.found)
+        return;
+      if (enabled())
+        load();
+      return (enabled() ? bindings.get(id) : void 0) ?? declared.combo;
+    },
+    rebind(key, combo, item) {
+      let id = item === void 0 ? key : `${key}/${item}`, declared = declaredShortcut(id);
+      if (!declared.found)
+        throw Error(`Not an action or toolbar button: ${id}`);
+      if (!enabled())
+        return;
+      load();
+      let next = combo === void 0 ? void 0 : normalizeCombo(combo);
+      if (combo !== void 0 && combo.trim() && !next)
+        throw Error(`Not a key combination: ${combo}`);
+      let was = bindings.get(id);
+      if (next === void 0 || next === (declared.combo ?? ""))
+        bindings.delete(id);
+      else
+        bindings.set(id, next);
+      if (bindings.get(id) === was)
+        return;
+      persist(), notify();
+    },
     canRoll(key) {
       if (!enabled())
         return !1;
@@ -1891,15 +2155,15 @@ function defineControls(id, input, options = {}) {
         return;
       if (!hold)
         return release();
-      let before = past.at(-1), now = load();
+      let before = past.at(-1)?.values, now = load();
       if (comparing || !before || equal(before, now))
         return;
       comparing = before, options.onChange?.(changes(now, before), before, { source: "compare" }), notify();
     },
-    preset(id) {
+    preset(id, presetOptions) {
       if (!Object.hasOwn(presets, id))
         throw Error(`Unknown preset: ${id}`);
-      set(presets[id], { source: "preset" });
+      write(presets[id], { source: "preset", coalesce: presetOptions?.coalesce }, id === "default" ? NO_BASE : makeBase(Object.freeze({ kind: "preset", id }), {}));
     },
     matchingPreset: () => Object.keys(presets).find((id) => equal(get(), presets[id])) ?? "custom",
     get groupPresets() {
@@ -1911,14 +2175,26 @@ function defineControls(id, input, options = {}) {
         throw Error(`Unknown preset ${index + 1} for group ${group}`);
       if (!enabled())
         return;
-      set(preset.values, { source: "preset", group, coalesce: presetOptions?.coalesce }), options.onPreset?.({ group, index, name: preset.name });
+      let b = activeBase();
+      write(preset.values, { source: "preset", group, coalesce: presetOptions?.coalesce }, makeBase(b.preset, { ...b.groups, [group]: index })), options.onPreset?.({ group, index, name: preset.name });
+    },
+    activePreset() {
+      if (!enabled())
+        return null;
+      return activeBase().preset;
+    },
+    activeGroupPreset(group) {
+      if (!enabled())
+        return -1;
+      return activeBase().groups[group] ?? -1;
     },
+    baseValues,
     matchingGroupPreset(group) {
       let cur = get();
       return (groupPresets[group] ?? []).findIndex((p) => Object.entries(p.values).every(([k, v]) => same(cur[k], v)));
     },
     code: (format, values) => formatCode(values ?? get(), format),
-    variants: createVariants(() => schema, id, storageKey(id, "variants"), variantStorage, get, (v) => set(v, { source: "variant" }), notify, enabled),
+    variants,
     attach(element, chip) {
       let load = options.ship ? () => options.ship().then((m) => m.attach) : void 0;
       if (!load || !enabled())
@@ -1970,7 +2246,11 @@ var optionId = (o) => typeof o === "string" ? o : String(o.id ?? o.value ?? o.la
 function descriptorToField(d) {
   let meta = pickMeta(d);
   if (d.kind === "action")
-    return action(d.label, meta);
+    return action(d.label, {
+      ...meta,
+      ...d.global ? { global: !0 } : {},
+      ...d.rebind ? { rebind: !0 } : {}
+    });
   if (readoutDescriptor(d))
     return readoutField(d);
   if (d.kind === "toolbar")
@@ -2246,9 +2526,11 @@ function createRemoteControls(id, descriptors, options = {}) {
     groupFolded: options.groupFolded,
     sectionFolded: options.sectionFolded,
     onChange(patch, _values, meta) {
-      if (meta.source === "remote" || meta.source === "reset")
+      if (meta.source === "remote")
+        return;
+      if (meta.source === "reset" && !meta.base)
         return;
-      if (meta.source === "preset" && meta.group !== void 0 && options.onPreset)
+      if ((meta.source === "preset" || meta.base && meta.group !== void 0 && controls.activeGroupPreset(meta.group) >= 0) && meta.group !== void 0 && options.onPreset)
         return;
       let changes = [];
       for (let [key, val] of Object.entries(patch)) {
@@ -2309,10 +2591,12 @@ function fromSettings(groups, home = {}) {
   return { descriptors, values };
 }
 export {
+  AROUND,
   CURVE_SHAPES,
   EASINGS,
   SPRING,
   action,
+  actionShortcut,
   angle,
   bezierCss,
   bezierPoint,