# Newsletter (Notchset): prompt.md (v1.0.0)

- id: `newsletter` · version 1.0.0 · block · free
- category: Marketing
- build: Base UI (one set of files; its dependencies follow the build)
- install (this build): `npx shadcn@latest add https://beautiful-ui.dev/r/newsletter.json`
- npm dependencies: none
- registry dependencies: utils, @beautiful-ui/segmented-control, https://beautiful-ui.dev/r/notchset-foundation.json
- docs: https://beautiful-ui.dev/components/newsletter
- The install command carries everything this item needs (files, CSS, tokens, npm and registry dependencies). Prefer it to copying source by hand.

A newsletter signup, inline beside a deck of recent issues you can turn or as a compact card with its readers, with a frequency switch that rewrites the copy, validation in place, the scanner while sending, and a swap to CHECK YOUR INBOX with a drawn check.

## Build it
- Stack: React 19 (`ref` is a plain prop), TypeScript, Tailwind CSS v4 utilities, a shadcn-initialised project with the `@/*` alias.
- Packages: none beyond React.
- Files: `components/ui/notchset/blocks/newsletter.tsx`; shared code: `lib/beautiful-ui/notchset/instrument.tsx`, `lib/beautiful-ui/notchset/root.ts`.
- Registry dependencies, installed with it automatically: shadcn `utils` (cn), `segmented-control`, `notchset-foundation`.
- Builds: one set of files for both, but its dependencies come in Base UI and Radix builds. Install the one that matches the project (see Install): a free item's bare URL installs the Base UI build of it and its dependencies.
- Exports to keep: `Newsletter`, and every exported type.
- CSS: the install adds the notchset foundation (tokens, keyframes, motion levels) to your global stylesheet once. Nothing to import by hand.
- Re-running `add` (or `--overwrite`) re-applies those rules: put overrides in your own CSS, never in the installed rules.
- Tokens: retheme with the `--notchset-*` custom properties (`--notchset-check`, `--notchset-control-edge`, `--notchset-draw-from`, `--notchset-ease-bloom`, `--notchset-ease-glide`, `--notchset-ease-key-down`, `--notchset-ease-key-up`, `--notchset-ease-travel`, `--notchset-fade`, `--notchset-focus-color`, `--notchset-focus-inset`, `--notchset-grow-to`, `--notchset-key-down`, `--notchset-key-up`, `--notchset-life-from`, `--notchset-life-ms`, `--notchset-node-blink`, `--notchset-node-bloom`, `--notchset-node-delay`, `--notchset-plate-color`, `--notchset-rise-from`, `--notchset-rule`, `--notchset-scan-to`, `--notchset-scroll`, `--notchset-signal`, `--notchset-sweep-to`, `--notchset-travel`). Never add Tailwind colour classes inside the component.

```tsx
import { Newsletter } from "@/components/ui/notchset/blocks/newsletter";
```

## Parts

| Part | data-slot | What it is for |
|---|---|---|
| `Newsletter` | `newsletter` | The signup, inline or as a card. |

Style a part with `[data-slot="<slot>"]` selectors or its `className`; keep the attributes when editing.

## Sound
- Keep every `data-slot` and `data-sound` attribute: the sound layer reads them.
- Installing this item adds no audio. Nothing plays until the app mounts `SoundProvider` once (install: `npx shadcn@latest add https://beautiful-ui.dev/r/notchset-sound.json`, import from `@/components/ui/notchset/sound-provider`); `useSound()` gives `muted` and `setMuted` for a mute control. Without a provider the audio engine never loads.

## Match the original
- Read `components/ui/notchset/blocks/newsletter.tsx` as the reference implementation before changing or recreating anything, and match it: sizes, colours per theme, motion timings, copy and behaviour.
- If you deviate (a prop you can't honour, a style you changed, a dependency you swapped), say so in your reply, part by part.
- Keep the accessibility contract, the keyboard map and the motion levels listed below.

## Use it when
- newsletter, email signup, subscribe form, mailing list, digest signup, issue preview, Notchset
- Asking readers to subscribe on a blog, docs or landing page
- Showing what they'll get before they give their email

### Not when
- Signing up for the product itself: use the CTA's signup
- A one-off waitlist with a place number: use your waitlist flow

## Mistakes
- Use double opt-in: show CHECK YOUR INBOX, not SUBSCRIBED, until the link is confirmed
- Reject the promise on a failed send, so the reader sees it and keeps their email

## Usage

```tsx
import { Newsletter } from "@/components/ui/notchset/blocks/newsletter";

export function Signup() {
  return (
    <Newsletter
      variant="card"
      eyebrow="THE TRACE · A RELAY NEWSLETTER"
      frequencies={[{ value: "monthly", label: "MONTHLY", headline: "One email a month", body: "What shipped, what broke and what we learned." }]}
      onSubscribe={(email) =>
        fetch("/api/newsletter", { method: "POST", body: JSON.stringify({ email }) }).then((r) => {
          if (!r.ok) throw new Error("subscribe failed");
        })
      }
      footnote="NO TRACKING PIXELS · ONE-CLICK UNSUBSCRIBE"
    />
  );
}
```

## Props

| Prop | Type | Default | What it does |
|---|---|---|---|
| `variant` | `"inline" \| "card"` |  | Inline shows the issue deck; card is compact with the readers under it. |
| `eyebrow` | `string` |  | The line above the headline (also the section's name). |
| `frequencies` | `{ value, label, headline, body, issues? }[]` |  | Two or more add a switch that rewrites the copy and the deck. |
| `frequency / onFrequencyChange` | `string / (value) => void` |  | Control the frequency (optional). |
| `onSubscribe` | `(email, frequency) => Promise` |  | Resolve to show CHECK YOUR INBOX; reject to show the failure line (the email stays). |
| `readers` | `{ count, label, initials }` |  | The readers line; the count rolls up by one on a signup. |
| `footnote / sentTo / failure` | `ReactNode / (email) => string / string` |  | The line under the form, the success line and the failure line. |

Full docs: https://beautiful-ui.dev/components/newsletter

## Customising
- Colours: the component reads your shadcn tokens (`--background`, `--foreground`, `--border` …), refined by the `--notchset-*` tokens. The signal colour is `--notchset-signal` (it falls back to `--destructive`). Set tokens on `:root`, or on any container to retheme one area.
- Dark mode follows the `.dark` class on an ancestor (the shadcn and next-themes convention).
- Update later by re-running the install with `--overwrite` (review the diff if you edited it). Changelog: https://beautiful-ui.dev/r/changelog.json

## Keyboard

| Keys | Action |
|---|---|
| Enter | Subscribe from the field |
| ← → | Change the frequency |
| Tab | The turn buttons and USE ANOTHER EMAIL |

## Performance

- Plain markup and CSS transitions; nothing runs while idle.

## Responsive

- Inline stacks the deck under the form under 760px (container width); the card fits 320px.

## Motion inventory

| Interaction | What moves |
|---|---|
| Invalid email | A signal edge and a short shake (250ms) |
| Sending | The 5-tick scanner |
| Sent | The form lifts away, the confirmation rises and its check draws (260ms) |
| Deck | Issues turn with 12px offsets (520ms glide) |
| Readers | The count rolls up by one |

## Accessibility contract (preserve when editing)
- The section is named by its eyebrow; the email field has a label and marks invalid input (aria-invalid) with the message tied to it (aria-describedby)
- Messages and the success state are announced (aria-live, role=status); the hidden form is inert while the success shows
- The issue deck shows one issue to assistive tech at a time; the turn buttons are named and the position is announced

## Install

Base UI project (a base-* style in components.json):

```bash
npx shadcn@latest add https://beautiful-ui.dev/r/newsletter.json
```

Radix project (a radix-*, new-york or default style):

```bash
npx shadcn@latest add https://beautiful-ui.dev/r/radix-nova/newsletter.json
```

Or add the `@beautiful-ui` registry to components.json and run `npx shadcn@latest add @beautiful-ui/newsletter`: the CLI picks the build from your style.

## Credits
- Built on shadcn/ui (https://ui.shadcn.com)

## Source (Base UI build)

### components/ui/notchset/blocks/newsletter.tsx

```tsx
"use client";

import * as React from "react";
import { cn } from "@/lib/utils";
import { SegmentedControl } from "@/components/ui/notchset/segmented-control";
import { NOTCHSET_ROOT, OWN_SOUND, RollingNumber, Scanner, motionOff, playCue } from "@/lib/beautiful-ui/notchset/instrument";

/*
 * Notchset Newsletter (a block, one file for both builds). A signup for a newsletter: inline (the form
 * beside a deck of recent issues you can turn) or card (compact, with the readers under it). An optional
 * frequency switch rewrites the copy. The form validates in place (a signal edge and a shake), works
 * with the scanner, and swaps to CHECK YOUR INBOX with a drawn check; a failure says so and keeps the email.
 */

export type NewsletterIssue = { number: string; date: string; title: string; links: readonly { title: string; meta: string }[] };
export type NewsletterFrequency = { value: string; label: string; headline: string; body: React.ReactNode; issues?: readonly NewsletterIssue[] };

export type NewsletterProps = Omit<React.ComponentProps<"section">, "children" | "title"> & {
  variant?: "inline" | "card";
  /** The small line above the headline. */
  eyebrow: string;
  /** One or more frequencies; with two or more, a switch picks between them and rewrites the copy. */
  frequencies: readonly NewsletterFrequency[];
  frequency?: string;
  onFrequencyChange?: (value: string) => void;
  /** Subscribe; resolve on success, reject to show `failure`. */
  onSubscribe: (email: string, frequency: string) => Promise<unknown>;
  /** The line under the form (privacy, unsubscribe). */
  footnote?: React.ReactNode;
  readers?: { count: number; label: string; initials: readonly string[] };
  /** The success line; gets the address. */
  sentTo?: (email: string) => string;
  failure?: string;
};

const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/;

function Readers({ readers, count }: { readers: NonNullable<NewsletterProps["readers"]>; count: number }) {
  return (
    <span className="flex items-center gap-2.5">
      <span aria-hidden className="flex">
        {readers.initials.slice(0, 4).map((i, k) => (
          <span key={i} className={cn("flex size-[22px] items-center justify-center rounded-full border-[1.5px] border-solid border-background bg-foreground font-mono text-[10px] font-medium text-background", k > 0 && "-ms-1.5")}>
            {i}
          </span>
        ))}
      </span>
      <span className="flex items-center gap-1.5 font-mono text-[10px] tracking-[0.06em] whitespace-nowrap">
        <RollingNumber value={count.toLocaleString("en-US")} height={14} />
        <span className="text-muted-foreground">{readers.label}</span>
      </span>
    </span>
  );
}

function Deck({ issues }: { issues: readonly NewsletterIssue[] }) {
  const [top, setTop] = React.useState(0);
  const root = React.useRef<HTMLDivElement>(null);
  const n = issues.length;
  // A new frequency brings a new deck: start from its newest issue.
  const [seen, setSeen] = React.useState(issues);
  if (seen !== issues) {
    setSeen(issues);
    setTop(0);
  }
  const turn = (d: number) => {
    playCue(root.current, "tick");
    setTop((t) => (t + d + n) % n);
  };
  return (
    <div ref={root} className="flex min-w-0 flex-col gap-4">
      <div className="relative me-6 mt-6 h-[330px]">
        {issues.map((issue, i) => {
          const pos = (i - top + n) % n;
          return (
            <article
              key={issue.number}
              aria-hidden={pos !== 0 || undefined}
              className={cn(
                "absolute inset-0 box-border flex flex-col gap-3.5 border border-solid bg-background px-[22px] py-5 transition-[translate,opacity,border-color] duration-[520ms] ease-(--notchset-ease-glide)",
                pos === 0 ? "border-foreground" : "border-[var(--notchset-rule,var(--border))]",
              )}
              style={{ zIndex: n - pos, translate: `${pos * 12}px ${pos * -12}px`, opacity: pos === 0 ? 1 : pos === 1 ? 0.75 : 0.45 }}
            >
              <div className="flex items-baseline justify-between border-0 border-b border-solid border-[var(--notchset-rule,var(--border))] pb-3">
                <span className="flex flex-col gap-1">
                  <span className="text-[20px] leading-none font-extrabold tracking-[0.02em] uppercase [font-stretch:62%]">{issue.title.split(" · ")[0]}</span>
                  <span className="font-mono text-[10px] tracking-[0.1em] whitespace-nowrap text-muted-foreground">{issue.date}</span>
                </span>
                <span className="font-mono text-[10px] tracking-[0.1em] whitespace-nowrap text-muted-foreground">{issue.number}</span>
              </div>
              <span className="text-[19px] leading-[1.25] font-semibold [text-wrap:balance]">{issue.title.split(" · ")[1] ?? issue.title}</span>
              <div className="flex flex-col">
                {issue.links.map((l, k) => (
                  <div key={l.title} className="grid min-h-10 grid-cols-[24px_minmax(0,1fr)_auto] items-center gap-2.5 border-0 border-t border-solid border-[var(--notchset-rule,var(--border))]">
                    <span className="font-mono text-[10px] text-muted-foreground">{String(k + 1).padStart(2, "0")}</span>
                    <span className="text-[13px] leading-[1.35]">{l.title}</span>
                    <span className="font-mono text-[10px] whitespace-nowrap text-muted-foreground">{l.meta}</span>
                  </div>
                ))}
              </div>
            </article>
          );
        })}
      </div>
      {n > 1 && (
        <div className="me-6 flex items-center justify-end gap-1.5">
          <span aria-live="polite" className="me-1 font-mono text-[10px] tracking-[0.08em] whitespace-nowrap text-muted-foreground">
            {issues[top]!.number} · {top + 1} OF {n}
          </span>
          {[
            ["Previous issue", -1, "‹"],
            ["Next issue", 1, "›"],
          ].map(([label, d, glyph]) => (
            <button
              key={label as string}
              {...OWN_SOUND}
              type="button"
              aria-label={label as string}
              onClick={() => turn(d as number)}
              className={cn(`notchset-focus`, "[--notchset-focus-inset:-3px] size-[30px] cursor-pointer border border-solid border-[var(--notchset-rule,var(--border))] bg-transparent p-0 font-mono text-[12px] text-foreground transition-colors duration-(--notchset-fade) ease-(--notchset-ease-fade) hover:border-foreground")}
            >
              {glyph}
            </button>
          ))}
        </div>
      )}
    </div>
  );
}

function Newsletter({
  variant = "inline",
  eyebrow,
  frequencies,
  frequency: frequencyProp,
  onFrequencyChange,
  onSubscribe,
  footnote,
  readers,
  sentTo = (email) => `We sent a confirmation link to ${email}.`,
  failure = "COULDN’T REACH THE SERVER · TRY AGAIN",
  className,
  ...props
}: NewsletterProps) {
  const [ownFrequency, setOwnFrequency] = React.useState(frequencies[0]?.value ?? "");
  const frequency = frequencyProp ?? ownFrequency;
  const current = frequencies.find((f) => f.value === frequency) ?? frequencies[0]!;
  const [email, setEmail] = React.useState("");
  const [state, setState] = React.useState<{ kind: "idle" | "invalid" | "sending" | "sent" | "failed"; message?: string; sentTo?: string }>({ kind: "idle" });
  // The shake runs once per refusal and clears on animationend (re-keying would remount the field and drop focus).
  const [shaking, setShaking] = React.useState(false);
  const [count, setCount] = React.useState(readers?.count ?? 0);
  const [seenCount, setSeenCount] = React.useState(readers?.count);
  if (seenCount !== readers?.count) {
    setSeenCount(readers?.count);
    setCount(readers?.count ?? 0);
  }
  const field = React.useRef<HTMLInputElement>(null);
  const msgId = React.useId();
  const formRef = React.useRef<HTMLFormElement>(null);
  const card = variant === "card";

  const submit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (state.kind === "sending") return;
    const value = email.trim();
    if (!EMAIL.test(value)) {
      playCue(formRef.current, "signal");
      if (!motionOff(formRef.current)) setShaking(true);
      setState({ kind: "invalid", message: value ? "THAT EMAIL LOOKS INCOMPLETE" : "ENTER AN EMAIL FIRST" });
      field.current?.focus();
      return;
    }
    setState({ kind: "sending" });
    try {
      await onSubscribe(value, frequency);
      playCue(formRef.current, "done");
      setCount((c) => c + 1);
      setState({ kind: "sent", sentTo: value });
    } catch {
      playCue(formRef.current, "signal");
      setState({ kind: "failed", message: failure });
    }
  };
  const sent = state.kind === "sent";
  const bad = state.kind === "invalid" || state.kind === "failed";

  return (
    <section {...NOTCHSET_ROOT} data-slot="newsletter" data-variant={variant} aria-label={eyebrow} className={cn("@container box-border border border-solid border-foreground bg-background text-foreground", className)} {...props}>
      <div className={cn("grid items-center justify-center gap-12", card ? "grid-cols-1 p-8" : "grid-cols-[minmax(0,1fr)_minmax(0,1fr)] px-10 py-11 @max-[760px]:grid-cols-1 @max-[760px]:px-6")}>
        <div className={cn("flex min-w-0 flex-col gap-[18px]", card && "mx-auto w-full max-w-[460px]")}>
          <span className="flex items-center gap-2 font-mono text-[10px] tracking-[0.14em] whitespace-nowrap text-muted-foreground uppercase">
            <span aria-hidden className="size-2 rounded-full bg-foreground" />
            {eyebrow}
          </span>
          <h2 className={cn("m-0 font-extrabold uppercase [font-stretch:62%] [text-wrap:balance]", card ? "text-[34px]" : "text-[clamp(34px,4.4vw,48px)]", "leading-[0.9]")}>{current.headline}</h2>
          <p className="m-0 max-w-[460px] text-[15px] leading-[1.55] text-muted-foreground [text-wrap:pretty]">{current.body}</p>
          {frequencies.length > 1 && (
            <SegmentedControl
              aria-label="How often"
              size="sm"
              segment={96}
              className="self-start"
              options={frequencies.map((f) => ({ value: f.value, label: f.label }))}
              value={frequency}
              onValueChange={(v) => {
                setOwnFrequency(v);
                onFrequencyChange?.(v);
              }}
            />
          )}
          <div className="grid">
            <form
              ref={formRef}
              noValidate
              onSubmit={submit}
              aria-hidden={sent || undefined}
              inert={sent || undefined}
              className={cn("col-start-1 row-start-1 flex flex-col gap-2 transition-[opacity,translate] duration-(--notchset-fold) ease-(--notchset-ease-glide)", sent ? "-translate-y-1.5 opacity-0" : "translate-y-0 opacity-100")}
            >
              <div
                onAnimationEnd={() => setShaking(false)}
                className={cn(
                  "flex h-12 border border-solid bg-[var(--notchset-field,var(--background))] transition-[border-color] duration-(--notchset-fade) ease-(--notchset-ease-fade)",
                  bad ? "border-[var(--notchset-signal,var(--destructive))]" : "border-[var(--notchset-control-edge,var(--input))] focus-within:border-foreground",
                  shaking && "motion-safe:animate-[notchset-shake_var(--notchset-shake)_linear]",
                )}
              >
                <input
                  ref={field}
                  type="email"
                  aria-label="Email address"
                  aria-invalid={bad || undefined}
                  aria-describedby={msgId}
                  value={email}
                  readOnly={state.kind === "sending"}
                  onChange={(e) => {
                    setEmail(e.target.value);
                    if (state.kind === "invalid" || state.kind === "failed") setState({ kind: "idle" });
                  }}
                  placeholder="you@company.com"
                  autoComplete="email"
                  spellCheck={false}
                  className="min-w-0 flex-1 border-0 bg-transparent px-3.5 text-[15px] text-foreground outline-none placeholder:text-muted-foreground"
                />
                <button
                  {...OWN_SOUND}
                  type="submit"
                  aria-busy={state.kind === "sending" || undefined}
                  className={cn(`notchset-focus`, "[--notchset-focus-inset:-3px] m-[5px] flex flex-none cursor-pointer items-center gap-2 border-0 bg-foreground px-4 font-mono text-[12px] font-medium tracking-[0.08em] whitespace-nowrap text-background")}
                >
                  {state.kind === "sending" ? (
                    <>
                      <Scanner height={9} /> SENDING
                    </>
                  ) : (
                    "SUBSCRIBE"
                  )}
                </button>
              </div>
              <span id={msgId} aria-live="polite" className={cn("min-h-3.5 font-mono text-[10px] tracking-[0.08em]", bad ? "text-[var(--notchset-signal-text,var(--destructive))]" : "text-muted-foreground")}>
                {state.message ?? ""}
              </span>
            </form>
            <div
              role="status"
              aria-hidden={!sent || undefined}
              className={cn(
                "col-start-1 row-start-1 box-border flex min-h-12 items-center gap-3.5 self-start border border-solid border-foreground px-3.5 py-2 transition-[opacity,translate] duration-(--notchset-unfold) ease-(--notchset-ease-glide)",
                sent ? "translate-y-0 opacity-100" : "pointer-events-none translate-y-1.5 opacity-0",
              )}
            >
              <svg aria-hidden width="22" height="22" viewBox="0 0 22 22" className="flex-none">
                <circle cx="11" cy="11" r="10" className="fill-foreground" />
                <path d="M6.5 11.3 L9.6 14.3 L15.6 8" fill="none" className="stroke-background transition-[stroke-dashoffset] delay-150 duration-(--notchset-check) ease-(--notchset-ease-check)" strokeWidth="1.7" pathLength={1} strokeDasharray={1} style={{ strokeDashoffset: sent ? 0 : 1 }} />
              </svg>
              <span className="flex min-w-0 flex-1 flex-col gap-[3px]">
                <span className="font-mono text-[10px] font-medium tracking-[0.1em] whitespace-nowrap">CHECK YOUR INBOX</span>
                <span className="truncate text-[13px] text-muted-foreground">{state.sentTo ? sentTo(state.sentTo) : ""}</span>
              </span>
              <button
                {...OWN_SOUND}
                type="button"
                tabIndex={sent ? 0 : -1}
                onClick={() => {
                  setEmail("");
                  setState({ kind: "idle" });
                  requestAnimationFrame(() => field.current?.focus());
                }}
                className={cn(`notchset-focus`, "[--notchset-focus-inset:-3px] h-7 flex-none cursor-pointer border-0 bg-transparent px-1.5 font-mono text-[10px] font-medium tracking-[0.08em] text-foreground underline underline-offset-[3px]")}
              >
                USE ANOTHER EMAIL
              </button>
            </div>
          </div>
          {footnote && <span className="flex flex-wrap items-center gap-2.5 font-mono text-[10px] tracking-[0.06em] text-muted-foreground">{footnote}</span>}
          {card && readers && (
            <div className="border-0 border-t border-solid border-[var(--notchset-rule,var(--border))] pt-3.5">
              <Readers readers={readers} count={count} />
            </div>
          )}
        </div>
        {!card && (
          <div className="flex min-w-0 flex-col gap-4">
            {current.issues && current.issues.length > 0 && <Deck issues={current.issues} />}
            {readers && (
              <div className="me-6">
                <Readers readers={readers} count={count} />
              </div>
            )}
          </div>
        )}
      </div>
    </section>
  );
}

export { Newsletter };
```

### lib/beautiful-ui/notchset/instrument.tsx

```tsx
"use client";

import * as React from "react";
import { createPortal } from "react-dom";
import { cn } from "@/lib/utils";

/*
 * Notchset instrument parts, shared by every member of a pack: the node (a round light that reports
 * state), the legend printed above a control, the plate a key presses onto, the traced check, the
 * five-tick scanner, and the glyph flip that lands a changed label left to right. Nodes and checks
 * are inline SVG (round at every DPR); the CSS lives in the Notchset foundation. Also: the one motion
 * policy (reduced motion or a data-motion="off" ancestor), ref composition, the portal container
 * and the sound attributes every Notchset root carries.
 */

// ---------------------------------------------------------------------------------------------
// Motion, refs, portals, sound
// ---------------------------------------------------------------------------------------------

/**
 * Whether motion is off for an element, kept live: it follows the OS reduced-motion setting and any
 * data-motion attribute change above it, so a preference switched mid-playback stops decoration at once.
 */
export function useMotionOff(ref: React.RefObject<Element | null>) {
  const [off, setOff] = React.useState(false);
  React.useEffect(() => {
    const read = () => setOff(motionOff(ref.current));
    const r = requestAnimationFrame(read);
    const mq = window.matchMedia?.("(prefers-reduced-motion: reduce)");
    mq?.addEventListener?.("change", read);
    const mo = new MutationObserver(read);
    mo.observe(document.documentElement, { attributes: true, attributeFilter: ["data-motion"], subtree: true });
    return () => {
      cancelAnimationFrame(r);
      mq?.removeEventListener?.("change", read);
      mo.disconnect();
    };
  }, [ref]);
  return off;
}

/**
 * The microphone, or a rejection after `timeoutMs` (a prompt left open, a denied permission). A stream
 * that arrives after the timeout is stopped at once, so a late "Allow" never leaves the mic on.
 */
export function requestMic(timeoutMs = 5000): Promise<MediaStream> {
  if (typeof navigator === "undefined" || !navigator.mediaDevices?.getUserMedia) return Promise.reject(new Error("no mic"));
  const ask = navigator.mediaDevices.getUserMedia({ audio: true });
  return new Promise((resolve, reject) => {
    let late = false;
    const t = setTimeout(() => {
      late = true;
      reject(new Error("timeout"));
    }, timeoutMs);
    ask.then(
      (stream) => {
        clearTimeout(t);
        if (late) stream.getTracks().forEach((track) => track.stop());
        else resolve(stream);
      },
      (err) => {
        clearTimeout(t);
        reject(err);
      },
    );
  });
}

/** True under prefers-reduced-motion or inside a data-motion="off" scope. Checked when an effect runs. */
export function motionOff(el: Element | null | undefined) {
  if (typeof window === "undefined") return true;
  if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) return true;
  return Boolean(el?.closest('[data-motion="off"]'));
}

function assignRef<T>(ref: React.Ref<T> | undefined, node: T | null): () => void {
  if (typeof ref === "function") {
    const cleanup = ref(node);
    return typeof cleanup === "function" ? cleanup : () => ref(null);
  }
  if (ref) (ref as React.RefObject<T | null>).current = node;
  return () => {
    if (ref) (ref as React.RefObject<T | null>).current = null;
  };
}

/**
 * Puts text on the clipboard. Resolves true once it is there and false when the browser refuses (no
 * permission, an insecure page, no clipboard API), so a "copied" state is only ever shown for a copy.
 */
export async function copyText(text: string): Promise<boolean> {
  try {
    await navigator.clipboard.writeText(text);
    return true;
  } catch {
    return false;
  }
}

/** The glide easing shared by travelling marks (selection blocks, highlights, runs). */
export const GLIDE = "cubic-bezier(.65,0,.35,1)";

/** Base UI's className may be a function of state: merges ours with it in either form. */
export const withClass =
  <S,>(base: string, className: string | ((state: S) => string | undefined) | undefined) =>
  (state: S) =>
    cn(base, typeof className === "function" ? className(state) : className);

/** Composes two refs, keeping React 19 ref cleanups. */
export function useComposedRefs<T>(a: React.Ref<T> | undefined, b: React.Ref<T> | undefined): React.RefCallback<T> {
  return React.useCallback(
    (node: T | null) => {
      const release = [assignRef(a, node), assignRef(b, node)];
      return () => release.forEach((f) => f());
    },
    [a, b],
  );
}

/**
 * Runs each step on its own animation frame, in order (the first on the next frame), and returns one
 * cancel that stops whichever frame is pending. A no-op step just waits a frame: frames(set pre, wait,
 * go) lets the browser paint the start state before the transition begins.
 */
export function frames(...steps: (() => void)[]): () => void {
  let id = 0;
  let i = 0;
  const tick = () => {
    steps[i++]?.();
    if (i < steps.length) id = requestAnimationFrame(tick);
  };
  id = requestAnimationFrame(tick);
  return () => cancelAnimationFrame(id);
}
export const wait = () => {};

let idSeq = 0;
/** A unique id for something the user creates (a milestone, a note): random where the browser can, else a counter. */
export const newId = () => (typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID() : `id-${Date.now()}-${++idSeq}`);

/**
 * True while an input method (Japanese, Chinese, Korean…) is composing: Enter, Tab and delimiters
 * then belong to the composition, not to the component. keyCode 229 covers Safari's late flag.
 */
export function composing(e: React.KeyboardEvent | KeyboardEvent) {
  const native = "nativeEvent" in e ? e.nativeEvent : e;
  return native.isComposing || native.keyCode === 229;
}

const hotkeyOwners = new Map<string, number[]>();
let hotkeySeq = 0;
/**
 * A page-wide shortcut ("/" or "mod+k", mod being ⌘ or Ctrl) with a single owner: when several
 * components claim the same key, only the one mounted last answers, so one press never opens two.
 * A plain key is ignored while typing in a field.
 */
export function useHotkey(combo: string | undefined, run: () => void) {
  const latest = useLatest(run);
  React.useEffect(() => {
    if (!combo) return;
    const me = ++hotkeySeq;
    const stack = hotkeyOwners.get(combo) ?? [];
    stack.push(me);
    hotkeyOwners.set(combo, stack);
    const mod = combo.startsWith("mod+");
    const key = (mod ? combo.slice(4) : combo).toLowerCase();
    const onKey = (e: KeyboardEvent) => {
      if (hotkeyOwners.get(combo)?.at(-1) !== me || e.key.toLowerCase() !== key) return;
      if (mod ? !(e.metaKey || e.ctrlKey) : e.metaKey || e.ctrlKey || e.altKey) return;
      if (!mod && (e.target as HTMLElement | null)?.closest("input, textarea, select, [contenteditable=true]")) return;
      e.preventDefault();
      latest.current();
    };
    window.addEventListener("keydown", onKey);
    return () => {
      window.removeEventListener("keydown", onKey);
      const s = hotkeyOwners.get(combo) ?? [];
      s.splice(s.indexOf(me), 1);
    };
  }, [combo, latest]);
}

/** Keeps the latest value in a ref, for callbacks read inside timers and animation frames. */
export function useLatest<T>(value: T) {
  const ref = React.useRef(value);
  React.useLayoutEffect(() => {
    ref.current = value;
  });
  return ref;
}

/*
 * Where Notchset overlays (menus, popovers, tooltips) portal to. Unset, document.body, as shadcn's
 * do. Provide an element to keep them inside a scoped theme: a preview, a widget, a shadow root.
 */
export const NotchsetPortalContext = React.createContext<HTMLElement | null>(null);
export function useNotchsetPortal(): HTMLElement | undefined {
  return React.useContext(NotchsetPortalContext) ?? undefined;
}

const subscribeNothing = () => () => {};

/**
 * A scope that turns motion or sound off for everything inside it, popups included. A plain
 * data-motion="off" wrapper can't reach a menu that portals to the body; this one also gives its
 * overlays a portal host carrying the same preferences (inside any outer scope's host), so motionOff
 * and the cues see them there too.
 */
export function NotchsetScope({ motion, sound, children, ...props }: React.ComponentProps<"div"> & { motion?: "off"; sound?: "off" }) {
  const outer = React.useContext(NotchsetPortalContext);
  const [host, setHost] = React.useState<HTMLElement | null>(null);
  const client = React.useSyncExternalStore(subscribeNothing, () => true, () => false);
  return (
    <div data-motion={motion} data-sound={sound} {...props}>
      <NotchsetPortalContext value={host ?? outer}>{children}</NotchsetPortalContext>
      {client && createPortal(<div ref={setHost} data-slot="notchset-scope-host" data-motion={motion} data-sound={sound} />, outer ?? document.body)}
    </div>
  );
}

export { NOTCHSET_ROOT, OWN_SOUND } from "@/lib/beautiful-ui/notchset/root";

// ---------------------------------------------------------------------------------------------
// Parts
// ---------------------------------------------------------------------------------------------

export type NodeState = "off" | "on" | "live" | "signal";

/** The node: a 9×9 ring whose dot blooms on (`on`), blinks (`live`) or turns signal. */
function Node({ state = "off", delay, className, style, ...props }: Omit<React.ComponentProps<"svg">, "children"> & { state?: NodeState; delay?: number }) {
  return (
    <svg
      aria-hidden
      data-slot="indicator"
      data-state={state}
      width="9"
      height="9"
      viewBox="0 0 9 9"
      className={cn(`notchset-node`, className)}
      style={delay ? ({ "--notchset-node-delay": `${delay}ms`, ...style } as React.CSSProperties) : style}
      {...props}
    >
      <circle data-slot="indicator-ring" cx="4.5" cy="4.5" r="3.25" fill="none" strokeWidth="1" />
      <circle data-slot="indicator-dot" cx="4.5" cy="4.5" />
    </svg>
  );
}

/** A small solid round mark (the node where a leader meets a popup, a pointer): SVG, round at every DPR. */
function Dot({ size = 7, className, style }: { size?: number; className?: string; style?: React.CSSProperties }) {
  return (
    <svg aria-hidden width={size} height={size} viewBox={`0 0 ${size} ${size}`} className={cn("pointer-events-none absolute overflow-visible", className)} style={style}>
      <circle cx={size / 2} cy={size / 2} r={size / 2} fill="currentColor" />
    </svg>
  );
}

/** The legend: a mono label above a control, with an optional node (or any trailing reading). */
function Legend({ label, node, children, className, ...props }: React.ComponentProps<"div"> & { label?: React.ReactNode; node?: NodeState }) {
  return (
    <div data-slot="legend" className={cn(`notchset-legend`, className)} {...props}>
      <span data-slot="legend-label">{label}</span>
      {(children != null || node) && (
        <span data-slot="legend-reading" className="flex items-center gap-2">
          {children}
          {node && <Node state={node} />}
        </span>
      )}
    </div>
  );
}

/** A key on its plate: the plate is an offset frame behind the child; `--notchset-plate-color` tints it. */
function Plated({ className, children, ...props }: React.ComponentProps<"span">) {
  return (
    <span data-slot="plated" className={cn("relative inline-flex", className)} {...props}>
      <span aria-hidden data-slot="plate" className={`notchset-plate`} />
      {children}
    </span>
  );
}

/**
 * The success check. Mounted, it traces itself in over --notchset-check (instant under reduced
 * motion); pass `drawn` to drive the trace yourself.
 */
function Check({ drawn, size = 16 }: { drawn?: boolean; size?: number }) {
  return (
    <svg aria-hidden data-slot="check" width={size} height={size} viewBox="0 0 24 24">
      <path
        d="M4 12.5 L9.5 18 L20 6"
        fill="none"
        stroke="currentColor"
        strokeWidth={1.75}
        strokeLinecap="square"
        pathLength={1}
        strokeDasharray={1}
        className={drawn === undefined ? `notchset-check-draw` : undefined}
        style={drawn === undefined ? undefined : { strokeDashoffset: drawn ? 0 : 1, transition: "stroke-dashoffset var(--notchset-check) var(--notchset-ease-travel)" }}
      />
    </svg>
  );
}

/** The scanner: five 1px ticks fading in turn while something works (static, centre lit, when motion is off). */
function Scanner({ height = 12 }: { height?: number }) {
  return (
    <span aria-hidden data-slot="scanner" className={cn(`notchset-scanner`, "inline-flex items-end gap-[2px]")} style={{ height }}>
      {[0.82, 0.66, 1, 0.66, 0.82].map((h, i) => (
        <span key={i} className="w-px bg-current" style={{ height: height * h, animationDelay: `${i * 140 - 700}ms` }} />
      ))}
    </span>
  );
}

// ---------------------------------------------------------------------------------------------
// Glyph flip: each character cycles through glyphs and lands at 110 + i·14ms, left to right
// ---------------------------------------------------------------------------------------------

const GLYPHS = "ABCDEFGHJKLMNPRSTUVWXYZ0123456789#/+=";
const STILL = new Set([" ", "·", "/", ".", ":"]);
const FLIP_CHARS = 24;

export function scramble(text: string, elapsed: number) {
  let out = "";
  for (let i = 0; i < text.length; i++) {
    const ch = text[i]!;
    // Characters past the 24th land with the 24th, so a long label flips as briefly as a short one.
    out += STILL.has(ch) || elapsed >= 110 + Math.min(i, FLIP_CHARS) * 14 ? ch : GLYPHS[(Math.floor(elapsed / 36) * 5 + i * 11) % GLYPHS.length];
  }
  return out;
}

/**
 * The text to show for `text`: when it changes, a few frames of glyphs that land left to right.
 * Runs on requestAnimationFrame only while a flip is active; the settled text is never state. Off
 * under reduced motion, inside data-motion="off" (pass the element) or with `off`.
 */
export function useGlyphFlip(text: string, { off = false, el }: { off?: boolean; el?: React.RefObject<Element | null> } = {}) {
  const [frame, setFrame] = React.useState<{ for: string; shown: string } | null>(null);
  const first = React.useRef(true);
  React.useEffect(() => {
    if (first.current) {
      first.current = false;
      return;
    }
    if (off || motionOff(el?.current)) return;
    let raf = 0;
    const t0 = performance.now();
    const end = 110 + Math.min(text.length, FLIP_CHARS) * 14 + 40;
    const step = (now: number) => {
      const elapsed = now - t0;
      if (elapsed >= end) {
        setFrame(null);
        return;
      }
      setFrame({ for: text, shown: scramble(text, elapsed) });
      raf = requestAnimationFrame(step);
    };
    raf = requestAnimationFrame(step);
    return () => cancelAnimationFrame(raf);
  }, [text, off, el]);
  // Turned off mid-flip, the label shows its text at once (the cancelled frame never lingers).
  return !off && frame && frame.for === text ? frame.shown : text;
}

/** A label that flips when its text changes; screen readers read the final text only. */
function FlipText({ children, off, className, ref: refProp, ...props }: Omit<React.ComponentProps<"span">, "children"> & { children: string; off?: boolean }) {
  const ref = React.useRef<HTMLSpanElement>(null);
  const refs = useComposedRefs<HTMLSpanElement>(refProp, ref);
  const shown = useGlyphFlip(children, { off, el: ref });
  return (
    <span {...props} ref={refs} data-slot="flip-text" className={cn("relative whitespace-nowrap", className)}>
      <span aria-hidden>{shown}</span>
      <span className="sr-only">{children}</span>
    </span>
  );
}

// ---------------------------------------------------------------------------------------------
// Sound: Notchset components announce cues; the page's beautiful-ui-sound layer (opt-in) plays them.
// ---------------------------------------------------------------------------------------------

/** The Notchset cues, in the shared sound layer's names (played in the mechanical voice). */
export const NOTCHSET_CUES = { tap: "tap", latch: "lock", signal: "destructive", confirm: "halt", done: "success", tick: "tick" } as const;
export type NotchsetCue = keyof typeof NOTCHSET_CUES;

export function playCue(el: Element | null, cue: NotchsetCue) {
  if (!el || typeof CustomEvent === "undefined" || el.closest('[data-sound="off"]')) return;
  el.dispatchEvent(new CustomEvent("beautiful-ui:sound", { bubbles: true, detail: { cue: NOTCHSET_CUES[cue] } }));
}

// ---------------------------------------------------------------------------------------------
// Shortcuts: "⌘↵" → "Meta+Enter Control+Enter" (aria-keyshortcuts)
// ---------------------------------------------------------------------------------------------

const KEY_NAMES: Record<string, string> = { "⌘": "Meta", "⌃": "Control", "⌥": "Alt", "⇧": "Shift", "↵": "Enter", "⏎": "Enter", "⎋": "Escape", "⌫": "Backspace", "⇥": "Tab", "␣": "Space" };

export function kbdToShortcut(kbd: string | undefined): string | undefined {
  if (!kbd) return undefined;
  const parts = [...kbd.replace(/\s+/g, "")].map((c) => KEY_NAMES[c] ?? c.toUpperCase());
  if (!parts.length) return undefined;
  const combo = parts.join("+");
  // ⌘ on a Mac is Ctrl elsewhere: announce both.
  return combo.includes("Meta") ? `${combo} ${combo.replace("Meta", "Control")}` : combo;
}

/**
 * Digits that roll: each digit is a 0–9 strip; the ones digit moves first and each digit to its left
 * 40ms later, counting digits only (620ms, a small overshoot). `delay` offsets the whole text. Other
 * characters (",", "$", "%", letters) sit still. Screen readers get the plain text. The one
 * implementation behind RollingNumber and the calendar's RollingLabel.
 */
export function DigitRoll({ text, height, delay = 0, className }: { text: string; height: number; delay?: number; className?: string }) {
  const chars = [...text];
  let k = 0;
  const order = chars.map((_, i) => (/\d/.test(chars[chars.length - 1 - i]!) ? k++ : 0)).reverse();
  return (
    <span className={cn("relative inline-flex flex-none overflow-hidden tabular-nums", className)} style={{ height, lineHeight: `${height}px` }}>
      <span className="sr-only">{text}</span>
      <span aria-hidden className="flex">
        {chars.map((d, i) =>
          /\d/.test(d) ? (
            <span
              key={chars.length - i}
              className="flex flex-col transition-transform duration-[620ms] ease-[cubic-bezier(.34,1.15,.5,1)] motion-reduce:transition-none"
              style={{ transform: `translateY(${-Number(d) * height}px)`, transitionDelay: `${delay + order[i]! * 40}ms` }}
            >
              {Array.from({ length: 10 }, (_, n) => (
                <span key={n} style={{ height }}>
                  {n}
                </span>
              ))}
            </span>
          ) : (
            <span key={`s${chars.length - i}`}>{d}</span>
          ),
        )}
      </span>
    </span>
  );
}

/** A number that rolls (DigitRoll at the readout's own size). `delay` offsets it (rows 60ms apart). */
function RollingNumber({ value, height = 32, delay = 0, className }: { value: string | number; height?: number; delay?: number; className?: string }) {
  return <DigitRoll text={String(value)} height={height} delay={delay} {...(className ? { className } : {})} />;
}

export { Check, Dot, FlipText, Legend, Node, Plated, RollingNumber, Scanner };
```

### lib/beautiful-ui/notchset/root.ts

```tsx
/*
 * Notchset's root attributes, server-safe (no client directive), so server components can spread
 * them too. Every Notchset root (and portalled popup) carries data-notchset (the motion policy's
 * scope), plays its own cues in the mechanical voice, and keeps the page's click layer out.
 */
export const NOTCHSET_ROOT = { "data-notchset": "", "data-sound": "none", "data-sound-voice": "analogue" } as const;

/** On every interactive element: it plays its own cues, so the page's click layer adds no tap. */
export const OWN_SOUND = { "data-sound": "none" } as const;
```

The notchset foundation (the tokens listed above, keyframes and motion levels) installs once with the first component; its CSS is public at https://beautiful-ui.dev/r/notchset-foundation.json.