hensei-web/prd/migrate-next-to-sveltekit-runes.md

# PRD: Migrate Web App from Next.js to SvelteKit (Svelte 5 + Runes)

## Context
The app is a small but interactive site for building, saving, and sharing Granblue Fantasy team compositions. It currently runs on Next.js 14 using a hybrid of App Router and legacy Pages, with `next-intl` for i18n, Valtio for state, Radix-based UI wrappers, and Tiptap for rich text. The backend is a Rails API and will not change.

## Problem / Opportunity
- The UI layer carries Next-specific complexity (hybrid routing, middleware composition, Valtio, React wrappers around primitives) for a scope that aligns well with SvelteKit’s simpler mental model.
- Svelte 5 (Runes) and SvelteKit provide small, fast bundles and ergonomic state management for highly interactive UIs like the party editor.
- A rewrite would impose upfront cost but could yield better performance, maintainability, and developer experience.

## Goals
- Achieve feature and URL parity (including localized routing and auth/method guards) with the current Next.js app.
- Reuse domain types, data contracts, and i18n content; minimize churn to the Rails API layer.
- Maintain or improve perceived performance, accessibility, and UX of primitives (menus, dialogs, tooltips, toasts).

## Non‑Goals
- No changes to the Rails API endpoints, auth semantics, or data shape.
- No new product features beyond parity (performance and a11y improvements are in scope).

## Current State (Summary)
- Framework: Next.js 14 with `app/` and `pages/` side by side.
- Routing/i18n: `app/[locale]/…` with `next-intl` and “as-needed” default-locale prefixing; middleware composes i18n with auth/method guards.
- State: Valtio global stores for `accountState` and `appState` (party/grid/editor flows).
- Data: axios-based `utils/api.tsx`, app route handlers under `app/api/**` proxy to Rails; server helpers in `app/lib/*` with zod validation.
- UI: Components under `components/**` using SCSS modules, Radix-based wrappers, custom editor based on Tiptap React + custom extensions.
- URL State: `nuqs` binds filters to query params.
- Storybook: React/Next preset.

## Feature/Parity Requirements
- Public routes: `/`, `/new`, `/teams`, `/p/[party]` (+ tab segments), `/[username]`, `/about`, `/updates`, `/roadmap` with locale variants under `/ja` and default-locale “as-needed” behavior.
- Auth/method gates: protect `/saved` and `/profile`; 401 JSON for unauthorized API mutations; preserve method-based rules under `/api/**`.
- Party editor: weapons/summons/characters, job/skills/accessory, guidebooks, toggles, remix/delete, editability rules by cookie/user.
- Search & filters: team discovery with element/raid/recency, advanced filters from cookie, pagination (append/replace).
- i18n: reuse JSON namespaces; preserve current translation keys and locale cookie behavior.
- Primitives: dropdown menu, dialog, tooltip, toast, popover, select, switch, slider, command, segmented control with keyboard a11y.
- Editor: Tiptap with mentions, link, lists, headings, youtube, highlight, placeholder.

## Proposed Direction
Rebuild the web app on SvelteKit 2 and Svelte 5 Runes. Keep the Rails API contract intact. Adopt Svelte stores for global state and Runes for local component state. Replace React-specific libraries with Svelte-native equivalents while reusing JSON messages, type declarations, API contracts, and Tiptap core extensions.

## Target Architecture (SvelteKit)
- Routing: `src/routes/[lang=locale]/…` to mirror localized segments; top-level `/` redirects to `/new`.
- Hooks: `hooks.server.ts` handles locale detection/redirects and reproduces auth/method gates; `handleFetch` attaches bearer tokens from cookies.
- Data loading: `+layout.server.ts`/`+page.server.ts` for SSR (e.g., version, lists); `+page.ts` for client/SSR-unified fetches.
- Endpoints: `src/routes/api/**/+server.ts` proxy to Rails with zod validation and consistent status codes.
- State: Svelte `writable` stores for `account` and `app` (party, grid, search, jobs, skills, version), with typed helper actions; local UI state via runes.
- Theming: small store plus SSR-safe initial theme; apply class/data-theme on `<html>`.
- i18n: `svelte-i18n` (recommended) loading existing JSON bundles; locale cookie + accept-language fallback; “as-needed” default-locale paths.

## Dependency Mapping (Equivalents)
- Framework/Core:
  - `next` → `@sveltejs/kit`
  - `react`, `react-dom` → `svelte@5`
  - `@svgr/webpack` → `vite-svg-loader` (or inline SVG)
- Routing/URL State:
  - `next/navigation` → SvelteKit `goto`, `$page`, `afterNavigate`
  - `nuqs` → `$page.url.searchParams` + small helper or `sveltekit-search-params`
- Data/Query:
  - `@tanstack/react-query` → `@tanstack/svelte-query@5`
  - `axios` → keep or migrate to `fetch`; keep zod
- i18n:
  - `next-intl` → `svelte-i18n` (reuse JSON); remove `next-i18next`
  - `i18next*` libs → only if choosing an i18next-based Svelte binding (otherwise remove)
- UI/A11y:
  - `@radix-ui/*` → `bits-ui` primitives and/or `shadcn-svelte`
  - `tippy.js` → `svelte-tippy` (or small custom)
  - `cmdk` → `cmdk-svelte`/`cmdk-sv`
- Theming:
  - `next-themes` → small Svelte store + cookie bootstrap
- Editor:
  - `@tiptap/react` → Tiptap core with Svelte integration (e.g., `svelte-tiptap`); reuse custom extensions
- Typeahead/Select/Infinite:
  - `react-bootstrap-typeahead` → `svelte-select`
  - `react-infinite-scroll-component` → `svelte-infinite-loading` or IO-based action
- Misc:
  - `cookies-next` → `event.cookies` server-side; `js-cookie` client
  - `react-use`/`usehooks-ts` → `svelte-use`
  - `remixicon-react` → `svelte-remixicon` or `unplugin-icons` (`ri:*`)
  - `react-linkify` → `linkifyjs`/`linkify-html`
  - SCSS → `svelte-preprocess` with component-scoped styles and global imports
  - Storybook: `@storybook/nextjs` → `@storybook/sveltekit`

## Reuse vs. Rewrite
- Reuse
  - i18n bundles under `public/locales/{en,ja}`
  - Domain types `types/*.d.ts` (move to `src/lib/types`)
  - Pure utilities in `utils/*` (parsers, enums, formatters)
  - API contracts and zod schemas (`app/lib/api-utils.ts`)
  - Tiptap custom extensions (`extensions/CustomMention`, `CustomSuggestion`)
  - Public assets and SVGs
- Rewrite
  - All React components and Valtio stores as Svelte components/stores
  - Next middleware as `hooks.server.ts` (auth + locale); API handlers as `+server.ts`
  - URL/query state helpers (replace `nuqs`)
  - Theming (replace `next-themes`)
  - Storybook stories
  - Font handling (move `pages/fonts/gk-variable.woff2` to `static/` and add `@font-face`)

## Routing & i18n Details
- Localized route group `[lang=locale]` constrained to `en|ja` (from existing `i18n.config.ts`).
- “As-needed” default-locale behavior via redirects in `handle` and locale-aware links.
- Preserve existing route structure and query semantics (e.g., `/teams?element=…&raid=…`).

## Auth & Cookies
- Mirror `middleware.ts` logic: protect `/saved` and `/profile`; method-guard mixed routes; return 401 JSON for API.
- Server: use `event.cookies` and set `locals.user`; client: `js-cookie` where necessary.
- Use `handleFetch` to inject `Authorization` header from `account` cookie token.

## State & Data
- Global state: writable stores mirroring `initialAccountState` and `initialAppState` with typed actions; local UI state via runes.
- Queries: `@tanstack/svelte-query` for client/SSR-safe caching; SSR data via `+page.server.ts` where beneficial.
- Invalidation: use SvelteKit `invalidate`/`invalidateAll` in place of Next `revalidatePath`.

## UI & Editor
- Primitives: build on Bits-UI/shadcn-svelte; verify keyboard navigation and focus management; carry over SCSS look-and-feel.
- Editor: use Tiptap core with Svelte wrapper; reuse mention/suggestion logic and toolbar feature set (bold/italic/strike/heading/list/link/youtube/highlight/placeholder).

## Performance & SEO
- Expect smaller bundles and faster hydration from Svelte runtime.
- Maintain SSR for primary pages and content; keep linkable, crawlable party pages and listings.
- Optimize images/SVGs via Vite pipeline; keep existing public assets.

## Tradeoffs (Pros / Cons)
- Pros: performance, simpler state and data flows, clearer SSR/CSR boundaries, component‑scoped styling, fast DX.
- Cons: full component rewrite, parity tuning for UI primitives, community-maintained editor bindings, team ramp‑up, Storybook conversion.

## Alternatives Considered
- Stay on Next.js and complete the ongoing App Router + next‑intl consolidation (lowest risk and cost).
- Prototype SvelteKit for the party editor only (dual‑stack) and evaluate before committing.

## Open Questions
- Keep proxy endpoints under `/api/**` or talk to Rails directly with CORS? (Proxy simplifies auth and error shaping.)
- UI library choice finalization: Bits‑UI vs shadcn‑svelte (or a minimal custom layer where needed).
- Icon strategy: `unplugin-icons` vs direct SVG imports.

## Acceptance Criteria
- Route and locale parity with auth/method guards and “as‑needed” default‑locale behavior.
- Party editor parity (create/update/remix/delete; grids; jobs/skills/accessories; guidebooks; toggles).
- Query‑linked filters and pagination on `/teams`, `/saved`, `/[username]`.
- Editor parity (mentions, link, lists, headings, youtube, highlight, placeholder) and equivalent styling.
- Primitives parity with keyboard a11y and visual consistency.
- i18n keys resolve from existing JSON bundles; theme persists SSR + client.

## Success Measures
- Time‑to‑interactive and bundle size improved vs. Next build.
- No regression in error rates for API interactions (remix/delete/save).
- Positive qualitative feedback on responsiveness in editor/grid interactions.