@marianmeres/stuic 3.113.0 → 3.115.0

package/dist/actions/popover/popover.svelte.js

@@ -1,6 +1,7 @@
 import { mount, unmount } from "svelte";
 import { twMerge } from "../../utils/tw-merge.js";
 import { addAnchorName, removeAnchorName } from "../../utils/anchor-name.js";
+import { clampIntoViewport } from "../../utils/anchor-position.js";
 import { iconX } from "../../icons/index.js";
 import { BodyScroll } from "../../utils/body-scroll-locker.js";
 import PopoverContent from "./PopoverContent.svelte";
@@ -434,8 +435,15 @@ export function popover(anchorEl, fn) {
                 requestAnimationFrame(() => {
                     if (!popoverEl)
                         return;
+                    // Clamp into the viewport first. The discrete @position-try
+                    // fallbacks can leave a residual overflow (and don't cover
+                    // sub-pixel/vertical cases); clamping keeps small edge-anchored
+                    // popovers anchored instead of switching them to a modal.
+                    clampIntoViewport(popoverEl);
                     const rect = popoverEl.getBoundingClientRect();
                     const viewportWidth = window.innerWidth;
+                    // If it STILL overflows horizontally after clamping, the content
+                    // is too wide to fit anchored — fall back to the centered modal.
                     if (rect.left < 0 || rect.right > viewportWidth) {
                         debug("overflow detected, switching to fallback mode");
                         switchingToFallback = true;

package/dist/actions/spotlight/index.css

@@ -26,11 +26,18 @@
 
 @supports (anchor-name: --anchor) {
 	.stuic-spotlight-annotation {
-		position-try-order: most-width;
+		/* The spotlight action overrides these inline per-instance, tailoring the
+		   fallbacks to each annotation's position (see buildPositionTryFallbacks).
+		   These are a sane default for the centered `bottom` placement. `normal`
+		   order keeps the base position when it fits and only engages the span
+		   fallbacks on overflow; the JS clamp is the final backstop. */
+		position-try-order: normal;
 		position-try-fallbacks:
 			flip-block,
 			flip-inline,
-			flip-block flip-inline;
+			flip-block flip-inline,
+			bottom span-left,
+			bottom span-right;
 
 		&.spot-block {
 			display: block;

package/dist/actions/spotlight/spotlight.svelte.js

@@ -1,6 +1,7 @@
 import { mount, unmount } from "svelte";
 import { twMerge } from "../../utils/tw-merge.js";
 import { addAnchorName, removeAnchorName } from "../../utils/anchor-name.js";
+import { buildPositionTryFallbacks, clampIntoViewport, } from "../../utils/anchor-position.js";
 import { BodyScroll } from "../../utils/body-scroll-locker.js";
 import SpotlightContent from "./SpotlightContent.svelte";
 //
@@ -189,6 +190,9 @@ export function spotlight(targetEl, fn) {
     let resizeObserver = null;
     let rafId = null;
     let lastRect = null;
+    // True once the annotation is display:block and laid out — gates the
+    // viewport clamp so it never measures a `display:none` element (zeros).
+    let annotationShown = false;
     // Unique identifiers
     const rnd = Math.random().toString(36).slice(2);
     const anchorName = `--anchor-spotlight-${rnd}`;
@@ -230,9 +234,14 @@ export function spotlight(targetEl, fn) {
             anchorEl.style.width = `${rect.width + padding * 2}px`;
             anchorEl.style.height = `${rect.height + padding * 2}px`;
         }
-        // Update fallback annotation position
-        if (annotationEl && !isSupported) {
-            positionAnnotationFallback(rect, padding);
+        // Reposition / re-clamp the annotation. The fallback path recomputes its
+        // base left/top here; the anchor path is re-placed by the browser. Either
+        // way we re-clamp so an edge-anchored annotation stays on-screen as the
+        // target moves (the anchor path has no built-in viewport clamping).
+        if (annotationEl) {
+            if (!isSupported)
+                positionAnnotationFallback(rect, padding);
+            clampAnnotationIntoViewport();
         }
     }
     /**
@@ -305,27 +314,21 @@ export function spotlight(targetEl, fn) {
             annotationEl.style.left = `${x + w + offset}px`;
             annotationEl.style.top = `${y}px`;
         }
-        // Clamp into viewport after layout settles. Using transform keeps the
-        // underlying left/top intent intact so the next call recomputes cleanly.
-        requestAnimationFrame(() => {
-            if (!annotationEl)
-                return;
-            const a = annotationEl.getBoundingClientRect();
-            const m = 8;
-            const vw = window.innerWidth;
-            const vh = window.innerHeight;
-            let dx = 0;
-            let dy = 0;
-            if (a.left < m)
-                dx = m - a.left;
-            else if (a.right > vw - m)
-                dx = vw - m - a.right;
-            if (a.top < m)
-                dy = m - a.top;
-            else if (a.bottom > vh - m)
-                dy = vh - m - a.bottom;
-            annotationEl.style.transform = dx || dy ? `translate(${dx}px, ${dy}px)` : "";
-        });
+        // Viewport clamping is handled by clampAnnotationIntoViewport(), called by
+        // the caller once the annotation is laid out (and on every reposition).
+    }
+    /**
+     * Clamp the annotation into the viewport, on BOTH positioning paths. The CSS
+     * Anchor Positioning path has no built-in way to slide a centered annotation
+     * back on-screen when the target is near a viewport edge (visible on Android
+     * Chrome, which supports anchor positioning; iOS Safari ≤18 takes the JS
+     * fallback path). Gated on `annotationShown` so it never measures a
+     * `display:none` element. See {@link clampIntoViewport}.
+     */
+    function clampAnnotationIntoViewport() {
+        if (!annotationEl || !annotationShown)
+            return;
+        clampIntoViewport(annotationEl);
     }
     function renderContent() {
         if (!annotationEl || !currentOptions.content)
@@ -406,8 +409,8 @@ export function spotlight(targetEl, fn) {
 						position: fixed;
 						position-anchor: ${anchorName};
 						position-area: ${POSITION_MAP[currentOptions.position || "bottom"] || "bottom"};
-						position-try-fallbacks: flip-block, flip-inline, flip-block flip-inline;
-						position-try-order: most-width;
+						position-try-fallbacks: ${buildPositionTryFallbacks(currentOptions.position || "bottom")};
+						position-try-order: normal;
 						max-width: calc(100vw - 1rem);
 						max-height: calc(100vh - 1rem);
 						transition-duration: ${TRANSITION}ms;
@@ -437,6 +440,10 @@ export function spotlight(targetEl, fn) {
                 backdropEl?.classList.add("spot-visible");
                 if (annotationEl) {
                     annotationEl.classList.add("spot-block");
+                    // Now display:block and laid out — clamp into the viewport before
+                    // it fades in. Applies to both the anchor and fallback paths.
+                    annotationShown = true;
+                    clampAnnotationIntoViewport();
                     requestAnimationFrame(() => {
                         annotationEl?.classList.add("spot-visible");
                     });
@@ -467,6 +474,7 @@ export function spotlight(targetEl, fn) {
         if (!isVisible)
             return;
         isVisible = false;
+        annotationShown = false;
         if (currentOptions.id) {
             spotlightOpenStates[currentOptions.id] = false;
         }
@@ -555,6 +563,7 @@ export function spotlight(targetEl, fn) {
     $effect(() => {
         return () => {
             // Cleanup on unmount
+            annotationShown = false;
             if (mountedComponent) {
                 unmount(mountedComponent);
                 mountedComponent = null;

package/dist/actions/tooltip/tooltip.svelte.js

@@ -1,5 +1,6 @@
 import { twMerge } from "../../utils/tw-merge.js";
 import { addAnchorName, removeAnchorName } from "../../utils/anchor-name.js";
+import { clampIntoViewport } from "../../utils/anchor-position.js";
 const TIMEOUT = 200;
 const TRANSITION = 200;
 /**
@@ -224,6 +225,10 @@ export function tooltip(anchorEl, fn) {
                 anchorEl.setAttribute("aria-expanded", "true");
                 //
                 tooltipEl.classList.add("tt-block");
+                // Backstop: the CSS @position-try fallbacks handle most edge cases,
+                // but can leave a residual overflow (and don't cover the "no fallback
+                // fits" case) — clamp fully on-screen now that it's laid out.
+                clampIntoViewport(tooltipEl);
                 requestAnimationFrame(() => {
                     tooltipEl.classList.add("tt-visible");
                     on_show?.();

package/dist/actions/validate.svelte.js

@@ -170,9 +170,20 @@ export function validate(el, fn) {
         // 	}">`,
         // 	{ enabled, on, hasCustomValidator: typeof customValidator === "function" }
         // );
+        // Flipped to `true` in this $effect's cleanup. Guards the deferred blur
+        // validation (and any other stray late event) from running after the action
+        // is torn down — see the guard in `_doValidate` and the `onBlur` deferral.
+        let destroyed = false;
         const _doValidate = () => {
             if (!enabled)
                 return;
+            // Bail if the action has already been torn down. Together with the
+            // deferral in `onBlur`, this makes the deferred validation a guaranteed
+            // no-op after unmount even in the rare case the node stays connected —
+            // e.g. a keyed `{#each}` move that destroys this effect while the DOM
+            // node persists, where the `isConnected` check below would still pass.
+            if (destroyed)
+                return;
             // A focused, dirty field torn down by a route change fires a final
             // synchronous `change`/`blur` while being removed from the DOM. That
             // removal runs inside Svelte's flush, so writing `validation` state here
@@ -241,13 +252,36 @@ export function validate(el, fn) {
         let _touchCount = 0;
         const onFocus = () => _touchCount++;
         el.addEventListener("focus", onFocus);
-        // also validate on first blur
+        // also validate on first blur — but DEFERRED out of the current task.
+        //
+        // When a focused, touched field is unmounted (e.g. a successful submit
+        // navigates away and tears down the form), the browser fires a final
+        // synchronous `blur` *during* Svelte's destroy flush, while the node is
+        // still connected. Running `_doValidate` there reads any consumer `$derived`
+        // belonging to the now-destroyed effect (`derived_inert` warning) and writes
+        // the parent's `validation` `$state` (`state_unsafe_mutation`, uncaught) —
+        // the existing `isConnected` guard misses it because the node hasn't been
+        // detached yet at blur time.
+        //
+        // A microtask runs *after* the synchronous flush completes: by then a
+        // torn-down node is detached and this $effect's cleanup has set `destroyed`,
+        // so `_doValidate`'s guards bail (no derived read, no state write). On a real
+        // user blur the field is still connected and alive, so validation runs as
+        // before — just one microtask later (imperceptible).
+        //
+        // Only `blur` is deferred. The `change`/`input` listener and the imperative
+        // `setDoValidate` path must stay synchronous: `onSubmitValidityCheck`
+        // dispatches synthetic `input`/`change` and reads `el.validity` immediately,
+        // and `FieldInput.validate()` reads `validation` right after invoking the
+        // exposed validator — deferring either would break submit-time validation.
         const onBlur = () => {
-            if (_touchCount === 1)
-                _doValidate();
+            if (_touchCount !== 1)
+                return;
+            queueMicrotask(_doValidate);
         };
         el.addEventListener("blur", onBlur);
         return () => {
+            destroyed = true;
             el.removeEventListener(on, _doValidate);
             el.removeEventListener("focus", onFocus);
             el.removeEventListener("blur", onBlur);

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/dist/utils/anchor-position.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared helpers for CSS Anchor Positioning based actions (spotlight, popover,
+ * tooltip).
+ */
+/**
+ * Builds the `position-try-fallbacks` value for an anchored element at a given
+ * position.
+ *
+ * For the centered positions (`top`/`bottom` are inline-centered; `left`/`right`
+ * are block-centered) a `flip-inline`/`flip-block` is a no-op on the centered
+ * axis, so the browser cannot slide the element back on-screen when the target
+ * sits near a viewport edge. We append `span-*` variants that give it an edge to
+ * align to. A JS clamp (see {@link clampIntoViewport}) should still be used as
+ * the ultimate backstop; these fallbacks just yield nicer native placement.
+ *
+ * Note: tooltip/popover declare their fallbacks via `@position-try` named rules
+ * in CSS instead and don't use this; it's primarily for the spotlight action,
+ * which sets `position-try-fallbacks` inline.
+ */
+export declare function buildPositionTryFallbacks(position: string): string;
+/**
+ * Pull an element fully into the viewport with a corrective `transform`.
+ *
+ * This is the backstop for CSS Anchor Positioning: `position-try` can only swap
+ * between discrete declared positions and cannot slide a centered annotation
+ * back on-screen when the target is near a viewport edge — so without this an
+ * anchored element can render off-screen on browsers that support anchor
+ * positioning (e.g. Android Chrome).
+ *
+ * Synchronous and flicker-free: it clears any prior transform, force-measures
+ * the natural rect (`getBoundingClientRect` triggers a synchronous layout), then
+ * applies a single translate — all within one JS turn, so the browser only
+ * paints the final, clamped position. The element MUST be laid out
+ * (`display: block`) when called, and `transform` MUST NOT be in its
+ * `transition-property` (callers use `transition-property: opacity`) so the
+ * correction applies instantly. The caller owns the element's `transform`.
+ *
+ * @param el - The (anchored, position:fixed) element to clamp
+ * @param margin - Minimum gap from each viewport edge, in px (default 8)
+ */
+export declare function clampIntoViewport(el: HTMLElement, margin?: number): void;

package/dist/utils/anchor-position.js

@@ -0,0 +1,69 @@
+/**
+ * Shared helpers for CSS Anchor Positioning based actions (spotlight, popover,
+ * tooltip).
+ */
+/**
+ * Builds the `position-try-fallbacks` value for an anchored element at a given
+ * position.
+ *
+ * For the centered positions (`top`/`bottom` are inline-centered; `left`/`right`
+ * are block-centered) a `flip-inline`/`flip-block` is a no-op on the centered
+ * axis, so the browser cannot slide the element back on-screen when the target
+ * sits near a viewport edge. We append `span-*` variants that give it an edge to
+ * align to. A JS clamp (see {@link clampIntoViewport}) should still be used as
+ * the ultimate backstop; these fallbacks just yield nicer native placement.
+ *
+ * Note: tooltip/popover declare their fallbacks via `@position-try` named rules
+ * in CSS instead and don't use this; it's primarily for the spotlight action,
+ * which sets `position-try-fallbacks` inline.
+ */
+export function buildPositionTryFallbacks(position) {
+    const flips = "flip-block, flip-inline, flip-block flip-inline";
+    if (position === "top" || position === "bottom") {
+        return `${flips}, ${position} span-left, ${position} span-right`;
+    }
+    if (position === "left" || position === "right") {
+        return `${flips}, ${position} span-top, ${position} span-bottom`;
+    }
+    return flips;
+}
+/**
+ * Pull an element fully into the viewport with a corrective `transform`.
+ *
+ * This is the backstop for CSS Anchor Positioning: `position-try` can only swap
+ * between discrete declared positions and cannot slide a centered annotation
+ * back on-screen when the target is near a viewport edge — so without this an
+ * anchored element can render off-screen on browsers that support anchor
+ * positioning (e.g. Android Chrome).
+ *
+ * Synchronous and flicker-free: it clears any prior transform, force-measures
+ * the natural rect (`getBoundingClientRect` triggers a synchronous layout), then
+ * applies a single translate — all within one JS turn, so the browser only
+ * paints the final, clamped position. The element MUST be laid out
+ * (`display: block`) when called, and `transform` MUST NOT be in its
+ * `transition-property` (callers use `transition-property: opacity`) so the
+ * correction applies instantly. The caller owns the element's `transform`.
+ *
+ * @param el - The (anchored, position:fixed) element to clamp
+ * @param margin - Minimum gap from each viewport edge, in px (default 8)
+ */
+export function clampIntoViewport(el, margin = 8) {
+    // Remove any prior correction so we measure the natural (anchored or
+    // left/top) position, then recompute from scratch.
+    el.style.transform = "";
+    const a = el.getBoundingClientRect();
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    let dx = 0;
+    let dy = 0;
+    if (a.left < margin)
+        dx = margin - a.left;
+    else if (a.right > vw - margin)
+        dx = vw - margin - a.right;
+    if (a.top < margin)
+        dy = margin - a.top;
+    else if (a.bottom > vh - margin)
+        dy = vh - margin - a.bottom;
+    if (dx || dy)
+        el.style.transform = `translate(${dx}px, ${dy}px)`;
+}

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