working-on-web

name	working-on-web
description	SvelteKit frontend development conventions for Savecraft. Use when working on files in web/, including Svelte components, pages, stores, Storybook stories, or frontend tests. Triggers on SvelteKit code, Svelte components, Storybook, web UI, dashboard, onboarding, or frontend screenshots.

Working on the Web UI

Read docs/web.md for the dashboard architecture, onboarding state machine, and component specs.

Verification

cd web && npm run check          # TypeScript + Svelte checks
cd web && npm run lint            # ESLint
cd web && npm run test            # Component tests

Conventions

• SvelteKit conventions throughout. TypeScript strict mode.
• Component tests use mock WebSocket and mock API responses.
• Reactive stores ($sources, MCP status) drive the UI — no explicit state machines.

Storybook

Storybook runs on port 6006. Start it before taking screenshots.

just storybook                    # Start Storybook (port 6006)

Story IDs follow the pattern category-component--story-name (lowercase, hyphens).

Screenshots

Custom Playwright-based tool at web/scripts/screenshot.ts. Output goes to web/screenshots/<story-id>.png.

cd web && npm run screenshot components-gamecard--watching     # Single story
cd web && npm run screenshot:all                                # All stories

NixOS requirement: Uses system chromium via findChromium(). Do NOT use Playwright's bundled chromium — it won't work on NixOS due to dynamic linking. The findChromium() function auto-detects the system binary.

Key Paths

web/src/routes/          # SvelteKit pages
web/src/lib/             # Shared components, stores, utilities
web/scripts/screenshot.ts # Playwright screenshot tool
web/screenshots/         # Screenshot output directory
web/.storybook/          # Storybook config