@kitlangton/knobs 0.4.0-next.10 → 0.4.0-next.11

package/README.md

@@ -765,7 +765,33 @@ panel.tab("emitter") // shows a tab; panel.tab() answers the one showing
   none show on every tab. The strip's underline slides to the chosen tab and the rows cross: what
   leaves folds away as what arrives unfolds, a moment behind. `⌥1`–`⌥9` pick a tab, and `[` / `]`
   cycle tabs when there's no preset strip. The tab last shown is remembered for these controls (and
-  in the session).
+  in the session). The preset strip sits under the tabs and crosses a tab change with the rows; a
+  tab that no preset or saved variant moves shows no strip at all (not even its `+`).
+- **Pinned groups.** Groups that apply to every tab (a global speed, a slow-motion switch) sit at
+  the top of the panel, under its one header and above the tab strip, and a tab change never moves
+  them. Name them on the store, `pinned: ["Global"]`, or say `pinned: true` on a field (the first
+  field of a group that says wins; a field without a group pins itself). A pinned field's `tab` is
+  ignored. Pinned groups keep their own die and reset. Presets and saved variants leave them out:
+  applying one keeps their values, saving one doesn't record them, a preset's chip doesn't drift
+  when they change, and their modified marks are against their defaults. Random rolls them freely
+  even under an active preset. The header's Random and Reset still cover everything, pinned
+  groups included, as they cover every tab; give a field `random: false` to keep it out of
+  Random. Keyboard order and search follow the panel top to bottom: pinned rows, the tabs, the
+  preset strip, then the tab's rows. `controls.isPinned(key)` says whether a key is pinned.
+
+  ```ts
+  const motion = defineControls(
+    "motion",
+    {
+      speed: knob(1, { min: 0.25, max: 4, step: 0.05, unit: "×", group: "Global" }),
+      slow: toggle(false, { label: "Slow motion (0.25×)", group: "Global" }),
+      sidebars: spring({ duration: 0.3, bounce: 0 }, { group: "Sidebars", tab: "Sidebars" }),
+      hover: spring({ duration: 0.14, bounce: 0 }, { group: "Experiments", tab: "Experiments" }),
+    },
+    { pinned: ["Global"], defaultLabel: "Shipped", presets: { snappy, smooth, calm } },
+  )
+  motion.mount(el, { title: "Knobs", tabs: ["Sidebars", "Experiments"] })
+  ```
 - **Sub-headings.** Fields with the same `subsection` in a group sit under a flat heading inside the
   group's card, split off by a hairline (never a card inside a card). They're gathered: a group's
   rows without a sub-heading come first, then each sub-heading's rows together, in the order the

package/dist/dev/{chunk-a7cjgy8x.js → chunk-75gbzbyd.js}

@@ -1,6 +1,6 @@
 import {
   __preload
-} from "./chunk-3ygqgy1x.js";
+} from "./chunk-mjdgzad5.js";
 import {
   applyLook,
   panelLook,
@@ -9,7 +9,7 @@ import {
   writeSession,
   injectStyles,
   toggleLayer
-} from "./chunk-dyq4m24m.js";
+} from "./chunk-j57rhjtm.js";
 
 // src/panel/attach.ts
 function attach(controls, element, options = {}) {
@@ -85,7 +85,7 @@ function attach(controls, element, options = {}) {
       return;
     loading = !0;
     try {
-      let { createPanel } = await (__preload("5pb7ymrd"), import("./chunk-5pb7ymrd.js"));
+      let { createPanel } = await (__preload("bnhzf1tj"), import("./chunk-bnhzf1tj.js"));
       if (disposed || !controls.enabled || panel)
         return;
       if (panel = createPanel(controls, element, close, { restored, chip }), remember)

package/dist/dev/{chunk-5pb7ymrd.js → chunk-bnhzf1tj.js}

@@ -44,7 +44,7 @@ import {
   pushReadout,
   READOUT,
   storageKey
-} from "./chunk-3ygqgy1x.js";
+} from "./chunk-mjdgzad5.js";
 import {
   resolveLook,
   themeOf,
@@ -116,7 +116,7 @@ import {
   createHintController,
   pageHints,
   toggleLayer
-} from "./chunk-dyq4m24m.js";
+} from "./chunk-j57rhjtm.js";
 
 // src/panel/die.ts
 var ROUND = 16 * Math.sqrt(5), DIE = { half: 64 + ROUND, round: ROUND, pip: 12 }, PIPS = {
@@ -994,6 +994,9 @@ function resolveActivePresetEntry(entries, currentValues, lastAppliedId, baseId
     isCustom: !0
   };
 }
+function presetsTouch(entries, keys, defaults) {
+  return entries.some((e) => !(e.kind === "preset" && e.rawId === "default") && keys.some((k) => !same(e.values[k], defaults[k])));
+}
 function nextPresetIndex(count, activeIndex, direction) {
   if (count <= 0)
     return -1;
@@ -1001,7 +1004,7 @@ function nextPresetIndex(count, activeIndex, direction) {
     return direction > 0 ? 0 : count - 1;
   return ((activeIndex + direction) % count + count) % count;
 }
-function createPresetStrip(doc, controls, showVariants, run, onAfterChange, presetLabel = (id) => controls.presetLabel(id)) {
+function createPresetStrip(doc, controls, showVariants, run, onAfterChange, presetLabel = (id) => controls.presetLabel(id), relevant) {
   let wake = () => onAfterChange?.(), el = (tag, cls, text) => {
     let node = doc.createElement(tag);
     if (cls)
@@ -1018,7 +1021,13 @@ function createPresetStrip(doc, controls, showVariants, run, onAfterChange, pres
     saveButton.type = "button", saveButton.tabIndex = -1, saveButton.setAttribute("aria-label", "Save as variant"), saveButton.setAttribute("aria-keyshortcuts", "Shift+S"), saveButton.dataset.hint = "Save", saveButton.onclick = () => run(save);
   if (track.append(pill), root.append(track), saveButton)
     root.append(saveButton);
-  let pillEdges = new Edges, pillY = new Spring(0, 28, 0.86), pillAlpha = new Spring(1, 26, 0.9), entries = [], buttons = [], signature = "", lastVariantsRef = null, lastAppliedId = null, activeState = { activeId: "p:default", activeIndex: 0, isCustom: !1 }, prevActiveId = "", prevActiveIndex = -2, prevIsCustom = !1, prevDrifted = !1, initializedPill = !1, slideUntil = 0;
+  let pillEdges = new Edges, pillY = new Spring(0, 28, 0.86), pillAlpha = new Spring(1, 26, 0.9), entries = [], buttons = [], signature = "", lastVariantsRef = null, lastAppliedId = null, activeState = { activeId: "p:default", activeIndex: 0, isCustom: !1 }, prevActiveId = "", prevActiveIndex = -2, prevIsCustom = !1, prevDrifted = !1, initializedPill = !1, slideUntil = 0, unpinned = (values) => {
+    let out;
+    for (let k of Object.keys(values))
+      if (controls.isPinned(k) && !same(values[k], controls.locked[k]))
+        out ??= { ...values }, out[k] = controls.locked[k];
+    return out ?? values;
+  };
   function buildEntries() {
     let presetEntries = Object.entries(controls.presets).map(([id, presetValues]) => ({
       id: `p:${id}`,
@@ -1035,7 +1044,7 @@ function createPresetStrip(doc, controls, showVariants, run, onAfterChange, pres
       kind: "variant",
       rawId: v.id,
       label: v.name ?? v.id.slice(0, 8),
-      values: v.values,
+      values: unpinned(v.values),
       apply: (coalesce) => controls.variants.load(v.id, { coalesce })
     }));
     return [...presetEntries, ...variantEntries];
@@ -1070,7 +1079,12 @@ function createPresetStrip(doc, controls, showVariants, run, onAfterChange, pres
     if (pill.style.left = `${left}px`, pill.style.right = `${box.trackWidth - right}px`, pill.style.top = `${top}px`, pill.style.height = `${box.height}px`, pill.style.opacity = activeState.drifted ? String(DRIFTED_PILL) : "1", pill.style.scale = "", first)
       doc.defaultView?.requestAnimationFrame(() => pill.style.transition = "");
   }
-  let resolve = () => resolveActivePresetEntry(entries, controls.get(), lastAppliedId, activeEntryId(controls));
+  let resolve = () => resolveActivePresetEntry(entries, unpinned(controls.get()), lastAppliedId, activeEntryId(controls)), wanted = (list) => (list.length > 1 || showVariants) && (relevant?.(list) ?? !0);
+  function syncShown() {
+    let show = wanted(entries);
+    if (root.hidden === show && root.dataset.presence === void 0)
+      root.hidden = !show;
+  }
   function syncSelection(snap = !1) {
     if (activeState = resolve(), lastAppliedId !== null && activeState.activeId !== lastAppliedId)
       lastAppliedId = null;
@@ -1110,12 +1124,12 @@ function createPresetStrip(doc, controls, showVariants, run, onAfterChange, pres
     run(() => {
       let variantsRef = showVariants ? controls.variants.list() : null;
       if (signature !== "" && variantsRef === lastVariantsRef) {
-        syncSelection(!1);
+        syncShown(), syncSelection(!1);
         return;
       }
       lastVariantsRef = variantsRef;
-      let nextEntries = buildEntries(), nextSig = JSON.stringify(nextEntries.map((e) => [e.id, e.label])), shouldShow = nextEntries.length > 1 || showVariants;
-      if (root.hidden = !shouldShow, nextSig !== signature)
+      let nextEntries = buildEntries(), nextSig = JSON.stringify(nextEntries.map((e) => [e.id, e.label]));
+      if (entries = nextEntries, syncShown(), nextSig !== signature)
         signature = nextSig, entries = nextEntries, buttons = entries.map((entry, idx) => {
           let b = el("button", "knobs-preset-chip", entry.label);
           return b.type = "button", b.tabIndex = -1, b.dataset.presetId = entry.id, b.dataset.presetKind = entry.kind, b.dataset.presetName = entry.label, b.setAttribute("role", "radio"), b.setAttribute("aria-label", entry.label), b.onclick = (e) => {
@@ -1286,6 +1300,7 @@ function createPresetStrip(doc, controls, showVariants, run, onAfterChange, pres
     getEntries: () => entries,
     getButtons: () => buttons,
     getActiveState: () => activeState,
+    shows: () => wanted(entries),
     cycle,
     selectById,
     save: () => {
@@ -3762,7 +3777,9 @@ class GpuOverlayManager {
     let ro = new ResizeObserver(() => {
       this.wake();
     });
-    ro.observe(panel.root), ro.observe(panel.body), ro.observe(panel.presetStrip.track);
+    if (ro.observe(panel.root), ro.observe(panel.body), panel.pinned)
+      ro.observe(panel.pinned);
+    ro.observe(panel.presetStrip.track);
     let mo = new MutationObserver(() => {
       this.styleVersion++, this.wake();
     });
@@ -5838,8 +5855,9 @@ class GpuOverlayManager {
             ], this.maskCount * MASK_FLOATS), this.curMask = ++this.maskCount;
         }
       }
-      let ps = panel.presetStrip, hinting = panel.root.classList.contains("knobs-hinting");
+      let ps = panel.presetStrip, hinting = panel.root.classList.contains("knobs-hinting"), stripAlpha = this.curAlpha;
       if (!ps.element.hidden) {
+        this.curAlpha = stripAlpha * this.presence(ps.element);
         let psHovered = this.curPanelHovered && ps.element.matches(":hover");
         this.curSubHovered = psHovered;
         let psRect = this.rectOf(ps.element), trackRect = this.rectOf(ps.track);
@@ -5941,6 +5959,7 @@ class GpuOverlayManager {
             align: "center"
           });
         }
+        this.curAlpha = stripAlpha;
       }
       let tabs = panel.tabs;
       if (tabs && !tabs.element.hidden)
@@ -6042,7 +6061,7 @@ class GpuOverlayManager {
       }
       if (bodyRevealing || pageMoving)
         this.curBypassRectCache = !0;
-      let bodyHovered = this.curPanelHovered && panel.body.matches(":hover");
+      let bodyHovered = this.curPanelHovered && (panel.body.matches(":hover") || Boolean(panel.pinned?.matches(":hover")));
       this.curSubHovered = bodyHovered, this.curPointerRow = bodyHovered && panel.root.hasAttribute("data-k-row-hover");
       let panelAlpha = this.curAlpha;
       for (let g of panel.groups) {
@@ -14856,7 +14875,7 @@ function buildPanel(controls, host, options) {
   if (helpButton?.hidden)
     titleEl.title = `${titleEl.textContent ? `${titleEl.textContent}
 ` : ""}Press ${show("help")} for keyboard shortcuts`;
-  let presetLabel = (id) => options.presetLabels?.[id] ?? (id === "default" ? options.defaultLabel : void 0) ?? controls.presetLabel(id), presetStrip = createPresetStrip(doc, controls, showVariants, run, () => wakeGpu(), presetLabel), tabStrip = createTabStrip(doc, (id, animate) => selectTab(id, animate)), activeTab, searchOptions = typeof options.search === "object" ? options.search : {}, chipTests = /* @__PURE__ */ new Map, search = options.search && !page ? createSearch(doc, {
+  let presetLabel = (id) => options.presetLabels?.[id] ?? (id === "default" ? options.defaultLabel : void 0) ?? controls.presetLabel(id), presetStrip = createPresetStrip(doc, controls, showVariants, run, () => wakeGpu(), presetLabel, (entries) => presetsTouchTab(entries)), tabStrip = createTabStrip(doc, (id, animate) => selectTab(id, animate)), activeTab, searchOptions = typeof options.search === "object" ? options.search : {}, chipTests = /* @__PURE__ */ new Map, search = options.search && !page ? createSearch(doc, {
     placeholder: searchOptions.placeholder ?? "Search",
     chips: (searchOptions.chips ?? ["modified"]).map((chip) => {
       if (chip === "modified")
@@ -14878,7 +14897,10 @@ function buildPanel(controls, host, options) {
   let allActions = [
     ...controls.actions ?? [],
     ...options.actions ?? []
-  ], body = el("div"), tabMotion = tabTransition(body, root, () => wakeGpu()), blocks = [], cards = [], groupResetButtons = /* @__PURE__ */ new Map, groupDice = /* @__PURE__ */ new Map, gpuGroups = [], gpuRows = [], layout, layoutTick = 0, foldSource = null, userFolding = !1, noteFold = (source) => {
+  ], body = el("div"), tabMotion = tabTransition(body, root, () => wakeGpu()), pinnedBody = el("div");
+  if (pinnedBody.className = "knobs-pinned", !page)
+    body.append(presetStrip.element);
+  let blocks = [], cards = [], groupResetButtons = /* @__PURE__ */ new Map, groupDice = /* @__PURE__ */ new Map, gpuGroups = [], gpuRows = [], layout, layoutTick = 0, foldSource = null, userFolding = !1, noteFold = (source) => {
     if (foldSource !== "user")
       foldSource = source;
   }, byUser = (act) => {
@@ -15195,8 +15217,11 @@ function buildPanel(controls, host, options) {
         section: field.section
       });
     }
-    return gatherSubsections(specs);
-  }, gatherSubsections = (specs) => {
+    let planned = gatherSubsections(specs);
+    if (page || !planned.some(pinnedRow))
+      return planned;
+    return [...planned.filter(pinnedRow), ...planned.filter((spec) => !pinnedRow(spec))];
+  }, pinnedRow = (r) => !page && controls.isPinned(r.keys[0] ?? r.id), gatherSubsections = (specs) => {
     let out = [];
     for (let i = 0;i < specs.length; ) {
       let end = i;
@@ -15720,13 +15745,13 @@ function buildPanel(controls, host, options) {
     } else {
       let runs = [];
       for (let r of next) {
-        let last = runs.at(-1);
-        if (last && last.group === r.group)
+        let last = runs.at(-1), pinned = pinnedRow(r);
+        if (last && last.group === r.group && last.pinned === pinned)
           last.rows.push(r);
         else
-          runs.push({ group: r.group, rows: [r] });
+          runs.push({ group: r.group, pinned, rows: [r] });
       }
-      let free = blocks.filter((b) => !b.leaving), chosen = [], usedSubheads = /* @__PURE__ */ new Set;
+      let free = blocks.filter((b) => !b.leaving), chosen = [], pinnedBlocks = /* @__PURE__ */ new Set, usedSubheads = /* @__PURE__ */ new Set;
       for (let run of runs) {
         let at = free.findIndex((b) => b.group === run.group), block = at >= 0 ? free.splice(at, 1)[0] : newBlock(run.group);
         if (at < 0) {
@@ -15741,7 +15766,8 @@ function buildPanel(controls, host, options) {
               motion.push({ node: block.card, show: !0 });
           }
         }
-        chosen.push(block);
+        if (chosen.push(block), run.pinned)
+          pinnedBlocks.add(block);
         let nodes = [], under;
         for (let r of run.rows) {
           let name = r.field.subsection;
@@ -15766,7 +15792,8 @@ function buildPanel(controls, host, options) {
             gpuRows.splice(gi, 1);
           subheads.delete(id);
         }
-      arrange(body, chosen.flatMap((b) => b.head ? [b.head, b.card] : [b.card]));
+      let nodesOf = (list) => list.flatMap((b) => b.head ? [b.head, b.card] : [b.card]);
+      arrange(pinnedBody, nodesOf(chosen.filter((b) => pinnedBlocks.has(b)))), arrange(body, [presetStrip.element, ...nodesOf(chosen.filter((b) => !pinnedBlocks.has(b)))]);
       for (let block of free) {
         block.leaving = !0;
         let fold = () => {
@@ -15872,15 +15899,24 @@ function buildPanel(controls, host, options) {
       if (f.group === group && f.tab !== void 0)
         return f.tab;
     return;
-  }, tabOf = (r) => r.field.tab ?? (r.group !== void 0 ? groupTab(r.group) : void 0), tabList = () => {
+  }, tabOf = (r) => pinnedRow(r) ? void 0 : r.field.tab ?? (r.group !== void 0 ? groupTab(r.group) : void 0), tabList = () => {
     if (page)
       return [];
     let list = (options.tabs ?? []).map((t) => typeof t === "string" ? { id: t, label: readableTitle(t) } : { id: t.id, label: t.label ?? readableTitle(t.id) }), seen = new Set(list.map((t) => t.id));
-    for (let f of Object.values(controls.schema))
-      if (f.tab !== void 0 && !seen.has(f.tab))
+    for (let [key, f] of Object.entries(controls.schema))
+      if (f.tab !== void 0 && !seen.has(f.tab) && !controls.isPinned(key))
         seen.add(f.tab), list.push({ id: f.tab, label: readableTitle(f.tab) });
     return list;
   };
+  function presetsTouchTab(entries) {
+    if (page || activeTab === void 0)
+      return !0;
+    let keys = rows.flatMap((r) => {
+      let tab = tabOf(r);
+      return !pinnedRow(r) && (tab === void 0 || tab === activeTab) ? r.keys : [];
+    });
+    return presetsTouch(entries, keys, controls.locked);
+  }
   function syncTabs() {
     let list = tabList(), has = (id) => id !== void 0 && list.some((t) => t.id === id);
     if (!has(activeTab))
@@ -15934,7 +15970,7 @@ function buildPanel(controls, host, options) {
         want.set(b.head, any);
       want.set(b.card, any && !(b.group !== void 0 && folds.get(b.group) && !finding));
     }
-    return want;
+    return want.set(presetStrip.element, presetStrip.shows()), want;
   }
   let shift = (node, show, delay) => {
     shifting.add(node), node.dataset.presence = show ? "in" : "out", reveal(node, show, () => {
@@ -15951,6 +15987,9 @@ function buildPanel(controls, host, options) {
     }
     if (tabMotion.running)
       tabMotion.finish();
+    let strip = presetStrip.element;
+    if (strip.hidden === want.get(strip))
+      strip.hidden = !want.get(strip);
     let showing = (n) => !n.hidden && n.dataset.leaving !== "true", set = (node, show, animate) => {
       if (showing(node) === show)
         return;
@@ -16155,9 +16194,9 @@ function buildPanel(controls, host, options) {
   } else {
     if (root.append(header), showFooter)
       root.append(popover);
-    if (root.append(tabStrip.element), search)
+    if (root.append(pinnedBody, tabStrip.element), search)
       root.append(search.element);
-    if (root.append(presetStrip.element, body), panelActions.length > 0)
+    if (root.append(body), panelActions.length > 0)
       root.append(customActions);
     root.append(text, apply, status, live);
   }
@@ -16389,35 +16428,44 @@ function buildPanel(controls, host, options) {
       nodes.push(...r.editor?.stops() ?? [r.input]);
     return nodes.push(...body.querySelectorAll("[data-knobs-stop],.knobs-tile>[data-foldable],.knobs-section-head[data-foldable]")), nodes.filter(visible).sort((a, b) => a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1);
   }, actionBarButtons = () => [...customActions.querySelectorAll("button")].filter((b) => visible(b) && !b.disabled), lastActionButton, stops = () => {
-    let list = [];
+    let list = [], strips = [];
     if (visible(tabStrip.element))
-      list.push({
-        contains: (n) => tabStrip.element.contains(n),
-        focus: (o) => tabStrip.focus(o)
+      strips.push({
+        at: tabStrip.element,
+        stops: [{ contains: (n) => tabStrip.element.contains(n), focus: (o) => tabStrip.focus(o) }]
       });
     if (visible(presetStrip.element))
-      list.push({
-        contains: (n) => presetStrip.element.contains(n),
-        focus: (o) => presetStrip.element.focus(o)
+      strips.push({
+        at: presetStrip.element,
+        stops: [
+          {
+            contains: (n) => presetStrip.element.contains(n),
+            focus: (o) => presetStrip.element.focus(o)
+          }
+        ]
       });
     if (page) {
+      for (let strip of strips)
+        list.push(...strip.stops);
       for (let stop of pageStops())
         list.push({ contains: (n) => stop.contains(n), focus: (o) => stop.focus(o) });
       return list;
     }
-    let runs = rows.map((r) => ({
+    let stopOf = (stop) => ({
+      contains: (n) => stop.contains(n),
+      focus: (o) => stop.focus(o)
+    }), shown = (stops) => stops.filter((s) => !s.closest('[hidden],[data-presence="out"]')).map(stopOf), runs = rows.map((r) => ({
       at: r.row,
-      stops: r.editor?.stops() ?? [r.input]
+      stops: shown(r.editor?.stops() ?? [r.input])
     }));
     for (let b of blocks)
       if (b.head?.hasAttribute("data-foldable") && !b.leaving)
-        runs.push({ at: b.head, stops: [b.head] });
+        runs.push({ at: b.head, stops: shown([b.head]) });
     for (let sh of subheads.values())
-      runs.push({ at: sh.el, stops: [sh.el] });
-    runs.sort((a, b) => a.at.compareDocumentPosition(b.at) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1);
+      runs.push({ at: sh.el, stops: shown([sh.el]) });
+    runs.push(...strips), runs.sort((a, b) => a.at.compareDocumentPosition(b.at) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1);
     for (let run of runs)
-      for (let stop of run.stops.filter((s) => !s.closest('[hidden],[data-presence="out"]')))
-        list.push({ contains: (n) => stop.contains(n), focus: (o) => stop.focus(o) });
+      list.push(...run.stops);
     let bar = actionBarButtons();
     if (bar.length)
       list.push({
@@ -17523,6 +17571,7 @@ function buildPanel(controls, host, options) {
     id: controls.id,
     root,
     body,
+    pinned: pinnedBody,
     inline,
     header,
     titleEl,

package/dist/dev/{chunk-dyq4m24m.js → chunk-j57rhjtm.js}

@@ -10,7 +10,7 @@ import {
   DEFAULT_LINEAR,
   motionCss,
   storageKey
-} from "./chunk-3ygqgy1x.js";
+} from "./chunk-mjdgzad5.js";
 
 // src/core/theme.ts
 var property = (k) => k.startsWith("--") ? k : `--k-${k}`;
@@ -2586,6 +2586,9 @@ ${GRAD_PROPS}
 .knobs-group-head{display:flex;align-items:center;justify-content:space-between;gap:8px;min-height:20px;margin:var(--k-group-gap) 0 var(--_k-gap);padding:0 var(--k-group-inset);color:var(--_k-group-label);font-size:var(--k-group-size);font-weight:var(--_k-weight-title);letter-spacing:var(--k-group-tracking);text-transform:var(--k-group-transform)}
 .knobs-panel:not(.knobs-page) .knobs-group-head:not(:first-child){border-top:1px solid var(--k-group-divider);padding-top:var(--k-group-divider-gap)}
 .knobs-group-head:first-child{margin-top:0}
+.knobs-panel:not(.knobs-page) .knobs-presets+.knobs-group-head{margin-top:0;border-top:0;padding-top:0}
+.knobs-pinned{margin-bottom:var(--k-group-gap)}
+.knobs-pinned:empty{display:none}
 .knobs-group-head>span:last-child{display:flex;align-items:center;gap:var(--_k-tray-pad);margin-right:calc((var(--k-icon-sm) - 20px) / 2)}
 .knobs-group-head button{height:20px;padding:0 6px;font-size:var(--_k-text-meta);font-weight:500;letter-spacing:0;text-transform:none;color:var(--_k-fg-2);background:transparent;border-radius:var(--_k-radius-sm);cursor:pointer}
 .knobs-group-head button:is(:hover:not([disabled]),:focus-visible){background:var(--_k-fill-selected);color:var(--_k-fg)}

package/dist/dev/{chunk-3ygqgy1x.js → chunk-mjdgzad5.js}

@@ -516,6 +516,7 @@ var META_KEYS = [
   "folded",
   "sectionFolded",
   "tab",
+  "pinned",
   "subsection"
 ];
 function pickMeta(source, skip = []) {
@@ -527,7 +528,19 @@ function pickMeta(source, skip = []) {
   }
   return out;
 }
-var READOUT_KINDS = /* @__PURE__ */ new Set(["watch", "sparkline", "graph", "meter", "table", "log"]), isReadout2 = (field) => READOUT_KINDS.has(field.kind), hasValue2 = (field) => field.kind !== "action" && field.kind !== "toolbar" && !READOUT_KINDS.has(field.kind), SPRING2 = {
+var READOUT_KINDS = /* @__PURE__ */ new Set(["watch", "sparkline", "graph", "meter", "table", "log"]), isReadout2 = (field) => READOUT_KINDS.has(field.kind), hasValue2 = (field) => field.kind !== "action" && field.kind !== "toolbar" && !READOUT_KINDS.has(field.kind);
+function pinnedKeys(schema, groups = []) {
+  let byGroup = new Map(groups.map((g) => [g, !0]));
+  for (let f of Object.values(schema))
+    if (f.group !== void 0 && f.pinned !== void 0 && !byGroup.has(f.group))
+      byGroup.set(f.group, f.pinned);
+  let out = /* @__PURE__ */ new Set;
+  for (let [key, f] of Object.entries(schema))
+    if (f.group === void 0 ? f.pinned === !0 : byGroup.get(f.group) === !0)
+      out.add(key);
+  return out;
+}
+var SPRING2 = {
   duration: { min: 0.05, max: 2, step: 0.01 },
   bounce: { min: -0.5, max: 1, step: 0.01 }
 };
@@ -1160,4 +1173,4 @@ function urlFlag2(name) {
 }
 var storageKey = (id, part) => `knobs:${encodeURIComponent(id)}:${part}:v1`;
 
-export { __preload, __chunks, maxChroma, oklchToRgb, parseColor2, fitColor, formatColor, colorHex2, EASINGS2, EASING_Y, easingName, bezierPoint2, bezierCss2, normalizeCombo2, letterOf2, comboFromEvent2, heldMods, matchesCombo2, comboParts2, comboLabel2, isTypingTarget, GRADIENT_SAMPLES, sampleGradient2, gradientSamples, gradientCss2, stopColorAt, sampleCurve2, curveSamples, CURVE_SHAPES2, inRange, sameRamp, randomStops, mutateStops, randomPoints, mutatePoints, pickMeta, isReadout2, hasValue2, SPRING2, valueKeys, knob2, choice2, action2, flatSpring2, toggle2, spring2, color2, point2, easing2, vec22, vec32, range2, angle2, seed2, keybind2, gradient2, curve2, toolbarShortcut2, actionShortcut2, toolbar2, watch2, sparkline2, graph2, meter2, table2, log2, wrapAngle2, normalizeField, normalize, isRecord, same, equal, Spring, springMotion2, springResponse, springEasing, springCss2, SPRINGS2, FADE, MOTION, reducedMotion, reducedSpring2, springLinear, DEFAULT_LINEAR, motionCss, RESHAPE, RESET_KEYS, REFRESHES, readoutState, pushReadout, READOUT, memoryStorage2, browserStorage, urlFlag2, storageKey };
+export { __preload, __chunks, maxChroma, oklchToRgb, parseColor2, fitColor, formatColor, colorHex2, EASINGS2, EASING_Y, easingName, bezierPoint2, bezierCss2, normalizeCombo2, letterOf2, comboFromEvent2, heldMods, matchesCombo2, comboParts2, comboLabel2, isTypingTarget, GRADIENT_SAMPLES, sampleGradient2, gradientSamples, gradientCss2, stopColorAt, sampleCurve2, curveSamples, CURVE_SHAPES2, inRange, sameRamp, randomStops, mutateStops, randomPoints, mutatePoints, pickMeta, isReadout2, hasValue2, pinnedKeys, SPRING2, valueKeys, knob2, choice2, action2, flatSpring2, toggle2, spring2, color2, point2, easing2, vec22, vec32, range2, angle2, seed2, keybind2, gradient2, curve2, toolbarShortcut2, actionShortcut2, toolbar2, watch2, sparkline2, graph2, meter2, table2, log2, wrapAngle2, normalizeField, normalize, isRecord, same, equal, Spring, springMotion2, springResponse, springEasing, springCss2, SPRINGS2, FADE, MOTION, reducedMotion, reducedSpring2, springLinear, DEFAULT_LINEAR, motionCss, RESHAPE, RESET_KEYS, REFRESHES, readoutState, pushReadout, READOUT, memoryStorage2, browserStorage, urlFlag2, storageKey };

package/dist/dev/index.js

@@ -27,6 +27,7 @@ import {
   pickMeta,
   isReadout2,
   hasValue2,
+  pinnedKeys,
   SPRING2,
   valueKeys,
   knob2,
@@ -75,8 +76,8 @@ import {
   browserStorage,
   urlFlag2,
   storageKey
-} from "./chunk-3ygqgy1x.js";
-__chunks(import.meta.url,["kdk2476q","5pb7ymrd","a7cjgy8x","3ygqgy1x","dyq4m24m"],[["./index.js",3],["./chunk-5pb7ymrd.js",3,4],["./chunk-a7cjgy8x.js",3,4],["./chunk-3ygqgy1x.js"],["./chunk-dyq4m24m.js",3]],0);
+} from "./chunk-mjdgzad5.js";
+__chunks(import.meta.url,["js6xfzn6","bnhzf1tj","75gbzbyd","mjdgzad5","j57rhjtm"],[["./index.js",3],["./chunk-bnhzf1tj.js",3,4],["./chunk-75gbzbyd.js",3,4],["./chunk-mjdgzad5.js"],["./chunk-j57rhjtm.js",3]],0);
 // src/core/random.ts
 var lattice = (min, max, step, r) => min + Math.floor(r * (Math.floor((max - min) / step + 0.000000001) + 1)) * step, between = (min, max, r) => min + (max - min) * r;
 function pick(field, random) {
@@ -594,12 +595,30 @@ function defineControls(id, input, options = {}) {
   let schema = Object.freeze({ ...input }), locked = normalize(schema, {}), actions = Object.freeze([...options.actions ?? []]), { theme, appearance } = options, density = options.density ?? "default", renderer = options.renderer ?? "auto", enabled = () => typeof options.enabled === "function" ? options.enabled() : options.enabled ?? (Boolean(options.ship) || isUnlocked() || typeof location < "u" && ["localhost", "127.0.0.1", "[::1]"].includes(location.hostname)), storage = () => options.storage === void 0 ? browserStorage() : options.storage, persistMode = options.persist ?? "all", valueStorage = () => persistMode === "all" ? storage() : null, variantStorage = () => persistMode === "none" ? null : storage(), draw = options.random ?? Math.random, hostHistory = options.history, unsubscribeHistory, unsubscribeUnlock, listeners = /* @__PURE__ */ new Set, refreshes = 0, notify = () => {
     for (let cb of [...listeners])
       cb();
-  }, mixed = /* @__PURE__ */ new Set, current = locked, read = !1, error = null, locks = /* @__PURE__ */ new Set, bindings = /* @__PURE__ */ new Map, comparing = null, landing = !1, echo = Math.max(0, options.echo ?? 0), grabbed = /* @__PURE__ */ new Set, changedAt = /* @__PURE__ */ new Map, sent = /* @__PURE__ */ new Map, pending = /* @__PURE__ */ new Map, echoTimer, now = () => typeof performance < "u" ? performance.now() : Date.now(), isHeld = (key) => grabbed.has(key) || echo > 0 && now() - (changedAt.get(key) ?? -1 / 0) < echo, NO_BASE = Object.freeze({ preset: null, groups: Object.freeze({}) }), base = NO_BASE, past = [], future = [], HISTORY = 100, stateKey = storageKey(id, "state"), buildPresets = () => Object.freeze(Object.fromEntries([
+  }, mixed = /* @__PURE__ */ new Set, current = locked, read = !1, error = null, locks = /* @__PURE__ */ new Set, bindings = /* @__PURE__ */ new Map, comparing = null, landing = !1, echo = Math.max(0, options.echo ?? 0), grabbed = /* @__PURE__ */ new Set, changedAt = /* @__PURE__ */ new Map, sent = /* @__PURE__ */ new Map, pending = /* @__PURE__ */ new Map, echoTimer, now = () => typeof performance < "u" ? performance.now() : Date.now(), isHeld = (key) => grabbed.has(key) || echo > 0 && now() - (changedAt.get(key) ?? -1 / 0) < echo, NO_BASE = Object.freeze({ preset: null, groups: Object.freeze({}) }), base = NO_BASE, past = [], future = [], HISTORY = 100, stateKey = storageKey(id, "state"), pinnedOf, pinned = () => {
+    if (pinnedOf?.schema !== schema)
+      pinnedOf = { schema, keys: pinnedKeys(schema, options.pinned) };
+    return pinnedOf.keys;
+  }, unpinned = (values) => {
+    let keys = pinned();
+    if (keys.size === 0)
+      return values;
+    let out = { ...values };
+    for (let k of keys)
+      if (Object.hasOwn(locked, k))
+        out[k] = locked[k];
+    return Object.freeze(out);
+  }, presetPatch = (values) => {
+    let keys = pinned();
+    if (keys.size === 0)
+      return values;
+    return Object.fromEntries(Object.entries(values).filter(([k]) => !keys.has(k)));
+  }, buildPresets = () => Object.freeze(Object.fromEntries([
     ["default", locked],
     ...Object.entries(options.presets ?? {}).map(([id, patch]) => {
       if (id === "default" || id === "custom")
         throw Error(`Reserved preset id: ${id}`);
-      return [id, normalize(schema, { ...locked, ...patch })];
+      return [id, unpinned(normalize(schema, { ...locked, ...patch }))];
     })
   ])), presets = buildPresets(), buildGroupPresets = () => Object.freeze(Object.fromEntries(Object.entries(options.groupPresets ?? {}).map(([group, list]) => {
     let named = list.flatMap((p) => Object.keys(p.values).filter((k) => Object.hasOwn(schema, k))), covered = new Set((named.length ? named : Object.keys(schema).filter((k) => schema[k].group === group)).filter((k) => hasValue2(schema[k])));
@@ -700,7 +719,7 @@ function defineControls(id, input, options = {}) {
     else if (ref?.kind === "variant") {
       let found = list?.find((v) => v.id === ref.id);
       if (found)
-        out = normalize(schema, found.values);
+        out = unpinned(normalize(schema, found.values));
     }
     let groups = Object.entries(b.groups);
     if (groups.length) {
@@ -712,11 +731,10 @@ function defineControls(id, input, options = {}) {
     return baseCache = { base: b, schema, presets, groupPresets, variants: list, values }, values;
   }
   let covered = (key) => {
-    let b = activeBase();
-    if (b.preset)
+    let b = activeBase(), group = schema[key]?.group;
+    if (group !== void 0 && Object.hasOwn(b.groups, group))
       return !0;
-    let group = schema[key]?.group;
-    return group !== void 0 && Object.hasOwn(b.groups, group);
+    return b.preset !== null && !pinned().has(key);
   };
   function declaredShortcut(id) {
     let slash = id.indexOf("/"), key = slash < 0 ? id : id.slice(0, slash), field = Object.hasOwn(schema, key) ? schema[key] : void 0;
@@ -986,7 +1004,7 @@ function defineControls(id, input, options = {}) {
     listen(cb) {
       return readoutListeners.add(cb), () => readoutListeners.delete(cb);
     }
-  }, variants = createVariants(() => schema, id, storageKey(id, "variants"), variantStorage, get, (v, variant, coalesce) => write(v, { source: "variant", coalesce }, makeBase(Object.freeze({ kind: "variant", id: variant }), {})), notify, enabled), resettable = (keys) => (keys ?? fieldKeys()).filter((k) => valueField(k) && !blocked(k));
+  }, variants = createVariants(() => schema, id, storageKey(id, "variants"), variantStorage, () => unpinned(get()), (v, variant, coalesce) => write(presetPatch(v), { source: "variant", coalesce }, makeBase(Object.freeze({ kind: "variant", id: variant }), {})), notify, enabled), resettable = (keys) => (keys ?? fieldKeys()).filter((k) => valueField(k) && !blocked(k));
   function offBase(keys) {
     if (!hasBase())
       return !1;
@@ -1071,6 +1089,7 @@ function defineControls(id, input, options = {}) {
     groupFolded: options.groupFolded,
     sectionFolded: options.sectionFolded,
     presetLabel: (presetId) => options.presetLabels?.[presetId] ?? (presetId === "default" ? options.defaultLabel : void 0) ?? presetId,
+    isPinned: (key) => pinned().has(key),
     get,
     set,
     sync,
@@ -1345,9 +1364,12 @@ function defineControls(id, input, options = {}) {
     preset(id, presetOptions) {
       if (!Object.hasOwn(presets, id))
         throw Error(`Unknown preset: ${id}`);
-      write(presets[id], { source: "preset", coalesce: presetOptions?.coalesce }, id === "default" ? NO_BASE : makeBase(Object.freeze({ kind: "preset", id }), {}));
+      write(presetPatch(presets[id]), { source: "preset", coalesce: presetOptions?.coalesce }, id === "default" ? NO_BASE : makeBase(Object.freeze({ kind: "preset", id }), {}));
+    },
+    matchingPreset: () => {
+      let cur = unpinned(get());
+      return Object.keys(presets).find((id) => equal(cur, presets[id])) ?? "custom";
     },
-    matchingPreset: () => Object.keys(presets).find((id) => equal(get(), presets[id])) ?? "custom",
     get groupPresets() {
       return groupPresets;
     },
@@ -1378,11 +1400,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) : () => (__preload("a7cjgy8x"), import("./chunk-a7cjgy8x.js")).then((m) => m.attach);
+      let load = options.ship ? () => options.ship().then((m) => m.attach) : () => (__preload("75gbzbyd"), import("./chunk-75gbzbyd.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) : () => (__preload("5pb7ymrd"), import("./chunk-5pb7ymrd.js")).then((m) => m.mountPanel);
+      let load = options.ship ? () => options.ship().then((m) => m.mountPanel) : () => (__preload("bnhzf1tj"), import("./chunk-bnhzf1tj.js")).then((m) => m.mountPanel);
       return live(load, (mountPanel) => {
         let panel = mountPanel(controls, container, mountOptions);
         return mountOptions?.onReady?.(panel), panel;
@@ -1674,6 +1696,7 @@ function createRemoteControls(id, descriptors, options = {}) {
     tunable: options.tunable,
     history: options.history,
     presets: options.presets,
+    pinned: options.pinned,
     groupPresets: options.groupPresets,
     onPreset: options.onPreset,
     actions: options.actions,

package/dist/index.js

@@ -460,6 +460,7 @@ var META_KEYS = [
   "folded",
   "sectionFolded",
   "tab",
+  "pinned",
   "subsection"
 ];
 function pickMeta(source, skip = []) {
@@ -471,7 +472,19 @@ function pickMeta(source, skip = []) {
   }
   return out;
 }
-var READOUT_KINDS = /* @__PURE__ */ new Set(["watch", "sparkline", "graph", "meter", "table", "log"]), isReadout = (field) => READOUT_KINDS.has(field.kind), hasValue = (field) => field.kind !== "action" && field.kind !== "toolbar" && !READOUT_KINDS.has(field.kind), SPRING = {
+var READOUT_KINDS = /* @__PURE__ */ new Set(["watch", "sparkline", "graph", "meter", "table", "log"]), isReadout = (field) => READOUT_KINDS.has(field.kind), hasValue = (field) => field.kind !== "action" && field.kind !== "toolbar" && !READOUT_KINDS.has(field.kind);
+function pinnedKeys(schema, groups = []) {
+  let byGroup = new Map(groups.map((g) => [g, !0]));
+  for (let f of Object.values(schema))
+    if (f.group !== void 0 && f.pinned !== void 0 && !byGroup.has(f.group))
+      byGroup.set(f.group, f.pinned);
+  let out = /* @__PURE__ */ new Set;
+  for (let [key, f] of Object.entries(schema))
+    if (f.group === void 0 ? f.pinned === !0 : byGroup.get(f.group) === !0)
+      out.add(key);
+  return out;
+}
+var SPRING = {
   duration: { min: 0.05, max: 2, step: 0.01 },
   bounce: { min: -0.5, max: 1, step: 0.01 }
 };
@@ -1612,12 +1625,30 @@ function defineControls(id, input, options = {}) {
   let schema = Object.freeze({ ...input }), locked = normalize(schema, {}), actions = Object.freeze([...options.actions ?? []]), { theme, appearance } = options, density = options.density ?? "default", renderer = options.renderer ?? "auto", enabled = () => (Boolean(options.ship) || isUnlocked()) && (typeof options.enabled === "function" ? options.enabled() : options.enabled ?? (Boolean(options.ship) || isUnlocked() || typeof location < "u" && ["localhost", "127.0.0.1", "[::1]"].includes(location.hostname))), storage = () => options.storage === void 0 ? browserStorage() : options.storage, persistMode = options.persist ?? "all", valueStorage = () => persistMode === "all" ? storage() : null, variantStorage = () => persistMode === "none" ? null : storage(), draw = options.random ?? Math.random, hostHistory = options.history, unsubscribeHistory, unsubscribeUnlock, listeners = /* @__PURE__ */ new Set, refreshes = 0, notify = () => {
     for (let cb of [...listeners])
       cb();
-  }, mixed = /* @__PURE__ */ new Set, current = locked, read = !1, error = null, locks = /* @__PURE__ */ new Set, bindings = /* @__PURE__ */ new Map, comparing = null, landing = !1, echo = Math.max(0, options.echo ?? 0), grabbed = /* @__PURE__ */ new Set, changedAt = /* @__PURE__ */ new Map, sent = /* @__PURE__ */ new Map, pending = /* @__PURE__ */ new Map, echoTimer, now = () => typeof performance < "u" ? performance.now() : Date.now(), isHeld = (key) => grabbed.has(key) || echo > 0 && now() - (changedAt.get(key) ?? -1 / 0) < echo, NO_BASE = Object.freeze({ preset: null, groups: Object.freeze({}) }), base = NO_BASE, past = [], future = [], HISTORY = 100, stateKey = storageKey(id, "state"), buildPresets = () => Object.freeze(Object.fromEntries([
+  }, mixed = /* @__PURE__ */ new Set, current = locked, read = !1, error = null, locks = /* @__PURE__ */ new Set, bindings = /* @__PURE__ */ new Map, comparing = null, landing = !1, echo = Math.max(0, options.echo ?? 0), grabbed = /* @__PURE__ */ new Set, changedAt = /* @__PURE__ */ new Map, sent = /* @__PURE__ */ new Map, pending = /* @__PURE__ */ new Map, echoTimer, now = () => typeof performance < "u" ? performance.now() : Date.now(), isHeld = (key) => grabbed.has(key) || echo > 0 && now() - (changedAt.get(key) ?? -1 / 0) < echo, NO_BASE = Object.freeze({ preset: null, groups: Object.freeze({}) }), base = NO_BASE, past = [], future = [], HISTORY = 100, stateKey = storageKey(id, "state"), pinnedOf, pinned = () => {
+    if (pinnedOf?.schema !== schema)
+      pinnedOf = { schema, keys: pinnedKeys(schema, options.pinned) };
+    return pinnedOf.keys;
+  }, unpinned = (values) => {
+    let keys = pinned();
+    if (keys.size === 0)
+      return values;
+    let out = { ...values };
+    for (let k of keys)
+      if (Object.hasOwn(locked, k))
+        out[k] = locked[k];
+    return Object.freeze(out);
+  }, presetPatch = (values) => {
+    let keys = pinned();
+    if (keys.size === 0)
+      return values;
+    return Object.fromEntries(Object.entries(values).filter(([k]) => !keys.has(k)));
+  }, buildPresets = () => Object.freeze(Object.fromEntries([
     ["default", locked],
     ...Object.entries(options.presets ?? {}).map(([id, patch]) => {
       if (id === "default" || id === "custom")
         throw Error(`Reserved preset id: ${id}`);
-      return [id, normalize(schema, { ...locked, ...patch })];
+      return [id, unpinned(normalize(schema, { ...locked, ...patch }))];
     })
   ])), presets = buildPresets(), buildGroupPresets = () => Object.freeze(Object.fromEntries(Object.entries(options.groupPresets ?? {}).map(([group, list]) => {
     let named = list.flatMap((p) => Object.keys(p.values).filter((k) => Object.hasOwn(schema, k))), covered = new Set((named.length ? named : Object.keys(schema).filter((k) => schema[k].group === group)).filter((k) => hasValue(schema[k])));
@@ -1718,7 +1749,7 @@ function defineControls(id, input, options = {}) {
     else if (ref?.kind === "variant") {
       let found = list?.find((v) => v.id === ref.id);
       if (found)
-        out = normalize(schema, found.values);
+        out = unpinned(normalize(schema, found.values));
     }
     let groups = Object.entries(b.groups);
     if (groups.length) {
@@ -1730,11 +1761,10 @@ function defineControls(id, input, options = {}) {
     return baseCache = { base: b, schema, presets, groupPresets, variants: list, values }, values;
   }
   let covered = (key) => {
-    let b = activeBase();
-    if (b.preset)
+    let b = activeBase(), group = schema[key]?.group;
+    if (group !== void 0 && Object.hasOwn(b.groups, group))
       return !0;
-    let group = schema[key]?.group;
-    return group !== void 0 && Object.hasOwn(b.groups, group);
+    return b.preset !== null && !pinned().has(key);
   };
   function declaredShortcut(id) {
     let slash = id.indexOf("/"), key = slash < 0 ? id : id.slice(0, slash), field = Object.hasOwn(schema, key) ? schema[key] : void 0;
@@ -2004,7 +2034,7 @@ function defineControls(id, input, options = {}) {
     listen(cb) {
       return readoutListeners.add(cb), () => readoutListeners.delete(cb);
     }
-  }, variants = createVariants(() => schema, id, storageKey(id, "variants"), variantStorage, get, (v, variant, coalesce) => write(v, { source: "variant", coalesce }, makeBase(Object.freeze({ kind: "variant", id: variant }), {})), notify, enabled), resettable = (keys) => (keys ?? fieldKeys()).filter((k) => valueField(k) && !blocked(k));
+  }, variants = createVariants(() => schema, id, storageKey(id, "variants"), variantStorage, () => unpinned(get()), (v, variant, coalesce) => write(presetPatch(v), { source: "variant", coalesce }, makeBase(Object.freeze({ kind: "variant", id: variant }), {})), notify, enabled), resettable = (keys) => (keys ?? fieldKeys()).filter((k) => valueField(k) && !blocked(k));
   function offBase(keys) {
     if (!hasBase())
       return !1;
@@ -2089,6 +2119,7 @@ function defineControls(id, input, options = {}) {
     groupFolded: options.groupFolded,
     sectionFolded: options.sectionFolded,
     presetLabel: (presetId) => options.presetLabels?.[presetId] ?? (presetId === "default" ? options.defaultLabel : void 0) ?? presetId,
+    isPinned: (key) => pinned().has(key),
     get,
     set,
     sync,
@@ -2363,9 +2394,12 @@ function defineControls(id, input, options = {}) {
     preset(id, presetOptions) {
       if (!Object.hasOwn(presets, id))
         throw Error(`Unknown preset: ${id}`);
-      write(presets[id], { source: "preset", coalesce: presetOptions?.coalesce }, id === "default" ? NO_BASE : makeBase(Object.freeze({ kind: "preset", id }), {}));
+      write(presetPatch(presets[id]), { source: "preset", coalesce: presetOptions?.coalesce }, id === "default" ? NO_BASE : makeBase(Object.freeze({ kind: "preset", id }), {}));
+    },
+    matchingPreset: () => {
+      let cur = unpinned(get());
+      return Object.keys(presets).find((id) => equal(cur, presets[id])) ?? "custom";
     },
-    matchingPreset: () => Object.keys(presets).find((id) => equal(get(), presets[id])) ?? "custom",
     get groupPresets() {
       return groupPresets;
     },
@@ -2692,6 +2726,7 @@ function createRemoteControls(id, descriptors, options = {}) {
     tunable: options.tunable,
     history: options.history,
     presets: options.presets,
+    pinned: options.pinned,
     groupPresets: options.groupPresets,
     onPreset: options.onPreset,
     actions: options.actions,

package/dist/panel.js

@@ -3288,6 +3288,9 @@ ${GRAD_PROPS}
 .knobs-group-head{display:flex;align-items:center;justify-content:space-between;gap:8px;min-height:20px;margin:var(--k-group-gap) 0 var(--_k-gap);padding:0 var(--k-group-inset);color:var(--_k-group-label);font-size:var(--k-group-size);font-weight:var(--_k-weight-title);letter-spacing:var(--k-group-tracking);text-transform:var(--k-group-transform)}
 .knobs-panel:not(.knobs-page) .knobs-group-head:not(:first-child){border-top:1px solid var(--k-group-divider);padding-top:var(--k-group-divider-gap)}
 .knobs-group-head:first-child{margin-top:0}
+.knobs-panel:not(.knobs-page) .knobs-presets+.knobs-group-head{margin-top:0;border-top:0;padding-top:0}
+.knobs-pinned{margin-bottom:var(--k-group-gap)}
+.knobs-pinned:empty{display:none}
 .knobs-group-head>span:last-child{display:flex;align-items:center;gap:var(--_k-tray-pad);margin-right:calc((var(--k-icon-sm) - 20px) / 2)}
 .knobs-group-head button{height:20px;padding:0 6px;font-size:var(--_k-text-meta);font-weight:500;letter-spacing:0;text-transform:none;color:var(--_k-fg-2);background:transparent;border-radius:var(--_k-radius-sm);cursor:pointer}
 .knobs-group-head button:is(:hover:not([disabled]),:focus-visible){background:var(--_k-fill-selected);color:var(--_k-fg)}
@@ -6928,6 +6931,9 @@ function resolveActivePresetEntry(entries, currentValues, lastAppliedId, baseId
     isCustom: true
   };
 }
+function presetsTouch(entries, keys, defaults) {
+  return entries.some((e) => !(e.kind === "preset" && e.rawId === "default") && keys.some((k) => !same2(e.values[k], defaults[k])));
+}
 function nextPresetIndex(count, activeIndex, direction) {
   if (count <= 0)
     return -1;
@@ -6935,7 +6941,7 @@ function nextPresetIndex(count, activeIndex, direction) {
     return direction > 0 ? 0 : count - 1;
   return ((activeIndex + direction) % count + count) % count;
 }
-function createPresetStrip(doc, controls, showVariants, run, onAfterChange, presetLabel = (id) => controls.presetLabel(id)) {
+function createPresetStrip(doc, controls, showVariants, run, onAfterChange, presetLabel = (id) => controls.presetLabel(id), relevant) {
   const wake = () => onAfterChange?.();
   const el = (tag, cls, text) => {
     const node = doc.createElement(tag);
@@ -6981,6 +6987,15 @@ function createPresetStrip(doc, controls, showVariants, run, onAfterChange, pres
   let prevDrifted = false;
   let initializedPill = false;
   let slideUntil = 0;
+  const unpinned = (values) => {
+    let out;
+    for (const k of Object.keys(values))
+      if (controls.isPinned(k) && !same2(values[k], controls.locked[k])) {
+        out ??= { ...values };
+        out[k] = controls.locked[k];
+      }
+    return out ?? values;
+  };
   function buildEntries() {
     const presetEntries = Object.entries(controls.presets).map(([id, presetValues]) => ({
       id: `p:${id}`,
@@ -6998,7 +7013,7 @@ function createPresetStrip(doc, controls, showVariants, run, onAfterChange, pres
       kind: "variant",
       rawId: v.id,
       label: v.name ?? v.id.slice(0, 8),
-      values: v.values,
+      values: unpinned(v.values),
       apply: (coalesce) => controls.variants.load(v.id, { coalesce })
     }));
     return [...presetEntries, ...variantEntries];
@@ -7050,7 +7065,13 @@ function createPresetStrip(doc, controls, showVariants, run, onAfterChange, pres
     if (first)
       doc.defaultView?.requestAnimationFrame(() => pill.style.transition = "");
   }
-  const resolve = () => resolveActivePresetEntry(entries, controls.get(), lastAppliedId, activeEntryId(controls));
+  const resolve = () => resolveActivePresetEntry(entries, unpinned(controls.get()), lastAppliedId, activeEntryId(controls));
+  const wanted = (list) => (list.length > 1 || showVariants) && (relevant?.(list) ?? true);
+  function syncShown() {
+    const show = wanted(entries);
+    if (root.hidden === show && root.dataset.presence === undefined)
+      root.hidden = !show;
+  }
   function syncSelection(snap = false) {
     activeState = resolve();
     if (lastAppliedId !== null && activeState.activeId !== lastAppliedId) {
@@ -7107,14 +7128,15 @@ function createPresetStrip(doc, controls, showVariants, run, onAfterChange, pres
     run(() => {
       const variantsRef = showVariants ? controls.variants.list() : null;
       if (signature !== "" && variantsRef === lastVariantsRef) {
+        syncShown();
         syncSelection(false);
         return;
       }
       lastVariantsRef = variantsRef;
       const nextEntries = buildEntries();
       const nextSig = JSON.stringify(nextEntries.map((e) => [e.id, e.label]));
-      const shouldShow = nextEntries.length > 1 || showVariants;
-      root.hidden = !shouldShow;
+      entries = nextEntries;
+      syncShown();
       if (nextSig !== signature) {
         signature = nextSig;
         entries = nextEntries;
@@ -7385,6 +7407,7 @@ function createPresetStrip(doc, controls, showVariants, run, onAfterChange, pres
     getEntries: () => entries,
     getButtons: () => buttons,
     getActiveState: () => activeState,
+    shows: () => wanted(entries),
     cycle,
     selectById,
     save: () => {
@@ -10164,6 +10187,8 @@ class GpuOverlayManager {
     });
     ro.observe(panel.root);
     ro.observe(panel.body);
+    if (panel.pinned)
+      ro.observe(panel.pinned);
     ro.observe(panel.presetStrip.track);
     const mo = new MutationObserver(() => {
       this.styleVersion++;
@@ -12873,7 +12898,9 @@ class GpuOverlayManager {
       }
       const ps = panel.presetStrip;
       const hinting = panel.root.classList.contains("knobs-hinting");
+      const stripAlpha = this.curAlpha;
       if (!ps.element.hidden) {
+        this.curAlpha = stripAlpha * this.presence(ps.element);
         const psHovered = this.curPanelHovered && ps.element.matches(":hover");
         this.curSubHovered = psHovered;
         const psRect = this.rectOf(ps.element);
@@ -12997,6 +13024,7 @@ class GpuOverlayManager {
             align: "center"
           });
         }
+        this.curAlpha = stripAlpha;
       }
       const tabs = panel.tabs;
       if (tabs && !tabs.element.hidden)
@@ -13112,7 +13140,7 @@ class GpuOverlayManager {
       }
       if (bodyRevealing || pageMoving)
         this.curBypassRectCache = true;
-      const bodyHovered = this.curPanelHovered && panel.body.matches(":hover");
+      const bodyHovered = this.curPanelHovered && (panel.body.matches(":hover") || Boolean(panel.pinned?.matches(":hover")));
       this.curSubHovered = bodyHovered;
       this.curPointerRow = bodyHovered && panel.root.hasAttribute("data-k-row-hover");
       const panelAlpha = this.curAlpha;
@@ -25740,7 +25768,7 @@ function buildPanel(controls, host, options) {
     titleEl.title = `${titleEl.textContent ? `${titleEl.textContent}
 ` : ""}Press ${show("help")} for keyboard shortcuts`;
   const presetLabel = (id) => options.presetLabels?.[id] ?? (id === "default" ? options.defaultLabel : undefined) ?? controls.presetLabel(id);
-  const presetStrip = createPresetStrip(doc, controls, showVariants, run, () => wakeGpu(), presetLabel);
+  const presetStrip = createPresetStrip(doc, controls, showVariants, run, () => wakeGpu(), presetLabel, (entries) => presetsTouchTab(entries));
   const tabStrip = createTabStrip(doc, (id, animate) => selectTab(id, animate));
   let activeTab;
   const searchOptions = typeof options.search === "object" ? options.search : {};
@@ -25783,6 +25811,10 @@ function buildPanel(controls, host, options) {
   ];
   const body = el("div");
   const tabMotion = tabTransition(body, root, () => wakeGpu());
+  const pinnedBody = el("div");
+  pinnedBody.className = "knobs-pinned";
+  if (!page)
+    body.append(presetStrip.element);
   const blocks = [];
   const cards = [];
   const groupResetButtons = new Map;
@@ -26264,8 +26296,12 @@ function buildPanel(controls, host, options) {
         section: field.section
       });
     }
-    return gatherSubsections(specs);
+    const planned = gatherSubsections(specs);
+    if (page || !planned.some(pinnedRow))
+      return planned;
+    return [...planned.filter(pinnedRow), ...planned.filter((spec) => !pinnedRow(spec))];
   };
+  const pinnedRow = (r) => !page && controls.isPinned(r.keys[0] ?? r.id);
   const gatherSubsections = (specs) => {
     const out = [];
     for (let i = 0;i < specs.length; ) {
@@ -26911,13 +26947,15 @@ function buildPanel(controls, host, options) {
       const runs = [];
       for (const r of next) {
         const last = runs.at(-1);
-        if (last && last.group === r.group)
+        const pinned = pinnedRow(r);
+        if (last && last.group === r.group && last.pinned === pinned)
           last.rows.push(r);
         else
-          runs.push({ group: r.group, rows: [r] });
+          runs.push({ group: r.group, pinned, rows: [r] });
       }
       const free = blocks.filter((b) => !b.leaving);
       const chosen = [];
+      const pinnedBlocks = new Set;
       const usedSubheads = new Set;
       for (const run of runs) {
         const at = free.findIndex((b) => b.group === run.group);
@@ -26935,6 +26973,8 @@ function buildPanel(controls, host, options) {
           }
         }
         chosen.push(block);
+        if (run.pinned)
+          pinnedBlocks.add(block);
         const nodes = [];
         let under;
         for (const r of run.rows) {
@@ -26966,7 +27006,9 @@ function buildPanel(controls, host, options) {
             gpuRows.splice(gi, 1);
           subheads.delete(id);
         }
-      arrange(body, chosen.flatMap((b) => b.head ? [b.head, b.card] : [b.card]));
+      const nodesOf = (list) => list.flatMap((b) => b.head ? [b.head, b.card] : [b.card]);
+      arrange(pinnedBody, nodesOf(chosen.filter((b) => pinnedBlocks.has(b))));
+      arrange(body, [presetStrip.element, ...nodesOf(chosen.filter((b) => !pinnedBlocks.has(b)))]);
       for (const block of free) {
         block.leaving = true;
         const fold = () => {
@@ -27097,19 +27139,28 @@ function buildPanel(controls, host, options) {
         return f.tab;
     return;
   };
-  const tabOf = (r) => r.field.tab ?? (r.group !== undefined ? groupTab(r.group) : undefined);
+  const tabOf = (r) => pinnedRow(r) ? undefined : r.field.tab ?? (r.group !== undefined ? groupTab(r.group) : undefined);
   const tabList = () => {
     if (page)
       return [];
     const list = (options.tabs ?? []).map((t) => typeof t === "string" ? { id: t, label: readableTitle(t) } : { id: t.id, label: t.label ?? readableTitle(t.id) });
     const seen = new Set(list.map((t) => t.id));
-    for (const f of Object.values(controls.schema))
-      if (f.tab !== undefined && !seen.has(f.tab)) {
+    for (const [key, f] of Object.entries(controls.schema))
+      if (f.tab !== undefined && !seen.has(f.tab) && !controls.isPinned(key)) {
         seen.add(f.tab);
         list.push({ id: f.tab, label: readableTitle(f.tab) });
       }
     return list;
   };
+  function presetsTouchTab(entries) {
+    if (page || activeTab === undefined)
+      return true;
+    const keys = rows.flatMap((r) => {
+      const tab = tabOf(r);
+      return !pinnedRow(r) && (tab === undefined || tab === activeTab) ? r.keys : [];
+    });
+    return presetsTouch(entries, keys, controls.locked);
+  }
   function syncTabs() {
     const list = tabList();
     const has = (id) => id !== undefined && list.some((t) => t.id === id);
@@ -27172,6 +27223,7 @@ function buildPanel(controls, host, options) {
         want.set(b.head, any);
       want.set(b.card, any && !(b.group !== undefined && folds.get(b.group) && !finding));
     }
+    want.set(presetStrip.element, presetStrip.shows());
     return want;
   }
   const shift = (node, show, delay) => {
@@ -27195,6 +27247,9 @@ function buildPanel(controls, host, options) {
     }
     if (tabMotion.running)
       tabMotion.finish();
+    const strip = presetStrip.element;
+    if (strip.hidden === want.get(strip))
+      strip.hidden = !want.get(strip);
     const showing = (n) => !n.hidden && n.dataset.leaving !== "true";
     const set = (node, show, animate) => {
       if (showing(node) === show)
@@ -27481,10 +27536,10 @@ function buildPanel(controls, host, options) {
     root.append(header);
     if (showFooter)
       root.append(popover);
-    root.append(tabStrip.element);
+    root.append(pinnedBody, tabStrip.element);
     if (search)
       root.append(search.element);
-    root.append(presetStrip.element, body);
+    root.append(body);
     if (panelActions.length > 0)
       root.append(customActions);
     root.append(text, apply, status, live);
@@ -27784,34 +27839,47 @@ function buildPanel(controls, host, options) {
   let lastActionButton;
   const stops = () => {
     const list = [];
+    const strips = [];
     if (visible(tabStrip.element))
-      list.push({
-        contains: (n) => tabStrip.element.contains(n),
-        focus: (o) => tabStrip.focus(o)
+      strips.push({
+        at: tabStrip.element,
+        stops: [{ contains: (n) => tabStrip.element.contains(n), focus: (o) => tabStrip.focus(o) }]
       });
     if (visible(presetStrip.element))
-      list.push({
-        contains: (n) => presetStrip.element.contains(n),
-        focus: (o) => presetStrip.element.focus(o)
+      strips.push({
+        at: presetStrip.element,
+        stops: [
+          {
+            contains: (n) => presetStrip.element.contains(n),
+            focus: (o) => presetStrip.element.focus(o)
+          }
+        ]
       });
     if (page) {
+      for (const strip of strips)
+        list.push(...strip.stops);
       for (const stop of pageStops())
         list.push({ contains: (n) => stop.contains(n), focus: (o) => stop.focus(o) });
       return list;
     }
+    const stopOf = (stop) => ({
+      contains: (n) => stop.contains(n),
+      focus: (o) => stop.focus(o)
+    });
+    const shown = (stops) => stops.filter((s) => !s.closest('[hidden],[data-presence="out"]')).map(stopOf);
     const runs = rows.map((r) => ({
       at: r.row,
-      stops: r.editor?.stops() ?? [r.input]
+      stops: shown(r.editor?.stops() ?? [r.input])
     }));
     for (const b of blocks)
       if (b.head?.hasAttribute("data-foldable") && !b.leaving)
-        runs.push({ at: b.head, stops: [b.head] });
+        runs.push({ at: b.head, stops: shown([b.head]) });
     for (const sh of subheads.values())
-      runs.push({ at: sh.el, stops: [sh.el] });
+      runs.push({ at: sh.el, stops: shown([sh.el]) });
+    runs.push(...strips);
     runs.sort((a, b) => a.at.compareDocumentPosition(b.at) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1);
     for (const run of runs)
-      for (const stop of run.stops.filter((s) => !s.closest('[hidden],[data-presence="out"]')))
-        list.push({ contains: (n) => stop.contains(n), focus: (o) => stop.focus(o) });
+      list.push(...run.stops);
     const bar = actionBarButtons();
     if (bar.length)
       list.push({
@@ -29265,6 +29333,7 @@ function buildPanel(controls, host, options) {
     id: controls.id,
     root,
     body,
+    pinned: pinnedBody,
     inline,
     header,
     titleEl,

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

@@ -130,6 +130,8 @@ export interface RemoteControlsOptions {
     readonly nullDefaults?: boolean;
     readonly values?: State;
     readonly presets?: Readonly<Record<string, State>>;
+    /** Groups pinned above the tab strip, outside the presets (see `ControlsOptions.pinned`). */
+    readonly pinned?: readonly string[];
     /** Numbered presets per group, e.g. the phone's preset sets (see `ControlsOptions.groupPresets`). */
     readonly groupPresets?: Readonly<Record<string, readonly GroupPreset[]>>;
     /** Display labels by group id, section id and preset id (see `ControlsOptions.groupLabels`). */

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

@@ -50,6 +50,12 @@ export interface FieldMeta {
      * Fields without a tab show on every tab.
      */
     readonly tab?: string;
+    /**
+     * Pins the field's group to the top of a panel, under the header and above the tab strip, on
+     * every tab (the first field of a group that says wins; a field without a group pins itself).
+     * Panel presets and saved variants leave pinned fields alone. See `ControlsOptions.pinned`.
+     */
+    readonly pinned?: boolean;
     /**
      * A collapsible sub-heading inside the field's group: a flat heading with a hairline, never a
      * card inside the card. Consecutive fields that share it sit under one heading.
@@ -57,7 +63,7 @@ export interface FieldMeta {
     readonly subsection?: string;
 }
 /** Meta keys copied from a field's options or a descriptor onto the field. */
-export declare const META_KEYS: readonly ["label", "group", "groupLabel", "section", "sectionLabel", "groupDescription", "sectionDescription", "shortcut", "random", "disabled", "readOnly", "folded", "sectionFolded", "tab", "subsection"];
+export declare const META_KEYS: readonly ["label", "group", "groupLabel", "section", "sectionLabel", "groupDescription", "sectionDescription", "shortcut", "random", "disabled", "readOnly", "folded", "sectionFolded", "tab", "pinned", "subsection"];
 /** The meta `source` gives, without undefined keys. */
 export declare function pickMeta(source: FieldMeta | undefined, skip?: readonly string[]): FieldMeta;
 /** Marks a knob as half of a flat spring: two number keys drawn as one spring card. */
@@ -329,6 +335,11 @@ export declare const isReadout: (field: {
 /** Whether a field holds a value (actions, toolbars and readouts don't). */
 export declare const hasValue: (field: Field) => field is ValueField;
 export type Schema = Readonly<Record<string, Field>>;
+/**
+ * The schema's pinned keys (values, actions and readouts alike): every key of a group in `groups`,
+ * or whose first field that gives `pinned` says `true`, and ungrouped fields that say so themselves.
+ */
+export declare function pinnedKeys(schema: Schema, groups?: readonly string[]): ReadonlySet<string>;
 export type FieldValue<F extends Field> = F extends Knob ? number : F extends Choice<infer T> ? T : F extends Toggle ? boolean : F extends SpringField ? SpringValue : F extends ColorField ? string : F extends PointField ? Point : F extends EasingField ? Bezier : F extends VecField<3> ? Vec3 : F extends VecField<2> ? Point : F extends RangeField ? readonly [number, number] : F extends AngleField | SeedField ? number : F extends KeybindField ? string : F extends GradientField ? readonly GradientStop[] : F extends CurveField ? readonly CurvePoint[] : never;
 /** The keys of a schema's readouts (what `controls.watch` takes). */
 export type ReadoutKeys<S extends Schema> = {
@@ -449,6 +460,7 @@ export declare function range(value: readonly [number, number], options: FieldMe
     folded?: boolean;
     sectionFolded?: boolean;
     tab?: string;
+    pinned?: boolean;
     subsection?: string;
 };
 /** Degrees on a dial (0–360 and wrapping by default): `angle(45)`, `angle(30, { min: -90, max: 90 })`. */

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

@@ -348,6 +348,12 @@ export interface ControlsOptions<S extends Schema> extends LabelOptions {
     /** An undo stack the host owns; undo and redo call it (see `HostHistory`). */
     history?: HostHistory;
     presets?: Readonly<Record<string, Partial<Values<S>>>>;
+    /**
+     * 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.
+     */
+    pinned?: readonly string[];
     /**
      * Numbered presets per group, shown as 1, 2, 3… on the group's card in a page. A group's
      * presets cover every key any of them names; keys a preset leaves out are at their defaults,
@@ -426,6 +432,8 @@ export interface Controls<S extends Schema = Schema> {
     readonly sectionFolded: SectionFolded | undefined;
     /** A preset's display label (`presetLabels`, `defaultLabel`), else its id. */
     presetLabel(id: string): string;
+    /** Whether `key` is pinned (its group is, see `ControlsOptions.pinned`), outside the presets. */
+    isPinned(key: string): boolean;
     readonly error: string | null;
     get(): Values<S>;
     getServerSnapshot(): Values<S>;

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

@@ -407,6 +407,8 @@ export interface GpuPanelBinding {
     readonly id: string;
     readonly root: HTMLElement;
     readonly body: HTMLElement;
+    /** The pinned groups' cards, above the tab strip (empty while none are pinned). */
+    readonly pinned?: HTMLElement;
     readonly inline: boolean;
     readonly header: HTMLElement;
     readonly titleEl: HTMLElement;

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

@@ -28,6 +28,8 @@ export declare function activeEntryId(controls: Controls<any>): string | null;
  * cycling never gets stuck when a saved variant has the exact same values as a built-in preset.
  */
 export declare function resolveActivePresetEntry<V extends Record<string, any>>(entries: readonly PresetEntry<V>[], currentValues: V, lastAppliedId: string | null, baseId?: string | null): ActivePresetState;
+/** Whether any entry but the defaults gives one of `keys` a value other than its default. */
+export declare function presetsTouch(entries: readonly PresetEntry<any>[], keys: readonly string[], defaults: Readonly<Record<string, unknown>>): boolean;
 export declare function nextPresetIndex(count: number, activeIndex: number, direction: number): number;
 export interface PresetStrip {
     readonly element: HTMLElement;
@@ -52,9 +54,13 @@ export interface PresetStrip {
     readonly nameField: () => HTMLInputElement | null;
     /** Deletes the selected chip when it's a saved variant; returns a status message. */
     deleteActive(): string | undefined;
+    /** Whether the strip should show: presets to pick (or saving on) that touch what's shown. */
+    shows(): boolean;
     update(): void;
     dispose(): void;
 }
 export declare function createPresetStrip<S extends Schema>(doc: Document, controls: Controls<S>, showVariants: boolean, run: (action: () => unknown) => void, onAfterChange?: () => void, 
 /** What a preset's chip says (its id stays its identity); `controls.presetLabel` by default. */
-presetLabel?: (id: string) => string): PresetStrip;
+presetLabel?: (id: string) => string, 
+/** Whether these entries matter where the strip is shown (a tab they don't touch hides it). */
+relevant?: (entries: readonly PresetEntry<any>[]) => boolean): PresetStrip;

package/package.json

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