@marianmeres/stuic 3.113.0 → 3.115.0

package/docs/component-testing/01-framework-setup.md

@@ -0,0 +1,164 @@
+<!--
+GENERATED ANALYSIS — @marianmeres/stuic real-browser component testing
+Produced 2026-06-08 by multi-agent research → adversarial verify → synthesize.
+Claims verified against the codebase at commit cc9958b and the live Vitest 4 docs.
+Planning artifact; no code was changed.
+-->
+
+# Framework Setup
+
+> This is the infrastructure dimension: the one-time work that turns "no DOM, no `$effect`"
+> into a working browser test harness. The single most important takeaway: **a Vitest
+> `projects` split routed by filename** (`*.test.ts` → fast node, `*.svelte.test.ts` → real
+> browser) keeps the 9 existing suites untouched while adding component tests on top. The one
+> hard prerequisite is a **vitest 3 → 4 major upgrade** — `vitest-browser-svelte@^2` peer-requires
+> `vitest ^4`, and Browser Mode only became *stable* in Vitest 4.
+
+## Current state (verified at `cc9958b`)
+
+- **Package manager:** pnpm. **Svelte:** 5.56.2. **SvelteKit:** 2.63.0 (adapter-auto). **Vitest:** 3.2.6.
+- **Test config:** none dedicated. Vitest is configured only implicitly through
+  [`vite.config.ts`](../../vite.config.ts) (`plugins: [tailwindcss(), sveltekit()]`), and the
+  script is `"test": "vitest --dir src/"`.
+- **What runs today:** 9 suites / ~59 tests, all **node environment, pure logic** — validation
+  helpers, stack classes (`NotificationsStack`, `AlertConfirmPromptStack`), `tr`, `replace-map`,
+  `storage-abstraction`, `checkout-utils`, `max-height`, `phone-validation`. Zero component tests.
+- **Why components can't be tested today:** the `@sveltejs/kit/vite` plugin makes Vitest resolve
+  Svelte's **server (SSR) build** in node, so components render as strings and `$effect` / actions /
+  lifecycle never run (documented in project memory; an `$effect.root` + `flushSync` probe left the
+  effect body unrun even with `resolve.conditions: ['browser']`). Real-browser mode fixes this by
+  resolving the **client build** and running in an actual Chromium page.
+- **No CI** (`.github/` absent). No browser-testing deps installed.
+
+## Target state
+
+A two-project Vitest config. Tests are routed purely by filename:
+
+| Project | Environment | Matches | Runs |
+|---------|-------------|---------|------|
+| `server` | `node` | `src/**/*.test.ts` (excl. `*.svelte.test.ts`) | the existing 9 pure-logic suites — unchanged, fast |
+| `client` | real browser (Chromium via Playwright) | `src/**/*.svelte.test.ts` | new component tests with DOM, `$effect`, layout, focus |
+
+## Step 1 — Upgrade Vitest 3 → 4 (own commit, gating)
+
+```bash
+pnpm add -D vitest@^4
+pnpm test          # confirm the 9 existing suites still pass before touching anything else
+```
+
+Vitest 4 breaking changes that touch this repo (budget for them):
+
+1. **Browser providers are separate packages now** — there is no built-in `@vitest/browser` provider; you install `@vitest/browser-playwright` (Step 2).
+2. **Browser context import moved** — `@vitest/browser/context` → `vitest/browser` (only matters if/when we import `page`, `userEvent`, etc. directly; not needed for the basics).
+3. `test.workspace` is deprecated in favour of `test.projects` (we use `projects` from the start).
+
+> **Risk:** an incidental break in the 9 node suites during the bump. Mitigation: this is its own
+> commit; if `pnpm test` regresses, fix or revert before any browser work. Verify against
+> `@sveltejs/vite-plugin-svelte@6.2.4` and `@tailwindcss/vite` — both are Vite-7-era and compatible
+> with Vitest 4, but confirm the dev server (`pnpm dev`) and `pnpm build` still work after the bump.
+
+## Step 2 — Add browser deps + Chromium
+
+```bash
+pnpm add -D @vitest/browser-playwright vitest-browser-svelte playwright
+pnpm exec playwright install chromium     # without this, browser tests fail: "No browsers found"
+```
+
+We do **not** install `@vitest/browser` directly (pulled in transitively by the provider), and we
+do **not** need `@testing-library/svelte` or `@testing-library/jest-dom` — `vitest-browser-svelte`'s
+`render()` + `expect.element` replace both.
+
+## Step 3 — The `projects` config
+
+Add a `test` block to [`vite.config.ts`](../../vite.config.ts) (keep the file; just extend it).
+Verified against the live Vitest 4 docs (`provider: playwright()` is an imported **function**, not
+the old `'playwright'` string; `instances` is required):
+
+```ts
+/// <reference types="node" />
+import { sveltekit } from "@sveltejs/kit/vite";
+import { defineConfig } from "vitest/config";
+import tailwindcss from "@tailwindcss/vite";
+import { playwright } from "@vitest/browser-playwright";
+import dotenv from "dotenv";
+
+dotenv.config();
+
+export default defineConfig({
+	plugins: [tailwindcss(), sveltekit()],
+	server: {
+		port: parseInt(process.env.DEV_PORT || "8886"),
+		host: true,
+	},
+	test: {
+		projects: [
+			{
+				extends: true, // inherit root plugins (tailwind + sveltekit)
+				test: {
+					name: "server",
+					environment: "node",
+					include: ["src/**/*.test.ts"],
+					exclude: ["src/**/*.svelte.test.ts"],
+				},
+			},
+			{
+				extends: true,
+				test: {
+					name: "client",
+					include: ["src/**/*.svelte.test.ts"],
+					setupFiles: ["vitest-browser-svelte"],
+					testTimeout: 2000,
+					browser: {
+						enabled: true,
+						headless: true,
+						provider: playwright(),
+						instances: [{ browser: "chromium" }],
+					},
+				},
+			},
+		],
+	},
+});
+```
+
+Why this shape:
+
+- **`extends: true`** makes each project inherit the root `plugins` array, so both the `tailwindcss()`
+  (component CSS / variant classes resolve — several STUIC components assert on variant/size class
+  output) and `sveltekit()` plugins apply. In the `client` project Vitest builds for the browser, so
+  the **client** Svelte build is used and `$effect`/actions run — the exact thing the node setup can't do.
+- **The filename glob is the routing mechanism** and the single most important config decision. Note
+  `src/**/*.test.ts` *also* matches `foo.svelte.test.ts` (it ends in `.test.ts`), so the server
+  project's `exclude` is **required**, not optional.
+- **`setupFiles: ['vitest-browser-svelte']`** is the entire setup — it registers auto-cleanup and
+  helpers. Browser mode eliminates the 60–250-line jsdom API-mock setup files older guides used.
+- **`headless: true`** for CI; drop it (or `--browser.headless=false`) locally to watch tests run.
+
+## Step 4 — Update the test scripts
+
+`--dir src/` is now redundant (the `include` globs scope each project). Suggested:
+
+```jsonc
+"test":       "vitest run",   // one-shot, used by CI
+"test:watch": "vitest",       // watch mode for local dev
+"test:ui":    "vitest --ui"   // optional: the Vitest UI, handy for browser tests
+```
+
+`pnpm test` then runs **both** projects (node + browser) in one command.
+
+## Step 5 — Smoke test (prove the harness before writing real tests)
+
+Create one trivial browser test — e.g. `src/lib/components/Separator/Separator.svelte.test.ts`
+that renders `<Separator />` and asserts it's in the document. If it goes green, the client build +
+Chromium + tailwind + sveltekit-plugin chain all work. **This is where the project-memory
+"server-build" risk is actually disproven or confirmed** — treat a passing smoke test as the gate to
+the rest of the plan.
+
+## Open questions / decisions needed
+
+- **Config location** — keep it in `vite.config.ts` (recommended, minimal change; chosen here) vs a
+  dedicated `vitest.config.ts`. Purely organizational; nothing functional depends on it.
+- **`@sveltejs/kit/vite` vs plain `@sveltejs/vite-plugin-svelte` in the `client` project** — the
+  SvelteKit plugin should be fine in browser mode (the `sv` CLI's own vitest add-on uses it), but if
+  the smoke test surfaces SSR/`$lib` alias issues, the fallback is to give the `client` project a
+  plain `svelte()` plugin instead of inheriting `sveltekit()`. Decide only if the smoke test fails.

package/docs/component-testing/02-test-conventions.md

@@ -0,0 +1,148 @@
+<!--
+GENERATED ANALYSIS — @marianmeres/stuic real-browser component testing
+Produced 2026-06-08 by multi-agent research → adversarial verify → synthesize.
+Claims verified against the codebase at commit cc9958b and the live
+vitest-browser-svelte docs. Planning artifact; no code was changed.
+-->
+
+# Test Conventions
+
+> How to write a STUIC browser component test, and — just as important — **what is worth
+> asserting**. The headline: test *behavior the build can't see* (events fire, bindings update,
+> aria/disabled/active states, computed layout), not "does it render" (already gated by
+> `svelte-check` + `publint` + the build). Use `render()` → locators → `expect.element`. In Svelte 5
+> events are props, so you assert them with spies; snippet children come from `createRawSnippet`.
+
+## Reconciling with `docs/testing.md`
+
+[`docs/testing.md`](../testing.md) currently states the library **deliberately does not** test full
+component rendering ("50+ components × prop combinations = slow suite with tiny yield... Rendering is
+already gated by svelte-check + publint + the build") and treats interactive/visual behavior as
+out of scope.
+
+That reasoning was **correct for what it described and is not actually reversed here** — it just
+predates a capability we didn't have:
+
+- "Does it render / compile / export" → still low-yield, still covered by `svelte-check` + `publint` +
+  build. We will **not** write tests for that.
+- "Does it *behave*" — click handlers, two-way `bind:`, `aria-*`/`disabled`/`active` state, focus
+  traps, viewport-clamped anchor positioning (cf. the recent `9d8c974` annotation-clamp fix) — was
+  **previously impossible** (node/server build, no DOM, no `$effect`). Browser mode makes it possible,
+  and *this* is the high-yield target.
+
+**Task in the roadmap:** update `docs/testing.md` to add this browser-test layer so the docs aren't
+self-contradictory — promote "interactive behavior" from ❌ to ✅-when-it's-a-real-contract, and point
+to this directory. (See [`PROGRESS.md`](./PROGRESS.md), sprint task.)
+
+## File naming & location
+
+- One test per component, **co-located** next to the `.svelte` file (matches the existing co-located
+  style, e.g. `Input/phone-validation.test.ts`).
+- Name it `ComponentName.svelte.test.ts` — the `.svelte.test.ts` suffix is what routes it into the
+  browser `client` project (see [01](./01-framework-setup.md)). A plain `*.test.ts` next to a
+  component stays in the fast node project (correct for extracted pure logic like `_internal/*.ts`).
+
+## The canonical test
+
+```ts
+// src/lib/components/Pill/Pill.svelte.test.ts
+import { render } from "vitest-browser-svelte";
+import { expect, test, vi } from "vitest";
+import Pill from "./Pill.svelte";
+
+test("renders label and applies intent", async () => {
+	const screen = render(Pill, { label: "Beta", intent: "primary" });
+	const pill = screen.getByText("Beta");
+	await expect.element(pill).toBeVisible();
+	await expect.element(pill).toHaveAttribute("data-intent", "primary");
+});
+
+test("dismiss button fires ondismiss", async () => {
+	const ondismiss = vi.fn();
+	const screen = render(Pill, { label: "Beta", ondismiss });
+	await screen.getByRole("button", { name: /dismiss/i }).click();
+	expect(ondismiss).toHaveBeenCalledOnce();
+});
+```
+
+Key facts (verified against the `vitest-browser-svelte` README):
+
+- `render(Component, props)` returns a **screen** object with Playwright-style locator methods
+  (`getByRole`, `getByText`, `getByLabelText`, …). `render` is imported from `"vitest-browser-svelte"`.
+- **`expect.element(locator)` auto-retries** — it polls the DOM until the assertion passes or times
+  out (`testTimeout`, set to 2000ms in our config). Prefer it over reading values synchronously; it
+  removes the need for `act`/manual `tick()` for in-component reactivity.
+- `.click()`, `.fill()`, etc. are awaited interactions on a locator.
+- **No `@testing-library`, no `act`.** `vitest-browser-svelte` intentionally omits `act`.
+
+## Events are props (Svelte 5)
+
+There are no `component.$on` listeners in Svelte 5 — events are callback props (`onclick`,
+`onchange`, and STUIC's own `ondismiss`, `onLogout`, etc.). Assert them by passing a spy:
+
+```ts
+const onclick = vi.fn();
+render(Button, { onclick, children: text("Save") });
+await screen.getByRole("button").click();
+expect(onclick).toHaveBeenCalledOnce();
+```
+
+## Snippet props (`children`, `header`, etc.)
+
+Many STUIC components take snippet props (`children`, header/footer snippets). A `.svelte.test.ts`
+file can't contain markup, so build snippets with `createRawSnippet`:
+
+```ts
+import { createRawSnippet } from "svelte";
+
+// tiny helper for static text children — keep it in a shared test util
+const text = (s: string) => createRawSnippet(() => ({ render: () => `<span>${s}</span>` }));
+
+render(Button, { children: text("Click me") });
+```
+
+For complex snippet scenarios (a snippet that itself renders a STUIC component, takes args, etc.),
+the escape hatch is a **fixture component**: a small `ComponentName.fixture.svelte` next to the test
+that composes the real component with markup, then `render(Fixture, props)`. Prefer `createRawSnippet`
+for the common case; reach for a fixture only when markup composition is the thing under test.
+
+## Two-way binding (`bind:value`, `bind:checked`)
+
+To assert that user interaction updates bound state, render a fixture that binds the prop to local
+state and exposes it, **or** assert the observable DOM proxy (e.g. the hidden `<input>`'s `checked`
+for `Switch`, the `<input>`'s `value` for `FieldInput`). Default to asserting the DOM — it's what a
+consumer observes — and use a fixture only when you must read the bound JS value directly.
+
+## What to assert (the high-yield checklist)
+
+For each component, prefer these over snapshot dumps:
+
+1. **Prop → DOM contract** — `intent`/`variant`/`size` → `data-*` attribute or class; `href` → renders
+   `<a>` vs `<button>`; `disabled` → the `disabled` attribute / blocked clicks.
+2. **Events** — the right callback fires once, with the right argument, and `disabled` suppresses it.
+3. **Binding** — interaction updates the value/checked state.
+4. **A11y** — `role`, `aria-*`, label association, focus order where it's a contract.
+5. **Computed layout** (browser-only superpower) — width from a `progress` value, viewport clamping
+   of anchor-positioned elements, focus actually trapped. These are exactly what jsdom returns zeros
+   for, and what regressed in recent commits.
+
+Avoid: asserting exact class strings (brittle — assert the `data-*` contract or a single meaningful
+class), and snapshotting full HTML (self-closing-tag / class-order differences make them noisy).
+
+## Cleanup gotcha
+
+`vitest-browser-svelte` cleans up **before** each test, not after — so the last rendered component
+stays on screen for debugging. Import from `vitest-browser-svelte/pure` to opt out of auto-cleanup
+when a test needs to manage it manually. Rarely needed.
+
+## Timing / flakiness
+
+Rely on `expect.element` retries and awaited locator actions — **never fixed `sleep`s**. In-component
+reactivity resolves through the retry loop; only assertions on *external* universal state living in a
+`*.svelte.ts` module may need `flushSync()` from `svelte`.
+
+## Open questions / decisions needed
+
+- **Shared test utilities** — agree on one home for the `text()` snippet helper and any future
+  fixtures (suggest `src/lib/test-utils/` or `src/test-helpers.ts`), so it's not redefined per file.
+  Decide when the second snippet-needing component lands.

package/docs/component-testing/03-component-coverage-roadmap.md

@@ -0,0 +1,92 @@
+<!--
+GENERATED ANALYSIS — @marianmeres/stuic real-browser component testing
+Produced 2026-06-08 by multi-agent research → adversarial verify → synthesize.
+Component inventory verified against src/lib/components at commit cc9958b.
+Planning artifact; no code was changed.
+-->
+
+# Component Coverage Roadmap
+
+> The library has **74 components** (≈105 `.svelte` files incl. sub-components). Roughly **26 are
+> "easy"** (deterministic prop→DOM, no portals/traps), **23 "medium"** (actions, focus jumps, layout
+> reads), **30 "hard/E2E-only"** (portals, focus traps, anchor positioning, drag, Milkdown). The plan:
+> **one commit per component**, starting with the easy primitives that are used everywhere, then a
+> single "hard proof" to validate that browser mode earns its keep (see [04](./04-hard-cases-and-e2e.md)).
+
+## Summary of recommendations
+
+| # | Recommendation | Value | Effort | Risk |
+|---|----------------|-------|--------|------|
+| 1 | Cover the **easy tier** primitives first (Button, Pill, Switch, …), one commit each | high | S | low |
+| 2 | Establish reusable assertion patterns on Button (the flagship), reuse everywhere | high | S | low |
+| 3 | Do **one hard proof** early (focus trap or anchor positioning) to de-risk the approach | high | M | med |
+| 4 | Cover the **medium tier** (form fields with actions) once patterns are settled | med | M | low |
+| 5 | Defer the **hard 30** to a later sprint / standalone Playwright E2E layer | med | L | med |
+
+## Tier 1 — Easy, highest-value (the warm-up; one commit each)
+
+Deterministic prop→DOM/aria/event surface; no portals, traps, or external geometry. Paths under
+`src/lib/components/`.
+
+| Order | Component | Path | What to assert |
+|-------|-----------|------|----------------|
+| 1 | **Button** | `Button/Button.svelte` | `intent`/`variant`/`size` → `data-*`; `disabled` attr + click suppressed; `href` → `<a>`; spinner shows/hides; `roleSwitch` toggle; `onclick` fires once. The flagship — sets every pattern. |
+| 2 | **Pill** | `Pill/Pill.svelte` | intent/variant → `data-*`; `active` state; dismissible click → `ondismiss` (+ `stopPropagation`); `href` → link; disabled blocks click. |
+| 3 | **Switch** | `Switch/Switch.svelte` | `checked` reflected in hidden input; click toggles; `disabled`; intent/size classes; on/off snippets. First real "reactivity in a browser" proof. |
+| 4 | **Spinner** | `Spinner/Spinner.svelte` | size → dims; `count` → number of bars; thickness/direction/duration → style/CSS var. Pure CSS, no motion lib. |
+| 5 | **Skeleton** | `Skeleton/Skeleton.svelte` | variant (text/circle/rect) markup; `lines` count; rounded class; animation off under `prefers-reduced-motion`; width/height inline style. |
+| 6 | **DismissibleMessage** | `DismissibleMessage/DismissibleMessage.svelte` | message renders; `intent` → `data-intent`; dismiss button hidden when `onDismiss=false`; `ondismiss` fires; new message resets dismissed state. |
+| 7 | **Avatar** | `Avatar/Avatar.svelte` | `src` → `<img>` + alt; initials extracted from name; icon fallback; error→fallback switch; `autoColor` deterministic; size class. |
+| 8 | **Progress** | `Progress/Progress.svelte` | `type=bar` vs `circle` markup; value → bar **width** / circle stroke (genuine layout read — jsdom can't). |
+| 9 | **Separator** | `Separator/Separator.svelte` | orientation → classes/role. Near-zero risk — good harness smoke test (see [01](./01-framework-setup.md) Step 5). |
+| 10 | **H** | `H/H.svelte` | `level` → correct `h1`–`h6` tag; size override class. |
+| 11 | **KbdShortcut** | `KbdShortcut/KbdShortcut.svelte` | key labels rendered; modifier order; cross-platform output. |
+| 12 | **ButtonGroupRadio** | `ButtonGroupRadio/ButtonGroupRadio.svelte` | single selection; click changes selection; value binding. |
+| 13 | **ListItemButton** | `ListItemButton/ListItemButton.svelte` | active class; disabled blocks click; `onclick`; icon/avatar slot. |
+| 14 | **Card** | `Card/Card.svelte` | variant → `data-*`; header/footer/children snippets render. |
+| 15 | **TabbedMenu** | `TabbedMenu/TabbedMenu.svelte` | tab click updates bound `activeTab`; active content renders; indicator moves. |
+| 16 | **IconSwap** | `IconSwap/IconSwap.svelte` | `active` swaps icon; animation class applied. |
+| 17 | **Collapsible** | `Collapsible/Collapsible.svelte` | `needsCollapse` true when `scrollHeight > clientHeight` (browser-only); expand removes line-clamp; toggle visible only when needed. |
+
+> The first sprint targets **#1–#9 plus one hard proof**; #10–#17 are ranked backlog (still Tier 1,
+> just diminishing marginal value). Adjust freely as patterns settle.
+
+## Tier 2 — Medium value, moderate complexity (next sprint)
+
+Use actions (`trim`/`typeahead`/`validate`/`autogrow`/`tooltip`) and/or real focus/geometry, but stay
+deterministic. Form fields are the bulk and share one harness pattern once `FieldInput` is solved.
+
+`FieldInput`, `FieldTextarea`, `FieldCheckbox`, `FieldSelect`, `FieldRadios`, `FieldSwitch`,
+`FieldKeyValues`, `FieldObject`, `FieldPhoneNumber`, `FieldLikeButton` · `OtpInput` (focus jumps,
+paste) · `Nav` (expand/collapse) · `ImageCycler` · `AppShell`/`AppShellSimple` · `PricingTable` ·
+`ThemePreview` · `AssetsPreview` · `SlidingPanels` · `Notifications` (timers; portal — borderline) ·
+`TypeaheadInput` · `ColorScheme` (localStorage).
+
+Pattern note: for the `validate` action, inject a stub validator (`(k) => k` style, as existing util
+tests do) rather than exercising live validation — keeps these fast and deterministic.
+
+## Tier 3 — Hard / E2E-only (later; see [04](./04-hard-cases-and-e2e.md))
+
+Portals & focus traps (`Modal`, `ModalDialog`, `Backdrop`, `Drawer`, `AlertConfirmPrompt`), anchor
+positioning (`DropdownMenu`, `CommandMenu`, `UserAvatarMenu`), drag (`Tree`, `FieldOptions`,
+`FieldFile`, `FieldAssets`), scroll/observer (`Carousel`, `DataTable`, `Book`), heavy 3rd-party
+(`MarkdownEditor`/Milkdown, `CronInput`), and the composite flows (`Checkout/*`, `LoginForm`,
+`RegisterForm`, `EmailVerifyForm`, `LoginOrRegisterForm`, `FieldInputLocalized`).
+
+Several of these *can* be done in browser mode (focus traps, anchor positioning, observers all work
+in a real Chromium); only drag-heavy and Milkdown components genuinely want standalone Playwright
+E2E. [04](./04-hard-cases-and-e2e.md) draws that line.
+
+## Cadence
+
+- **One component per commit**, message like `test(Button): browser-mode coverage`.
+- Each commit: write `ComponentName.svelte.test.ts`, run `pnpm test` (both projects green), tick the
+  row in [`PROGRESS.md`](./PROGRESS.md), commit.
+- Don't chase coverage %. Stop at the behavior contracts in [02](./02-test-conventions.md)'s checklist.
+
+## Open questions / decisions needed
+
+- **Depth per component** — assert the headline contracts (recommended) vs exhaustive prop-matrix.
+  Default: headline contracts; expand only where a real regression happened.
+- **Where to stop Tier 1 before pausing for the hard proof** — plan assumes after #9; confirm or
+  extend.

package/docs/component-testing/04-hard-cases-and-e2e.md

@@ -0,0 +1,97 @@
+<!--
+GENERATED ANALYSIS — @marianmeres/stuic real-browser component testing
+Produced 2026-06-08 by multi-agent research → adversarial verify → synthesize.
+Claims verified against src/lib at commit cc9958b. Planning artifact; no code was changed.
+-->
+
+# Hard Cases & E2E Strategy
+
+> ~30 of the 74 components are "hard". But "hard" splits two ways: **most are hard for *jsdom* yet
+> perfectly testable in Vitest browser mode** (focus traps, anchor positioning, ResizeObserver — all
+> work in a real Chromium); only **drag-heavy and Milkdown-class** components genuinely need a
+> separate Playwright **E2E** layer against a running app. The single most valuable near-term action
+> is **one "hard proof"** test now — pick the thing that recently regressed — to prove browser mode
+> earns its setup cost before we invest in the easy tier en masse.
+
+## The two kinds of "hard"
+
+| Kind | Examples | Where it's tested |
+|------|----------|-------------------|
+| **Hard for jsdom, fine in browser mode** | focus traps, anchor/viewport positioning, scroll/observer tracking, transitions, computed layout | **Vitest browser mode** (this plan) — a real Chromium page gives real `getBoundingClientRect`, focus, layout |
+| **Hard even in browser mode** | drag-and-drop reorder, file drop, full WYSIWYG editors, multi-step composite flows | **Standalone Playwright E2E** against `pnpm dev`/`preview` (deferred to a later sprint) |
+
+This matters because the naive read ("30 components are E2E-only") is wrong — it would defer exactly
+the high-value behaviors (focus, positioning) that motivated this whole effort. Most of the 30 belong
+in browser mode; only a handful are true E2E.
+
+## The "hard proof" — do this once, early
+
+Per the agreed scope (easy warm-up → one hard proof), after the first easy components land, write
+**one** test that is impossible in jsdom and protects a real, recent regression. Two strong
+candidates, both verified to exist:
+
+### Candidate A (recommended) — anchor-position viewport clamping
+
+- **Code:** [`src/lib/utils/anchor-position.ts`](../../src/lib/utils/anchor-position.ts), consumed by
+  `DropdownMenu/DropdownMenu.svelte` (and others).
+- **Why:** this is precisely what regressed in `9d8c974` *"clamp anchor-positioned annotations to
+  viewport on all paths"* and `8c52afe`. A test here has immediate, proven value and prevents
+  recurrence. It's also the textbook "jsdom returns all-zeros from `getBoundingClientRect`" case — so
+  it can only exist in browser mode.
+- **Shape:** render a host + an anchored element positioned near a viewport edge in a real page;
+  assert the element's rect stays clamped inside `window.innerWidth/innerHeight`.
+- **Bonus:** the *pure* clamp math in `anchor-position.ts` can additionally get a fast **node** test
+  (`anchor-position.test.ts`) — cheap regression net independent of the browser.
+
+### Candidate B (alternative) — focus trap
+
+- **Code:** [`src/lib/actions/focus-trap.ts`](../../src/lib/actions/focus-trap.ts), used by
+  `ModalDialog`, `Backdrop`, `Drawer`.
+- **Why:** Tab/Shift-Tab cycling and `returnFocus`-on-teardown are core a11y contracts that node
+  cannot exercise at all.
+- **Shape:** render a container with the action + 3 focusables; assert Tab from the last wraps to the
+  first, Shift-Tab from the first wraps to the last, and focus returns to the opener on destroy.
+
+> **Open question (resolve at this task):** A or B as the single hard proof. Recommendation: **A** —
+> it guards a regression that already happened twice. Doing both is fine but only one is required to
+> de-risk the approach.
+
+## Portals & focus traps (browser-mode, later sprint)
+
+`Modal`, `ModalDialog`, `Backdrop`, `Drawer`, `AlertConfirmPrompt` — all use
+[`focus-trap.ts`](../../src/lib/actions/focus-trap.ts), scroll-lock, and an Escape-key stack. These
+are testable in browser mode (open → focus trapped → Escape closes → backdrop click closes →
+`returnFocus`). The stack/queue *logic* is already unit-tested (`AlertConfirmPromptStack`,
+`NotificationsStack`); browser tests add the DOM-interaction layer. Higher effort, real value —
+schedule after Tier 1/2.
+
+## Anchor positioning (browser-mode, later sprint)
+
+`DropdownMenu`, `CommandMenu`, `UserAvatarMenu` — positioning + keyboard nav + click-outside. Test
+positioning and keyboard nav in browser mode; the search/filter logic should be extracted to
+`_internal/*.ts` and unit-tested in node where practical.
+
+## True E2E candidates (standalone Playwright, deferred)
+
+These want a running app, not isolated component mounts:
+
+- **Drag & file drop:** `Tree` (reorder + auto-expand + async `onMove`), `FieldOptions`, `FieldFile`,
+  `FieldAssets`. Extract and node-test the pure logic (`calcDropPosition`, `isDescendantOf` per
+  `docs/testing.md`); E2E the gesture.
+- **Heavy editors:** `MarkdownEditor` (Milkdown + CodeMirror) — E2E only; mock/skip at component
+  level. `CronInput` — node-test the cron logic, E2E the builder UI.
+- **Composite flows:** `Checkout/*`, `LoginForm`/`RegisterForm`/`EmailVerifyForm`/
+  `LoginOrRegisterForm`, `FieldInputLocalized` — multi-step, cross-component; E2E the flow, browser-
+  test the leaf fields individually.
+
+A standalone Playwright E2E project (its own `playwright.config.ts` against `pnpm preview`) is a
+**separate later initiative** — explicitly out of scope for the first sprint. Visual-regression
+(Vitest 4 ships `toMatchScreenshot`) is likewise deferred.
+
+## Open questions / decisions needed
+
+- **Hard proof A vs B** (above) — recommend A.
+- **When to start the standalone Playwright E2E layer** — not in sprint 1; revisit after Tier 2.
+- **Logic-extraction appetite** — several hard components get much cheaper if pure logic moves to
+  `_internal/*.ts` (already endorsed by `docs/testing.md`). Decide per-component whether to extract
+  before testing.

package/docs/component-testing/05-ci.md

@@ -0,0 +1,88 @@
+<!--
+GENERATED ANALYSIS — @marianmeres/stuic real-browser component testing
+Produced 2026-06-08 by multi-agent research → adversarial verify → synthesize.
+Claims verified against the repo at commit cc9958b. Planning artifact; no code was changed.
+-->
+
+# CI — GitHub Actions
+
+> The repo is on GitHub (`github.com/marianmeres/stuic`) and publishes to npm, so CI pays off: it
+> runs the tests automatically on every push/PR in a clean machine, catching regressions **before**
+> a broken release reaches npm. The plan: **one ~30-line workflow** that installs Chromium and runs
+> `pnpm test`. It's fully decoupled from the tests themselves (those run identically via `pnpm test`
+> locally) and is scheduled **late in the first sprint**, once a few component tests pass locally, so
+> the first CI run verifies something real.
+
+## What CI is, briefly
+
+A robot that runs your checks on every push. **GitHub Actions** is GitHub's built-in version: you
+commit a YAML file at `.github/workflows/test.yml` describing *when* to run (push / pull_request) and
+*what steps* to run on a fresh Linux VM. GitHub then shows a green ✓ / red ✗ on each commit and PR.
+Free for this repo's usage.
+
+## The one wrinkle vs a normal Node test job
+
+Browser tests need a real Chromium binary on the CI machine, so the workflow adds one step —
+`pnpm exec playwright install --with-deps chromium` — before `pnpm test`. (`--with-deps` also
+installs the OS libraries Chromium needs on the Ubuntu runner.) Everything else is a standard
+pnpm + Node setup.
+
+## The workflow (to create as the sprint's CI task)
+
+```yaml
+# .github/workflows/test.yml
+name: test
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Install Chromium for browser tests
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Run tests (node + browser projects)
+        run: pnpm test           # = "vitest run", runs both projects headless
+```
+
+Notes:
+
+- `pnpm test` must be the one-shot `vitest run` (see [01](./01-framework-setup.md) Step 4), not watch
+  mode, or CI hangs.
+- `browser.headless: true` is already set in the config, so no display server is needed.
+- Pin `node-version` to whatever you develop on (22 shown). `pnpm/action-setup@v4` reads the pnpm
+  version from `package.json`'s `packageManager` field if present — the repo currently has none, so
+  either add one (e.g. `"packageManager": "pnpm@9.x"`) or pin `version:` in the action. **Decide this
+  when creating the workflow.**
+
+## Alternative considered (not chosen)
+
+Running the job inside the official Playwright Docker image
+(`container: mcr.microsoft.com/playwright:v1.xx-jammy`) ships browsers pre-installed and is ~30%
+faster per published benchmarks. For a library this size the absolute difference is seconds; the
+plain workflow above is more readable, so it's the chosen default. The Docker route stays available
+if CI time ever matters.
+
+## Open questions / decisions needed
+
+- **`packageManager` field vs pinned pnpm version in the action** — pick one so `pnpm/action-setup`
+  is deterministic.
+- **Node version** to pin (suggest 22).
+- **Add `pnpm check` / `pnpm lint` to the same workflow?** — cheap to fold in (the repo already has
+  both scripts) and would make CI a full quality gate, but it widens scope beyond testing. Recommend
+  yes, as a second job, but only after the test job is green.

package/docs/component-testing/PROGRESS.md

@@ -0,0 +1,63 @@
+# Implementation Progress — Component Testing
+
+Living tracker for acting on [`00-overview-and-roadmap.md`](./00-overview-and-roadmap.md).
+A fresh conversation should read this file first, then the relevant `NN-*.md` section.
+
+**Status legend:** ⬜ not started · 🚧 in progress · ⏸️ blocked/awaiting decision · ✅ done · ⏭️ deferred
+
+> Convention: branch `feat/component-testing`; **one commit per task**. Each task resolves its source
+> doc's "Open questions" first (record in the Decisions log), then implement → `pnpm test` green →
+> tick here → commit.
+
+## First sprint (harness + easy tier + one hard proof + CI)
+
+Branch: `feat/component-testing`
+
+| # | Task | Source | Status | Commit |
+|---|------|--------|--------|--------|
+| 1 | Upgrade vitest 3→4; confirm 9 existing node suites still green | [01](./01-framework-setup.md) Step 1 | ✅ | `71e47e2` |
+| 2 | Browser harness: add deps, `projects` config split, `playwright install chromium`, fix test scripts, Separator smoke test | [01](./01-framework-setup.md) Steps 2–5 | ✅ | `980b323` |
+| 3 | Reconcile [`docs/testing.md`](../testing.md) — add the browser-behavior layer | [02](./02-test-conventions.md) | ✅ | _next_ |
+| 4 | **Button** — flagship; establish assertion patterns | [03](./03-component-coverage-roadmap.md) #1 | ⬜ | — |
+| 5 | **Pill** — intent/active/dismissible event | [03](./03-component-coverage-roadmap.md) #2 | ⬜ | — |
+| 6 | **Switch** — checked binding, toggle, disabled | [03](./03-component-coverage-roadmap.md) #3 | ⬜ | — |
+| 7 | **Spinner** — size/count/direction | [03](./03-component-coverage-roadmap.md) #4 | ⬜ | — |
+| 8 | **Skeleton** — variants, reduced-motion | [03](./03-component-coverage-roadmap.md) #5 | ⬜ | — |
+| 9 | **DismissibleMessage** — intent, dismiss, auto-reset | [03](./03-component-coverage-roadmap.md) #6 | ⬜ | — |
+| 10 | **Avatar** — initials/img/icon fallback, autoColor | [03](./03-component-coverage-roadmap.md) #7 | ⬜ | — |
+| 11 | **Progress** — value→width/stroke (real layout) | [03](./03-component-coverage-roadmap.md) #8 | ⬜ | — |
+| 12 | **Hard proof** — anchor-position viewport clamp (rec.) *or* focus trap | [04](./04-hard-cases-and-e2e.md) | ⏸️ | — |
+| 13 | CI — minimal GitHub Actions `test.yml` | [05](./05-ci.md) | ⬜ | — |
+
+## Backlog (ranked, post-sprint)
+
+| Rank | Task | Source | Status |
+|------|------|--------|--------|
+| 14 | Rest of Tier 1 (Separator already smoke-tested · H, KbdShortcut, ButtonGroupRadio, ListItemButton, Card, TabbedMenu, IconSwap, Collapsible) | [03](./03-component-coverage-roadmap.md) #10–17 | ⬜ |
+| 15 | Tier 2 — `FieldInput` first, then the Field* family + OtpInput, Nav, etc. | [03](./03-component-coverage-roadmap.md) | ⬜ |
+| 16 | Portals/focus-traps in browser mode (Modal, ModalDialog, Backdrop, Drawer, AlertConfirmPrompt) | [04](./04-hard-cases-and-e2e.md) | ⬜ |
+| 17 | Anchor-positioned menus (DropdownMenu, CommandMenu, UserAvatarMenu) + extract search logic to `_internal` | [04](./04-hard-cases-and-e2e.md) | ⬜ |
+| 18 | Standalone Playwright E2E layer (drag: Tree/FieldOptions/FieldFile; Milkdown; Checkout/auth flows) | [04](./04-hard-cases-and-e2e.md) | ⏭️ |
+| 19 | Add `pnpm check` + `pnpm lint` as a second CI job | [05](./05-ci.md) | ⬜ |
+| 20 | (Maybe) visual-regression via `toMatchScreenshot`; multi-browser matrix | [00](./00-overview-and-roadmap.md) | ⏭️ |
+
+## Decisions log
+
+- **2026-06-08** — Adopt **Vitest 4 Browser Mode + `vitest-browser-svelte` + `@vitest/browser-playwright` (Chromium)** — verified the right default for a component library whose value is DOM/layout/focus behavior the current node/server-build setup can't test.
+- **2026-06-08** — **Take the vitest 3→4 major upgrade now** (gating prerequisite) — `vitest-browser-svelte@^2` peer-requires `vitest ^4`; the vitest-3-compatible `0.1.0` is a dead-end.
+- **2026-06-08** — **Scope:** easy warm-up (Button/Pill/Switch/…) then **one** hard proof — not full coverage up front.
+- **2026-06-08** — **Browsers: Chromium only** — leanest CI; add Firefox/WebKit only if engine-specific behavior demands it.
+- **2026-06-08** — **CI: yes, minimal GitHub Actions**, added late in the sprint once a few component tests pass locally.
+- **2026-06-08** — **Config lives in `vite.config.ts`** (extend with a `test` block) rather than a separate `vitest.config.ts` — minimal change.
+- **2026-06-08** — Task 1 done: **vitest 4.1.8** installed (vite already `^7.3.5`, compatible); all 9 node suites / 59 tests pass unchanged. `--dir src/` still supported in v4.
+- **2026-06-08** — Task 2 done: harness works. Deps: `@vitest/browser-playwright 4.1.8`, `playwright 1.60.0`, `vitest-browser-svelte 2.1.1`. `projects` split added to `vite.config.ts`; scripts now `test` = `vitest run` (+ `test:watch`, `test:ui`). Separator smoke test (3 assertions) passes in Chromium → **10 files / 62 tests green**, `pnpm check` clean (0 errors). **The documented SvelteKit-plugin/server-build blocker is resolved** — browser mode resolves the client build, `toHaveClass("stuic-separator")` confirms tailwind + the client runtime run. No `client`-project plugin fallback needed.
+- **⏸️ Open (task 12):** which single hard proof — anchor-position clamp (recommended, guards the `9d8c974` regression) vs focus trap.
+- **⏸️ Open (task 13):** `packageManager` field vs pinned pnpm version in the CI action; Node version to pin.
+
+## How to resume (for a fresh conversation)
+
+1. Read this file + [`00-overview-and-roadmap.md`](./00-overview-and-roadmap.md).
+2. Pick the next ⬜ task; open its source doc section for the verified detail.
+3. Resolve that task's "Open questions" with the owner; record in the Decisions log.
+4. On `feat/component-testing`: implement → `pnpm test` (both projects green) → update this file →
+   commit when the owner asks (one commit per task).