@heyramzi/ui 2.18.0 → 2.19.1

package/README.md

@@ -95,6 +95,34 @@ Many components take their content through snippets, so you keep full control:
 <Button variant="outline" size="sm" onclick={save}>Save</Button>
 ```
 
+## Sound
+
+`@heyramzi/ui/lib/sound` gives the kit's controls interaction sounds from
+[cuelume](https://cuelume.dev). They're off until the person turns them on, and the choice is
+saved in their browser. Start it once in the root layout:
+
+```svelte
+<script lang="ts">
+  import { onMount } from "svelte";
+  import { startSound } from "@heyramzi/ui/lib/sound";
+
+  onMount(() => startSound());
+</script>
+```
+
+It reads each control's `data-slot`, so buttons tap, switches toggle, dialog triggers open and
+menu items select without a prop. `SLOT_CUES` in `src/lib/sound.ts` is the full map. The rest:
+
+- **The setting.** Call `setSound(on)` from the click that flips your Sound toggle. It resolves
+  `false` when the browser still blocks audio. `soundOn()` reads the saved choice.
+- **Outcomes.** `cue("success")` after a save, `cue("error")` on a failure, `cue("ready")` when a
+  long job lands. It plays nothing while sound is off.
+- **Recording.** `const resume = silence()` before the mic opens and `resume()` after, or the
+  sounds end up in the take.
+- **Opting out.** `data-sound="off"` on an element quiets it and everything inside. A control
+  that sets its own `data-cuelume-*` attribute keeps it. Text fields are quiet unless you add
+  `data-cuelume-type`.
+
 ## shadcn-svelte
 
 The primitives in `src/shadcn` are copies of

package/dist/charts/index.js

@@ -1,3 +1,4 @@
+import "../../src/charts/chart-tokens.css";
 import "../../src/charts/charts.css";
 export { default as BarChart } from "../../src/charts/bar-chart.svelte";
 export { default as AreaChart } from "../../src/charts/area-chart.svelte";

package/dist/charts/motion.js

@@ -1,5 +1,5 @@
 import { cubicInOut } from "svelte/easing";
-/** Mirrors `--chart-motion-reveal` in charts.css, for when no element is mounted to read it from. */
+/** Mirrors `--chart-motion-reveal` in chart-tokens.css, for when no element is mounted to read it from. */
 export const REVEAL_MS = 1100;
 /** Rescales the axes when the data changes; the first render never animates. */
 export const DOMAIN_MOTION = {

package/dist/lib/sound.js

@@ -0,0 +1,167 @@
+/**
+* Interface sounds from cuelume, off until the person turns them on. Call `startSound()` once in
+* the root layout: it marks the kit's controls by their `data-slot` and binds them, so no
+* component carries a sound attribute of its own. Outcomes (saved, failed, ready) are `cue()`
+* calls in the app. The cue for each job follows https://cuelume.dev/agents.md, "Which cue?".
+*/
+import { bind, play, setEnabled, unlock } from "cuelume";
+/**
+* Which kit slots sound, and how. Text fields are left out on purpose: a keystroke sound in every
+* input is too much for tools people type in all day, so an app opts a field in with
+* `data-cuelume-type`.
+*/
+export const SLOT_CUES = {
+	button: { binding: "tap" },
+	"code-block-copy-button": {
+		binding: "tap",
+		cue: "success",
+		subtle: true
+	},
+	switch: { binding: "toggle" },
+	checkbox: { binding: "toggle" },
+	toggle: { binding: "toggle" },
+	"sidebar-trigger": {
+		binding: "toggle",
+		subtle: true
+	},
+	"dialog-trigger": { binding: "open" },
+	"sheet-trigger": { binding: "open" },
+	"alert-dialog-trigger": { binding: "open" },
+	"popover-trigger": {
+		binding: "open",
+		subtle: true
+	},
+	"dropdown-menu-trigger": {
+		binding: "open",
+		subtle: true
+	},
+	"select-trigger": {
+		binding: "open",
+		subtle: true
+	},
+	"dialog-close": { binding: "close" },
+	"sheet-close": { binding: "close" },
+	"popover-close": {
+		binding: "close",
+		subtle: true
+	},
+	"select-item": { binding: "select" },
+	"dropdown-menu-item": { binding: "select" },
+	"dropdown-menu-checkbox-item": { binding: "select" },
+	"dropdown-menu-radio-item": { binding: "select" },
+	"context-menu-item": { binding: "select" },
+	"command-item": { binding: "select" },
+	"tabs-trigger": { binding: "select" },
+	"radio-group-item": { binding: "select" },
+	"toggle-group-item": { binding: "select" }
+};
+const BINDING_ATTRS = [
+	"tap",
+	"type",
+	"select",
+	"toggle",
+	"open",
+	"close",
+	"navigate"
+].map((b) => `data-cuelume-${b}`);
+const STORAGE_KEY = "heyramzi:sound";
+/** The saved setting, read on first use so a server render never touches storage. */
+let wanted;
+/** Open `silence()` holds. Any one of them mutes everything, whatever the setting says. */
+let holds = 0;
+function readSaved() {
+	try {
+		return localStorage.getItem(STORAGE_KEY) === "on";
+	} catch {
+		return false;
+	}
+}
+function audible() {
+	wanted ??= typeof window === "undefined" ? false : readSaved();
+	return wanted && holds === 0;
+}
+function apply() {
+	setEnabled(audible());
+}
+/** Whether the person turned sound on. A `silence()` hold doesn't change it. */
+export function soundOn() {
+	audible();
+	return wanted === true;
+}
+/**
+* Turns sound on or off and saves it. Call it from the click that flips the setting: turning on
+* unlocks audio inside that gesture, and the result says whether the browser lets it play.
+*/
+export function setSound(on) {
+	wanted = on;
+	try {
+		localStorage.setItem(STORAGE_KEY, on ? "on" : "off");
+	} catch {}
+	apply();
+	return on ? unlock() : Promise.resolve(false);
+}
+/**
+* Mutes every cue until the returned function runs, such as while the mic records, so no sound
+* lands in the take. Holds stack; each release counts once.
+*/
+export function silence() {
+	holds++;
+	apply();
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		holds--;
+		apply();
+	};
+}
+/** Plays a cue for an outcome the app knows about, only while sound is on and nothing silences it. */
+export function cue(name, options) {
+	if (audible()) play(name, options);
+}
+function mark(el) {
+	const slot = SLOT_CUES[el.getAttribute("data-slot") ?? ""];
+	if (!slot || el.closest("[data-sound=\"off\"]")) return;
+	// A control that names its own cue keeps it.
+	if (BINDING_ATTRS.some((attr) => el.hasAttribute(attr))) return;
+	el.setAttribute(`data-cuelume-${slot.binding}`, slot.cue ?? "");
+	if (slot.subtle && !el.hasAttribute("data-cuelume-emphasis")) {
+		el.setAttribute("data-cuelume-emphasis", "subtle");
+	}
+}
+/** Stamps the cuelume attribute on every kit control under `root`, `root` included. */
+export function markSlots(root) {
+	if (root instanceof Element && root.hasAttribute("data-slot")) mark(root);
+	for (const el of root.querySelectorAll("[data-slot]")) mark(el);
+}
+/**
+* Binds the kit's controls under `root` and keeps marking the ones that mount later. Safe on the
+* server, where it does nothing. Returns the function that stops it.
+*/
+export function startSound(root = globalThis.document) {
+	if (typeof window === "undefined" || !root) return () => {};
+	apply();
+	markSlots(root);
+	const observer = new MutationObserver((records) => {
+		for (const record of records) {
+			if (record.type === "attributes") {
+				if (record.target instanceof Element) mark(record.target);
+				continue;
+			}
+			for (const node of record.addedNodes) {
+				if (node instanceof Element) markSlots(node);
+			}
+		}
+	});
+	observer.observe(root, {
+		childList: true,
+		subtree: true,
+		attributes: true,
+		attributeFilter: ["data-slot"]
+	});
+	const unbind = bind(root);
+	return () => {
+		observer.disconnect();
+		unbind();
+	};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyramzi/ui",
-  "version": "2.18.0",
+  "version": "2.19.1",
   "description": "Svelte 5 UI for apps: primitives, effects and animations, plus work (tasks and docs), charts, slides, an editor, onboarding and a canvas as subpaths.",
   "homepage": "https://ui.heyramzi.com",
   "license": "MIT",
@@ -398,6 +398,7 @@
     "@zag-js/svelte": "^1.46.0",
     "@zag-js/tour": "^1.46.0",
     "clsx": "^2.1.1",
+    "cuelume": "^0.2.8",
     "d3-scale": "^4.0.2",
     "d3-shape": "^3.2.0",
     "layerchart": "^2.9.1",

package/src/charts/area-chart.svelte

@@ -2,6 +2,7 @@
 	// =========================
 	// IMPORTS
 	// =========================
+	import "./chart-tokens.css";
 	import "./area-chart.css";
 	import { Area, Axis, Chart, Highlight, LinearGradient, Spline, Svg, Tooltip } from "layerchart";
 	import { curveMonotoneX } from "d3-shape";

package/src/charts/bar-chart.svelte

@@ -2,6 +2,7 @@
 	// =========================
 	// IMPORTS
 	// =========================
+	import "./chart-tokens.css";
 	import "./bar-chart.css";
 	import { Axis, Bars, Chart, Highlight, Svg, Tooltip } from "layerchart";
 	import { scaleBand } from "d3-scale";

package/src/charts/chart-tokens.css

@@ -0,0 +1,36 @@
+/* Each chart imports these beside its own stylesheet, so a deep import such as
+   `@heyramzi/ui/charts/dashboard` keeps its card edge without the barrel. */
+
+/* Shared chart tokens, held at zero specificity by `:where()`. The reveal pair
+   is the entrance every chart shares; motion.ts mirrors its duration. */
+:where(
+  .hr-area-chart,
+  .hr-bar-chart,
+  .hr-line-chart,
+  .hr-sparkline,
+  .hr-number-chart,
+  .hr-stat-card,
+  .hr-legend,
+  .hr-ts-chart,
+  .hr-donut-chart,
+  .hr-ring,
+  .hr-gauge
+) {
+  --chart-label: var(--muted-foreground, oklch(0.5 0.01 286));
+  --chart-grid: color-mix(in srgb, var(--border, oklch(0.5 0.01 286)) 50%, transparent);
+  --chart-ease-out: var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
+  --chart-motion-fast: var(--duration-quick, 150ms);
+  --chart-motion: var(--duration-fast, 250ms);
+  --chart-motion-slow: 800ms;
+  --chart-motion-reveal: 1100ms;
+  --chart-ease-reveal: cubic-bezier(0.85, 0, 0.15, 1);
+  --chart-stagger: 30ms;
+  --chart-crosshair: color-mix(
+    in srgb,
+    var(--muted-foreground, oklch(0.5 0.01 286)) 60%,
+    transparent
+  );
+  /* The card step draws its own hairline, so a chart card carries no border of its own. */
+  --chart-card-shadow: var(--elev-card);
+  --chart-card-shadow-hover: var(--elev-card-hover);
+}

package/src/charts/charts.css

@@ -67,38 +67,6 @@
   font-variant-numeric: tabular-nums;
 }
 
-/* Shared chart tokens, held at zero specificity by `:where()`. The reveal pair
-   is the entrance every chart shares; motion.ts mirrors its duration. */
-:where(
-  .hr-area-chart,
-  .hr-bar-chart,
-  .hr-line-chart,
-  .hr-sparkline,
-  .hr-number-chart,
-  .hr-stat-card,
-  .hr-legend,
-  .hr-ts-chart,
-  .hr-donut-chart,
-  .hr-ring,
-  .hr-gauge
-) {
-  --chart-label: var(--muted-foreground, oklch(0.5 0.01 286));
-  --chart-grid: color-mix(in srgb, var(--border, oklch(0.5 0.01 286)) 65%, transparent);
-  --chart-ease-out: cubic-bezier(0.22, 1, 0.36, 1);
-  --chart-motion-fast: 150ms;
-  --chart-motion: 250ms;
-  --chart-motion-slow: 800ms;
-  --chart-motion-reveal: 1100ms;
-  --chart-ease-reveal: cubic-bezier(0.85, 0, 0.15, 1);
-  --chart-stagger: 30ms;
-  --chart-crosshair: color-mix(
-    in srgb,
-    var(--muted-foreground, oklch(0.5 0.01 286)) 60%,
-    transparent
-  );
-  --chart-card-shadow: 0 1px 2px 0 oklch(0 0 0 / 0.04), 0 1px 3px 0 oklch(0 0 0 / 0.06);
-}
-
 /* Axis labels, grid rules and hover highlights for every chart, defined once.
    `:where()` keeps specificity at 0 so a component can still override them. */
 :where(

package/src/charts/donut-chart.svelte

@@ -2,6 +2,7 @@
 	// =========================
 	// IMPORTS
 	// =========================
+	import "./chart-tokens.css";
 	import "./donut-chart.css";
 	import { Arc, Chart, Group, Pie, Svg, Text } from "layerchart";
 	import { scaleOrdinal } from "d3-scale";

package/src/charts/figure.svelte

@@ -2,6 +2,7 @@
 	// =========================
 	// IMPORTS
 	// =========================
+	import "./chart-tokens.css";
 	import "./figure.css";
 	import { cn } from "../lib/utils.js";
 	import type { Snippet } from "svelte";

package/src/charts/gauge-chart.svelte

@@ -8,6 +8,7 @@
 	// =========================
 	// IMPORTS
 	// =========================
+	import "./chart-tokens.css";
 	import "./gauge-chart.css";
 	import { cn } from "../lib/utils.js";
 	import AnimatedValue from "./animated-value.svelte";

package/src/charts/index.ts

@@ -1,3 +1,4 @@
+import "./chart-tokens.css";
 import "./charts.css";
 
 export { default as BarChart } from "./bar-chart.svelte";

package/src/charts/legend.svelte

@@ -2,6 +2,7 @@
 	// =========================
 	// IMPORTS
 	// =========================
+	import "./chart-tokens.css";
 	import "./legend.css";
 	import { cn } from "../lib/utils.js";
 

package/src/charts/line-chart.svelte

@@ -2,6 +2,7 @@
 	// =========================
 	// IMPORTS
 	// =========================
+	import "./chart-tokens.css";
 	import "./line-chart.css";
 	import {
 		Area,

package/src/charts/motion.ts

@@ -1,6 +1,6 @@
 import { cubicInOut } from "svelte/easing";
 
-/** Mirrors `--chart-motion-reveal` in charts.css, for when no element is mounted to read it from. */
+/** Mirrors `--chart-motion-reveal` in chart-tokens.css, for when no element is mounted to read it from. */
 export const REVEAL_MS = 1100;
 
 /** Rescales the axes when the data changes; the first render never animates. */

package/src/charts/number-chart.svelte

@@ -13,6 +13,7 @@
 	// =========================
 	// IMPORTS
 	// =========================
+	import "./chart-tokens.css";
 	import "./number-chart.css";
 	import { Minus, TrendDown, TrendUp } from "phosphor-svelte";
 	import { cn } from "../lib/utils.js";

package/src/charts/ring-chart.svelte

@@ -2,6 +2,7 @@
 	// =========================
 	// IMPORTS
 	// =========================
+	import "./chart-tokens.css";
 	import "./ring-chart.css";
 	import type { Snippet } from "svelte";
 	import { cn } from "../lib/utils.js";

package/src/charts/sparkline.svelte

@@ -2,6 +2,7 @@
 	// =========================
 	// IMPORTS
 	// =========================
+	import "./chart-tokens.css";
 	import "./sparkline.css";
 	import { Area, Chart, Highlight, LinearGradient, Points, Spline, Svg, Tooltip } from "layerchart";
 	import { curveMonotoneX } from "d3-shape";

package/src/charts/stat-card.svelte

@@ -2,6 +2,7 @@
 	// =========================
 	// IMPORTS
 	// =========================
+	import "./chart-tokens.css";
 	import "./stat-card.css";
 	import { Area, Bars, Chart, Highlight, LinearGradient, Spline, Svg, Tooltip } from "layerchart";
 	import { scaleBand } from "d3-scale";

package/src/charts/time-series-chart.svelte

@@ -2,6 +2,7 @@
 	// =========================
 	// IMPORTS
 	// =========================
+	import "./chart-tokens.css";
 	import "./time-series-chart.css";
 	import { scaleTime } from "d3-scale";
 	import { curveMonotoneX } from "d3-shape";

package/src/components/segmented/segmented-filter.svelte

@@ -13,6 +13,8 @@
 		splitSegments,
 	} from "./collapse.js";
 	import { segmentedTriggerClass } from "./segmented.js";
+	import { Icon } from "../icon/index.js";
+	import { Mark } from "../mark/index.js";
 
 	// =========================
 	// TYPES
@@ -42,6 +44,10 @@
 		max?: number | "none";
 		/** What the menu segment says. Translate at the call site. */
 		moreLabel?: string;
+		/** An option with an `image` or `icon` draws the mark alone, and its label
+		 *  moves to `aria-label` and the hover title. For a toolbar with no room
+		 *  for words, where every mark is a brand people know. */
+		iconOnly?: boolean;
 		class?: string;
 	}
 
@@ -57,6 +63,7 @@
 		block = true,
 		max = SEGMENT_MAX,
 		moreLabel,
+		iconOnly = false,
 		class: className,
 	}: Props = $props();
 
@@ -99,21 +106,39 @@
 	<SegmentedTrack fill={block}>
 		{#each split.visible as option (option.value)}
 			{@const active = value === option.value}
+			{@const markOnly = iconOnly && Boolean(option.image || option.icon)}
 			<button
 				type="button"
 				class={segmentedTriggerClass({ fill: block, active })}
 				onclick={() => pick(option.value)}
 				aria-pressed={active}
+				aria-label={markOnly ? option.label : undefined}
+				title={markOnly ? option.label : undefined}
 			>
-				<Segment
-					label={option.label}
-					count={option.count}
-					icon={option.icon}
-					image={option.image}
-					done={option.done}
-					badge={option.badge}
-					{active}
-				/>
+				<!-- WHY the mark is drawn here, not by `Segment`: `Segment` always
+				     writes the label, and a count or dot beside a bare mark reads as noise. -->
+				{#if markOnly && option.image}
+					<Mark
+						src={option.image}
+						label={option.label}
+						class={cn(
+							"opacity-75 transition-opacity duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] group-hover/segment:opacity-100",
+							active && "opacity-100",
+						)}
+					/>
+				{:else if markOnly && option.icon}
+					<Icon icon={option.icon} size={16} class="shrink-0" />
+				{:else}
+					<Segment
+						label={option.label}
+						count={option.count}
+						icon={option.icon}
+						image={option.image}
+						done={option.done}
+						badge={option.badge}
+						{active}
+					/>
+				{/if}
 			</button>
 		{/each}
 		{#snippet after()}

package/src/lib/sound.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const cuelume = vi.hoisted(() => ({
+  bind: vi.fn(() => () => {}),
+  play: vi.fn(),
+  setEnabled: vi.fn(),
+  unlock: vi.fn(() => Promise.resolve(true)),
+}));
+vi.mock("cuelume", () => cuelume);
+
+// The module holds the setting and the silence count, so each test loads a fresh copy.
+async function load() {
+  vi.resetModules();
+  return import("./sound.js");
+}
+
+function lastEnabled(): unknown {
+  return cuelume.setEnabled.mock.calls.at(-1)?.[0];
+}
+
+beforeEach(() => {
+  localStorage.clear();
+  document.body.innerHTML = "";
+  for (const fn of Object.values(cuelume)) fn.mockClear();
+});
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("markSlots", () => {
+  it("gives each kit control the binding for its job", async () => {
+    const { markSlots } = await load();
+    document.body.innerHTML = `
+      <button data-slot="button">Save</button>
+      <button data-slot="switch"></button>
+      <button data-slot="dropdown-menu-trigger"></button>
+      <button data-slot="code-block-copy-button"></button>
+      <input data-slot="input" />`;
+    markSlots(document);
+    const [button, sw, menu, copy, input] = document.body.children;
+    expect(button.getAttribute("data-cuelume-tap")).toBe("");
+    expect(sw.hasAttribute("data-cuelume-toggle")).toBe(true);
+    expect(menu.hasAttribute("data-cuelume-open")).toBe(true);
+    expect(menu.getAttribute("data-cuelume-emphasis")).toBe("subtle");
+    expect(copy.getAttribute("data-cuelume-tap")).toBe("success");
+    // Text fields stay quiet unless the app opts one in.
+    expect(input.getAttributeNames().some((n) => n.startsWith("data-cuelume-"))).toBe(false);
+  });
+
+  it("leaves a control alone that names its own cue or sits under data-sound=off", async () => {
+    const { markSlots } = await load();
+    document.body.innerHTML = `
+      <button data-slot="button" data-cuelume-close="">Delete</button>
+      <div data-sound="off"><button data-slot="button">Quiet</button></div>`;
+    markSlots(document);
+    const [own, quiet] = document.querySelectorAll("button");
+    expect(own.hasAttribute("data-cuelume-tap")).toBe(false);
+    expect(quiet.hasAttribute("data-cuelume-tap")).toBe(false);
+  });
+});
+
+describe("startSound", () => {
+  it("binds the root and marks controls that mount later", async () => {
+    const { startSound } = await load();
+    const stop = startSound(document);
+    expect(cuelume.bind).toHaveBeenCalledWith(document);
+    const later = document.createElement("button");
+    later.setAttribute("data-slot", "tabs-trigger");
+    document.body.append(later);
+    await Promise.resolve();
+    expect(later.hasAttribute("data-cuelume-select")).toBe(true);
+    stop();
+  });
+
+  it("starts muted when nothing was saved", async () => {
+    const { startSound, soundOn } = await load();
+    startSound(document)();
+    expect(soundOn()).toBe(false);
+    expect(lastEnabled()).toBe(false);
+  });
+
+  it("starts audible when the person turned sound on before", async () => {
+    localStorage.setItem("heyramzi:sound", "on");
+    const { startSound } = await load();
+    startSound(document)();
+    expect(lastEnabled()).toBe(true);
+  });
+});
+
+describe("setSound, silence and cue", () => {
+  it("saves the choice and unlocks audio only when turning on", async () => {
+    const { setSound } = await load();
+    await expect(setSound(true)).resolves.toBe(true);
+    expect(localStorage.getItem("heyramzi:sound")).toBe("on");
+    expect(cuelume.unlock).toHaveBeenCalledOnce();
+    await expect(setSound(false)).resolves.toBe(false);
+    expect(localStorage.getItem("heyramzi:sound")).toBe("off");
+    expect(cuelume.unlock).toHaveBeenCalledOnce();
+  });
+
+  it("mutes while any hold is open, and a second release changes nothing", async () => {
+    const { setSound, silence, cue } = await load();
+    await setSound(true);
+    const first = silence();
+    const second = silence();
+    cue("success");
+    expect(cuelume.play).not.toHaveBeenCalled();
+    first();
+    first();
+    expect(lastEnabled()).toBe(false);
+    second();
+    expect(lastEnabled()).toBe(true);
+    cue("success", { emphasis: "strong" });
+    expect(cuelume.play).toHaveBeenCalledWith("success", { emphasis: "strong" });
+  });
+
+  it("plays nothing while sound is off", async () => {
+    const { cue } = await load();
+    cue("error");
+    expect(cuelume.play).not.toHaveBeenCalled();
+  });
+});

package/src/lib/sound.ts

@@ -0,0 +1,166 @@
+/**
+ * Interface sounds from cuelume, off until the person turns them on. Call `startSound()` once in
+ * the root layout: it marks the kit's controls by their `data-slot` and binds them, so no
+ * component carries a sound attribute of its own. Outcomes (saved, failed, ready) are `cue()`
+ * calls in the app. The cue for each job follows https://cuelume.dev/agents.md, "Which cue?".
+ */
+import { bind, play, setEnabled, unlock, type PlayOptions, type SoundName } from "cuelume";
+
+type Binding = "tap" | "select" | "toggle" | "open" | "close" | "navigate";
+
+interface SlotCue {
+  binding: Binding;
+  /** Another cue than the binding's own, as `data-cuelume-tap="success"` plays `success`. */
+  cue?: SoundName;
+  subtle?: true;
+}
+
+/**
+ * Which kit slots sound, and how. Text fields are left out on purpose: a keystroke sound in every
+ * input is too much for tools people type in all day, so an app opts a field in with
+ * `data-cuelume-type`.
+ */
+export const SLOT_CUES: Readonly<Record<string, SlotCue>> = {
+  button: { binding: "tap" },
+  "code-block-copy-button": { binding: "tap", cue: "success", subtle: true },
+  switch: { binding: "toggle" },
+  checkbox: { binding: "toggle" },
+  toggle: { binding: "toggle" },
+  "sidebar-trigger": { binding: "toggle", subtle: true },
+  "dialog-trigger": { binding: "open" },
+  "sheet-trigger": { binding: "open" },
+  "alert-dialog-trigger": { binding: "open" },
+  "popover-trigger": { binding: "open", subtle: true },
+  "dropdown-menu-trigger": { binding: "open", subtle: true },
+  "select-trigger": { binding: "open", subtle: true },
+  "dialog-close": { binding: "close" },
+  "sheet-close": { binding: "close" },
+  "popover-close": { binding: "close", subtle: true },
+  "select-item": { binding: "select" },
+  "dropdown-menu-item": { binding: "select" },
+  "dropdown-menu-checkbox-item": { binding: "select" },
+  "dropdown-menu-radio-item": { binding: "select" },
+  "context-menu-item": { binding: "select" },
+  "command-item": { binding: "select" },
+  "tabs-trigger": { binding: "select" },
+  "radio-group-item": { binding: "select" },
+  "toggle-group-item": { binding: "select" },
+};
+
+const BINDING_ATTRS = ["tap", "type", "select", "toggle", "open", "close", "navigate"].map(
+  (b) => `data-cuelume-${b}`,
+);
+const STORAGE_KEY = "heyramzi:sound";
+
+/** The saved setting, read on first use so a server render never touches storage. */
+let wanted: boolean | undefined;
+/** Open `silence()` holds. Any one of them mutes everything, whatever the setting says. */
+let holds = 0;
+
+function readSaved(): boolean {
+  try {
+    return localStorage.getItem(STORAGE_KEY) === "on";
+  } catch {
+    return false;
+  }
+}
+
+function audible(): boolean {
+  wanted ??= typeof window === "undefined" ? false : readSaved();
+  return wanted && holds === 0;
+}
+
+function apply(): void {
+  setEnabled(audible());
+}
+
+/** Whether the person turned sound on. A `silence()` hold doesn't change it. */
+export function soundOn(): boolean {
+  audible();
+  return wanted === true;
+}
+
+/**
+ * Turns sound on or off and saves it. Call it from the click that flips the setting: turning on
+ * unlocks audio inside that gesture, and the result says whether the browser lets it play.
+ */
+export function setSound(on: boolean): Promise<boolean> {
+  wanted = on;
+  try {
+    localStorage.setItem(STORAGE_KEY, on ? "on" : "off");
+  } catch {
+    // Private windows and blocked storage keep the choice for this page only.
+  }
+  apply();
+  return on ? unlock() : Promise.resolve(false);
+}
+
+/**
+ * Mutes every cue until the returned function runs, such as while the mic records, so no sound
+ * lands in the take. Holds stack; each release counts once.
+ */
+export function silence(): () => void {
+  holds++;
+  apply();
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    holds--;
+    apply();
+  };
+}
+
+/** Plays a cue for an outcome the app knows about, only while sound is on and nothing silences it. */
+export function cue(name: SoundName, options?: PlayOptions): void {
+  if (audible()) play(name, options);
+}
+
+function mark(el: Element): void {
+  const slot = SLOT_CUES[el.getAttribute("data-slot") ?? ""];
+  if (!slot || el.closest('[data-sound="off"]')) return;
+  // A control that names its own cue keeps it.
+  if (BINDING_ATTRS.some((attr) => el.hasAttribute(attr))) return;
+  el.setAttribute(`data-cuelume-${slot.binding}`, slot.cue ?? "");
+  if (slot.subtle && !el.hasAttribute("data-cuelume-emphasis")) {
+    el.setAttribute("data-cuelume-emphasis", "subtle");
+  }
+}
+
+/** Stamps the cuelume attribute on every kit control under `root`, `root` included. */
+export function markSlots(root: ParentNode): void {
+  if (root instanceof Element && root.hasAttribute("data-slot")) mark(root);
+  for (const el of root.querySelectorAll("[data-slot]")) mark(el);
+}
+
+/**
+ * Binds the kit's controls under `root` and keeps marking the ones that mount later. Safe on the
+ * server, where it does nothing. Returns the function that stops it.
+ */
+export function startSound(root: ParentNode = globalThis.document): () => void {
+  if (typeof window === "undefined" || !root) return () => {};
+  apply();
+  markSlots(root);
+  const observer = new MutationObserver((records) => {
+    for (const record of records) {
+      if (record.type === "attributes") {
+        if (record.target instanceof Element) mark(record.target);
+        continue;
+      }
+      for (const node of record.addedNodes) {
+        if (node instanceof Element) markSlots(node);
+      }
+    }
+  });
+  observer.observe(root as Node, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    attributeFilter: ["data-slot"],
+  });
+  const unbind = bind(root);
+  return () => {
+    observer.disconnect();
+    unbind();
+  };
+}