biggus-dickus/docs/superpowers/plans/2026-06-03-frontend-spa-milestone-1.md

# Frontend SPA — Milestone 1 (Foundation Slice) Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** A working `web/` React SPA that lets an admin log in, browse a paginated object list, read a record (two-pane master–detail), switch sv/en, and log out — embeddable into the `server` binary via `memory-serve`.

**Architecture:** Vite + React + TypeScript SPA in `web/`, consuming the existing utoipa OpenAPI through a generated typed client (`openapi-typescript` types + `openapi-fetch`). Server state via TanStack Query; UI via shadcn/ui (Tailwind); i18n via react-i18next. Tests run in Vitest with React Testing Library and MSW (typed mock handlers). In dev, Vite proxies `/api` to the Rust server; in release, `pnpm build` output is embedded into the `server` binary behind a `embed-web` cargo feature and served at `/` with SPA fallback.

**Tech Stack:** pnpm, Vite 6, React 19, TypeScript 5, Tailwind 4 + shadcn/ui, @tanstack/react-query 5, openapi-typescript + openapi-fetch, react-i18next, Vitest + @testing-library/react + msw, Rust `memory-serve` (server crate).

**Reference spec:** `docs/superpowers/specs/2026-06-03-frontend-spa-milestone-1-design.md`

**Backend contract (verified, already shipped):**
- `POST /api/admin/login` body `{email,password}` → `204` + session cookie; bad creds → `401`.
- `POST /api/admin/logout` → `204`.
- `GET /api/admin/me` → `200 {id,email,role}` (`UserView`); no session → `401`.
- `GET /api/admin/objects?limit&offset` → `200 {items:[AdminObjectView],total,limit,offset}` (`ViewInternal`).
- `GET /api/admin/objects/{id}` → `200 AdminObjectView` | `404`.
- `GET /api/admin/field-definitions` → `200 [FieldDefinitionView]` (`{key,data_type,vocabulary_id?,authority_kind?,required,group?,labels:[{lang,label}]}`).
- `AdminObjectView` = `{id, object_number, object_name, number_of_objects, brief_description?, current_location?, current_owner?, recorder?, recording_date?, visibility:"draft"|"internal"|"public", fields: object}`.
- OpenAPI JSON served at `GET /api-docs/openapi.json`.

**Prerequisites for the implementer:**
- A running backend for `gen:api` and manual checks: `DATABASE_URL=postgres://postgres:postgres@localhost:5433/cms_dev cargo run -p server` (server on `:8080`). Create a test admin: `BOOTSTRAP_PASSWORD=pw-admin-123 cargo run -p server -- create-user --email admin@example.com --role admin`.
- Node ≥ 20, `pnpm` ≥ 9. All web commands run from `web/`.
- The codename "biggus"/"dickus" must appear NOWHERE in code, config, or text.

---

## Task 1: Scaffold `web/` (Vite + React + TS) and a green test runner

**Files:**
- Create: `web/package.json`, `web/pnpm-lock.yaml`, `web/tsconfig.json`, `web/tsconfig.node.json`, `web/vite.config.ts`, `web/index.html`, `web/src/main.tsx`, `web/src/app.tsx`, `web/src/vite-env.d.ts`
- Create test: `web/src/app.test.tsx`
- Modify: `.gitignore` (add `web/node_modules`, `web/dist`)

- [ ] **Step 1: Scaffold with Vite (non-interactive), then pin scripts**

Run from repo root:
```bash
pnpm create vite@latest web -- --template react-ts
cd web
pnpm install
pnpm add -D vitest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom
```

- [ ] **Step 2: Replace `web/package.json` scripts** so the toolchain is explicit

```json
{
  "name": "web",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "preview": "vite preview",
    "test": "vitest run",
    "test:watch": "vitest",
    "typecheck": "tsc -b --noEmit",
    "lint": "eslint .",
    "gen:api": "openapi-typescript http://localhost:8080/api-docs/openapi.json -o src/api/schema.d.ts"
  }
}
```
(Keep the `dependencies`/`devDependencies` blocks Vite generated; later tasks add to them.)

- [ ] **Step 3: Configure Vite — dev proxy + Vitest**

Replace `web/vite.config.ts`:
```ts
/// <reference types="vitest/config" />
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      "/api": "http://localhost:8080",
      "/api-docs": "http://localhost:8080",
      "/health": "http://localhost:8080",
    },
  },
  test: {
    environment: "jsdom",
    globals: true,
    setupFiles: ["./src/test/setup.ts"],
  },
});
```
Create `web/src/test/setup.ts` (filled out in Task 4; for now just jest-dom):
```ts
import "@testing-library/jest-dom/vitest";
```

- [ ] **Step 4: Write the failing test** `web/src/app.test.tsx`

```tsx
import { render, screen } from "@testing-library/react";
import { App } from "./app";

test("renders the app placeholder", () => {
  render(<App />);
  expect(screen.getByRole("heading", { name: /collection/i })).toBeInTheDocument();
});
```

- [ ] **Step 5: Run the test to verify it fails**

Run: `pnpm test`
Expected: FAIL — `./app` has no `App` export (Vite scaffolded `App.tsx`, not `app.tsx`).

- [ ] **Step 6: Replace the scaffold with a minimal app**

Delete `web/src/App.tsx`, `web/src/App.css`, `web/src/index.css`, `web/src/assets` (Vite demo cruft).

Create `web/src/app.tsx`:
```tsx
export function App() {
  return <h1>Collection</h1>;
}
```
Replace `web/src/main.tsx`:
```tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./app";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);
```
Set `web/index.html` `<title>` to `Collection` and keep `<div id="root"></div>` + the `main.tsx` module script.

- [ ] **Step 7: Run the test to verify it passes**

Run: `pnpm test`
Expected: PASS (1 test).
Run: `pnpm build`
Expected: typechecks and builds to `web/dist`.

- [ ] **Step 8: Ignore build artifacts and commit**

Append to repo-root `.gitignore`:
```
web/node_modules/
web/dist/
```
```bash
cd ..
git add web .gitignore
git commit -m "feat(web): scaffold Vite + React + TS SPA with Vitest"
```

---

## Task 2: Tailwind 4 + shadcn/ui + ESLint

**Files:**
- Create: `web/src/index.css`, `web/components.json`, `web/eslint.config.js`, `web/src/lib/utils.ts`, `web/src/components/ui/button.tsx`
- Modify: `web/vite.config.ts`, `web/src/main.tsx`, `web/tsconfig.json`, `web/package.json`

- [ ] **Step 1: Install Tailwind 4 + the Vite plugin + path alias tooling**

```bash
cd web
pnpm add -D tailwindcss @tailwindcss/vite @types/node
pnpm add class-variance-authority clsx tailwind-merge lucide-react
```

- [ ] **Step 2: Wire Tailwind into Vite and add the `@` path alias**

In `web/vite.config.ts` add the Tailwind plugin and resolve alias:
```ts
import tailwindcss from "@tailwindcss/vite";
import path from "node:path";
// plugins: [react(), tailwindcss()],
// add after plugins:
//   resolve: { alias: { "@": path.resolve(__dirname, "./src") } },
```
In `web/tsconfig.json` add under `compilerOptions`:
```json
"baseUrl": ".",
"paths": { "@/*": ["./src/*"] }
```
Create `web/src/index.css`:
```css
@import "tailwindcss";
```
Import it in `web/src/main.tsx` (add `import "./index.css";` at the top).

- [ ] **Step 3: Initialise shadcn/ui (non-interactive) and add Button**

```bash
pnpm dlx shadcn@latest init -d -b neutral
pnpm dlx shadcn@latest add button
```
This creates `components.json`, `src/lib/utils.ts`, and `src/components/ui/button.tsx`. If `init` prompts despite `-d`, accept: style "new-york", base color "neutral", CSS variables yes.

- [ ] **Step 4: Add ESLint flat config**

```bash
pnpm add -D eslint @eslint/js typescript-eslint eslint-plugin-react-hooks eslint-plugin-react-refresh globals
```
Create `web/eslint.config.js`:
```js
import js from "@eslint/js";
import globals from "globals";
import reactHooks from "eslint-plugin-react-hooks";
import reactRefresh from "eslint-plugin-react-refresh";
import tseslint from "typescript-eslint";

export default tseslint.config(
  { ignores: ["dist", "src/components/ui", "src/api/schema.d.ts"] },
  {
    extends: [js.configs.recommended, ...tseslint.configs.recommended],
    files: ["**/*.{ts,tsx}"],
    languageOptions: { ecmaVersion: 2022, globals: globals.browser },
    plugins: { "react-hooks": reactHooks, "react-refresh": reactRefresh },
    rules: { ...reactHooks.configs.recommended.rules },
  },
);
```

- [ ] **Step 5: Verify build, lint, and the Task 1 test still pass**

Run: `pnpm lint` → Expected: no errors.
Run: `pnpm test` → Expected: PASS.
Run: `pnpm build` → Expected: builds (Tailwind processed).

- [ ] **Step 6: Commit**

```bash
cd ..
git add web
git commit -m "feat(web): Tailwind 4 + shadcn/ui + ESLint"
```

---

## Task 3: Generated OpenAPI types + typed `openapi-fetch` client (401 redirect)

**Files:**
- Create: `web/src/api/schema.d.ts` (generated, committed), `web/src/api/client.ts`, `web/src/api/auth-redirect.ts`
- Test: `web/src/api/client.test.ts`
- Modify: `web/package.json`

- [ ] **Step 1: Install the client libraries and generate types from the running server**

```bash
cd web
pnpm add openapi-fetch
pnpm add -D openapi-typescript
```
Start the backend in another terminal (see Prerequisites), then:
```bash
pnpm gen:api
```
Expected: `src/api/schema.d.ts` is written with `paths` including `/api/admin/objects`, `/api/admin/me`, etc. Commit this generated file (do not gitignore it).

- [ ] **Step 2: Write the failing test** `web/src/api/client.test.ts`

```ts
import { describe, expect, test, vi, beforeEach } from "vitest";
import { server } from "../test/server";
import { http, HttpResponse } from "msw";
import { api } from "./client";
import * as redirect from "./auth-redirect";

describe("api client", () => {
  beforeEach(() => server.resetHandlers());

  test("returns typed data on success", async () => {
    server.use(
      http.get("/api/admin/me", () =>
        HttpResponse.json({ id: "u1", email: "a@b.se", role: "admin" }),
      ),
    );
    const { data, error } = await api.GET("/api/admin/me");
    expect(error).toBeUndefined();
    expect(data?.email).toBe("a@b.se");
  });

  test("a 401 triggers the auth redirect", async () => {
    const spy = vi.spyOn(redirect, "redirectToLogin").mockImplementation(() => {});
    server.use(http.get("/api/admin/me", () => new HttpResponse(null, { status: 401 })));
    await api.GET("/api/admin/me");
    expect(spy).toHaveBeenCalledOnce();
  });
});
```
(`../test/server` is created in Task 4; this test will not run until then.)

- [ ] **Step 3: Implement the client + redirect helper**

Create `web/src/api/auth-redirect.ts`:
```ts
/** Hard-navigate to login. Isolated so it can be spied/mocked in tests and swapped
 *  for a router navigation if needed. */
export function redirectToLogin(): void {
  if (window.location.pathname !== "/login") {
    window.location.assign("/login");
  }
}
```
Create `web/src/api/client.ts`:
```ts
import createClient, { type Middleware } from "openapi-fetch";
import type { paths } from "./schema";
import { redirectToLogin } from "./auth-redirect";

const onUnauthorized: Middleware = {
  async onResponse({ response }) {
    if (response.status === 401) {
      redirectToLogin();
    }
    return response;
  },
};

export const api = createClient<paths>({ credentials: "include" });
api.use(onUnauthorized);
```

- [ ] **Step 4: Run the test (after Task 4 wires MSW)**

This task's test depends on Task 4's `src/test/server.ts` + setup. Proceed to Task 4, then run:
Run: `pnpm test src/api/client.test.ts`
Expected: PASS (2 tests).

- [ ] **Step 5: Commit**

```bash
cd ..
git add web
git commit -m "feat(web): generated OpenAPI types + typed openapi-fetch client with 401 redirect"
```

---

## Task 4: MSW test harness (typed mock handlers)

**Files:**
- Create: `web/src/test/server.ts`, `web/src/test/handlers.ts`, `web/src/test/fixtures.ts`
- Modify: `web/src/test/setup.ts`
- Test: this task makes Task 3's `client.test.ts` runnable and adds a handler smoke test in `web/src/test/handlers.test.ts`

- [ ] **Step 1: Install MSW**

```bash
cd web
pnpm add -D msw
```

- [ ] **Step 2: Create typed fixtures** `web/src/test/fixtures.ts`

```ts
import type { components } from "../api/schema";

export type AdminObjectView = components["schemas"]["AdminObjectView"];
export type AdminObjectPage = components["schemas"]["AdminObjectPage"];

export const amphora: AdminObjectView = {
  id: "11111111-1111-1111-1111-111111111111",
  object_number: "LM-0042",
  object_name: "Amphora",
  number_of_objects: 1,
  brief_description: "Storage jar",
  current_location: "Vault 3",
  current_owner: null,
  recorder: null,
  recording_date: null,
  visibility: "public",
  fields: { material: "Bronze" },
};

export const fibula: AdminObjectView = {
  ...amphora,
  id: "22222222-2222-2222-2222-222222222222",
  object_number: "LM-0043",
  object_name: "Bronze fibula",
  visibility: "internal",
  fields: {},
};

export const objectsPage: AdminObjectPage = {
  items: [amphora, fibula],
  total: 2,
  limit: 50,
  offset: 0,
};
```
(If `components["schemas"]["AdminObjectView"]` is absent, open `schema.d.ts` and use the exact generated schema name; utoipa names schemas after the Rust type, so `AdminObjectView`/`AdminObjectPage` should exist.)

- [ ] **Step 3: Create default handlers** `web/src/test/handlers.ts`

```ts
import { http, HttpResponse } from "msw";
import { amphora, fibula, objectsPage } from "./fixtures";

export const handlers = [
  http.get("/api/admin/me", () =>
    HttpResponse.json({ id: "u1", email: "editor@example.com", role: "editor" }),
  ),
  http.get("/api/admin/objects", () => HttpResponse.json(objectsPage)),
  http.get("/api/admin/objects/:id", ({ params }) => {
    const found = [amphora, fibula].find((o) => o.id === params.id);
    return found ? HttpResponse.json(found) : new HttpResponse(null, { status: 404 });
  }),
  http.get("/api/admin/field-definitions", () =>
    HttpResponse.json([
      {
        key: "material",
        data_type: "term",
        vocabulary_id: "v1",
        authority_kind: null,
        required: false,
        group: null,
        labels: [{ lang: "en", label: "Material" }],
      },
    ]),
  ),
  http.post("/api/admin/login", () => new HttpResponse(null, { status: 204 })),
  http.post("/api/admin/logout", () => new HttpResponse(null, { status: 204 })),
];
```

- [ ] **Step 4: Create the server** `web/src/test/server.ts`

```ts
import { setupServer } from "msw/node";
import { handlers } from "./handlers";

export const server = setupServer(...handlers);
```

- [ ] **Step 5: Wire MSW lifecycle into the global setup** — replace `web/src/test/setup.ts`

```ts
import "@testing-library/jest-dom/vitest";
import { afterAll, afterEach, beforeAll } from "vitest";
import { server } from "./server";

beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
```

- [ ] **Step 6: Add a handler smoke test** `web/src/test/handlers.test.ts`

```ts
import { expect, test } from "vitest";
import { api } from "../api/client";

test("default handler serves the objects page", async () => {
  const { data } = await api.GET("/api/admin/objects", { params: { query: {} } });
  expect(data?.total).toBe(2);
  expect(data?.items[0].object_number).toBe("LM-0042");
});
```

- [ ] **Step 7: Run all tests (now Task 3's client test runs too)**

Run: `pnpm test`
Expected: PASS — `client.test.ts` (2) + `handlers.test.ts` (1) + `app.test.tsx` (1).

- [ ] **Step 8: Commit**

```bash
cd ..
git add web
git commit -m "test(web): MSW harness with typed handlers and fixtures"
```

---

## Task 5: i18n (react-i18next, sv/en)

**Files:**
- Create: `web/src/i18n/index.ts`, `web/src/i18n/en.json`, `web/src/i18n/sv.json`, `web/src/i18n/use-locale.ts`
- Test: `web/src/i18n/i18n.test.tsx`
- Modify: `web/src/main.tsx`

- [ ] **Step 1: Install**

```bash
cd web
pnpm add i18next react-i18next
```

- [ ] **Step 2: Translation resources** — `web/src/i18n/en.json`

```json
{
  "app": { "name": "Collection" },
  "nav": { "objects": "Objects", "vocabularies": "Vocabularies", "authorities": "Authorities", "fields": "Fields", "search": "Search", "soon": "Coming soon" },
  "auth": { "email": "Email", "password": "Password", "signIn": "Sign in", "signOut": "Sign out", "invalid": "Invalid email or password", "networkError": "Could not reach the server" },
  "objects": { "title": "Objects", "empty": "No objects yet", "loadError": "Could not load objects", "selectPrompt": "Select an object to view its details", "notFound": "Object not found", "prev": "Previous", "next": "Next", "of": "of" },
  "fieldsLabels": { "objectNumber": "Object number", "objectName": "Name", "count": "Number of objects", "briefDescription": "Brief description", "currentLocation": "Current location", "currentOwner": "Current owner", "recorder": "Recorder", "recordingDate": "Recording date", "visibility": "Visibility", "flexible": "Catalogue fields" },
  "visibility": { "draft": "Draft", "internal": "Internal", "public": "Public" }
}
```
`web/src/i18n/sv.json` (same keys, Swedish):
```json
{
  "app": { "name": "Samling" },
  "nav": { "objects": "Föremål", "vocabularies": "Vokabulär", "authorities": "Auktoriteter", "fields": "Fält", "search": "Sök", "soon": "Kommer snart" },
  "auth": { "email": "E-post", "password": "Lösenord", "signIn": "Logga in", "signOut": "Logga ut", "invalid": "Fel e-post eller lösenord", "networkError": "Kunde inte nå servern" },
  "objects": { "title": "Föremål", "empty": "Inga föremål ännu", "loadError": "Kunde inte ladda föremål", "selectPrompt": "Välj ett föremål för att se detaljer", "notFound": "Föremålet hittades inte", "prev": "Föregående", "next": "Nästa", "of": "av" },
  "fieldsLabels": { "objectNumber": "Föremålsnummer", "objectName": "Namn", "count": "Antal föremål", "briefDescription": "Kort beskrivning", "currentLocation": "Nuvarande plats", "currentOwner": "Nuvarande ägare", "recorder": "Registrerad av", "recordingDate": "Registreringsdatum", "visibility": "Synlighet", "flexible": "Katalogfält" },
  "visibility": { "draft": "Utkast", "internal": "Intern", "public": "Publik" }
}
```

- [ ] **Step 3: Init i18next** — `web/src/i18n/index.ts`

```ts
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import en from "./en.json";
import sv from "./sv.json";

export const LOCALE_KEY = "locale";
const stored = localStorage.getItem(LOCALE_KEY);
const fallback = "en";

void i18n.use(initReactI18next).init({
  resources: { en: { translation: en }, sv: { translation: sv } },
  lng: stored ?? fallback,
  fallbackLng: fallback,
  interpolation: { escapeValue: false },
});

export default i18n;
```
`web/src/i18n/use-locale.ts`:
```ts
import { useTranslation } from "react-i18next";
import i18n, { LOCALE_KEY } from "./index";

export function useLocale() {
  const { i18n: instance } = useTranslation();
  const setLocale = (lng: "en" | "sv") => {
    localStorage.setItem(LOCALE_KEY, lng);
    void i18n.changeLanguage(lng);
  };
  return { locale: instance.language, setLocale };
}
```
Add `import "./i18n";` to `web/src/main.tsx` (top, after `index.css`).

- [ ] **Step 4: Write the failing test** `web/src/i18n/i18n.test.tsx`

```tsx
import { expect, test } from "vitest";
import { render, screen, act } from "@testing-library/react";
import { useTranslation } from "react-i18next";
import "./index";
import { useLocale } from "./use-locale";

function Probe() {
  const { t } = useTranslation();
  const { setLocale } = useLocale();
  return (
    <div>
      <span data-testid="title">{t("objects.title")}</span>
      <button onClick={() => setLocale("sv")}>sv</button>
    </div>
  );
}

test("switches language at runtime", async () => {
  render(<Probe />);
  expect(screen.getByTestId("title")).toHaveTextContent("Objects");
  await act(async () => {
    screen.getByRole("button", { name: "sv" }).click();
  });
  expect(screen.getByTestId("title")).toHaveTextContent("Föremål");
});
```

- [ ] **Step 5: Run → fail → (already implemented in Step 3) → pass**

Run: `pnpm test src/i18n/i18n.test.tsx`
Expected: PASS.

- [ ] **Step 6: Commit**

```bash
cd ..
git add web
git commit -m "feat(web): i18n with react-i18next (sv/en)"
```

---

## Task 6: TanStack Query + `useMe` + session guard

**Files:**
- Create: `web/src/api/queries.ts`, `web/src/auth/require-auth.tsx`, `web/src/test/render.tsx`
- Test: `web/src/auth/require-auth.test.tsx`
- Modify: `web/src/main.tsx`

- [ ] **Step 1: Install TanStack Query + the router**

```bash
cd web
pnpm add @tanstack/react-query react-router-dom
```

- [ ] **Step 2: Query hooks** — `web/src/api/queries.ts`

```ts
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { api } from "./client";
import type { components } from "./schema";

type UserView = components["schemas"]["UserView"];

export function useMe() {
  return useQuery({
    queryKey: ["me"],
    queryFn: async (): Promise<UserView | null> => {
      const { data, response } = await api.GET("/api/admin/me");
      if (response.status === 401) return null;
      if (!data) throw new Error("failed to load session");
      return data;
    },
    retry: false,
  });
}

export function useObjectsPage(limit: number, offset: number) {
  return useQuery({
    queryKey: ["objects", { limit, offset }],
    queryFn: async () => {
      const { data, error } = await api.GET("/api/admin/objects", {
        params: { query: { limit, offset } },
      });
      if (error || !data) throw new Error("failed to load objects");
      return data;
    },
  });
}

export function useObject(id: string) {
  return useQuery({
    queryKey: ["object", id],
    queryFn: async () => {
      const { data, response } = await api.GET("/api/admin/objects/{id}", {
        params: { path: { id } },
      });
      if (response.status === 404) return null;
      if (!data) throw new Error("failed to load object");
      return data;
    },
  });
}

export function useFieldDefinitions() {
  return useQuery({
    queryKey: ["field-definitions"],
    queryFn: async () => {
      const { data, error } = await api.GET("/api/admin/field-definitions");
      if (error || !data) throw new Error("failed to load field definitions");
      return data;
    },
    staleTime: 5 * 60 * 1000,
  });
}

export function useLogin() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: async (body: { email: string; password: string }) => {
      const { response } = await api.POST("/api/admin/login", { body });
      if (response.status !== 204) {
        throw new Error(response.status === 401 ? "invalid" : "network");
      }
    },
    onSuccess: () => qc.invalidateQueries({ queryKey: ["me"] }),
  });
}

export function useLogout() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: async () => {
      await api.POST("/api/admin/logout");
    },
    onSuccess: () => qc.setQueryData(["me"], null),
  });
}
```
(Confirm the path-param style `/api/admin/objects/{id}` matches the generated `paths` keys in `schema.d.ts`; openapi-typescript keeps the `{id}` template literally.)

- [ ] **Step 3: A test render helper** — `web/src/test/render.tsx`

```tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { MemoryRouter } from "react-router-dom";
import { render } from "@testing-library/react";
import type { ReactElement } from "react";
import "../i18n";

export function renderApp(ui: ReactElement, { route = "/" } = {}) {
  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
  return render(
    <QueryClientProvider client={qc}>
      <MemoryRouter initialEntries={[route]}>{ui}</MemoryRouter>
    </QueryClientProvider>,
  );
}
```

- [ ] **Step 4: Write the failing test** `web/src/auth/require-auth.test.tsx`

```tsx
import { expect, test } from "vitest";
import { screen, waitFor } from "@testing-library/react";
import { http, HttpResponse } from "msw";
import { Routes, Route } from "react-router-dom";
import { server } from "../test/server";
import { renderApp } from "../test/render";
import { RequireAuth } from "./require-auth";

function tree() {
  return (
    <Routes>
      <Route path="/login" element={<div>login page</div>} />
      <Route element={<RequireAuth />}>
        <Route path="/objects" element={<div>secret objects</div>} />
      </Route>
    </Routes>
  );
}

test("renders children when authenticated", async () => {
  renderApp(tree(), { route: "/objects" });
  expect(await screen.findByText("secret objects")).toBeInTheDocument();
});

test("redirects to /login when unauthenticated", async () => {
  server.use(http.get("/api/admin/me", () => new HttpResponse(null, { status: 401 })));
  renderApp(tree(), { route: "/objects" });
  await waitFor(() => expect(screen.getByText("login page")).toBeInTheDocument());
});
```

- [ ] **Step 5: Implement** — `web/src/auth/require-auth.tsx`

```tsx
import { Navigate, Outlet } from "react-router-dom";
import { useMe } from "../api/queries";

export function RequireAuth() {
  const { data: user, isLoading } = useMe();
  if (isLoading) return <div role="status" aria-label="loading" />;
  if (!user) return <Navigate to="/login" replace />;
  return <Outlet />;
}
```

- [ ] **Step 6: Run the test**

Run: `pnpm test src/auth/require-auth.test.tsx`
Expected: PASS (2 tests).

- [ ] **Step 7: Commit**

```bash
cd ..
git add web
git commit -m "feat(web): TanStack Query hooks + session-guarded routes"
```

---

## Task 7: Login page (sign in / sign out)

**Files:**
- Create: `web/src/auth/login-page.tsx`
- Test: `web/src/auth/login-page.test.tsx`
- May add: shadcn `input`, `label`, `card` (`pnpm dlx shadcn@latest add input label card`)

- [ ] **Step 1: Add the shadcn primitives the form uses**

```bash
cd web
pnpm dlx shadcn@latest add input label card
```

- [ ] **Step 2: Write the failing test** `web/src/auth/login-page.test.tsx`

```tsx
import { expect, test, vi } from "vitest";
import { screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { http, HttpResponse } from "msw";
import { Routes, Route } from "react-router-dom";
import { server } from "../test/server";
import { renderApp } from "../test/render";
import { LoginPage } from "./login-page";

function tree() {
  return (
    <Routes>
      <Route path="/login" element={<LoginPage />} />
      <Route path="/objects" element={<div>objects landing</div>} />
    </Routes>
  );
}

test("successful login navigates to /objects", async () => {
  renderApp(tree(), { route: "/login" });
  await userEvent.type(screen.getByLabelText(/email/i), "editor@example.com");
  await userEvent.type(screen.getByLabelText(/password/i), "pw-editor-123");
  await userEvent.click(screen.getByRole("button", { name: /sign in/i }));
  expect(await screen.findByText("objects landing")).toBeInTheDocument();
});

test("invalid credentials show an inline error", async () => {
  server.use(http.post("/api/admin/login", () => new HttpResponse(null, { status: 401 })));
  renderApp(tree(), { route: "/login" });
  await userEvent.type(screen.getByLabelText(/email/i), "x@y.se");
  await userEvent.type(screen.getByLabelText(/password/i), "wrong");
  await userEvent.click(screen.getByRole("button", { name: /sign in/i }));
  await waitFor(() =>
    expect(screen.getByText(/invalid email or password/i)).toBeInTheDocument(),
  );
});
```

- [ ] **Step 3: Implement** — `web/src/auth/login-page.tsx`

```tsx
import { useState, type FormEvent } from "react";
import { useNavigate } from "react-router-dom";
import { useTranslation } from "react-i18next";
import { useLogin } from "../api/queries";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";

export function LoginPage() {
  const { t } = useTranslation();
  const navigate = useNavigate();
  const login = useLogin();
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");

  const onSubmit = (event: FormEvent) => {
    event.preventDefault();
    login.mutate(
      { email, password },
      { onSuccess: () => navigate("/objects", { replace: true }) },
    );
  };

  const errorKey = login.error
    ? login.error.message === "invalid"
      ? "auth.invalid"
      : "auth.networkError"
    : null;

  return (
    <div className="flex min-h-screen items-center justify-center p-4">
      <form onSubmit={onSubmit} className="w-full max-w-sm space-y-4">
        <h1 className="text-2xl font-semibold">{t("app.name")}</h1>
        <div className="space-y-2">
          <Label htmlFor="email">{t("auth.email")}</Label>
          <Input id="email" type="email" value={email}
                 onChange={(e) => setEmail(e.target.value)} autoComplete="username" />
        </div>
        <div className="space-y-2">
          <Label htmlFor="password">{t("auth.password")}</Label>
          <Input id="password" type="password" value={password}
                 onChange={(e) => setPassword(e.target.value)} autoComplete="current-password" />
        </div>
        {errorKey && <p role="alert" className="text-sm text-red-600">{t(errorKey)}</p>}
        <Button type="submit" className="w-full" disabled={login.isPending}>
          {t("auth.signIn")}
        </Button>
      </form>
    </div>
  );
}
```

- [ ] **Step 4: Run the test**

Run: `pnpm test src/auth/login-page.test.tsx`
Expected: PASS (2 tests).

- [ ] **Step 5: Commit**

```bash
cd ..
git add web
git commit -m "feat(web): login page with inline error handling"
```

---

## Task 8: App shell (sidebar + top bar + language/logout)

**Files:**
- Create: `web/src/shell/app-shell.tsx`, `web/src/shell/lang-switch.tsx`
- Test: `web/src/shell/app-shell.test.tsx`

- [ ] **Step 1: Write the failing test** `web/src/shell/app-shell.test.tsx`

```tsx
import { expect, test } from "vitest";
import { screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { Routes, Route } from "react-router-dom";
import { renderApp } from "../test/render";
import { AppShell } from "./app-shell";

function tree() {
  return (
    <Routes>
      <Route element={<AppShell />}>
        <Route path="/objects" element={<div>objects outlet</div>} />
      </Route>
      <Route path="/login" element={<div>login page</div>} />
    </Routes>
  );
}

test("shows active and disabled nav and renders the outlet", async () => {
  renderApp(tree(), { route: "/objects" });
  expect(await screen.findByText("objects outlet")).toBeInTheDocument();
  expect(screen.getByRole("link", { name: /objects/i })).toBeInTheDocument();
  // later milestones are present but disabled
  expect(screen.getByRole("button", { name: /search/i })).toBeDisabled();
});

test("language switch toggles to Swedish", async () => {
  renderApp(tree(), { route: "/objects" });
  await userEvent.click(await screen.findByRole("button", { name: "SV" }));
  await waitFor(() => expect(screen.getByText("Föremål")).toBeInTheDocument());
});
```

- [ ] **Step 2: Implement the language switch** — `web/src/shell/lang-switch.tsx`

```tsx
import { useLocale } from "../i18n/use-locale";

export function LangSwitch() {
  const { locale, setLocale } = useLocale();
  const base = locale.startsWith("sv") ? "sv" : "en";
  return (
    <div className="flex gap-1 text-xs">
      {(["sv", "en"] as const).map((lng) => (
        <button key={lng} onClick={() => setLocale(lng)}
                aria-pressed={base === lng}
                className={base === lng ? "font-bold" : "text-neutral-400"}>
          {lng.toUpperCase()}
        </button>
      ))}
    </div>
  );
}
```

- [ ] **Step 3: Implement the shell** — `web/src/shell/app-shell.tsx`

```tsx
import { NavLink, Outlet, useNavigate } from "react-router-dom";
import { useTranslation } from "react-i18next";
import { useLogout } from "../api/queries";
import { LangSwitch } from "./lang-switch";
import { Button } from "@/components/ui/button";

const FUTURE = ["vocabularies", "authorities", "fields", "search"] as const;

export function AppShell() {
  const { t } = useTranslation();
  const navigate = useNavigate();
  const logout = useLogout();

  const onSignOut = () =>
    logout.mutate(undefined, { onSuccess: () => navigate("/login", { replace: true }) });

  return (
    <div className="flex min-h-screen">
      <aside className="w-44 shrink-0 border-r bg-neutral-50 p-3">
        <div className="mb-4 font-semibold">{t("app.name")}</div>
        <nav className="space-y-1 text-sm">
          <NavLink to="/objects"
            className={({ isActive }) =>
              `block rounded px-2 py-1 ${isActive ? "bg-neutral-200 font-medium" : ""}`}>
            {t("nav.objects")}
          </NavLink>
          {FUTURE.map((key) => (
            <button key={key} disabled title={t("nav.soon")}
              className="block w-full cursor-not-allowed rounded px-2 py-1 text-left text-neutral-400">
              {t(`nav.${key}`)}
            </button>
          ))}
        </nav>
      </aside>
      <div className="flex flex-1 flex-col">
        <header className="flex items-center gap-4 border-b px-4 py-2">
          <div className="flex-1" />
          <LangSwitch />
          <Button variant="ghost" size="sm" onClick={onSignOut}>
            {t("auth.signOut")}
          </Button>
        </header>
        <main className="flex-1 overflow-hidden">
          <Outlet />
        </main>
      </div>
    </div>
  );
}
```

- [ ] **Step 4: Run the test**

Run: `pnpm test src/shell/app-shell.test.tsx`
Expected: PASS (2 tests).

- [ ] **Step 5: Commit**

```bash
cd ..
git add web
git commit -m "feat(web): app shell with sidebar nav, language switch, sign out"
```

---

## Task 9: Objects list (left pane) + visibility badge

**Files:**
- Create: `web/src/objects/visibility-badge.tsx`, `web/src/objects/object-list.tsx`
- Test: `web/src/objects/object-list.test.tsx`
- May add shadcn `badge`, `skeleton` (`pnpm dlx shadcn@latest add badge skeleton`)

- [ ] **Step 1: Add primitives**

```bash
cd web
pnpm dlx shadcn@latest add badge skeleton
```

- [ ] **Step 2: Write the failing test** `web/src/objects/object-list.test.tsx`

```tsx
import { expect, test } from "vitest";
import { screen } from "@testing-library/react";
import { http, HttpResponse } from "msw";
import { Routes, Route } from "react-router-dom";
import { server } from "../test/server";
import { renderApp } from "../test/render";
import { ObjectList } from "./object-list";

function tree() {
  return (
    <Routes>
      <Route path="/objects" element={<ObjectList />} />
      <Route path="/objects/:id" element={<ObjectList />} />
    </Routes>
  );
}

test("renders object rows with number, name and visibility", async () => {
  renderApp(tree(), { route: "/objects" });
  expect(await screen.findByText("LM-0042")).toBeInTheDocument();
  expect(screen.getByText("Amphora")).toBeInTheDocument();
  expect(screen.getByText("Public")).toBeInTheDocument();
});

test("shows an empty state when there are no objects", async () => {
  server.use(
    http.get("/api/admin/objects", () =>
      HttpResponse.json({ items: [], total: 0, limit: 50, offset: 0 }),
    ),
  );
  renderApp(tree(), { route: "/objects" });
  expect(await screen.findByText(/no objects yet/i)).toBeInTheDocument();
});

test("shows an error state on failure", async () => {
  server.use(
    http.get("/api/admin/objects", () => new HttpResponse(null, { status: 500 })),
  );
  renderApp(tree(), { route: "/objects" });
  expect(await screen.findByText(/could not load objects/i)).toBeInTheDocument();
});
```

- [ ] **Step 3: Implement the badge** — `web/src/objects/visibility-badge.tsx`

```tsx
import { useTranslation } from "react-i18next";
import { Badge } from "@/components/ui/badge";

const STYLES: Record<string, string> = {
  draft: "bg-neutral-100 text-neutral-600",
  internal: "bg-amber-100 text-amber-800",
  public: "bg-green-100 text-green-800",
};

export function VisibilityBadge({ visibility }: { visibility: string }) {
  const { t } = useTranslation();
  return (
    <Badge variant="outline" className={STYLES[visibility] ?? ""}>
      {t(`visibility.${visibility}`)}
    </Badge>
  );
}
```

- [ ] **Step 4: Implement the list** — `web/src/objects/object-list.tsx`

```tsx
import { NavLink, useParams } from "react-router-dom";
import { useState } from "react";
import { useTranslation } from "react-i18next";
import { useObjectsPage } from "../api/queries";
import { VisibilityBadge } from "./visibility-badge";
import { Skeleton } from "@/components/ui/skeleton";
import { Button } from "@/components/ui/button";

const LIMIT = 50;

export function ObjectList() {
  const { t } = useTranslation();
  const { id: selectedId } = useParams();
  const [offset, setOffset] = useState(0);
  const { data, isLoading, isError } = useObjectsPage(LIMIT, offset);

  if (isLoading) {
    return (
      <div className="space-y-2 p-3">
        {Array.from({ length: 6 }).map((_, i) => <Skeleton key={i} className="h-9 w-full" />)}
      </div>
    );
  }
  if (isError) return <p className="p-4 text-sm text-red-600">{t("objects.loadError")}</p>;
  if (!data || data.items.length === 0) {
    return <p className="p-4 text-sm text-neutral-500">{t("objects.empty")}</p>;
  }

  const from = data.total === 0 ? 0 : offset + 1;
  const to = Math.min(offset + LIMIT, data.total);

  return (
    <div className="flex h-full flex-col">
      <ul className="flex-1 overflow-auto">
        {data.items.map((object) => (
          <li key={object.id}>
            <NavLink to={`/objects/${object.id}`}
              className={`flex items-center justify-between gap-2 border-b px-3 py-2 text-sm ${
                object.id === selectedId ? "bg-indigo-50" : "hover:bg-neutral-50"}`}>
              <span className="truncate">
                <span className="text-neutral-500">{object.object_number}</span>{" "}
                {object.object_name}
              </span>
              <VisibilityBadge visibility={object.visibility} />
            </NavLink>
          </li>
        ))}
      </ul>
      <div className="flex items-center justify-between border-t px-3 py-2 text-xs text-neutral-500">
        <span>{from}–{to} {t("objects.of")} {data.total}</span>
        <span className="flex gap-2">
          <Button variant="ghost" size="sm" disabled={offset === 0}
                  onClick={() => setOffset(Math.max(0, offset - LIMIT))}>
            {t("objects.prev")}
          </Button>
          <Button variant="ghost" size="sm" disabled={to >= data.total}
                  onClick={() => setOffset(offset + LIMIT)}>
            {t("objects.next")}
          </Button>
        </span>
      </div>
    </div>
  );
}
```

- [ ] **Step 5: Run the test**

Run: `pnpm test src/objects/object-list.test.tsx`
Expected: PASS (3 tests).

- [ ] **Step 6: Commit**

```bash
cd ..
git add web
git commit -m "feat(web): paginated object list with visibility badges and states"
```

---

## Task 10: Object detail (right pane) + two-pane page + routing

**Files:**
- Create: `web/src/objects/object-detail.tsx`, `web/src/objects/objects-page.tsx`
- Test: `web/src/objects/object-detail.test.tsx`, `web/src/objects/objects-page.test.tsx`

- [ ] **Step 1: Write the failing detail test** `web/src/objects/object-detail.test.tsx`

```tsx
import { expect, test } from "vitest";
import { screen } from "@testing-library/react";
import { http, HttpResponse } from "msw";
import { Routes, Route } from "react-router-dom";
import { server } from "../test/server";
import { renderApp } from "../test/render";
import { ObjectDetail } from "./object-detail";

function tree() {
  return (
    <Routes>
      <Route path="/objects/:id" element={<ObjectDetail />} />
    </Routes>
  );
}

test("renders inventory-minimum fields, flexible values and visibility", async () => {
  renderApp(tree(), { route: "/objects/11111111-1111-1111-1111-111111111111" });
  expect(await screen.findByText("Amphora")).toBeInTheDocument();
  expect(screen.getByText("Vault 3")).toBeInTheDocument();
  expect(screen.getByText("Bronze")).toBeInTheDocument(); // flexible field value
  expect(screen.getByText("Public")).toBeInTheDocument();
});

test("shows a not-found state for a missing object", async () => {
  server.use(http.get("/api/admin/objects/:id", () => new HttpResponse(null, { status: 404 })));
  renderApp(tree(), { route: "/objects/does-not-exist" });
  expect(await screen.findByText(/object not found/i)).toBeInTheDocument();
});
```

- [ ] **Step 2: Implement the detail** — `web/src/objects/object-detail.tsx`

```tsx
import { useParams } from "react-router-dom";
import { useTranslation } from "react-i18next";
import { useObject, useFieldDefinitions } from "../api/queries";
import { VisibilityBadge } from "./visibility-badge";
import { Skeleton } from "@/components/ui/skeleton";

function Field({ label, value }: { label: string; value: string | number | null | undefined }) {
  if (value === null || value === undefined || value === "") return null;
  return (
    <div className="border-b py-2">
      <div className="text-xs uppercase tracking-wide text-neutral-400">{label}</div>
      <div className="text-sm text-neutral-900">{value}</div>
    </div>
  );
}

export function ObjectDetail() {
  const { t } = useTranslation();
  const { id } = useParams();
  const { data: object, isLoading, isError } = useObject(id!);
  const { data: definitions } = useFieldDefinitions();

  if (isLoading) return <div className="p-4"><Skeleton className="h-40 w-full" /></div>;
  if (isError) return <p className="p-4 text-sm text-red-600">{t("objects.loadError")}</p>;
  if (!object) return <p className="p-4 text-sm text-neutral-500">{t("objects.notFound")}</p>;

  const labelFor = (key: string) =>
    definitions?.find((d) => d.key === key)?.labels.find((l) => l.lang === "en")?.label ?? key;
  const flexible = Object.entries(object.fields ?? {});

  return (
    <div className="overflow-auto p-4">
      <div className="mb-4 flex items-center gap-3">
        <h2 className="text-xl font-semibold">{object.object_name}</h2>
        <VisibilityBadge visibility={object.visibility} />
      </div>
      <Field label={t("fieldsLabels.objectNumber")} value={object.object_number} />
      <Field label={t("fieldsLabels.count")} value={object.number_of_objects} />
      <Field label={t("fieldsLabels.briefDescription")} value={object.brief_description} />
      <Field label={t("fieldsLabels.currentLocation")} value={object.current_location} />
      <Field label={t("fieldsLabels.currentOwner")} value={object.current_owner} />
      <Field label={t("fieldsLabels.recorder")} value={object.recorder} />
      <Field label={t("fieldsLabels.recordingDate")} value={object.recording_date} />
      {flexible.length > 0 && (
        <div className="mt-4">
          <div className="mb-1 text-xs font-medium uppercase text-neutral-500">
            {t("fieldsLabels.flexible")}
          </div>
          {flexible.map(([key, value]) => (
            <Field key={key} label={labelFor(key)}
                   value={typeof value === "object" ? JSON.stringify(value) : String(value)} />
          ))}
        </div>
      )}
    </div>
  );
}
```

- [ ] **Step 3: Write the failing two-pane test** `web/src/objects/objects-page.test.tsx`

```tsx
import { expect, test } from "vitest";
import { screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { Routes, Route } from "react-router-dom";
import { renderApp } from "../test/render";
import { ObjectsPage } from "./objects-page";

function tree() {
  return (
    <Routes>
      <Route path="/objects" element={<ObjectsPage />} />
      <Route path="/objects/:id" element={<ObjectsPage />} />
    </Routes>
  );
}

test("selecting a row shows its detail in the right pane", async () => {
  renderApp(tree(), { route: "/objects" });
  expect(await screen.findByText(/select an object/i)).toBeInTheDocument();
  await userEvent.click(screen.getByText("Amphora"));
  expect(await screen.findByRole("heading", { name: "Amphora" })).toBeInTheDocument();
});
```

- [ ] **Step 4: Implement the two-pane page** — `web/src/objects/objects-page.tsx`

```tsx
import { useParams } from "react-router-dom";
import { useTranslation } from "react-i18next";
import { ObjectList } from "./object-list";
import { ObjectDetail } from "./object-detail";

export function ObjectsPage() {
  const { t } = useTranslation();
  const { id } = useParams();
  return (
    <div className="grid h-full grid-cols-[20rem_1fr]">
      <div className="overflow-hidden border-r">
        <ObjectList />
      </div>
      <div className="overflow-hidden">
        {id ? (
          <ObjectDetail />
        ) : (
          <div className="flex h-full items-center justify-center p-4 text-sm text-neutral-400">
            {t("objects.selectPrompt")}
          </div>
        )}
      </div>
    </div>
  );
}
```

- [ ] **Step 5: Wire the router** — replace `web/src/app.tsx`

```tsx
import { BrowserRouter, Navigate, Route, Routes } from "react-router-dom";
import { RequireAuth } from "./auth/require-auth";
import { LoginPage } from "./auth/login-page";
import { AppShell } from "./shell/app-shell";
import { ObjectsPage } from "./objects/objects-page";

export function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/login" element={<LoginPage />} />
        <Route element={<RequireAuth />}>
          <Route element={<AppShell />}>
            <Route path="/objects" element={<ObjectsPage />} />
            <Route path="/objects/:id" element={<ObjectsPage />} />
            <Route path="/" element={<Navigate to="/objects" replace />} />
          </Route>
        </Route>
        <Route path="*" element={<Navigate to="/objects" replace />} />
      </Routes>
    </BrowserRouter>
  );
}
```
Update `web/src/main.tsx` to wrap `<App/>` in `QueryClientProvider`:
```tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { App } from "./app";
import "./index.css";
import "./i18n";

const queryClient = new QueryClient({
  defaultOptions: { queries: { retry: false, refetchOnWindowFocus: false } },
});

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </StrictMode>,
);
```
Update `web/src/app.test.tsx` (the Task 1 smoke test) — `App` now renders the router and immediately fetches `/me`; assert the login or objects landing instead:
```tsx
import { render, screen } from "@testing-library/react";
import { App } from "./app";
import "./i18n";

test("mounts and routes to a known screen", async () => {
  render(<App />);
  expect(await screen.findByText(/object|föremål|sign in|logga in/i)).toBeInTheDocument();
});
```

- [ ] **Step 6: Run the full suite + typecheck + lint + build**

Run: `pnpm test` → Expected: all PASS.
Run: `pnpm typecheck` → Expected: clean.
Run: `pnpm lint` → Expected: clean.
Run: `pnpm build` → Expected: builds to `web/dist`.

- [ ] **Step 7: Manual smoke against the real server (optional but recommended)**

With the backend running and a user created, run `pnpm dev`, open `http://localhost:5173`, log in, browse, open a record, switch language, sign out.

- [ ] **Step 8: Commit**

```bash
cd ..
git add web
git commit -m "feat(web): object detail + two-pane page + app routing"
```

---

## Task 11: Embed the SPA into the server binary (`memory-serve`, feature-gated)

**Files:**
- Modify: `crates/server/Cargo.toml`, `crates/server/src/lib.rs`, `Cargo.toml` (workspace dep)
- Create: `crates/server/src/web_assets.rs`
- Test: `crates/server/tests/embed.rs`

- [ ] **Step 1: Add `memory-serve` as an optional workspace dependency**

In root `Cargo.toml` `[workspace.dependencies]` add:
```toml
memory-serve = "1"
```
(Use `gateway_invoke(server="cargo-mcp", ...)`/`cratesio` to confirm the current major version and the exact `MemoryServe`/`load_assets!` API before pinning; adapt the code below to the resolved version.)

In `crates/server/Cargo.toml`:
```toml
[dependencies]
memory-serve = { workspace = true, optional = true }

[features]
embed-web = ["dep:memory-serve"]
```

- [ ] **Step 2: Create the assets module** — `crates/server/src/web_assets.rs`

```rust
//! Serves the embedded SPA (built `web/dist`) at `/` with a client-side-routing
//! fallback. Compiled only with the `embed-web` feature; in dev the SPA is served by
//! Vite (which proxies `/api` to this server), so this module is absent.

use axum::Router;
use memory_serve::{load_assets, MemoryServe};

/// A router that serves the embedded `web/dist` assets, falling back to `index.html`
/// for unknown paths so the SPA can own client-side routes.
pub fn routes() -> Router {
    MemoryServe::new(load_assets!("../../web/dist"))
        .index_file(Some("/index.html"))
        .fallback(Some("/index.html"))
        .into_router()
}
```
(`load_assets!` resolves its path relative to `CARGO_MANIFEST_DIR` = `crates/server`; `../../web/dist` points at the repo-root build output. Confirm the builder method names against the resolved `memory-serve` version and adjust.)

- [ ] **Step 3: Merge the assets router when the feature is on** — in `crates/server/src/lib.rs`

Add near the top:
```rust
#[cfg(feature = "embed-web")]
mod web_assets;
```
In `serve`, after `let app = build_app(state);`, merge the SPA routes (feature-gated) so API routes take precedence and everything else falls through to the SPA:
```rust
    let app = build_app(state);

    #[cfg(feature = "embed-web")]
    let app = app.merge(web_assets::routes());
```
(Keep the rest of `serve` unchanged.)

- [ ] **Step 4: Write the failing test** — `crates/server/tests/embed.rs`

```rust
//! Only meaningful with `--features embed-web` and a built `web/dist`. Skips itself
//! (passes trivially) when the feature is off.
#![cfg(feature = "embed-web")]

use axum::body::Body;
use axum::http::{Request, StatusCode};
use http_body_util::BodyExt;
use tower::ServiceExt;

#[tokio::test]
async fn serves_index_at_root_and_spa_fallback() {
    let app = server::test_support::web_router();

    let root = app
        .clone()
        .oneshot(Request::builder().uri("/").body(Body::empty()).unwrap())
        .await
        .unwrap();
    assert_eq!(root.status(), StatusCode::OK);
    let body = root.into_body().collect().await.unwrap().to_bytes();
    assert!(String::from_utf8_lossy(&body).contains("<div id=\"root\">"));

    // unknown client route falls back to index.html (not 404)
    let deep = app
        .oneshot(Request::builder().uri("/objects/123").body(Body::empty()).unwrap())
        .await
        .unwrap();
    assert_eq!(deep.status(), StatusCode::OK);
}
```
Expose a tiny test hook in `crates/server/src/lib.rs` (feature-gated):
```rust
#[cfg(feature = "embed-web")]
pub mod test_support {
    /// The SPA-asset router, for tests.
    pub fn web_router() -> axum::Router {
        super::web_assets::routes()
    }
}
```

- [ ] **Step 5: Build the SPA, then run the feature-gated test**

```bash
cd web && pnpm install && pnpm build && cd ..
DATABASE_URL='postgres://postgres:postgres@localhost:5433/cms_dev' \
  cargo test -p server --features embed-web --test embed
```
Expected: PASS — index served at `/`, `/objects/123` falls back to index.

- [ ] **Step 6: Confirm the default (no-feature) build/test is unaffected**

```bash
DATABASE_URL='postgres://postgres:postgres@localhost:5433/cms_dev' cargo test -p server
```
Expected: PASS, and compiles without `web/dist` present (the module + test are `#[cfg(feature = "embed-web")]`).

- [ ] **Step 7: fmt, clippy, commit**

```bash
cargo +nightly fmt
DATABASE_URL='postgres://postgres:postgres@localhost:5433/cms_dev' \
  cargo clippy -p server --features embed-web --all-targets -- -D warnings
git add crates/server Cargo.toml Cargo.lock
git commit -m "feat(server): embed SPA via memory-serve behind embed-web feature"
```

---

## Task 12: Web CI job + bundle-size budget

**Files:**
- Create: `web/scripts/check-bundle-size.mjs`
- Modify: `.gitea/workflows/<existing CI workflow>.yaml` (add a `web` job; inspect the existing workflow filename first)

- [ ] **Step 1: Bundle-size gate script** — `web/scripts/check-bundle-size.mjs`

```js
// Fails if the largest built JS entry chunk exceeds the gzipped budget.
import { readdirSync, readFileSync } from "node:fs";
import { gzipSync } from "node:zlib";
import { join } from "node:path";

const BUDGET_KB = 150;
const dir = "dist/assets";
const jsFiles = readdirSync(dir).filter((f) => f.endsWith(".js"));
let largest = 0;
let largestName = "";
for (const file of jsFiles) {
  const gz = gzipSync(readFileSync(join(dir, file))).length;
  if (gz > largest) { largest = gz; largestName = file; }
}
const kb = (largest / 1024).toFixed(1);
console.log(`largest JS chunk: ${largestName} = ${kb} KB gz (budget ${BUDGET_KB} KB)`);
if (largest > BUDGET_KB * 1024) {
  console.error(`bundle-size budget exceeded: ${kb} KB > ${BUDGET_KB} KB`);
  process.exit(1);
}
```
Add to `web/package.json` scripts: `"check:size": "node scripts/check-bundle-size.mjs"`.

- [ ] **Step 2: Run it locally after a build**

```bash
cd web && pnpm build && pnpm check:size
```
Expected: prints the chunk size and exits 0 (under 150 KB). If over, code-split (lazy-load routes via `React.lazy`) until under budget, then re-run.

- [ ] **Step 3: Add the CI job** — in the existing `.gitea/workflows` CI file, add:

```yaml
  web:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: web
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with: { version: 9 }
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: pnpm, cache-dependency-path: web/pnpm-lock.yaml }
      - run: pnpm install --frozen-lockfile
      - run: pnpm typecheck
      - run: pnpm lint
      - run: pnpm test
      - run: pnpm build
      - run: pnpm check:size
```
(Match the existing workflow's runner/style; first read the current `.gitea/workflows/*.yaml` to follow its conventions. `gen:api` is NOT run in CI — the committed `schema.d.ts` is the source of truth there.)

- [ ] **Step 4: Commit**

```bash
cd ..
git add web .gitea
git commit -m "ci(web): typecheck/lint/test/build + bundle-size budget"
```

---

## Self-Review (completed)

**Spec coverage:**
- Scaffold + build/dev/serve → Tasks 1, 2, 11. ✓
- Typed client (openapi-typescript + openapi-fetch, 401 redirect) → Task 3. ✓
- TanStack Query hooks (me/objects/object/field-defs/login/logout) → Task 6. ✓
- App shell (icon/sidebar nav, disabled future items, sv/en switch, logout) → Task 8. ✓
- Login + session guard → Tasks 6, 7. ✓
- Two-pane Objects (paginated list + read-only detail + visibility badge) → Tasks 9, 10. ✓
- i18n sv/en → Task 5. ✓
- States/errors (loading/empty/error/404/invalid-creds) → Tasks 7, 9, 10. ✓
- Testing Vitest+RTL+MSW → Tasks 4–10. ✓
- memory-serve embed behind `embed-web`, backend tests independent of build → Task 11. ✓
- CI + bundle budget (≤150 KB gz) → Task 12. ✓

**Placeholder scan:** none — every code step shows complete code; the two "confirm against resolved version" notes (memory-serve API, generated schema names) are verification instructions, not deferred work, with concrete adapt-to-reality guidance.

**Type consistency:** `api` client + `paths`/`components` from `schema.d.ts` used uniformly; hooks `useMe`/`useObjectsPage`/`useObject`/`useFieldDefinitions`/`useLogin`/`useLogout` defined in Task 6 and consumed in 7–10; `VisibilityBadge`, `renderApp`, `server` (MSW) consistent across tasks; route shape `/objects` + `/objects/:id` consistent in Tasks 9, 10.

## Notes for follow-on milestones
- Object create/edit/delete + dynamic flexible-field forms (Milestone 2) — reuse the typed client, query hooks, and shadcn form primitives.
- Publishing workflow surfacing the required-field 422 (Milestone 3).
- Playwright e2e smoke once a `--seed` dataset exists (relates to issue #14).
- Detail currently renders flexible object/array values as JSON; typed rendering (term/authority label resolution) lands with the authoring/forms milestone.