@hyperframes/studio 0.7.107 → 0.7.108

package/src/components/editor/propertyPanelFxPresetRun.tsx

@@ -0,0 +1,215 @@
+/**
+ * One preset's bracket in the rack: its own header, on/off switch, amount lane
+ * and the rows it wraps — or, for a run with no preset, just the rows.
+ *
+ * Split out of `propertyPanelFxSection.tsx`, whose `runs.map()` callback this
+ * body used to be — one card per run, hand-built nodes included as runs with no
+ * preset attached.
+ */
+
+import type {
+  HfAudioFxNode,
+  HfAudioFxParam,
+  HfAudioFxParamValues,
+} from "@hyperframes/core/audio-fx";
+import { getAudioFxPreset } from "@hyperframes/core/audio-fx-presets";
+import { FxParamRow } from "./propertyPanelFxControls.js";
+import { fxPresetBackground, fxPresetStyle } from "./propertyPanelFxPresetStyle.js";
+import { FxNodeRow } from "./propertyPanelFxNodeRow.js";
+
+/**
+ * The one control over a whole preset: how much of it is applied.
+ *
+ * Not in the effect registry — a preset is not an effect — so the row is
+ * fabricated the same way the derived one-knob control is, and rendered by the
+ * ordinary controls.
+ */
+const PRESET_AMOUNT_PARAM: HfAudioFxParam = {
+  kind: "number",
+  key: "amount",
+  label: "Amount",
+  unit: "",
+  min: 0,
+  max: 1,
+  step: 0.01,
+  default: 1,
+  hint: "How much of this preset is applied. Automate it to bring the whole preset in or out over time.",
+};
+
+export interface FxPresetRunProps {
+  run: { preset?: string; items: { node: HfAudioFxNode; i: number }[] };
+  /** The number each row wears, counted over the whole rack. */
+  positions: ReadonlyMap<number, number>;
+  /** So the last row in the WHOLE chain knows it cannot move further down. */
+  totalNodes: number;
+  automatedTargets?: ReadonlySet<string>;
+  liveAutomationValues?: ReadonlyMap<string, number>;
+  onAutomateParam?(nodeId: string, paramKey: string): void;
+  onRemoveParamAutomation?(nodeId: string, paramKey: string): void;
+  openNode: number | null;
+  onToggleOpenNode(index: number): void;
+  disabled?: boolean;
+  onUpdateNode(index: number, patch: Partial<HfAudioFxNode>): void;
+  onMoveNode(index: number, delta: number): void;
+  onRemoveNode(index: number): void;
+  onPreviewNode(index: number, params: HfAudioFxParamValues): void;
+  /** What the track reads as, carried onto each row's own telemetry events. */
+  trackKind?: string;
+  /** Whether this run's card is folded shut. Meaningless when there is no preset. */
+  collapsed: boolean;
+  onToggleCollapse(): void;
+  /** How much of the preset is applied, 0..1 — the switch and the lane read the same value. */
+  amount: number;
+  onSetAmount(amount: number, persist?: boolean): void;
+  onRemoveRun(): void;
+  automated: boolean;
+  onAutomate?(): void;
+  onRemoveAutomation?(): void;
+}
+
+/** One run: a preset's bracket around its nodes, or a bare hand-built node. */
+export function FxPresetRun({
+  run,
+  positions,
+  totalNodes,
+  automatedTargets,
+  liveAutomationValues,
+  onAutomateParam,
+  onRemoveParamAutomation,
+  openNode,
+  onToggleOpenNode,
+  disabled,
+  onUpdateNode,
+  onMoveNode,
+  onRemoveNode,
+  onPreviewNode,
+  trackKind,
+  collapsed,
+  onToggleCollapse,
+  amount,
+  onSetAmount,
+  onRemoveRun,
+  automated,
+  onAutomate,
+  onRemoveAutomation,
+}: FxPresetRunProps) {
+  const rows = run.items.map(({ node, i }) => (
+    <FxNodeRow
+      // Keyed by id, as the carve module's list above already is. On
+      // `${type}-${index}` two effects of the same type keep their keys through
+      // a reorder, so React reuses each row where it stands — and the controls
+      // hold real state (a half-typed number, an in-flight drag), which then
+      // lands on whichever effect moved into that slot.
+      key={node.id ?? `${node.type}-${i}`}
+      node={node}
+      index={i}
+      position={positions.get(i)}
+      automatedTargets={automatedTargets}
+      liveAutomationValues={liveAutomationValues}
+      onAutomateParam={onAutomateParam}
+      onRemoveParamAutomation={onRemoveParamAutomation}
+      open={openNode === i}
+      last={i === totalNodes - 1}
+      disabled={disabled}
+      onToggleOpen={() => onToggleOpenNode(i)}
+      onUpdate={onUpdateNode}
+      onMove={onMoveNode}
+      onRemove={onRemoveNode}
+      onPreview={onPreviewNode}
+      trackKind={trackKind}
+    />
+  ));
+
+  const preset = run.preset ? getAudioFxPreset(run.preset) : null;
+  if (!preset) return rows;
+
+  // On unless every node in it is bypassed: one switched back on means the
+  // preset is doing something, and the switch has to offer to stop it rather
+  // than claiming it has already stopped.
+  const runOn = amount > 0;
+  const style = fxPresetStyle(run.preset ?? "");
+  const background = fxPresetBackground(run.preset ?? "");
+
+  return (
+    <div
+      className="hf-fx-preset-run space-y-1 rounded-[4px] border border-l-2 border-dashed border-panel-border-input p-1"
+      data-fx-preset={run.preset}
+      data-collapsed={collapsed ? "" : undefined}
+      // The bracket's edge carries the preset's own colour, the way a module's
+      // carries its family's — and the wash behind it is the same hue taken to
+      // near-black, so a rack with three presets in it reads as three regions
+      // rather than one long list.
+      style={{
+        borderLeftColor: style.color,
+        ...(background ? { backgroundColor: background } : {}),
+      }}
+    >
+      <div className="hf-fx-preset-run-head flex min-h-6 items-center gap-1 px-0.5">
+        <button
+          type="button"
+          className={`hf-fx-preset-run-label min-w-0 flex-1 truncate text-left leading-tight hover:opacity-80 ${style.type}`}
+          // The face and the colour are data, not classes: a Tailwind class
+          // cannot name a font stack the config does not know, and adding eight
+          // to the config to style one panel would put them in every
+          // autocomplete in the studio.
+          style={{
+            color: style.color,
+            ...(style.family ? { fontFamily: style.family } : {}),
+          }}
+          aria-expanded={!collapsed}
+          title={
+            collapsed ? `Show what ${preset.label} contains` : `Hide ${preset.label}'s effects`
+          }
+          onClick={onToggleCollapse}
+        >
+          <span className="hf-fx-preset-run-caret pr-1 font-mono opacity-60" aria-hidden="true">
+            {collapsed ? "▸" : "▾"}
+          </span>
+          {preset.label}
+          {/* Collapsed, the count is what says the preset is still a chain
+              rather than one opaque effect. */}
+          {collapsed ? (
+            <span className="hf-fx-preset-run-count pl-1.5 font-mono text-[9px] opacity-60">
+              {run.items.length}
+            </span>
+          ) : null}
+        </button>
+        {/* The whole preset, on or off. Partly-bypassed reads as off, because
+            "some of it is running" is not a state an author set — it is one
+            they arrived at, and the switch is how they get back out of it. */}
+        <button
+          type="button"
+          className="hf-fx-preset-run-toggle rounded-[3px] border border-panel-border-input px-1.5 py-0.5 font-mono text-[9px] text-panel-text-2 hover:text-panel-text-0 disabled:opacity-40"
+          aria-pressed={runOn}
+          title={runOn ? `Switch ${preset.label} off` : `Switch ${preset.label} back on`}
+          disabled={disabled}
+          onClick={() => onSetAmount(runOn ? 0 : 1)}
+        >
+          {runOn ? "On" : "Off"}
+        </button>
+        <button
+          type="button"
+          className="hf-fx-preset-run-remove px-1 font-mono text-[11px] text-panel-text-2 hover:text-red-400 disabled:opacity-40"
+          title={`Remove ${preset.label}`}
+          disabled={disabled}
+          onClick={onRemoveRun}
+        >
+          &times;
+        </button>
+      </div>
+      {/* The same value the switch sets, so an author can put the preset half
+          in — and the lane below ramps it continuously. */}
+      <FxParamRow
+        param={PRESET_AMOUNT_PARAM}
+        value={amount}
+        disabled={disabled || automated}
+        automated={automated}
+        onChange={(_k, v) => onSetAmount(Number(v), false)}
+        onCommit={(_k, v) => onSetAmount(Number(v))}
+        onAutomate={onAutomate}
+        onRemoveAutomation={onRemoveAutomation}
+      />
+      {collapsed ? null : rows}
+    </div>
+  );
+}

package/src/components/editor/propertyPanelFxPresetStyle.test.ts

@@ -0,0 +1,142 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import { HF_AUDIO_FX_PRESETS } from "@hyperframes/core/audio-fx-presets";
+import {
+  FX_PRESET_STYLE,
+  FX_PRESET_STYLE_DEFAULT,
+  fxPresetBackground,
+  fxPresetStyle,
+  fxTintWash,
+} from "./propertyPanelFxPresetStyle.js";
+
+describe("per-preset title treatments", () => {
+  it("styles every preset the catalogue ships", () => {
+    // An unstyled preset is not broken — it falls back — but it is a row that
+    // silently opts out of the design, which nobody would notice.
+    const missing = HF_AUDIO_FX_PRESETS.filter((p) => !FX_PRESET_STYLE[p.id]).map((p) => p.id);
+    expect(missing).toEqual([]);
+  });
+
+  it("styles no preset the catalogue does not", () => {
+    // Dead entries for renamed or removed presets read as coverage.
+    const shipped = new Set(HF_AUDIO_FX_PRESETS.map((p) => p.id));
+    expect(Object.keys(FX_PRESET_STYLE).filter((id) => !shipped.has(id))).toEqual([]);
+  });
+
+  it("gives the character presets treatments that differ from each other", () => {
+    // The whole point: a preset is a character, and Telephone should not look
+    // like Megaphone. The corrective families may legitimately share a look.
+    const character = HF_AUDIO_FX_PRESETS.filter((p) => p.family === "character");
+    const looks = new Set(
+      character.map((p) => `${fxPresetStyle(p.id).type}|${fxPresetStyle(p.id).family}`),
+    );
+    expect(looks.size).toBe(character.length);
+  });
+
+  it("names a real font stack, ending in a generic the browser always has", () => {
+    // The studio has no webfont pipeline, so these are system faces — and a
+    // machine without the named one has to land somewhere deliberate rather
+    // than on the browser's default serif.
+    const generic = /(sans-serif|serif|monospace|fantasy|cursive|ui-monospace)\s*$/;
+    for (const [id, style] of Object.entries(FX_PRESET_STYLE)) {
+      expect(style.family, `${id} names no face`).toBeTruthy();
+      expect(style.family, `${id} has no generic fallback`).toMatch(generic);
+      // More than one option, or it is a single point of failure.
+      expect((style.family ?? "").split(",").length, `${id} has no fallback chain`).toBeGreaterThan(
+        2,
+      );
+    }
+  });
+
+  it("sets a title size on every preset, and keeps it legible", () => {
+    // The panel's own rows are 10px; a title at that size is not a title. The
+    // ceiling is what still fits the bracket without wrapping.
+    for (const [id, style] of Object.entries(FX_PRESET_STYLE)) {
+      const size = /text-\[(\d+)px\]/.exec(style.type);
+      expect(size, `${id} sets no title size`).toBeTruthy();
+      const px = Number(size?.[1]);
+      expect(px, `${id} is too small to read as a title`).toBeGreaterThanOrEqual(12);
+      expect(px, `${id} is too large for the bracket`).toBeLessThanOrEqual(18);
+    }
+  });
+
+  it("keeps every colour vibrant, and light enough to read on the panel", () => {
+    // The rack sits on #0C0C0E. A title has to carry real colour to be worth
+    // having, and still clear contrast against near-black.
+    for (const [id, style] of Object.entries(FX_PRESET_STYLE)) {
+      const match = /hsl\(\s*(\d+),\s*(\d+)%,\s*(\d+)%\s*\)/.exec(style.color);
+      expect(match, `${id} is not a plain hsl() colour`).toBeTruthy();
+      const saturation = Number(match?.[1 + 1]);
+      const lightness = Number(match?.[3]);
+      expect(saturation, `${id} is too washed out to read as a colour`).toBeGreaterThanOrEqual(60);
+      expect(lightness, `${id} is too dark against the panel`).toBeGreaterThanOrEqual(58);
+      expect(lightness, `${id} is so light the hue disappears`).toBeLessThanOrEqual(78);
+    }
+  });
+
+  it("keeps the title hues clear of the accent, which means something else", () => {
+    // The panel spends #3CE6AC (hue 160) on "automated" and "playing". A title
+    // sitting on that hue reads as a status the preset does not have.
+    for (const [id, style] of Object.entries(FX_PRESET_STYLE)) {
+      const hue = Number(/hsl\(\s*(\d+),/.exec(style.color)?.[1]);
+      const distance = Math.min(Math.abs(hue - 160), 360 - Math.abs(hue - 160));
+      expect(distance, `${id} sits on the accent's hue`).toBeGreaterThan(20);
+    }
+  });
+
+  it("backs each preset with its own hue, dark enough to sit under the panel", () => {
+    // Derived from the title rather than picked, so a background cannot drift
+    // away from the title it belongs to.
+    const seen = new Set<string>();
+    for (const [id, style] of Object.entries(FX_PRESET_STYLE)) {
+      const bg = fxPresetBackground(id);
+      expect(bg, `${id} has no background`).toBeTruthy();
+      const titleHue = /hsl\(\s*(\d+),/.exec(style.color)?.[1];
+      expect(bg, `${id}'s background is a different hue from its title`).toContain(
+        `hsl(${titleHue},`,
+      );
+      const lightness = Number(/,\s*(\d+)%\s*\)/.exec(bg ?? "")?.[1]);
+      expect(lightness, `${id}'s background would fight the controls on it`).toBeLessThanOrEqual(
+        16,
+      );
+      seen.add(bg ?? "");
+    }
+    // Presets that share a title colour share a background — the repair family
+    // is deliberately uniform — but the character ones must not.
+    const character = HF_AUDIO_FX_PRESETS.filter((p) => p.family === "character");
+    expect(new Set(character.map((p) => fxPresetBackground(p.id))).size).toBe(character.length);
+  });
+
+  it("has no background for a preset it does not know", () => {
+    expect(fxPresetBackground("not-a-preset")).toBeNull();
+  });
+
+  it("falls back rather than failing for a preset it does not know", () => {
+    expect(fxPresetStyle("not-a-preset")).toBe(FX_PRESET_STYLE_DEFAULT);
+  });
+});
+
+/**
+ * The wash is shared with the smart modules, which do not have preset entries
+ * to look up — the carve derives its colour from `fxFamilyTint`, and that one
+ * COMPUTES its lightness, so it emits `62.0%` where every preset colour is a
+ * whole number. An integer-only pattern reads those as no match and returns
+ * null, which renders as no wash at all rather than as an error.
+ */
+describe("the tint wash", () => {
+  it("reads a computed colour, decimals and all", () => {
+    expect(fxTintWash("hsl(95, 32%, 62.0%)")).toBe("hsl(95, 22%, 11%)");
+    expect(fxTintWash("hsl(95, 32.5%, 76%)")).toBe("hsl(95, 22%, 11%)");
+  });
+
+  it("keeps the hue and takes everything else to near-black", () => {
+    // Same hue in, same hue out: the wash cannot clash with the title it sits
+    // behind, because it IS the title's hue.
+    expect(fxTintWash("hsl(288, 85%, 72%)")).toBe("hsl(288, 22%, 11%)");
+  });
+
+  it("declines a colour it cannot read rather than guessing", () => {
+    expect(fxTintWash("#52525B")).toBeNull();
+    expect(fxTintWash("rebeccapurple")).toBeNull();
+  });
+});

package/src/components/editor/propertyPanelFxPresetStyle.ts

@@ -0,0 +1,216 @@
+/**
+ * A title treatment per preset — the label as a small piece of design rather
+ * than eighteen rows of the same condensed caps.
+ *
+ * The rack already letters by FAMILY (`propertyPanelFxFamily.ts`), which answers
+ * "what kind of thing is this". This answers a different question: a preset is a
+ * character, and the point of Telephone or Megaphone is that you know what it
+ * sounds like before you play it. Type can carry that — a bullhorn's name should
+ * look shouted, a tape's should look worn.
+ *
+ * Deliberately NOT a per-preset colour free-for-all. Each hue sits in the same
+ * narrow lightness band as the family tints so nothing reads as a status colour,
+ * and the panel already spends saturation on "automated" and "bypassed".
+ *
+ * A preset with no entry falls back to the neutral treatment, so the catalogue
+ * can grow without this file — an unstyled preset looks plain, not broken.
+ */
+
+export interface FxPresetStyle {
+  /** Tailwind classes for the title: weight, case, tracking, size. */
+  type: string;
+  /** The title's colour, and the bracket's left edge. */
+  color: string;
+  /**
+   * A real font stack, when the character wants one.
+   *
+   * Tailwind ships three generic families, and a set of presets styled only
+   * with those ends up variations of the same two faces. These are system
+   * faces with a documented fallback chain: the studio has no webfont
+   * pipeline, and the Google Fonts cache under `~/.cache/hyperframes` belongs
+   * to the CLI's composition build — reaching into it from the panel would be
+   * inventing a second one.
+   *
+   * Every stack ends in a generic keyword, so a machine without the named face
+   * still lands somewhere deliberate.
+   */
+  family?: string;
+}
+
+/** Faces that ship with macOS and/or Windows, grouped by what they read as. */
+const FACE = {
+  /** Narrow industrial caps — signage, stencils, equipment panels. */
+  condensed: '"Haettenschweiler", "Arial Narrow", Impact, sans-serif',
+  /** Geometric and mechanical; reads as a machine rather than a voice. */
+  geometric: '"Futura", "Century Gothic", "Avenir Next", sans-serif',
+  /** Typewriter — struck, worn, slightly irregular. */
+  typewriter: '"American Typewriter", "Courier New", Courier, monospace',
+  /** High-contrast editorial serif; broadcast and print authority. */
+  editorial: '"Didot", "Bodoni 72", "Playfair Display", Georgia, serif',
+  /** Old-style serif with real warmth — books, not headlines. */
+  bookish: '"Iowan Old Style", "Palatino Linotype", Palatino, Georgia, serif',
+  /** Display face with no restraint at all. Theatrical, and a bit absurd. */
+  theatrical: '"Luminari", "Papyrus", "Comic Sans MS", fantasy',
+  /** Engraved caps — plaques, institutions, things bolted to walls. */
+  engraved: '"Copperplate", "Optima", "Perpetua Titling MT", serif',
+  /** Terminal type: fixed, plain, no personality of its own. */
+  terminal: '"SF Mono", Consolas, Menlo, ui-monospace, monospace',
+} as const;
+
+/** Plain, and what any preset without its own entry gets. */
+export const FX_PRESET_STYLE_DEFAULT: FxPresetStyle = {
+  type: "text-[12px] uppercase tracking-wide",
+  color: "hsl(220, 24%, 72%)",
+  family: FACE.terminal,
+};
+
+export const FX_PRESET_STYLE: Record<string, FxPresetStyle> = {
+  // --- voice: reach for these to sound like yourself, only better -----------
+  // Restrained rather than plain. These are corrective, and a costume would
+  // promise a character they deliberately do not add — but they still get a
+  // face, because "no styling at all" is what every other row in the panel has.
+  "voice-clean": {
+    type: "text-[13px] font-medium tracking-tight",
+    color: "hsl(202, 82%, 66%)",
+    family: FACE.geometric,
+  },
+  "voice-broadcast": {
+    type: "text-[13px] font-bold uppercase tracking-[0.14em]",
+    color: "hsl(214, 84%, 70%)",
+    family: FACE.editorial,
+  },
+  "voice-warm": {
+    type: "text-[14px] italic tracking-normal",
+    color: "hsl(32, 88%, 66%)",
+    family: FACE.bookish,
+  },
+
+  // --- repair: workshop labels. Fixed, plain, nothing decorative ------------
+  "rumble-cut": {
+    type: "text-[12px] uppercase tracking-[0.18em]",
+    color: "hsl(196, 78%, 64%)",
+    family: FACE.terminal,
+  },
+  "room-gate": {
+    type: "text-[12px] uppercase tracking-[0.18em]",
+    color: "hsl(196, 78%, 64%)",
+    family: FACE.terminal,
+  },
+  "boom-tame": {
+    type: "text-[12px] uppercase tracking-[0.18em]",
+    color: "hsl(196, 78%, 64%)",
+    family: FACE.terminal,
+  },
+  "harsh-tame": {
+    type: "text-[12px] uppercase tracking-[0.18em]",
+    color: "hsl(196, 78%, 64%)",
+    family: FACE.terminal,
+  },
+
+  // --- character: the costumes. This is where type does the work ------------
+  // A phone's band is narrow; so is the tracking, on a face with no warmth.
+  telephone: {
+    type: "text-[13px] uppercase tracking-[0.3em]",
+    color: "hsl(186, 85%, 62%)",
+    family: FACE.terminal,
+  },
+  // A dial face: high-contrast serif caps, spaced like printed frequencies.
+  "radio-am": {
+    type: "text-[14px] uppercase tracking-[0.24em]",
+    color: "hsl(42, 92%, 62%)",
+    family: FACE.editorial,
+  },
+  // Shouted through a horn — the heaviest, narrowest thing available, leaning.
+  megaphone: {
+    type: "text-[17px] font-black italic uppercase tracking-tight",
+    color: "hsl(12, 90%, 64%)",
+    family: FACE.condensed,
+  },
+  // Struck on a machine, played back years later.
+  "lofi-tape": {
+    type: "text-[13px] tracking-wide",
+    color: "hsl(28, 72%, 62%)",
+    family: FACE.typewriter,
+  },
+  // Bolted to a wall in a station concourse.
+  "pa-system": {
+    type: "text-[13px] uppercase tracking-[0.26em]",
+    color: "hsl(222, 80%, 70%)",
+    family: FACE.engraved,
+  },
+  // Small, squeezed through a grille, no room for anything but the letters.
+  intercom: {
+    type: "text-[12px] font-bold uppercase tracking-tighter",
+    color: "hsl(96, 68%, 60%)",
+    family: FACE.terminal,
+  },
+  // The name is a joke and the type is in on it.
+  "doofus-worble": {
+    type: "text-[16px] tracking-[0.1em]",
+    color: "hsl(288, 85%, 72%)",
+    family: FACE.theatrical,
+  },
+
+  // --- space: rooms. Light and wide, because that is what space looks like ---
+  "room-tight": {
+    type: "text-[13px] uppercase tracking-[0.2em]",
+    color: "hsl(252, 74%, 72%)",
+    family: FACE.geometric,
+  },
+  "room-natural": {
+    type: "text-[13px] uppercase tracking-[0.26em]",
+    color: "hsl(258, 78%, 72%)",
+    family: FACE.geometric,
+  },
+  // The biggest room gets the widest setting — the word itself opens out.
+  hall: {
+    type: "text-[15px] uppercase tracking-[0.4em]",
+    color: "hsl(246, 84%, 74%)",
+    family: FACE.engraved,
+  },
+  "slap-echo": {
+    type: "text-[13px] uppercase tracking-[0.28em]",
+    color: "hsl(274, 76%, 70%)",
+    family: FACE.geometric,
+  },
+  "dub-throw": {
+    type: "text-[14px] italic tracking-[0.3em]",
+    color: "hsl(312, 78%, 70%)",
+    family: FACE.editorial,
+  },
+};
+
+export function fxPresetStyle(presetId: string): FxPresetStyle {
+  return FX_PRESET_STYLE[presetId] ?? FX_PRESET_STYLE_DEFAULT;
+}
+
+/**
+ * The wash behind a titled module, derived from the colour of its own title.
+ *
+ * Derived rather than picked: twenty hand-chosen pairs is twenty chances for
+ * one to clash with its own title, and a hue rotation cannot. Same hue,
+ * saturation pulled right down and lightness taken to near-black, so the panel
+ * reads as tinted rather than coloured — the rack sits on `#0C0C0E` and
+ * anything with real lightness here would fight every control on top of it.
+ *
+ * Takes a colour rather than an id so the smart modules can use it too: the
+ * carve has a title worth setting and no preset entry to look up. Returns null
+ * for a colour it cannot read, which is how a caller opts out.
+ */
+export function fxTintWash(color: string): string | null {
+  // Decimals allowed: the preset colours are whole numbers, but `fxFamilyTint`
+  // computes its lightness and emits `62.0%`, which an integer-only pattern
+  // silently declines — the module then renders with no wash at all.
+  const num = String.raw`\d+(?:\.\d+)?`;
+  const hsl = new RegExp(`hsl\\(\\s*(${num}),\\s*${num}%,\\s*${num}%\\s*\\)`).exec(color);
+  if (!hsl) return null;
+  // 22% saturation at 11% lightness: present enough to tell two brackets apart
+  // at a glance, dark enough that white body text still clears WCAG AA on it.
+  return `hsl(${hsl[1]}, 22%, 11%)`;
+}
+
+/** The wash behind a preset's bracket. Null when the preset has no character. */
+export function fxPresetBackground(presetId: string): string | null {
+  const style = FX_PRESET_STYLE[presetId];
+  return style ? fxTintWash(style.color) : null;
+}