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

package/dist/panel.js

@@ -1825,6 +1825,14 @@ var init_schema = __esm(() => {
       doc: "Panel and card radius, concentric with controls.",
       deprecated: ["--k-panel-radius", "--ku-panel-radius"]
     },
+    {
+      name: "radius-frame",
+      tier: "semantic",
+      type: "length",
+      group: "Shape",
+      source: css("calc(var(--k-radius) + min(var(--k-radius) * 999, var(--_k-pad) + 1px))"),
+      doc: "A tuning panel's outer corners: its cards' radius plus its padding and border, so the cards, the preset strip and the focus lens inside run concentric. Squares when --k-radius is 0."
+    },
     {
       name: "round",
       tier: "semantic",
@@ -2943,7 +2951,16 @@ var init_glide = __esm(() => {
     "border-subtle",
     "bg-page"
   ];
-  LENGTH_TOKENS = ["pad", "inset", "row", "gap", "radius", "radius-panel", "font-size"];
+  LENGTH_TOKENS = [
+    "pad",
+    "inset",
+    "row",
+    "gap",
+    "radius",
+    "radius-panel",
+    "radius-frame",
+    "font-size"
+  ];
   NUMBER_TOKENS = ["weight-label", "blur", "glow", "glass", "glass-tone"];
   ANIMATED = [...COLOR_TOKENS, ...LENGTH_TOKENS, ...NUMBER_TOKENS, "width"];
   TOKEN_TRANSITIONS = ANIMATED.map((t) => `--kt-${t} var(--k-token-t)`).join(",");
@@ -3129,13 +3146,15 @@ ${GRAD_PROPS}
    catches its top. The light rides on the edge (a shadow raised by its width, so only its top
    shows), not inside the card's 1px border, where it read as a second edge. */
 .knobs-panel{-webkit-user-select:none;user-select:none;transition:${TOKEN_TRANSITIONS},--k-armed ${ARMED_T};position:fixed;z-index:2147480001;width:var(--_k-width);max-width:calc(100vw - 16px);max-height:calc(100dvh - 16px);overflow:auto;padding:var(--_k-pad);
-  background:color-mix(in srgb,var(--_k-bg) calc(100% - var(--_k-glass) * 20%),transparent);border:1px solid transparent;border-radius:var(--_k-radius-panel);box-shadow:var(--_k-shadow-overlay),0 calc(var(--k-rim-width) * -1) 0 var(--_k-rim),0 0 0 var(--k-rim-width) var(--ka-edge),var(--ka-glow);scrollbar-width:thin;
+  background:color-mix(in srgb,var(--_k-bg) calc(100% - var(--_k-glass) * 20%),transparent);border:1px solid transparent;border-radius:var(--_k-radius-frame);box-shadow:var(--_k-shadow-overlay),0 calc(var(--k-rim-width) * -1) 0 var(--_k-rim),0 0 0 var(--k-rim-width) var(--ka-edge),var(--ka-glow);scrollbar-width:thin;
   /* Armed (focus inside: keys come here), the edge takes the accent and a faint glow lifts it. */
   --ka-edge:color-mix(in srgb,var(--_k-accent) calc(var(--k-armed) * var(--k-armed-edge) * 100%),var(--_k-border-subtle));
   --ka-glow:0 0 calc(var(--k-armed-glow) * 1px) color-mix(in srgb,var(--_k-accent) calc(var(--k-armed) * var(--k-armed-glow-a) * var(--k-chrome,1) * 100%),transparent);
   --k-backdrop:blur(calc(var(--_k-glass) * 24px)) saturate(calc(1 + var(--_k-glass) * .8)) brightness(calc(1 + (var(--_k-glass-tone) - 1) * var(--_k-glass)));
   -webkit-backdrop-filter:var(--k-backdrop);backdrop-filter:var(--k-backdrop);
   animation:knobs-in .16s var(--k-ease);}
+/* On a phone a floating panel takes the width, less a gutter, and scrolls inside the height. */
+@media(max-width:420px){.knobs-panel:not(.knobs-inline){width:calc(100vw - 16px)}}
 .knobs-panel[data-restored]{animation:none}
 /* Opening from its chip, the panel's chrome rides a separate shape (see morph.ts) while the
    content, laid out at full size, is clipped to it and revealed top first. */
@@ -3169,8 +3188,9 @@ ${GRAD_PROPS}
 :is(.knobs-panel,.knobs-menu) :is(:focus,:focus-visible):where(:not(.knobs-accessory *)){outline:none}
 
 /* Header */
-.knobs-panel header{position:relative;display:flex;align-items:center;justify-content:space-between;gap:6px;cursor:grab;touch-action:none;padding:0 var(--_k-inset) var(--k-section-gap);min-height:var(--k-icon-btn)}
-.knobs-panel.knobs-inline header,.knobs-panel.knobs-inline header:active{cursor:default}
+/* A floating panel's header carries it; the hand shows only while it's carrying (data-dragging). */
+.knobs-panel header{position:relative;display:flex;align-items:center;justify-content:space-between;gap:6px;touch-action:none;padding:0 var(--_k-inset) var(--k-section-gap);min-height:var(--k-icon-btn)}
+.knobs-panel[data-dragging]>header,.knobs-panel[data-dragging]>header *{cursor:grabbing}
 /* The title row stays pinned while the rows scroll under it, in the panel (it scrolls once it's
    bounded) or, with .knobs-pin-ancestor (which also makes the panel overflow:visible), in the
    nearest scroller around it. Once rows are under it, and only then, it frosts (backdrop blur over
@@ -3185,7 +3205,7 @@ ${GRAD_PROPS}
 @supports (animation-timeline:scroll()){
   .knobs-panel:not(.knobs-page){scroll-timeline:--knobs-self block}
   .knobs-panel.knobs-pin-ancestor:not(.knobs-page){overflow:visible;view-timeline:--knobs-view block}
-  .knobs-panel:not(.knobs-page)>header{position:sticky;top:0;z-index:4;border-radius:max(0px,calc(var(--_k-radius-panel) - 1px)) max(0px,calc(var(--_k-radius-panel) - 1px)) 0 0;
+  .knobs-panel:not(.knobs-page)>header{position:sticky;top:0;z-index:4;border-radius:max(0px,calc(var(--_k-radius-frame) - 1px)) max(0px,calc(var(--_k-radius-frame) - 1px)) 0 0;
     --k-head-on:max(var(--k-head-s),var(--k-head-v));--k-head-bg:color-mix(in srgb,var(--_k-bg) 88%,transparent);
     background:color-mix(in srgb,var(--k-head-bg) calc(var(--k-head-on) * 100%),transparent);
     animation:knobs-head-s linear both;animation-timeline:--knobs-self;animation-range:0px 24px}
@@ -3195,7 +3215,6 @@ ${GRAD_PROPS}
   .knobs-panel[data-gpu-active="true"]:not(.knobs-page)>header{background:transparent!important;-webkit-backdrop-filter:none!important;backdrop-filter:none!important}
   .knobs-panel[data-gpu-active="true"]:not(.knobs-page)>header::after{display:none}
 }
-.knobs-panel header:active{cursor:grabbing}
 .knobs-panel header strong{flex:1;min-width:0;font-weight:var(--_k-weight-title);font-size:var(--_k-text-title);letter-spacing:-.01em;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;transition:opacity .2s var(--k-ease),color ${ARMED_T};
   color:color-mix(in srgb,var(--_k-fg) calc(var(--k-title-rest) * 100%),var(--_k-fg-2))}
 /* At rest a panel's title is a little quiet; armed (keys come here) it's at full strength. */
@@ -5146,12 +5165,24 @@ function createRegistry(doc) {
       return;
     if (e.metaKey || e.ctrlKey || e.altKey || e.key !== PAGE_HINT_KEY)
       return;
-    if (isTyping(e.target) || !wide())
+    if (isTyping(e.target) || !wide(e.target))
       return;
     if (registry.start())
       e.preventDefault();
   };
-  const wide = () => listening && (sources.length > 1 || [...doc.querySelectorAll("[data-hint]")].some((el) => !el.closest(".knobs-panel")));
+  const hostHints = () => [...doc.querySelectorAll("[data-hint]")].some((el) => !el.closest(".knobs-panel"));
+  const wide = (target) => {
+    if (!listening)
+      return false;
+    if (sources.some((s) => s.listen && s.rank >= 2) || hostHints())
+      return true;
+    if (sources.length < 2)
+      return false;
+    if (target === undefined)
+      return true;
+    const piece = target?.closest?.(".knobs-ui,.knobs-pane-body");
+    return Boolean(piece?.classList.contains("knobs-ui"));
+  };
   const relisten = () => {
     const next = sources.some((s) => s.listen);
     if (next === listening)
@@ -9135,6 +9166,7 @@ function readPanelTokens(panel, version = -1) {
   const trayPad = numProp(style, "tray-pad", unit * 0.5);
   const radius = numProp(style, "radius", 8);
   const panelRadius = numProp(style, "radius-panel", radius + unit);
+  const frameRadius = numProp(style, "radius-frame", radius > 0 ? radius + pad + 1 : 0);
   const radiusMd = Math.max(0, radius - trayPad);
   const radiusSm = Math.max(0, radius - trayPad * 2);
   const fontSize = parseFloat(style.fontSize) || numProp(style, "font-size", 12);
@@ -9191,6 +9223,7 @@ function readPanelTokens(panel, version = -1) {
     trayPad,
     radius,
     panelRadius,
+    frameRadius,
     radiusMd,
     radiusSm,
     fontSize,
@@ -13039,7 +13072,7 @@ class GpuOverlayManager {
       const morph = panel.morph?.(this.frameNow);
       const shown = morph ? clamp2(morph.progress, 0, 1) : 1;
       const card = morph ? new DOMRect(morph.x, morph.y, morph.w, morph.h) : pRect;
-      const cardRadius = morph ? morph.radius : tokens.panelRadius;
+      const cardRadius = morph ? morph.radius : tokens.frameRadius;
       if (morph)
         anyMoving = true;
       const masked = morph !== undefined && this.maskCount < MAX_MASKS;
@@ -19880,7 +19913,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;
@@ -19900,6 +19932,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
@@ -20706,6 +20741,62 @@ var init_overlay_model = __esm(() => {
   opposite = { top: "bottom", bottom: "top", left: "right", right: "left" };
 });
 
+// src/ui/tooltip-model.ts
+function tipSchedule(clock, view) {
+  let shown = null;
+  let pending = null;
+  let timer;
+  let hiddenAt = -Infinity;
+  const cancel = () => {
+    if (pending)
+      clock.clear(timer);
+    pending = null;
+  };
+  const hide = (now = false) => {
+    cancel();
+    if (!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();
+      const handoff = shown !== null || clock.now() - hiddenAt < HANDOFF_MS;
+      if (handoff || options.now) {
+        shown = tip;
+        view.show(tip, handoff);
+        return;
+      }
+      pending = tip;
+      timer = clock.set(() => {
+        pending = null;
+        if (!view.connected(tip))
+          return;
+        shown = tip;
+        view.show(tip, false);
+      }, options.delay ?? TIP_DELAY_MS);
+    },
+    hide,
+    leave(within) {
+      if (pending && within(pending))
+        cancel();
+      if (shown && within(shown))
+        hide();
+    }
+  };
+}
+var HANDOFF_MS = 400, TIP_DELAY_MS = 500;
+
 // src/ui/tooltip.ts
 function tipOf(start) {
   let node = start instanceof Element ? start : null;
@@ -20739,9 +20830,6 @@ function controllerOf(doc) {
   let text;
   let keys;
   let target = null;
-  let pending = null;
-  let timer = 0;
-  let hiddenAt = -Infinity;
   let quiet = null;
   let keyboard = false;
   const build = (look) => {
@@ -20786,41 +20874,32 @@ function controllerOf(doc) {
     else
       motion.show();
   };
-  const hide = (now = false) => {
-    win.clearTimeout(timer);
-    pending = null;
-    if (!target)
-      return;
-    target.removeAttribute("aria-describedby");
-    target = null;
-    hiddenAt = performance.now();
-    if (now)
-      motion?.snap(0);
-    else
-      motion?.hide();
-  };
-  const want = (found) => {
+  const 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) => {
+      target?.removeAttribute("aria-describedby");
+      target = null;
+      if (now)
+        motion?.snap(0);
+      else
+        motion?.hide();
+    },
+    connected: ({ el }) => el.isConnected
+  });
+  const hide = (now = false) => schedule.hide(now);
+  const want = (found, now = false) => {
     if (!found)
       return hide();
-    if (found.el === target || found.el === pending?.el)
-      return;
     if (found.el === quiet)
       return;
-    win.clearTimeout(timer);
-    const handoff = target !== null || performance.now() - hiddenAt < HANDOFF_MS;
-    if (handoff) {
-      pending = null;
-      show(found.el, found.tip, true);
-      return;
-    }
-    if (target)
-      hide();
-    pending = found;
-    timer = win.setTimeout(() => {
-      pending = null;
-      if (found.el.isConnected)
-        show(found.el, found.tip, false);
-    }, found.tip.opts.delay ?? 500);
+    schedule.want(found, {
+      now,
+      ...found.tip.opts.delay !== undefined ? { delay: found.tip.opts.delay } : {}
+    });
   };
   doc.addEventListener("pointerover", (e) => {
     if (e.pointerType === "touch")
@@ -20854,11 +20933,10 @@ function controllerOf(doc) {
   doc.addEventListener("focusin", (e) => {
     const found = tipOf(e.target);
     if (found && keyboard && e.target.matches(":focus-visible"))
-      want(found);
+      want(found, true);
   });
   doc.addEventListener("focusout", (e) => {
-    if (target && target.contains(e.target))
-      hide();
+    schedule.leave(({ el }) => el.contains(e.target));
   });
   doc.addEventListener("scroll", () => target && hide(true), true);
   const c = { hide };
@@ -20877,7 +20955,7 @@ function tooltip(el, content, options = {}) {
     c.hide(true);
   };
 }
-var tips, HANDOFF_MS = 400, controllers;
+var tips, controllers;
 var init_tooltip = __esm(() => {
   init_keys();
   init_layer();
@@ -22293,6 +22371,14 @@ var init_inspector = __esm(() => {
   CAP_MORPH = springLinear(SPRINGS.snappy);
 });
 
+// src/panel/description-ids.ts
+function descriptionIds(storeId) {
+  const prefix = `knobs-desc-${++panels2}-${storeId.replace(/[^\w-]/g, "-")}`;
+  let n = 0;
+  return () => `${prefix}-${++n}`;
+}
+var panels2 = 0;
+
 // src/panel/search.ts
 function createSearch(doc, options) {
   const element = doc.createElement("div");
@@ -25531,7 +25617,7 @@ function morphFromChip(chip, root, wake, restored) {
     if (shape)
       return shape;
     const cs = getComputedStyle(root);
-    const r = parseFloat(cs.getPropertyValue("--kv-radius-panel"));
+    const r = parseFloat(cs.getPropertyValue("--kv-radius-frame"));
     if (Number.isFinite(r))
       panelRadius = r;
     shape = doc.createElement("div");
@@ -25747,6 +25833,7 @@ function foldMemory(id, storage) {
       const next = {
         sections: { ...data.sections },
         groups: { ...data.groups },
+        ...data.subsections ? { subsections: { ...data.subsections } } : {},
         [kind]: { ...data[kind], [at]: folded }
       };
       try {
@@ -25758,6 +25845,18 @@ function foldMemory(id, storage) {
 var init_folds = () => {};
 
 // src/panel/position.ts
+function savedPosition(left, top, width, view) {
+  const right = left + width / 2 > view / 2;
+  return right ? { x: view - left - width, y: top, right } : { x: left, y: top };
+}
+function readPosition(raw) {
+  try {
+    const saved = JSON.parse(raw ?? "null");
+    if (saved && Number.isFinite(saved.x) && Number.isFinite(saved.y))
+      return { x: saved.x, y: saved.y, ...saved.right === true ? { right: true } : {} };
+  } catch {}
+  return;
+}
 function positionPanel(panel, header, anchor, id, storage) {
   const doc = panel.ownerDocument;
   const win = doc.defaultView;
@@ -25767,16 +25866,14 @@ function positionPanel(panel, header, anchor, id, storage) {
   let x = bounds.right + w <= win.innerWidth - 8 ? bounds.right + 8 : clampX(bounds.left - w - 8);
   let y = Math.max(8, bounds.top);
   const key = storageKey(id, "position");
-  let hasSaved = false;
+  let saved;
   try {
-    const saved = JSON.parse(storage()?.getItem(key) ?? "null");
-    if (saved && Number.isFinite(saved.x) && Number.isFinite(saved.y)) {
-      x = saved.x;
-      y = saved.y;
-      hasSaved = true;
-    }
+    saved = readPosition(storage()?.getItem(key));
   } catch {}
-  if (!hasSaved) {
+  if (saved) {
+    x = leftOf(saved, w, win.innerWidth);
+    y = saved.y;
+  } else {
     const others = [...doc.querySelectorAll(".knobs-panel:not(.knobs-inline)")].filter((el) => el !== panel).map((el) => el.getBoundingClientRect());
     if (others.length > 0) {
       const overlaps = (cx, cy) => others.some((r) => Math.abs(cx - r.left) < w - 24 && Math.abs(cy - r.top) < 120);
@@ -25800,6 +25897,8 @@ function positionPanel(panel, header, anchor, id, storage) {
   }
   let shown = { x, y };
   const 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))
@@ -25813,22 +25912,35 @@ function positionPanel(panel, header, anchor, id, storage) {
       return;
     event.preventDefault();
     drag = { id: event.pointerId, x: event.clientX, y: event.clientY, left: shown.x, top: shown.y };
-    header.setPointerCapture(event.pointerId);
   };
   header.onpointermove = (event) => {
     if (!drag || event.pointerId !== drag.id)
       return;
+    if (!("dragging" in panel.dataset)) {
+      if (!(event.buttons & 1))
+        return void (drag = undefined);
+      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 = undefined;
+  };
   header.onlostpointercapture = () => {
     if (!drag)
       return;
     drag = undefined;
+    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 {}
   };
   const observer = new ResizeObserver(constrain);
@@ -25843,6 +25955,7 @@ function positionPanel(panel, header, anchor, id, storage) {
     }
   };
 }
+var leftOf = (saved, width, view) => saved.right ? view - width - saved.x : saved.x;
 var init_position = () => {};
 
 // src/panel/dock.ts
@@ -25986,7 +26099,7 @@ function createPresence(root, options) {
         return;
       const look = presenceLook(spring.x, inline, reduced);
       const r = root.getBoundingClientRect();
-      radius ??= parseFloat(win.getComputedStyle(root).getPropertyValue("--kv-radius-panel")) || 12;
+      radius ??= parseFloat(win.getComputedStyle(root).getPropertyValue("--kv-radius-frame")) || 12;
       const s = look.scale;
       const ox = r.left + r.width / 2;
       const oy = inline ? r.top : r.top + r.height / 2;
@@ -26707,8 +26820,11 @@ function buildPanel(controls, host, options) {
     if (page) {
       if (remember)
         foldsKept?.set("groups", group, next);
-    } else if (sessionKept)
+    } else if (sessionKept) {
       writeSession(controls.id, { groups: { ...readSession(controls.id).groups, [group]: next } });
+      if (remember)
+        panelFolds?.set("groups", group, next);
+    }
     refreshFolds();
     positioned?.constrain();
     wakeGpu();
@@ -26757,8 +26873,7 @@ function buildPanel(controls, host, options) {
     gRandom.dataset.hint = `${title} random`;
     gRandom.querySelector(".knobs-icon")?.replaceWith(gDie.node);
     gRandom.onclick = (event) => run(() => rerollGroup(groupName, event.altKey));
-    const rollable = Object.values(controls.schema).some((f) => f.group === groupName && hasValue(f));
-    if (!bound("random") && !bound("mutate") || !rollable)
+    if (!bound("random") && !bound("mutate"))
       gRandom.hidden = true;
     groupDice.set(groupName, { button: gRandom, die: gDie });
     const presets = page ? (controls.groupPresets[groupName] ?? []).slice(0, 9) : [];
@@ -26877,7 +26992,7 @@ function buildPanel(controls, host, options) {
       gHead.tabIndex = -1;
       gHead.setAttribute("role", "button");
       gHead.setAttribute("aria-label", title);
-      const folded = (page ? foldsKept?.get("groups", groupName) : session.groups?.[groupName]) ?? foldAt;
+      const folded = (page ? foldsKept?.get("groups", groupName) : session.groups?.[groupName] ?? panelFolds?.get("groups", groupName)) ?? foldAt;
       folds.set(groupName, folded);
       gHead.setAttribute("aria-expanded", String(!folded));
       if (!page)
@@ -26953,6 +27068,7 @@ function buildPanel(controls, host, options) {
   const session = remember ? readSession(controls.id) : {};
   const foldPort = page?.foldStorage !== undefined ? page.foldStorage : controls.persist === "none" ? null : controls.storage;
   const foldsKept = page && foldPort ? foldMemory(controls.id, () => foldPort) : null;
+  const panelFolds = !page && remember && foldPort ? foldMemory(controls.id, () => foldPort) : null;
   const tracks = new Map;
   const toolbars = new Map;
   const keyedActions = new Map;
@@ -26993,7 +27109,8 @@ function buildPanel(controls, host, options) {
             label,
             ...duration.group !== undefined ? { group: duration.group } : {},
             ...duration.section !== undefined ? { section: duration.section } : {},
-            ...duration.shortcut !== undefined ? { shortcut: duration.shortcut } : {}
+            ...duration.shortcut !== undefined ? { shortcut: duration.shortcut } : {},
+            ...duration.description !== undefined ? { description: duration.description } : {}
           },
           parts: { duration, bounce },
           group: duration.group,
@@ -27503,6 +27620,41 @@ function buildPanel(controls, host, options) {
       return;
     slot.replaceChildren(...node ? [node] : []);
   }
+  const descriptions = el("div");
+  descriptions.hidden = true;
+  root.append(descriptions);
+  const described = new Map;
+  const descriptionId = descriptionIds(controls.id);
+  function describe(row) {
+    const text = row.field.description?.trim() ?? "";
+    const had = described.get(row);
+    if ((had?.text ?? "") === text)
+      return;
+    const inputs = row.choice ? [row.choice.seg, row.choice.menu] : [row.input];
+    if (had) {
+      had.untip();
+      had.node.remove();
+      described.delete(row);
+      for (const input of inputs)
+        input.removeAttribute("aria-describedby");
+    }
+    if (!text)
+      return;
+    const node = el("span", text);
+    node.id = descriptionId();
+    descriptions.append(node);
+    for (const input of inputs)
+      input.setAttribute("aria-describedby", node.id);
+    described.set(row, { text, node, untip: tooltip(row.row, text) });
+  }
+  const undescribe = (row) => {
+    const had = described.get(row);
+    if (!had)
+      return;
+    had.untip();
+    had.node.remove();
+    described.delete(row);
+  };
   const fieldFlag = (field, name) => {
     const v = field[name];
     return typeof v === "function" ? Boolean(v(controls.get())) : Boolean(v);
@@ -27548,6 +27700,7 @@ function buildPanel(controls, host, options) {
     wakeGpu();
   };
   const dropGpu = (row) => {
+    undescribe(row);
     row.dispose?.();
     row.slider?.dispose();
     row.editor?.dispose();
@@ -27606,11 +27759,13 @@ function buildPanel(controls, host, options) {
       if (existing && existing.shape === shapeOf(spec)) {
         kept.delete(spec.id);
         existing.retune(spec);
+        describe(existing);
         next.push(existing);
         continue;
       }
       const row = buildRow(spec);
       decorate(row);
+      describe(row);
       gpuRows.push(...row.gpu);
       entering.add(row);
       next.push(row);
@@ -27814,7 +27969,7 @@ function buildPanel(controls, host, options) {
     const caret = caretSvg();
     node.append(label, caret);
     if (!subFolds.has(id))
-      subFolds.set(id, session.subsections?.[id] ?? options.subsectionFolded?.[name] ?? false);
+      subFolds.set(id, session.subsections?.[id] ?? panelFolds?.get("subsections", id) ?? options.subsectionFolded?.[name] ?? false);
     node.setAttribute("aria-expanded", String(!subFolds.get(id)));
     node.addEventListener("click", (event) => {
       if (event.detail < 2)
@@ -27848,10 +28003,12 @@ function buildPanel(controls, host, options) {
     if (next && rows.some((r) => r.subhead === id && r.row.contains(doc.activeElement)))
       sh.el.focus({ preventScroll: true, focusVisible: false });
     applyVisibility("reveal");
-    if (remember)
+    if (remember) {
       writeSession(controls.id, {
         subsections: { ...readSession(controls.id).subsections, [id]: next }
       });
+      panelFolds?.set("subsections", id, next);
+    }
   }
   const groupTab = (group) => {
     for (const f of Object.values(controls.schema))
@@ -27937,7 +28094,7 @@ function buildPanel(controls, host, options) {
   const searching = () => search?.filtering() ?? false;
   const rowMatches = (r) => {
     const 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 false;
     for (const chip of search.active())
       if (!r.keys.some((k) => chipTests.get(chip)?.(k)))
@@ -28059,6 +28216,10 @@ function buildPanel(controls, host, options) {
   };
   const keysOf = (indices) => indices.flatMap((i) => rows[i]?.keys ?? []);
   const groupKeys = (group) => rows.filter((r) => r.group === group).flatMap((r) => r.keys);
+  const mayRoll = (key) => {
+    const field = controls.schema[key];
+    return Boolean(field && hasValue(field) && field.random !== false);
+  };
   const rerollGroup = (group, nudge) => {
     const roller = groupDice.get(group)?.die;
     if (!roller)
@@ -28205,22 +28366,29 @@ function buildPanel(controls, host, options) {
   apply.setAttribute("aria-label", "Import JSON");
   apply.hidden = true;
   const copy = async (value, inPlace = true) => {
-    try {
-      await doc.defaultView.navigator.clipboard.writeText(value);
+    const done = () => {
       if (inPlace && !copyButton.hidden && headerShown())
         copied();
       else
         say("Copied.");
+    };
+    try {
+      await doc.defaultView.navigator.clipboard.writeText(value);
+      done();
     } catch {
-      text.value = value;
-      if (page)
-        togglePopover(true);
-      reveal(text, true);
-      apply.hidden = true;
-      positioned?.constrain();
-      text.focus();
-      text.select();
-      say("Clipboard unavailable. Copy the selected text.", 6000);
+      if (copyByCommand(doc, value))
+        done();
+      else {
+        text.value = value;
+        if (page)
+          togglePopover(true);
+        reveal(text, true);
+        apply.hidden = true;
+        positioned?.constrain();
+        text.focus();
+        text.select();
+        say("Clipboard unavailable. Copy the selected text.", 6000);
+      }
     }
     wakeGpu();
   };
@@ -28468,10 +28636,17 @@ function buildPanel(controls, host, options) {
     }
     if (randomButton.disabled !== (unlocked === 0))
       randomButton.disabled = unlocked === 0;
+    const rolls = (bound("random") || bound("mutate")) && shows("random");
+    const headerHidden = !rolls || !rows.some((r) => r.keys.some(mayRoll));
+    if (randomButton.hidden !== headerHidden)
+      randomButton.hidden = headerHidden;
     for (const [group, { button }] of groupDice) {
       const off = !options.groupRandom && !groupKeys(group).some((k) => controls.canRoll(k));
       if (button.disabled !== off)
         button.disabled = off;
+      const 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);
@@ -28656,7 +28831,7 @@ function buildPanel(controls, host, options) {
     layout.change(() => {
       layout.openFolds(Boolean(query));
       for (const r of rows) {
-        const 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));
+        const 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;
       }
@@ -29260,7 +29435,20 @@ function buildPanel(controls, host, options) {
       queueScope();
     });
   };
+  const onPressOutside = (event) => {
+    const target = event.target;
+    if (page || !target || root.contains(target))
+      return;
+    if (target.closest?.(".knobs-root,.knobs-layers"))
+      return;
+    setTimeout(() => {
+      const active = doc.activeElement;
+      if (active && root.contains(active))
+        active.blur();
+    });
+  };
   doc.addEventListener("pointerdown", onPress, true);
+  doc.addEventListener("pointerdown", onPressOutside, true);
   doc.addEventListener("pointerup", onRelease, true);
   doc.addEventListener("pointercancel", onRelease, true);
   root.addEventListener("keydown", () => {
@@ -30362,6 +30550,7 @@ function buildPanel(controls, host, options) {
       lens.dispose();
       win?.cancelAnimationFrame(lensFrame);
       doc.removeEventListener("pointerdown", onPress, true);
+      doc.removeEventListener("pointerdown", onPressOutside, true);
       doc.removeEventListener("pointerup", onRelease, true);
       doc.removeEventListener("pointercancel", onRelease, true);
       crumbs?.dispose();
@@ -30569,6 +30758,24 @@ function buildPanel(controls, host, options) {
   }
   return pageApi;
 }
+function copyByCommand(doc, value) {
+  const was = doc.activeElement;
+  const 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 = false;
+  try {
+    ok = doc.execCommand("copy");
+  } catch {
+    ok = false;
+  }
+  area.remove();
+  was?.focus({ preventScroll: true });
+  return ok;
+}
 function createPanel(controls, anchor, close, options) {
   return buildPanel(controls, anchor.ownerDocument.body, {
     ...options,
@@ -30601,6 +30808,7 @@ var init_panel = __esm(() => {
   init_readout();
   init_readout_row();
   init_toast();
+  init_tooltip();
   init_tabs();
   init_tab_transition();
   init_choice();
@@ -30747,7 +30955,7 @@ function attach(controls, element, options = {}) {
   const open = async (restored = false) => {
     if (panel) {
       unpress();
-      panel.focus();
+      focusPanel(panel);
       return;
     }
     if (leaving?.reopen()) {
@@ -30758,7 +30966,7 @@ function attach(controls, element, options = {}) {
         writeSession(controls.id, { open: true });
       chip.setAttribute("aria-expanded", "true");
       update();
-      panel.focus();
+      focusPanel(panel);
       return;
     }
     leaving = undefined;
@@ -30775,7 +30983,7 @@ function attach(controls, element, options = {}) {
       chip.setAttribute("aria-expanded", "true");
       update();
       if (!restored)
-        panel.focus();
+        focusPanel(panel);
     } catch (cause) {
       chip.title = String(cause);
       renderFace("Retry knobs");
@@ -30833,6 +31041,7 @@ function attach(controls, element, options = {}) {
       element.removeAttribute("tabindex");
   };
 }
+var focusPanel = (panel) => panel.element.focus({ preventScroll: true });
 var MODE_KEY = "knobs:mode";
 var MODE_EVENT = "knobs-mode";
 function knobsMode(win) {