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

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,
@@ -27530,7 +27707,7 @@ function buildPanel(controls, host, options) {
           under = name;
           nodes.push(r.row);
         }
-        const strip = run.group !== undefined && !run.pinned && !stripped.has(run.group) ? groupStripFor(run.group) : undefined;
+        const strip = run.group !== undefined && !stripped.has(run.group) ? groupStripFor(run.group) : undefined;
         if (strip)
           stripped.add(run.group);
         arrange(block.card, strip ? [strip.element, ...nodes] : nodes);
@@ -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;
     /**
@@ -389,13 +417,15 @@ export interface ControlsOptions<S extends Schema> extends LabelOptions {
      * Groups pinned to the top of a panel, under the header and above the tab strip, on every tab
      * (as fields' `pinned: true` pins theirs). Presets and saved variants leave them alone: applying
      * one keeps their values, saving one keeps them out, and they're modified against their defaults.
+     * A scope keyed by the group's own name (`scopedPresets`) still moves it.
      */
     pinned?: readonly string[];
     /**
      * Groups presets leave alone, where they are: `{ Motion: false }`. As with pinned groups,
      * applying a preset or variant keeps their values, saving one leaves them out, and a preset's chip
-     * doesn't drift when they change; but their rows stay in place. A field says it alone with
-     * `inPresets: false`.
+     * doesn't drift when they change; but their rows stay in place. A scope keyed by the group's own
+     * name (`scopedPresets: { Motion: … }`) still moves it: only other scopes' presets leave it
+     * alone. A field says it alone with `inPresets: false`, and then no scope moves it.
      */
     inPresets?: Readonly<Record<string, boolean>>;
     /**
@@ -449,7 +479,7 @@ export interface Controls<S extends Schema = Schema> {
     readonly scopes: Readonly<Record<string, PresetScope<Values<S>>>>;
     /**
      * The scope `key`'s presets come from: a tab or group's id, `""` for `presets`, or undefined
-     * when presets leave it alone (pinned, `inPresets: false`).
+     * when presets leave it alone (pinned, `inPresets: false`, without a scope of its group's own).
      */
     scopeOf(key: string): string | undefined;
     readonly actions: readonly ControlAction<Values<S>>[];
@@ -485,7 +515,10 @@ export interface Controls<S extends Schema = Schema> {
     presetLabel(id: string, scope?: string): string;
     /** Whether `key` is pinned (its group is, see `ControlsOptions.pinned`), outside the presets. */
     isPinned(key: string): boolean;
-    /** Whether presets move `key`: false when it's pinned or says `inPresets: false` (or its group does). */
+    /**
+     * Whether presets move `key`: false when it's pinned or says `inPresets: false` (or its group
+     * does). Its group's own scope may still move it (see `scopeOf`).
+     */
     inPresets(key: string): boolean;
     readonly error: string | null;
     get(): Values<S>;

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";