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

package/README.md

@@ -777,7 +777,19 @@ mountPanel(station, column, {
   foldable, starting folded. Its header folds and opens it with a click, Enter or Space; it's a ↑↓
   stop of its own, ← folds and → opens. `panel.fold(group, folded?)` does it from code. On a
   [full page](#full-page) the group's tile folds to its header, the cards below follow, and the
-  filter opens it while it runs.
+  filter opens it while it runs. Folded, the header sums the card up on its right, quietly and
+  live: a one-row card's value ("CSS orb"), otherwise its matching group preset (or "Custom"),
+  else its first changed value, else its first choice, then "· 2 changed". The title keeps its
+  room; the summary truncates first. `groupSummary(group, info)` on the mount replaces it, as on a
+  page (`info` is `{ preset, changed, keys }`; `null` shows nothing).
+- **Card descriptions.** A group's `groupDescription` (on any of its fields; the first wins) or the
+  store's `groupDescriptions` puts one muted line under its card's title, wrapping under the whole
+  header. Search matches it.
+- **What's active.** `onActive: (at) => …` hears which card or row the pointer or keyboard focus is
+  on: `{ group }` for a card's header or body, `{ group, key }` for a row, `null` for nothing
+  (pinned cards and group preset strips count). Whichever moved last wins; it's called at most once
+  a frame, never twice with the same value, and once more with `null` when the panel goes. Use it
+  to outline the part of your app a card changes. `mountPage` takes it too.
 - **Group Random by the host.** `groupRandom: (group, mode) => …` runs first for a group's die, `g`
   and `⌥G` (`mode` is `"random"` or `"mutate"`). Return `true` when the host rolled the group (its
   own seeded "Randomize <group>"): the die tumbles and knobs leaves the values alone. Return
@@ -1099,7 +1111,7 @@ A page with many sections reads better folded. `sectionFolded` starts sections f
 
 Folded things say what's in them. A folded group card trades its presets, reset and die for "Compact · 7 changed" (the matching group preset, or "Custom", then its changed rows; each part only when it applies). A folded section's heading reads "2 changed · 3 cards". `groupSummary(group, info)` and `sectionSummary(section, info)` on the mount replace either (`info` is a `FoldSummaryInfo`: `{ preset, changed, keys }`; return `null` for nothing). Group cards fold as in a panel, by a field's or descriptor's `folded`, or `groupFolded` on the mount, `defineControls` or `createRemoteControls` (both take `sectionFolded` too).
 
-Descriptions add one muted line under a title: `groupDescriptions` and `sectionDescriptions` by id (on the store, remote options or the mount), or `groupDescription` / `sectionDescription` on any field or descriptor (the first that gives one wins). `page.card({ description })` does the same for a custom card. The filter matches descriptions too.
+Descriptions add one muted line under a title: `groupDescriptions` and `sectionDescriptions` by id (on the store, remote options or the mount), or `groupDescription` / `sectionDescription` on any field or descriptor (the first that gives one wins). `page.card({ description })` does the same for a custom card. The filter matches descriptions too. Group descriptions show in panels as well, wrapping under the card's header.
 
 What the user folds and opens (sections and group cards) is remembered under `knobs:<id>:folds:v1` (`storageKey(id, "folds")`) as `{ sections: Record<string, boolean>, groups: Record<string, boolean> }`, and wins over `sectionFolded` and `groupFolded`. Only the user's folds and those made with `remember` are written; folds for context (`remember: false`, a highlight's `expand`) and the filter's never are. By default they go to the store's own storage, or nowhere with `persist: "none"`. `foldStorage` on the mount always wins and keeps folds only, never values, locks or variants, so a remote store on `storage: null` (the phone's values always win) can still remember them; `null` keeps none.
 
@@ -2039,11 +2051,12 @@ The package has two core exports selected through the standard `development` con
 | `unlock({ panel, sequence?, query?, corner?, persist? })` / `KONAMI` | Lets a production deploy be unlocked by a typed secret, `?knobs` or three corner taps; returns `{ unlocked, unlock(), lock(), dispose() }`. See [Show, hide and unlock](#show-hide-and-unlock). |
 | `action(label, { run, shortcut?, global?, rebind? })` / `flatSpring({ duration, bounce }, meta)` | A button row, with a shortcut its key cap can rebind; two flat number fields drawn as one spring card. `actionShortcut(field)` reads an action's shortcut as `{ key, scope }`. |
 | Field meta `random?`, `disabled?`, `readOnly?`, `folded?`, `tab?`, `subsection?` | On any field or descriptor: `random: false` stays out of Random and Mutate (switches, seeds and key combinations start out; `random: true` brings them in); `disabled` / `readOnly` (boolean or `(values) => boolean`) gate the row; `folded` makes its group foldable, starting folded; `tab` puts the row on a tab; `subsection` puts it under a sub-heading in its group. |
-| Field meta `groupDescription?: string`, `sectionDescription?: string`, `sectionFolded?: boolean` | On any field or descriptor, for pages (the first field of a group or section that gives one wins): a muted line under the card's title or the section's heading; `sectionFolded` makes the section foldable, starting folded. |
-| `mountPanel(controls, container, options?)` (`knobs/panel`) | An inline panel. Beside theme, density, renderer and keys: `preset`, `header` (`false` or `{ title?, buttons? }`), `crumbs` (`true` adds the scope line), `session`, `groupFolded`, `subsectionFolded`, `tabs`, `tab`, `onTab`, `search`, `groupRandom(group, mode)`, `rowAccessory(key)`, `marks`, `haptics`, `detents`, `sound`. The handle adds `panel.fold(group, folded?)`, `panel.tab(id?)`, `panel.search(query?, chips?)` (returns `{ query, chips }`) and `panel.updateAccessories()`. |
+| Field meta `groupDescription?: string`, `sectionDescription?: string`, `sectionFolded?: boolean` | On any field or descriptor (the first field of a group or section that gives one wins): a muted line under the card's title (in a panel or a page) or a page section's heading; `sectionFolded` makes a page section foldable, starting folded. |
+| `mountPanel(controls, container, options?)` (`knobs/panel`) | An inline panel. Beside theme, density, renderer and keys: `preset`, `header` (`false` or `{ title?, buttons? }`), `crumbs` (`true` adds the scope line), `session`, `groupFolded`, `groupSummary`, `onActive`, `subsectionFolded`, `tabs`, `tab`, `onTab`, `search`, `groupRandom(group, mode)`, `rowAccessory(key)`, `marks`, `haptics`, `detents`, `sound`. The handle adds `panel.fold(group, folded?)`, `panel.tab(id?)`, `panel.search(query?, chips?)` (returns `{ query, chips }`) and `panel.updateAccessories()`. |
 | `sound` (`knobs/panel`) | The page's sound effects (see **Sound**): `enabled`, `enable(on?)`, `volume`, `setVolume(v)`, `theme`, `setTheme("glass" \| "mech")`, `play(cue \| layers, detail?)`, `output()`, `subscribe(listener)`. Panels play only with `sound` on their mount. |
 | `mountPage(controls, container, options?)` (`knobs/panel`) | A full page of group cards in sections under a sticky header; `page.card({ title?, section?, element?, collapsed?, summary?, description? })` adds custom cards (`card.collapse(collapsed?)`, `card.collapsed`, `card.summary(content \| null)`), and `page.highlight({ groups?, sections? } \| null, { reveal?, expand? })` marks what's on screen. Options take `groupLabels`, `sectionLabels`, `groupDescriptions`, `sectionDescriptions`, `presetLabels`, `defaultLabel`, `groupPresetDisplay` and `groupFolded` over the store's. |
-| `MountPageOptions` folds | `sectionFolded?: SectionFolded` (`boolean \| Record<string, boolean>`), `foldStorage?: StoragePort \| null`, `nav?: boolean`, `groupSummary?(group, info: FoldSummaryInfo): string \| Node \| null`, `sectionSummary?(section, info: FoldSummaryInfo): string \| Node \| null`; `FoldSummaryInfo` is `{ preset: string \| null, changed: number, keys: readonly string[] }`. |
+| `MountPageOptions` folds | `sectionFolded?: SectionFolded` (`boolean \| Record<string, boolean>`), `foldStorage?: StoragePort \| null`, `nav?: boolean`, `groupSummary?(group, info: FoldSummaryInfo): string \| Node \| null` (a panel's option too), `sectionSummary?(section, info: FoldSummaryInfo): string \| Node \| null`; `FoldSummaryInfo` is `{ preset: string \| null, changed: number, keys: readonly string[] }`. |
+| `MountPanelOptions.onActive?: (at: PanelActive \| null) => void` | The card (`{ group }`) or row (`{ group, key }`) under the pointer or focus, `null` for nothing; on `mountPanel`, `controls.mount` and `mountPage`. At most once a frame, never the same value twice, and a last `null` when the panel goes. `PanelActive` is `{ group: string, key?: string }`. |
 | `page.fold(group: string, folded?: boolean, options?: PageFoldOptions): void` / `page.foldSection(section: string, folded?: boolean, options?: PageFoldOptions): void` / `page.sectionFolded(section: string): boolean` | Fold a group's card or a section or open it (toggles without `folded`), and ask which a section is. `PageFoldOptions` is `{ remember?: boolean, reveal?: boolean }`; `remember` defaults to `true`. |
 | `page.reveal(target: { section: string } \| { group: string }, options?: { remember?: boolean }): void` | Open a section (or a group's card and its section) and glide it into view; `remember` defaults to `false`. |
 | `page.sections(): readonly PageSectionInfo[]` / `page.onSections(listener: (sections: readonly PageSectionInfo[]) => void): () => void` | `PageSectionInfo` is `{ id, label, description?, folded, changed, groups: PageGroupInfo[] }`; `PageGroupInfo` is `{ id, label, folded, changed, preset: string \| null }`. |

package/dist/dev/{chunk-bejz4qcg.js → chunk-9y93net8.js}

@@ -2632,6 +2632,13 @@ ${GRAD_PROPS}
 .knobs-group-head .knobs-group-die{width:20px;padding:0;display:inline-flex;align-items:center;justify-content:center;border-radius:var(--_k-round);color:var(--_k-fg-3)}
 .knobs-group-head .knobs-group-die[disabled]{opacity:var(--k-disabled-opacity);cursor:default}
 .knobs-panel .knobs-group-head button:where(:not(.knobs-group-reset)){transition:background var(--k-hover-t),color var(--k-hover-t),opacity .2s,transform .12s}
+/* A panel card's header: its title, a folded card's summary and its buttons on one line, and its
+   description on the next. The title takes its room first; the summary gets what's left. */
+.knobs-panel:not(.knobs-page) .knobs-group-head{flex-wrap:wrap;row-gap:0}
+.knobs-panel:not(.knobs-page) .knobs-group-head>.knobs-group-label{flex:1000 1 0;max-width:max-content;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.knobs-group-head>.knobs-group-desc{order:1;flex:0 0 100%;padding:0;line-height:16px;white-space:normal;overflow:visible;text-wrap:pretty}
+.knobs-group-head>.knobs-group-summary{flex:1 1 0;max-width:max-content;margin-left:auto;font-size:var(--_k-text-meta);text-transform:none}
+.knobs-group-head[data-folded]>.knobs-group-summary:not(:empty){display:block}
 
 /* Grouped cards: rows share one surface, split by hairlines that stay put whatever a row is doing */
 .knobs-card{position:relative;margin-bottom:var(--k-section-gap);border-radius:var(--_k-radius);background:var(--_k-fill);overflow:hidden}
@@ -3338,7 +3345,7 @@ ${POINTER_ROW} .knobs-slider.knobs-modified:not(:hover,.knobs-active) .knobs-val
 .knobs-group-summary{display:none;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:var(--_k-fg-3);font-size:var(--_k-text-control);font-weight:500;letter-spacing:0;font-variant-numeric:tabular-nums}
 .knobs-tile[data-folded]>.knobs-group-head .knobs-group-summary:not(:empty){display:block}
 .knobs-tile[data-folded]>.knobs-group-head .knobs-group-ctl{display:none}
-.knobs-tile[data-fold-motion]>.knobs-group-head :is(.knobs-group-summary,.knobs-group-ctl){animation:knobs-fade .2s var(--k-ease) both}
+.knobs-tile[data-fold-motion]>.knobs-group-head :is(.knobs-group-summary,.knobs-group-ctl),.knobs-group-head[data-fold-motion]>.knobs-group-summary{animation:knobs-fade .2s var(--k-ease) both}
 /* A highlight (page.highlight): the rest dims under a veil of the page's colour (--k-page-dim at
    full), and what's highlighted on its own gets a dot in the gutter by its title. The veil and
    dot are written each frame on the panel spring (see page.ts). */

package/dist/dev/{chunk-49hkdggk.js → chunk-e5hbs8fe.js}

@@ -119,7 +119,7 @@ import {
   createHintController,
   pageHints,
   toggleLayer
-} from "./chunk-bejz4qcg.js";
+} from "./chunk-9y93net8.js";
 
 // src/panel/die.ts
 var ROUND = 16 * Math.sqrt(5), DIE = { half: 64 + ROUND, round: ROUND, pip: 12 }, PIPS = {
@@ -4734,6 +4734,33 @@ class GpuOverlayManager {
     let clipped = width > 0 && el.scrollWidth > el.clientWidth;
     return this.clipCache.set(el, { key, text, width, clipped }), clipped;
   }
+  lineCache = /* @__PURE__ */ new WeakMap;
+  linesOf(el, width) {
+    let text = el.textContent ?? "", hit = this.lineCache.get(el);
+    if (hit && hit.text === text && hit.width === width)
+      return hit.lines;
+    let lines = [], node = el.firstChild;
+    if (node?.nodeType === Node.TEXT_NODE) {
+      let top = el.getBoundingClientRect().top, range = el.ownerDocument.createRange(), line, flush = () => {
+        if (line)
+          lines.push({
+            text: text.slice(line.from, line.to),
+            y: (line.top + line.bottom) / 2 - top
+          });
+      };
+      for (let word of text.matchAll(/\S+/g)) {
+        let from = word.index, to = from + word[0].length;
+        range.setStart(node, from), range.setEnd(node, to);
+        let r = range.getBoundingClientRect();
+        if (line && Math.abs(r.top - line.top) < 1)
+          line.to = to, line.bottom = Math.max(line.bottom, r.bottom);
+        else
+          flush(), line = { from, to, top: r.top, bottom: r.bottom };
+      }
+      flush();
+    }
+    return this.lineCache.set(el, { text, width, lines }), lines;
+  }
   curReduced = !1;
   curLocks;
   curSelected = 0;
@@ -6146,12 +6173,10 @@ class GpuOverlayManager {
             this.drawText(this.fit(g.labelEl.textContent ?? "", lr.width, px, tokens.titleWeight), lr.left, cy, withAlpha(tokens.text, 1 - peek), { px, weight: tokens.titleWeight, track: -0.01 });
           if (g.peek && peek > 0.005)
             this.drawText(this.fit(g.peek.textContent ?? "", lr.width, px, tokens.titleWeight), lr.left, cy, withAlpha(tokens.text, peek), { px, weight: tokens.titleWeight, track: -0.01 });
-        } else
-          this.drawText(tokens.groupUpper ? (g.labelEl.textContent ?? "").toUpperCase() : g.labelEl.textContent ?? "", lr.left, lr.top + lr.height * 0.5, tokens.groupColor, {
-            px: Math.max(9, tokens.groupSize),
-            weight: tokens.titleWeight,
-            track: tokens.groupTracking
-          });
+        } else {
+          let label = tokens.groupUpper ? (g.labelEl.textContent ?? "").toUpperCase() : g.labelEl.textContent ?? "", px = Math.max(9, tokens.groupSize);
+          this.drawText(this.domClipped(g.labelEl, label, lr.width) ? this.fit(label, lr.width, px, tokens.titleWeight, void 0, tokens.groupTracking, !0) : label, lr.left, lr.top + lr.height * 0.5, tokens.groupColor, { px, weight: tokens.titleWeight, track: tokens.groupTracking });
+        }
         if (!g.title && tokens.groupDivider[3] > 0 && g.element.previousElementSibling)
           this.pushPrim({
             x: gr.left,
@@ -6162,13 +6187,14 @@ class GpuOverlayManager {
             kind: 1
           });
         if (g.desc && !g.desc.hidden) {
-          let r = this.rectOf(g.desc), cs = getComputedStyle(g.desc), left = r.left + (parseFloat(cs.paddingLeft) || 0), w = r.width - (parseFloat(cs.paddingLeft) || 0) - (parseFloat(cs.paddingRight) || 0);
-          this.drawText(this.fit(g.desc.textContent ?? "", w + 0.5, tokens.textMeta, tokens.labelWeight), left, r.top + r.height * 0.5, tokens.dim, { px: tokens.textMeta, weight: tokens.labelWeight });
+          let r = this.rectOf(g.desc), cs = getComputedStyle(g.desc), left = r.left + (parseFloat(cs.paddingLeft) || 0), w = r.width - (parseFloat(cs.paddingLeft) || 0) - (parseFloat(cs.paddingRight) || 0), lines = cs.whiteSpace.includes("nowrap") ? [{ text: g.desc.textContent ?? "", y: r.height * 0.5 }] : this.linesOf(g.desc, r.width);
+          for (let line of lines)
+            this.drawText(this.fit(line.text, w + 0.5, tokens.textMeta, tokens.labelWeight), left, r.top + line.y, tokens.dim, { px: tokens.textMeta, weight: tokens.labelWeight });
         }
         let fadeIn = (node) => node.parentElement?.closest("[data-fold-motion]") ? Number(getComputedStyle(node).opacity) || 0 : 1;
         if (g.summary && g.summary.getClientRects().length) {
-          let r = this.rectOf(g.summary), a = fadeIn(g.summary);
-          this.drawText(this.fit(g.summary.textContent ?? "", r.width + 0.5, tokens.textControl, 500), r.left, r.top + r.height * 0.5, withAlpha(tokens.dim, a), { px: tokens.textControl, weight: 500 });
+          let r = this.rectOf(g.summary), a = fadeIn(g.summary), px = g.title ? tokens.textControl : tokens.textMeta;
+          this.drawText(this.fit(g.summary.textContent ?? "", r.width + 0.5, px, 500), r.left, r.top + r.height * 0.5, withAlpha(tokens.dim, a), { px, weight: 500 });
         }
         let ctlShown = !g.controls || g.controls.getClientRects().length > 0, headAlpha = this.curAlpha;
         if (g.controls && ctlShown)
@@ -14439,6 +14465,79 @@ function createLens(o) {
   };
 }
 
+// src/panel/active.ts
+var same2 = (a, b) => a === b || a !== null && b !== null && a.group === b.group && a.key === b.key;
+function activeReporter(resolve, report, schedule) {
+  let hover = null, focus = null, lead = "pointer", last = null, cancel, flush = () => {
+    cancel = void 0;
+    let [first, second] = lead === "pointer" ? [hover, focus] : [focus, hover], at = resolve(first) ?? resolve(second);
+    if (same2(at, last))
+      return;
+    last = at, report(at);
+  }, touch = () => {
+    cancel ??= schedule(flush);
+  };
+  return {
+    pointer(target) {
+      if (hover = target, target !== null)
+        lead = "pointer";
+      touch();
+    },
+    focus(target) {
+      if (focus = target, target !== null)
+        lead = "focus";
+      touch();
+    },
+    dispose() {
+      if (cancel?.(), cancel = void 0, hover = focus = null, last !== null)
+        report(last = null);
+    }
+  };
+}
+function activeEvents(reporter, where) {
+  let inMenu = !1;
+  return {
+    over(e) {
+      reporter.pointer(e.target);
+    },
+    move(e) {
+      if (e.movementX || e.movementY)
+        reporter.pointer(e.target);
+    },
+    out(e) {
+      if (where(e.relatedTarget) !== "inside")
+        reporter.pointer(null);
+    },
+    focusIn(e) {
+      let at = where(e.target);
+      if (inMenu = at === "menu", at === "inside")
+        reporter.focus(e.target);
+      else if (at === "outside")
+        reporter.focus(null);
+    },
+    focusOut(e) {
+      if (e.relatedTarget !== null)
+        return;
+      let at = where(e.target);
+      if (at === "inside" || at === "menu" && inMenu)
+        inMenu = !1, reporter.focus(null);
+    }
+  };
+}
+function watchActive(root, resolve, report) {
+  let doc = root.ownerDocument, win = doc.defaultView, reporter = activeReporter(resolve, report, (flush) => {
+    let id = win.requestAnimationFrame(flush);
+    return () => win.cancelAnimationFrame(id);
+  }), events = activeEvents(reporter, (node) => node instanceof Node && root.contains(node) ? "inside" : node instanceof Element && node.closest(".knobs-menu") ? "menu" : "outside"), el = (node) => node, over = (e) => events.over({ target: el(e.target) }), move = (e) => events.move({ target: el(e.target), movementX: e.movementX, movementY: e.movementY }), out = (e) => events.out({ relatedTarget: el(e.relatedTarget) }), focusIn = (e) => events.focusIn({ target: el(e.target) }), focusOut = (e) => events.focusOut({ target: el(e.target), relatedTarget: el(e.relatedTarget) });
+  if (root.addEventListener("pointerover", over), root.addEventListener("pointermove", move), root.addEventListener("pointerout", out), doc.addEventListener("focusin", focusIn), doc.addEventListener("focusout", focusOut), doc.activeElement && root.contains(doc.activeElement))
+    reporter.focus(doc.activeElement);
+  return {
+    dispose() {
+      root.removeEventListener("pointerover", over), root.removeEventListener("pointermove", move), root.removeEventListener("pointerout", out), doc.removeEventListener("focusin", focusIn), doc.removeEventListener("focusout", focusOut), reporter.dispose();
+    }
+  };
+}
+
 // src/panel/has.ts
 function trackHas(root) {
   let doc = root.ownerDocument, win = doc.defaultView, marked = { fv: [], active: [] }, mark = (list, name, nodes, value = "") => {
@@ -14915,6 +15014,19 @@ function createPresence(root, options) {
   };
 }
 
+// src/panel/summary.ts
+function panelFoldSummary(rows, preset) {
+  if (rows.length === 1 && rows[0].value)
+    return rows[0].value;
+  let lead = preset ?? rows.find((r) => r.changed && r.value)?.value ?? rows.find((r) => r.choice && r.value)?.value, changed = rows.filter((r) => r.changed).length;
+  return [lead, changed ? `${changed} changed` : ""].filter(Boolean).join(" · ");
+}
+var baseSignature = (controls) => JSON.stringify([
+  controls.activePreset(),
+  Object.keys(controls.scopes).map((s) => controls.activePreset(s)),
+  Object.keys(controls.groupPresets).map((g) => controls.activeGroupPreset(g))
+]);
+
 // src/panel/panel.ts
 var layer = 2147480001, COPIED_MS = 1000, lastTab = /* @__PURE__ */ new Map, REVEAL_QUIET_MS = 2000, NUDGE_BURST_MS = 300;
 function readableTitle(id) {
@@ -15339,16 +15451,17 @@ function buildPanel(controls, host, options) {
       foldTile(card, next && !filterEl.value.trim(), animate);
     else
       applyVisibility(animate ? "reveal" : "instant");
+    let marked = page ? card.parentElement : head;
+    if (marked) {
+      if (marked.toggleAttribute("data-folded", next), animate)
+        marked.setAttribute("data-fold-motion", ""), clearTimeout(foldMotions.get(marked)), foldMotions.set(marked, setTimeout(() => marked.removeAttribute("data-fold-motion"), 400));
+    }
     if (page) {
-      let tile = card.parentElement;
-      if (tile.toggleAttribute("data-folded", next), animate)
-        tile.setAttribute("data-fold-motion", ""), clearTimeout(foldMotions.get(tile)), foldMotions.set(tile, setTimeout(() => tile.removeAttribute("data-fold-motion"), 400));
       if (remember)
         foldsKept?.set("groups", group, next);
-      refreshFolds();
     } else if (sessionKept)
       writeSession(controls.id, { groups: { ...readSession(controls.id).groups, [group]: next } });
-    positioned?.constrain(), wakeGpu();
+    refreshFolds(), positioned?.constrain(), wakeGpu();
   }
   function foldTile(card, shut, animate) {
     if ((!card.hidden && card.dataset.leaving !== "true") !== shut)
@@ -15444,11 +15557,13 @@ function buildPanel(controls, host, options) {
       desc.className = "knobs-group-desc", groupDescs.set(groupName, desc), describeGroup(groupName);
     }
     if (foldAt !== void 0) {
-      if (page)
-        summary = el("span"), summary.className = "knobs-group-summary", 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);
+      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;
-      folds.set(groupName, folded), gHead.setAttribute("aria-expanded", String(!folded)), gHead.addEventListener("click", (event) => {
+      if (folds.set(groupName, folded), gHead.setAttribute("aria-expanded", String(!folded)), !page)
+        gHead.toggleAttribute("data-folded", folded);
+      gHead.addEventListener("click", (event) => {
         if (event.detail > 1 || event.target.closest("button"))
           return;
         byUser(() => fold(groupName));
@@ -15457,8 +15572,10 @@ function buildPanel(controls, host, options) {
     if (page) {
       let gTitle = el("span");
       gTitle.className = "knobs-group-title", gTitle.append(gLabel, gPeek), gHead.append(gTitle, gRight);
-    } else
-      gHead.append(gLabel, gRight);
+    } else {
+      let desc = el("span");
+      desc.className = "knobs-group-desc", groupDescs.set(groupName, desc), describeGroup(groupName), gHead.append(gLabel, desc, ...summary ? [summary] : [], gRight);
+    }
     return gpuGroups.push({
       element: gHead,
       labelEl: gLabel,
@@ -16116,6 +16233,8 @@ function buildPanel(controls, host, options) {
               motion.push({ node: r.row, show: !0 });
         }
       }
+      for (let group of groupDescs.keys())
+        describeGroup(group);
       for (let [id, sh] of subheads)
         if (!usedSubheads.has(id)) {
           sh.el.remove();
@@ -16166,9 +16285,7 @@ function buildPanel(controls, host, options) {
       let stagger = cascade(motion.length);
       motion.forEach((m, i) => present(m.node, m.show, i * stagger, m.after));
     }
-    if (applyVisibility(animate ? "reveal" : "instant"), page)
-      refreshFolds();
-    if (focused && root.contains(focused) && doc.activeElement !== focused && focused.isConnected)
+    if (applyVisibility(animate ? "reveal" : "instant"), refreshFolds(), focused && root.contains(focused) && doc.activeElement !== focused && focused.isConnected)
       focused.focus({ preventScroll: !0 });
     let gone = focused ? leaving.find((r) => r.row.contains(focused)) : void 0;
     if (gone) {
@@ -16293,7 +16410,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.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))
       return !1;
     for (let chip of search.active())
       if (!r.keys.some((k) => chipTests.get(chip)?.(k)))
@@ -16585,11 +16702,7 @@ function buildPanel(controls, host, options) {
     if (changed)
       wakeGpu();
   }
-  let shownBase = "", baseSignature = () => JSON.stringify([
-    controls.activePreset(),
-    Object.keys(controls.scopes).map((s) => controls.activePreset(s)),
-    Object.keys(controls.groupPresets).map((g) => controls.activeGroupPreset(g))
-  ]);
+  let shownBase = "";
   function update() {
     if (!controls.enabled) {
       close?.();
@@ -16608,7 +16721,7 @@ function buildPanel(controls, host, options) {
         if (!fresh(r) && changed(r))
           changedCount++;
     }
-    let stagger = initialized ? cascade(changedCount) : 0, moving = initialized ? rows.filter(changed) : rows;
+    let stagger = initialized ? cascade(changedCount) : 0, moving = initialized ? rows.filter(changed) : rows, rebasing = baseSignature(controls) !== shownBase;
     if (updateStrips(), batchMeasures(() => {
       for (let row of moving)
         if (row.slider?.prime(), row.editor?.prime?.(), row.choice)
@@ -16616,7 +16729,7 @@ function buildPanel(controls, host, options) {
       for (let chips of groupChips.values())
         primeSegPill(chips.seg, chips.buttons);
       showValues(values, moving, stagger, landing);
-    }), moving.length || !initialized)
+    }), moving.length || !initialized || rebasing)
       refreshFolds();
     shown = values, initialized = !0, wakeGpu();
   }
@@ -16636,7 +16749,7 @@ function buildPanel(controls, host, options) {
     }
   }
   function showValues(values, moving, stagger, landing) {
-    let baseline = controls.baseValues(), fresh = (r) => r.row.dataset.shown === void 0, now = performance.now(), turn = 0, based = baseSignature(), rebased = based !== shownBase;
+    let baseline = controls.baseValues(), fresh = (r) => r.row.dataset.shown === void 0, now = performance.now(), turn = 0, based = baseSignature(controls), rebased = based !== shownBase;
     shownBase = based;
     for (let row of moving) {
       let instant = !initialized || landing || fresh(row);
@@ -16889,16 +17002,45 @@ function buildPanel(controls, host, options) {
     preset: null,
     changed: changedRows((r) => r.section === section),
     keys: rows.filter((r) => r.section === section).flatMap((r) => r.keys)
-  }), changedText = (n) => n && marks ? `${n} changed` : "";
+  }), changedText = (n) => n && marks ? `${n} changed` : "", valueText = (r, values) => {
+    let f = r.field, v = r.value(values), num = (n) => String(Number(n.toFixed(2)));
+    switch (f.kind) {
+      case "choice":
+        return f.labels?.[v] ?? String(v);
+      case "toggle":
+        return v ? "On" : "Off";
+      case "knob":
+        return `${v.toFixed(f.decimals ?? decimals(f.step))}${f.unit ? ` ${f.unit}` : ""}`;
+      case "spring": {
+        let { duration, bounce } = v;
+        return `${num(duration)} s${bounce ? `, bounce ${num(bounce)}` : ""}`;
+      }
+      case "color":
+        return colorHex2(v);
+      case "text":
+        return String(v);
+      default:
+        return "";
+    }
+  }, groupSummary = (group) => {
+    let info = groupInfo(group);
+    if (options.groupSummary)
+      return options.groupSummary(group, info);
+    if (page)
+      return [info.preset, changedText(info.changed)].filter(Boolean).join(" · ") || null;
+    let values = controls.get(), own = rows.filter((r) => r.group === group && !r.leaving && r.keys.length);
+    return panelFoldSummary(own.map((r) => ({
+      value: valueText(r, values),
+      changed: marks && r.keys.some((k) => controls.isModified(k)),
+      choice: r.field.kind === "choice"
+    })), info.preset) || null;
+  };
   function refreshFolds() {
+    for (let [group, node] of groupSummaries)
+      if (folds.get(group))
+        putSummary(node, groupSummary(group));
     if (!layout || !page)
       return;
-    for (let [group, node] of groupSummaries) {
-      if (!folds.get(group))
-        continue;
-      let info = groupInfo(group);
-      putSummary(node, page.groupSummary ? page.groupSummary(group, info) : [info.preset, changedText(info.changed)].filter(Boolean).join(" · ") || null);
-    }
     for (let s of layout.sectionList()) {
       let node = s.label?.querySelector(":scope > .knobs-section-summary");
       if (!node || !s.folded)
@@ -18050,7 +18192,15 @@ function buildPanel(controls, host, options) {
     attributes: !0,
     attributeFilter: ["data-knobs-renderer", "data-theme", "data-appearance", "class", "style"]
   });
-  let panel = {
+  let onActive = options.onActive, active = onActive ? watchActive(root, (node) => {
+    if (!node || !root.contains(node))
+      return null;
+    let r = rows.find((r) => !r.leaving && r.row.contains(node));
+    if (r)
+      return r.group === void 0 ? null : { group: r.group, key: r.key };
+    let card = node.closest("[data-group]");
+    return card && root.contains(card) ? { group: card.dataset.group } : null;
+  }, onActive) : void 0, panel = {
     element: root,
     presetStrip,
     focus() {
@@ -18113,7 +18263,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(), 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("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();

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

@@ -6,7 +6,7 @@ import {
   writeSession,
   injectStyles,
   toggleLayer
-} from "./chunk-bejz4qcg.js";
+} from "./chunk-9y93net8.js";
 
 // src/panel/attach.ts
 function attach(controls, element, options = {}) {
@@ -82,7 +82,7 @@ function attach(controls, element, options = {}) {
       return;
     loading = !0;
     try {
-      let { createPanel } = await import("./chunk-49hkdggk.js");
+      let { createPanel } = await import("./chunk-e5hbs8fe.js");
       if (disposed || !controls.enabled || panel)
         return;
       if (panel = createPanel(controls, element, close, { restored, chip }), remember)

package/dist/dev/index.js

@@ -1526,11 +1526,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-902v1jgd.js").then((m) => m.attach);
+      let load = options.ship ? () => options.ship().then((m) => m.attach) : () => import("./chunk-exaya50m.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-49hkdggk.js").then((m) => m.mountPanel);
+      let load = options.ship ? () => options.ship().then((m) => m.mountPanel) : () => import("./chunk-e5hbs8fe.js").then((m) => m.mountPanel);
       return live(load, (mountPanel) => {
         let panel = mountPanel(controls, container, mountOptions);
         return mountOptions?.onReady?.(panel), panel;

package/dist/panel.js

@@ -3335,6 +3335,13 @@ ${GRAD_PROPS}
 .knobs-group-head .knobs-group-die{width:20px;padding:0;display:inline-flex;align-items:center;justify-content:center;border-radius:var(--_k-round);color:var(--_k-fg-3)}
 .knobs-group-head .knobs-group-die[disabled]{opacity:var(--k-disabled-opacity);cursor:default}
 .knobs-panel .knobs-group-head button:where(:not(.knobs-group-reset)){transition:background var(--k-hover-t),color var(--k-hover-t),opacity .2s,transform .12s}
+/* A panel card's header: its title, a folded card's summary and its buttons on one line, and its
+   description on the next. The title takes its room first; the summary gets what's left. */
+.knobs-panel:not(.knobs-page) .knobs-group-head{flex-wrap:wrap;row-gap:0}
+.knobs-panel:not(.knobs-page) .knobs-group-head>.knobs-group-label{flex:1000 1 0;max-width:max-content;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.knobs-group-head>.knobs-group-desc{order:1;flex:0 0 100%;padding:0;line-height:16px;white-space:normal;overflow:visible;text-wrap:pretty}
+.knobs-group-head>.knobs-group-summary{flex:1 1 0;max-width:max-content;margin-left:auto;font-size:var(--_k-text-meta);text-transform:none}
+.knobs-group-head[data-folded]>.knobs-group-summary:not(:empty){display:block}
 
 /* Grouped cards: rows share one surface, split by hairlines that stay put whatever a row is doing */
 .knobs-card{position:relative;margin-bottom:var(--k-section-gap);border-radius:var(--_k-radius);background:var(--_k-fill);overflow:hidden}
@@ -4041,7 +4048,7 @@ ${POINTER_ROW} .knobs-slider.knobs-modified:not(:hover,.knobs-active) .knobs-val
 .knobs-group-summary{display:none;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:var(--_k-fg-3);font-size:var(--_k-text-control);font-weight:500;letter-spacing:0;font-variant-numeric:tabular-nums}
 .knobs-tile[data-folded]>.knobs-group-head .knobs-group-summary:not(:empty){display:block}
 .knobs-tile[data-folded]>.knobs-group-head .knobs-group-ctl{display:none}
-.knobs-tile[data-fold-motion]>.knobs-group-head :is(.knobs-group-summary,.knobs-group-ctl){animation:knobs-fade .2s var(--k-ease) both}
+.knobs-tile[data-fold-motion]>.knobs-group-head :is(.knobs-group-summary,.knobs-group-ctl),.knobs-group-head[data-fold-motion]>.knobs-group-summary{animation:knobs-fade .2s var(--k-ease) both}
 /* A highlight (page.highlight): the rest dims under a veil of the page's colour (--k-page-dim at
    full), and what's highlighted on its own gets a dot in the gutter by its title. The veil and
    dot are written each frame on the panel spring (see page.ts). */
@@ -11521,6 +11528,44 @@ class GpuOverlayManager {
     this.clipCache.set(el, { key, text, width, clipped });
     return clipped;
   }
+  lineCache = new WeakMap;
+  linesOf(el, width) {
+    const text = el.textContent ?? "";
+    const hit = this.lineCache.get(el);
+    if (hit && hit.text === text && hit.width === width)
+      return hit.lines;
+    const lines = [];
+    const node = el.firstChild;
+    if (node?.nodeType === Node.TEXT_NODE) {
+      const top = el.getBoundingClientRect().top;
+      const range = el.ownerDocument.createRange();
+      let line;
+      const flush = () => {
+        if (line)
+          lines.push({
+            text: text.slice(line.from, line.to),
+            y: (line.top + line.bottom) / 2 - top
+          });
+      };
+      for (const word of text.matchAll(/\S+/g)) {
+        const from = word.index;
+        const to = from + word[0].length;
+        range.setStart(node, from);
+        range.setEnd(node, to);
+        const r = range.getBoundingClientRect();
+        if (line && Math.abs(r.top - line.top) < 1) {
+          line.to = to;
+          line.bottom = Math.max(line.bottom, r.bottom);
+        } else {
+          flush();
+          line = { from, to, top: r.top, bottom: r.bottom };
+        }
+      }
+      flush();
+    }
+    this.lineCache.set(el, { text, width, lines });
+    return lines;
+  }
   curReduced = false;
   curLocks;
   curSelected = 0;
@@ -13320,12 +13365,11 @@ class GpuOverlayManager {
             this.drawText(this.fit(g.labelEl.textContent ?? "", lr.width, px, tokens.titleWeight), lr.left, cy, withAlpha2(tokens.text, 1 - peek), { px, weight: tokens.titleWeight, track: -0.01 });
           if (g.peek && peek > 0.005)
             this.drawText(this.fit(g.peek.textContent ?? "", lr.width, px, tokens.titleWeight), lr.left, cy, withAlpha2(tokens.text, peek), { px, weight: tokens.titleWeight, track: -0.01 });
-        } else
-          this.drawText(tokens.groupUpper ? (g.labelEl.textContent ?? "").toUpperCase() : g.labelEl.textContent ?? "", lr.left, lr.top + lr.height * 0.5, tokens.groupColor, {
-            px: Math.max(9, tokens.groupSize),
-            weight: tokens.titleWeight,
-            track: tokens.groupTracking
-          });
+        } else {
+          const label = tokens.groupUpper ? (g.labelEl.textContent ?? "").toUpperCase() : g.labelEl.textContent ?? "";
+          const px = Math.max(9, tokens.groupSize);
+          this.drawText(this.domClipped(g.labelEl, label, lr.width) ? this.fit(label, lr.width, px, tokens.titleWeight, undefined, tokens.groupTracking, true) : label, lr.left, lr.top + lr.height * 0.5, tokens.groupColor, { px, weight: tokens.titleWeight, track: tokens.groupTracking });
+        }
         if (!g.title && tokens.groupDivider[3] > 0 && g.element.previousElementSibling)
           this.pushPrim({
             x: gr.left,
@@ -13340,13 +13384,16 @@ class GpuOverlayManager {
           const cs = getComputedStyle(g.desc);
           const left = r.left + (parseFloat(cs.paddingLeft) || 0);
           const w = r.width - (parseFloat(cs.paddingLeft) || 0) - (parseFloat(cs.paddingRight) || 0);
-          this.drawText(this.fit(g.desc.textContent ?? "", w + 0.5, tokens.textMeta, tokens.labelWeight), left, r.top + r.height * 0.5, tokens.dim, { px: tokens.textMeta, weight: tokens.labelWeight });
+          const lines = cs.whiteSpace.includes("nowrap") ? [{ text: g.desc.textContent ?? "", y: r.height * 0.5 }] : this.linesOf(g.desc, r.width);
+          for (const line of lines)
+            this.drawText(this.fit(line.text, w + 0.5, tokens.textMeta, tokens.labelWeight), left, r.top + line.y, tokens.dim, { px: tokens.textMeta, weight: tokens.labelWeight });
         }
         const fadeIn = (node) => node.parentElement?.closest("[data-fold-motion]") ? Number(getComputedStyle(node).opacity) || 0 : 1;
         if (g.summary && g.summary.getClientRects().length) {
           const r = this.rectOf(g.summary);
           const a = fadeIn(g.summary);
-          this.drawText(this.fit(g.summary.textContent ?? "", r.width + 0.5, tokens.textControl, 500), r.left, r.top + r.height * 0.5, withAlpha2(tokens.dim, a), { px: tokens.textControl, weight: 500 });
+          const px = g.title ? tokens.textControl : tokens.textMeta;
+          this.drawText(this.fit(g.summary.textContent ?? "", r.width + 0.5, px, 500), r.left, r.top + r.height * 0.5, withAlpha2(tokens.dim, a), { px, weight: 500 });
         }
         const ctlShown = !g.controls || g.controls.getClientRects().length > 0;
         const headAlpha = this.curAlpha;
@@ -25131,6 +25178,114 @@ var init_lens = __esm(() => {
   };
 });
 
+// src/panel/active.ts
+function activeReporter(resolve, report, schedule) {
+  let hover = null;
+  let focus = null;
+  let lead = "pointer";
+  let last = null;
+  let cancel;
+  const flush = () => {
+    cancel = undefined;
+    const [first, second] = lead === "pointer" ? [hover, focus] : [focus, hover];
+    const at = resolve(first) ?? resolve(second);
+    if (same3(at, last))
+      return;
+    last = at;
+    report(at);
+  };
+  const touch = () => {
+    cancel ??= schedule(flush);
+  };
+  return {
+    pointer(target) {
+      hover = target;
+      if (target !== null)
+        lead = "pointer";
+      touch();
+    },
+    focus(target) {
+      focus = target;
+      if (target !== null)
+        lead = "focus";
+      touch();
+    },
+    dispose() {
+      cancel?.();
+      cancel = undefined;
+      hover = focus = null;
+      if (last !== null)
+        report(last = null);
+    }
+  };
+}
+function activeEvents(reporter, where) {
+  let inMenu = false;
+  return {
+    over(e) {
+      reporter.pointer(e.target);
+    },
+    move(e) {
+      if (e.movementX || e.movementY)
+        reporter.pointer(e.target);
+    },
+    out(e) {
+      if (where(e.relatedTarget) !== "inside")
+        reporter.pointer(null);
+    },
+    focusIn(e) {
+      const at = where(e.target);
+      inMenu = at === "menu";
+      if (at === "inside")
+        reporter.focus(e.target);
+      else if (at === "outside")
+        reporter.focus(null);
+    },
+    focusOut(e) {
+      if (e.relatedTarget !== null)
+        return;
+      const at = where(e.target);
+      if (at === "inside" || at === "menu" && inMenu) {
+        inMenu = false;
+        reporter.focus(null);
+      }
+    }
+  };
+}
+function watchActive(root, resolve, report) {
+  const doc = root.ownerDocument;
+  const win = doc.defaultView;
+  const reporter = activeReporter(resolve, report, (flush) => {
+    const id = win.requestAnimationFrame(flush);
+    return () => win.cancelAnimationFrame(id);
+  });
+  const events = activeEvents(reporter, (node) => node instanceof Node && root.contains(node) ? "inside" : node instanceof Element && node.closest(".knobs-menu") ? "menu" : "outside");
+  const el = (node) => node;
+  const over = (e) => events.over({ target: el(e.target) });
+  const move = (e) => events.move({ target: el(e.target), movementX: e.movementX, movementY: e.movementY });
+  const out = (e) => events.out({ relatedTarget: el(e.relatedTarget) });
+  const focusIn = (e) => events.focusIn({ target: el(e.target) });
+  const focusOut = (e) => events.focusOut({ target: el(e.target), relatedTarget: el(e.relatedTarget) });
+  root.addEventListener("pointerover", over);
+  root.addEventListener("pointermove", move);
+  root.addEventListener("pointerout", out);
+  doc.addEventListener("focusin", focusIn);
+  doc.addEventListener("focusout", focusOut);
+  if (doc.activeElement && root.contains(doc.activeElement))
+    reporter.focus(doc.activeElement);
+  return {
+    dispose() {
+      root.removeEventListener("pointerover", over);
+      root.removeEventListener("pointermove", move);
+      root.removeEventListener("pointerout", out);
+      doc.removeEventListener("focusin", focusIn);
+      doc.removeEventListener("focusout", focusOut);
+      reporter.dispose();
+    }
+  };
+}
+var same3 = (a, b) => a === b || a !== null && b !== null && a.group === b.group && a.key === b.key;
+
 // src/panel/has.ts
 function trackHas(root) {
   const doc = root.ownerDocument;
@@ -25879,6 +26034,20 @@ var init_presence = __esm(() => {
   LOOK = ["opacity", "filter", "scale", "transform-origin"];
 });
 
+// src/panel/summary.ts
+function panelFoldSummary(rows, preset) {
+  if (rows.length === 1 && rows[0].value)
+    return rows[0].value;
+  const lead = preset ?? rows.find((r) => r.changed && r.value)?.value ?? rows.find((r) => r.choice && r.value)?.value;
+  const changed = rows.filter((r) => r.changed).length;
+  return [lead, changed ? `${changed} changed` : ""].filter(Boolean).join(" · ");
+}
+var baseSignature = (controls) => JSON.stringify([
+  controls.activePreset(),
+  Object.keys(controls.scopes).map((s) => controls.activePreset(s)),
+  Object.keys(controls.groupPresets).map((g) => controls.activeGroupPreset(g))
+]);
+
 // src/panel/panel.ts
 function readableTitle(id) {
   if (/\s/.test(id))
@@ -26526,19 +26695,21 @@ function buildPanel(controls, host, options) {
       foldTile(card, next && !filterEl.value.trim(), animate);
     else
       applyVisibility(animate ? "reveal" : "instant");
-    if (page) {
-      const tile = card.parentElement;
-      tile.toggleAttribute("data-folded", next);
+    const marked = page ? card.parentElement : head;
+    if (marked) {
+      marked.toggleAttribute("data-folded", next);
       if (animate) {
-        tile.setAttribute("data-fold-motion", "");
-        clearTimeout(foldMotions.get(tile));
-        foldMotions.set(tile, setTimeout(() => tile.removeAttribute("data-fold-motion"), 400));
+        marked.setAttribute("data-fold-motion", "");
+        clearTimeout(foldMotions.get(marked));
+        foldMotions.set(marked, setTimeout(() => marked.removeAttribute("data-fold-motion"), 400));
       }
+    }
+    if (page) {
       if (remember)
         foldsKept?.set("groups", group, next);
-      refreshFolds();
     } else if (sessionKept)
       writeSession(controls.id, { groups: { ...readSession(controls.id).groups, [group]: next } });
+    refreshFolds();
     positioned?.constrain();
     wakeGpu();
   }
@@ -26695,12 +26866,11 @@ function buildPanel(controls, host, options) {
       describeGroup(groupName);
     }
     if (foldAt !== undefined) {
-      if (page) {
-        summary = el("span");
-        summary.className = "knobs-group-summary";
+      summary = el("span");
+      summary.className = "knobs-group-summary";
+      if (page)
         gRight.append(summary);
-        groupSummaries.set(groupName, summary);
-      }
+      groupSummaries.set(groupName, summary);
       caret = caretSvg();
       gRight.append(caret);
       gHead.dataset.foldable = "";
@@ -26710,6 +26880,8 @@ function buildPanel(controls, host, options) {
       const folded = (page ? foldsKept?.get("groups", groupName) : session.groups?.[groupName]) ?? foldAt;
       folds.set(groupName, folded);
       gHead.setAttribute("aria-expanded", String(!folded));
+      if (!page)
+        gHead.toggleAttribute("data-folded", folded);
       gHead.addEventListener("click", (event) => {
         if (event.detail > 1 || event.target.closest("button"))
           return;
@@ -26721,8 +26893,13 @@ function buildPanel(controls, host, options) {
       gTitle.className = "knobs-group-title";
       gTitle.append(gLabel, gPeek);
       gHead.append(gTitle, gRight);
-    } else
-      gHead.append(gLabel, gRight);
+    } else {
+      const desc = el("span");
+      desc.className = "knobs-group-desc";
+      groupDescs.set(groupName, desc);
+      describeGroup(groupName);
+      gHead.append(gLabel, desc, ...summary ? [summary] : [], gRight);
+    }
     gpuGroups.push({
       element: gHead,
       labelEl: gLabel,
@@ -27540,6 +27717,8 @@ function buildPanel(controls, host, options) {
               motion.push({ node: r.row, show: true });
         }
       }
+      for (const group of groupDescs.keys())
+        describeGroup(group);
       for (const [id, sh] of subheads)
         if (!usedSubheads.has(id)) {
           sh.el.remove();
@@ -27598,8 +27777,7 @@ function buildPanel(controls, host, options) {
       motion.forEach((m, i) => present(m.node, m.show, i * stagger, m.after));
     }
     applyVisibility(animate ? "reveal" : "instant");
-    if (page)
-      refreshFolds();
+    refreshFolds();
     if (focused && root.contains(focused) && doc.activeElement !== focused && focused.isConnected)
       focused.focus({ preventScroll: true });
     const gone = focused ? leaving.find((r) => r.row.contains(focused)) : undefined;
@@ -27759,7 +27937,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.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))
       return false;
     for (const chip of search.active())
       if (!r.keys.some((k) => chipTests.get(chip)?.(k)))
@@ -28157,11 +28335,6 @@ function buildPanel(controls, host, options) {
       wakeGpu();
   }
   let shownBase = "";
-  const baseSignature = () => JSON.stringify([
-    controls.activePreset(),
-    Object.keys(controls.scopes).map((s) => controls.activePreset(s)),
-    Object.keys(controls.groupPresets).map((g) => controls.activeGroupPreset(g))
-  ]);
   function update() {
     if (!controls.enabled) {
       close?.();
@@ -28188,6 +28361,7 @@ function buildPanel(controls, host, options) {
     }
     const stagger = initialized ? cascade(changedCount) : 0;
     const moving = initialized ? rows.filter(changed) : rows;
+    const rebasing = baseSignature(controls) !== shownBase;
     updateStrips();
     batchMeasures(() => {
       for (const row of moving) {
@@ -28200,7 +28374,7 @@ function buildPanel(controls, host, options) {
         primeSegPill(chips.seg, chips.buttons);
       showValues(values, moving, stagger, landing);
     });
-    if (moving.length || !initialized)
+    if (moving.length || !initialized || rebasing)
       refreshFolds();
     shown = values;
     initialized = true;
@@ -28226,7 +28400,7 @@ function buildPanel(controls, host, options) {
     const fresh = (r) => r.row.dataset.shown === undefined;
     const now = performance.now();
     let turn = 0;
-    const based = baseSignature();
+    const based = baseSignature(controls);
     const rebased = based !== shownBase;
     shownBase = based;
     for (const row of moving) {
@@ -28531,15 +28705,49 @@ function buildPanel(controls, host, options) {
     keys: rows.filter((r) => r.section === section).flatMap((r) => r.keys)
   });
   const changedText = (n) => n && marks ? `${n} changed` : "";
+  const valueText = (r, values) => {
+    const f = r.field;
+    const v = r.value(values);
+    const num = (n) => String(Number(n.toFixed(2)));
+    switch (f.kind) {
+      case "choice":
+        return f.labels?.[v] ?? String(v);
+      case "toggle":
+        return v ? "On" : "Off";
+      case "knob":
+        return `${v.toFixed(f.decimals ?? decimals(f.step))}${f.unit ? ` ${f.unit}` : ""}`;
+      case "spring": {
+        const { duration, bounce } = v;
+        return `${num(duration)} s${bounce ? `, bounce ${num(bounce)}` : ""}`;
+      }
+      case "color":
+        return colorHex(v);
+      case "text":
+        return String(v);
+      default:
+        return "";
+    }
+  };
+  const groupSummary = (group) => {
+    const info = groupInfo(group);
+    if (options.groupSummary)
+      return options.groupSummary(group, info);
+    if (page)
+      return [info.preset, changedText(info.changed)].filter(Boolean).join(" · ") || null;
+    const values = controls.get();
+    const own = rows.filter((r) => r.group === group && !r.leaving && r.keys.length);
+    return panelFoldSummary(own.map((r) => ({
+      value: valueText(r, values),
+      changed: marks && r.keys.some((k) => controls.isModified(k)),
+      choice: r.field.kind === "choice"
+    })), info.preset) || null;
+  };
   function refreshFolds() {
+    for (const [group, node] of groupSummaries)
+      if (folds.get(group))
+        putSummary(node, groupSummary(group));
     if (!layout || !page)
       return;
-    for (const [group, node] of groupSummaries) {
-      if (!folds.get(group))
-        continue;
-      const info = groupInfo(group);
-      putSummary(node, page.groupSummary ? page.groupSummary(group, info) : [info.preset, changedText(info.changed)].filter(Boolean).join(" · ") || null);
-    }
     for (const s of layout.sectionList()) {
       const node = s.label?.querySelector(":scope > .knobs-section-summary");
       if (!node || !s.folded)
@@ -30057,6 +30265,16 @@ function buildPanel(controls, host, options) {
     attributes: true,
     attributeFilter: ["data-knobs-renderer", "data-theme", "data-appearance", "class", "style"]
   });
+  const onActive = options.onActive;
+  const active = onActive ? watchActive(root, (node) => {
+    if (!node || !root.contains(node))
+      return null;
+    const r = rows.find((r) => !r.leaving && r.row.contains(node));
+    if (r)
+      return r.group === undefined ? null : { group: r.group, key: r.key };
+    const card = node.closest("[data-group]");
+    return card && root.contains(card) ? { group: card.dataset.group } : null;
+  }, onActive) : undefined;
   const panel = {
     element: root,
     presetStrip,
@@ -30147,6 +30365,7 @@ function buildPanel(controls, host, options) {
       doc.removeEventListener("pointerup", onRelease, true);
       doc.removeEventListener("pointercancel", onRelease, true);
       crumbs?.dispose();
+      active?.dispose();
       clearTimeout(escTimer);
       win?.removeEventListener("blur", queueScope);
       win?.removeEventListener("focus", queueScope);

package/dist/types/core/schema.d.ts

@@ -15,7 +15,10 @@ export interface FieldMeta {
     readonly section?: string;
     /** What the section's heading shows (the first field that gives one wins); `section` by default. */
     readonly sectionLabel?: string;
-    /** One muted line under the group's card title on a page (the first field that gives one wins). */
+    /**
+     * One muted line under the group's card title, in a panel or a page (the first field that gives
+     * one wins).
+     */
     readonly groupDescription?: string;
     /** One muted line under the section's heading on a page (the first field that gives one wins). */
     readonly sectionDescription?: string;

package/dist/types/core/store.d.ts

@@ -96,7 +96,7 @@ export interface LabelOptions {
     readonly defaultLabel?: string | Readonly<Record<string, string>>;
     /** How a page card shows its group presets (see `GroupPresetDisplay`). */
     readonly groupPresetDisplay?: GroupPresetDisplay;
-    /** By group id: one muted line under its card's title on a page, over fields' `groupDescription`. */
+    /** By group id: one muted line under its card's title, over fields' `groupDescription`. */
     readonly groupDescriptions?: Readonly<Record<string, string>>;
     /** By section id: one muted line under its heading on a page, over fields' `sectionDescription`. */
     readonly sectionDescriptions?: Readonly<Record<string, string>>;
@@ -146,6 +146,20 @@ export interface HeaderOptions {
      */
     readonly buttons?: readonly HeaderButton[];
 }
+/** What's active in a panel (see `MountPanelOptions.onActive`): a card, or one of its rows. */
+export interface PanelActive {
+    readonly group: string;
+    readonly key?: string;
+}
+/** What a folded card's or section's summary is made of (see `MountPanelOptions.groupSummary`). */
+export interface FoldSummaryInfo {
+    /** The group preset its values match (its name), "Custom" when none does; null without any. */
+    readonly preset: string | null;
+    /** How many of its rows differ from their defaults (a spring's two keys count once). */
+    readonly changed: number;
+    /** Its value keys. */
+    readonly keys: readonly string[];
+}
 export interface MountPanelOptions extends LabelOptions {
     readonly title?: string | false;
     /**
@@ -253,6 +267,20 @@ export interface MountPanelOptions extends LabelOptions {
     readonly sound?: boolean | SoundOptions;
     /** Called once the panel is mounted, with a handle to focus it (a host's "Tune" key). */
     readonly onReady?: (panel: PanelHandle) => void;
+    /**
+     * Called when the card or row under the pointer or focus changes: `{ group }` for a card's
+     * header or body, `{ group, key }` for one of its rows, `null` for nothing (and once more when
+     * the panel goes). Whichever of pointer and focus moved last wins; at most once a frame, never
+     * the same value twice. For outlining the part of the app a card changes.
+     */
+    readonly onActive?: (at: PanelActive | null) => void;
+    /**
+     * What a folded group card's header says on its right. In a panel, by default, a one-row card's
+     * value ("CSS orb"); otherwise its matching group preset, else its first changed value, else
+     * its first choice, then "· N changed". On a page, "<matching preset, or Custom> · N changed".
+     * Each part shows only where it applies; `null` shows nothing.
+     */
+    readonly groupSummary?: (group: string, info: FoldSummaryInfo) => string | Node | null;
     /** What Copy (and ⇧C) puts on the clipboard; `controls.code()` by default. */
     readonly copy?: () => string;
     /**

package/dist/types/index.d.ts

@@ -5,7 +5,7 @@ export { colorHex, parseColor, type Oklch } from "./core/color.js";
 export { sampleGradient, sampleCurve, gradientCss, CURVE_SHAPES, type GradientStop, type GradientSpace, type CurvePoint, type CurveInterp, type SampleGradientOptions, type SampleCurveOptions, } from "./core/ramp.js";
 export { bezierCss, bezierPoint, EASINGS, type Bezier, type EasingName } from "./core/easing.js";
 export { AROUND } from "./core/random.js";
-export { defineControls, type ChangeMeta, type GestureEvent, type ChangeSource, type ChipOptions, type ControlAction, type Controls, type ControlsOptions, type DensityMode, type GroupPreset, type GroupPresetDisplay, type PresetRef, type HeaderButton, type HeaderOptions, type HostHistory, type LabelOptions, type MountPanelOptions, type PanelCommand, type PanelHandle, type PanelModule, type PanelKeys, type PersistMode, type SearchChip, type SearchOptions, type SyncOptions, type RendererMode, type RevealMode, type SectionFolded, type SoundOptions, type SoundTheme, type ThemeMode, type Appearance, } from "./core/store.js";
+export { defineControls, type ChangeMeta, type GestureEvent, type ChangeSource, type ChipOptions, type ControlAction, type Controls, type ControlsOptions, type DensityMode, type FoldSummaryInfo, type GroupPreset, type GroupPresetDisplay, type PresetRef, type HeaderButton, type HeaderOptions, type HostHistory, type LabelOptions, type MountPanelOptions, type PanelActive, type PanelCommand, type PanelHandle, type PanelModule, type PanelKeys, type PersistMode, type SearchChip, type SearchOptions, type SyncOptions, type RendererMode, type RevealMode, type SectionFolded, type SoundOptions, type SoundTheme, type ThemeMode, type Appearance, } from "./core/store.js";
 export { createRemoteControls, descriptorToField, formatSwift, fromDescriptors, fromSettings, type SettingsGroup, type SettingsItem, type ActionDescriptor, type ChoiceOption, type ControlDescriptor, type SpringBindingDescriptor, type ToolbarDescriptor, type ReadoutDescriptor, type ValueDescriptor, type RemoteControls, type RemoteControlsOptions, } from "./core/remote.js";
 export type { LogEntry, LogLevel, TableRows, WatchValue } from "./core/readout.js";
 export { memoryStorage, urlFlag, type StoragePort } from "./core/storage.js";

package/dist/types/panel/active.d.ts

@@ -0,0 +1,53 @@
+import type { PanelActive } from "../core/store.js";
+/**
+ * What's active in a panel, from where the pointer is and where focus is, each told as it moves.
+ * Whichever last moved onto something leads; while it's on nothing (or off the panel), the
+ * other's target stands. `report` hears the result at most once a frame (`schedule`), and never
+ * the same value twice in a row.
+ */
+export declare function activeReporter<T>(resolve: (target: T | null) => PanelActive | null, report: (at: PanelActive | null) => void, schedule: (flush: () => void) => () => void): {
+    pointer(target: T | null): void;
+    focus(target: T | null): void;
+    /** Stops listening; what was active is no longer, so a last `null` is reported. */
+    dispose(): void;
+};
+/** Where an event's node is: in the panel, in one of its menus (on the body), or elsewhere. */
+export type ActiveWhere = "inside" | "menu" | "outside";
+/**
+ * The panel's pointer and focus events, told to `reporter` (see `activeReporter`). Focus that
+ * moves into one of the panel's menus keeps the row that opened it until it comes back, moves
+ * elsewhere, or leaves the menu for nowhere (a blur, the menu closing without handing it back).
+ * A pointer that moves (not just one the page scrolled under) takes the lead back from focus.
+ */
+export declare function activeEvents<T>(reporter: {
+    pointer(target: T | null): void;
+    focus(target: T | null): void;
+}, where: (node: T | null) => ActiveWhere): {
+    over(e: {
+        readonly target: T | null;
+    }): void;
+    move(e: {
+        readonly target: T | null;
+        readonly movementX: number;
+        readonly movementY: number;
+    }): void;
+    out(e: {
+        readonly relatedTarget: T | null;
+    }): void;
+    /** On the document: focus arriving anywhere. */
+    focusIn(e: {
+        readonly target: T | null;
+    }): void;
+    /** On the document: focus going nowhere (the window losing it, a blur) fires no focusin. */
+    focusOut(e: {
+        readonly target: T | null;
+        readonly relatedTarget: T | null;
+    }): void;
+};
+/**
+ * Tells `report` what the pointer or focus is on in `root` (see `activeReporter` and
+ * `activeEvents`), resolving the element under them with `resolve`. Returns a cleanup.
+ */
+export declare function watchActive(root: HTMLElement, resolve: (node: Element | null) => PanelActive | null, report: (at: PanelActive | null) => void): {
+    dispose(): void;
+};

package/dist/types/panel/gpu/renderer.d.ts

@@ -399,9 +399,9 @@ export interface GpuGroupBinding {
     readonly peek?: HTMLElement;
     /** On a page: the header's controls (presets, reset, die), hidden while the card is folded. */
     readonly controls?: HTMLElement;
-    /** On a page: what a folded card's header says in place of its controls. */
+    /** What a folded card's header says (on a page, in place of its controls). */
     readonly summary?: HTMLElement;
-    /** On a page: the muted line under the card's title. */
+    /** The muted line under the card's title. */
     readonly desc?: HTMLElement;
     /** On a page: the group's presets, as named or numbered segments, or a compact menu. */
     readonly presets?: {
@@ -732,6 +732,12 @@ declare class GpuOverlayManager {
     private clipCache;
     /** Whether the DOM lays `el`'s text out wider than its box (so text-overflow shows "…"). */
     private domClipped;
+    private lineCache;
+    /**
+     * The lines the DOM wraps `el`'s text into, each with its middle's offset from `el`'s top, read
+     * back word by word (kept until the text or the width changes).
+     */
+    private linesOf;
     private curReduced;
     private curLocks;
     /** The current row's selection wash (0…1), which its hover wash gives way to. */

package/dist/types/panel/index.d.ts

@@ -5,6 +5,7 @@ export { computeHintPrefixes, type HintBadgeState, type HintCandidate, type Hint
 export { assignPageCodes, hints, pageHints, type HintPainter, type HintSourceOptions, type PageHints, type PageHintTarget, } from "./page-hints.js";
 export { Spring, VelocityTracker } from "./motion.js";
 export { createPanel, mountPage, mountPanel, type Panel, type PanelSearch } from "./panel.js";
+export type { PanelActive } from "../core/store.js";
 export { balancedRuns, type FoldSummaryInfo, type MountPageOptions, type Page, type PageAction, type PageCard, type PageCardOptions, type PageControl, type PageFoldOptions, type PageFoldSource, type PageGroupInfo, type PageHighlight, type PageSectionInfo, } from "./page.js";
 export { createPresetStrip, nextPresetIndex, resolveActivePresetEntry, type ActivePresetState, type PresetEntry, type PresetStrip, } from "./presets.js";
 export { sound, type CueDetail, type Sound, type SoundCue, type SoundLayer, type SoundOptions, type SoundTheme, } from "./sound.js";

package/dist/types/panel/page.d.ts

@@ -1,15 +1,7 @@
 import type { StoragePort } from "../core/storage.js";
-import type { MountPanelOptions, SectionFolded } from "../core/store.js";
+import type { FoldSummaryInfo, MountPanelOptions, SectionFolded } from "../core/store.js";
 import type { Panel } from "./panel.js";
-/** What a folded card's or section's summary is made of (see `MountPageOptions.groupSummary`). */
-export interface FoldSummaryInfo {
-    /** The group preset its values match (its name), "Custom" when none does; null without any. */
-    readonly preset: string | null;
-    /** How many of its rows differ from their defaults (a spring's two keys count once). */
-    readonly changed: number;
-    /** Its value keys. */
-    readonly keys: readonly string[];
-}
+export type { FoldSummaryInfo };
 export interface MountPageOptions extends MountPanelOptions {
     /** Section order; sections not listed follow in the order they first appear. */
     readonly sections?: readonly string[];
@@ -39,11 +31,6 @@ export interface MountPageOptions extends MountPanelOptions {
      * opening it if it's folded.
      */
     readonly nav?: boolean;
-    /**
-     * What a folded group card's header says. By default "<matching preset, or Custom> · N
-     * changed", leaving out what doesn't apply. `null` shows nothing.
-     */
-    readonly groupSummary?: (group: string, info: FoldSummaryInfo) => string | Node | null;
     /** What a folded section's heading says ("N changed · M cards" by default; `preset` is null). */
     readonly sectionSummary?: (section: string, info: FoldSummaryInfo) => string | Node | null;
 }

package/dist/types/panel/summary.d.ts

@@ -0,0 +1,22 @@
+import type { Controls } from "../core/store.js";
+/** A row of a folded panel card, as its summary reads it. */
+export interface SummaryRow {
+    /** Its value as text ("CSS orb", "12 px"), or "" where it has no short form. */
+    readonly value: string;
+    /** Whether it differs from its default. */
+    readonly changed: boolean;
+    /** Whether it's a choice (the likeliest to say what the card is set to). */
+    readonly choice: boolean;
+}
+/**
+ * A folded panel card's summary, by default: a one-row card's value; otherwise the most telling
+ * value (its matching group preset, else its first changed value, else its first choice) and
+ * "N changed", each only where it applies. `preset` is null for a card without group presets.
+ */
+export declare function panelFoldSummary(rows: readonly SummaryRow[], preset: string | null): string;
+/**
+ * Which presets the values are measured against (the panel's, each scope's and each group's).
+ * It changes when one is chosen or saved even if no value moves, which still changes what counts
+ * as changed: marks, resets and folded summaries follow it.
+ */
+export declare const baseSignature: (controls: Pick<Controls<any>, "activePreset" | "activeGroupPreset" | "scopes" | "groupPresets">) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitlangton/knobs",
-  "version": "0.4.0-next.15",
+  "version": "0.4.0-next.16",
   "description": "Per-component tuning controls. Explore in development, ship constants.",
   "type": "module",
   "license": "MIT",