feat(core): land the plain-language layer, and test that it covers the rack

`copy.mts` lived in `plans/` and was read by one build script. Moving it
to `packages/core/src/audioFxCopy.ts` puts it beside the registry it
describes, and turns the coverage into `audioFxCopy.test.ts` — every
shipped effect, every one of its parameters, and every preset has to have
copy. That check existed before as a step in `build-preview.mts`, which
means it only fired when somebody remembered to rebuild the review page.
Now it fires on the commit that adds an effect without a plain name for
it, which is the only moment it can still be cheap to fix.

Four more assertions the build step never made, each of which was a real
hole: copy for an effect the registry no longer ships (dead text that
reads as coverage), a `SUMMARY` missing for an effect that has one
everywhere else, a summary that renders `undefined` or `NaN` at the
effect's own defaults — which is the first thing an author reads after
adding one — and a gap or overlap in the shared frequency ruler, which
would be a band the rack can name in one module and not in another.

`PROFILES` deliberately did NOT come along. Its figures are proposed, not
measured, nothing derives from them yet, and they want the same
before/after listen the clip-before-duck fix got before a knob is wired
to them. So it stays in `plans/audio-fx-ux/copy.mts`, which is now all
that file holds, and `build-preview.mts` imports the shipped four from
core and that one from beside itself.

Landing the data is not wiring it: nothing in the studio reads this yet,
and it should not until the three open UX questions are settled — whether
the plain name replaces the DSP name or sits beside it decides what the
rack renders. The README says so where the status used to say the layer
had not landed.

Falsified: deleting one parameter's entry fails the highpass case.

core 1745 passing (111 files), studio unchanged at 3674 / 18 todo.

Author: vanceingalls

packages/core/package-subpaths.json

@@ -92,6 +92,12 @@
       "types": "./dist/audioFx.d.ts",
       "environments": ["browser", "bun", "node"]
     },
+    "./audio-fx-copy": {
+      "source": "./src/audioFxCopy.ts",
+      "runtime": "./dist/audioFxCopy.js",
+      "types": "./dist/audioFxCopy.d.ts",
+      "environments": ["browser", "bun", "node"]
+    },
     "./audio-fx-eq": {
       "source": "./src/audioFxEq.ts",
       "runtime": "./dist/audioFxEq.js",

packages/core/package.json

@@ -106,6 +106,12 @@
       "import": "./src/audioFx.ts",
       "types": "./src/audioFx.ts"
     },
+    "./audio-fx-copy": {
+      "bun": "./src/audioFxCopy.ts",
+      "node": "./dist/audioFxCopy.js",
+      "import": "./src/audioFxCopy.ts",
+      "types": "./src/audioFxCopy.ts"
+    },
     "./audio-fx-eq": {
       "bun": "./src/audioFxEq.ts",
       "node": "./dist/audioFxEq.js",
@@ -410,6 +416,10 @@
         "import": "./dist/audioFx.js",
         "types": "./dist/audioFx.d.ts"
       },
+      "./audio-fx-copy": {
+        "import": "./dist/audioFxCopy.js",
+        "types": "./dist/audioFxCopy.d.ts"
+      },
       "./audio-fx-eq": {
         "import": "./dist/audioFxEq.js",
         "types": "./dist/audioFxEq.d.ts"

packages/core/src/audioFxCopy.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import { defaultAudioFxParams, HF_AUDIO_FX } from "./audioFx.js";
+import { HF_AUDIO_FX_PRESETS } from "./audioFxPresets.js";
+import { BANDS, EFFECT_COPY, PRESET_PROBLEM, SUMMARY } from "./audioFxCopy.js";
+
+/**
+ * The copy layer is only worth having if it covers everything that ships. A gap
+ * is not a missing nicety — it is a rack panel labelled `highpass` in front of
+ * somebody who came here to stop a hum, which is the exact failure this layer
+ * exists to prevent.
+ *
+ * This was a build step in `plans/audio-fx-ux/build-preview.mts`, which meant it
+ * only caught a gap when somebody remembered to rebuild the review page. Here it
+ * catches it on the commit that adds the effect.
+ */
+describe("every shipped effect has plain-language copy", () => {
+  for (const def of HF_AUDIO_FX) {
+    it(`${def.id}`, () => {
+      const copy = EFFECT_COPY[def.id];
+      expect(copy, `${def.id} has no copy`).toBeDefined();
+      if (!copy) return;
+      for (const param of def.params) {
+        expect(copy.params[param.key], `${def.id}.${param.key} has no plain name`).toBeDefined();
+      }
+      // "strength" is the one legal fiction: it means the module gets a single
+      // derived knob and its real parameters live behind Details. Anything else
+      // has to name a parameter the effect actually has, or the panel would put
+      // its headline control on a knob that does not exist.
+      if (copy.primary !== "strength") {
+        expect(
+          def.params.map((p) => p.key),
+          `${def.id}'s primary "${copy.primary}" is not one of its parameters`,
+        ).toContain(copy.primary);
+      }
+      expect(SUMMARY[def.id], `${def.id} has no closed-state summary`).toBeDefined();
+    });
+  }
+});
+
+it("every preset says which everyday problem it answers", () => {
+  const missing = HF_AUDIO_FX_PRESETS.filter((p) => !PRESET_PROBLEM[p.id]).map((p) => p.id);
+  expect(missing).toEqual([]);
+});
+
+it("describes no effect the registry does not ship", () => {
+  const shipped = new Set(HF_AUDIO_FX.map((d) => d.id));
+  // The other direction. Copy for an effect that has been removed or renamed is
+  // dead text that reads as covered, and the count in the review page would say
+  // so too.
+  expect(Object.keys(EFFECT_COPY).filter((id) => !shipped.has(id))).toEqual([]);
+  expect(Object.keys(SUMMARY).filter((id) => !shipped.has(id))).toEqual([]);
+});
+
+it("summarises every effect at its own defaults without throwing", () => {
+  for (const def of HF_AUDIO_FX) {
+    const summary = SUMMARY[def.id];
+    if (!summary) continue;
+    // The first thing an author reads after adding an effect, so it has to be a
+    // sentence at the values it arrives with — not "undefined dB".
+    const text = summary(defaultAudioFxParams(def.id));
+    expect(text, `${def.id} summarised as "${text}"`).toMatch(/^[^u].*[^ ]$/);
+    expect(text).not.toContain("undefined");
+    expect(text).not.toContain("NaN");
+  }
+});
+
+it("covers the spectrum without a gap or an overlap", () => {
+  // The ruler is shared by every spectral module, so a hole in it is a frequency
+  // the rack can name in one place and not in another.
+  expect(BANDS[0]?.from).toBe(20);
+  expect(BANDS.at(-1)?.to).toBe(20000);
+  for (let i = 1; i < BANDS.length; i++) {
+    expect(BANDS[i]?.from, `gap or overlap before ${BANDS[i]?.name}`).toBe(BANDS[i - 1]?.to);
+  }
+});