From 9a282dda869fc01c22131b86380c4dd6d8644bca Mon Sep 17 00:00:00 2001
From: LyAhn <admin@jezz.wtf>
Date: Sun, 5 Jul 2026 20:48:16 +0100
Subject: [PATCH] docs(claude): document UI Lab, Playwright e2e tests, and
 tooling scripts

CLAUDE.md still claimed no test suites existed. Update it for the
current repo state:

- add pnpm test:e2e commands (full run, single file, single test) and
  note the suite runs against UI Lab mocks, not the Tauri app
- new UI Lab section: src/dev mock layer, ?scenario=/?changelog= params,
  mediaSrc rule, and the mockBackend requirement for new commands
- add dev:ui and format:all to the command list
- note website/ as a separate Vite project and document the
  changelog:add script syntax
---
 CLAUDE.md | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 763c895..b1ec28a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -15,6 +15,9 @@ pnpm dev:app
 # Frontend only (no Tauri window)
 pnpm dev:vite
 
+# UI Lab — browser-only frontend with mocked Tauri backend (http://127.0.0.1:1422)
+pnpm dev:ui
+
 # Production build (CPU)
 pnpm build:app:cpu
 
@@ -23,11 +26,19 @@ pnpm build:app:cuda
 
 # Type-check frontend
 pnpm build:vite
+
+# E2E tests (Playwright against the UI Lab; auto-starts the server)
+pnpm test:e2e
+pnpm exec playwright test tests/ui-lab.spec.ts        # single file
+pnpm exec playwright test -g "filename search"        # single test by name
+
+# Formatting (Prettier + prettier-plugin-tailwindcss; cargo fmt for Rust)
+pnpm format:all
 ```
 
 Use **pnpm** — never npm.
 
-There are no test suites configured.
+The only tests are the Playwright e2e smoke tests in `tests/`, which run against the UI Lab (browser mocks), not the real Tauri app. There are no unit tests.
 
 ## Architecture
 
@@ -42,6 +53,16 @@ There are no test suites configured.
 - Virtualized gallery grid: `@tanstack/react-virtual`.
 - Animation: `framer-motion`.
 
+### UI Lab (`src/dev/`)
+
+`pnpm dev:ui` runs the real frontend (same `App.tsx`, store, components, CSS) in a plain browser with Tauri fully mocked — no Rust backend or Tauri window. `src/main.tsx` imports `src/dev/setupMockTauri.ts` before `App` in `ui` mode; `mockBackend.ts` implements an in-memory command backend, with fixtures in `mockFixtures.ts`/`mockScenarios.ts`. Pick a seeded state via `?scenario=` (`rich` default; also `empty`, `new-user`, `just-updated`, `busy`, `duplicates`, `album`, `errors`, `huge`) and a What's New entry via `?changelog=`. `Ctrl+Shift+D` opens the demo panel. Full guide: `docs/ui-lab.md`.
+
+Rules that keep UI Lab working:
+- Components that render thumbnails/covers/posters must use `mediaSrc(...)` from `src/lib/mediaSrc.ts`, never `convertFileSrc(...)` directly.
+- New Tauri commands invoked from the frontend need a mock in `src/dev/mockBackend.ts` (unmocked commands log console errors, which fail the e2e tests).
+
+UI Lab is for visual/layout work and agent browser inspection. Native behavior (file pickers, real thumbnails, window controls, updater) must still be validated in `pnpm dev:app`.
+
 ### Search modes
 
 The search bar supports prefix syntax parsed by `parseSearchValue` in `src/store/helpers.ts`:
@@ -98,3 +119,5 @@ Database: SQLite with WAL mode, stored in the Tauri app data directory as `galle
 - ML inference crates (`candle-*`, `ort`, `image`, `rayon`, `tokenizers`, `xxhash-rust`, `rusqlite`) use `opt-level = 3` in dev profile to keep inference performance acceptable.
 - The caption worker is intentionally disabled (`lib.rs:73`) — the backend code is intact for future re-enabling.
 - **Never use `any` type** in TypeScript — look up correct types.
+- `website/` is a separate Vite project for the marketing site (phokus.jezz.wtf): `pnpm dev:web` / `pnpm build:web`. It is not part of the app build.
+- `pnpm changelog:add -- --type fixed --message "..."` appends an entry to the `[Unreleased]` section of `CHANGELOG.md`, which also feeds the in-app What's New modal (types: added, changed, deprecated, removed, fixed, security).