From 9af6267704b5a4f55473a6218216add13589f80f Mon Sep 17 00:00:00 2001 From: Patrick Demichiel Date: Tue, 10 Nov 2026 21:21:07 +0100 Subject: [PATCH] refactor: move the Svelte UI to Svelte 5 best practices, avoiding $effect State that follows other state is now a writable $derived (ModuleCard's rename, menu, page and previews), a reaction lives in its handler or a function binding's setter (Select's onOpenChange, the site header's spin counter), DOM work is an {@attach} (Switch's line measurement, ModuleCard's size tween, the setup wizard's input metering, ToolSidebar's action via fromAction), and devicePixelRatio() subscribes on read through createSubscriber, so Rack needs no effect to track it. Every remaining $effect carries a `// Effect:` line saying why it is one, and src/lib/effectGuard.test.ts fails on one that does not, across ui/ and site/. class: directives become class arrays, except on the module panel, whose classList the size tween writes. App.svelte loses the UTF-8 BOM that made svelte-autofixer fail to parse it, and its mojibake comments are repaired. AGENTS.md records the rule. Refs #47 --- AGENTS.md | 14 ++ .../src/lib/components/DownloadButtons.svelte | 2 +- site/src/lib/components/Header.svelte | 20 +- site/src/lib/components/VideoEmbed.svelte | 6 +- ui/src/App.svelte | 25 ++- ui/src/features/drawer/DrawerShelf.svelte | 1 - ui/src/features/info/updateStore.svelte.ts | 8 +- ui/src/features/knob/Knob.svelte | 12 +- ui/src/features/knob/Switch.svelte | 31 ++- ui/src/features/module/ModuleCard.svelte | 205 ++++++++++-------- ui/src/features/module/PatchBar.svelte | 9 +- ui/src/features/plugins/PluginsPanel.svelte | 7 +- ui/src/features/rack/MixStrip.svelte | 14 +- ui/src/features/rack/Rack.svelte | 83 ++++--- ui/src/features/setup/SetupWizard.svelte | 13 +- ui/src/features/sidebar/ToolSidebar.svelte | 6 +- ui/src/features/status/GainMeter.svelte | 1 + ui/src/features/status/StrobeDisplay.svelte | 3 + ui/src/features/status/TunerReadout.svelte | 5 +- ui/src/lib/components/DropOverlay.svelte | 4 +- ui/src/lib/components/MidiLearn.svelte | 2 + ui/src/lib/components/Popover.svelte | 2 + ui/src/lib/components/SegmentedControl.svelte | 2 +- ui/src/lib/components/Select.svelte | 33 ++- ui/src/lib/components/SwitcherGroup.svelte | 2 +- ui/src/lib/components/TaskDialog.svelte | 6 +- ui/src/lib/devicePixels.svelte.ts | 63 ++---- ui/src/lib/effectGuard.test.ts | 71 ++++++ 28 files changed, 395 insertions(+), 255 deletions(-) create mode 100644 ui/src/lib/effectGuard.test.ts diff --git a/AGENTS.md b/AGENTS.md index d3fd620..079bda4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1959,6 +1959,20 @@ as are AU and CLAP hosting. `import type` for types), Tailwind utility classes for styling, interfaces documented with JSDoc-style comments. Features are plain callback props, not global stores. +- **`$effect` is the last resort.** State that follows other state is + `$derived` (a *writable* `$derived` when it is set locally and resets when + its input changes); a reaction to something the user did goes in that + handler, or in a function binding's setter (`bind:x={() => x, setX}`); DOM + wiring and measurement is an `{@attach}`; an external value that changes on + its own is `createSubscriber` (see `lib/devicePixels.svelte.ts`). What is + left — timers, writes to the document or localStorage, engine requests, + latching an engine stream — carries a `// Effect: …` line in the comment + directly above it saying why, which `src/lib/effectGuard.test.ts` enforces + for `ui/` and `site/`. Check any Svelte file you touch with the Svelte MCP's + `svelte-autofixer` (or `npx @sveltejs/mcp svelte-autofixer `) until + it reports no issues. Prefer the class array/object form to `class:` + directives, except on an element whose classes are also toggled with + `classList` — a class array rewrites `className` whole. - **Formatting**: don't hand-format UI files. Run `pnpm format` in `ui/`; Prettier formats Svelte/TypeScript/CSS at 100 columns and the Tailwind plugin applies the canonical utility-class order. diff --git a/site/src/lib/components/DownloadButtons.svelte b/site/src/lib/components/DownloadButtons.svelte index 8b6a57d..eced9a9 100644 --- a/site/src/lib/components/DownloadButtons.svelte +++ b/site/src/lib/components/DownloadButtons.svelte @@ -36,7 +36,7 @@
{#each DOWNLOADS as dl (dl.os)} - + {#if dl.platform === 'windows'} // paints the page and the resize handles and tooltips render outside it. + // Effect: writes the document root and localStorage, outside this tree. $effect(() => applyTheme(appSettings.theme)); // Auto Standby's activity ping. The engine can only see the guitar input, so - // silent interaction — editing a rig, reading the manual with the window - // focused — has to be reported from here or standby would engage mid-session. + // silent interaction — editing a rig, reading the manual with the window + // focused — has to be reported from here or standby would engage mid-session. // Throttled hard: this fires on raw pointer/key/wheel traffic, and the engine // only needs to know the user is present, not how busy they are. const ACTIVITY_PING_MS = 5000; @@ -383,7 +386,7 @@ /> {#snippet toolsSidebar()} @@ -423,7 +426,7 @@ {/snippet}
diff --git a/ui/src/features/drawer/DrawerShelf.svelte b/ui/src/features/drawer/DrawerShelf.svelte index 6cc5f2c..a0391ce 100644 --- a/ui/src/features/drawer/DrawerShelf.svelte +++ b/ui/src/features/drawer/DrawerShelf.svelte @@ -81,7 +81,6 @@ }: Props = $props(); -
onMeasure(px ?? 0)} diff --git a/ui/src/features/info/updateStore.svelte.ts b/ui/src/features/info/updateStore.svelte.ts index 857823d..496be9d 100644 --- a/ui/src/features/info/updateStore.svelte.ts +++ b/ui/src/features/info/updateStore.svelte.ts @@ -33,10 +33,10 @@ export function latestVersion(): string { * case, and by the time the user opens About the network may well be back. */ export async function checkForUpdate(force = false): Promise { // Untracked, and this must stay the only read of `phase` in this function: - // both callers run it from an `$effect`, so a tracked read would make that - // effect depend on the phase this function immediately sets. The effect - // re-runs, calls in again — and because 'failed' is not a terminal phase, - // a failing check would retry forever instead of once. + // both callers run it from `onMount`, which tracks nothing, but a caller in a + // reactive context would otherwise come to depend on the phase this function + // immediately sets. It would re-run, call in again — and because 'failed' is + // not a terminal phase, a failing check would retry forever instead of once. const current = untrack(() => phase); if (current === 'checking' || (current === 'checked' && !force)) return; phase = 'checking'; diff --git a/ui/src/features/knob/Knob.svelte b/ui/src/features/knob/Knob.svelte index e2cf384..96acf43 100644 --- a/ui/src/features/knob/Knob.svelte +++ b/ui/src/features/knob/Knob.svelte @@ -126,9 +126,10 @@
{#if p.isMeter} {/each} {/each}