feat(studio): family lettering, tints, and the rack as a signal path

packages/studio/src/components/editor/propertyPanelFxCarveModule.tsx

@@ -17,6 +17,7 @@ import {
 import { DEFAULT_CARVE, type HfCarveSettings } from "@hyperframes/core/audio-carve";
 import { fxAutomationTarget } from "@hyperframes/core/audio-automation";
 import { FxParamRow } from "./propertyPanelFxControls.js";
+import { FX_FAMILY_TYPE, fxFamilyTint } from "./propertyPanelFxFamily.js";
 // Shared with the timeline's lane labels: a band is named by its frequency in
 // both places, and two formatters would drift.
 import { formatHz } from "../../player/components/automationLaneData";
@@ -201,16 +202,21 @@ export function FxCarveModule({
           : "pick a voice";
   return (
     <div
-      className={`hf-fx-node hf-fx-carve-module hf-fx-carve rounded-[4px] border border-panel-border-input${
+      className={`hf-fx-node hf-fx-carve-module hf-fx-carve rounded-[4px] border border-l-2 border-panel-border-input${
         on ? "" : " opacity-50"
       }`}
       data-fx-node="carve"
+      data-fx-family="smart"
+      // Smart, like the Tone EQ and the leveller: it measures the audio and
+      // writes its own settings, and what it shows is a readout of what it
+      // decided rather than controls the author set.
+      style={{ borderLeftColor: fxFamilyTint({ type: "carve", fromCarve: true }) }}
       data-carve-enabled={on ? "" : undefined}
     >
       <div className="hf-fx-node-head flex min-h-7 items-center gap-1 px-1.5">
         <button
           type="button"
-          className="hf-fx-node-name min-w-0 flex-1 truncate text-left text-[11px] font-semibold text-panel-text-1 hover:text-panel-text-0"
+          className={`hf-fx-node-name min-w-0 flex-1 truncate text-left text-[11px] text-panel-text-1 hover:text-panel-text-0 ${FX_FAMILY_TYPE.smart}`}
           aria-expanded={open}
           onClick={onToggleOpen}
         >

packages/studio/src/components/editor/propertyPanelFxEqModule.tsx

@@ -13,6 +13,7 @@ import {
   HF_AUDIO_EQ_RANGE_DB,
   type HfAudioEqBand,
 } from "@hyperframes/core/audio-fx-eq";
+import { FX_FAMILY_TYPE, fxFamilyTint } from "./propertyPanelFxFamily.js";
 
 export interface FxEqModuleProps {
   eqId: string;
@@ -137,13 +138,17 @@ export function FxEqModule({
 
   return (
     <div
-      className="hf-fx-node hf-fx-eq-module rounded-[4px] border border-panel-border-input"
+      className="hf-fx-node hf-fx-eq-module rounded-[4px] border border-l-2 border-panel-border-input"
       data-fx-node="eq"
+      data-fx-family="smart"
+      // Smart, with the carve and the leveller: three bands the author sets by
+      // ear on a control surface, not three filters they configured.
+      style={{ borderLeftColor: fxFamilyTint({ type: "eq", fromEq: "eq" }) }}
     >
       <div className="hf-fx-node-head flex items-center gap-1.5 px-1.5 py-1">
         <button
           type="button"
-          className="hf-fx-node-name flex-1 text-left text-[11px] text-panel-text-0"
+          className={`hf-fx-node-name flex-1 text-left text-[11px] text-panel-text-0 ${FX_FAMILY_TYPE.smart}`}
           aria-expanded={open}
           onClick={onToggleOpen}
         >

packages/studio/src/components/editor/propertyPanelFxFamily.ts

@@ -0,0 +1,83 @@
+/**
+ * Telling module families apart before the word registers.
+ *
+ * A rack of eight modules is eight lines of text, and reading it top to bottom
+ * means reading eight names. Lettering each family differently means an author
+ * knows what KIND of module they are looking at with the label out of focus —
+ * the shape of the line carries it, and the word only confirms.
+ *
+ * Two faces of type, as budgeted in `plans/audio-fx-ux/README.md`: the sans
+ * carries four families apart by weight, case and tracking, and the serif is
+ * spent on the single family that behaves differently from all of them.
+ * Non-linear is the only generative one — it invents signal rather than
+ * measuring or shaping what is there — so it should not look like the others.
+ *
+ * Alongside it, a tint step per module WITHIN its family, derived from position
+ * in the registry rather than assigned by hand: two filters read as two
+ * different modules without reading as two different families, and adding an
+ * effect upstream never re-colours its siblings.
+ */
+
+import { HF_AUDIO_FX, type HfAudioFxNode } from "@hyperframes/core/audio-fx";
+
+export type FxFamily = "filter" | "dynamics" | "nonlinear" | "time" | "smart";
+
+/**
+ * How each family letters.
+ *
+ * `smart` is not a registry group. It is the measuring modules — the carve, the
+ * Tone EQ, the leveller — which analyse the audio and write their own settings.
+ * Monospace because that is what a readout looks like, and what they show IS a
+ * readout: numbers something else decided.
+ */
+export const FX_FAMILY_TYPE: Record<FxFamily, string> = {
+  filter: "font-light uppercase tracking-[0.14em]",
+  dynamics: "font-bold uppercase tracking-tight",
+  nonlinear: "font-serif italic tracking-normal",
+  time: "font-extralight uppercase tracking-[0.24em]",
+  smart: "font-mono font-medium tracking-normal",
+};
+
+/** Hue per family, and a lightness ramp across the modules inside it. */
+const FAMILY_HUE: Record<FxFamily, number> = {
+  filter: 205,
+  dynamics: 25,
+  nonlinear: 310,
+  time: 165,
+  smart: 95,
+};
+
+/**
+ * Which family a chain node belongs to.
+ *
+ * The composite tags win over the registry group, because what a node IS to the
+ * author is the module that owns it: a carve's peaking filters are not filters
+ * the author added, they are one carve.
+ */
+export function fxFamilyOf(
+  node: Pick<HfAudioFxNode, "type" | "fromCarve" | "fromEq" | "fromLeveller">,
+): FxFamily {
+  if (node.fromCarve || node.fromEq || node.fromLeveller) return "smart";
+  const group = HF_AUDIO_FX.find((def) => def.id === node.type)?.group;
+  return group === "dynamics" || group === "nonlinear" || group === "time" ? group : "filter";
+}
+
+/**
+ * The module's own tint: its family's hue, stepped by where it sits among its
+ * siblings in the registry.
+ *
+ * Kept narrow on purpose — 62% to 76% lightness at low saturation. This has to
+ * separate two modules at a glance without reading as a status colour, and the
+ * panel already spends saturation on "automated" and "bypassed".
+ */
+export function fxFamilyTint(
+  node: Pick<HfAudioFxNode, "type" | "fromCarve" | "fromEq" | "fromLeveller">,
+): string {
+  const family = fxFamilyOf(node);
+  const siblings = HF_AUDIO_FX.filter((def) => fxFamilyOf({ type: def.id }) === family);
+  const index = siblings.findIndex((def) => def.id === node.type);
+  const step = siblings.length > 1 ? Math.max(0, index) / (siblings.length - 1) : 0;
+  // Comma syntax rather than the space-separated modern form: it is what every
+  // CSS parser in the chain agrees on, including the one the tests run in.
+  return `hsl(${FAMILY_HUE[family]}, 32%, ${(62 + step * 14).toFixed(1)}%)`;
+}

packages/studio/src/components/editor/propertyPanelFxNodeRow.tsx

@@ -22,6 +22,7 @@ import { EFFECT_COPY, SUMMARY } from "@hyperframes/core/audio-fx-copy";
 import { fxAutomationTarget } from "@hyperframes/core/audio-automation";
 import { FxParams } from "./propertyPanelFxControls.js";
 import { FxBandRuler } from "./propertyPanelFxBandRuler.js";
+import { FX_FAMILY_TYPE, fxFamilyOf, fxFamilyTint } from "./propertyPanelFxFamily.js";
 
 /**
  * The one control that carries the module, if it has one.
@@ -72,6 +73,8 @@ function plainDef(def: HfAudioFxDef): HfAudioFxDef {
 interface FxNodeRowProps {
   node: HfAudioFxNode;
   index: number;
+  /** Where it sits in the signal path, as the rack counts it. Absent means unnumbered. */
+  position?: number;
   automatedTargets?: ReadonlySet<string>;
   liveAutomationValues?: ReadonlyMap<string, number>;
   onAutomateParam?(nodeId: string, paramKey: string): void;
@@ -115,6 +118,8 @@ function FxMoveButton({
 /** Name, bypass, reorder and remove for one effect. */
 function FxNodeHeader({
   label,
+  family,
+  position,
   open,
   bypassed,
   first,
@@ -126,6 +131,9 @@ function FxNodeHeader({
   onRemove,
 }: {
   label: string;
+  /** How this family letters, so the KIND reads before the word does. */
+  family: string;
+  position?: number;
   open: boolean;
   bypassed: boolean;
   first: boolean;
@@ -138,9 +146,17 @@ function FxNodeHeader({
 }) {
   return (
     <div className="hf-fx-node-head flex min-h-7 items-center gap-1 px-1.5">
+      {/* Two digits, because a rack reads as a path when its steps are numbered
+          and as a list when they are not — and the difference decides whether an
+          author thinks the order matters. It does; it is audible. */}
+      {position !== undefined ? (
+        <span className="hf-fx-node-index shrink-0 font-mono text-[9px] tabular-nums text-panel-text-4">
+          {String(position).padStart(2, "0")}
+        </span>
+      ) : null}
       <button
         type="button"
-        className="hf-fx-node-name flex-1 truncate text-left text-[11px] font-semibold text-panel-text-1 hover:text-panel-text-0"
+        className={`hf-fx-node-name flex-1 truncate text-left text-[11px] text-panel-text-1 hover:text-panel-text-0 ${family}`}
         aria-expanded={open}
         onClick={onToggleOpen}
       >
@@ -259,6 +275,7 @@ function FxNodeParams({
 export function FxNodeRow({
   node,
   index,
+  position,
   automatedTargets,
   liveAutomationValues,
   onAutomateParam,
@@ -293,10 +310,17 @@ export function FxNodeRow({
   const summary = SUMMARY[node.type]?.(params);
   return (
     <div
-      className={`hf-fx-node rounded-[4px] border border-panel-border-input${bypassed ? " opacity-50" : ""}`}
+      className={`hf-fx-node rounded-[4px] border border-l-2 border-panel-border-input${bypassed ? " opacity-50" : ""}`}
       data-fx-node={node.type}
+      data-fx-family={fxFamilyOf(node)}
+      // The tint is on the edge rather than the text: the name already carries
+      // the family in its lettering, and colouring it too would fight the
+      // panel's own tokens for automated and bypassed.
+      style={{ borderLeftColor: fxFamilyTint(node) }}
     >
       <FxNodeHeader
+        family={FX_FAMILY_TYPE[fxFamilyOf(node)]}
+        position={position}
         // The node's own job name when a preset gave it one, because that is the
         // most specific truth available: a chain that cuts mud and then lifts
         // clarity must not show the same name twice. Then the plain name, and

packages/studio/src/components/editor/propertyPanelFxSection.test.tsx

@@ -364,6 +364,89 @@ describe("FxSection chain", () => {
     );
   });
 
+  it("draws the rack as a signal path, with both ends named", () => {
+    // Order is audible here, and a list does not look ordered. Numbering the
+    // steps and naming the two ends is what makes "move up" read as the most
+    // consequential control in the panel rather than a cosmetic one.
+    const { host } = mount({ chain: chainOf("highpass", "limiter") });
+    const terms = Array.from(host.querySelectorAll(".hf-fx-term")).map((e) => e.textContent);
+    expect(terms).toHaveLength(2);
+    expect(terms[0]).toContain("In");
+    expect(terms[1]).toContain("Out");
+    // Counted over what the rack SHOWS: the carve module leads it, so the first
+    // hand-built effect is 02.
+    const numbers = Array.from(host.querySelectorAll(".hf-fx-node-index")).map((e) =>
+      e.textContent?.trim(),
+    );
+    expect(numbers).toEqual(["02", "03"]);
+  });
+
+  it("draws a preset's nodes as the one thing that was added", () => {
+    // Applying a preset drops five rows into the rack with nothing saying they
+    // arrived together — the same failure the carve module exists to fix, one
+    // level down.
+    const { host, onChainChange } = mount({ chain: { version: 1, nodes: [] } });
+    click(byText(host, "button", "Presets"));
+    click(presetButton(host, "telephone"));
+    // Applying does not re-render this mount — the chain comes back as a prop —
+    // so the rack is read from what was written.
+    const applied = onChainChange.mock.calls[0]?.[0] as HfAudioFxChain | undefined;
+    const written = applied?.nodes ?? [];
+    const { host: after } = mount({ chain: { version: 1, nodes: written } });
+
+    const run = after.querySelector("[data-fx-preset='telephone']");
+    expect(run).toBeTruthy();
+    expect(run?.querySelector(".hf-fx-preset-run-label")?.textContent).toBe("Telephone");
+    expect(run?.querySelectorAll(".hf-fx-node")).toHaveLength(written.length);
+  });
+
+  it("brackets only nodes a preset still sits next to", () => {
+    // Pulled apart by a reorder, they are no longer a unit — and a bracket
+    // around the gap would claim an adjacency the signal path does not have.
+    const { host } = mount({
+      chain: {
+        version: 1,
+        nodes: [
+          { type: "highpass", fromPreset: "telephone", params: defaultAudioFxParams("highpass") },
+          { type: "reverb", params: defaultAudioFxParams("reverb") },
+          { type: "lowpass", fromPreset: "telephone", params: defaultAudioFxParams("lowpass") },
+        ],
+      } as unknown as HfAudioFxChain,
+    });
+    const runs = Array.from(host.querySelectorAll("[data-fx-preset='telephone']"));
+    expect(runs).toHaveLength(2);
+    for (const run of runs) expect(run.querySelectorAll(".hf-fx-node")).toHaveLength(1);
+  });
+
+  it("letters each family differently, so the kind reads before the word does", () => {
+    // A rack of eight modules is eight lines of text. Reading it should not mean
+    // reading eight names — the shape of the line carries what KIND of module
+    // this is, and the word only confirms it.
+    const { host } = mount({ chain: chainOf("lowpass", "compressor", "saturate", "delay") });
+    const families = Array.from(host.querySelectorAll("[data-fx-family]")).map((e) =>
+      e.getAttribute("data-fx-family"),
+    );
+    // The carve module leads the rack and is smart; then the four registry ones.
+    expect(families).toEqual(["smart", "filter", "dynamics", "nonlinear", "time"]);
+
+    const names = Array.from(host.querySelectorAll(".hf-fx-node-name")).map((e) => e.className);
+    // Four families told apart by the sans, and the serif spent on the one that
+    // generates signal rather than measuring or shaping what is there.
+    expect(names.filter((c) => c.includes("font-serif"))).toHaveLength(1);
+    expect(names[3]).toContain("font-serif");
+    expect(new Set(names.map((c) => c.replace(/^.*?(?=font-)/, "")))).toHaveProperty("size", 5);
+  });
+
+  it("tints two modules of the same family apart without changing family", () => {
+    const { host } = mount({ chain: chainOf("lowpass", "highpass") });
+    const cards = Array.from(host.querySelectorAll<HTMLElement>("[data-fx-family='filter']"));
+    expect(cards).toHaveLength(2);
+    // Same hue, different step: two filters, visibly two modules.
+    const tints = cards.map((c) => c.style.borderLeftColor);
+    expect(tints[0]).not.toBe(tints[1]);
+    for (const tint of tints) expect(tint).toContain("205");
+  });
+
   it("says where a filter is working, in the words the rack shares", () => {
     // Frequencies mean nothing to somebody who has not been taught them, and the
     // rack speaks entirely in them. The ruler is where they get taught.