@kitlangton/knobs 0.4.0-next.16 → 0.4.0-next.17

package/dist/dev/{chunk-e5hbs8fe.js → chunk-5cv3g7ca.js}

@@ -46,7 +46,7 @@ import {
   pushReadout,
   READOUT,
   storageKey
-} from "./chunk-v2g91mrm.js";
+} from "./chunk-2g0znytq.js";
 import {
   resolveLook,
   themeOf,
@@ -119,7 +119,7 @@ import {
   createHintController,
   pageHints,
   toggleLayer
-} from "./chunk-9y93net8.js";
+} from "./chunk-3vag4n3q.js";
 
 // src/panel/die.ts
 var ROUND = 16 * Math.sqrt(5), DIE = { half: 64 + ROUND, round: ROUND, pip: 12 }, PIPS = {
@@ -2666,7 +2666,7 @@ function readPanelTokens(panel, version = -1) {
     if (hit && hit.version === version)
       return hit.tokens;
   }
-  let style = getComputedStyle(panel), light = isLightStyle(style), theme = gpuDefaults(themeOf(panel), light), bg = parseCssColor(token(style, "bg"), theme.bg), isLight = light || bg[0] * 0.2126 + bg[1] * 0.7152 + bg[2] * 0.0722 > 0.55, surface = parseCssColor(token(style, "fill"), theme.fill), surfaceHi = parseCssColor(token(style, "fill-selected"), theme["fill-selected"]), line = parseCssColor(token(style, "border"), theme.border), lineHi = parseCssColor(token(style, "border-strong"), theme["border-strong"]), text = parseCssColor(token(style, "fg"), theme.fg), label = parseCssColor(token(style, "fg-2"), theme["fg-2"]), dim = parseCssColor(token(style, "fg-3"), theme["fg-3"]), accent = parseCssColor(token(style, "accent"), theme.accent), modified = parseCssColor(token(style, "modified"), theme.modified), segBg = parseCssColor(token(style, "segmented-track"), theme["segmented-track"]), segActive = parseCssColor(token(style, "segmented-active"), theme["segmented-active"]), toggleTrack = parseCssColor(token(style, "toggle-track"), theme["toggle-track"]), fillBase = style.getPropertyValue("--k-fill-base").trim() ? parseCssColor(token(style, "fill-base"), surfaceHi) : surfaceHi, toggleThumb = parseCssColor(token(style, "toggle-thumb"), theme["toggle-thumb"]), [duration, bounce] = style.getPropertyValue("--k-spring").trim().split(/\s+/).map(Number), fill = Number.isFinite(duration) && Number.isFinite(bounce) ? springMotion2({ duration, bounce }) : MOTION.default, fontFamily = style.fontFamily || style.getPropertyValue("--_k-font").trim() || 'system-ui, -apple-system, "SF Pro Text", sans-serif', monoFamily = style.getPropertyValue("--_k-mono").trim() || '"SF Mono", SFMono-Regular, ui-monospace, Menlo, monospace', unit = numProp(style, "unit", 4), pad = numProp(style, "pad", 10), inset = numProp(style, "inset", pad), row = numProp(style, "row", 32), gap = numProp(style, "gap", 4), trayPad = numProp(style, "tray-pad", unit * 0.5), radius = numProp(style, "radius", 8), panelRadius = numProp(style, "radius-panel", radius + unit), radiusMd = Math.max(0, radius - trayPad), radiusSm = Math.max(0, radius - trayPad * 2), fontSize = parseFloat(style.fontSize) || numProp(style, "font-size", 12), roundRaw = style.getPropertyValue("--_k-round").trim(), round = /^-?[\d.]+(px)?$/.test(roundRaw) ? Math.max(0, parseFloat(roundRaw)) : radius > 0 ? 1e4 : 0, tokens = {
+  let style = getComputedStyle(panel), light = isLightStyle(style), theme = gpuDefaults(themeOf(panel), light), bg = parseCssColor(token(style, "bg"), theme.bg), isLight = light || bg[0] * 0.2126 + bg[1] * 0.7152 + bg[2] * 0.0722 > 0.55, surface = parseCssColor(token(style, "fill"), theme.fill), surfaceHi = parseCssColor(token(style, "fill-selected"), theme["fill-selected"]), line = parseCssColor(token(style, "border"), theme.border), lineHi = parseCssColor(token(style, "border-strong"), theme["border-strong"]), text = parseCssColor(token(style, "fg"), theme.fg), label = parseCssColor(token(style, "fg-2"), theme["fg-2"]), dim = parseCssColor(token(style, "fg-3"), theme["fg-3"]), accent = parseCssColor(token(style, "accent"), theme.accent), modified = parseCssColor(token(style, "modified"), theme.modified), segBg = parseCssColor(token(style, "segmented-track"), theme["segmented-track"]), segActive = parseCssColor(token(style, "segmented-active"), theme["segmented-active"]), toggleTrack = parseCssColor(token(style, "toggle-track"), theme["toggle-track"]), fillBase = style.getPropertyValue("--k-fill-base").trim() ? parseCssColor(token(style, "fill-base"), surfaceHi) : surfaceHi, toggleThumb = parseCssColor(token(style, "toggle-thumb"), theme["toggle-thumb"]), [duration, bounce] = style.getPropertyValue("--k-spring").trim().split(/\s+/).map(Number), fill = Number.isFinite(duration) && Number.isFinite(bounce) ? springMotion2({ duration, bounce }) : MOTION.default, fontFamily = style.fontFamily || style.getPropertyValue("--_k-font").trim() || 'system-ui, -apple-system, "SF Pro Text", sans-serif', monoFamily = style.getPropertyValue("--_k-mono").trim() || '"SF Mono", SFMono-Regular, ui-monospace, Menlo, monospace', unit = numProp(style, "unit", 4), pad = numProp(style, "pad", 10), inset = numProp(style, "inset", pad), row = numProp(style, "row", 32), gap = numProp(style, "gap", 4), trayPad = numProp(style, "tray-pad", unit * 0.5), radius = numProp(style, "radius", 8), panelRadius = numProp(style, "radius-panel", radius + unit), frameRadius = numProp(style, "radius-frame", radius > 0 ? radius + pad + 1 : 0), radiusMd = Math.max(0, radius - trayPad), radiusSm = Math.max(0, radius - trayPad * 2), fontSize = parseFloat(style.fontSize) || numProp(style, "font-size", 12), roundRaw = style.getPropertyValue("--_k-round").trim(), round = /^-?[\d.]+(px)?$/.test(roundRaw) ? Math.max(0, parseFloat(roundRaw)) : radius > 0 ? 1e4 : 0, tokens = {
     bg,
     surface,
     surfaceHi,
@@ -2717,6 +2717,7 @@ function readPanelTokens(panel, version = -1) {
     trayPad,
     radius,
     panelRadius,
+    frameRadius,
     radiusMd,
     radiusSm,
     fontSize,
@@ -5902,7 +5903,7 @@ class GpuOverlayManager {
         this.curAlpha = 1;
       if (revealing)
         anyMoving = !0;
-      let blurMul = reducedMotion ? 0 : tokens.blurStrength, outerClip = panel.inline ? getEffectiveClipRect(panel.root, win, this.styleVersion) : [0, 0, win.innerWidth, win.innerHeight], morph = panel.morph?.(this.frameNow), shown = morph ? clamp(morph.progress, 0, 1) : 1, card = morph ? new DOMRect(morph.x, morph.y, morph.w, morph.h) : pRect, cardRadius = morph ? morph.radius : tokens.panelRadius;
+      let blurMul = reducedMotion ? 0 : tokens.blurStrength, outerClip = panel.inline ? getEffectiveClipRect(panel.root, win, this.styleVersion) : [0, 0, win.innerWidth, win.innerHeight], morph = panel.morph?.(this.frameNow), shown = morph ? clamp(morph.progress, 0, 1) : 1, card = morph ? new DOMRect(morph.x, morph.y, morph.w, morph.h) : pRect, cardRadius = morph ? morph.radius : tokens.frameRadius;
       if (morph)
         anyMoving = !0;
       let masked = morph !== void 0 && this.maskCount < MAX_MASKS, panelClip = intersectClip(outerClip, [pRect.left, pRect.top, pRect.right, pRect.bottom]);
@@ -10689,7 +10690,6 @@ var compareCss = `
 :where(.knobs-ui) .knobs-cmp-zoom-reset:is(:hover,:focus-visible){background:color-mix(in srgb,var(--_ku-on-media) 16%,transparent);color:var(--_ku-on-media);transition-duration:calc(var(--_k-hover-in) * 1ms)}
 .knobs-cmp-note{position:absolute;left:50%;top:50%;translate:-50% -50%;color:var(--_k-fg-3);pointer-events:none}
 .knobs-cmp-note:empty{display:none}
-.knobs-cmp-strip-host{flex:none;height:60px;min-height:0}
 .knobs-cmp-timeline-host{flex:none;min-height:0}
 /* The frame strip: Before over After per column, a difference bar under them, a dot where it peaks. */
 .knobs-ui.knobs-cmp-strip{--_ku-cmp-diff:var(--k-compare-diff,var(--_k-ok));position:relative;width:100%;height:100%;min-height:40px;overflow:hidden;cursor:col-resize;touch-action:none;
@@ -10709,6 +10709,9 @@ var playerCss = `
 .knobs-player-media{position:absolute;inset:0;display:block;width:100%;height:100%;margin:0;padding:0;border:0;object-fit:contain;
   opacity:0;filter:blur(4px);transition:opacity calc(var(--_k-motion-default-ms) * 1ms) var(--_k-motion-default),filter calc(var(--_k-motion-default-ms) * 1ms) var(--_k-motion-default)}
 .knobs-player[data-ready] .knobs-player-media{opacity:1;filter:none}
+/* Mid-scrub, the cached frame under the hand, over the video until it lands. */
+.knobs-player-preview{position:absolute;inset:0;display:block;width:100%;height:100%;object-fit:contain;pointer-events:none}
+.knobs-player-preview[hidden]{display:none}
 .knobs-player-line{flex:none;min-height:0}
 /* The timeline's own stylesheet is look.ts's; what the player's row and every timeline share
    about the hand is set here, after it. No hand cursor anywhere (the arrow, or a resize where it
@@ -11425,8 +11428,51 @@ function place2(o) {
 }
 var clamp2 = (v, lo, hi) => hi < lo ? lo : Math.max(lo, Math.min(hi, v));
 
+// src/ui/tooltip-model.ts
+function tipSchedule(clock, view) {
+  let shown = null, pending = null, timer, hiddenAt = -1 / 0, cancel = () => {
+    if (pending)
+      clock.clear(timer);
+    pending = null;
+  }, hide = (now = !1) => {
+    if (cancel(), !shown)
+      return;
+    shown = null, hiddenAt = clock.now(), view.hide(now);
+  };
+  return {
+    get shown() {
+      return shown;
+    },
+    get pending() {
+      return pending;
+    },
+    want(tip, options = {}) {
+      if (tip.el === shown?.el || tip.el === pending?.el)
+        return;
+      cancel();
+      let handoff = shown !== null || clock.now() - hiddenAt < 400;
+      if (handoff || options.now) {
+        shown = tip, view.show(tip, handoff);
+        return;
+      }
+      pending = tip, timer = clock.set(() => {
+        if (pending = null, !view.connected(tip))
+          return;
+        shown = tip, view.show(tip, !1);
+      }, options.delay ?? 500);
+    },
+    hide,
+    leave(within) {
+      if (pending && within(pending))
+        cancel();
+      if (shown && within(shown))
+        hide();
+    }
+  };
+}
+
 // src/ui/tooltip.ts
-var tips = /* @__PURE__ */ new WeakMap, HANDOFF_MS = 400, controllers = /* @__PURE__ */ new WeakMap;
+var tips = /* @__PURE__ */ new WeakMap, controllers = /* @__PURE__ */ new WeakMap;
 function tipOf(start) {
   let node = start instanceof Element ? start : null;
   while (node) {
@@ -11452,7 +11498,7 @@ function controllerOf(doc) {
   let existing = controllers.get(doc);
   if (existing)
     return existing;
-  let win = doc.defaultView, layer, motion, text, keys, target = null, pending = null, timer = 0, hiddenAt = -1 / 0, quiet = null, keyboard = !1, build = (look) => {
+  let win = doc.defaultView, layer, motion, text, keys, target = null, quiet = null, keyboard = !1, build = (look) => {
     layer = layerElement(doc, "knobs-layer knobs-tooltip", look), layer.id = `knobs-tooltip-${Math.random().toString(36).slice(2, 8)}`, layer.setAttribute("role", "tooltip"), text = doc.createElement("span"), text.className = "knobs-tooltip-text", keys = doc.createElement("span"), keys.className = "knobs-tooltip-keys", layer.append(text, keys), motion = presence(layer, { scale: 0.96, blur: 3, duration: 0.24 });
   }, show = (el, tip, instant) => {
     if (!layer?.isConnected)
@@ -11474,30 +11520,28 @@ function controllerOf(doc) {
       motion.snap(1);
     else
       motion.show();
-  }, hide = (now = !1) => {
-    if (win.clearTimeout(timer), pending = null, !target)
-      return;
-    if (target.removeAttribute("aria-describedby"), target = null, hiddenAt = performance.now(), now)
-      motion?.snap(0);
-    else
-      motion?.hide();
-  }, want = (found) => {
+  }, schedule = tipSchedule({
+    set: (run, ms) => win.setTimeout(run, ms),
+    clear: (handle) => win.clearTimeout(handle),
+    now: () => performance.now()
+  }, {
+    show: ({ el, tip }, snap) => show(el, tip, snap),
+    hide: (now) => {
+      if (target?.removeAttribute("aria-describedby"), target = null, now)
+        motion?.snap(0);
+      else
+        motion?.hide();
+    },
+    connected: ({ el }) => el.isConnected
+  }), hide = (now = !1) => schedule.hide(now), want = (found, now = !1) => {
     if (!found)
       return hide();
-    if (found.el === target || found.el === pending?.el)
-      return;
     if (found.el === quiet)
       return;
-    if (win.clearTimeout(timer), target !== null || performance.now() - hiddenAt < HANDOFF_MS) {
-      pending = null, show(found.el, found.tip, !0);
-      return;
-    }
-    if (target)
-      hide();
-    pending = found, timer = win.setTimeout(() => {
-      if (pending = null, found.el.isConnected)
-        show(found.el, found.tip, !1);
-    }, found.tip.opts.delay ?? 500);
+    schedule.want(found, {
+      now,
+      ...found.tip.opts.delay !== void 0 ? { delay: found.tip.opts.delay } : {}
+    });
   };
   doc.addEventListener("pointerover", (e) => {
     if (e.pointerType === "touch")
@@ -11524,10 +11568,9 @@ function controllerOf(doc) {
   }, !0), doc.addEventListener("focusin", (e) => {
     let found = tipOf(e.target);
     if (found && keyboard && e.target.matches(":focus-visible"))
-      want(found);
+      want(found, !0);
   }), doc.addEventListener("focusout", (e) => {
-    if (target && target.contains(e.target))
-      hide();
+    schedule.leave(({ el }) => el.contains(e.target));
   }), doc.addEventListener("scroll", () => target && hide(!0), !0);
   let c = { hide };
   return controllers.set(doc, c), c;
@@ -12458,6 +12501,13 @@ function toolbarRow(c, press, keyOf = toolbarShortcut2) {
   };
 }
 
+// src/panel/description-ids.ts
+var panels = 0;
+function descriptionIds(storeId) {
+  let prefix = `knobs-desc-${++panels}-${storeId.replace(/[^\w-]/g, "-")}`, n = 0;
+  return () => `${prefix}-${++n}`;
+}
+
 // src/panel/search.ts
 function createSearch(doc, options) {
   let element = doc.createElement("div");
@@ -14688,7 +14738,7 @@ function morphFromChip(chip, root, wake, restored) {
   }, ensureShape = () => {
     if (shape)
       return shape;
-    let cs = getComputedStyle(root), r = parseFloat(cs.getPropertyValue("--kv-radius-panel"));
+    let cs = getComputedStyle(root), r = parseFloat(cs.getPropertyValue("--kv-radius-frame"));
     if (Number.isFinite(r))
       panelRadius = r;
     shape = doc.createElement("div"), shape.className = "knobs-root knobs-morph", shape.setAttribute("aria-hidden", "true");
@@ -14818,6 +14868,7 @@ function foldMemory(id, storage) {
       let next = {
         sections: { ...data.sections },
         groups: { ...data.groups },
+        ...data.subsections ? { subsections: { ...data.subsections } } : {},
         [kind]: { ...data[kind], [at]: folded }
       };
       try {
@@ -14828,14 +14879,27 @@ function foldMemory(id, storage) {
 }
 
 // src/panel/position.ts
-function positionPanel(panel, header, anchor, id, storage) {
-  let doc = panel.ownerDocument, win = doc.defaultView, bounds = anchor.getBoundingClientRect(), w = panel.offsetWidth || 288, clampX = (v) => Math.max(8, Math.min(v, win.innerWidth - w - 8)), x = bounds.right + w <= win.innerWidth - 8 ? bounds.right + 8 : clampX(bounds.left - w - 8), y = Math.max(8, bounds.top), key = storageKey(id, "position"), hasSaved = !1;
+function savedPosition(left, top, width, view) {
+  let right = left + width / 2 > view / 2;
+  return right ? { x: view - left - width, y: top, right } : { x: left, y: top };
+}
+var leftOf = (saved, width, view) => saved.right ? view - width - saved.x : saved.x;
+function readPosition(raw) {
   try {
-    let saved = JSON.parse(storage()?.getItem(key) ?? "null");
+    let saved = JSON.parse(raw ?? "null");
     if (saved && Number.isFinite(saved.x) && Number.isFinite(saved.y))
-      x = saved.x, y = saved.y, hasSaved = !0;
+      return { x: saved.x, y: saved.y, ...saved.right === !0 ? { right: !0 } : {} };
+  } catch {}
+  return;
+}
+function positionPanel(panel, header, anchor, id, storage) {
+  let doc = panel.ownerDocument, win = doc.defaultView, bounds = anchor.getBoundingClientRect(), w = panel.offsetWidth || 288, clampX = (v) => Math.max(8, Math.min(v, win.innerWidth - w - 8)), x = bounds.right + w <= win.innerWidth - 8 ? bounds.right + 8 : clampX(bounds.left - w - 8), y = Math.max(8, bounds.top), key = storageKey(id, "position"), saved;
+  try {
+    saved = readPosition(storage()?.getItem(key));
   } catch {}
-  if (!hasSaved) {
+  if (saved)
+    x = leftOf(saved, w, win.innerWidth), y = saved.y;
+  else {
     let others = [...doc.querySelectorAll(".knobs-panel:not(.knobs-inline)")].filter((el) => el !== panel).map((el) => el.getBoundingClientRect());
     if (others.length > 0) {
       let overlaps = (cx, cy) => others.some((r) => Math.abs(cx - r.left) < w - 24 && Math.abs(cy - r.top) < 120);
@@ -14855,6 +14919,8 @@ function positionPanel(panel, header, anchor, id, storage) {
     }
   }
   let shown = { x, y }, constrain = () => {
+    if (saved && !drag)
+      x = leftOf(saved, panel.offsetWidth, win.innerWidth);
     shown = {
       x: Math.max(8, Math.min(x, win.innerWidth - panel.offsetWidth - 8)),
       y: Math.max(8, Math.min(y, win.innerHeight - panel.offsetHeight - 8))
@@ -14863,17 +14929,27 @@ function positionPanel(panel, header, anchor, id, storage) {
   header.onpointerdown = (event) => {
     if (event.button !== 0 || event.target.closest("button,select,input"))
       return;
-    event.preventDefault(), drag = { id: event.pointerId, x: event.clientX, y: event.clientY, left: shown.x, top: shown.y }, header.setPointerCapture(event.pointerId);
+    event.preventDefault(), drag = { id: event.pointerId, x: event.clientX, y: event.clientY, left: shown.x, top: shown.y };
   }, header.onpointermove = (event) => {
     if (!drag || event.pointerId !== drag.id)
       return;
+    if (!("dragging" in panel.dataset)) {
+      if (!(event.buttons & 1))
+        return void (drag = void 0);
+      if (Math.hypot(event.clientX - drag.x, event.clientY - drag.y) <= 2)
+        return;
+      panel.dataset.dragging = "", header.setPointerCapture(event.pointerId);
+    }
     x = drag.left + event.clientX - drag.x, y = drag.top + event.clientY - drag.y, constrain();
+  }, header.onpointerup = header.onpointercancel = () => {
+    if (drag && !("dragging" in panel.dataset))
+      drag = void 0;
   }, header.onlostpointercapture = () => {
     if (!drag)
       return;
-    drag = void 0, { x, y } = shown;
+    drag = void 0, delete panel.dataset.dragging, { x, y } = shown, saved = savedPosition(x, y, panel.offsetWidth, win.innerWidth);
     try {
-      storage()?.setItem(key, JSON.stringify({ x, y }));
+      storage()?.setItem(key, JSON.stringify(saved));
     } catch {}
   };
   let observer = new ResizeObserver(constrain);
@@ -14987,7 +15063,7 @@ function createPresence(root, options) {
       if (!root.dataset.presence || root.hidden)
         return;
       let look = presenceLook(spring.x, inline, reduced), r = root.getBoundingClientRect();
-      radius ??= parseFloat(win.getComputedStyle(root).getPropertyValue("--kv-radius-panel")) || 12;
+      radius ??= parseFloat(win.getComputedStyle(root).getPropertyValue("--kv-radius-frame")) || 12;
       let s = look.scale, ox = r.left + r.width / 2, oy = inline ? r.top : r.top + r.height / 2;
       return {
         x: ox + (r.left - ox) * s,
@@ -15459,8 +15535,10 @@ function buildPanel(controls, host, options) {
     if (page) {
       if (remember)
         foldsKept?.set("groups", group, next);
-    } else if (sessionKept)
-      writeSession(controls.id, { groups: { ...readSession(controls.id).groups, [group]: next } });
+    } else if (sessionKept) {
+      if (writeSession(controls.id, { groups: { ...readSession(controls.id).groups, [group]: next } }), remember)
+        panelFolds?.set("groups", group, next);
+    }
     refreshFolds(), positioned?.constrain(), wakeGpu();
   }
   function foldTile(card, shut, animate) {
@@ -15488,9 +15566,7 @@ function buildPanel(controls, host, options) {
     });
     gReset.className = "knobs-group-reset", gReset.dataset.hint = `${title} reset`, bloom(gReset, !1), groupResetButtons.set(groupName, gReset);
     let gDie = createHeaderDie(doc, () => wakeGpu(), GROUP_DIE), gRandom = iconButton("random", `Randomize ${title}`, "g Alt+g", () => {});
-    gRandom.className = "knobs-group-die", gRandom.dataset.hint = `${title} random`, gRandom.querySelector(".knobs-icon")?.replaceWith(gDie.node), gRandom.onclick = (event) => run(() => rerollGroup(groupName, event.altKey));
-    let rollable = Object.values(controls.schema).some((f) => f.group === groupName && hasValue2(f));
-    if (!bound("random") && !bound("mutate") || !rollable)
+    if (gRandom.className = "knobs-group-die", gRandom.dataset.hint = `${title} random`, gRandom.querySelector(".knobs-icon")?.replaceWith(gDie.node), gRandom.onclick = (event) => run(() => rerollGroup(groupName, event.altKey)), !bound("random") && !bound("mutate"))
       gRandom.hidden = !0;
     groupDice.set(groupName, { button: gRandom, die: gDie });
     let presets = page ? (controls.groupPresets[groupName] ?? []).slice(0, 9) : [], ui, gPeek = el("span");
@@ -15560,7 +15636,7 @@ function buildPanel(controls, host, options) {
       if (summary = el("span"), summary.className = "knobs-group-summary", page)
         gRight.append(summary);
       groupSummaries.set(groupName, summary), caret = caretSvg(), gRight.append(caret), gHead.dataset.foldable = "", gHead.tabIndex = -1, gHead.setAttribute("role", "button"), gHead.setAttribute("aria-label", title);
-      let folded = (page ? foldsKept?.get("groups", groupName) : session.groups?.[groupName]) ?? foldAt;
+      let folded = (page ? foldsKept?.get("groups", groupName) : session.groups?.[groupName] ?? panelFolds?.get("groups", groupName)) ?? foldAt;
       if (folds.set(groupName, folded), gHead.setAttribute("aria-expanded", String(!folded)), !page)
         gHead.toggleAttribute("data-folded", folded);
       gHead.addEventListener("click", (event) => {
@@ -15616,7 +15692,7 @@ function buildPanel(controls, host, options) {
     if (!preset)
       return;
     cue(root, coalesce ? "select" : "preset"), controls.groupPreset(group, index, { coalesce }), peek(group, preset.name, 1100);
-  }, remember = options.session ?? controls.storage !== null, sessionKept = remember, session = remember ? readSession(controls.id) : {}, foldPort = page?.foldStorage !== void 0 ? page.foldStorage : controls.persist === "none" ? null : controls.storage, foldsKept = page && foldPort ? foldMemory(controls.id, () => foldPort) : null, tracks = /* @__PURE__ */ new Map, toolbars = /* @__PURE__ */ new Map, keyedActions = /* @__PURE__ */ new Map, actionKey = (key, field) => {
+  }, remember = options.session ?? controls.storage !== null, sessionKept = remember, session = remember ? readSession(controls.id) : {}, foldPort = page?.foldStorage !== void 0 ? page.foldStorage : controls.persist === "none" ? null : controls.storage, foldsKept = page && foldPort ? foldMemory(controls.id, () => foldPort) : null, panelFolds = !page && remember && foldPort ? foldMemory(controls.id, () => foldPort) : null, tracks = /* @__PURE__ */ new Map, toolbars = /* @__PURE__ */ new Map, keyedActions = /* @__PURE__ */ new Map, actionKey = (key, field) => {
     let combo = controls.shortcut(key);
     return combo ? { key: combo, scope: actionShortcut2(field)?.scope ?? "panel" } : void 0;
   }, readouts = /* @__PURE__ */ new Map, readoutPort = controls[READOUT], planRows = (schema) => {
@@ -15645,7 +15721,8 @@ function buildPanel(controls, host, options) {
             label,
             ...duration.group !== void 0 ? { group: duration.group } : {},
             ...duration.section !== void 0 ? { section: duration.section } : {},
-            ...duration.shortcut !== void 0 ? { shortcut: duration.shortcut } : {}
+            ...duration.shortcut !== void 0 ? { shortcut: duration.shortcut } : {},
+            ...duration.description !== void 0 ? { description: duration.description } : {}
           },
           parts: { duration, bounce },
           group: duration.group,
@@ -16075,7 +16152,33 @@ function buildPanel(controls, host, options) {
       return;
     slot.replaceChildren(...node ? [node] : []);
   }
-  let fieldFlag = (field, name) => {
+  let descriptions = el("div");
+  descriptions.hidden = !0, root.append(descriptions);
+  let described = /* @__PURE__ */ new Map, descriptionId = descriptionIds(controls.id);
+  function describe(row) {
+    let text = row.field.description?.trim() ?? "", had = described.get(row);
+    if ((had?.text ?? "") === text)
+      return;
+    let inputs = row.choice ? [row.choice.seg, row.choice.menu] : [row.input];
+    if (had) {
+      had.untip(), had.node.remove(), described.delete(row);
+      for (let input of inputs)
+        input.removeAttribute("aria-describedby");
+    }
+    if (!text)
+      return;
+    let node = el("span", text);
+    node.id = descriptionId(), descriptions.append(node);
+    for (let input of inputs)
+      input.setAttribute("aria-describedby", node.id);
+    described.set(row, { text, node, untip: tooltip(row.row, text) });
+  }
+  let undescribe = (row) => {
+    let had = described.get(row);
+    if (!had)
+      return;
+    had.untip(), had.node.remove(), described.delete(row);
+  }, fieldFlag = (field, name) => {
     let v = field[name];
     return typeof v === "function" ? Boolean(v(controls.get())) : Boolean(v);
   };
@@ -16106,7 +16209,7 @@ function buildPanel(controls, host, options) {
         announceSections();
     }, delay), wakeGpu();
   }, dropGpu = (row) => {
-    row.dispose?.(), row.slider?.dispose(), row.editor?.dispose();
+    undescribe(row), row.dispose?.(), row.slider?.dispose(), row.editor?.dispose();
     for (let g of row.gpu) {
       let at = gpuRows.indexOf(g);
       if (at >= 0)
@@ -16147,11 +16250,11 @@ function buildPanel(controls, host, options) {
     for (let spec of specs) {
       let existing = kept.get(spec.id);
       if (existing && existing.shape === shapeOf(spec)) {
-        kept.delete(spec.id), existing.retune(spec), next.push(existing);
+        kept.delete(spec.id), existing.retune(spec), describe(existing), next.push(existing);
         continue;
       }
       let row = buildRow(spec);
-      decorate(row), gpuRows.push(...row.gpu), entering.add(row), next.push(row);
+      decorate(row), describe(row), gpuRows.push(...row.gpu), entering.add(row), next.push(row);
     }
     let leaving = [...kept.values()];
     rows = next;
@@ -16310,7 +16413,7 @@ function buildPanel(controls, host, options) {
     label.className = "knobs-subhead-label";
     let caret = caretSvg();
     if (node.append(label, caret), !subFolds.has(id))
-      subFolds.set(id, session.subsections?.[id] ?? options.subsectionFolded?.[name] ?? !1);
+      subFolds.set(id, session.subsections?.[id] ?? panelFolds?.get("subsections", id) ?? options.subsectionFolded?.[name] ?? !1);
     node.setAttribute("aria-expanded", String(!subFolds.get(id))), node.addEventListener("click", (event) => {
       if (event.detail < 2)
         foldSub(id);
@@ -16341,7 +16444,7 @@ function buildPanel(controls, host, options) {
     if (applyVisibility("reveal"), remember)
       writeSession(controls.id, {
         subsections: { ...readSession(controls.id).subsections, [id]: next }
-      });
+      }), panelFolds?.set("subsections", id, next);
   }
   let groupTab = (group) => {
     for (let f of Object.values(controls.schema))
@@ -16410,7 +16513,7 @@ function buildPanel(controls, host, options) {
     return selectTab(list[(at + direction + list.length) % list.length].id, !1), !0;
   }, searching = () => search?.filtering() ?? !1, rowMatches = (r) => {
     let query = search.query();
-    if (query && !matchesFilter(query, r.display, r.key, r.group, r.group && groupTitle(r.group), r.group && groupDescription(r.group), r.field.subsection))
+    if (query && !matchesFilter(query, r.display, r.key, r.group, r.group && groupTitle(r.group), r.group && groupDescription(r.group), r.field.subsection, r.field.description))
       return !1;
     for (let chip of search.active())
       if (!r.keys.some((k) => chipTests.get(chip)?.(k)))
@@ -16509,7 +16612,10 @@ function buildPanel(controls, host, options) {
         lock.dataset.enter = "", lock.getBoundingClientRect();
     }
     return lock;
-  }, keysOf = (indices) => indices.flatMap((i) => rows[i]?.keys ?? []), groupKeys = (group) => rows.filter((r) => r.group === group).flatMap((r) => r.keys), rerollGroup = (group, nudge) => {
+  }, keysOf = (indices) => indices.flatMap((i) => rows[i]?.keys ?? []), groupKeys = (group) => rows.filter((r) => r.group === group).flatMap((r) => r.keys), mayRoll = (key) => {
+    let field = controls.schema[key];
+    return Boolean(field && hasValue2(field) && field.random !== !1);
+  }, rerollGroup = (group, nudge) => {
     let roller = groupDice.get(group)?.die;
     if (!roller)
       return;
@@ -16615,15 +16721,22 @@ function buildPanel(controls, host, options) {
   });
   apply.className = "knobs-apply-btn", apply.setAttribute("aria-label", "Import JSON"), apply.hidden = !0;
   let copy = async (value, inPlace = !0) => {
-    try {
-      if (await doc.defaultView.navigator.clipboard.writeText(value), inPlace && !copyButton.hidden && headerShown())
+    let done = () => {
+      if (inPlace && !copyButton.hidden && headerShown())
         copied();
       else
         say("Copied.");
+    };
+    try {
+      await doc.defaultView.navigator.clipboard.writeText(value), done();
     } catch {
-      if (text.value = value, page)
-        togglePopover(!0);
-      reveal(text, !0), apply.hidden = !0, positioned?.constrain(), text.focus(), text.select(), say("Clipboard unavailable. Copy the selected text.", 6000);
+      if (copyByCommand(doc, value))
+        done();
+      else {
+        if (text.value = value, page)
+          togglePopover(!0);
+        reveal(text, !0), apply.hidden = !0, positioned?.constrain(), text.focus(), text.select(), say("Clipboard unavailable. Copy the selected text.", 6000);
+      }
     }
     wakeGpu();
   }, gpuActionButtons = [], panelActions = allActions.filter((a) => !a.group), customActions = el("div");
@@ -16803,10 +16916,16 @@ function buildPanel(controls, host, options) {
     }
     if (randomButton.disabled !== (unlocked === 0))
       randomButton.disabled = unlocked === 0;
+    let headerHidden = !((bound("random") || bound("mutate")) && shows("random")) || !rows.some((r) => r.keys.some(mayRoll));
+    if (randomButton.hidden !== headerHidden)
+      randomButton.hidden = headerHidden;
     for (let [group, { button }] of groupDice) {
       let off = !options.groupRandom && !groupKeys(group).some((k) => controls.canRoll(k));
       if (button.disabled !== off)
         button.disabled = off;
+      let hidden = !bound("random") && !bound("mutate") || !options.groupRandom && !groupKeys(group).some(mayRoll);
+      if (button.hidden !== hidden)
+        button.hidden = hidden;
     }
     if (root.hasAttribute("data-comparing") !== controls.comparing)
       root.toggleAttribute("data-comparing", controls.comparing);
@@ -16959,7 +17078,7 @@ function buildPanel(controls, host, options) {
     filtered = query, root.toggleAttribute("data-filtering", Boolean(query)), layout.change(() => {
       layout.openFolds(Boolean(query));
       for (let r of rows) {
-        let show = !query || matchesFilter(query, r.display, r.key, r.group, r.group && groupTitle(r.group, r.section), r.group && groupDescription(r.group), r.section, r.section && sectionTitle(r.section), r.section && sectionDescription(r.section));
+        let show = !query || matchesFilter(query, r.display, r.key, r.group, r.group && groupTitle(r.group, r.section), r.group && groupDescription(r.group), r.section, r.section && sectionTitle(r.section), r.section && sectionDescription(r.section), r.field.description);
         if (r.row.hidden === show)
           r.row.hidden = !show;
       }
@@ -17436,8 +17555,19 @@ function buildPanel(controls, host, options) {
     setTimeout(() => {
       pointerHeld = !1, queueScope();
     });
+  }, onPressOutside = (event) => {
+    let target = event.target;
+    if (page || !target || root.contains(target))
+      return;
+    if (target.closest?.(".knobs-root,.knobs-layers"))
+      return;
+    setTimeout(() => {
+      let active = doc.activeElement;
+      if (active && root.contains(active))
+        active.blur();
+    });
   };
-  doc.addEventListener("pointerdown", onPress, !0), doc.addEventListener("pointerup", onRelease, !0), doc.addEventListener("pointercancel", onRelease, !0), root.addEventListener("keydown", () => {
+  doc.addEventListener("pointerdown", onPress, !0), doc.addEventListener("pointerdown", onPressOutside, !0), doc.addEventListener("pointerup", onRelease, !0), doc.addEventListener("pointercancel", onRelease, !0), root.addEventListener("keydown", () => {
     pointerOut = !1;
   }, !0);
   let syncScope = () => {
@@ -18263,7 +18393,7 @@ function buildPanel(controls, host, options) {
         doc.removeEventListener(type, onPointerUp, !0);
       for (let type of ["pointerup", "pointercancel"])
         doc.removeEventListener(type, endScrub, !0);
-      doc.defaultView?.removeEventListener("blur", endScrub), endScrub(), unregisterHints?.(), hintCtrl.stop(), modeObserver.disconnect(), unregisterGpu?.(), lens.dispose(), win?.cancelAnimationFrame(lensFrame), doc.removeEventListener("pointerdown", onPress, !0), doc.removeEventListener("pointerup", onRelease, !0), doc.removeEventListener("pointercancel", onRelease, !0), crumbs?.dispose(), active?.dispose(), clearTimeout(escTimer), win?.removeEventListener("blur", queueScope), win?.removeEventListener("focus", queueScope), unsubscribe(), unlisten?.(), rowsObserver.disconnect(), gpuObserver.disconnect(), doc.defaultView?.cancelAnimationFrame(landTimer);
+      doc.defaultView?.removeEventListener("blur", endScrub), endScrub(), unregisterHints?.(), hintCtrl.stop(), modeObserver.disconnect(), unregisterGpu?.(), lens.dispose(), win?.cancelAnimationFrame(lensFrame), doc.removeEventListener("pointerdown", onPress, !0), doc.removeEventListener("pointerdown", onPressOutside, !0), doc.removeEventListener("pointerup", onRelease, !0), doc.removeEventListener("pointercancel", onRelease, !0), crumbs?.dispose(), active?.dispose(), clearTimeout(escTimer), win?.removeEventListener("blur", queueScope), win?.removeEventListener("focus", queueScope), unsubscribe(), unlisten?.(), rowsObserver.disconnect(), gpuObserver.disconnect(), doc.defaultView?.cancelAnimationFrame(landTimer);
       for (let k of inHand)
         controls.hold(k, !1);
       inHand.clear(), positioned?.dispose(), die.dispose();
@@ -18414,6 +18544,17 @@ function buildPanel(controls, host, options) {
   }
   return pageApi;
 }
+function copyByCommand(doc, value) {
+  let was = doc.activeElement, area = doc.createElement("textarea");
+  area.value = value, area.setAttribute("readonly", ""), area.style.cssText = "position:fixed;top:0;left:0;opacity:0;pointer-events:none", doc.body.append(area), area.select();
+  let ok = !1;
+  try {
+    ok = doc.execCommand("copy");
+  } catch {
+    ok = !1;
+  }
+  return area.remove(), was?.focus({ preventScroll: !0 }), ok;
+}
 function createPanel(controls, anchor, close, options) {
   return buildPanel(controls, anchor.ownerDocument.body, {
     ...options,

package/dist/dev/{chunk-exaya50m.js → chunk-xzm0zawh.js}

@@ -6,7 +6,7 @@ import {
   writeSession,
   injectStyles,
   toggleLayer
-} from "./chunk-9y93net8.js";
+} from "./chunk-3vag4n3q.js";
 
 // src/panel/attach.ts
 function attach(controls, element, options = {}) {
@@ -69,26 +69,26 @@ function attach(controls, element, options = {}) {
       update();
   }, open = async (restored = !1) => {
     if (panel) {
-      unpress(), panel.focus();
+      unpress(), focusPanel(panel);
       return;
     }
     if (leaving?.reopen()) {
       if (unpress(), panel = leaving, leaving = void 0, remember)
         writeSession(controls.id, { open: !0 });
-      chip.setAttribute("aria-expanded", "true"), update(), panel.focus();
+      chip.setAttribute("aria-expanded", "true"), update(), focusPanel(panel);
       return;
     }
     if (leaving = void 0, loading)
       return;
     loading = !0;
     try {
-      let { createPanel } = await import("./chunk-e5hbs8fe.js");
+      let { createPanel } = await import("./chunk-5cv3g7ca.js");
       if (disposed || !controls.enabled || panel)
         return;
       if (panel = createPanel(controls, element, close, { restored, chip }), remember)
         writeSession(controls.id, { open: !0 });
       if (chip.setAttribute("aria-expanded", "true"), update(), !restored)
-        panel.focus();
+        focusPanel(panel);
     } catch (cause) {
       chip.title = String(cause), renderFace("Retry knobs");
     } finally {
@@ -124,7 +124,7 @@ function attach(controls, element, options = {}) {
       element.removeAttribute("tabindex");
   };
 }
-var MODE_KEY = "knobs:mode", MODE_EVENT = "knobs-mode";
+var focusPanel = (panel) => panel.element.focus({ preventScroll: !0 }), MODE_KEY = "knobs:mode", MODE_EVENT = "knobs-mode";
 function knobsMode(win) {
   try {
     return win.sessionStorage.getItem(MODE_KEY) === "on";

package/dist/dev/index.js

@@ -77,7 +77,7 @@ import {
   browserStorage,
   urlFlag2,
   storageKey
-} from "./chunk-v2g91mrm.js";
+} from "./chunk-2g0znytq.js";
 // src/core/random.ts
 var lattice = (min, max, step, r) => min + Math.floor(r * (Math.floor((max - min) / step + 0.000000001) + 1)) * step, between = (min, max, r) => min + (max - min) * r;
 function pick(field, random) {
@@ -945,11 +945,12 @@ function defineControls(id, input, options = {}) {
       ...setOpts?.base ? { base: !0 } : {}
     });
   }
-  function step(to, source) {
-    let before = load(), left = { values: before, base: activeBase() }, diff = changes(before, to.values);
+  function step(to, source, into) {
+    let before = load();
+    into.push({ values: before, base: activeBase() });
+    let 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);
@@ -1285,7 +1286,7 @@ function defineControls(id, input, options = {}) {
       let previous = past.pop();
       if (!previous)
         return;
-      future.push(step(previous, "undo"));
+      step(previous, "undo", future);
     },
     redo() {
       if (release(), hostHistory)
@@ -1293,7 +1294,7 @@ function defineControls(id, input, options = {}) {
       let next = future.pop();
       if (!next)
         return;
-      past.push(step(next, "redo"));
+      step(next, "redo", past);
     },
     getServerSnapshot: () => locked,
     subscribe(cb) {
@@ -1526,11 +1527,11 @@ function defineControls(id, input, options = {}) {
     code: (format, values) => formatCode(values ?? get(), format),
     variants,
     attach(element, chip) {
-      let load = options.ship ? () => options.ship().then((m) => m.attach) : () => import("./chunk-exaya50m.js").then((m) => m.attach);
+      let load = options.ship ? () => options.ship().then((m) => m.attach) : () => import("./chunk-xzm0zawh.js").then((m) => m.attach);
       return live(load, (attach) => attach(controls, element, chip), (detach) => detach());
     },
     mount(container, mountOptions) {
-      let load = options.ship ? () => options.ship().then((m) => m.mountPanel) : () => import("./chunk-e5hbs8fe.js").then((m) => m.mountPanel);
+      let load = options.ship ? () => options.ship().then((m) => m.mountPanel) : () => import("./chunk-5cv3g7ca.js").then((m) => m.mountPanel);
       return live(load, (mountPanel) => {
         let panel = mountPanel(controls, container, mountOptions);
         return mountOptions?.onReady?.(panel), panel;