variantkit 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "variantkit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The configuration panel for AI-built UI: your agent generates variants with a full contextual control panel, you tweak and finalize, the losers get pruned from the codebase. Built on DialKit.",
   "type": "module",
   "bin": {

package/variantkit/configs.ts

@@ -71,3 +71,29 @@ export function defaultsOf(cfg: PanelConfig): Record<string, number | string | b
 export function regOf(variantKeys: string[]): Record<string, true> {
   return Object.fromEntries(variantKeys.map((k) => [k, true]))
 }
+
+// Flatten a (possibly nested) config into the path→default map DialKit addresses values by:
+// dot-joined raw keys (`headingSize`, `Pricing Card.accent`). Used by the header Reset button
+// to push every control — INCLUDING the variant — back to where it started. Folders are plain
+// objects without a `type`; `_`-prefixed keys (e.g. `_collapsed`) and actions are skipped.
+export function flatDefaults(cfg: PanelConfig, prefix = ''): Record<string, number | string | boolean> {
+  const out: Record<string, number | string | boolean> = {}
+  for (const [key, c] of Object.entries(cfg)) {
+    if (key.startsWith('_') || c == null) continue
+    const path = prefix ? `${prefix}.${key}` : key
+    if (typeof c === 'number' || typeof c === 'string' || typeof c === 'boolean') {
+      out[path] = c
+    } else if (Array.isArray(c)) {
+      out[path] = c[0] as number
+    } else if (typeof c === 'object') {
+      const o = c as { type?: string; default?: unknown }
+      if (o.type === 'action') continue
+      if (o.type) {
+        if (o.default !== undefined) out[path] = o.default as number | string | boolean
+      } else {
+        Object.assign(out, flatDefaults(c as PanelConfig, path)) // nested folder of controls
+      }
+    }
+  }
+  return out
+}

package/variantkit/dialkit-clean.css

@@ -13,13 +13,34 @@
    bubble sets its own uniform 12px, so this only affects the open panel. */
 .dialkit-root .dialkit-panel-inner:not([data-collapsed='true']) {
   padding-bottom: 12px;
+  /* DialKit sets an inline pixel `height` from its own content measurement — but it under-measures
+     by ~14px (our bottom padding + the wrapped variant pills aren't counted), so the last control
+     (Finalize) gets clipped on EVERY window size, not just short ones. Force `height: auto` so the
+     panel hugs its real content, then cap to the viewport and scroll if a short window demands it.
+     Scoped to the expanded panel so DialKit's collapse animation (which drives `data-collapsed`)
+     is left untouched. */
+  height: auto !important;
+  max-height: calc(100vh - 28px);
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  scrollbar-width: thin;
+  scrollbar-color: var(--dial-surface-hover) transparent;
+}
+.dialkit-root .dialkit-panel-inner:not([data-collapsed='true'])::-webkit-scrollbar {
+  width: 8px;
+}
+.dialkit-root .dialkit-panel-inner:not([data-collapsed='true'])::-webkit-scrollbar-thumb {
+  background: var(--dial-surface-hover);
+  border-radius: 999px;
+  border: 2px solid transparent;
+  background-clip: padding-box;
 }
 .dialkit-root .dialkit-panel-header {
-  border-bottom: none !important;
-  /* The title row carried bottom spacing meant to clear the preset toolbar. With the toolbar
-     hidden that became a ~38px dead gap above the first control — reclaim it so the title sits
-     a normal step above the panel body. */
-  margin-bottom: 2px !important;
+  /* A quiet divider + breathing room separates the header (title + chrome) from the controls,
+     so the panel reads as "identity up top, then the body". */
+  border-bottom: 1px solid var(--dial-border) !important;
+  padding-bottom: 12px !important;
+  margin-bottom: 12px !important;
 }
 .dialkit-root .dialkit-panel-header .dialkit-folder-header-top {
   padding-bottom: 0 !important;
@@ -41,8 +62,10 @@
   align-items: stretch;
 }
 .dialkit-root .dialkit-vk-pills .dialkit-select-label {
-  /* sits on its own line above the pills */
-  padding: 0 2px;
+  /* Drop the "Variant" caption — the segmented pills are the first thing under the title and are
+     self-evidently the take selector. A lone label above them just read as an orphaned control
+     row. The panel now opens straight into the pills, like a tab bar. */
+  display: none;
 }
 .dialkit-root .dialkit-vk-pills-track {
   display: flex;
@@ -95,11 +118,94 @@
   color: var(--dial-glass-bg);
 }
 
-/* The injected panel theme toggle — placed just left of DialKit's settings icon (right:12). */
+/* ── Panel icon: collapse glyph (expanded) + brand mark (collapsed) ───────────────────────
+   DialKit's `.dialkit-panel-icon` sits top-right; clicking it (via the header's toggle) collapses
+   the panel. We paint it with a CSS mask in `currentColor` (themes itself, survives React
+   re-renders): a contract/minimize glyph while EXPANDED — that's its real job, the panel's
+   collapse affordance — and VariantKit's brand mark on the COLLAPSED bubble, where the panel
+   needs a face (two rounded cards, one solid, echoing the variant pills). */
+.dialkit-root .dialkit-panel-icon > * {
+  display: none; /* hide DialKit's own dial paths */
+}
+.dialkit-root .dialkit-panel-icon {
+  background-color: currentColor;
+  cursor: pointer;
+  -webkit-mask-repeat: no-repeat;
+  mask-repeat: no-repeat;
+  -webkit-mask-position: center;
+  mask-position: center;
+  -webkit-mask-size: contain;
+  mask-size: contain;
+}
+.dialkit-root .dialkit-panel-inner:not([data-collapsed='true']) .dialkit-panel-icon {
+  -webkit-mask-image: var(--vk-collapse-mark);
+  mask-image: var(--vk-collapse-mark);
+}
+.dialkit-root .dialkit-panel-inner[data-collapsed='true'] .dialkit-panel-icon {
+  -webkit-mask-image: var(--vk-brand-mark);
+  mask-image: var(--vk-brand-mark);
+}
+.dialkit-root {
+  --vk-brand-mark: url("data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2016%2016'%3E%3Crect%20x='2.2'%20y='4.4'%20width='5.2'%20height='7.2'%20rx='1.7'%20fill='black'/%3E%3Crect%20x='8.6'%20y='4.4'%20width='5.2'%20height='7.2'%20rx='1.7'%20fill='none'%20stroke='black'%20stroke-width='1.3'%20opacity='.5'/%3E%3C/svg%3E");
+  --vk-collapse-mark: url("data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2016%2016'%3E%3Cpath%20d='M12.8%203.2%20L9%207%20M9%204.7%20L9%207%20L11.3%207'%20fill='none'%20stroke='black'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3E%3Cpath%20d='M3.2%2012.8%20L7%209%20M7%2011.3%20L7%209%20L4.7%209'%20fill='none'%20stroke='black'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3E%3C/svg%3E");
+}
+
+/* ── Element actions: Shuffle + Reset, beside the element name ────────────────────────────
+   Two quiet icon buttons sit right after the title, in the same row — they act on the ELEMENT,
+   so they read as the element's own controls. Panel chrome (theme + collapse) stays on the far
+   right; the title row reserves space for it so the two groups never collide. */
+.dialkit-root .dialkit-panel-header .dialkit-folder-title-row {
+  display: flex;
+  align-items: center;
+  gap: 3px;
+  padding-right: 76px; /* clear the theme toggle (right 40) + collapse icon (right 12) */
+}
+.dialkit-root .dialkit-panel-header .dialkit-folder-title-row .dialkit-folder-title {
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.dialkit-root .vk-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: 1px;
+  margin-left: 4px;
+  flex: 0 0 auto;
+}
+.dialkit-root .vk-action-btn {
+  width: 24px;
+  height: 24px;
+  display: inline-grid;
+  place-items: center;
+  border: none;
+  background: transparent;
+  border-radius: 6px;
+  cursor: pointer;
+  color: var(--dial-text-secondary);
+  transition:
+    background-color 140ms cubic-bezier(0.23, 1, 0.32, 1),
+    color 140ms cubic-bezier(0.23, 1, 0.32, 1);
+}
+.dialkit-root .vk-action-btn:hover {
+  background: var(--dial-surface-hover);
+  color: var(--dial-text-primary);
+}
+.dialkit-root .vk-action-btn:active {
+  transform: scale(0.9);
+}
+.dialkit-root .vk-action-btn svg {
+  display: block;
+}
+
+/* ── Header chrome: theme toggle ─────────────────────────────────────────────────────────
+   Panel chrome on the right — the theme toggle, just left of the collapse/brand icon. */
 .dialkit-root .vk-theme-toggle {
   position: absolute;
   top: 6px;
-  right: 40px;
+  right: 40px; /* just left of the collapse icon (DialKit's panel-icon at right ~12) */
+  z-index: 2;
   width: 26px;
   height: 26px;
   display: inline-grid;
@@ -109,11 +215,13 @@
   border-radius: 7px;
   cursor: pointer;
   color: var(--dial-text-secondary);
-  z-index: 2;
-  transition: background-color 140ms cubic-bezier(0.23, 1, 0.32, 1);
+  transition:
+    background-color 140ms cubic-bezier(0.23, 1, 0.32, 1),
+    color 140ms cubic-bezier(0.23, 1, 0.32, 1);
 }
 .dialkit-root .vk-theme-toggle:hover {
   background: var(--dial-surface-hover);
+  color: var(--dial-text-primary);
 }
 .dialkit-root .vk-theme-toggle:active {
   transform: scale(0.92);

package/variantkit/motion.css

@@ -60,6 +60,35 @@
   }
 }
 
+/* ── Header actions feedback ─────────────────────────────────────────────────────────────
+   Reset spins its arrow once counter-clockwise; Shuffle gives its icon a quick tumble. Both
+   are keyed off a data attribute the JS sets for ~480ms, so each click animates fresh. */
+.dialkit-root .vk-reset[data-spinning] svg {
+  animation: vk-reset-spin 480ms var(--vk-ease-out);
+}
+@keyframes vk-reset-spin {
+  from {
+    transform: rotate(0);
+  }
+  to {
+    transform: rotate(-360deg);
+  }
+}
+.dialkit-root .vk-shuffle[data-shuffling] svg {
+  animation: vk-shuffle-tumble 420ms var(--vk-ease-out);
+}
+@keyframes vk-shuffle-tumble {
+  0% {
+    transform: rotate(0) scale(1);
+  }
+  45% {
+    transform: rotate(16deg) scale(0.86);
+  }
+  100% {
+    transform: rotate(0) scale(1);
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   .dialkit-root.vk-theming,
   .dialkit-root.vk-theming * {
@@ -68,6 +97,10 @@
   .vk-theme-toggle .vk-swap {
     animation: none;
   }
+  .dialkit-root .vk-reset[data-spinning] svg,
+  .dialkit-root .vk-shuffle[data-shuffling] svg {
+    animation: none;
+  }
   .dialkit-root button:active {
     transform: none;
   }

package/variantkit/patches/dialkit+1.2.0.patch

@@ -1,5 +1,5 @@
 diff --git a/node_modules/dialkit/dist/index.cjs b/node_modules/dialkit/dist/index.cjs
-index d9f4837..385c7dc 100644
+index d9f4837..ce0432f 100644
 --- a/node_modules/dialkit/dist/index.cjs
 +++ b/node_modules/dialkit/dist/index.cjs
 @@ -337,7 +337,7 @@ var DialStoreClass = class {
@@ -23,7 +23,23 @@ index d9f4837..385c7dc 100644
          children: folderContent
        }
      );
-@@ -1853,6 +1854,15 @@ function normalizeOptions(options) {
+@@ -1034,6 +1035,7 @@ function Slider({
+   shortcut,
+   shortcutActive
+ }) {
++  if (typeof value !== "number") value = typeof min === "number" ? min : 0;
+   const wrapperRef = (0, import_react5.useRef)(null);
+   const trackRef = (0, import_react5.useRef)(null);
+   const inputRef = (0, import_react5.useRef)(null);
+@@ -1825,6 +1827,7 @@ function EaseTextInput({ ease, onChange }) {
+ // src/components/TextControl.tsx
+ var import_jsx_runtime10 = require("react/jsx-runtime");
+ function TextControl({ label, value, onChange, placeholder }) {
++  if (typeof value !== "string") value = "";
+   return /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("div", { className: "dialkit-text-control", children: [
+     /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("label", { className: "dialkit-text-label", children: label }),
+     /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
+@@ -1853,6 +1856,15 @@ function normalizeOptions(options) {
      (opt) => typeof opt === "string" ? { value: opt, label: toTitleCase(opt) } : opt
    );
  }
@@ -39,7 +55,15 @@ index d9f4837..385c7dc 100644
  function SelectControl({ label, value, options, onChange }) {
    const [isOpen, setIsOpen] = (0, import_react10.useState)(false);
    const triggerRef = (0, import_react10.useRef)(null);
-@@ -2266,7 +2276,7 @@ Apply these values as the new defaults in the useDialKit call.`;
+@@ -1966,6 +1978,7 @@ var import_react12 = require("react");
+ var import_jsx_runtime12 = require("react/jsx-runtime");
+ var HEX_COLOR_REGEX = /^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/;
+ function ColorControl({ label, value, onChange }) {
++  if (typeof value !== "string") value = "#000000";
+   const [isEditing, setIsEditing] = (0, import_react12.useState)(false);
+   const [editValue, setEditValue] = (0, import_react12.useState)(value);
+   const colorInputRef = (0, import_react12.useRef)(null);
+@@ -2266,7 +2279,7 @@ Apply these values as the new defaults in the useDialKit call.`;
          );
        case "select":
          return /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(
@@ -49,7 +73,7 @@ index d9f4837..385c7dc 100644
              label: control.label,
              value,
 diff --git a/node_modules/dialkit/dist/index.js b/node_modules/dialkit/dist/index.js
-index f8d8baf..a58300a 100644
+index f8d8baf..47a7e4d 100644
 --- a/node_modules/dialkit/dist/index.js
 +++ b/node_modules/dialkit/dist/index.js
 @@ -297,7 +297,7 @@ var DialStoreClass = class {
@@ -73,7 +97,23 @@ index f8d8baf..a58300a 100644
          children: folderContent
        }
      );
-@@ -1813,6 +1814,15 @@ function normalizeOptions(options) {
+@@ -994,6 +995,7 @@ function Slider({
+   shortcut,
+   shortcutActive
+ }) {
++  if (typeof value !== "number") value = typeof min === "number" ? min : 0;
+   const wrapperRef = useRef4(null);
+   const trackRef = useRef4(null);
+   const inputRef = useRef4(null);
+@@ -1785,6 +1787,7 @@ function EaseTextInput({ ease, onChange }) {
+ // src/components/TextControl.tsx
+ import { jsx as jsx10, jsxs as jsxs9 } from "react/jsx-runtime";
+ function TextControl({ label, value, onChange, placeholder }) {
++  if (typeof value !== "string") value = "";
+   return /* @__PURE__ */ jsxs9("div", { className: "dialkit-text-control", children: [
+     /* @__PURE__ */ jsx10("label", { className: "dialkit-text-label", children: label }),
+     /* @__PURE__ */ jsx10(
+@@ -1813,6 +1816,15 @@ function normalizeOptions(options) {
      (opt) => typeof opt === "string" ? { value: opt, label: toTitleCase(opt) } : opt
    );
  }
@@ -89,7 +129,15 @@ index f8d8baf..a58300a 100644
  function SelectControl({ label, value, options, onChange }) {
    const [isOpen, setIsOpen] = useState6(false);
    const triggerRef = useRef8(null);
-@@ -2226,7 +2236,7 @@ Apply these values as the new defaults in the useDialKit call.`;
+@@ -1926,6 +1938,7 @@ import { useState as useState7, useRef as useRef9, useEffect as useEffect6 } fro
+ import { jsx as jsx12, jsxs as jsxs11 } from "react/jsx-runtime";
+ var HEX_COLOR_REGEX = /^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/;
+ function ColorControl({ label, value, onChange }) {
++  if (typeof value !== "string") value = "#000000";
+   const [isEditing, setIsEditing] = useState7(false);
+   const [editValue, setEditValue] = useState7(value);
+   const colorInputRef = useRef9(null);
+@@ -2226,7 +2239,7 @@ Apply these values as the new defaults in the useDialKit call.`;
          );
        case "select":
          return /* @__PURE__ */ jsx14(

package/variantkit/react.tsx

@@ -19,8 +19,8 @@
 // (recommended) ./dialkit-clean.css.
 import { useEffect, useRef, useState, type ReactElement, type ReactNode } from 'react'
 import { motion, MotionConfig } from 'motion/react'
-import { useDialKit } from 'dialkit'
-import { panelConfig, defaultsOf, regOf, type PanelConfig } from './configs'
+import { useDialKit, DialStore } from 'dialkit'
+import { panelConfig, defaultsOf, regOf, flatDefaults, type PanelConfig } from './configs'
 import { buildDecision, submitDecision, type ParamValue } from './buildDecision'
 
 export interface ElementDef {
@@ -32,8 +32,13 @@ export interface ElementDef {
    * The element's own controls — contextual, authored for THIS element (any DialKit control:
    * slider, select, boolean toggle, color, text, spring, nested folder groups…). VariantKit
    * adds `variant` + `finalize` around them; it never decides what these are.
+   *
+   * Pass a plain object for controls shared by every variant, OR a function of the active variant
+   * to make the control set DEPEND on the variant — different takes often need different knobs (a
+   * "split" hero has a media control a "minimal" one doesn't; a "vinyl" player has spin speed).
+   * Switch the variant and the panel swaps its controls; shared keys keep their values.
    */
-  controls?: PanelConfig
+  controls?: PanelConfig | ((variant: string) => PanelConfig)
   /** Render the active variant from its resolved values. */
   render: (variant: string, values: Record<string, ParamValue>) => ReactNode
   /** Optional full config override (replaces the assembled variant+controls+finalize). */
@@ -50,9 +55,6 @@ export interface StudioProps {
   onFinalize?: (decision: ReturnType<typeof buildDecision>) => void
 }
 
-const cfgFor = (e: ElementDef): PanelConfig =>
-  e.config ?? panelConfig(e.controls ?? {}, e.keys, { component: e.name })
-
 // Match DialKit's humanized folder title ("Pricing Card") back to an element name.
 const norm = (s: string) => s.replace(/\s+/g, '').toLowerCase()
 
@@ -77,23 +79,41 @@ export function Studio({ elements, name = 'VariantKit', focusOnHover, onFinalize
   const elsRef = useRef(elements)
   elsRef.current = elements
 
+  const single = elements.length === 1
+
+  // Each element's active variant — seeds the variant-specific control resolution below. Seeded
+  // with the first key, then synced from the live panel after each render (see the effect). When
+  // a variant changes, this updates → the config rebuilds → the panel swaps that variant's
+  // controls. (Studio is remounted per element set, so this reseeds correctly.)
+  const [variants, setVariants] = useState<Record<string, string>>(() =>
+    Object.fromEntries(elements.map((e) => [e.name, e.keys[0]])),
+  )
+
+  // Resolve an element's controls for its active variant: a function `controls` is called with the
+  // variant, a plain object is shared across all variants.
+  const controlsOf = (e: ElementDef): PanelConfig => {
+    const v = variants[e.name] ?? e.keys[0]
+    return typeof e.controls === 'function' ? e.controls(v) : e.controls ?? {}
+  }
+  const cfgForE = (e: ElementDef): PanelConfig =>
+    e.config ?? panelConfig(controlsOf(e), e.keys, { component: e.name })
+
   // Build the combined config. With ONE element, a per-element folder is pure redundancy —
   // the panel title already names it, so a "Button" folder under "Button Lab" just adds a
   // confusing second hierarchy level. So flatten: the lone element's controls sit at the panel
   // root. With 2+ elements, give each its own folder (first open, rest collapsed) — that's
   // where the grouping earns its keep. The finalize button's "✓ Copied" feedback is handled
   // inside copyDecision (panel-side), so the label stays a plain "Finalize <name>".
-  const single = elements.length === 1
   const combined: Record<string, unknown> = {}
   if (single) {
     const e = elements[0]
-    const base = cfgFor(e)
+    const base = cfgForE(e)
     Object.assign(combined, base, {
       finalize: { ...(base.finalize as object), label: `Finalize ${e.name}` },
     })
   } else {
     elements.forEach((e, i) => {
-      const base = cfgFor(e)
+      const base = cfgForE(e)
       const finalize = { ...(base.finalize as object), label: `Finalize ${e.name}` }
       combined[e.name] = { ...base, finalize, _collapsed: i !== 0 }
     })
@@ -109,19 +129,43 @@ export function Studio({ elements, name = 'VariantKit', focusOnHover, onFinalize
         string,
         ParamValue
       >
-      const decision = buildDecision(e.name, slice, defaultsOf(cfgFor(e)), regOf(e.keys))
+      const decision = buildDecision(e.name, slice, defaultsOf(cfgForE(e)), regOf(e.keys))
       // Dev transport first ("✓ Saved" -> .variantkit/decisions/), clipboard fallback ("✓ Copied").
       submitDecision(decision)
       onFinalize?.(decision)
     },
   }) as Record<string, Record<string, ParamValue>>
 
+  // Keep `variants` in step with the live panel so variant-specific controls swap in when you
+  // pick a different take. Runs after every commit; setVariants no-ops when nothing changed, so
+  // it settles in one extra render and never loops.
+  useEffect(() => {
+    setVariants((prev) => {
+      let changed = false
+      const next = { ...prev }
+      for (const e of elsRef.current) {
+        if (e.keys.length < 2) continue
+        const live = single
+          ? (all as unknown as Record<string, ParamValue>).variant
+          : (all as Record<string, Record<string, ParamValue>>)[e.name]?.variant
+        if (live != null && String(live) !== prev[e.name]) {
+          next[e.name] = String(live)
+          changed = true
+        }
+      }
+      return changed ? next : prev
+    })
+  })
+
   useEffect(() => {
     // Focus-on-hover only applies to the multi-element layout (it toggles per-element folders).
     // With a single flattened element there are no element folders to focus.
     if (focusOnHover && !single) focusFolder(focused)
   }, [focused, focusOnHover, single])
 
+  // Shuffle (randomize every knob — and the take) + Reset (back to defaults), in the header.
+  usePanelActions(name, combined as PanelConfig)
+
   // Render the elements as-is — VariantKit adds no layout, spacing, alignment, rings, or
   // badges around the project's UI. The host page owns presentation entirely.
   return (
@@ -188,6 +232,8 @@ export function useDialkitTheme(initial: 'light' | 'dark' = 'light') {
         if (el.getAttribute('data-theme') !== themeRef.current) el.setAttribute('data-theme', themeRef.current)
       })
       document.querySelectorAll<HTMLElement>('.dialkit-panel-header').forEach((hdr) => {
+        // Theme is PANEL chrome, so it lives in the header on the right (CSS pins it just left of
+        // the collapse icon) — deliberately apart from the element actions (shuffle/reset, left).
         const titleRow = hdr.querySelector<HTMLElement>('.dialkit-folder-header-top') ?? hdr
         // Keep exactly one toggle (hot-reload can leave a stale node behind).
         const existing = titleRow.querySelectorAll<HTMLButtonElement>('.vk-theme-toggle')
@@ -195,7 +241,6 @@ export function useDialkitTheme(initial: 'light' | 'dark' = 'light') {
         let btn = existing[0] ?? null
         if (!btn) {
           btn = document.createElement('button')
-          // Absolute, just left of DialKit's settings icon (which is absolute at right:12).
           btn.className = 'vk-theme-toggle'
           btn.type = 'button'
           btn.setAttribute('aria-label', 'Toggle panel theme')
@@ -215,18 +260,20 @@ export function useDialkitTheme(initial: 'light' | 'dark' = 'light') {
       })
     }
 
-    // Coalesce mutation bursts into one sync per frame, and pause the observer while WE write,
-    // so our own DOM changes can't re-trigger it. Belt and suspenders against the freeze.
+    // Coalesce mutation bursts into one sync per frame. sync() is idempotent (it only writes when
+    // a value actually differs and only appends the toggle when it's missing), so we stay
+    // connected rather than disconnecting around our own writes — the same reason as the action
+    // cluster: disconnecting opened a window where the panel-swap mutation landed unobserved and
+    // the toggle never got (re)appended into the freshly-built cluster.
     let frame = 0
-    const mo = new MutationObserver(() => {
+    const schedule = () => {
       if (frame) return
       frame = requestAnimationFrame(() => {
         frame = 0
-        mo.disconnect()
         sync()
-        mo.observe(document.body, { childList: true, subtree: true })
       })
-    })
+    }
+    const mo = new MutationObserver(schedule)
 
     // Delightful theme switch: add `.vk-theming` so the panel cross-fades its colors (the
     // class scopes a transition that only exists during the switch — see motion.css), then
@@ -234,6 +281,7 @@ export function useDialkitTheme(initial: 'light' | 'dark' = 'light') {
     const panels = document.querySelectorAll('.dialkit-root')
     panels.forEach((p) => p.classList.add('vk-theming'))
     sync()
+    schedule() // catch the action cluster if it commits a frame after this effect
     const settle = setTimeout(() => panels.forEach((p) => p.classList.remove('vk-theming')), 420)
     mo.observe(document.body, { childList: true, subtree: true })
     try {
@@ -250,3 +298,146 @@ export function useDialkitTheme(initial: 'light' | 'dark' = 'light') {
 
   return { theme, setTheme }
 }
+
+// ── Element actions: Shuffle + Reset ──────────────────────────────────────────────────────
+// Two icon buttons injected right after the element name in the header title row — they act on
+// the ELEMENT (randomize / restore its controls), so they read as the element's own controls
+// (panel chrome — theme + collapse — stays on the far right). They drive the live panel through
+// DialKit's store, so every control and the variant pills update in place, as if you'd dragged
+// them.
+//   Shuffle → a fresh random valid value for every slider/select/toggle (and the variant), so
+//             "surprise me" lands a whole new combination. Color/text/spring are left alone —
+//             random hex or copy is noise, not exploration.
+//   Reset   → every control (incl. the variant) back to its authored default.
+
+const SHUFFLE =
+  '<svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="16 3 21 3 21 8"/><line x1="4" y1="20" x2="21" y2="3"/><polyline points="21 16 21 21 16 21"/><line x1="15" y1="15" x2="21" y2="21"/><line x1="4" y1="4" x2="9" y2="9"/></svg>'
+const RESET =
+  '<svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="1 4 1 10 7 10"/><path d="M3.51 15a9 9 0 1 0 2.13-9.36L1 10"/></svg>'
+
+// A DialKit control's metadata (the shape we read from the live store). Loosely typed — we only
+// touch the fields we need and ignore the rest of DialKit's union.
+interface ControlMeta {
+  type: string
+  path: string
+  min?: number
+  max?: number
+  step?: number
+  options?: (string | { value: string; label: string })[]
+  children?: ControlMeta[]
+}
+
+// A random *valid* value for a single control, or undefined to leave it untouched. Sliders snap
+// to their step; selects/variant pick an option; toggles flip a coin. Anything else is skipped.
+function randomValue(meta: ControlMeta): number | string | boolean | undefined {
+  if (meta.type === 'slider') {
+    const min = meta.min ?? 0
+    const max = meta.max ?? 1
+    const step = meta.step ?? (Number.isInteger(min) && Number.isInteger(max) ? 1 : (max - min) / 100 || 1)
+    const steps = Math.max(1, Math.round((max - min) / step))
+    return +(min + Math.floor(Math.random() * (steps + 1)) * step).toFixed(4)
+  }
+  if (meta.type === 'toggle') return Math.random() < 0.5
+  if (meta.type === 'select') {
+    const opts = (meta.options ?? []).map((o) => (typeof o === 'string' ? o : o.value))
+    return opts.length ? opts[Math.floor(Math.random() * opts.length)] : undefined
+  }
+  return undefined // color / text / spring / transition / action / folder — left as-is
+}
+
+function usePanelActions(panelName: string, config: PanelConfig) {
+  const cfgRef = useRef(config)
+  cfgRef.current = config
+
+  useEffect(() => {
+    const panelId = () => DialStore.getPanels().find((p) => p.name === panelName)?.id
+
+    const reset = () => {
+      const id = panelId()
+      if (!id) return
+      for (const [path, value] of Object.entries(flatDefaults(cfgRef.current))) {
+        DialStore.updateValue(id, path, value as never)
+      }
+    }
+
+    const shuffle = () => {
+      const id = panelId()
+      if (!id) return
+      const panel = DialStore.getPanel(id)
+      if (!panel) return
+      const walk = (controls: ControlMeta[]) => {
+        for (const c of controls) {
+          if (c.children?.length) walk(c.children)
+          const v = randomValue(c)
+          if (v !== undefined) DialStore.updateValue(id, c.path, v as never)
+        }
+      }
+      walk(panel.controls as unknown as ControlMeta[])
+    }
+
+    // Build an icon button once; the spin/pop feedback comes from a data attribute the CSS keys
+    // off. `label` is the accessible/tooltip description (the button itself is icon-only).
+    const make = (cls: string, label: string, svg: string, onClick: () => void, flash: string) => {
+      const btn = document.createElement('button')
+      btn.type = 'button'
+      btn.className = `vk-action-btn ${cls}`
+      btn.setAttribute('aria-label', label)
+      btn.title = label
+      btn.innerHTML = svg
+      const stop = (e: Event) => e.stopPropagation()
+      btn.addEventListener('pointerdown', stop)
+      btn.addEventListener('mousedown', stop)
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation()
+        onClick()
+        btn.setAttribute(flash, '')
+        setTimeout(() => btn.removeAttribute(flash), 480)
+      })
+      return btn
+    }
+
+    const sync = () => {
+      // Ensure the panel header's title row (the element name, only present when expanded) carries
+      // exactly one shuffle/reset pair, appended after the title — robust against React re-renders.
+      // Then sweep any orphaned pairs (panel collapsed, element swapped, hot-reload).
+      const valid = new Set<Element>()
+      document.querySelectorAll<HTMLElement>('.dialkit-panel-header .dialkit-folder-title-row').forEach((row) => {
+        let bar = row.querySelector<HTMLElement>(':scope > .vk-actions')
+        if (!bar) {
+          bar = document.createElement('div')
+          bar.className = 'vk-actions'
+          bar.appendChild(make('vk-shuffle', 'Shuffle all controls', SHUFFLE, shuffle, 'data-shuffling'))
+          bar.appendChild(make('vk-reset', 'Reset to defaults', RESET, reset, 'data-spinning'))
+          row.appendChild(bar)
+        }
+        valid.add(bar)
+      })
+      document.querySelectorAll('.vk-actions').forEach((b) => {
+        if (!valid.has(b)) b.remove()
+      })
+    }
+
+    // Frame-coalesced sync on any DOM change. sync() is idempotent — it injects the cluster only
+    // when it's missing and bails when it's already there — so we DON'T disconnect the observer
+    // around our own writes: our injection fires one more (no-op) sync and then goes quiet. The
+    // old disconnect/reconnect dance opened a window where the panel-swap mutation (on project
+    // switch) landed unobserved, leaving the cluster un-injected. Staying connected closes it.
+    let frame = 0
+    const schedule = () => {
+      if (frame) return
+      frame = requestAnimationFrame(() => {
+        frame = 0
+        sync()
+      })
+    }
+    const mo = new MutationObserver(schedule)
+    sync()
+    schedule() // catch panel DOM that commits the frame after mount
+    mo.observe(document.body, { childList: true, subtree: true })
+    return () => {
+      if (frame) cancelAnimationFrame(frame)
+      mo.disconnect()
+      document.querySelectorAll('.vk-actions').forEach((el) => el.remove())
+    }
+  }, [panelName])
+}