refactor(svelte5): incremental runes migration — per-folder tracking

[escapedcat]

Part of #1201 (Stage 4 — ongoing, no deadline: Svelte 5 legacy mode supports the old syntax indefinitely; runes/legacy components mix freely).

After Stage 1, the table cluster (11 files) is runes-mode and the other ~157 components still use Svelte-4 syntax. This issue tracks converting them folder by folder. npx sv migrate svelte-5 supports per-folder runs and automates export let→$props, $:→$derived/$effect (wrapping timing-unsafe cases in run() from svelte/legacy), on:→event attributes, slots→snippets, new Component→mount.

Inventory (2026-08-04): export let in 130 files (406 uses), $: in 93 files (378), <slot> in 11 files, <svelte:component> in 4, $$props/$$restProps in 5, createEventDispatcher in 3.

Approach

• One PR per folder below; run the migrator, then hand-review every run() wrapper and @migration-task comment it leaves.
• Manual work the tool skips: the 3 createEventDispatcher components (AddressSearch, SaveAuthPrompt, ActivityTypeFilter) → callback props, plus their ~6 consumers.
• Hand-convert, don't auto-migrate, the reactivity hotspots: CommunityCard.svelte (25 $:), MerchantListPanel.svelte (23), merchant/[id]/+page.svelte (20), Socials.svelte (19 $: + 23 props), area/MerchantCard.svelte (16). routes/map/+page.svelte is 2,189 lines but only 10 $: — size, not reactivity, is its risk; do it last and consider splitting first.

Folder checklist

• src/components/ (shared, excl. leaderboard — already runes from Stage 1)
• src/components/area/
• src/routes/ — simple/static routes first
• src/routes/merchant/
• src/routes/communities/ + src/routes/countries/
• src/routes/map/ (last; 2,189-line page)
• sweep: remaining <svelte:component>, slots→snippets, $$restProps wrappers (Icon, IconButton, CollapseButton, PrimaryButton, TextLink)
• finale: enable compilerOptions.runes: true in svelte.config.js so legacy syntax can't creep back

[escapedcat]

Policy update (PR #1239): AGENTS.md now carries a boy-scout rule — any PR that meaningfully edits a legacy component converts that file to runes mode in the same PR (own commit, whole-file, template idioms included). Trivial edits and the hand-conversion hotspots listed above stay exempt. Opportunistic conversions should be ticked off in this issue's checklist alongside the folder PRs, so both paths converge on the runes: true finale.

via Claude Code 🤖

[escapedcat]

Pilot complete: /supporters converted in #1263 (sub-issue #1262). Recipe + learnings for the remaining folders:

Recipe

1. Don't use npx sv migrate svelte-5 for folder-scoped runs — it's interactive and whole-project. Drive its engine directly instead:

   // migrate-folder.mjs — run: node migrate-folder.mjs <files...>
   import { readFileSync, writeFileSync } from "node:fs";
   import { migrate } from "svelte/compiler";
   for (const f of process.argv.slice(2)) {
     const { code } = migrate(readFileSync(f, "utf8"), { filename: f, use_ts: true });
     writeFileSync(f, code);
   }

2. Run pnpm run format:fix — the migrator's indentation doesn't match Biome.
3. Hand-review checklist (everything the migrator gets wrong or half-right):
   • grep -rn 'svelte/legacy\|@migration-task' <folder> — must end at zero. Event modifiers (|stopPropagation etc.) become svelte/legacy wrapper imports; fold them into the handler as explicit calls with a comment.
   • It emits interface Props {...} — convert to type Props = {...} (repo standard), and on route pages use import type { PageProps } from "./$types" instead (matches community/[area]/*).
   • Uninitialized let x: T becomes let x: T = $state() — needs | undefined added to the annotation to type-check.
   • Redundant ?: T | undefined + = undefined in props — simplify.
4. Full checklist (format:fix, check, lint, test --run, build), then deploy-preview QA.

Calibration from the pilot

• Migrator quality was better than feared: zero run() wrappers and zero @migration-task comments across 4 files / ~500 lines / 5 $: / 11 export let. The $: t = $_ i18n idiom converts cleanly to $derived($_). Folders with denser reactivity may differ — that's what the hand-conversion hotspot list is for.
• Works as-is, no changes needed: $state(new Set()) with the reassignment pattern, bind: against still-legacy components (mixed-mode), use: actions.
• Effort: ~500 lines ≈ 1 focused hour including review and verification. The mechanical bulk of this issue is very tractable.

Suggested next PR: /user/activity + ActivityTypeFilter — adds the createEventDispatcher → callback-props class (its only consumer is that view), after which every conversion category except the hotspots has a worked example.

via Claude Code 🤖