first commit

docs/media/audio-fx/audio-fx-plugin-flanger/src/schemas/schemas.md

@@ -0,0 +1,56 @@
+# `flanger/schemas`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Zod schemas validating the construction-time options and preset payload of `FlangerPlugin`. These run on the public boundary between user code and the plugin: any malformed object hitting the constructor or `applyPreset` is rejected with `AUDIO_FX.INVALID_OPTIONS` / `AUDIO_FX.INVALID_PRESET` before it can corrupt runtime state.
+
+Separating schemas from the plugin module lets `index.ts` re-export them so callers can introspect the option surface for forms, RPC validation, or storybook controls without importing the audio implementation.
+
+## Features
+
+- `FlangerPluginOptionsSchema` — validates all five optional construction fields with their documented ranges (`rate` 0.05..10 Hz, `depth` 0..5 ms, `feedback` 0..0.95, `wet` 0..1, `baseDelay` 0.1..10 ms).
+- `FlangerPresetDataSchema` — empty strict object: the flanger has no plugin-specific preset payload, so any extra keys are rejected by `.strict()`.
+- All numeric fields use `z.number().finite()` so `NaN` and `Infinity` cannot sneak through.
+
+## Usage: Basic Example
+
+```ts
+import { FlangerPluginOptionsSchema } from "@suaveplan/audio-fx-plugin-flanger";
+
+const parsed = FlangerPluginOptionsSchema.parse({ initialDepthMs: 1.5 });
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    FlangerPluginOptionsSchema,
+    FlangerPresetDataSchema,
+} from "@suaveplan/audio-fx-plugin-flanger";
+
+// Pull keys + ranges from the schema for a generated form.
+const fields = FlangerPluginOptionsSchema.keyof().options;
+for (const field of fields) {
+    form.addRow(field);
+}
+
+// Strict preset validation at the IPC boundary.
+function isFlangerPreset(blob: unknown): boolean {
+    return FlangerPresetDataSchema.safeParse(blob).success;
+}
+```
+
+## API Reference
+
+- `FlangerPluginOptionsSchema: z.ZodObject<{ initialRateHz?, initialDepthMs?, initialFeedback?, initialWet?, initialBaseDelayMs? }>`
+- `FlangerPresetDataSchema: z.ZodObject<{}, "strict">`
+
+## Implementation Notes
+
+The maximum feedback is `0.95`, matching the chorus, phaser, and delay plugins so all four feedback-bearing effects share one mental model. The flanger lives close to that boundary by design — the resonant comb peaks are the effect's character — but the same hard cap keeps the loop strictly under unity gain so the output cannot diverge.
+
+`FlangerPresetDataSchema` is `.strict()` so unknown fields are rejected, matching the sibling-plugin policy. The flanger has no plugin-specific preset payload today: every parameter (`rate`, `depth`, `feedback`, `wet`, `baseDelay`) travels through the universal parameter snapshot that `AbstractAudioFxPlugin` builds, and the empty `presetData` field marks that the plugin opts out of plugin-specific state.