@marianmeres/stuic 3.114.0 → 3.115.0

package/dist/components/H/README.md

@@ -63,7 +63,7 @@ Render a semantic `h2` but style it like an `h4`:
 | `--stuic-h-line-height`    | `1.2`                                            | Line height          |
 | `--stuic-h-letter-spacing` | `normal`                                         | Letter spacing       |
 | `--stuic-h-color`          | `inherit`                                        | Text color           |
-| `--stuic-h-margin`         | `0`                                              | Margin               |
+| `--stuic-h-margin`         | `0 0 0.5em`                                      | Margin (bottom-only) |
 | `--stuic-h1-font-size`     | `clamp(1.875rem, 1.6rem + 1vw, 2.5rem)`          | H1 font size (fluid) |
 | `--stuic-h2-font-size`     | `clamp(1.5rem, 1.3rem + 0.9vw, 2.125rem)`        | H2 font size (fluid) |
 | `--stuic-h3-font-size`     | `clamp(1.25rem, 1.1rem + 0.65vw, 1.625rem)`      | H3 font size (fluid) |

package/dist/components/H/index.css

@@ -10,7 +10,10 @@
 	--stuic-h-line-height: 1.2;
 	--stuic-h-letter-spacing: normal;
 	--stuic-h-color: inherit;
-	--stuic-h-margin: 0;
+	/* Bottom-only by default: binds the heading to the content below it, while
+	   space above comes from the previous element's collapsing bottom margin.
+	   Avoids the first-child / flex-grid issues a baked-in margin-top would cause. */
+	--stuic-h-margin: 0 0 0.5em;
 
 	/* Per-level font sizes — fluid scaling, original values at ~1024px viewport */
 	--stuic-h1-font-size: clamp(1.875rem, 1.6rem + 1vw, 2.5rem);

package/docs/component-testing/00-overview-and-roadmap.md

@@ -0,0 +1,119 @@
+<!--
+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 /
+vitest-browser-svelte docs. Planning artifact; no code was changed.
+-->
+
+# @marianmeres/stuic — Component Testing: Overview & Roadmap
+
+> **Verdict:** the proposed stack — Vitest Browser Mode + `vitest-browser-svelte` + Playwright/Chromium
+> — is the right default for *this* library, where the value being shipped is precisely the DOM/layout/
+> focus/positioning behavior that the current node/server-build test setup **cannot exercise at all**.
+> The claim is *mostly* correct rather than gospel: it's not an officially-mandated singular standard
+> (svelte.dev still nominally leads with jsdom + @testing-library), and one term was dated — modern
+> spelling is `vitest-browser-svelte` + **`@vitest/browser-playwright`** + `playwright` on **Vitest 4**.
+>
+> **The one thing that matters most:** a **vitest 3 → 4 major upgrade is a hard prerequisite**
+> (`vitest-browser-svelte@^2` peer-requires `vitest ^4`; Browser Mode is only stable in v4). Do it as
+> a discrete, reversible first commit and confirm the 9 existing suites stay green before anything else.
+>
+> **The second thing:** route tests by filename into a Vitest `projects` split — `*.test.ts` → fast
+> **node** (the existing 9 suites, untouched), `*.svelte.test.ts` → real **browser**. Get that glob
+> right and nothing regresses; get it wrong and either utils crawl in a browser or components fail in
+> node with the very server-build error this effort exists to escape.
+>
+> Read order: this file → [`01-framework-setup`](./01-framework-setup.md) for the exact config →
+> [`02-test-conventions`](./02-test-conventions.md) for how to write a test → then work
+> [`PROGRESS.md`](./PROGRESS.md) top-down. [`03`](./03-component-coverage-roadmap.md) ranks all 74
+> components; [`04`](./04-hard-cases-and-e2e.md) handles the hard 30; [`05`](./05-ci.md) is CI.
+
+## A note on `docs/testing.md` (this is a partial reversal — by design)
+
+[`docs/testing.md`](../testing.md) records a deliberate decision **not** to test component rendering
+("50+ components × prop combos = slow suite, tiny yield; rendering is gated by svelte-check + publint +
+build"). That reasoning holds for *"does it render"* and we keep it. What changes: browser mode lets
+us test *"does it **behave**"* — events, two-way binding, aria/disabled/active state, focus traps,
+viewport-clamped positioning (cf. the `9d8c974` annotation regression) — which the build does **not**
+cover and which was **previously impossible**. Updating `docs/testing.md` to add this layer is an
+explicit sprint task so the docs don't contradict each other.
+
+## Top recommendations across all dimensions (ranked)
+
+| Rank | Recommendation | Dimension | Value | Effort | Risk | Why now |
+|------|----------------|-----------|-------|--------|------|---------|
+| 1 | Upgrade vitest 3→4, verify 9 suites green | [01](./01-framework-setup.md) | high | S | med | Gating prerequisite; nothing installs without it |
+| 2 | Add `projects` split (node `server` + browser `client`) + Chromium | [01](./01-framework-setup.md) | high | S | med | The harness; routes by `*.svelte.test.ts` filename |
+| 3 | Separator smoke test — prove client build + `$effect` actually run | [01](./01-framework-setup.md) | high | S | med | Disproves/confirms the documented server-build blocker |
+| 4 | Reconcile `docs/testing.md` (behavior ✅, rendering still ❌) | [02](./02-test-conventions.md) | med | S | low | Keep docs internally consistent before scaling |
+| 5 | Button — flagship; sets every assertion pattern | [03](./03-component-coverage-roadmap.md) | high | S | low | Most-used primitive; template for the rest |
+| 6 | Pill, Switch — events + binding patterns | [03](./03-component-coverage-roadmap.md) | high | S | low | Cover dismiss/toggle/bind once, reuse everywhere |
+| 7 | Spinner, Skeleton, DismissibleMessage, Avatar, Progress | [03](./03-component-coverage-roadmap.md) | high | S | low | Deterministic, high-traffic; quick wins |
+| 8 | **One hard proof** — anchor-position viewport clamp (or focus trap) | [04](./04-hard-cases-and-e2e.md) | high | M | med | Guards a real recent regression; proves browser mode's worth |
+| 9 | Minimal GitHub Actions workflow | [05](./05-ci.md) | high | S | low | Stops broken tests reaching npm; once a few tests pass |
+| 10 | Tier-2 form fields (`FieldInput` first, then the family) | [03](./03-component-coverage-roadmap.md) | med | M | low | Largest component group; one pattern unlocks many |
+| 11 | Portals/focus-traps in browser mode (Modal/Drawer/Backdrop) | [04](./04-hard-cases-and-e2e.md) | med | M | med | High-value a11y contracts; after patterns settle |
+| 12 | Standalone Playwright E2E layer (drag, Milkdown, checkout flows) | [04](./04-hard-cases-and-e2e.md) | med | L | med | Separate later initiative; explicitly out of sprint 1 |
+
+> **Deliberately deferred as low-yield:** visual-regression / `toMatchScreenshot`, multi-browser
+> (Firefox/WebKit) matrix, and exhaustive prop-matrix coverage. Revisit only if motivated by a real bug.
+
+## Recommended first sprint (do these first)
+
+Branch: `feat/component-testing`. One commit per task.
+
+1. **Vitest 4 upgrade (#1)** — `pnpm add -D vitest@^4`, run `pnpm test`, confirm 9 suites green. Why
+   first: everything else peer-depends on it; isolating it makes the one risky bump reversible.
+2. **Browser harness (#2, #3)** — add browser deps, the `projects` config, `playwright install
+   chromium`, fix the test scripts, and land the Separator smoke test. Unblocks all component tests
+   and proves the server-build blocker is gone. Detail in [01](./01-framework-setup.md).
+3. **Reconcile `docs/testing.md` (#4)** — small doc edit so the philosophy matches reality.
+4. **Button (#5)** — establishes the assertion vocabulary ([02](./02-test-conventions.md)) every later
+   test reuses. Highest-leverage single component.
+5. **Pill → Switch → Spinner → Skeleton → DismissibleMessage → Avatar → Progress (#6, #7)** — the easy
+   tier, one commit each; fast, deterministic, high-traffic coverage.
+6. **One hard proof (#8)** — anchor-position viewport clamp (recommended) or focus trap; the payoff
+   moment that justifies the whole setup. Detail in [04](./04-hard-cases-and-e2e.md).
+7. **CI (#9)** — the ~30-line workflow, now that there's a real suite to run. Detail in [05](./05-ci.md).
+
+## Cross-cutting themes
+
+- **Filename routing is load-bearing.** The `*.svelte.test.ts` vs `*.test.ts` convention is what keeps
+  node fast and browser correct. It appears in every dimension.
+- **Test behavior, not rendering.** The build already proves components render; tests exist for the
+  contracts it can't see (events, binding, aria, geometry). This both reconciles `docs/testing.md` and
+  picks the high-yield targets.
+- **Extract-then-unit-test stays valid.** Pure logic in `_internal/*.ts` (drop math, cron parsing,
+  clamp math) should keep getting fast node tests; browser mode is additive, not a replacement.
+- **One commit per component** keeps the effort resumable and reviewable, exactly matching the
+  PROGRESS.md convention.
+
+## Dependency / sequencing notes
+
+```mermaid
+flowchart TD
+  A["1. vitest 3→4 upgrade"] --> B["2. projects config + Chromium + smoke test"]
+  B --> C["3. reconcile docs/testing.md"]
+  B --> D["4. Button (flagship patterns)"]
+  D --> E["5. easy tier: Pill, Switch, Spinner, Skeleton, ..."]
+  E --> F["8. one hard proof (anchor clamp / focus trap)"]
+  E --> G["9. CI workflow"]
+  F --> H["later: Tier 2 fields, portals, standalone Playwright E2E"]
+  G --> H
+```
+
+## Completeness check
+
+- **Snippet-heavy components** (Button needs `children`): the `createRawSnippet` pattern is settled in
+  [02](./02-test-conventions.md); first real exercise is Button — watch for friction and codify a shared
+  helper home then.
+- **SvelteKit-plugin-in-browser-mode** is the top unknown; the Separator smoke test (task 2) is the
+  designated early canary, with a documented fallback (plain `svelte()` plugin for the client project).
+- **`packageManager` field is absent** — surfaces in CI ([05](./05-ci.md)); resolve when writing the
+  workflow.
+- Not yet scoped: a dedicated `playwright.config.ts` for the standalone E2E layer — intentionally
+  deferred to its own future initiative ([04](./04-hard-cases-and-e2e.md)).
+
+Source documents: [`01-framework-setup`](./01-framework-setup.md), [`02-test-conventions`](./02-test-conventions.md),
+[`03-component-coverage-roadmap`](./03-component-coverage-roadmap.md), [`04-hard-cases-and-e2e`](./04-hard-cases-and-e2e.md),
+[`05-ci`](./05-ci.md).

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).

package/docs/component-testing/README.md

@@ -0,0 +1,38 @@
+<!--
+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 /
+vitest-browser-svelte docs. Planning artifact; no code was changed.
+-->
+
+# Component Testing — @marianmeres/stuic
+
+This directory holds the plan for introducing **real-browser component tests** to STUIC
+(Vitest 4 Browser Mode + `vitest-browser-svelte` + Playwright/Chromium). It was produced
+2026-06-08 from a research pass over the codebase and the current Svelte/Vitest ecosystem.
+It is a **planning artifact — no code has been changed**; every claim is verified against the
+repo at commit `cc9958b` or against the live docs cited in each section.
+
+**Start here:** [`00-overview-and-roadmap.md`](./00-overview-and-roadmap.md). Then track and
+resume execution from [`PROGRESS.md`](./PROGRESS.md).
+
+## Documents
+
+| # | Doc | Scope | Headline |
+|---|-----|-------|----------|
+| 00 | [overview-and-roadmap](./00-overview-and-roadmap.md) | synthesis + roadmap | The stack is the right default; vitest 3→4 upgrade is the gating prerequisite. |
+| 01 | [framework-setup](./01-framework-setup.md) | infra | Upgrade vitest 4, add a `projects` split (node `server` + browser `client`), route by filename. |
+| 02 | [test-conventions](./02-test-conventions.md) | how-to | `render()` + locators + `expect.element`; events are props (spies); snippets via `createRawSnippet`. |
+| 03 | [component-coverage-roadmap](./03-component-coverage-roadmap.md) | what to cover | 74 components tiered; warm up on Button/Pill/Switch, one commit per component. |
+| 04 | [hard-cases-and-e2e](./04-hard-cases-and-e2e.md) | the hard 30 | Portals/focus-traps/anchor-positioning: one "hard proof" now; standalone Playwright E2E deferred. |
+| 05 | [ci](./05-ci.md) | automation | One ~30-line GitHub Actions workflow; install Chromium, run `pnpm test`. |
+
+## How it was produced
+
+Five parallel research agents (test-infra audit, full component inventory, multistep-format
+extraction, two independent web-research angles on the stack) → synthesis → live-docs
+verification of the exact Vitest 4 config syntax → this plan.
+
+> Nothing here is decided beyond the four clarifying answers recorded in
+> [`PROGRESS.md`](./PROGRESS.md) → Decisions log. Each doc's "Open questions / decisions needed"
+> lists what still needs a call.

package/docs/testing.md

@@ -11,7 +11,12 @@ This is a component library. Most of its correctness guarantees come from:
 3. **The build** — every component compiles, every export resolves.
 4. **Manual/visual review** — styling, animation, keyboard interaction, a11y cues.
 
-Unit tests are for what those tools can't see: **pure deterministic logic where a regression silently corrupts data**. We explicitly don't try to test everything.
+Tests are for what those tools can't see. There are **two layers**, split by filename:
+
+- **`*.test.ts` — node, fast.** Pure deterministic logic where a regression silently corrupts data.
+- **`*.svelte.test.ts` — real browser (Chromium).** Component _behavior_ the build can't see: events firing, two-way `bind:`, `aria`/`disabled`/`active` state, focus traps, computed layout/positioning.
+
+We still explicitly don't try to test everything. The browser layer targets **behavior contracts**, not "does it render" — see [`component-testing/`](./component-testing/) for the strategy, roadmap, and how-to.
 
 ## What we test
 
@@ -20,6 +25,7 @@ Unit tests are for what those tools can't see: **pure deterministic logic where
 - **Validation helpers** — `validateEmail`, `validateAddress`, `validateCustomerForm`, `validateLoginForm`, `validatePhoneNumber`, `addressesEqual`.
 - **State-machine classes** — `NotificationsStack`, `AlertConfirmPromptStack`, `SwitchState`, `InputHistory`. Tri-state transitions, dedupe, ordering, cleanup semantics.
 - **Pure utilities** — `replace-map`, `tr`, `storage-abstraction`, and anything else with non-trivial input/output logic.
+- **Component behavior** (browser mode, `*.svelte.test.ts`) — prop→DOM/`aria` contracts, events firing, `bind:` updates, focus traps, viewport-clamped positioning. One component at a time, asserting contracts a consumer relies on — not every prop permutation.
 
 ### ⚠️ Maybe, if motivated by a regression
 
@@ -27,18 +33,23 @@ Unit tests are for what those tools can't see: **pure deterministic logic where
 
 ### ❌ We don't test
 
-- **Full component rendering** via `@testing-library/svelte`. 50+ components × prop combinations = slow suite with tiny yield. Rendering is already gated by `svelte-check` + `publint` + the build.
-- **Visual regression**. That's a separate project (Playwright + screenshot diffing) — not part of `vitest --dir src/`.
-- **Interactive behavior** (keyboard nav, drag-drop, scroll snap) unless the underlying math is extracted to a pure function.
+- **Exhaustive prop-matrix / "does it render" tests.** 50+ components × every prop combination = slow suite with tiny yield. Rendering is already gated by `svelte-check` + `publint` + the build; the browser layer asserts _behavior contracts_, not coverage of every permutation.
+- **Visual regression**. A separate concern (Vitest's `toMatchScreenshot` / screenshot diffing) — deferred, not part of `pnpm test` today.
+- **Heavy gestures & 3rd-party editors** (drag-drop reorder, file drop, Milkdown/CodeMirror) — deferred to a future standalone Playwright **E2E** layer, not the in-repo browser project. Extract and node-test their pure logic where practical.
 - **Coverage % targets**. They're the wrong goal for a component library.
 
 ## Running tests
 
 ```bash
-pnpm run test
+pnpm test          # both projects (node + browser), one-shot
+pnpm test:watch    # watch mode
+pnpm test:ui       # Vitest UI (handy for the browser project)
 ```
 
-Vitest is configured to run everything under `src/`. Tests live next to the code they test: `foo.ts` → `foo.test.ts`.
+Vitest runs **two projects**, routed by filename: a node project for `*.test.ts` and a real-browser
+(Chromium, via Playwright) project for `*.svelte.test.ts`. Tests live next to the code they test:
+`foo.ts` → `foo.test.ts`; `Foo.svelte` → `Foo.svelte.test.ts`. The browser binary is installed once
+with `pnpm exec playwright install chromium`.
 
 ## Writing a test
 
@@ -65,8 +76,16 @@ import type { TranslateFn } from "$lib/types.js";
 const t: TranslateFn = (k) => k;
 ```
 
+For **component** tests (`*.svelte.test.ts`), the patterns differ — `render()` from
+`vitest-browser-svelte`, locators, and the retry-able `expect.element`; events are props (assert with
+spies); snippet children come from `createRawSnippet`. See
+[`component-testing/02-test-conventions.md`](./component-testing/02-test-conventions.md) for the full
+how-to and the "what to assert" checklist.
+
 ## When in doubt
 
-- **Logic in a `.ts` file with clear input/output?** Write a test.
+- **Logic in a `.ts` file with clear input/output?** Write a `*.test.ts`.
+- **A component behavior that's a real contract** (event fires, value binds, focus traps, position
+  clamps)? Write a `*.svelte.test.ts`.
 - **A regression just bit you in production?** Write a test for that specific case before fixing.
-- **Anything else?** Probably don't bother.
+- **"Does it render with these 12 props?"** Probably don't bother — the build already covers that.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.114.0",
+	"version": "3.115.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && pnpm run prepack",
@@ -13,7 +13,9 @@
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
 		"format": "prettier --write .",
 		"lint": "eslint . && prettier --check .",
-		"test": "vitest --dir src/",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"test:ui": "vitest --ui",
 		"svelte-check": "svelte-check",
 		"svelte-package": "svelte-package",
 		"rp": "pnpm run build && ./release.sh patch",
@@ -145,9 +147,11 @@
 		"@tailwindcss/typography": "^0.5.19",
 		"@tailwindcss/vite": "^4.3.0",
 		"@types/node": "^25.9.2",
+		"@vitest/browser-playwright": "^4.1.8",
 		"dotenv": "^16.6.1",
 		"eslint": "^9.39.4",
 		"globals": "^16.5.0",
+		"playwright": "^1.60.0",
 		"prettier": "^3.8.3",
 		"prettier-plugin-svelte": "^3.5.2",
 		"publint": "^0.3.21",
@@ -158,7 +162,8 @@
 		"typescript": "^5.9.3",
 		"typescript-eslint": "^8.60.1",
 		"vite": "^7.3.5",
-		"vitest": "^3.2.6"
+		"vitest": "^4.1.8",
+		"vitest-browser-svelte": "^2.1.1"
 	},
 	"dependencies": {
 		"@marianmeres/clog": "^3.21.0",