refactor: Proposal for refactor in SvelteKit with Storybook

.github/workflows/ci-client-web-svelte.yml

@@ -0,0 +1,75 @@
+---
+name: CI-Client-Web-Svelte
+permissions: {}
+
+on:
+  pull_request:
+    paths:
+      - 'crates/client-web-svelte/**'
+      - '.github/workflows/ci-client-web-svelte.yml'
+  push:
+    branches:
+      - master
+    paths:
+      - 'crates/client-web-svelte/**'
+      - '.github/workflows/ci-client-web-svelte.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: "${{ github.workflow }}-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  svelte:
+    name: Svelte Client (${{ matrix.run }})
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        run:
+          - check
+          - lint
+          - test
+          - build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: crates/client-web-svelte
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+
+      - name: Setup Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: crates/client-web-svelte/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Check (svelte-check)
+        if: matrix.run == 'check'
+        run: npm run check
+
+      - name: Lint (oxlint)
+        if: matrix.run == 'lint'
+        run: npm run lint:ci
+
+      - name: Test (vitest)
+        if: matrix.run == 'test'
+        run: npm run test
+
+      - name: Build
+        if: matrix.run == 'build'
+        run: npm run build
+
+      - name: Upload build artifact
+        if: matrix.run == 'build'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          if-no-files-found: error
+          name: client-web-svelte-dist
+          path: crates/client-web-svelte/dist

crates/client-web-svelte/.env.mock

@@ -0,0 +1,3 @@
+# Activated by `npm run dev:mock` (vite dev --mode mock).
+# Same toggle as the vanilla client's .env.mock — proves the workflow carries over.
+VITE_USE_MOCK_API=true

crates/client-web-svelte/.gitignore

@@ -0,0 +1,13 @@
+node_modules/
+/dist/
+/.svelte-kit/
+/build/
+/package
+.env
+.env.*
+!.env.mock
+*.log
+.DS_Store
+
+*storybook.log
+storybook-static

crates/client-web-svelte/.oxlintrc.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": [
+    "typescript",
+    "unicorn",
+    "oxc",
+    "import"
+  ],
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn",
+    "perf": "warn"
+  },
+  "rules": {
+    "no-console": "off",
+    "no-explicit-any": "off",
+    "no-underscore-dangle": "off",
+    "no-map-spread": "off",
+    "preserve-caught-error": "off",
+    "consistent-function-scoping": "off",
+    "require-module-specifiers": "off",
+    "no-shadow": "off",
+    "no-unassigned-import": "off",
+
+    "no-cond-assign": ["warn", "always"],
+    "no-empty-function": "warn",
+    "no-mutable-exports": "warn",
+    "no-nested-ternary": "warn",
+    "no-useless-assignment": "warn",
+    "prefer-at": "warn",
+    "prefer-math-min-max": "warn",
+    "prefer-modern-math-apis": "warn",
+    "prefer-optional-chain": "warn",
+    "prefer-regexp-exec": "warn",
+    "complexity": ["warn", { "max": 15 }]
+  },
+  "env": {
+    "builtin": true,
+    "browser": true
+  },
+  "overrides": [
+    {
+      "files": ["*.test.ts"],
+      "rules": {
+        "no-console": "off"
+      }
+    },
+    {
+      "files": ["*.stories.svelte", "src/lib/storybook/**"],
+      "rules": {
+        "no-empty-function": "off"
+      }
+    }
+  ]
+}

crates/client-web-svelte/.storybook/decorators/withStores.ts

@@ -0,0 +1,50 @@
+// Global Storybook decorator: seeds the store singletons + mock $app/state
+// around every story based on `args.preset` / `args.route`.
+//
+// Why a plain function (not a Svelte component)?
+//   The Svelte renderer decorator contract (see `decorateStory` in
+//   @storybook/svelte) calls each decorator as `decorator(storyFn, context)`
+//   where `context.args` holds the story's args. A function decorator is the
+//   documented way to read story context for mocking (addon-svelte-csf README
+//   "Accessing Story context"). Returning `storyFn()` hands rendering back to
+//   the renderer's normal mount path.
+//
+//   Registering a Svelte *component* as the decorator instead (the earlier
+//   `[WithStores]` / `() => WithStores` attempts) made the renderer invoke the
+//   component function with the wrong `(internal, props)` shape, corrupting
+//   Svelte 5's internal mount and producing `anchor.before is not a function`.
+//
+// Why untrack + synchronous seeding?
+//   The Svelte renderer invokes decorators from inside a reactive effect
+//   (decorateStory's reduce). Mutating store `$state` synchronously from there
+//   trips Svelte 5's `state_unsafe_mutation` guard ("Updating state inside a
+//   $derived/template expression is forbidden") *and* would register reactive
+//   dependencies we don't want.
+//
+//   `untrack` runs the seeding outside the current reactive computation, so
+//   the mutation is permitted and no spurious dependencies are recorded. It
+//   stays synchronous, so the component mounted by `storyFn()` below sees the
+//   already-seeded stores on first render (no race).
+//
+// `applyPreset` always calls `resetStores()` first, so state never bleeds
+// between stories — no `$effect` cleanup is required.
+import { untrack } from 'svelte';
+import type { Decorator } from '@storybook/svelte';
+import { applyPreset, type Preset } from '$lib/storybook/presets';
+import { setPage } from '$lib/storybook/mockAppState.svelte';
+import { setMockArtworkResolver } from '$lib/api';
+import { lookupArtwork } from '$lib/storybook/artworks';
+
+// Register the local CC0 artwork resolver once so getArtworkUrl() in mock mode
+// serves bundled images for fixture item ids (see artworks.ts registry).
+// Unknown ids fall through to the mock:// placeholder (gradient fallback).
+setMockArtworkResolver((itemId, kind) => lookupArtwork(itemId, kind));
+
+export const withStores: Decorator = (storyFn, context) => {
+  const args = (context.args ?? {}) as { preset?: Preset; route?: string };
+  untrack(() => {
+    applyPreset(args.preset ?? 'empty');
+    if (args.route) setPage({ pathname: args.route });
+  });
+  return storyFn();
+};

crates/client-web-svelte/.storybook/main.ts

@@ -0,0 +1,50 @@
+import type { StorybookConfig } from '@storybook/sveltekit';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|ts|svelte)'],
+  addons: [
+    '@storybook/addon-svelte-csf',
+    '@chromatic-com/storybook',
+    '@storybook/addon-vitest',
+    '@storybook/addon-a11y',
+    '@storybook/addon-docs',
+  ],
+  framework: {
+    name: '@storybook/sveltekit',
+    options: {},
+  },
+  docs: {
+    autodocs: 'tag',
+  },
+  // Dark theming is applied via the proper Storybook theme API, not CSS:
+  //  - manager.ts sets `addons.setConfig({ theme: themes.dark })` for the
+  //    sidebar + toolbar (Storybook 10 uses Emotion CSS-in-JS, so overriding
+  //    CSS variables does nothing — the theme API generates the right styles).
+  //  - preview.ts sets `parameters.docs.theme = themes.dark` for the docs page.
+  viteFinal: async (config) => {
+    // Stub the SvelteKit $app modules — Storybook isn't a router, so components
+    // that read $app/state (page) or $app/navigation (goto) get a mutable mock.
+    // See src/lib/storybook/mockAppState.svelte.ts + mockAppNavigation.ts.
+    config.resolve ??= {};
+    config.resolve.alias = {
+      ...(config.resolve.alias as Record<string, string> | undefined),
+      '$app/state': new URL('../src/lib/storybook/mockAppState.svelte.ts', import.meta.url)
+        .pathname,
+      '$app/navigation': new URL('../src/lib/storybook/mockAppNavigation.ts', import.meta.url)
+        .pathname,
+    };
+
+    // Force mock API mode in Storybook. Stories rely on the mock dispatch layer
+    // (src/lib/mockApi.ts) + store presets — without this, components try to
+    // hit a real backend and the artwork resolver / fixture seeding never runs.
+    // `import.meta.env.VITE_USE_MOCK_API` is read as a Vite env var (see
+    // api.ts:606), so we define the full property access on import.meta.env.
+    config.define ??= {};
+    const define = config.define as Record<string, string>;
+    define['import.meta.env.VITE_USE_MOCK_API'] = JSON.stringify('true');
+
+    return config;
+  },
+};
+
+export default config;

crates/client-web-svelte/.storybook/manager.ts

@@ -0,0 +1,17 @@
+// Storybook manager — runs in the Storybook UI shell (sidebar + toolbar), not
+// in the story canvas. The Koko client is dark-only, so we force the Storybook
+// UI to the built-in `dark` theme.
+//
+// Why the theme API and not CSS overrides?
+//   Storybook 10 renders its entire UI with Emotion CSS-in-JS (hashed class
+//   names like `css-1z0jwx`). There are no stable CSS variables or class names
+//   to override — a `<style>` block in managerHead/previewHead gets ignored by
+//   the Emotion-generated styles. `addons.setConfig({ theme })` is the
+//   supported way to theme the UI; it feeds the theme into Emotion so the
+//   correct dark styles are generated.
+import { addons } from 'storybook/manager-api';
+import { themes } from 'storybook/theming';
+
+addons.setConfig({
+  theme: themes.dark,
+});

crates/client-web-svelte/.storybook/preview.ts

@@ -0,0 +1,61 @@
+import type { Preview } from '@storybook/sveltekit';
+import { themes, ensure } from 'storybook/theming';
+import '../src/app.css'; // design tokens + shared rules — components depend on these
+import { withStores } from './decorators/withStores';
+import { PRESETS } from '$lib/storybook/presets';
+
+// The Koko client is dark-only. Force the docs page to the dark theme too —
+// the manager's `addons.setConfig({ theme: themes.dark })` (see manager.ts)
+// doesn't reliably propagate to docs pages (storybookjs/storybook#28664), so
+// we set it explicitly here. `ensure` makes the theme resolve synchronously.
+ensure(themes.dark);
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    docs: {
+      // Force the docs page chrome to dark (sidebar is handled by manager.ts).
+      theme: themes.dark,
+    },
+    backgrounds: {
+      // The Koko client is dark-only (color-scheme: dark hardcoded in app.css).
+      // Force the Storybook canvas to match so stories render on the right bg.
+      default: 'dark',
+      values: [{ name: 'dark', value: '#0c111d' }],
+    },
+    a11y: {
+      // 'todo' - show a11y violations in the test UI only
+      // 'error' - fail CI on a11y violations
+      // 'off' - skip a11y checks entirely
+      test: 'todo',
+    },
+  },
+  // Global argTypes — apply to every story. `preset` drives the store-seeding
+  // decorator (withStores.ts); making it a select dropdown prevents typos and
+  // shows the available fixture bundles. `route` simulates the current path
+  // for components reading $app/state.
+  argTypes: {
+    preset: {
+      control: { type: 'select' },
+      options: [...PRESETS],
+      description:
+        'Store fixture bundle applied by the withStores decorator (see src/lib/storybook/presets.ts). Seeds catalog/item/libraries/auth/ui stores for the story.',
+      table: { category: 'Storybook' },
+    },
+    route: {
+      control: 'text',
+      description: 'Simulated $app/state pathname for components reading the current route.',
+      table: { category: 'Storybook' },
+    },
+  },
+  // Seed stores + mock $app/state around every story. Stories select a fixture
+  // preset via args.preset (default 'empty'); see decorators/withStores.ts.
+  decorators: [withStores],
+};
+
+export default preview;