diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2093e53..8282b20 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,160 @@ This project follows [Semantic Versioning](https://semver.org/).
 ---
 ---
 
+## [4.2.0] — 2026-09-06
+
+Making the runtime loud where it used to be quiet. Every item below is a case
+where the library did the wrong thing — or the right thing for an unstated
+reason — without saying so, and the cost was paid by whoever had to guess. Two
+widened signatures, one new runtime behaviour, four new development warnings,
+and a production bundle that is *smaller* than 4.1.0 despite all of them. No
+breaking changes.
+
+### Fixed
+
+- **Development diagnostics now actually compile out of production builds.**
+  They did not. The dev gate led with a `globalThis.__SIBU_DEV__` lookup, and a
+  member expression is not something a bundler can substitute or fold — so
+  nothing was ever eliminated and every warning string the library can emit
+  shipped to every consumer, to be tested at runtime and never printed.
+
+  The gate is now a statically foldable constant, and the warning helpers test
+  the build-time define inline so their bodies fold to nothing even in a
+  published `dist` chunk. A production consumer's bundle no longer contains the
+  diagnostics at all — so the core runtime is smaller than 4.1.0 despite
+  everything added below:
+
+  | gzipped, minified, `__SIBU_DEV__: false` | 4.1.0 | 4.2.0 |
+  | --- | --- | --- |
+  | `sibujs` | 26,895 | **25,836** |
+  | `sibujs/plugins` | 28,877 | **28,615** |
+  | `sibujs/ui` | 16,462 | **16,112** |
+  | `dist/cdn.global.js` | 27,289 | **26,224** |
+  | application exercising every warning below | 33,658 | **32,958** |
+
+  `tests/treeshaking-dev-diagnostics.test.ts` bundles for real and fails if any
+  diagnostic string survives, and `tests/dist-artifacts.test.ts` asserts the
+  same thing against the built `dist/` files — the source-level test could not
+  see the CDN bundle, which is exactly where the leak hid. Development builds
+  grow, which is where the diagnostics are supposed to be: the same application
+  is 53,079 bytes gzipped with `__SIBU_DEV__: true`.
+
+- **The CDN bundle shipped every diagnostic and could not be stripped.** The
+  CDN build applied no `__SIBU_DEV__` define at all, and a
+  `<script src="…/cdn.global.js">` consumer has no bundler to fold it later —
+  the published bytes are what runs. Worse, with no define and no `process` in
+  a browser the dev gate resolves to `false` at runtime, so those thousands of
+  bytes of warning text were downloaded and parsed to never print.
+
+  `dist/cdn.global.js` is now built with `__SIBU_DEV__: false` and contains no
+  diagnostic text at all.
+
+### Added
+
+- **`dist/cdn.dev.global.js`** — a development CDN bundle, exported as
+  `sibujs/cdn-dev`. Stripping the production CDN would otherwise have left
+  no-build users with no diagnostics at all; loading this file instead turns
+  every warning on without a build step, which is the point of having them in a
+  no-build workflow. Use `dist/cdn.global.js` in production.
+
+- **`RouterLink` ignored a reactive `class`.** Tag factories honour a getter or
+  a `{ name: condition }` map; `RouterLink` read the prop with
+  `typeof classAttr === "string"`, so any other form fell through to `""` and
+  the attribute was simply never written — no error, no class, no clue. It now
+  resolves the prop through the same helper the tag factories use, inside the
+  effect that maintains active-link state, so a getter is genuinely reactive
+  rather than merely accepted.
+
+- **A focused field lost the caret on every reactive rebuild.** A block that
+  re-creates its children takes focus,
+  selection and IME state with it, so typing one character into an input inside
+  such a block ended the edit. Focus and the selection range are now restored
+  when the rebuilt subtree contains an element of re-establishable identity
+  (`data-focus-key`, `id`, or `name`), and the runtime warns in development when
+  it cannot.
+
+  It does not guess. A match must be unique — `name` is shared by every radio in
+  a group, and moving the caret to a sibling control is worse than losing it —
+  and focus is only restored when it was genuinely lost, never when the rebuild
+  moved it somewhere deliberately. An in-progress IME composition cannot be
+  preserved at all, because the composition belongs to the destroyed node; the
+  warning says so rather than implying otherwise.
+
+- **The style sanitizer dropped `url()` declarations in silence.** The guard is
+  correct and stays — `url()` in an inline style is an exfiltration channel —
+  but a blocked `background-image` reads as a rendering bug, not a security
+  decision, and images rendered as empty boxes across several renderers with
+  nothing in any console. Each dropped declaration is now announced in
+  development, naming the property, the value, the element, why it went, and the
+  sanctioned alternatives (`<img>` for content, a stylesheet class for
+  decoration — stylesheet CSS is not sanitized). Exactly one warning per dropped
+  declaration, de-duplicated per element so a reactive style cannot flood the
+  console.
+
+- **The duplicate-runtime warning gave obsolete advice.** It told users to
+  configure `optimizeDeps.exclude`, which the reactive core's global registry
+  already makes unnecessary — every copy routes through the first one, so signal
+  writes reach subscribers registered by any of them. Duplication is a size
+  problem, not a correctness one, and the message now says that.
+
+### Changed
+
+- **`show`, `when` and `match` accept both an element and a factory.** The
+  shapes disagreed: `show(cond, element)` took an element while
+  `when(cond, () => el)` took thunks. Passing the wrong one produced an obscure
+  `TypeError` from inside the directive, or — for `when` — rendered nothing at
+  all and said nothing. Every form is accepted everywhere now; a factory is
+  still rebuilt per switch, and a bare element is re-attached as-is.
+
+  A re-attached element keeps its own reactive bindings: the directive did not
+  create it and does not tear it down. Development warns on the reuse, because
+  the node also brings back whatever state it accumulated while detached.
+
+- **The lone-string class warning is narrower, and reports once.** It now
+  requires two or more whitespace-separated tokens with at least two
+  utility-shaped, where before any single token carrying a hyphen, colon, slash
+  or digit was enough.
+
+  The old rule flagged the identifiers applications legitimately render as text
+  — `item-0`, `home-content`, `user-42`, `v4.1.0`, `src/index.ts`,
+  `https://example.com`, `N/A` — at a measured 29.8% false-positive rate, and a
+  list rendering `item-0` through `item-999` produced a thousand warnings. The
+  new rule measures 0% on the same 131-string corpus, and a repeated mistake is
+  reported once per tag and string rather than once per element.
+
+  Both de-duplication caches are bounded at 100 distinct entries, and reaching
+  that bound stops reporting rather than merely stopping remembering — the
+  latter would let every mistake after the hundredth warn on every render, which
+  is the flood the cache exists to prevent. The suppression announces itself
+  once, so nothing goes quiet without saying so.
+
+  The cost, stated plainly: single-token class lists no longer warn.
+  `div("space-y-6")` and `div("truncate")` pass silently, where the first used
+  to be caught. A single hyphen-and-digit token is not distinguishable from an
+  identifier, and a warning developers learn to ignore protects nobody. The
+  multi-token form remains both the originally reported bug and the dominant
+  real-world shape. Measurements live in
+  `tests/lone-string-heuristic-rate.test.ts`.
+
+- **Sanitizer entry points take an optional context.** `sanitizeCSSValue`,
+  `sanitizeStyleAttribute` and `sanitizeAttributeString` accept an optional
+  property/element used only to enrich the development warning. It never changes
+  a security decision, and every existing call site keeps working.
+
+### Documentation
+
+- Every exported function reachable from an entry point now carries a doc
+  comment saying what it does and what it returns — the router's navigation and
+  guard API, the form validators, the tracking primitives, and the widget and
+  UI factories among them. Signatures that used to require reading
+  `dist/index.d.ts` are documented at the source.
+
+- Functions that participate in a known trap say so, and name the way out:
+  `when` and `match` carry the keying pattern that avoids destroying a live
+  edit; `show` explains when to prefer `when` and what that costs.
+
+---
+
 ## [4.1.0] — 2026-09-03
 
 Progressive-enhancement ergonomics, driven by building a complete chess
diff --git a/README.md b/README.md
index 9c3703b..c2b6530 100644
--- a/README.md
+++ b/README.md
@@ -200,13 +200,37 @@ Utilities for testing components and reactivity.
 ### `sibujs/cdn` — Script-tag bundle
 Self-registering IIFE build exposing `window.Sibu`, for use without a bundler.
 
+There are two builds. Load **exactly one** — they both define `window.Sibu`, so
+loading both leaves whichever came last in charge.
+
+Development, with every diagnostic live:
+
+```html
+<script src="https://unpkg.com/sibujs@latest/dist/cdn.dev.global.js"></script>
+```
+
+Production, with diagnostics compiled out rather than merely disabled:
+
 ```html
 <script src="https://unpkg.com/sibujs@latest/dist/cdn.global.js"></script>
+```
+
+Either way, the API is on `window.Sibu`:
+
+```html
 <script>
   const { signal, effect, div, mount } = window.Sibu;
 </script>
 ```
 
+Develop against `cdn.dev.global.js` and swap the one line to ship. The runtime
+behaviour is identical; only the warnings differ.
+
+A bundled app needs neither file — import from `"sibujs"` and let your bundler
+define `__SIBU_DEV__` per build (the Vite and webpack plugins in `sibujs/build`
+do this for you). The two CDN files exist because a `<script>` tag has no
+bundler to make that choice.
+
 ---
 
 ## Ecosystem
diff --git a/docs/interop.md b/docs/interop.md
index a71c0fd..2f19520 100644
--- a/docs/interop.md
+++ b/docs/interop.md
@@ -142,6 +142,11 @@ competing for the DOM, so rules 1–5 are all you need:
 No build step, no bundler, no npm. Emit the markup from whatever templating
 language you already use; the `data-ref` attributes are just attributes.
 
+> **Development vs production.** The snippet above loads the production bundle,
+> where development warnings are compiled out. While building, load
+> `dist/cdn.dev.global.js` instead — same runtime, warnings on — and switch back
+> to `dist/cdn.global.js` to ship. See the CDN section of the README.
+
 **Per-host notes:**
 
 - **Django / Rails / Laravel** — render the island in a partial/template so the
diff --git a/docs/islands.md b/docs/islands.md
index 268f230..6f7c6b5 100644
--- a/docs/islands.md
+++ b/docs/islands.md
@@ -754,6 +754,11 @@ No npm, no transpile — one HTML file:
 </script>
 ```
 
+> **Development vs production.** The snippet above loads the production bundle,
+> where development warnings are compiled out. While building, load
+> `dist/cdn.dev.global.js` instead — same runtime, warnings on — and switch back
+> to `dist/cdn.global.js` to ship. See the CDN section of the README.
+
 A complete, runnable version (multiple islands and strategies) lives in
 [`examples/islands.html`](../examples/islands.html).
 
diff --git a/examples/islands.html b/examples/islands.html
index 871e8b6..40c9c82 100644
--- a/examples/islands.html
+++ b/examples/islands.html
@@ -43,8 +43,13 @@ <h1>Reactive islands, zero build</h1>
       <p>Seconds on screen: <span class="count" data-ref="secs">0</span></p>
     </div>
 
-    <!-- The ONLY script tags on the page. In production, point src at the CDN:
-         https://unpkg.com/sibujs@latest/dist/cdn.global.js -->
+    <!-- The ONLY script tags on the page. Point src at the CDN to run this
+         without a local build:
+           production   https://unpkg.com/sibujs@latest/dist/cdn.global.js
+           development  https://unpkg.com/sibujs@latest/dist/cdn.dev.global.js
+         The two are identical at runtime; the development build additionally
+         emits SibuJS's warnings, which are compiled out of the production one.
+         Swap the local src below for ../dist/cdn.dev.global.js to see them. -->
     <script src="../dist/cdn.global.js"></script>
     <script>
       // Surface a load failure instead of failing silently. If you see this,
diff --git a/package-lock.json b/package-lock.json
index 84b076a..4e60790 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "sibujs",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "sibujs",
-      "version": "4.1.0",
+      "version": "4.2.0",
       "license": "MIT",
       "devDependencies": {
         "@biomejs/biome": "2.4.7",
diff --git a/package.json b/package.json
index aba45ca..9be92d0 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "sibujs",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "A lightweight, function-based frontend framework that combines the best of React, Svelte, and Vue — with zero VDOM and maximum simplicity. Designed for developers who want fine-grained reactivity and full control without compilation or magic.",
   "keywords": [
     "frontend",
@@ -40,7 +40,7 @@
     "typecheck": "tsc --noEmit",
     "typecheck:tests": "tsc -p tsconfig.test.json",
     "certify:rc": "node scripts/certify/run.mjs",
-    "build": "tsup index.ts data.ts browser.ts patterns.ts motion.ts ui.ts widgets.ts ssr.ts devtools.ts performance.ts ecosystem.ts plugins.ts build.ts testing.ts extras.ts --dts --format esm,cjs --out-dir dist --clean && tsup cdn.ts --format iife --globalName Sibu --out-dir dist --no-dts --minify",
+    "build": "tsup index.ts data.ts browser.ts patterns.ts motion.ts ui.ts widgets.ts ssr.ts devtools.ts performance.ts ecosystem.ts plugins.ts build.ts testing.ts extras.ts --dts --format esm,cjs --out-dir dist --clean && tsup --config tsup.cdn.config.ts",
     "example:chess:build": "node scripts/build-example-chess.mjs",
     "example:serve": "node tests-browser/server.mjs",
     "bench": "node bench.mjs",
@@ -130,6 +130,9 @@
     },
     "./cdn": {
       "default": "./dist/cdn.global.js"
+    },
+    "./cdn-dev": {
+      "default": "./dist/cdn.dev.global.js"
     }
   },
   "publishConfig": {
diff --git a/scripts/certify/exports-audit.mjs b/scripts/certify/exports-audit.mjs
index eeaa974..06672a1 100644
--- a/scripts/certify/exports-audit.mjs
+++ b/scripts/certify/exports-audit.mjs
@@ -124,13 +124,17 @@ for (const subpath of subpaths) {
   const entry = pkg.exports[subpath];
   const targets = typeof entry === "string" ? { default: entry } : entry;
 
-  // `./cdn` is an IIFE global build, not an ESM module — resolve-only.
+  // The `./cdn*` entries are IIFE global builds, not ESM modules —
+  // resolve-only. Matched by prefix so the production and development
+  // bundles are both covered without listing each one, and so a future
+  // variant does not fail the audit for being a global build.
+  const isGlobalBuild = subpath === "./cdn" || subpath.startsWith("./cdn-");
   const importable = Boolean(targets.import ?? targets.default?.endsWith(".js"));
 
   const timersBefore = timerLog.length;
   const readsBefore = listenerLog.length;
 
-  if (importable && subpath !== "./cdn") {
+  if (importable && !isGlobalBuild) {
     try {
       const ns = await import(spec);
       const named = Object.keys(ns).filter((k) => k !== "default");
@@ -191,7 +195,7 @@ for (const subpath of subpaths) {
   if (targets.types) {
     if (existsSync(resolve(PKG_DIR, targets.types))) pass(subpath, "types", targets.types);
     else fail(subpath, "types", `${targets.types} MISSING`);
-  } else if (subpath !== "./cdn") {
+  } else if (!isGlobalBuild) {
     fail(subpath, "types", "no `types` condition declared");
   } else {
     pass(subpath, "types", "n/a (global build)");
diff --git a/scripts/certify/node-matrix.mjs b/scripts/certify/node-matrix.mjs
index 5f677fb..a0771ef 100644
--- a/scripts/certify/node-matrix.mjs
+++ b/scripts/certify/node-matrix.mjs
@@ -264,7 +264,12 @@ for (const target of WANT) {
     // so a newly added entry cannot silently escape the matrix (§11).
     const pkgPath = join(consumer, "node_modules", "sibujs", "package.json");
     const subpaths = Object.keys(JSON.parse(readFileSync(pkgPath, "utf8")).exports ?? {});
-    const importable = subpaths.filter((s) => s !== "./cdn" && s !== "./package.json");
+    // `./cdn*` are IIFE global builds with no ESM/CJS shape to import, so
+    // they are resolve-only here. Prefix match keeps the production and
+    // development bundles in step without hard-coding each name.
+    const importable = subpaths.filter(
+      (s) => s !== "./package.json" && s !== "./cdn" && !s.startsWith("./cdn-"),
+    );
     const specs = importable.map((s) => (s === "." ? "sibujs" : `sibujs${s.slice(1)}`));
 
     writeFileSync(
diff --git a/src/core/dev.ts b/src/core/dev.ts
index 1b30bbc..bb1e2d8 100644
--- a/src/core/dev.ts
+++ b/src/core/dev.ts
@@ -6,43 +6,162 @@
  *
  * In production: dead code elimination removes all dev checks entirely.
  * In development: provides clear, actionable error messages.
+ *
+ * `tests/treeshaking-dev-diagnostics.test.ts` bundles this for real and asserts
+ * the message strings are gone, so a regression here fails the suite rather
+ * than quietly shipping every warning to every consumer.
  */
 
 declare const __SIBU_DEV__: boolean | undefined;
 
 /**
- * Returns true when running in development mode.
- * Tree-shakes to `false` in production builds.
+ * Dev mode as a **statically foldable constant**, snapshotted at module load.
+ *
+ * Prefer this over {@link isDev} for any guard whose only job is to gate a
+ * diagnostic. The distinction is not stylistic — it decides whether the
+ * diagnostic exists in a consumer's production bundle:
+ *
+ * - `DEV` inlines its `__SIBU_DEV__` define into every reference, so
+ *   `if (DEV) …` becomes `if (false) …` and the whole branch — warning strings
+ *   included — is deleted.
+ * - `isDev()` is a function CALL. Bundlers do not inline calls across modules,
+ *   so `const _isDev = isDev()` produces a runtime `var` and every branch that
+ *   reads it survives minification with its message strings intact. That alias
+ *   is exactly why this library used to ship every warning it could emit.
+ *
+ * Use {@link isDev} only where the answer must be read LIVE at call time rather
+ * than snapshotted at import time (devtools opt-in defaults, `strict()`).
+ *
+ * THREE THINGS ABOUT THIS DECLARATION ARE LOAD-BEARING. Changing any of them
+ * silently un-strips every diagnostic in the library:
+ *
+ * 1. **It must be the first declaration in this module.** esbuild inlines a
+ *    cross-module `const` only when no hoisted declaration precedes it;
+ *    anything above it (a function, another const) makes the inliner give up
+ *    and emit a runtime `var` instead. Verified empirically — moving `isDev`
+ *    above this line is enough to put every warning string back in the bundle.
+ * 2. **It must be an inline expression, not `isDev()`.** A cross-module call is
+ *    opaque to the bundler, which is the problem this constant exists to solve.
+ * 3. **The bare `__SIBU_DEV__` must come first in the ladder.** Only a bare
+ *    identifier is a `define` target; `globalThis.__SIBU_DEV__` is a member
+ *    expression and can never be substituted or folded.
+ *
+ * With no define at all (raw ESM, the test runner) an unqualified
+ * `__SIBU_DEV__` resolves to the global of that name, so the first branch reads
+ * the same value the `globalThis` branch would — which is why it coerces with
+ * `!!`: a test may set the override to `1` or `0` and still expect a strict
+ * boolean back. The runtime escape hatch `tests/prod-mode.test.ts` relies on
+ * keeps working, and diagnostics correctly stay in an unconfigured build.
+ */
+export const DEV: boolean =
+  typeof __SIBU_DEV__ !== "undefined"
+    ? !!__SIBU_DEV__
+    : typeof (globalThis as any).__SIBU_DEV__ !== "undefined"
+      ? !!(globalThis as any).__SIBU_DEV__
+      : // safe default: off in browser, on in test/dev Node
+        typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
+
+/**
+ * Returns true when running in development mode, read LIVE at call time.
+ *
+ * Unlike {@link DEV} this is a real call, so it observes a `__SIBU_DEV__`
+ * global that changed after module load. That also means it cannot be folded
+ * away: use it for behavior (devtools defaults, `strict()`), never as the guard
+ * on a warning string, or the string ships to production.
+ *
+ * @returns `true` in development, `false` in production.
  */
 export function isDev(): boolean {
-  return typeof (globalThis as any).__SIBU_DEV__ !== "undefined"
-    ? !!(globalThis as any).__SIBU_DEV__
-    : // The bare `__SIBU_DEV__` is a bundler define that only exists in
-      // production builds; under the test runner it is always undefined, so
-      // this branch is unreachable here.
-      /* v8 ignore next 2 */
-      typeof __SIBU_DEV__ !== "undefined"
-      ? __SIBU_DEV__
-      : typeof process !== "undefined" && process.env?.NODE_ENV !== "production"; // safe default: off in browser, on in test/dev Node
+  // globalThis FIRST — the opposite of {@link DEV}, deliberately.
+  //
+  // This function exists to be read live, and only the runtime global can
+  // change after load. Consulting the bare `__SIBU_DEV__` first would let a
+  // build-time define answer for it in any bundled build, making the runtime
+  // override dead code there and turning this into a slower copy of `DEV` —
+  // while the doc above promised a live read. Nothing here needs to fold, so
+  // ordering costs nothing.
+  if (typeof (globalThis as any).__SIBU_DEV__ !== "undefined") return !!(globalThis as any).__SIBU_DEV__;
+  if (typeof __SIBU_DEV__ !== "undefined") return !!__SIBU_DEV__;
+  return typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
 }
 
-// Cache dev mode at module load — avoids 3 typeof checks per call
-const _isDev = isDev();
-
 /**
  * Assert a condition in dev mode only. No-op in production.
+ *
+ * @param condition Asserted expression; a falsy value throws in dev.
+ * @param message Message for the thrown error, prefixed with `[SibuJS]`.
+ * @returns Nothing. Throws in dev when `condition` is falsy; in production the
+ * entire body — message string included — is eliminated at build time.
  */
 export function devAssert(condition: boolean, message: string): void {
-  if (_isDev && !condition) {
+  // See `devWarn` for why the define test is repeated inline instead of reusing
+  // `DEV`. Same reason, same requirement: this body must be able to fold to
+  // nothing so the message strings never reach a production bundle.
+  if ((typeof __SIBU_DEV__ !== "undefined" ? __SIBU_DEV__ : DEV) && !condition) {
     throw new Error(`[SibuJS] ${message}`);
   }
 }
 
 /**
  * Warn in dev mode only. No-op in production.
+ *
+ * Because the body is guarded by {@link DEV}, a production bundler folds this
+ * function to an empty one, inlines it at every call site, and drops the
+ * message literals with it — so a `devWarn` call costs nothing in production
+ * even when the call site itself is unguarded.
+ *
+ * @param message Warning text, printed to `console.warn` prefixed `[SibuJS]`.
+ * @returns Nothing.
  */
+/**
+ * Warn in dev only, composing the message lazily.
+ *
+ * @param build Called only in development; returns the warning text. Returning
+ * an empty string suppresses the warning, which lets a builder do its own
+ * de-duplication without that bookkeeping escaping into production.
+ * @returns Nothing. In production the call, the callback, and every string and
+ * lookup table the callback references are eliminated at build time.
+ */
+export function devWarnLazy(build: () => string): void {
+  // Same inline define test as `devWarn`, for the same reason — but this form
+  // also strips the WORK of composing the message, not just the call.
+  //
+  // `if (DEV) { const why = …long text…; devWarn(why); }` does NOT strip in a
+  // published build: `DEV` arrives as a runtime var there, so the branch is not
+  // provably dead and its string literals ship. Moving the composition into a
+  // callback fixes it, because this body folds to nothing, the bundler inlines
+  // it, and the now-unreferenced closure — with every literal and lookup table
+  // it touched — is tree-shaken away.
+  //
+  // Use this for any diagnostic that branches on the situation, interpolates,
+  // or reads a table of explanatory text. Use `devWarn` for a plain literal.
+  if (typeof __SIBU_DEV__ !== "undefined" ? __SIBU_DEV__ : DEV) {
+    const message = build();
+    if (message) console.warn(`[SibuJS] ${message}`);
+  }
+}
+
 export function devWarn(message: string): void {
-  if (_isDev) {
+  // The `__SIBU_DEV__` test is repeated INLINE here rather than reusing `DEV`,
+  // and that redundancy is the point.
+  //
+  // `DEV` folds only when it is the first declaration in the emitted module.
+  // That holds when a consumer bundles this package's SOURCE, but the published
+  // `dist` chunk carries the bundler's own runtime helpers (`__defProp`,
+  // `__export`) above it, which is enough to make the downstream inliner give
+  // up: `DEV` arrives as a runtime `var`, this body never becomes empty, and
+  // every message string in the library ships to production even though none
+  // can ever print.
+  //
+  // Testing the define directly sidesteps that entirely. With
+  // `__SIBU_DEV__: false` the condition folds to `false` here regardless of how
+  // `DEV` was emitted, the body becomes empty, and the bundler then inlines
+  // this function at each call site and drops the message argument with it —
+  // so an unguarded `devWarn(…)` costs a production consumer nothing.
+  //
+  // With no define, an unqualified `__SIBU_DEV__` resolves to the global of
+  // that name, so the behaviour is identical to reading `DEV`.
+  if (typeof __SIBU_DEV__ !== "undefined" ? __SIBU_DEV__ : DEV) {
     console.warn(`[SibuJS] ${message}`);
   }
 }
diff --git a/src/core/errors.ts b/src/core/errors.ts
index 4d13c0a..f4a8329 100644
--- a/src/core/errors.ts
+++ b/src/core/errors.ts
@@ -110,6 +110,8 @@ function state(): RuntimeErrorState {
  * This is application/runtime-global state, NOT request-scoped: under SSR it is
  * shared by every concurrent request in the process. Install it once at startup
  * and derive any request-specific detail from the error/context instead.
+ *
+ * @returns The previously installed handler, so a caller can restore it.
  */
 export function setRuntimeErrorHandler(handler: RuntimeErrorHandler | null): RuntimeErrorHandler | null {
   const s = state();
@@ -118,7 +120,11 @@ export function setRuntimeErrorHandler(handler: RuntimeErrorHandler | null): Run
   return prev;
 }
 
-/** The currently installed runtime error handler, if any. */
+/**
+ * Read the currently installed runtime error handler.
+ *
+ * @returns The installed handler, or `null` when none is set.
+ */
 export function getRuntimeErrorHandler(): RuntimeErrorHandler | null {
   return state().handler;
 }
diff --git a/src/core/rendering/context.ts b/src/core/rendering/context.ts
index c625b97..4e2708e 100644
--- a/src/core/rendering/context.ts
+++ b/src/core/rendering/context.ts
@@ -1,9 +1,7 @@
-import { devWarn, isDev } from "../dev";
+import { DEV, devWarn } from "../dev";
 import { signal } from "../signals/signal";
 import { isSSR } from "../ssr-context";
 
-const _isDev = isDev();
-
 /**
  * Context API for SibuJS — a reactive global value that any component
  * can read without prop drilling.
@@ -72,7 +70,7 @@ export function context<T>(defaultValue: T): Context<T> {
   // surprise to anyone arriving from React/Vue/Solid. Rather than silently
   // producing cross-request data bleed, say so at the point of misuse.
   const warnIfSSR = (method: string): void => {
-    if (!_isDev || !isSSR()) return;
+    if (!DEV || !isSSR()) return;
     devWarn(
       `context.${method}() called during SSR. SibuJS context() is application-global — it is NOT ` +
         "isolated per request, so a concurrent request can observe this value. Do not use context() " +
@@ -113,7 +111,7 @@ export function context<T>(defaultValue: T): Context<T> {
         // with a promise-aware restore: because the value is global, that would
         // still not isolate overlapping async scopes, and would merely make the
         // hazard harder to see. See docs/architecture/context.md.
-        if (_isDev && result !== null && typeof (result as { then?: unknown })?.then === "function") {
+        if (DEV && result !== null && typeof (result as { then?: unknown })?.then === "function") {
           devWarn(
             "context.withContext() received an async callback. Scoping is synchronous only — the " +
               "previous value is restored as soon as the callback returns its promise, so anything " +
diff --git a/src/core/rendering/directives.ts b/src/core/rendering/directives.ts
index 413ee10..4ce6b10 100644
--- a/src/core/rendering/directives.ts
+++ b/src/core/rendering/directives.ts
@@ -1,39 +1,65 @@
 import { track } from "../../reactivity/track";
+import { devWarnLazy } from "../dev";
 import { dispose, registerDisposer } from "./dispose";
+import { captureFocusWithin, restoreFocusWithin } from "./focusPreservation";
 import type { NodeChild } from "./types";
 
 /**
  * Conditional rendering directive. Shows or hides an element reactively.
  * Unlike `when()`, the element is always created — it just toggles display.
  *
+ * Accepts the element either directly or as a thunk, so the same call shape
+ * works here and in {@link when}. Which one you pass changes nothing: `show`
+ * never rebuilds, so a thunk is invoked exactly once, immediately.
+ *
  * @param condition Reactive getter returning boolean
- * @param element The element to show/hide
- * @returns The element with reactive display binding
+ * @param element The element to show/hide, or a function returning it
+ * @returns The element itself (not a wrapper), with a reactive display binding.
+ * The caller keeps the live node and can mutate it or attach listeners to it.
  *
  * @example
  * ```ts
  * const [visible, setVisible] = signal(true);
  * div([show(() => visible(), span("I toggle!"))]);
+ * div([show(() => visible(), () => span("also fine"))]);
  * ```
+ *
+ * TRAP — `show` keeps the element in the DOM and toggles `display`. Use
+ * {@link when} when the content must not exist at all while hidden (an
+ * expensive subtree, or one whose mere presence is observable). Note that
+ * `when` REBUILDS on every condition change, which discards focus and
+ * selection inside the branch — see the note on `when`.
  */
-export function show<T extends Element>(condition: () => boolean, element: T): T {
+export function show<T extends Element>(condition: () => boolean, element: T | (() => T)): T {
+  // Widened from `element: T`. `when` took thunks while `show` took an element,
+  // so passing one API's shape to the other failed — silently for `when`, and
+  // for `show` as a `TypeError` about `style` on `undefined` raised from inside
+  // the directive rather than at the call site. Both shapes work in both places
+  // now, which removes the mistake rather than reporting it.
+  const resolved: T = typeof element === "function" ? (element as () => T)() : element;
   const update = () => {
-    (element as unknown as HTMLElement).style.display = condition() ? "" : "none";
+    (resolved as unknown as HTMLElement).style.display = condition() ? "" : "none";
   };
   // Register the teardown on the element so disposing the element (e.g. when an
   // enclosing each/when row is removed) also stops the condition subscription.
   // Without this the effect — and everything it closes over — leaks forever.
-  registerDisposer(element, track(update));
-  return element;
+  registerDisposer(resolved, track(update));
+  return resolved;
 }
 
 /**
  * Conditional rendering directive. Renders content only when condition is true.
  * When false, renders nothing (comment placeholder). Re-evaluates reactively.
  *
- * @param condition Reactive getter returning boolean
- * @param thenBranch Function returning element when true
- * @param elseBranch Optional function returning element when false
+ * Each branch may be a THUNK (rebuilt on every condition change) or a bare
+ * element/value (attached as-is, and re-attached unchanged on every later
+ * change). Both shapes are accepted so that `when` and {@link show} take the
+ * same arguments; a bare element used to be accepted and then silently render
+ * nothing, because the directive called it as a function only.
+ *
+ * @param condition Reactive getter; its value is compared to decide the branch
+ * @param thenBranch Element, value, or function returning one, used when truthy
+ * @param elseBranch Optional counterpart used when falsy
  * @returns A Comment anchor that manages the conditional content
  *
  * @example
@@ -43,6 +69,7 @@ export function show<T extends Element>(condition: () => boolean, element: T): T
  *   () => div("Welcome!"),
  *   () => div("Please log in")
  * );
+ * when(() => isLoggedIn(), div("Welcome!"));   // also valid
  * ```
  *
  * GOTCHA — branch factories rebuild only when `condition` changes. A signal
@@ -53,13 +80,83 @@ export function show<T extends Element>(condition: () => boolean, element: T): T
  * ```
  * Drive per-branch reactivity with a nested getter (or a reactive child), not a
  * bare read in the factory body.
+ *
+ * TRAP — a rebuild DESTROYS the outgoing branch, so focus, selection and any
+ * in-progress IME composition inside it are lost. The runtime restores focus
+ * when the rebuilt branch contains an element with the same `id`, `name`, or
+ * `data-focus-key`, and warns in dev when it cannot. For a subtree holding a
+ * live edit, prefer {@link match} keyed on a shape key so the subtree is
+ * rebuilt only when the shape genuinely changes.
  */
-export function when<T>(condition: () => T, thenBranch: () => NodeChild, elseBranch?: () => NodeChild): Comment {
+/**
+ * Resolve one branch of `when`/`match`, insert it after the anchor, and report
+ * whether the calling directive OWNS the resulting node.
+ *
+ * Ownership decides disposal, and getting it wrong is silent in both
+ * directions: dispose a node the caller still holds and its reactive bindings
+ * die with no error; fail to dispose one nobody else references and its
+ * bindings leak. The rule is that a directive owns only what it produced —
+ * a node returned by a factory, or a text node built from a primitive.
+ *
+ * A factory that closes over ONE element and returns it every time (`() => el`)
+ * is the element form wearing a function's clothes. It is detected on the
+ * second attach and demoted to unowned, which stops repeated disposal; the
+ * first switch-away has already disposed it, so the dev warning names the fix.
+ */
+function attachBranch(
+  parent: Node,
+  anchor: Comment,
+  branch: NodeChild,
+  attachedOnce: WeakSet<Node>,
+  where: string,
+): { node: Node | null; owned: boolean } {
+  // A function branch is a FACTORY and is invoked; anything else is already
+  // the content. `NodeChild` includes `() => NodeChild`, so this one check
+  // covers thunks, accessors, elements, strings and numbers alike.
+  const result = typeof branch === "function" ? (branch as () => NodeChild)() : branch;
+  if (result == null || typeof result === "boolean") return { node: null, owned: false };
+
+  const node = result instanceof Node ? result : document.createTextNode(String(result));
+  const handedIn = node === (branch as unknown as Node);
+  const seenBefore = attachedOnce.has(node);
+  const owned = !handedIn && !seenBefore;
+
+  // Recorded unconditionally. Ownership must not depend on the build mode: if
+  // this bookkeeping were dev-only, a `() => stableEl` factory would be treated
+  // as unowned in dev and disposed in production — the worst kind of bug, one
+  // that only exists in the build nobody debugs.
+  attachedOnce.add(node);
+
+  if (seenBefore) {
+    // Lazy so the branch-dependent text is composed only in dev; see
+    // `devWarnLazy` for why an `if (DEV)` block would ship these literals.
+    devWarnLazy(
+      () =>
+        `${where}: ${handedIn ? "a branch was given as an element rather than a function" : "a branch factory returned a node it had already returned"}, ` +
+        "so the SAME node is being re-attached — any state it accumulated while detached (input value, scroll " +
+        "position, classes set imperatively) comes back with it. Its reactive bindings are left intact rather than " +
+        "disposed, because the node is not this directive's to tear down. Return a FRESH node per call " +
+        "(`() => div(…)`) for rebuild semantics, or keep this form deliberately when the reuse is what you want.",
+    );
+  }
+
+  parent.insertBefore(node, anchor.nextSibling);
+  return { node, owned };
+}
+
+export function when<T>(condition: () => T, thenBranch: NodeChild, elseBranch?: NodeChild): Comment {
   const anchor = document.createComment("when");
   let currentNode: Node | null = null;
   let lastCondition: T | undefined;
 
   let initialized = false;
+  // Tracks whether a bare-element branch has already been attached once, so the
+  // reuse warning fires on genuine reuse rather than on first render.
+  const attachedOnce = new WeakSet<Node>();
+  // Whether `currentNode` was produced BY this directive (a factory call, or a
+  // text node built from a primitive) or merely handed to it. Only the former
+  // may be disposed — see the teardown below.
+  let currentNodeOwned = false;
 
   const update = () => {
     // Always evaluate condition to register reactive dependencies
@@ -72,19 +169,32 @@ export function when<T>(condition: () => T, thenBranch: () => NodeChild, elseBra
     if (initialized && show === lastCondition) return;
     lastCondition = show;
 
-    // Remove previous node
+    // Snapshot focus before the outgoing branch is detached — afterwards
+    // `document.activeElement` has already fallen back to <body>.
+    const focused = currentNode ? captureFocusWithin([currentNode]) : null;
+
+    // Remove previous node.
+    //
+    // Disposing is ownership-dependent. A FACTORY branch is rebuilt on the next
+    // switch, so its old node is garbage and must be disposed or its bindings
+    // leak. A BARE ELEMENT branch is the same node every time: the caller built
+    // it, holds a reference to it, and gets it back on the next switch.
+    // Disposing that node tore down every reactive binding on it, so the
+    // element came back inert — its reactive class/style/text silently stopped
+    // updating, with nothing logged. Detaching is enough; teardown belongs to
+    // whoever created it.
     if (currentNode?.parentNode) {
-      dispose(currentNode);
+      if (currentNodeOwned) dispose(currentNode);
       currentNode.parentNode.removeChild(currentNode);
       currentNode = null;
     }
 
-    const result = show ? thenBranch() : elseBranch ? elseBranch() : null;
-    if (result != null) {
-      const node = result instanceof Node ? result : document.createTextNode(String(result));
-      parent.insertBefore(node, anchor.nextSibling);
-      currentNode = node;
-    }
+    const branch = show ? thenBranch : elseBranch !== undefined ? elseBranch : null;
+    const attached = attachBranch(parent, anchor, branch, attachedOnce, "when");
+    currentNode = attached.node;
+    currentNodeOwned = attached.owned;
+
+    restoreFocusWithin(focused, currentNode ? [currentNode] : [], "when");
     initialized = true;
   };
 
@@ -127,17 +237,37 @@ export function when<T>(condition: () => T, thenBranch: () => NodeChild, elseBra
  * GOTCHA — like `when()`, a case factory rebuilds only when the matched key
  * changes. A signal read eagerly inside a case is frozen at build time; use a
  * nested getter (`() => div(() => label())`) for reactive per-case content.
+ *
+ * THIS IS THE KEYING PATTERN for subtrees that hold a live edit. Because the
+ * subtree is rebuilt only when the KEY changes — not on every read of every
+ * signal inside it — a form can update its contents through reactive attributes
+ * and text children while its inputs keep focus, selection and IME state:
+ *
+ * ```ts
+ * // Rebuilds only when the form's shape changes, not on every keystroke.
+ * match(
+ *   () => `${entity()}:${mode()}`,
+ *   { "user:edit": () => UserForm(), "user:view": () => UserCard() },
+ * );
+ * ```
+ *
+ * Cases and the fallback accept a bare element as well as a factory, matching
+ * {@link when} and {@link show}. A bare element is re-attached rather than
+ * rebuilt, so it keeps whatever state it accumulated.
  */
 export function match<T extends string | number>(
   value: () => T,
-  cases: Record<string, () => NodeChild>,
-  fallback?: () => NodeChild,
+  cases: Record<string, NodeChild>,
+  fallback?: NodeChild,
 ): Comment {
   const anchor = document.createComment("match");
   let currentNode: Node | null = null;
   let lastKey: string | undefined;
 
   let initialized = false;
+  const attachedOnce = new WeakSet<Node>();
+  // See `when`: only a node this directive produced may be disposed.
+  let currentNodeOwned = false;
 
   const update = () => {
     // Always evaluate value() to register reactive dependencies
@@ -150,21 +280,25 @@ export function match<T extends string | number>(
     if (initialized && key === lastKey) return;
     lastKey = key;
 
+    // Same as `when`: the caret must be snapshotted while the outgoing case is
+    // still attached. `match` is the pattern recommended for AVOIDING rebuilds,
+    // but a genuine key change still replaces the subtree.
+    const focused = currentNode ? captureFocusWithin([currentNode]) : null;
+
     if (currentNode?.parentNode) {
-      dispose(currentNode);
+      if (currentNodeOwned) dispose(currentNode);
       currentNode.parentNode.removeChild(currentNode);
       currentNode = null;
     }
 
-    const renderFn = cases[key] || fallback;
-    if (renderFn) {
-      const result = renderFn();
-      if (result != null) {
-        const node = result instanceof Node ? result : document.createTextNode(String(result));
-        parent.insertBefore(node, anchor.nextSibling);
-        currentNode = node;
-      }
-    }
+    // `Object.hasOwn` rather than `||` so a case whose value is legitimately
+    // falsy (an empty string, 0) still wins over the fallback.
+    const branch = Object.hasOwn(cases, key) ? cases[key] : fallback;
+    const attached = attachBranch(parent, anchor, branch ?? null, attachedOnce, "match");
+    currentNode = attached.node;
+    currentNodeOwned = attached.owned;
+
+    restoreFocusWithin(focused, currentNode ? [currentNode] : [], "match");
     initialized = true;
   };
 
diff --git a/src/core/rendering/dispose.ts b/src/core/rendering/dispose.ts
index 2ff8780..22ce05c 100644
--- a/src/core/rendering/dispose.ts
+++ b/src/core/rendering/dispose.ts
@@ -1,4 +1,4 @@
-import { devWarn, isDev } from "../dev";
+import { DEV, devWarn } from "../dev";
 import { reportError } from "../errors";
 
 const elementDisposers = new WeakMap<Node, Array<() => void>>();
@@ -41,8 +41,6 @@ export function reportDrainRunaway(label: string, executed: number, remaining: n
 }
 
 // Dev-mode only: track active bindings to detect orphans.
-// In production, _isDev is false and the counter is never touched.
-const _isDev = isDev();
 let activeBindingCount = 0;
 
 /**
@@ -56,7 +54,7 @@ export function registerDisposer(node: Node, teardown: () => void): void {
     elementDisposers.set(node, disposers);
   }
   disposers.push(teardown);
-  if (_isDev) activeBindingCount++;
+  if (DEV) activeBindingCount++;
 }
 
 /**
@@ -75,7 +73,7 @@ export function unregisterDisposer(node: Node, teardown: () => void): void {
   const index = disposers.indexOf(teardown);
   if (index === -1) return;
   disposers.splice(index, 1);
-  if (_isDev) activeBindingCount--;
+  if (DEV) activeBindingCount--;
   if (disposers.length === 0) elementDisposers.delete(node);
 }
 
@@ -128,7 +126,7 @@ export function dispose(node: Node): void {
         // re-run these or land in an infinite cycle.
         const snapshot = pending.slice();
         elementDisposers.delete(current);
-        if (_isDev) activeBindingCount -= snapshot.length;
+        if (DEV) activeBindingCount -= snapshot.length;
 
         for (let i = 0; i < snapshot.length; i++) {
           if (executed >= MAX_DRAIN_TEARDOWNS) {
@@ -140,7 +138,7 @@ export function dispose(node: Node): void {
             const rest = snapshot.slice(i);
             const added = elementDisposers.get(current);
             elementDisposers.set(current, added ? rest.concat(added) : rest);
-            if (_isDev) activeBindingCount += rest.length;
+            if (DEV) activeBindingCount += rest.length;
             reportDrainRunaway("dispose", executed, rest.length + (added?.length ?? 0));
             runaway = true;
             break;
@@ -202,10 +200,12 @@ export function replaceChildrenSafely(parent: ParentNode, ...next: Node[]): void
 /**
  * Check for potential binding leaks. Returns the number of active DOM bindings.
  * In dev mode, logs a warning if the count exceeds the threshold.
- * In production, _isDev is false so the counter is always 0.
+ * In production, DEV is false so the counter is always 0.
+ *
+ * @returns Diagnostic counts of nodes still holding registered disposers.
  */
 export function checkLeaks(warnThreshold = 0): number {
-  if (!_isDev) return 0;
+  if (!DEV) return 0;
   if (warnThreshold > 0 && activeBindingCount > warnThreshold) {
     devWarn(
       `checkLeaks: ${activeBindingCount} active DOM bindings detected. ` +
diff --git a/src/core/rendering/each.ts b/src/core/rendering/each.ts
index d5c0006..7757e32 100644
--- a/src/core/rendering/each.ts
+++ b/src/core/rendering/each.ts
@@ -1,13 +1,11 @@
 import { batch } from "../../reactivity/batch";
 import { track } from "../../reactivity/track";
-import { devAssert, devWarn, isDev } from "../dev";
+import { DEV, devAssert, devWarn } from "../dev";
 import { reportError } from "../errors";
 import { signal } from "../signals/signal";
 import { dispose, registerDisposer } from "./dispose";
 import type { NodeChild } from "./types";
 
-const _isDev = isDev();
-
 /**
  * Resolves a NodeChild to a real Node.
  * - If it's a function, calls recursively.
@@ -215,7 +213,7 @@ export function each<T>(
       // Duplicate keys collapse to a single node reference, so two array
       // positions would share one DOM node — one row silently vanishes and
       // order can drift. Warn loudly in dev (mirrors bindChildNode).
-      if (_isDev && keyIndexMap.has(newKeys[i])) {
+      if (DEV && keyIndexMap.has(newKeys[i])) {
         devWarn(
           `each: duplicate key "${String(newKeys[i])}" at index ${i} (first seen at ${keyIndexMap.get(newKeys[i])}). ` +
             "Keys must be unique — duplicates cause rows to be dropped or mis-ordered.",
diff --git a/src/core/rendering/focusPreservation.ts b/src/core/rendering/focusPreservation.ts
new file mode 100644
index 0000000..e164b0e
--- /dev/null
+++ b/src/core/rendering/focusPreservation.ts
@@ -0,0 +1,238 @@
+import { devWarnLazy } from "../dev";
+
+// ---------------------------------------------------------------------------
+// Keeping the caret alive across a reactive rebuild.
+//
+// A reactive block that re-creates its children destroys the focused node. The
+// browser then moves focus to <body>, and the user's next keystroke goes
+// nowhere — one character typed into an input inside such a block ends the
+// edit. Nothing throws and nothing is logged, so it reads as the application
+// losing what you typed rather than as a framework behaviour.
+//
+// This module does the honest half of the fix: where the rebuilt subtree
+// contains an element whose identity can be RE-ESTABLISHED, focus and the
+// selection range come back; where it cannot, dev says so and names the way
+// out. It deliberately does not guess. Focusing the wrong element is worse than
+// focusing nothing, because the next keystroke then lands in a field the user
+// was not editing.
+//
+// What identity means here, in priority order:
+//   1. `data-focus-key` — an explicit author-supplied identity.
+//   2. `id`
+//   3. `name`
+// All three are stable across a rebuild by construction, because the author
+// writes them into the factory that rebuilds. Structural matching ("the second
+// input in the third div") is deliberately NOT used: it silently re-targets the
+// caret whenever the shape changes, which is exactly when a rebuild happens.
+//
+// A match must also be UNIQUE in the rebuilt subtree. `name` is shared by
+// design — every radio in a group carries the same one — so taking the first
+// hit would put the caret on a sibling control the user was not using. An
+// ambiguous match is treated as no match, and warned about.
+//
+// Focus is restored only when it was LOST (it fell to <body>). If something in
+// the rebuild moved focus deliberately, that wins: an autofocusing branch is
+// not something to fight.
+//
+// NOT preserved, and it cannot be: an in-progress IME composition. The
+// composition is owned by the DOM node, so destroying the node ends it. A
+// keyed subtree that never rebuilds mid-edit is the only real fix, which is
+// what the warning points at.
+// ---------------------------------------------------------------------------
+
+/** Identity attributes consulted, in priority order. */
+const IDENTITY_ATTRS = ["data-focus-key", "id", "name"] as const;
+
+/**
+ * Input types whose selection range is readable/writable. Reading
+ * `selectionStart` on any other type throws in some engines, so the set is an
+ * allowlist rather than a try/catch.
+ */
+const SELECTABLE_TYPES = new Set(["text", "search", "url", "tel", "password", ""]);
+
+export interface FocusSnapshot {
+  /** The element that had focus, kept so we can tell whether it survived. */
+  el: Element;
+  /** `attr=value` identity pair, or null when the element has no stable identity. */
+  attr: string | null;
+  value: string | null;
+  tag: string;
+  start: number | null;
+  end: number | null;
+  direction: string | null;
+}
+
+function selectionOf(el: Element): Pick<FocusSnapshot, "start" | "end" | "direction"> {
+  const tag = el.tagName;
+  const selectable =
+    tag === "TEXTAREA" || (tag === "INPUT" && SELECTABLE_TYPES.has((el as HTMLInputElement).type.toLowerCase()));
+  if (!selectable) return { start: null, end: null, direction: null };
+  const field = el as HTMLInputElement | HTMLTextAreaElement;
+  return { start: field.selectionStart, end: field.selectionEnd, direction: field.selectionDirection };
+}
+
+/**
+ * Snapshot the focused element if it lives inside `nodes`, which are about to
+ * be removed. Returns null — the overwhelmingly common case — when nothing is
+ * focused or focus is elsewhere on the page.
+ *
+ * @param nodes The nodes a rebuild is about to discard.
+ * @returns A snapshot to pass to {@link restoreFocusWithin}, or null when there
+ * is no focus at stake.
+ */
+export function captureFocusWithin(nodes: readonly Node[]): FocusSnapshot | null {
+  if (nodes.length === 0 || typeof document === "undefined") return null;
+  const active = document.activeElement;
+  // `<body>` is the "nothing is focused" resting state. Bailing here keeps this
+  // to one property read on every rebuild in a page where no field is active.
+  if (!active || active === document.body) return null;
+
+  let inside = false;
+  for (let i = 0; i < nodes.length; i++) {
+    const n = nodes[i];
+    if (n === active || (n.nodeType === 1 && (n as Element).contains(active))) {
+      inside = true;
+      break;
+    }
+  }
+  if (!inside) return null;
+
+  let attr: string | null = null;
+  let value: string | null = null;
+  for (let i = 0; i < IDENTITY_ATTRS.length; i++) {
+    const candidate = active.getAttribute(IDENTITY_ATTRS[i]);
+    if (candidate) {
+      attr = IDENTITY_ATTRS[i];
+      value = candidate;
+      break;
+    }
+  }
+
+  return { el: active, attr, value, tag: active.tagName, ...selectionOf(active) };
+}
+
+/** Quote a value for use inside an attribute selector. */
+function quote(value: string): string {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * Find the ONE element matching `selector`, or nothing.
+ *
+ * Ambiguity is treated as failure, not as a reason to pick the first hit.
+ * `name` in particular is shared by design — every radio in a group carries the
+ * same one — so first-match would restore focus onto a sibling control and the
+ * user's next keystroke would act on something they were not using. That is
+ * strictly worse than losing focus, which is at least visible. When the match
+ * is ambiguous the caller warns instead.
+ */
+function findUniqueByIdentity(nodes: readonly Node[], selector: string): { el: Element | null; count: number } {
+  let el: Element | null = null;
+  let count = 0;
+  for (let i = 0; i < nodes.length; i++) {
+    const n = nodes[i];
+    if (n.nodeType !== 1) continue;
+    const root = n as Element;
+    if (root.matches(selector)) {
+      count++;
+      el ??= root;
+    }
+    const inner = root.querySelectorAll(selector);
+    for (let j = 0; j < inner.length; j++) {
+      count++;
+      el ??= inner[j];
+    }
+    // Two is already ambiguous; counting the rest tells us nothing more.
+    if (count > 1) return { el: null, count };
+  }
+  return count === 1 ? { el, count } : { el: null, count };
+}
+
+/** Give `el` focus and put the snapshotted selection range back. */
+function refocus(el: Element, snapshot: FocusSnapshot): void {
+  (el as HTMLElement).focus();
+  if (snapshot.start !== null && typeof (el as HTMLInputElement).setSelectionRange === "function") {
+    const field = el as HTMLInputElement;
+    // The rebuilt value may be shorter than the old one; clamping keeps
+    // setSelectionRange from throwing on an out-of-range index.
+    const max = field.value.length;
+    const start = Math.min(snapshot.start, max);
+    const end = Math.min(snapshot.end ?? start, max);
+    field.setSelectionRange(start, end, (snapshot.direction as "forward" | "backward" | "none") ?? "none");
+  }
+}
+
+/**
+ * Put focus (and the selection range) back after a rebuild, or explain in dev
+ * why it could not be done.
+ *
+ * @param snapshot Result of {@link captureFocusWithin}, or null.
+ * @param nodes The nodes the rebuild produced.
+ * @param where Name of the calling directive, used in the dev warning.
+ * @returns Nothing.
+ */
+export function restoreFocusWithin(snapshot: FocusSnapshot | null, nodes: readonly Node[], where: string): void {
+  if (!snapshot) return;
+  if (typeof document === "undefined") return;
+
+  const active = document.activeElement;
+
+  // Still focused — nothing happened worth undoing. Re-focusing here would only
+  // risk an unwanted scroll.
+  if (active === snapshot.el) return;
+
+  // Focus is on some OTHER real element. Something during the rebuild moved it
+  // deliberately (a branch that autofocuses its first field, say), and stealing
+  // it back would fight the application. Only a focus that fell to the document
+  // is a focus that was LOST.
+  //
+  // Testing where focus actually IS — rather than whether the old node is still
+  // connected — is what catches the case where the node survives the rebuild
+  // but is blurred by being MOVED: re-inserting a focused element blurs it in
+  // real browsers, so `isConnected` reported "nothing to do" while the caret
+  // was already gone.
+  if (active && active !== document.body && active !== document.documentElement) return;
+
+  // The node itself survived (reused or reordered) and merely lost focus. No
+  // identity matching needed — this IS the element the user was editing.
+  if (snapshot.el.isConnected) {
+    refocus(snapshot.el, snapshot);
+    return;
+  }
+
+  let ambiguous = false;
+  if (snapshot.attr && snapshot.value) {
+    const { el: replacement, count } = findUniqueByIdentity(nodes, `[${snapshot.attr}=${quote(snapshot.value)}]`);
+    // Same identity AND same element type. A `data-focus-key` reused across a
+    // <input> and a <button> is an authoring mistake, not an invitation to move
+    // the caret onto a button.
+    if (replacement && replacement.tagName === snapshot.tag) {
+      refocus(replacement, snapshot);
+      return;
+    }
+    // "Several matches" and "no match" need different advice, so the warning
+    // below distinguishes them.
+    ambiguous = count > 1;
+  }
+
+  // Composed inside the callback rather than in an `if (DEV)` block: a
+  // published build leaves `DEV` as a runtime var, so a guarded block's string
+  // literals are not provably dead and ship to production. See `devWarnLazy`.
+  devWarnLazy(() => {
+    const id = snapshot.attr ? ` (${snapshot.attr}="${snapshot.value}")` : "";
+    const why = ambiguous
+      ? `several elements in the rebuilt subtree share ${snapshot.attr}="${snapshot.value}", so there is no way to ` +
+        "tell which one the user was in — a shared name (a radio group) identifies a GROUP, not a control. Add a " +
+        "unique id or data-focus-key to each"
+      : "no element in the rebuilt subtree carries the same identity. Give it a stable id, name, or data-focus-key " +
+        "that the rebuild reproduces";
+    return (
+      `${where}: a reactive rebuild discarded the focused element <${snapshot.tag.toLowerCase()}>${id} and could not ` +
+      "re-establish it, so focus fell back to <body>. An in-progress edit ends here, and an in-progress IME " +
+      "composition is lost outright — a composition belongs to the DOM node, so it cannot survive the node being " +
+      `destroyed. ${why}, or stop the rebuild from happening: key the subtree with match(() => shapeKey(), { … }) ` +
+      "so it is re-created only when the shape actually changes, and drive the rest with reactive attributes and " +
+      "text children, which mutate nodes in place instead of replacing them."
+    );
+  });
+}
diff --git a/src/core/rendering/htm.ts b/src/core/rendering/htm.ts
index 8450d63..e2236c9 100644
--- a/src/core/rendering/htm.ts
+++ b/src/core/rendering/htm.ts
@@ -1,4 +1,4 @@
-import { devWarn, isDev } from "../../core/dev";
+import { DEV, devWarn } from "../../core/dev";
 import { bindAttribute } from "../../reactivity/bindAttribute";
 import { bindChildNode } from "../../reactivity/bindChildNode";
 import { setSafeAttribute } from "../../utils/setSafeAttribute";
@@ -6,8 +6,6 @@ import { registerDisposer } from "./dispose";
 import { SVG_NS } from "./tagFactory";
 import type { NodeChild } from "./types";
 
-const _isDev = isDev();
-
 // Tags whose children are treated as raw text by the HTML parser and thus
 // cannot safely embed dynamic expressions.
 const RAW_TEXT_TAGS = new Set(["script", "style"]);
@@ -428,7 +426,7 @@ function executeElement(tmpl: TmplElement, values: unknown[]): Element {
         const fn = values[attr.idx];
         if (typeof fn === "function") {
           el.addEventListener(attr.name, fn as EventListener);
-        } else if (_isDev) {
+        } else if (DEV) {
           devWarn(
             `html: on:${attr.name} handler is not a function (got ${typeof fn}). Event listener was not attached.`,
           );
@@ -489,6 +487,9 @@ function executeElement(tmpl: TmplElement, values: unknown[]): Element {
  * Templates are parsed once per call site and cached. Subsequent calls at the
  * same source location skip parsing entirely and only replay the cached
  * structure with fresh expression values.
+ *
+ * @returns The live DOM node (or fragment) the template describes — not a
+ * string, and not a virtual node.
  */
 export function html(strings: TemplateStringsArray, ...values: unknown[]): Element {
   let tmpl = cache.get(strings);
diff --git a/src/core/rendering/lazy.ts b/src/core/rendering/lazy.ts
index 2327028..923f925 100644
--- a/src/core/rendering/lazy.ts
+++ b/src/core/rendering/lazy.ts
@@ -40,6 +40,15 @@ function dispatchPropagate(node: Element, error: Error): void {
   });
 }
 
+/**
+ * Read and CLEAR an error stashed on a node by an async boundary.
+ *
+ * Consuming is the point: an error handed to one boundary must not also reach
+ * an outer one, so this is deliberately not a plain getter.
+ *
+ * @param node Element the error was stashed on.
+ * @returns The pending error, or `undefined` when there is none.
+ */
 export function takePendingError(node: Element): Error | undefined {
   const rec = node as unknown as Record<string, unknown>;
   const err = rec[PENDING_ERROR];
@@ -138,6 +147,18 @@ export interface SuspenseProps {
   fallback: () => HTMLElement;
 }
 
+/**
+ * Render `fallback` until the async `nodes` factory resolves, then swap it for
+ * the resolved content.
+ *
+ * @param props `nodes` is the async content factory; `fallback` builds the
+ * placeholder shown while it is pending.
+ * @returns The live container element, already holding the fallback.
+ *
+ * TRAP — the swap REPLACES the container's children, so focus and selection in
+ * the fallback are discarded. That is usually harmless (a spinner rarely holds
+ * focus) but matters for a skeleton form; see the note on `when`.
+ */
 export function Suspense({ nodes, fallback }: SuspenseProps): HTMLElement {
   const container = div({ class: "sibu-suspense" }) as HTMLElement;
 
diff --git a/src/core/rendering/mount.ts b/src/core/rendering/mount.ts
index 08576e2..9ad5198 100644
--- a/src/core/rendering/mount.ts
+++ b/src/core/rendering/mount.ts
@@ -4,6 +4,11 @@ import { dispose } from "./dispose";
 /**
  * Mounts a root component into a DOM element.
  * Supports both function components and pre-created HTMLElements.
+ *
+ * @param component Component function, or an already-built Element/Node.
+ * @param container Element to mount into.
+ * @returns `{ node, unmount }` — the live root node, and a teardown that
+ * disposes the tree and removes it.
  */
 export function mount(
   component: (() => Element) | Element | Node,
diff --git a/src/core/rendering/slots.ts b/src/core/rendering/slots.ts
index ba1aad5..e7477b5 100644
--- a/src/core/rendering/slots.ts
+++ b/src/core/rendering/slots.ts
@@ -1,6 +1,13 @@
 export type SlotFn = () => Element | string | number | null | undefined;
 export type Slots = Record<string, SlotFn>;
 
+/**
+ * Look up a named slot factory.
+ *
+ * @param slots The slot map, which may be undefined.
+ * @param name Slot name; defaults to `"default"`.
+ * @returns The slot factory, or `undefined` when the slot was not provided.
+ */
 export function getSlot(slots: Slots | undefined, name = "default"): SlotFn | undefined {
   return slots?.[name];
 }
diff --git a/src/core/rendering/tagFactory.ts b/src/core/rendering/tagFactory.ts
index 685f26d..9646c3d 100644
--- a/src/core/rendering/tagFactory.ts
+++ b/src/core/rendering/tagFactory.ts
@@ -1,4 +1,4 @@
-import { devWarn, isDev } from "../../core/dev";
+import { DEV, devWarn, devWarnLazy } from "../../core/dev";
 import { bindAttribute } from "../../reactivity/bindAttribute";
 import { bindChildNode } from "../../reactivity/bindChildNode";
 import { reactiveBinding } from "../../reactivity/track";
@@ -9,8 +9,6 @@ import type { NodeChild, NodeChildren } from "./types";
 
 export const SVG_NS = "http://www.w3.org/2000/svg";
 
-const _isDev = isDev();
-
 // Tag names that must never be created via tagFactory — they enable script
 // execution or arbitrary plugin loading regardless of attributes. The check
 // is case-insensitive and applies to HTML, SVG, and MathML namespaces since
@@ -57,29 +55,16 @@ export interface TagProps {
   [attr: string]: unknown;
 }
 
-// Heuristic: does a lone string argument look like a CSS class list rather
-// than human-readable text? Used ONLY to emit a dev warning — never to change
-// behavior. A lone string is always a text child (see tagFactory), but a value
-// like "space-y-6" or "h-6 w-48" is almost certainly a misplaced className, so
-// we surface the footgun loudly. Conservative on purpose: prose words ("Hello
-// world") never trip it; only strings whose every token is class-shaped AND at
-// least one token carries a class-indicator char (hyphen, colon, slash, digit)
-// — the Tailwind-utility shape that bit downstream users.
-function looksLikeClassList(s: string): boolean {
-  const t = s.trim();
-  if (!t) return false;
-  const tokens = t.split(/\s+/);
-  let sawClassish = false;
-  for (let i = 0; i < tokens.length; i++) {
-    const tok = tokens[i];
-    // Every token must be a plausible CSS class token.
-    if (!/^-?[A-Za-z_][A-Za-z0-9_:/.-]*$/.test(tok)) return false;
-    // A hyphen / colon / slash / digit marks a utility-class token
-    // (h-6, md:flex, w-1/2). Plain words ("Hello") do not qualify.
-    if (/[-:/0-9]/.test(tok)) sawClassish = true;
-  }
-  return sawClassish;
-}
+// Lone strings already warned about, so a list rendering the same mistaken
+// class string for every row reports it ONCE instead of once per element.
+// Keyed by tag + string. Dev-only: the only writer is inside a `devWarnLazy`
+// callback, so in production this is an unreferenced empty Set.
+const warnedLoneStrings = new Set<string>();
+const MAX_WARNED_LONE_STRINGS = 100;
+// Whether the "reporting has stopped" notice has already been printed. See the
+// cap handling at the call site for why reaching the cap must SUPPRESS rather
+// than merely stop remembering.
+let loneStringCapAnnounced = false;
 
 // Cache for camelCase → kebab-case conversions
 const kebabCache = new Map<string, string>();
@@ -112,14 +97,14 @@ function applyStyle(el: Element, style: TagProps["style"]) {
   // authoring intent with two different policies.
   if (typeof style === "function") {
     const teardown = reactiveBinding(() => {
-      el.setAttribute("style", sanitizeStyleAttribute(String((style as () => string)())));
+      el.setAttribute("style", sanitizeStyleAttribute(String((style as () => string)()), { element: el }));
     }, el);
     registerDisposer(el, teardown);
     return;
   }
 
   if (typeof style === "string") {
-    el.setAttribute("style", sanitizeStyleAttribute(style));
+    el.setAttribute("style", sanitizeStyleAttribute(style, { element: el }));
     return;
   }
 
@@ -130,15 +115,42 @@ function applyStyle(el: Element, style: TagProps["style"]) {
     if (typeof val === "function") {
       const getter = val as () => string | number;
       const teardown = reactiveBinding(() => {
-        htmlEl.style.setProperty(name, sanitizeCSSValue(String(getter())));
+        htmlEl.style.setProperty(name, sanitizeCSSValue(String(getter()), { property: name, element: el }));
       }, el);
       registerDisposer(el, teardown);
     } else {
-      htmlEl.style.setProperty(name, sanitizeCSSValue(String(val)));
+      htmlEl.style.setProperty(name, sanitizeCSSValue(String(val), { property: name, element: el }));
     }
   }
 }
 
+/**
+ * Resolve any of the three `class` shapes a tag factory accepts — a string, a
+ * getter, or a `{ name: boolean | getter }` map — down to one class string.
+ *
+ * Call it INSIDE a reactive context to get a reactive result: it reads the
+ * getters it is given, so the enclosing effect subscribes to whatever they
+ * touch. Exported so components that build their own elements (`RouterLink`)
+ * honour exactly the shapes the tag factories do, instead of each re-deciding
+ * which forms it supports — that drift is what made a reactive `class` render
+ * as nothing on a `RouterLink` while working on every `div`.
+ *
+ * @param cls The `class` prop in any accepted shape.
+ * @returns The resolved class string; `""` when the prop is absent.
+ */
+export function resolveClassValue(cls: TagProps["class"]): string {
+  if (typeof cls === "string") return cls;
+  if (typeof cls === "function") return (cls as () => string)();
+  if (!cls) return "";
+  let out = "";
+  for (const name in cls) {
+    const val = (cls as Record<string, boolean | (() => boolean)>)[name];
+    const active = typeof val === "function" ? val() : val;
+    if (active) out = out ? `${out} ${name}` : name;
+  }
+  return out;
+}
+
 function applyClass(el: Element, cls: TagProps["class"]) {
   if (typeof cls === "string") {
     el.setAttribute("class", cls);
@@ -288,14 +300,77 @@ export const tagFactory = (tag: string, ns?: string) => {
         return el;
       }
       // Lone string → text child (unchanged). Warn in dev if it looks like a
-      // misplaced class list so a styled empty wrapper doesn't silently render
+      // misplaced class list, so a styled empty wrapper doesn't silently render
       // its class names as visible text.
-      if (_isDev && looksLikeClassList(first)) {
-        devWarn(
+      //
+      // The heuristic, its de-duplication and its message all live INSIDE the
+      // callback: a production build drops the closure whole, so none of this
+      // reaches a consumer (see `devWarnLazy`). It costs one closure per
+      // lone-string element creation in development, and nothing otherwise.
+      devWarnLazy(() => {
+        const tokens = first.trim().split(/\s+/);
+        // TWO OR MORE tokens required, at least two of them utility-shaped.
+        //
+        // The earlier rule — any single token carrying a hyphen, colon, slash
+        // or digit — measured 3.3% false positives on a corpus of prose, which
+        // badly understated it: that corpus had no identifiers. Real
+        // applications pass `item-0`, `home-content`, `user-42`, `v4.1.0`,
+        // `src/index.ts`, `https://example.com` and `N/A` as ordinary text, and
+        // every one of them tripped it. On a corpus including those the true
+        // rate was 29.8%, and a list rendering `item-0`…`item-999` produced a
+        // thousand warnings.
+        //
+        // Requiring two utility-shaped tokens takes measured false positives to
+        // 0% (131 strings), because every one of those identifiers is a single
+        // token, and hyphenated English ("state-of-the-art design", "read-only
+        // field") carries only one. The cost is single-token class lists:
+        // `div("space-y-6")` and `div("truncate")` no longer warn. That is a
+        // deliberate trade — a warning developers learn to ignore protects
+        // nobody, and the multi-token form is both the reported bug and the
+        // dominant real-world shape.
+        if (tokens.length < 2) return "";
+        let utilityTokens = 0;
+        for (let i = 0; i < tokens.length; i++) {
+          const tok = tokens[i];
+          // Every token must be a plausible CSS class token.
+          if (!/^-?[A-Za-z_][A-Za-z0-9_:/.-]*$/.test(tok)) return "";
+          // A hyphen / colon / slash / digit marks a utility-class token
+          // (h-6, md:flex, w-1/2). Plain words ("flex", "border") do not.
+          if (/[-:/0-9]/.test(tok)) utilityTokens++;
+        }
+        if (utilityTokens < 2) return "";
+
+        // One mistake reported once, however many elements repeat it.
+        const key = `${tag}|${first}`;
+        if (warnedLoneStrings.has(key)) return "";
+
+        // Past the cap, STOP REPORTING — do not merely stop remembering.
+        //
+        // The cache previously kept returning the message while refusing to
+        // insert new keys, which made `has(key)` permanently false for every
+        // mistake after the hundredth. Those warned on every single render,
+        // forever: the exact per-element flood this cache exists to prevent,
+        // just postponed until a page was busy enough to hit the cap.
+        //
+        // Going quiet risks hiding a real mistake, so the silence announces
+        // itself once. A developer who sees it knows to fix what has already
+        // been reported and look again.
+        if (warnedLoneStrings.size >= MAX_WARNED_LONE_STRINGS) {
+          if (loneStringCapAnnounced) return "";
+          loneStringCapAnnounced = true;
+          return (
+            `tagFactory: ${MAX_WARNED_LONE_STRINGS} distinct lone-string class warnings have been reported; ` +
+            "suppressing further ones for the rest of this session so they cannot flood the console. " +
+            "Fix the reported ones and reload to see any that remain."
+          );
+        }
+        warnedLoneStrings.add(key);
+
+        return (
           `tagFactory: lone string "${first}" looks like a class list but is being rendered as TEXT. ` +
-            `For a class, use ${tag}({ class: "${first}" }) — or ${tag}("${first}", children) to set the class AND add children.`,
+          `For a class, use ${tag}({ class: "${first}" }) — or ${tag}("${first}", children) to set the class AND add children.`
         );
-      }
+      });
       el.textContent = first;
       return el;
     }
@@ -329,7 +404,7 @@ export const tagFactory = (tag: string, ns?: string) => {
       // DOM clobbering: an element with id="foo" becomes window.foo. If the
       // id value is user-controlled, it can shadow globals like `config`,
       // `location`, etc. Warn in dev so authors notice.
-      if (_isDev && typeof pId === "string" && CLOBBER_RISKY_IDS.has(pId.toLowerCase())) {
+      if (DEV && typeof pId === "string" && CLOBBER_RISKY_IDS.has(pId.toLowerCase())) {
         devWarn(
           `tagFactory: element id="${pId}" matches a common global and may cause DOM clobbering. Avoid setting ids from untrusted input.`,
         );
@@ -351,7 +426,7 @@ export const tagFactory = (tag: string, ns?: string) => {
         const handler = pOn[ev];
         if (typeof handler === "function") {
           el.addEventListener(ev, handler as EventListener);
-        } else if (_isDev) {
+        } else if (DEV) {
           devWarn(
             `tagFactory: on.${ev} handler is not a function (got ${typeof handler}). Event listener was not attached.`,
           );
diff --git a/src/core/signals/array.ts b/src/core/signals/array.ts
index ba7449f..51aa909 100644
--- a/src/core/signals/array.ts
+++ b/src/core/signals/array.ts
@@ -52,6 +52,14 @@ export interface ArrayActions<T> {
   clear(): void;
 }
 
+/**
+ * A signal holding an array, plus mutation helpers that write a NEW array each
+ * time so the signal actually notifies.
+ *
+ * @param initial Starting items; copied, so the caller's array is not aliased.
+ * @returns A `[accessor, actions]` pair — `actions` carries `push`, `remove`,
+ * `insert`, `move`, `clear` and friends.
+ */
 export function array<T>(initial: T[] = []): [Accessor<T[]>, ArrayActions<T>] {
   const [arr, setArr] = signal<T[]>([...initial]);
 
diff --git a/src/core/signals/asyncDerived.ts b/src/core/signals/asyncDerived.ts
index 3029e75..831a048 100644
--- a/src/core/signals/asyncDerived.ts
+++ b/src/core/signals/asyncDerived.ts
@@ -87,6 +87,9 @@ export interface AsyncDerivedContext {
  *   return r.json();
  * }, []);
  * ```
+ *
+ * @returns An accessor exposing the async result along with its loading and
+ * error state.
  */
 export function asyncDerived<T>(
   factory: (context: AsyncDerivedContext) => Promise<T>,
diff --git a/src/core/signals/derived.ts b/src/core/signals/derived.ts
index d6d35de..7aeac16 100644
--- a/src/core/signals/derived.ts
+++ b/src/core/signals/derived.ts
@@ -31,6 +31,9 @@ import type { Accessor } from "./signal";
  * That keeps the cheap boolean dirty flag AND makes `equals` actually stop
  * propagation, with recomputation still fully lazy: `_validate` only ever runs
  * when an effect is genuinely about to observe the value.
+ *
+ * @returns An accessor for the computed value. It recomputes lazily on read
+ * after any dependency changes.
  */
 export function derived<T>(
   getter: () => T,
diff --git a/src/core/signals/effect.ts b/src/core/signals/effect.ts
index de8a782..5e1a826 100644
--- a/src/core/signals/effect.ts
+++ b/src/core/signals/effect.ts
@@ -190,6 +190,9 @@ function disposeEffect(ctx: EffectCtx): void {
  *   onCleanup(() => window.removeEventListener("resize", handler));
  * });
  * ```
+ *
+ * @returns A dispose function that stops the effect and releases its
+ * dependencies. Idempotent.
  */
 export function effect(effectFn: EffectBody | (() => void), options?: EffectOptions): () => void {
   devAssert(typeof effectFn === "function", "effect: argument must be a function.");
diff --git a/src/core/signals/ref.ts b/src/core/signals/ref.ts
index 5a8bdcb..6ab9828 100644
--- a/src/core/signals/ref.ts
+++ b/src/core/signals/ref.ts
@@ -22,6 +22,13 @@ export interface Ref<T> {
 
 export function ref<T>(initial: T): Ref<T>;
 export function ref<T = undefined>(): Ref<T | undefined>;
+/**
+ * A reactive box: reading `.current` inside a reactive context subscribes to
+ * it, and assigning to it notifies.
+ *
+ * @param initial Optional initial value.
+ * @returns An object whose `current` property is a reactive getter/setter.
+ */
 export function ref<T>(initial?: T): Ref<T | undefined> {
   const [get, set] = signal<T | undefined>(initial);
   return {
diff --git a/src/core/signals/signal.ts b/src/core/signals/signal.ts
index cb77367..0fd6c61 100644
--- a/src/core/signals/signal.ts
+++ b/src/core/signals/signal.ts
@@ -1,7 +1,7 @@
 import { enqueueBatchedSignal } from "../../reactivity/batch";
 import type { ReactiveSignal } from "../../reactivity/signal";
 import { notifySubscribers, recordDependency } from "../../reactivity/track";
-import { isDev } from "../dev";
+import { DEV } from "../dev";
 
 // Phantom brand symbol — exists only in the type system, never at runtime.
 declare const __accessor: unique symbol;
@@ -35,15 +35,14 @@ export interface SignalOptions<T = unknown> {
 // and allows tests to set the hook after module load.
 const _g = globalThis as any;
 
-// Cache dev mode at module load — avoids checking on every signal write
-const _isDev = isDev();
-
 /**
  * signal creates a reactive signal that holds a value of type T.
  * Returns a tuple: [getter, setter].
  *
  * @param initial Initial value
  * @param options Optional config: `{ name: "count" }` for devtools labeling
+ * @returns A `[getter, setter]` tuple. Calling the getter inside a reactive
+ * context subscribes to the signal; the setter accepts a value or an updater.
  */
 export function signal<T>(initial: T, options?: SignalOptions<T>): StateTuple<T> {
   // Pre-initialize every internal field the reactivity core touches. This
@@ -84,7 +83,7 @@ export function signal<T>(initial: T, options?: SignalOptions<T>): StateTuple<T>
     _d: false,
     _validate: undefined,
   };
-  const debugName = _isDev ? options?.name : undefined;
+  const debugName = DEV ? options?.name : undefined;
   const equalsFn = options?.equals;
 
   // Debug name is pre-declared on the state shape so the hidden class stays
@@ -107,7 +106,7 @@ export function signal<T>(initial: T, options?: SignalOptions<T>): StateTuple<T>
   // giving them their own closure with no branch on `equalsFn` lets the JIT
   // inline it. Signals with custom equals pay the extra call, same as before.
   //
-  // Dev-mode devtools hook emission lives behind the cached `_isDev` so
+  // Dev-mode devtools hook emission lives behind the cached `DEV` so
   // production closures don't carry the branch either.
   // ---------------------------------------------------------------------------
   let set: SetState<T>;
@@ -119,7 +118,7 @@ export function signal<T>(initial: T, options?: SignalOptions<T>): StateTuple<T>
       if (equalsFn(prev, newValue)) return;
       state.value = newValue;
       state.__v++;
-      if (_isDev) {
+      if (DEV) {
         const hook = _g.__SIBU_DEVTOOLS_GLOBAL_HOOK__;
         if (hook) hook.emit("signal:update", { signal: state, name: debugName, oldValue: prev, newValue });
       }
@@ -127,7 +126,7 @@ export function signal<T>(initial: T, options?: SignalOptions<T>): StateTuple<T>
         notifySubscribers(state as ReactiveSignal);
       }
     };
-  } else if (_isDev) {
+  } else if (DEV) {
     set = (next) => {
       const prev = state.value;
       const newValue = typeof next === "function" ? (next as (p: T) => T)(prev) : next;
@@ -155,7 +154,7 @@ export function signal<T>(initial: T, options?: SignalOptions<T>): StateTuple<T>
     };
   }
 
-  if (_isDev) {
+  if (DEV) {
     const hook = _g.__SIBU_DEVTOOLS_GLOBAL_HOOK__;
     if (hook) hook.emit("signal:create", { signal: state, name: debugName, getter: get, initial });
   }
diff --git a/src/core/signals/writable.ts b/src/core/signals/writable.ts
index 743a43a..5607458 100644
--- a/src/core/signals/writable.ts
+++ b/src/core/signals/writable.ts
@@ -34,6 +34,8 @@ import type { Accessor } from "./signal";
  * lastName();              // "Smith"
  * fullName();              // "Jane Smith"
  * ```
+ *
+ * @returns A store handle with `subscribe`, `set` and `update`.
  */
 export function writable<T>(
   get: () => T,
diff --git a/src/devtools/debug.ts b/src/devtools/debug.ts
index 07645ce..860bab2 100644
--- a/src/devtools/debug.ts
+++ b/src/devtools/debug.ts
@@ -159,6 +159,13 @@ export function runCleanups(component: string): void {
   }
 }
 
+/**
+ * Report components that still hold registered cleanups, i.e. that were never
+ * disposed. A development aid — it observes only what `debug.ts` tracked.
+ *
+ * @returns A map of component name to the number of outstanding cleanups.
+ * Empty when nothing is leaking.
+ */
 export function checkLeaks(): Record<string, number> {
   const leaks: Record<string, number> = {};
   for (const [component, cleanups] of trackedCleanups) {
diff --git a/src/patterns/persist.ts b/src/patterns/persist.ts
index 4619b1a..80f26ca 100644
--- a/src/patterns/persist.ts
+++ b/src/patterns/persist.ts
@@ -68,6 +68,14 @@ export interface PersistOptions<T = unknown> {
   decrypt?: (value: string) => string;
 }
 
+/**
+ * A signal mirrored into persistent storage, rehydrated on creation.
+ *
+ * @param key Storage key.
+ * @param initial Value used when storage holds nothing (or holds junk).
+ * @param options Storage backend, serializer and version/migration settings.
+ * @returns A `[accessor, setter]` pair with the same shape as `signal`.
+ */
 export function persisted<T>(
   key: string,
   initial: T,
diff --git a/src/performance/domRecycler.ts b/src/performance/domRecycler.ts
index 892f82c..cec0409 100644
--- a/src/performance/domRecycler.ts
+++ b/src/performance/domRecycler.ts
@@ -2,12 +2,10 @@
 // DOM RECYCLING & RESOURCE PRELOADING
 // ============================================================================
 
-import { devWarn, isDev } from "../core/dev";
+import { DEV, devWarn } from "../core/dev";
 import { replaceChildrenSafely } from "../core/rendering/dispose";
 import { sanitizeUrl } from "../utils/sanitize";
 
-const _isDev = isDev();
-
 /**
  * DOMPool manages a pool of reusable DOM elements to reduce GC pressure.
  */
@@ -41,7 +39,7 @@ export class DOMPool {
    * is almost certainly a bug.
    */
   release(element: HTMLElement): void {
-    if (_isDev && element.isConnected) {
+    if (DEV && element.isConnected) {
       devWarn(
         "DOMPool.release() called on a still-connected element. Detach it from the DOM first (remove() / dispose()).",
       );
diff --git a/src/platform/ssr.ts b/src/platform/ssr.ts
index 651f8c9..7265354 100644
--- a/src/platform/ssr.ts
+++ b/src/platform/ssr.ts
@@ -27,7 +27,7 @@
 //  - `hydrateIslands` / `hydrateProgressively` use `hasOwnProperty.call`
 //    to block prototype-pollution lookups on the islands map.
 
-import { isDev } from "../core/dev";
+import { DEV } from "../core/dev";
 import { dispose, replaceChildrenSafely } from "../core/rendering/dispose";
 import { getSSRStore } from "../core/ssr-context";
 import { serializeHeadEntry } from "../utils/headEntry";
@@ -91,8 +91,6 @@ function sanitizeSsrAttributeValue(lowerName: string, value: string): string {
   return sanitizeAttributeString(lowerName, value);
 }
 
-const _isDev = isDev();
-
 /** Strict attribute-name validation. HTML5 allows more, but this subset is sufficient for real elements and keeps attackers from smuggling `"`, `>`, `=`, or whitespace. */
 const SAFE_ATTR_NAME = /^[A-Za-z_:][-A-Za-z0-9_.:]*$/;
 
@@ -102,7 +100,7 @@ function isSafeAttrName(name: string): boolean {
 
 /** Format an SSR error as an HTML comment. In production, omits the message to prevent information leakage. */
 function ssrErrorComment(err: unknown): string {
-  if (_isDev) {
+  if (DEV) {
     const msg = escapeHtml(err instanceof Error ? err.message : String(err));
     return `<!--SSR error: ${safeCommentText(msg)}-->`;
   }
@@ -178,12 +176,12 @@ export function renderToString(element: HTMLElement | DocumentFragment | Node):
   // escaping and would execute if injected data is present. Scripts and
   // styles must be added via `renderToDocument`'s dedicated options.
   if (tag === "script" || tag === "style") {
-    return _isDev ? `<!--ssr:${tag}-stripped-->` : "";
+    return DEV ? `<!--ssr:${tag}-stripped-->` : "";
   }
 
   // Defense-in-depth: reject tags with unexpected characters.
   if (!/^[a-z][a-z0-9-]*$/i.test(tag)) {
-    return _isDev ? "<!--ssr:invalid-tag-->" : "";
+    return DEV ? "<!--ssr:invalid-tag-->" : "";
   }
 
   let html = `<${tag}`;
@@ -287,7 +285,7 @@ export function hydrate(component: () => HTMLElement, container: HTMLElement, op
       const first = mismatches[0];
       if (options.onMismatch) {
         options.onMismatch(first);
-      } else if (_isDev) {
+      } else if (DEV) {
         console.warn(
           `[SibuJS hydration] ${first.message}\n  at ${first.path}\n  server: ${first.serverValue}\n  client: ${first.clientValue}`,
         );
@@ -643,12 +641,12 @@ export async function* renderToStream(element: HTMLElement | DocumentFragment |
   const tag = element.tagName.toLowerCase();
 
   if (tag === "script" || tag === "style") {
-    if (_isDev) yield `<!--ssr:${tag}-stripped-->`;
+    if (DEV) yield `<!--ssr:${tag}-stripped-->`;
     return;
   }
 
   if (!/^[a-z][a-z0-9-]*$/i.test(tag)) {
-    if (_isDev) yield "<!--ssr:invalid-tag-->";
+    if (DEV) yield "<!--ssr:invalid-tag-->";
     return;
   }
 
@@ -926,7 +924,7 @@ export function ssrSuspense(props: {
       if (timer) clearTimeout(timer);
       // Emit the fallback HTML on timeout/error so the stream still
       // produces a deterministic swap payload instead of hanging.
-      if (_isDev) console.warn("[SibuJS SSR] ssrSuspense rejected:", err);
+      if (DEV) console.warn("[SibuJS SSR] ssrSuspense rejected:", err);
       return { id, html: fallbackHtml };
     },
   );
@@ -1065,7 +1063,7 @@ export function serializeState(
  */
 export function deserializeState<T = Record<string, unknown>>(validate?: (data: unknown) => data is T): T | undefined {
   if (typeof window === "undefined") return undefined;
-  if (_isDev && !validate) {
+  if (DEV && !validate) {
     console.warn(
       "[SibuJS SSR] deserializeState() called without a validate guard — tampered SSR payloads will not be detected.",
     );
diff --git a/src/plugins/router.ts b/src/plugins/router.ts
index 7ec4a6a..86ac9f9 100644
--- a/src/plugins/router.ts
+++ b/src/plugins/router.ts
@@ -1,5 +1,6 @@
 import { devWarn, isDev } from "../core/dev";
 import { dispose, registerDisposer } from "../core/rendering/dispose";
+import { resolveClassValue, type TagProps } from "../core/rendering/tagFactory";
 import { effect } from "../core/signals/effect";
 import { signal } from "../core/signals/signal";
 import { track } from "../reactivity/track";
@@ -1827,6 +1828,15 @@ function normalizeRoutes(routes: RouteDef[]): RouteDef[] {
   });
 }
 
+/**
+ * Create the global router and make it the one `route()`, `navigate()` and
+ * `RouterLink` talk to. Any previously created router is destroyed first.
+ *
+ * @param routesOrOptions Either the route table, or the options object when
+ * routes are supplied later via {@link setRoutes}.
+ * @param options Router options when the first argument is the route table.
+ * @returns The created router instance.
+ */
 export function createRouter(routesOrOptions: RouteDef[] | RouterOptions, options: RouterOptions = {}): SibuRouter {
   if (_routerRef.current) {
     _routerRef.current.destroy();
@@ -1858,11 +1868,24 @@ export function setRoutes(routes: RouteDef[]): void {
 // COMPATIBILITY API (uses global router instance)
 // ============================================================================
 
+/**
+ * Read the current route as a plain snapshot.
+ *
+ * @returns The active {@link RouteContext} (path, params, query, hash).
+ * @throws If no router has been created yet.
+ */
 export function route(): RouteContext {
   if (!_routerRef.current) throw new Error("Router not initialized. Call createRouter() first.");
   return _routerRef.current.currentRoute;
 }
 
+/**
+ * Handle onto the global router's navigation surface.
+ *
+ * @returns An object exposing the current route plus `push`, `replace`, `go`,
+ * `back`, `forward` and the three guard registrars.
+ * @throws If no router has been created yet.
+ */
 export function router() {
   if (!_routerRef.current) throw new Error("Router not initialized. Call createRouter() first.");
 
@@ -1881,6 +1904,16 @@ export function router() {
   };
 }
 
+/**
+ * Navigate to a target, running every registered guard.
+ *
+ * @param to Path string or location descriptor.
+ * @param options `replace` swaps the current history entry instead of pushing;
+ * `state` is stored on the history entry.
+ * @returns A promise for the {@link NavigationResult} — resolved even when a
+ * guard cancels, so the outcome must be inspected rather than assumed.
+ * @throws If no router has been created yet.
+ */
 export function navigate(
   to: NavigationTarget,
   options?: { replace?: boolean; state?: unknown },
@@ -1889,41 +1922,82 @@ export function navigate(
   return _routerRef.current.navigate(to, options);
 }
 
+/**
+ * Navigate by pushing a new history entry.
+ *
+ * @param to Path string or location descriptor.
+ * @returns A promise for the {@link NavigationResult}.
+ */
 export function push(to: NavigationTarget): Promise<NavigationResult> {
   if (!_routerRef.current) throw new Error("Router not initialized. Call createRouter() first.");
   return _routerRef.current.push(to);
 }
 
+/**
+ * Navigate by replacing the current history entry.
+ *
+ * @param to Path string or location descriptor.
+ * @returns A promise for the {@link NavigationResult}.
+ */
 export function replace(to: NavigationTarget): Promise<NavigationResult> {
   if (!_routerRef.current) throw new Error("Router not initialized. Call createRouter() first.");
   return _routerRef.current.replace(to);
 }
 
+/**
+ * Move through history by a relative offset, as `history.go` does.
+ *
+ * @param delta Number of entries to move; negative goes back.
+ * @returns Nothing — history moves asynchronously, so nothing is awaited here.
+ */
 export function go(delta: number): void {
   if (!_routerRef.current) throw new Error("Router not initialized. Call createRouter() first.");
   _routerRef.current.go(delta);
 }
 
+/** Go back one history entry. Equivalent to `go(-1)`. */
 export function back(): void {
   if (!_routerRef.current) throw new Error("Router not initialized. Call createRouter() first.");
   _routerRef.current.back();
 }
 
+/** Go forward one history entry. Equivalent to `go(1)`. */
 export function forward(): void {
   if (!_routerRef.current) throw new Error("Router not initialized. Call createRouter() first.");
   _routerRef.current.forward();
 }
 
+/**
+ * Register a guard that runs before every navigation is confirmed.
+ *
+ * @param guard Called with the target and current routes; return `false` to
+ * cancel, or a target to redirect.
+ * @returns An unregister function.
+ */
 export function beforeEach(guard: NavigationGuard): () => void {
   if (!_routerRef.current) throw new Error("Router not initialized. Call createRouter() first.");
   return _routerRef.current.beforeEach(guard);
 }
 
+/**
+ * Register a guard that runs after `beforeEach` and after async components have
+ * resolved, but before the route commits.
+ *
+ * @param guard Called with the target and current routes.
+ * @returns An unregister function.
+ */
 export function beforeResolve(guard: NavigationGuard): () => void {
   if (!_routerRef.current) throw new Error("Router not initialized. Call createRouter() first.");
   return _routerRef.current.beforeResolve(guard);
 }
 
+/**
+ * Register a hook that runs after every confirmed navigation. It cannot cancel
+ * or redirect — by the time it runs the route has already committed.
+ *
+ * @param hook Called with the new and previous routes.
+ * @returns An unregister function.
+ */
 export function afterEach(hook: (to: RouteContext, from: RouteContext) => void): () => void {
   if (!_routerRef.current) throw new Error("Router not initialized. Call createRouter() first.");
   return _routerRef.current.afterEach(hook);
@@ -1936,6 +2010,18 @@ export function afterEach(hook: (to: RouteContext, from: RouteContext) => void):
 // Registry of Route cleanup functions for destroyRouter
 const routeCleanups: (() => void)[] = [];
 
+/**
+ * The route outlet: renders whichever component matches the current route, and
+ * swaps it on every navigation.
+ *
+ * @returns A Comment anchor that manages the matched component. Like every
+ * factory here it hands back a live node the caller can insert directly.
+ *
+ * TRAP — a navigation REBUILDS the outlet's subtree, so focus and selection
+ * inside the outgoing route are discarded. The runtime restores focus when the
+ * incoming route contains an element with the same `id`, `name` or
+ * `data-focus-key`, and warns in dev when it cannot.
+ */
 export function Route(): Node {
   const anchor = document.createComment("route-outlet");
   let currentNode: Node | null = null;
@@ -2510,7 +2596,12 @@ export function RouterLink(
   // Children pass positionally (the framework-wide convention); `nodes` is kept
   // only as a deprecated fallback for existing callers.
   const content = children !== undefined ? children : nodes;
-  const baseClass = typeof classAttr === "string" ? classAttr : "";
+  // A `class` prop is resolved with the SAME rules the tag factories use, so a
+  // getter or a conditional map works here exactly as it does on a `div`.
+  // Reading it with `typeof classAttr === "string"` meant a reactive class fell
+  // through to `""` — the attribute was never written and nothing said so.
+  // Resolution happens inside the active-class effect below, which is what
+  // makes a getter reactive rather than merely accepted.
 
   const routeGetter = _routerRef.current.routeGetter;
   const rawHref = _routerRef.current["resolvePath"](to);
@@ -2574,7 +2665,7 @@ export function RouterLink(
       if (exactActiveClass) classes.push(exactActiveClass);
       else if (options.linkExactActiveClass) classes.push(options.linkExactActiveClass);
     }
-    link.className = [baseClass, ...classes].filter(Boolean).join(" ");
+    link.className = [resolveClassValue(classAttr as TagProps["class"]), ...classes].filter(Boolean).join(" ");
   });
   registerDisposer(link, effectCleanup);
 
@@ -2597,7 +2688,7 @@ export function RouterLink(
         // Inline style is a CSS-injection sink (url() exfiltration, legacy
         // expression()/behavior). Uses the shared declaration-list sanitizer so
         // one dangerous declaration no longer discards the safe ones with it.
-        link.setAttribute(key, sanitizeStyleAttribute(str));
+        link.setAttribute(key, sanitizeStyleAttribute(str, { element: link }));
       } else {
         link.setAttribute(key, str);
       }
@@ -2867,6 +2958,13 @@ export function __getNavigationEpoch(): number {
   return _routerRef.current?.navigationEpoch ?? -1;
 }
 
+/**
+ * Whether a named route is registered.
+ *
+ * @param name The route's `name`.
+ * @returns `true` when a route with that name exists; `false` when it does not,
+ * and also when no router has been created yet.
+ */
 export function hasRoute(name: string): boolean {
   if (!_routerRef.current) return false;
   return _routerRef.current["matcher"].findByName(name) !== null;
diff --git a/src/reactivity/bindChildNode.ts b/src/reactivity/bindChildNode.ts
index 11dbca0..d9a9ce6 100644
--- a/src/reactivity/bindChildNode.ts
+++ b/src/reactivity/bindChildNode.ts
@@ -1,11 +1,10 @@
-import { devWarn, isDev } from "../core/dev";
+import { DEV, devWarn } from "../core/dev";
 import { reportError } from "../core/errors";
 import { dispose } from "../core/rendering/dispose";
+import { captureFocusWithin, restoreFocusWithin } from "../core/rendering/focusPreservation";
 import type { NodeChild } from "../core/rendering/types";
 import { reactiveBinding } from "./track";
 
-const _isDev = isDev();
-
 /**
  * Binds a reactive getter that returns NodeChild or NodeChild[] next to a placeholder comment.
  * A throwing getter is contained — the last successful children stay on screen —
@@ -32,6 +31,12 @@ export function bindChildNode(placeholder: Comment, getter: () => NodeChild | No
       return;
     }
 
+    // Snapshot focus BEFORE anything is detached — once a node is removed,
+    // `document.activeElement` has already fallen back to <body> and there is
+    // nothing left to identify. Returns null unless a field inside the subtree
+    // we are about to discard actually held focus.
+    const focused = captureFocusWithin(lastNodes);
+
     if (result == null || typeof result === "boolean") {
       // Remove and DISPOSE all previously inserted nodes. Once detached they
       // are no longer reachable by an ancestor dispose-walk, so without
@@ -43,6 +48,9 @@ export function bindChildNode(placeholder: Comment, getter: () => NodeChild | No
         if (node.parentNode) node.parentNode.removeChild(node);
       }
       lastNodes.length = 0;
+      // Nothing was rendered in their place, so there is no counterpart to
+      // restore to — this reports the loss rather than repairing it.
+      restoreFocusWithin(focused, lastNodes, "bindChildNode");
       return;
     }
 
@@ -64,8 +72,7 @@ export function bindChildNode(placeholder: Comment, getter: () => NodeChild | No
         if (item == null || typeof item === "boolean") continue;
         const node = item instanceof Node ? item : document.createTextNode(String(item));
         if (seen.has(node)) {
-          if (_isDev)
-            devWarn("bindChildNode: duplicate node reference in array — only the first occurrence is rendered.");
+          if (DEV) devWarn("bindChildNode: duplicate node reference in array — only the first occurrence is rendered.");
           continue;
         }
         seen.add(node);
@@ -111,6 +118,10 @@ export function bindChildNode(placeholder: Comment, getter: () => NodeChild | No
     }
 
     lastNodes = newNodes;
+
+    // Placement is finished, so the rebuilt counterpart (if any) exists and can
+    // be focused. A no-op unless the focused node was actually discarded.
+    restoreFocusWithin(focused, newNodes, "bindChildNode");
   }
 
   // Initial render and reactive subscription. `reactiveBinding` re-tracks
diff --git a/src/reactivity/track-core.ts b/src/reactivity/track-core.ts
index 33e7ebf..892a15a 100644
--- a/src/reactivity/track-core.ts
+++ b/src/reactivity/track-core.ts
@@ -354,6 +354,16 @@ function depsChanged(sub: SubWithList): boolean {
 let suspendDepth = 0;
 let trackingSuspended = false;
 
+/**
+ * Stop recording dependency edges until the matching {@link resumeTracking}.
+ * Nestable — the depth is counted, so an inner pair does not resume early.
+ *
+ * Prefer {@link untracked}, which pairs the two calls for you even when the
+ * body throws. Reach for the raw pair only when the suspended region cannot be
+ * expressed as a single function.
+ *
+ * @returns Nothing.
+ */
 export function suspendTracking(): void {
   if (suspendDepth === 0) {
     // Capture the ACTUAL current subscriber (not null). Resume restores
@@ -366,6 +376,12 @@ export function suspendTracking(): void {
   suspendDepth++;
 }
 
+/**
+ * Undo one {@link suspendTracking}. Dependency recording resumes only when the
+ * outermost pair closes.
+ *
+ * @returns Nothing.
+ */
 export function resumeTracking(): void {
   suspendDepth--;
   if (suspendDepth === 0) {
@@ -380,6 +396,15 @@ export function isTrackingSuspended(): boolean {
   return trackingSuspended;
 }
 
+/**
+ * Run `fn` without recording anything it reads as a dependency.
+ *
+ * The suspension is released even if `fn` throws, which is the reason to prefer
+ * this over a manual suspend/resume pair.
+ *
+ * @param fn Function to run outside dependency tracking.
+ * @returns Whatever `fn` returns.
+ */
 export function untracked<T>(fn: () => T): T {
   suspendTracking();
   try {
@@ -717,12 +742,26 @@ let drainEpoch = 0;
 // see `drainQueue`. Cleared when the outermost drain completes.
 const quarantined = new Set<Subscriber>();
 
+/**
+ * Cap how many times one subscriber may re-run within a single drain before it
+ * is quarantined as a runaway cycle. A safety valve, not a tuning knob.
+ *
+ * @param n New limit; ignored unless finite and positive.
+ * @returns The previous limit, so a caller can restore it.
+ */
 export function setMaxSubscriberRepeats(n: number): number {
   const prev = maxSubscriberRepeats;
   if (Number.isFinite(n) && n > 0) maxSubscriberRepeats = Math.floor(n);
   return prev;
 }
 
+/**
+ * Cap how many passes one notification drain may make before giving up on a
+ * self-refeeding update cycle.
+ *
+ * @param n New limit; ignored unless finite and positive.
+ * @returns The previous limit, so a caller can restore it.
+ */
 export function setMaxDrainIterations(n: number): number {
   const prev = maxDrainIterations;
   if (Number.isFinite(n) && n > 0) maxDrainIterations = Math.floor(n);
@@ -806,6 +845,15 @@ function drainQueue(): void {
   }
 }
 
+/**
+ * Flush queued signal notifications, running every dirty subscriber.
+ *
+ * Re-entrant calls are ignored: a write performed from inside a subscriber adds
+ * to the queue the current drain is already working through, rather than
+ * starting a nested one.
+ *
+ * @returns Nothing.
+ */
 export function drainNotificationQueue(): void {
   if (notifyDepth > 0) return;
   notifyDepth++;
@@ -893,6 +941,12 @@ export function queueSignalNotification(signal: ReactiveSignal): void {
   }
 }
 
+/**
+ * Mark every subscriber of `signal` dirty and queue them for the next drain.
+ *
+ * @param signal The signal that changed.
+ * @returns Nothing.
+ */
 export function notifySubscribers(signal: ReactiveSignal) {
   const sig = signal as SignalWithList;
   const head = sig.subsHead;
diff --git a/src/reactivity/track.ts b/src/reactivity/track.ts
index af49749..bf8c948 100644
--- a/src/reactivity/track.ts
+++ b/src/reactivity/track.ts
@@ -1,4 +1,4 @@
-import { devWarn, isDev } from "../core/dev";
+import { DEV, devWarn } from "../core/dev";
 import * as core from "./track-core";
 
 // ---------------------------------------------------------------------------
@@ -32,8 +32,6 @@ import * as core from "./track-core";
 // in lockstep with batch.ts's sibling registry key.
 // ---------------------------------------------------------------------------
 
-const _isDev = isDev();
-
 // Build version stamped onto the registry. Mirrors the `__SIBU_DEV__` define
 // pattern: the bundler may inline `__SIBU_VERSION__`; under the test runner /
 // raw ESM it is undefined, so we fall back to "dev". Only used to enrich the
@@ -77,14 +75,17 @@ function resolveReactiveApi(): ReactiveApi {
     // of the reactive runtime was loaded on this page. We delegate to the first
     // copy (reactivity keeps working), but the duplication is wasteful and a
     // sign of a bundler misconfig.
-    if (_isDev && !existing.__dupWarned) {
+    if (DEV && !existing.__dupWarned) {
       existing.__dupWarned = true;
       devWarn(
         "Multiple instances of the reactive runtime detected on this page " +
-          `(active: ${existing.version}, duplicate: ${_runtimeVersion}). Reactivity ` +
-          "still works — all copies share the first one — but de-duplicate sibujs in " +
-          "your bundler (e.g. Vite optimizeDeps.exclude: ['sibujs'] or " +
-          "resolve.dedupe: ['sibujs']).",
+          `(active: ${existing.version}, duplicate: ${_runtimeVersion}). Reactivity is NOT ` +
+          "broken and no bundler configuration is required: every copy routes through the " +
+          "first one via a global registry, so signal writes still reach subscribers " +
+          "registered by any copy. This is only a SIZE issue — the duplicate copy's bytes " +
+          "are downloaded and parsed for nothing. If you want them back, de-duplicate " +
+          "sibujs in your bundler (Vite: resolve.dedupe: ['sibujs']). Mismatched VERSIONS " +
+          "above are worth fixing regardless, since only the first one loaded is used.",
       );
     }
     return existing;
diff --git a/src/ui/a11y.ts b/src/ui/a11y.ts
index 2247e20..e8f5257 100644
--- a/src/ui/a11y.ts
+++ b/src/ui/a11y.ts
@@ -308,6 +308,13 @@ function drainAnnounceQueue(priority: "polite" | "assertive"): void {
   });
 }
 
+/**
+ * Announce a message to screen readers through a shared live region.
+ *
+ * @param message Text to announce.
+ * @param priority `"polite"` waits for a pause; `"assertive"` interrupts.
+ * @returns Nothing. A no-op without a DOM, so it is safe under SSR.
+ */
 export function announce(message: string, priority: "polite" | "assertive" = "polite"): void {
   if (typeof document === "undefined") return;
   announceQueues[priority].push(message);
diff --git a/src/ui/dialog.ts b/src/ui/dialog.ts
index df29da4..c35cd38 100644
--- a/src/ui/dialog.ts
+++ b/src/ui/dialog.ts
@@ -61,6 +61,12 @@ function removeGlobalListenerIfIdle(): void {
   _dlg.listenerAttached = false;
 }
 
+/**
+ * Dialog open/close state with focus trapping and scroll locking wired in.
+ *
+ * @returns A handle exposing `open`, `close`, `toggle` and the reactive
+ * `isOpen` accessor.
+ */
 export function dialog(): {
   open: () => void;
   close: () => void;
diff --git a/src/ui/form.ts b/src/ui/form.ts
index cca6987..b5f2639 100644
--- a/src/ui/form.ts
+++ b/src/ui/form.ts
@@ -45,6 +45,12 @@ export interface FormReturn<T extends object> {
 // BUILT-IN VALIDATORS
 // ============================================================================
 
+/**
+ * Require a non-empty value. Rejects `null`, `undefined`, `""` and `[]`.
+ *
+ * @param message Overrides the default message.
+ * @returns A validator returning the message on failure, `null` on success.
+ */
 export function required(message = "This field is required"): ValidatorFn<unknown> {
   return (value: unknown) => {
     if (value == null || value === "" || (Array.isArray(value) && value.length === 0)) {
@@ -54,6 +60,14 @@ export function required(message = "This field is required"): ValidatorFn<unknow
   };
 }
 
+/**
+ * Require a minimum string length. An empty value passes — pair with
+ * {@link required} when the field is mandatory.
+ *
+ * @param min Minimum number of characters.
+ * @param message Overrides the default message.
+ * @returns A validator returning the message on failure, `null` on success.
+ */
 export function minLength(min: number, message?: string): ValidatorFn<string> {
   return (value: string) => {
     if (value && value.length < min) {
@@ -63,6 +77,13 @@ export function minLength(min: number, message?: string): ValidatorFn<string> {
   };
 }
 
+/**
+ * Require a maximum string length. An empty value passes.
+ *
+ * @param max Maximum number of characters.
+ * @param message Overrides the default message.
+ * @returns A validator returning the message on failure, `null` on success.
+ */
 export function maxLength(max: number, message?: string): ValidatorFn<string> {
   return (value: string) => {
     if (value && value.length > max) {
@@ -72,6 +93,13 @@ export function maxLength(max: number, message?: string): ValidatorFn<string> {
   };
 }
 
+/**
+ * Require the value to match a regular expression. An empty value passes.
+ *
+ * @param regex Pattern the value must satisfy.
+ * @param message Message used on failure.
+ * @returns A validator returning the message on failure, `null` on success.
+ */
 export function matchesPattern(regex: RegExp, message = "Invalid format"): ValidatorFn<string> {
   return (value: string) => {
     if (value && !regex.test(value)) {
@@ -81,10 +109,24 @@ export function matchesPattern(regex: RegExp, message = "Invalid format"): Valid
   };
 }
 
+/**
+ * Require a syntactically plausible email address. Deliberately permissive —
+ * the only authoritative check is sending mail to it. An empty value passes.
+ *
+ * @param message Message used on failure.
+ * @returns A validator returning the message on failure, `null` on success.
+ */
 export function email(message = "Invalid email address"): ValidatorFn<string> {
   return matchesPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, message);
 }
 
+/**
+ * Require a numeric value to be at least `minVal`. `null`/`undefined` passes.
+ *
+ * @param minVal Inclusive lower bound.
+ * @param message Overrides the default message.
+ * @returns A validator returning the message on failure, `null` on success.
+ */
 export function min(minVal: number, message?: string): ValidatorFn<number> {
   return (value: number) => {
     if (value != null && value < minVal) {
@@ -94,6 +136,13 @@ export function min(minVal: number, message?: string): ValidatorFn<number> {
   };
 }
 
+/**
+ * Require a numeric value to be at most `maxVal`. `null`/`undefined` passes.
+ *
+ * @param maxVal Inclusive upper bound.
+ * @param message Overrides the default message.
+ * @returns A validator returning the message on failure, `null` on success.
+ */
 export function max(maxVal: number, message?: string): ValidatorFn<number> {
   return (value: number) => {
     if (value != null && value > maxVal) {
@@ -103,6 +152,13 @@ export function max(maxVal: number, message?: string): ValidatorFn<number> {
   };
 }
 
+/**
+ * Build a validator from an arbitrary predicate.
+ *
+ * @param fn Returns `true` when the value is acceptable.
+ * @param message Message used when `fn` returns `false`.
+ * @returns A validator returning the message on failure, `null` on success.
+ */
 export function custom<T>(fn: (value: T) => boolean, message: string): ValidatorFn<T> {
   return (value: T) => (fn(value) ? null : message);
 }
diff --git a/src/ui/scrollLock.ts b/src/ui/scrollLock.ts
index ed6da80..f0f8ad5 100644
--- a/src/ui/scrollLock.ts
+++ b/src/ui/scrollLock.ts
@@ -45,6 +45,12 @@ const _lock = globalSingleton(Symbol.for("sibujs.scrollLock.v1"), () => ({
   savedPaddingRight: null as string | null,
 }));
 
+/**
+ * Acquire a reference-counted lock on document scrolling, so nested overlays
+ * can each lock and unlock without one release re-enabling scroll for all.
+ *
+ * @returns A handle with `lock`, `unlock` and `isLocked`.
+ */
 export function scrollLock(): ScrollLockHandle {
   let owned = false;
 
diff --git a/src/ui/toast.ts b/src/ui/toast.ts
index b527ca5..a6bc93f 100644
--- a/src/ui/toast.ts
+++ b/src/ui/toast.ts
@@ -25,6 +25,14 @@ export interface ToastInstance {
   dismissAll: () => void;
 }
 
+/**
+ * Create a toast queue.
+ *
+ * @param options `duration` in ms before auto-dismiss; `maxToasts` caps how
+ * many are shown at once.
+ * @returns A {@link ToastInstance} with `info`, `success`, `warning`, `error`,
+ * plus the reactive list to render.
+ */
 export function toast(options?: { duration?: number; maxToasts?: number }): ToastInstance {
   const duration = options?.duration ?? 3000;
   const maxToasts = options?.maxToasts ?? Infinity;
diff --git a/src/utils/sanitize.ts b/src/utils/sanitize.ts
index 9a2d55c..192ae31 100644
--- a/src/utils/sanitize.ts
+++ b/src/utils/sanitize.ts
@@ -1,3 +1,5 @@
+import { devWarnLazy } from "../core/dev";
+
 /**
  * Strip C0/C1 control characters and ASCII whitespace that browsers silently
  * ignore while parsing a URL/protocol (e.g. "java\tscript:" or a leading
@@ -249,14 +251,178 @@ function decodeCssEscapes(value: string): string {
   return out;
 }
 
+/**
+ * Where a dropped declaration came from, so the dev warning can point at it.
+ *
+ * Every field is optional: the sanitizers are public and are called from
+ * contexts that know nothing about an element. More context means a more useful
+ * warning, never a different security decision.
+ */
+export interface StyleSanitizerContext {
+  /** The CSS property the value belongs to, e.g. `background-image`. */
+  property?: string;
+  /** The element the style was being applied to, for locating it on the page. */
+  element?: Element;
+}
+
+// The blocked constructs, in the order `sanitizeCSSValue` tests them.
+//
+// Needles and explanations live in SEPARATE arrays, indexed in lockstep, and
+// that separation is a size decision rather than a style one. The needles are
+// load-bearing in production; the explanations are dev-only prose. Pairing them
+// in one table made the prose reachable from the production code path — the
+// table is indexed by the live matcher — so ~600 bytes of English shipped to
+// every consumer to explain warnings production can never print. Split, the
+// reasons are referenced only from inside a `devWarnLazy` callback, which the
+// bundler drops whole, taking the array with it.
+//
+// KEEP THE NEEDLES ALIGNED WITH the `reasons` array in `warnDroppedDeclaration`.
+// `blockedCssReason` returns an index into both.
+const BLOCKED_CSS_NEEDLES = [
+  "url(",
+  "expression(",
+  "javascript:",
+  "vbscript:",
+  "-moz-binding",
+  "behavior:",
+  "@import",
+  "image-set(",
+  "filter:progid",
+] as const;
+
+/**
+ * Describe an element well enough to find it in a page full of similar ones.
+ * Dev-only: every caller is inside a {@link DEV} guard, so this and the strings
+ * it builds are eliminated from production builds.
+ */
+function describeElement(el: Element | undefined): string {
+  if (!el) return "an element";
+  let out = el.tagName.toLowerCase();
+  const id = el.getAttribute("id");
+  if (id) out += `#${id}`;
+  const cls = el.getAttribute("class");
+  if (cls) out += `.${cls.trim().split(/\s+/).slice(0, 3).join(".")}`;
+  return `<${out}>`;
+}
+
+/**
+ * Announce a dropped declaration, naming what went, from where, why, and what
+ * to do instead. Dev-only.
+ *
+ * The "what to do instead" half is not politeness — a silent drop taught
+ * consumers that the library was broken, because the honest alternative was
+ * never stated anywhere they would look. It is stated here, in the warning.
+ */
+// Declarations already announced, so a reactive style that recomputes on every
+// frame reports its blocked value ONCE instead of flooding the console with the
+// same ~700-character message.
+//
+// Keyed on ELEMENT + declaration, not declaration alone. The flooding case is
+// one element recomputing the same blocked value, which this still collapses;
+// but the same bad declaration on a different element is a different site in
+// the source, and the whole point of the warning is to say which element. A
+// declaration-only key would report the first `background-image` on the page
+// and silently swallow every other one.
+//
+// Dev-only: every write is inside a `DEV` guard, so the Set and its contents
+// are eliminated in production.
+const warnedDeclarations = new Set<string>();
+// A page with pathological churn (a blocked value derived from a signal that
+// takes thousands of distinct values) must not turn this cache into a leak.
+// Past the cap reporting STOPS, after one notice saying so. An earlier version
+// of this comment claimed warnings should keep printing past the cap because
+// "noisy beats silent" — but combined with no longer inserting keys, that made
+// every declaration after the hundredth warn on every recomputation, which is
+// the unbounded flood the cache exists to prevent rather than a considered
+// trade-off.
+const MAX_WARNED_DECLARATIONS = 100;
+let declarationCapAnnounced = false;
+
+function warnDroppedDeclaration(value: string, reason: number, ctx?: StyleSanitizerContext): void {
+  // EVERYTHING — the dedupe bookkeeping included — happens inside the callback.
+  // Hoisting even the key construction out to an `if (DEV)` block would put
+  // these string literals back on the production code path; see `devWarnLazy`.
+  devWarnLazy(() => {
+    // Declared HERE, inside the callback, and that placement is load-bearing.
+    //
+    // Tree-shaking decides what to keep from the module graph BEFORE the
+    // `__SIBU_DEV__` define folds this callback away, so any TOP-LEVEL binding
+    // the callback names — a `const REASONS = [...]`, or a function wrapping
+    // it — is already marked live by the time its last reference disappears,
+    // and ships. Only what is textually inside the callback dies with it.
+    // Re-allocating per warning is irrelevant: development only, and only when
+    // a declaration was actually dropped.
+    const reasons = [
+      "url() in an inline style is an exfiltration channel: the browser fetches it immediately and the URL's path or query can carry page data off-origin",
+      "expression() executes arbitrary script in legacy engines",
+      "the javascript: scheme executes script",
+      "the vbscript: scheme executes script",
+      "-moz-binding loads and runs remote XBL",
+      "behavior: loads and runs a remote HTC script",
+      "@import pulls in a remote stylesheet",
+      "image-set() fetches remote images, the same exfiltration channel as url()",
+      "filter:progid activates legacy scriptable filters",
+    ];
+    const declaration = ctx?.property ? `${ctx.property}: ${value}` : value;
+    const where = describeElement(ctx?.element);
+    const key = `${where}|${declaration}`;
+    if (warnedDeclarations.has(key)) return "";
+    // See `MAX_WARNED_DECLARATIONS`: reaching the cap must suppress, not just
+    // stop remembering, or a reactive style recomputing per frame reports its
+    // blocked value on every frame once the cache is full.
+    if (warnedDeclarations.size >= MAX_WARNED_DECLARATIONS) {
+      if (declarationCapAnnounced) return "";
+      declarationCapAnnounced = true;
+      return (
+        `${MAX_WARNED_DECLARATIONS} distinct dropped style declarations have been reported; suppressing further ` +
+        "ones for the rest of this session so they cannot flood the console. The declarations are still dropped — " +
+        "only the reporting stops. Fix the reported ones and reload to see any that remain."
+      );
+    }
+    warnedDeclarations.add(key);
+    return (
+      `style declaration "${declaration}" was dropped by the style sanitizer on ${where} — ` +
+      `${reasons[reason]}. The element renders without it, which usually looks like a missing image ` +
+      "rather than an error. Sanctioned alternatives: for a content image use an <img> element (or a <picture>); " +
+      "for decoration, put the rule in a stylesheet and set a class instead — stylesheet CSS is not sanitized, only " +
+      "inline style attributes are. If this declaration is not yours, it came from untrusted data and the drop just " +
+      "prevented an exfiltration."
+    );
+  });
+}
+
 /**
  * Sanitizes a CSS value to prevent data exfiltration via url(), expression(),
  * or other injection vectors. Strips url() and expression() calls entirely.
  *
+ * A dropped value is announced via `console.warn` in development, naming the
+ * property, the element and the reason — the drop used to be completely silent,
+ * which is how a blocked `background-image` reads as a rendering bug rather
+ * than a security decision. The warning and its strings are eliminated from
+ * production builds.
+ *
  * @param value CSS property value to sanitize
+ * @param context Optional property/element used only to enrich the dev warning.
+ * Passing it never changes the security decision.
  * @returns The sanitized value, or empty string if dangerous
  */
-export function sanitizeCSSValue(value: string): string {
+/**
+ * The security decision, with no reporting attached: which blocked construct
+ * does `value` contain, if any?
+ *
+ * Separated from `sanitizeCSSValue` so a caller that tests the same declaration
+ * twice — `sanitizeStyleAttribute` checks the value alone AND joined to its
+ * property name, because `behavior:` and `filter:progid` only match once the
+ * name is present — can decide ONCE whether to announce it. With the warning
+ * built into the check, one dropped declaration produced two identical console
+ * messages.
+ *
+ * @param value CSS value (or `property:value` pair) to judge.
+ * @returns Index into {@link BLOCKED_CSS_NEEDLES} of the construct that blocks
+ * it, or `-1` when the value is safe. An index rather than the reason text, so
+ * production never touches the prose.
+ */
+function blockedCssReason(value: string): number {
   // Fast path: every blocked construct is gated by one of `(` (url/expression/
   // image-set), `:` (javascript:/vbscript:/behavior:/filter:progid), or `@`
   // (@import) — and a CSS escape that could synthesize them requires `\`. A
@@ -264,7 +430,7 @@ export function sanitizeCSSValue(value: string): string {
   // skip the decode + lower-case + whitespace-strip allocations and the nine
   // substring scans. This is the overwhelmingly common case for style values
   // ("red", "14px", "#fff", "1px solid black", "flex").
-  if (!CSS_DANGER_GATE.test(value)) return value;
+  if (!CSS_DANGER_GATE.test(value)) return -1;
 
   // Normalize to what the CSS parser sees BEFORE looking for blocked tokens —
   // every escape production, not just the hex one. See `decodeCssEscapes`.
@@ -273,20 +439,21 @@ export function sanitizeCSSValue(value: string): string {
   // functional notation like `calc(…)`, `rgba(…)`, `var(…)`, gradients.
   const normalized = value.includes("\\") ? decodeCssEscapes(value) : value;
   const lower = normalized.toLowerCase().replace(/\s+/g, "");
-  if (
-    lower.includes("url(") ||
-    lower.includes("expression(") ||
-    lower.includes("javascript:") ||
-    lower.includes("vbscript:") ||
-    lower.includes("-moz-binding") ||
-    lower.includes("behavior:") ||
-    lower.includes("@import") ||
-    lower.includes("image-set(") ||
-    lower.includes("filter:progid")
-  ) {
-    return "";
+  // Scanning the table costs one pass over the same needles the inlined `||`
+  // chain tested, and it yields WHICH construct matched so the dev warning can
+  // name it. Only values that already passed CSS_DANGER_GATE get here, so this
+  // is off the hot path either way.
+  for (let i = 0; i < BLOCKED_CSS_NEEDLES.length; i++) {
+    if (lower.includes(BLOCKED_CSS_NEEDLES[i])) return i;
   }
-  return value;
+  return -1;
+}
+
+export function sanitizeCSSValue(value: string, context?: StyleSanitizerContext): string {
+  const reason = blockedCssReason(value);
+  if (reason === -1) return value;
+  warnDroppedDeclaration(value, reason, context);
+  return "";
 }
 
 /**
@@ -315,13 +482,25 @@ export function sanitizeCSSValue(value: string): string {
  * Without a DOM (SSR in a bare runtime) there is no parser available, so the
  * conservative all-or-nothing check applies: a list containing anything
  * dangerous is dropped entirely rather than partially trusted.
+ *
+ * Every dropped declaration is announced via `console.warn` in development —
+ * exactly one warning per declaration, naming the property, the value, the
+ * element and the reason. Production builds eliminate the warning entirely.
+ *
+ * @param cssText The whole `style` attribute value, a `;`-separated list.
+ * @param context Optional element used only to enrich the dev warning. It never
+ * changes which declarations survive.
+ * @returns The surviving declarations, re-joined. Safe declarations are kept
+ * even when a sibling declaration in the same list is dropped.
  */
-export function sanitizeStyleAttribute(cssText: string): string {
+export function sanitizeStyleAttribute(cssText: string, context?: StyleSanitizerContext): string {
   const input = String(cssText);
   if (input.trim() === "") return "";
 
   if (typeof document === "undefined") {
-    return sanitizeCSSValue(input) === "" ? "" : input;
+    // No parser: the list is judged as one value, so the warning necessarily
+    // names the whole list rather than a single declaration.
+    return sanitizeCSSValue(input, context) === "" ? "" : input;
   }
 
   const probe = document.createElement("div");
@@ -339,8 +518,16 @@ export function sanitizeStyleAttribute(cssText: string): string {
     // Check the value on its own AND joined to its property name: the danger
     // list contains property-qualified forms (`behavior:`, `filter:progid`)
     // that only match once the name is present.
-    if (sanitizeCSSValue(value) === "") continue;
-    if (sanitizeCSSValue(`${property}:${value}`) === "") continue;
+    //
+    // Both checks go through `blockedCssReason`, which does not report. One
+    // dropped declaration is one problem, so it is announced exactly once here
+    // regardless of which of the two checks caught it.
+    let reason = blockedCssReason(value);
+    if (reason === -1) reason = blockedCssReason(`${property}:${value}`);
+    if (reason !== -1) {
+      warnDroppedDeclaration(value, reason, { property, element: context?.element });
+      continue;
+    }
     const priority = probe.style.getPropertyPriority(property);
     declarations.push(`${property}: ${value}${priority ? ` !${priority}` : ""}`);
   }
@@ -536,7 +723,7 @@ export function isPolicyAttribute(name: string): boolean {
  * the reactive write paths (`bindAttribute` / `bindDynamic`) so the two can
  * never drift on which attribute gets which treatment.
  */
-export function sanitizeAttributeString(attr: string, value: string): string {
+export function sanitizeAttributeString(attr: string, value: string, context?: StyleSanitizerContext): string {
   const lower = attr.toLowerCase();
   if (lower === "srcset") return sanitizeSrcset(value);
   if (URL_ATTRIBUTES.has(lower)) return sanitizeUrl(value);
@@ -544,7 +731,7 @@ export function sanitizeAttributeString(attr: string, value: string): string {
   // VALUE trusted. Every generic writer (reactive bindings, html`` expressions,
   // prop spreads) funnels through here, so the declaration-list policy applies
   // to all of them rather than only to the tag factory.
-  if (lower === "style") return sanitizeStyleAttribute(value);
+  if (lower === "style") return sanitizeStyleAttribute(value, context);
   return value;
 }
 
diff --git a/src/utils/setSafeAttribute.ts b/src/utils/setSafeAttribute.ts
index 66fa1ba..ea13868 100644
--- a/src/utils/setSafeAttribute.ts
+++ b/src/utils/setSafeAttribute.ts
@@ -25,11 +25,9 @@
  * guarantees every writer runs the existing one.
  */
 
-import { devWarn, isDev } from "../core/dev";
+import { DEV, devWarn } from "../core/dev";
 import { isEventHandlerAttr, isHtmlContentAttribute, sanitizeAttributeString } from "./sanitize";
 
-const _isDev = isDev();
-
 const HTML_NS = "http://www.w3.org/1999/xhtml";
 const SVG_NS = "http://www.w3.org/2000/svg";
 const XLINK_NS = "http://www.w3.org/1999/xlink";
@@ -129,7 +127,7 @@ export function setSafeAttribute(
   const localName = ns ? name.slice(name.indexOf(":") + 1) : name;
 
   if (isEventHandlerAttr(name)) {
-    if (_isDev) {
+    if (DEV) {
       devWarn(
         `${options.label ?? "setSafeAttribute"}: refusing to set event-handler attribute "${name}". ` +
           `Its value would be evaluated as JavaScript. Use on:{ ${name.slice(2)}: fn } instead.`,
@@ -154,7 +152,7 @@ export function setSafeAttribute(
   }
 
   if (isHtmlContentAttribute(name)) {
-    if (_isDev) {
+    if (DEV) {
       devWarn(
         `${options.label ?? "setSafeAttribute"}: refusing to set "${name}". The browser parses this ` +
           "attribute as a nested HTML document, so a generic string value cannot be made safe — " +
@@ -199,7 +197,7 @@ export function setSafeAttribute(
   // `sanitizeAttributeString` keys off the attribute NAME, and the URL set it
   // consults already contains `xlink:href` — so the prefixed name is passed in
   // whole even though the write itself uses the local name plus a namespace.
-  const safe = sanitizeAttributeString(name, str);
+  const safe = sanitizeAttributeString(name, str, { element: el });
 
   // No-op check on the SANITIZED result, never on the caller's raw input.
   //
diff --git a/src/widgets/Select.ts b/src/widgets/Select.ts
index 3eed482..848916e 100644
--- a/src/widgets/Select.ts
+++ b/src/widgets/Select.ts
@@ -15,6 +15,14 @@ export interface SelectOptions<T> {
   isDisabled?: (item: T) => boolean;
 }
 
+/**
+ * Selection state for a list — single or multiple, with keyboard-friendly
+ * helpers. Headless: it owns state, not markup.
+ *
+ * @param options Item list, selection mode, and comparison strategy.
+ * @returns A handle exposing `selectedItem`/`selectedItems` accessors and the
+ * `select`, `deselect`, `toggle` and `clear` operations.
+ */
 export function select<T>(options: SelectOptions<T>): {
   selectedItems: () => T[];
   selectedItem: () => T | null;
diff --git a/tests/api-uniformity.test.ts b/tests/api-uniformity.test.ts
new file mode 100644
index 0000000..9dc5191
--- /dev/null
+++ b/tests/api-uniformity.test.ts
@@ -0,0 +1,161 @@
+/**
+ * Signature uniformity across the rendering API.
+ *
+ * Two inconsistencies cost real debugging time because the wrong shape was
+ * accepted without complaint, or accepted and then ignored:
+ *
+ *  - Tag factories honour a reactive (function) `class`; `RouterLink` read it
+ *    with `typeof classAttr === "string"`, so a function fell through to `""`
+ *    and the attribute was simply never written. No error, no class.
+ *  - `show(cond, element)` takes an element while `when(cond, () => el)` takes
+ *    thunks. Passing the wrong shape produced an obscure `TypeError` from deep
+ *    inside the directive rather than a message naming the mistake.
+ *
+ * Both are widened here — every form accepted everywhere — with a dev warning
+ * only where a shape is genuinely ambiguous rather than merely unusual.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { show, when } from "../src/core/rendering/directives";
+import { div, span } from "../src/core/rendering/html";
+import { signal } from "../src/core/signals/signal";
+import { createRouter, destroyRouter, RouterLink, setRoutes } from "../src/plugins/router";
+
+const settle = async () => {
+  for (let i = 0; i < 20; i++) await Promise.resolve();
+  await new Promise((r) => setTimeout(r, 0));
+};
+
+const stub = (label: string) => () => {
+  const d = document.createElement("div");
+  d.textContent = label;
+  return d;
+};
+
+describe("RouterLink honours a reactive class", () => {
+  beforeEach(() => {
+    window.history.replaceState({}, "", "/");
+    createRouter({ mode: "history", base: "" });
+    setRoutes([
+      { path: "/", component: stub("home") },
+      { path: "/docs", component: stub("docs") },
+    ]);
+  });
+
+  afterEach(() => {
+    destroyRouter();
+  });
+
+  it("writes the class produced by a function", async () => {
+    await settle();
+    const link = RouterLink({ to: "/docs", class: () => "btn primary" }, "Docs");
+    expect(link.className).toContain("btn");
+    expect(link.className).toContain("primary");
+  });
+
+  it("updates the class when the signal it reads changes", async () => {
+    await settle();
+    const [theme, setTheme] = signal("light");
+    const link = RouterLink({ to: "/docs", class: () => `btn ${theme()}` }, "Docs");
+    expect(link.className).toContain("light");
+
+    setTheme("dark");
+    await settle();
+    expect(link.className).toContain("dark");
+    expect(link.className).not.toContain("light");
+  });
+
+  it("keeps the reactive class alongside the router's active classes", async () => {
+    await settle();
+    const link = RouterLink({ to: "/", class: () => "btn", activeClass: "on" }, "Home");
+    await settle();
+    expect(link.className).toContain("btn");
+    expect(link.className).toContain("on");
+  });
+
+  it("still accepts a plain string class", async () => {
+    await settle();
+    const link = RouterLink({ to: "/docs", class: "btn" }, "Docs");
+    expect(link.className).toContain("btn");
+  });
+});
+
+describe("show() and when() accept both an element and a thunk", () => {
+  let warn: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    warn.mockRestore();
+  });
+
+  it("show() accepts a thunk and toggles the element it returns", () => {
+    const [visible, setVisible] = signal(true);
+    const el = show(
+      () => visible(),
+      () => span("hi"),
+    ) as HTMLElement;
+    expect(el.tagName).toBe("SPAN");
+    expect(el.style.display).toBe("");
+
+    setVisible(false);
+    expect(el.style.display).toBe("none");
+  });
+
+  it("show() still accepts a bare element", () => {
+    const [visible, setVisible] = signal(true);
+    const el = show(() => visible(), span("hi"));
+    expect(el.tagName).toBe("SPAN");
+    setVisible(false);
+    expect((el as HTMLElement).style.display).toBe("none");
+  });
+
+  it("when() accepts bare elements for its branches", async () => {
+    const [flag, setFlag] = signal(true);
+    const host = div([when(() => flag(), span("yes"), span("no"))]);
+    document.body.appendChild(host);
+    await Promise.resolve();
+
+    expect(host.textContent).toContain("yes");
+    setFlag(false);
+    await Promise.resolve();
+    expect(host.textContent).toContain("no");
+    host.remove();
+  });
+
+  it("when() still accepts thunks", async () => {
+    const [flag, setFlag] = signal(true);
+    const host = div([
+      when(
+        () => flag(),
+        () => span("yes"),
+        () => span("no"),
+      ),
+    ]);
+    document.body.appendChild(host);
+    await Promise.resolve();
+    expect(host.textContent).toContain("yes");
+    setFlag(false);
+    await Promise.resolve();
+    expect(host.textContent).toContain("no");
+    host.remove();
+  });
+
+  it("warns in dev when when() is given an element that a rebuild will reuse", async () => {
+    // A bare element branch cannot be re-created, so toggling away and back
+    // re-attaches the SAME node — with whatever state it accumulated. That is
+    // usually fine and sometimes surprising, so it is a warning, not an error.
+    const [flag, setFlag] = signal(true);
+    const host = div([when(() => flag(), span("yes"), span("no"))]);
+    document.body.appendChild(host);
+    await Promise.resolve();
+    setFlag(false);
+    await Promise.resolve();
+    setFlag(true);
+    await Promise.resolve();
+
+    const msg = warn.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(msg).toContain("branch was given as an element");
+    host.remove();
+  });
+});
diff --git a/tests/consumption.test.ts b/tests/consumption.test.ts
index 04ca674..5aa2523 100644
--- a/tests/consumption.test.ts
+++ b/tests/consumption.test.ts
@@ -130,8 +130,10 @@ describe("Package consumption", () => {
     it("each export has types, import, and require fields", () => {
       const pkg = JSON.parse(readFileSync(resolve(__dirname, "../package.json"), "utf-8"));
       for (const [key, value] of Object.entries(pkg.exports)) {
-        // ./cdn ships an IIFE bundle for direct <script> tags — no ESM/CJS/dts.
-        if (key === "./cdn") continue;
+        // The ./cdn* entries ship IIFE bundles for direct <script> tags — no
+        // ESM/CJS/dts. Matched by prefix so the production and development
+        // bundles are both covered without listing each one.
+        if (key.startsWith("./cdn")) continue;
         const entry = value as Record<string, string>;
         expect(entry.types).toBeDefined();
         expect(entry.import).toBeDefined();
diff --git a/tests/dist-artifacts.test.ts b/tests/dist-artifacts.test.ts
new file mode 100644
index 0000000..cb76914
--- /dev/null
+++ b/tests/dist-artifacts.test.ts
@@ -0,0 +1,98 @@
+// @vitest-environment node
+//
+// Nothing here needs a DOM: it reads built files and inspects strings.
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+// ---------------------------------------------------------------------------
+// Assertions against the REAL published artifacts, not against source.
+//
+// `treeshaking-dev-diagnostics.test.ts` proves that dev diagnostics CAN be
+// compiled out: it bundles source with `__SIBU_DEV__: false` and checks the
+// strings are gone. That is the right test for the ESM/CJS entry points, which
+// are handed to a consumer's bundler to make that decision.
+//
+// It proves nothing about the CDN bundle, because nobody rebundles a
+// `<script src="…/cdn.global.js">` — the published bytes ARE what runs. And it
+// was in exactly that gap that the diagnostics shipped: the CDN build applied
+// no `__SIBU_DEV__` define at all, so every warning string in the library rode
+// along as dead weight (with no define and no `process` in a browser, the dev
+// gate resolves to `false` at runtime — the text could never even print).
+//
+// So these tests read `dist/` directly. A define that silently stops being
+// applied is not visible from source, and this is the only place it shows up.
+// ---------------------------------------------------------------------------
+
+const ROOT = resolve(__dirname, "..");
+const PROD_CDN = resolve(ROOT, "dist/cdn.global.js");
+const DEV_CDN = resolve(ROOT, "dist/cdn.dev.global.js");
+
+// Every diagnostic, identified by a literal only it emits, which survives
+// minification verbatim. Keep in step with the marker list in
+// `treeshaking-dev-diagnostics.test.ts`.
+const DIAGNOSTIC_MARKERS = {
+  "lone-string class heuristic": "looks like a class list",
+  "duplicate node in reactive array": "duplicate node reference",
+  "dropped style declaration": "was dropped by the style sanitizer",
+  "blocked-construct explanation": "exfiltration channel",
+  "focus lost on rebuild": "discarded the focused element",
+  "ambiguous focus identity": "several elements in the rebuilt subtree",
+  "when()/match() element-branch reuse": "branch was given as an element",
+  "duplicate reactive runtime": "Multiple instances of the reactive runtime",
+  "warning cap notice": "suppressing further",
+} as const;
+
+// `dist/` only exists after `npm run build`. Skipping locally keeps a plain
+// `vitest` run working on a fresh clone; on CI a missing artifact is a failure,
+// because CI always builds first and a silent skip there would hide exactly the
+// regression this file exists to catch.
+const built = existsSync(PROD_CDN) && existsSync(DEV_CDN);
+const onCI = !!process.env.CI;
+
+describe.skipIf(!built && !onCI)("published CDN artifacts", () => {
+  it("both CDN bundles exist (run `npm run build` first)", () => {
+    expect(existsSync(PROD_CDN), `missing ${PROD_CDN}`).toBe(true);
+    expect(existsSync(DEV_CDN), `missing ${DEV_CDN}`).toBe(true);
+  });
+
+  it("the production CDN bundle contains NO diagnostic text", () => {
+    const source = readFileSync(PROD_CDN, "utf8");
+    for (const [name, marker] of Object.entries(DIAGNOSTIC_MARKERS)) {
+      expect(
+        source.includes(marker),
+        `${name}: ${JSON.stringify(marker)} leaked into dist/cdn.global.js — a <script> consumer cannot strip it`,
+      ).toBe(false);
+    }
+  });
+
+  it("the development CDN bundle keeps every diagnostic", () => {
+    // The counterpart guarantee. A no-build consumer opts into warnings by
+    // loading this file instead; if the define were inverted, or this artifact
+    // silently became a copy of the production one, the warnings would be gone
+    // and nothing else would notice.
+    const source = readFileSync(DEV_CDN, "utf8");
+    for (const [name, marker] of Object.entries(DIAGNOSTIC_MARKERS)) {
+      expect(source.includes(marker), `${name}: ${JSON.stringify(marker)} missing from dist/cdn.dev.global.js`).toBe(
+        true,
+      );
+    }
+  });
+
+  it("the production CDN bundle is smaller than the development one", () => {
+    // A cheap structural check that the two builds really are different
+    // artifacts built with different defines, rather than the same bytes
+    // written twice under two names.
+    const prod = statSync(PROD_CDN).size;
+    const dev = statSync(DEV_CDN).size;
+    expect(prod).toBeLessThan(dev);
+  });
+
+  it("the production CDN bundle still self-registers on window", () => {
+    // Stripping diagnostics must not strip the entry behaviour that makes this
+    // artifact a CDN bundle at all.
+    const source = readFileSync(PROD_CDN, "utf8");
+    expect(source).toContain("Sibu");
+  });
+});
diff --git a/tests/focus-preservation.test.ts b/tests/focus-preservation.test.ts
new file mode 100644
index 0000000..85bb547
--- /dev/null
+++ b/tests/focus-preservation.test.ts
@@ -0,0 +1,181 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { when } from "../src/core/rendering/directives";
+import { div, input } from "../src/core/rendering/html";
+import { signal } from "../src/core/signals/signal";
+
+// ---------------------------------------------------------------------------
+// A reactive rebuild must not silently take the caret with it.
+//
+// A block that re-creates its children destroys the focused node, and focus
+// falls back to <body>. Typing one character into an input inside such a block
+// therefore ends the edit — the user's next keystroke goes nowhere. Nothing is
+// logged; it reads as the app "losing" what you typed.
+//
+// Two behaviours are pinned here:
+//   1. Where the rebuilt subtree contains an element of re-establishable
+//      identity, focus AND the selection range come back.
+//   2. Where identity cannot be re-established, dev says so out loud and points
+//      at the keying pattern that avoids the rebuild altogether.
+// ---------------------------------------------------------------------------
+
+// Reactive bindings commit synchronously; when()/match() defer their FIRST
+// render to a microtask. Two turns covers both.
+const flushMicrotasks = () => Promise.resolve().then(() => Promise.resolve());
+
+let warn: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  document.body.innerHTML = "";
+});
+
+afterEach(() => {
+  warn.mockRestore();
+  document.body.innerHTML = "";
+});
+
+function messages(): string {
+  return warn.mock.calls.map((c) => String(c[0])).join("\n");
+}
+
+describe("focus preservation across reactive rebuilds", () => {
+  it("keeps focus on an input with a stable id when the subtree rebuilds", async () => {
+    const [n, setN] = signal(0);
+    // Each run builds a BRAND NEW input — node identity is not preserved by the
+    // getter, which is exactly the situation that loses the caret.
+    const host = div(() => [input({ id: "title", type: "text", value: String(n()) })]);
+    document.body.appendChild(host);
+    await flushMicrotasks();
+
+    const first = host.querySelector<HTMLInputElement>("#title");
+    expect(first).not.toBeNull();
+    first?.focus();
+    expect(document.activeElement).toBe(first);
+
+    setN(1);
+    await flushMicrotasks();
+
+    const rebuilt = host.querySelector<HTMLInputElement>("#title");
+    expect(rebuilt).not.toBe(first); // proves a real rebuild happened
+    expect(document.activeElement).toBe(rebuilt);
+  });
+
+  it("restores the selection range, not just focus", async () => {
+    const [n, setN] = signal(0);
+    // The getter MUST read the signal, or there is no rebuild and the test
+    // proves nothing.
+    const host = div(() => [input({ id: "title", type: "text", value: `hello world ${n()}` })]);
+    document.body.appendChild(host);
+    await flushMicrotasks();
+
+    const first = host.querySelector<HTMLInputElement>("#title");
+    if (!first) throw new Error("input not rendered");
+    first.focus();
+    first.setSelectionRange(2, 7);
+
+    setN(n() + 1);
+    await flushMicrotasks();
+
+    const rebuilt = host.querySelector<HTMLInputElement>("#title");
+    if (!rebuilt) throw new Error("input not rebuilt");
+    expect(document.activeElement).toBe(rebuilt);
+    expect(rebuilt.selectionStart).toBe(2);
+    expect(rebuilt.selectionEnd).toBe(7);
+  });
+
+  it("re-establishes identity from name when there is no id", async () => {
+    const [n, setN] = signal(0);
+    const host = div(() => [input({ name: "email", type: "email", value: String(n()) })]);
+    document.body.appendChild(host);
+    await flushMicrotasks();
+
+    const first = host.querySelector<HTMLInputElement>("[name=email]");
+    first?.focus();
+    setN(1);
+    await flushMicrotasks();
+
+    const rebuilt = host.querySelector<HTMLInputElement>("[name=email]");
+    expect(rebuilt).not.toBe(first);
+    expect(document.activeElement).toBe(rebuilt);
+  });
+
+  it("warns in dev when a rebuild discards the focused element and identity cannot be re-established", async () => {
+    const [showText, setShowText] = signal(true);
+    // The branches have nothing in common — no id, no name, not even the same
+    // tag — so there is no honest way to decide what "the same element" is.
+    const host = div(() => (showText() ? [input({ type: "text" })] : [div("replaced")]));
+    document.body.appendChild(host);
+    await flushMicrotasks();
+
+    host.querySelector("input")?.focus();
+    setShowText(false);
+    await flushMicrotasks();
+
+    expect(messages()).toContain("discarded the focused element");
+  });
+
+  it("names the match() keying pattern in the warning", async () => {
+    const [showText, setShowText] = signal(true);
+    const host = div(() => (showText() ? [input({ type: "text" })] : [div("replaced")]));
+    document.body.appendChild(host);
+    await flushMicrotasks();
+    host.querySelector("input")?.focus();
+    setShowText(false);
+    await flushMicrotasks();
+
+    expect(messages()).toContain("match(");
+  });
+
+  it("stays silent when the focused element is outside the rebuilt subtree", async () => {
+    const [n, setN] = signal(0);
+    const outside = input({ id: "outside", type: "text" });
+    const host = div(() => [div(String(n()))]);
+    document.body.append(outside, host);
+    await flushMicrotasks();
+
+    outside.focus();
+    setN(1);
+    await flushMicrotasks();
+
+    expect(document.activeElement).toBe(outside);
+    expect(messages()).not.toContain("discarded the focused element");
+  });
+
+  it("stays silent when nothing was focused", async () => {
+    const [n, setN] = signal(0);
+    // Reads the signal, so setN below genuinely rebuilds the subtree — the
+    // point is that a rebuild with NOTHING focused must stay quiet.
+    const host = div(() => [input({ type: "text", value: `v${n()}` })]);
+    document.body.appendChild(host);
+    await flushMicrotasks();
+
+    const first = host.querySelector("input");
+    setN(1);
+    await flushMicrotasks();
+
+    expect(host.querySelector("input")).not.toBe(first); // a rebuild did happen
+    expect(messages()).not.toContain("discarded the focused element");
+  });
+
+  it("preserves focus across a when() branch rebuild that keeps the same identity", async () => {
+    const [flag, setFlag] = signal(true);
+    const host = div([
+      when(
+        () => flag(),
+        () => div([input({ id: "q", type: "text" })]),
+        () => div([input({ id: "q", type: "text" })]),
+      ),
+    ]);
+    document.body.appendChild(host);
+    await flushMicrotasks();
+
+    const first = host.querySelector<HTMLInputElement>("#q");
+    first?.focus();
+    setFlag(false);
+    await flushMicrotasks();
+
+    const rebuilt = host.querySelector<HTMLInputElement>("#q");
+    expect(rebuilt).not.toBe(first);
+    expect(document.activeElement).toBe(rebuilt);
+  });
+});
diff --git a/tests/hardening-review-regressions.test.ts b/tests/hardening-review-regressions.test.ts
new file mode 100644
index 0000000..b1f1383
--- /dev/null
+++ b/tests/hardening-review-regressions.test.ts
@@ -0,0 +1,277 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { match, when } from "../src/core/rendering/directives";
+import { div, input, span } from "../src/core/rendering/html";
+import { signal } from "../src/core/signals/signal";
+import { sanitizeCSSValue, sanitizeStyleAttribute } from "../src/utils/sanitize";
+
+// ---------------------------------------------------------------------------
+// Regressions found reviewing the hardening work itself.
+//
+// Widening `when`/`match` to accept a bare element, and adding focus
+// preservation, each introduced a new way to fail quietly — the exact fault the
+// original work set out to remove. Pinned here.
+// ---------------------------------------------------------------------------
+
+const flush = () => Promise.resolve().then(() => Promise.resolve());
+
+let warn: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  document.body.innerHTML = "";
+});
+afterEach(() => {
+  warn.mockRestore();
+  document.body.innerHTML = "";
+});
+
+const messages = () => warn.mock.calls.map((c) => String(c[0])).join("\n");
+
+describe("a bare element branch stays reactive across a switch", () => {
+  it("when(): the re-attached element's reactive class still updates", async () => {
+    const [flag, setFlag] = signal(true);
+    const [label, setLabel] = signal("one");
+    // The element is built ONCE and handed to `when` directly, so `when` does
+    // not own it and must not tear down bindings the caller still relies on.
+    const el = div({ class: () => label() });
+    const host = div([when(() => flag(), el, span("other"))]);
+    document.body.appendChild(host);
+    await flush();
+
+    expect(el.getAttribute("class")).toBe("one");
+
+    setFlag(false); // detached
+    await flush();
+    setFlag(true); // re-attached
+    await flush();
+
+    setLabel("two");
+    await flush();
+    expect(el.getAttribute("class")).toBe("two");
+  });
+
+  it("match(): the re-attached case element still updates", async () => {
+    const [key, setKey] = signal("a");
+    const [label, setLabel] = signal("one");
+    const el = div({ class: () => label() });
+    const host = div([match(() => key(), { a: el, b: span("other") })]);
+    document.body.appendChild(host);
+    await flush();
+
+    setKey("b");
+    await flush();
+    setKey("a");
+    await flush();
+
+    setLabel("two");
+    await flush();
+    expect(el.getAttribute("class")).toBe("two");
+  });
+
+  it("still disposes a FACTORY-built branch, which it does own", async () => {
+    const [flag, setFlag] = signal(true);
+    const [label, setLabel] = signal("one");
+    // Collected into an array rather than a `let … = null` binding: TypeScript
+    // does not track assignments made inside a callback, so a `let` initialised
+    // to null narrows to `null` at the read below and then to `never` after the
+    // guard. Pushing also records every node the factory builds, which is what
+    // the assertion is really about.
+    const built: HTMLElement[] = [];
+    const host = div([
+      when(
+        () => flag(),
+        () => {
+          const el = div({ class: () => label() }) as HTMLElement;
+          built.push(el);
+          return el;
+        },
+        () => span("other"),
+      ),
+    ]);
+    document.body.appendChild(host);
+    await flush();
+    const first = built[0];
+    if (!first) throw new Error("branch not built");
+
+    setFlag(false); // discarded — `when` built it, so `when` disposes it
+    await flush();
+    setLabel("two");
+    await flush();
+    // The discarded node must NOT still be tracking the signal.
+    expect(first.getAttribute("class")).toBe("one");
+  });
+
+  it("warns about reuse of a bare element branch", async () => {
+    const [flag, setFlag] = signal(true);
+    const el = div("reused");
+    const host = div([when(() => flag(), el, span("other"))]);
+    document.body.appendChild(host);
+    await flush();
+    setFlag(false);
+    await flush();
+    setFlag(true);
+    await flush();
+
+    expect(messages()).toContain("branch was given as an element");
+  });
+
+  it("match() warns about reuse too", async () => {
+    const [key, setKey] = signal("a");
+    const el = div("reused");
+    const host = div([match(() => key(), { a: el, b: span("other") })]);
+    document.body.appendChild(host);
+    await flush();
+    setKey("b");
+    await flush();
+    setKey("a");
+    await flush();
+
+    expect(messages()).toContain("branch was given as an element");
+  });
+});
+
+describe("focus restoration never guesses", () => {
+  it("does not move focus onto a different member of a radio group", async () => {
+    const [n, setN] = signal(0);
+    // Three radios share one `name`. `name` alone therefore does NOT identify
+    // an element, and restoring on it would put the caret on the wrong control.
+    const host = div(() => [
+      input({ type: "radio", name: "color", value: `red${n()}` }),
+      input({ type: "radio", name: "color", value: `green${n()}` }),
+      input({ type: "radio", name: "color", value: `blue${n()}` }),
+    ]);
+    document.body.appendChild(host);
+    await flush();
+
+    const radios = host.querySelectorAll<HTMLInputElement>("input");
+    radios[1].focus();
+    expect(document.activeElement).toBe(radios[1]);
+
+    setN(1);
+    await flush();
+
+    const rebuilt = host.querySelectorAll<HTMLInputElement>("input");
+    // Restoring onto rebuilt[0] would be worse than not restoring: the next
+    // keystroke would land on a control the user was not using.
+    expect(document.activeElement).not.toBe(rebuilt[0]);
+    expect(document.activeElement).not.toBe(rebuilt[2]);
+  });
+
+  it("still restores on a name that IS unique in the subtree", async () => {
+    const [n, setN] = signal(0);
+    const host = div(() => [input({ type: "email", name: "email", value: `v${n()}` })]);
+    document.body.appendChild(host);
+    await flush();
+
+    const first = host.querySelector<HTMLInputElement>("[name=email]");
+    first?.focus();
+    setN(1);
+    await flush();
+
+    const rebuilt = host.querySelector<HTMLInputElement>("[name=email]");
+    expect(rebuilt).not.toBe(first);
+    expect(document.activeElement).toBe(rebuilt);
+  });
+
+  it("notices focus lost by a MOVE, where the node survives but is blurred", async () => {
+    // Re-inserting a focused node blurs it in real browsers. jsdom does NOT
+    // emulate that, so driving this through a live rebuild would prove nothing;
+    // the capture/restore pair is exercised directly instead, with the blur
+    // injected between them exactly where a browser would perform it.
+    const { captureFocusWithin, restoreFocusWithin } = await import("../src/core/rendering/focusPreservation");
+
+    const field = input({ id: "stable", type: "text", value: "hello" }) as HTMLInputElement;
+    document.body.appendChild(field);
+    field.focus();
+    field.setSelectionRange(2, 4);
+
+    const snapshot = captureFocusWithin([field]);
+    expect(snapshot).not.toBeNull();
+
+    // What the browser does when the node is moved: same node, still in the
+    // document, no longer focused.
+    field.blur();
+    expect(field.isConnected).toBe(true);
+    expect(document.activeElement).not.toBe(field);
+
+    restoreFocusWithin(snapshot, [field], "bindChildNode");
+
+    expect(document.activeElement).toBe(field);
+    expect(field.selectionStart).toBe(2);
+    expect(field.selectionEnd).toBe(4);
+  });
+
+  it("does not steal focus that the rebuild deliberately moved elsewhere", async () => {
+    const { captureFocusWithin, restoreFocusWithin } = await import("../src/core/rendering/focusPreservation");
+
+    const old = input({ id: "old", type: "text" }) as HTMLInputElement;
+    const fresh = input({ id: "fresh", type: "text" }) as HTMLInputElement;
+    document.body.append(old, fresh);
+    old.focus();
+    const snapshot = captureFocusWithin([old]);
+
+    // A new branch autofocuses its own first field. Restoring the old caret
+    // over the top of that would fight the application.
+    old.remove();
+    fresh.focus();
+    restoreFocusWithin(snapshot, [fresh], "when");
+
+    expect(document.activeElement).toBe(fresh);
+  });
+});
+
+describe("style sanitizer warns exactly once per dropped declaration", () => {
+  it("warns once for a property-qualified block (filter: progid)", () => {
+    sanitizeStyleAttribute("filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#fff')");
+    const drops = warn.mock.calls
+      .map((c) => String(c[0]))
+      .filter((m) => m.includes("was dropped by the style sanitizer"));
+    expect(drops).toHaveLength(1);
+  });
+
+  it("warns once for a custom property whose joined form is blocked", () => {
+    sanitizeStyleAttribute("--behavior: red; behavior: url(#x)");
+    const drops = warn.mock.calls
+      .map((c) => String(c[0]))
+      .filter((m) => m.includes("was dropped by the style sanitizer"));
+    // Only `behavior: url(#x)` is dangerous; `--behavior: red` is a custom
+    // property holding the word "red" and must survive untouched.
+    expect(drops).toHaveLength(1);
+  });
+
+  it("does not flood when a reactive style recomputes", () => {
+    // The same declaration blocked 50 times is one problem, not 50.
+    for (let i = 0; i < 50; i++) sanitizeCSSValue("url(/poster.jpg)", { property: "background-image" });
+    const drops = warn.mock.calls
+      .map((c) => String(c[0]))
+      .filter((m) => m.includes("was dropped by the style sanitizer"));
+    expect(drops.length).toBeLessThanOrEqual(1);
+  });
+
+  it("still reports a DIFFERENT dropped declaration", () => {
+    sanitizeCSSValue("url(/a.png)", { property: "background-image" });
+    sanitizeCSSValue("url(/b.png)", { property: "border-image" });
+    const drops = warn.mock.calls
+      .map((c) => String(c[0]))
+      .filter((m) => m.includes("was dropped by the style sanitizer"));
+    expect(drops).toHaveLength(2);
+  });
+});
+
+describe("isDev() honours a globalThis override set after module load", () => {
+  it("reads the global live, which is what makes it different from DEV", async () => {
+    const { isDev } = await import("../src/core/dev");
+    const g = globalThis as Record<string, unknown>;
+    const had = "__SIBU_DEV__" in g;
+    const prev = g.__SIBU_DEV__;
+    try {
+      g.__SIBU_DEV__ = false;
+      expect(isDev()).toBe(false);
+      g.__SIBU_DEV__ = true;
+      expect(isDev()).toBe(true);
+    } finally {
+      if (had) g.__SIBU_DEV__ = prev;
+      else delete g.__SIBU_DEV__;
+    }
+  });
+});
diff --git a/tests/lone-string-heuristic-rate.test.ts b/tests/lone-string-heuristic-rate.test.ts
new file mode 100644
index 0000000..dee1525
--- /dev/null
+++ b/tests/lone-string-heuristic-rate.test.ts
@@ -0,0 +1,311 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { div, p, span } from "../src/core/rendering/html";
+
+// ---------------------------------------------------------------------------
+// The lone-string class heuristic, measured rather than asserted.
+//
+// `div("mb-3 aspect-video w-full")` renders Tailwind classes as visible text,
+// because a LONE string argument is a text child while `div("mb-3", [child])`
+// treats the same string as a class. The shorthand is ergonomic and stays; the
+// mistake is made detectable with a dev warning instead.
+//
+// A heuristic is only honest if its error rate is known on a REALISTIC corpus.
+// The first version of this file measured 3.3% false positives and was wrong —
+// not arithmetically, but because the corpus was all prose. Real applications
+// pass identifiers (`item-0`, `home-content`, `user-42`), versions, paths and
+// URLs as ordinary text, and the original rule flagged every one of them. On a
+// corpus containing those the true rate was 29.8%, and a list rendering
+// `item-0` through `item-999` produced a thousand warnings.
+//
+// The rule now requires TWO OR MORE tokens with at least two utility-shaped,
+// which takes measured false positives to zero: every one of those identifiers
+// is a single token, and hyphenated English carries only one utility-shaped
+// token per phrase. The cost is single-token class lists — `div("space-y-6")`
+// no longer warns — and that trade is deliberate and recorded below.
+//
+// This is a RATE test with headroom, and the exact misses are listed so a
+// change to the heuristic surfaces as a changed list rather than silent drift.
+// ---------------------------------------------------------------------------
+
+let warn: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+});
+afterEach(() => {
+  warn.mockRestore();
+});
+
+/**
+ * Does a lone-string `div(s)` trip the class-list warning?
+ *
+ * Each corpus string is distinct, so the runtime's de-duplication (one warning
+ * per tag+string) never fires within a single sweep. Re-checking a string
+ * already used in a sweep needs a different tag — see the reported-case test.
+ */
+function flags(s: string): boolean {
+  warn.mockClear();
+  div(s);
+  return warn.mock.calls.some((c) => String(c[0]).includes("looks like a class list"));
+}
+
+// Text a developer legitimately passes as a lone text child.
+const TEXT = [
+  // prose, labels, button captions
+  "Hello world",
+  "Submit",
+  "Cancel",
+  "Save changes",
+  "Loading…",
+  "No results found",
+  "Sign in",
+  "Sign out",
+  "Create account",
+  "Forgot your password?",
+  "Try again",
+  "Settings",
+  "Profile",
+  "Dashboard",
+  "Notifications",
+  "Search",
+  "Filter",
+  "Sort by",
+  "Read more",
+  "Show less",
+  "Back to top",
+  "Next",
+  "Previous",
+  "Edit",
+  "Delete",
+  "Duplicate",
+  "Archive",
+  "Restore",
+  "Download",
+  "Share",
+  "Copy link",
+  "Name",
+  "Email address",
+  "Password",
+  "Confirm password",
+  "Phone number",
+  "Street address",
+  "City",
+  "Postal code",
+  "Country",
+  "Date of birth",
+  "Are you sure?",
+  "This action cannot be undone.",
+  "Your changes have been saved.",
+  "An unexpected error occurred. Please try again later.",
+  "Drag files here or click to upload",
+  "Powered by SibuJS",
+  "All rights reserved",
+  "Select an option",
+  "Choose a file",
+  "Nothing here yet",
+  "Get started",
+  "Offline",
+  "Reconnecting…",
+  "Updated just now",
+  "Last updated 3 minutes ago",
+  // counts, money, dates, versions
+  "3 items selected",
+  "12 unread",
+  "Page 1 of 20",
+  "99+",
+  "42",
+  "0",
+  "1,234 followers",
+  "$19.99",
+  "€1.500,00",
+  "12:30",
+  "2026-09-06",
+  "3.14159",
+  "v4.1.0",
+  "100%",
+  "50 MB",
+  "OK",
+  "Yes",
+  "No",
+  "Done",
+  "N/A",
+  "—",
+  "…",
+  // identifiers, keys, paths, URLs — absent from the original corpus, and the
+  // reason its 3.3% figure was not the operational rate
+  "item-0",
+  "item-1",
+  "item-999",
+  "home-content",
+  "main-nav",
+  "user-42",
+  "row-7",
+  "tab-2",
+  "step-3",
+  "https://example.com",
+  "http://localhost:3000",
+  "user@example.com",
+  "README.md",
+  "package.json",
+  "src/index.ts",
+  "dist/cdn.global.js",
+  "GET /api/users",
+  "500 Internal Server Error",
+  "404 Not Found",
+  // hyphenated English, both as phrases and as lone labels
+  "e-mail address",
+  "state-of-the-art design",
+  "up-to-date now",
+  "well-known issues",
+  "opt-in only",
+  "read-only field",
+  "built-in support",
+  "end-to-end tests",
+  "real-time updates",
+  "drag-and-drop here",
+  "end-to-end",
+  "state-of-the-art",
+  "up-to-date",
+  "drag-and-drop",
+  "out-of-stock",
+  "one-to-one",
+  "read-only",
+  "well-known",
+  "built-in",
+  "real-time",
+  "opt-in",
+  "sign-in",
+  "follow-up",
+  "check-in",
+  // non-English
+  "Iniciar sesión",
+  "Cerrar sesión",
+  "Guardar cambios",
+  "No hay resultados",
+  "こんにちは",
+  "登录",
+  "Anmelden",
+  "S'inscrire",
+  "Zurück",
+  "Weiter",
+];
+
+// Strings that really are a className, passed by mistake.
+const CLASSES = [
+  "mb-3 aspect-video w-full",
+  "space-y-6",
+  "h-6 w-48",
+  "flex items-center gap-2",
+  "text-sm text-muted-foreground",
+  "rounded-lg border bg-card p-6 shadow-sm",
+  "grid grid-cols-3 gap-4",
+  "absolute inset-0 z-50",
+  "md:flex lg:hidden",
+  "w-1/2",
+  "mt-4",
+  "px-4 py-2",
+  "font-semibold tracking-tight",
+  "hover:bg-accent focus:outline-none",
+  "min-h-screen",
+  "max-w-2xl mx-auto",
+  "btn btn-primary",
+  "card card-body",
+  "col-md-6",
+  "d-flex justify-content-between",
+  "sr-only",
+  "animate-pulse",
+  "overflow-x-auto",
+  "border-t-2",
+  "opacity-50",
+  "dark:bg-slate-900",
+  "text-2xl",
+  "gap-x-8",
+  "truncate",
+  "sticky top-0",
+  "list-none",
+  "cursor-pointer select-none",
+  "transition-colors duration-200",
+  "bg-red-500 text-white",
+  "ring-2 ring-offset-2",
+  "aspect-square object-cover",
+  "container mx-auto px-4",
+  "h-full w-full",
+  "leading-6",
+  "-mt-px",
+  "z-10",
+];
+
+// Every miss is a single token, or a pair carrying only ONE utility-shaped
+// token ("btn btn-primary", "sticky top-0"). Accepted in exchange for a zero
+// false-positive rate; a warning that cries wolf protects nobody.
+const KNOWN_FALSE_NEGATIVES = [
+  "space-y-6",
+  "w-1/2",
+  "mt-4",
+  "min-h-screen",
+  "btn btn-primary",
+  "card card-body",
+  "col-md-6",
+  "sr-only",
+  "animate-pulse",
+  "overflow-x-auto",
+  "border-t-2",
+  "opacity-50",
+  "dark:bg-slate-900",
+  "text-2xl",
+  "gap-x-8",
+  "truncate",
+  "sticky top-0",
+  "list-none",
+  "leading-6",
+  "-mt-px",
+  "z-10",
+];
+
+describe("lone-string class heuristic: measured error rate", () => {
+  it("flags no prose, identifier, path, URL or version in the corpus", () => {
+    const wrong = TEXT.filter(flags);
+    expect(wrong).toEqual([]);
+  });
+
+  it("has a false-negative rate at or below 55% on real class lists", () => {
+    const missed = CLASSES.filter((s) => !flags(s));
+    expect(missed).toEqual(KNOWN_FALSE_NEGATIVES);
+    expect(missed.length / CLASSES.length).toBeLessThanOrEqual(0.55);
+  });
+
+  it("catches the exact string from the original report", () => {
+    // A different tag than the corpus sweep used, so the tag+string
+    // de-duplication key is fresh and this asserts against a real warning.
+    warn.mockClear();
+    span("mb-3 aspect-video w-full");
+    expect(warn.mock.calls.map((c) => String(c[0])).join("\n")).toContain("looks like a class list");
+  });
+
+  it("does not flood: one warning per repeated mistake, not one per element", () => {
+    // The failure this replaced: a list of 1,000 rows produced 1,000 warnings.
+    warn.mockClear();
+    for (let i = 0; i < 500; i++) p("grid grid-cols-3 gap-4");
+    const hits = warn.mock.calls.map((c) => String(c[0])).filter((m) => m.includes("looks like a class list"));
+    expect(hits).toHaveLength(1);
+  });
+
+  it("still reports a DIFFERENT mistaken class string", () => {
+    warn.mockClear();
+    p("flex items-center gap-2");
+    const hits = warn.mock.calls.map((c) => String(c[0])).filter((m) => m.includes("looks like a class list"));
+    expect(hits).toHaveLength(1);
+  });
+
+  it("never changes behaviour — a flagged string is still rendered as text", () => {
+    const el = div("px-4 py-2");
+    expect(el.textContent).toBe("px-4 py-2");
+    expect(el.getAttribute("class")).toBeNull();
+  });
+
+  it("treats the same string as a class when children follow", () => {
+    const el = div("mb-3 aspect-video w-full", [div("child")]);
+    expect(el.getAttribute("class")).toBe("mb-3 aspect-video w-full");
+    expect(el.textContent).toBe("child");
+  });
+});
diff --git a/tests/loneStringClassWarning.test.ts b/tests/loneStringClassWarning.test.ts
index 820b854..2bf3151 100644
--- a/tests/loneStringClassWarning.test.ts
+++ b/tests/loneStringClassWarning.test.ts
@@ -21,10 +21,10 @@ describe("BUG 2 — lone class-like string warning (core tag)", () => {
   });
 
   it("warns when a lone string looks like a class list", () => {
-    div("space-y-6");
+    div("px-4 py-2");
     expect(warn).toHaveBeenCalledTimes(1);
     expect(warn.mock.calls[0][0]).toContain("looks like a class list");
-    expect(warn.mock.calls[0][0]).toContain('class: "space-y-6"');
+    expect(warn.mock.calls[0][0]).toContain('class: "px-4 py-2"');
   });
 
   it("warns for multi-token Tailwind-shaped strings", () => {
@@ -33,6 +33,24 @@ describe("BUG 2 — lone class-like string warning (core tag)", () => {
     expect(warn.mock.calls[0][0]).toContain("h-6 w-48");
   });
 
+  it("does NOT warn for a SINGLE token — a deliberate narrowing", () => {
+    // `space-y-6` is a real class list and this used to warn. It no longer
+    // does, because a single hyphen-and-digit token is indistinguishable from
+    // the identifiers applications legitimately render as text: `item-0`,
+    // `user-42`, `home-content`, `v4.1.0`. Warning on that shape measured 29.8%
+    // false positives, and a list rendering `item-0`…`item-999` emitted a
+    // thousand warnings — noise that trains developers to ignore the whole
+    // diagnostic. Requiring two utility-shaped tokens takes false positives to
+    // zero. See `tests/lone-string-heuristic-rate.test.ts` for the measurement.
+    div("space-y-6");
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("reports a repeated mistake once, not once per element", () => {
+    for (let i = 0; i < 100; i++) div("mt-4 mb-4");
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
   it("does NOT warn for prose text", () => {
     div("Hello world");
     span("Click here to continue");
diff --git a/tests/sanitize-style-drop-warning.test.ts b/tests/sanitize-style-drop-warning.test.ts
new file mode 100644
index 0000000..f294b56
--- /dev/null
+++ b/tests/sanitize-style-drop-warning.test.ts
@@ -0,0 +1,87 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { div } from "../src/core/rendering/html";
+import { sanitizeCSSValue, sanitizeStyleAttribute } from "../src/utils/sanitize";
+
+// ---------------------------------------------------------------------------
+// A dropped style declaration must ANNOUNCE ITSELF in dev.
+//
+// The guard is correct and stays: `url()` in an inline style is a real
+// exfiltration channel (it issues a request whose path can carry data), so the
+// declaration is removed. What was wrong is that removal was SILENT. A
+// consumer's images rendered as empty boxes across five renderers with nothing
+// in any console, because "background-image: url(/poster.jpg)" simply
+// evaporated between the author writing it and the browser seeing it.
+//
+// These tests pin the diagnostic: which declaration, on which element, why it
+// went, and what to do instead.
+// ---------------------------------------------------------------------------
+
+let warn: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  warn.mockRestore();
+});
+
+function messages(): string[] {
+  return warn.mock.calls.map((c) => String(c[0]));
+}
+
+describe("sanitizeStyleAttribute — announcing dropped declarations", () => {
+  it("warns naming the property and the reason when a url() declaration is dropped", () => {
+    const out = sanitizeStyleAttribute("color: red; background-image: url(/poster.jpg)");
+
+    // The guard still applies — the url() declaration is gone, the rest stays.
+    expect(out).toContain("color");
+    expect(out).not.toContain("url(");
+
+    const msg = messages().join("\n");
+    expect(msg).toContain("background-image");
+    expect(msg).toContain("was dropped by the style sanitizer");
+  });
+
+  it("names <img> as the sanctioned alternative for a legitimate image", () => {
+    // A distinct URL from the test above on purpose: identical declarations on
+    // the same element are deduplicated so a reactive style cannot flood the
+    // console, and reusing the value here would assert against a suppressed
+    // warning rather than a real one.
+    sanitizeStyleAttribute("background-image: url(/banner-for-img-advice.jpg)");
+    expect(messages().join("\n")).toMatch(/<img>/);
+  });
+
+  it("quotes the offending value so the author can find it in their source", () => {
+    sanitizeStyleAttribute("background: url(https://cdn.example.com/a.png) no-repeat");
+    expect(messages().join("\n")).toContain("cdn.example.com/a.png");
+  });
+
+  it("stays silent when nothing is dropped", () => {
+    const out = sanitizeStyleAttribute("color: red; margin: 0");
+    expect(out).toContain("color");
+    expect(messages()).toHaveLength(0);
+  });
+
+  it("warns once per dropped declaration, not once per style attribute", () => {
+    sanitizeStyleAttribute("background-image: url(/a.png); border-image: url(/b.png)");
+    const dropWarnings = messages().filter((m) => m.includes("was dropped by the style sanitizer"));
+    expect(dropWarnings).toHaveLength(2);
+  });
+
+  it("warns for the OBJECT form too, not only the string form", () => {
+    // The object form goes through sanitizeCSSValue per property, which is the
+    // path `style: { backgroundImage: … }` takes. It dropped just as silently.
+    const out = sanitizeCSSValue("url(/poster.jpg)");
+    expect(out).toBe("");
+    expect(messages().join("\n")).toContain("was dropped by the style sanitizer");
+  });
+
+  it("identifies the element the declaration was dropped from", () => {
+    div({ id: "hero", class: "banner", style: "background-image: url(/poster.jpg)" });
+    const msg = messages().join("\n");
+    // Enough of a fingerprint to locate the element in a page full of divs.
+    expect(msg).toContain("div");
+    expect(msg).toContain("hero");
+  });
+});
diff --git a/tests/treeshaking-dev-diagnostics.test.ts b/tests/treeshaking-dev-diagnostics.test.ts
new file mode 100644
index 0000000..672e86a
--- /dev/null
+++ b/tests/treeshaking-dev-diagnostics.test.ts
@@ -0,0 +1,108 @@
+// @vitest-environment node
+//
+// esbuild refuses to run inside jsdom (its TextEncoder produces a Uint8Array
+// from a different realm), and nothing here needs a DOM: it bundles source and
+// inspects strings.
+
+import { resolve } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, it } from "vitest";
+
+// ---------------------------------------------------------------------------
+// Dev diagnostics must COMPILE OUT of a production build.
+//
+// Every warning this library emits is a developer-experience feature paid for
+// by consumers in bytes unless the gate that guards it can be statically folded
+// away. `isDev()` is that gate, and the only thing a bundler can fold is the
+// `__SIBU_DEV__` define — so `isDev()` must consult the define FIRST. If it
+// leads with a `globalThis.__SIBU_DEV__` runtime lookup instead, nothing folds,
+// every warning string ships, and each new diagnostic makes the production
+// bundle bigger for no runtime benefit.
+//
+// Each diagnostic is identified by a string literal only that diagnostic emits,
+// which survives minification verbatim.
+// ---------------------------------------------------------------------------
+
+const ROOT = resolve(__dirname, "..");
+
+async function bundle(entry: string, dev: boolean): Promise<string> {
+  const result = await build({
+    stdin: { contents: entry, resolveDir: ROOT, loader: "ts" },
+    bundle: true,
+    minify: true,
+    format: "esm",
+    target: "es2020",
+    write: false,
+    define: { __SIBU_DEV__: String(dev), __SIBU_VERSION__: '"test"' },
+  });
+  return result.outputFiles[0].text;
+}
+
+// Markers for diagnostics reachable from the main entry point.
+const CORE_MARKERS = {
+  "lone-string class heuristic": "looks like a class list",
+  "duplicate node in reactive array": "duplicate node reference",
+  "dropped style declaration": "was dropped by the style sanitizer",
+  "focus lost on rebuild": "discarded the focused element",
+  "ambiguous focus identity": "several elements in the rebuilt subtree",
+  "when() element-branch reuse": "branch was given as an element",
+  // Emitted by tagFactory and the style sanitizer once their warning caches
+  // fill up, so it belongs with the core diagnostics.
+  "warning cap notice": "suppressing further",
+  // Explanatory prose reached only from a warning callback. It leaked twice
+  // while this work was in progress, because tree-shaking marks a TOP-LEVEL
+  // binding live before the `__SIBU_DEV__` define folds its only reference
+  // away — so dev-only text has to live INSIDE the callback, not in a constant
+  // or helper the callback names. These two markers are the regression guard.
+  "blocked-construct explanation": "exfiltration channel",
+  "blocked-construct explanation (2)": "legacy scriptable filters",
+} as const;
+
+// NOTE: `[SibuJS]` is deliberately NOT a marker. `reportError` uses the same
+// prefix for uncaught runtime errors, which must survive into production — so
+// its presence proves nothing either way.
+
+const PLUGIN_MARKERS = {
+  "duplicate reactive runtime": "Multiple instances of the reactive runtime",
+} as const;
+
+describe("dev diagnostics are stripped from production builds", () => {
+  it("emits every core diagnostic when __SIBU_DEV__ is true", async () => {
+    const out = await bundle(`export * from "./index";`, true);
+    for (const [name, marker] of Object.entries(CORE_MARKERS)) {
+      expect(out.includes(marker), `${name}: expected marker ${JSON.stringify(marker)} in the DEV bundle`).toBe(true);
+    }
+  }, 60_000);
+
+  it("strips every core diagnostic when __SIBU_DEV__ is false", async () => {
+    const out = await bundle(`export * from "./index";`, false);
+    for (const [name, marker] of Object.entries(CORE_MARKERS)) {
+      expect(out.includes(marker), `${name}: marker ${JSON.stringify(marker)} leaked into the PROD bundle`).toBe(false);
+    }
+  }, 60_000);
+
+  it("strips the duplicate-runtime warning from a production plugins build", async () => {
+    const dev = await bundle(`export * from "./plugins";`, true);
+    const prod = await bundle(`export * from "./plugins";`, false);
+    for (const [name, marker] of Object.entries(PLUGIN_MARKERS)) {
+      expect(dev.includes(marker), `${name}: expected marker in the DEV bundle`).toBe(true);
+      expect(prod.includes(marker), `${name}: marker leaked into the PROD bundle`).toBe(false);
+    }
+  }, 60_000);
+
+  it("keeps the globalThis override working when no define is present", async () => {
+    // Without a `__SIBU_DEV__` define the library cannot know the mode at build
+    // time, so it must fall back to the runtime global. Diagnostics stay in the
+    // bundle here — that is the correct, honest outcome for an un-configured
+    // build, and the escape hatch the test suite itself relies on.
+    const result = await build({
+      stdin: { contents: `export * from "./index";`, resolveDir: ROOT, loader: "ts" },
+      bundle: true,
+      minify: true,
+      format: "esm",
+      target: "es2020",
+      write: false,
+    });
+    expect(result.outputFiles[0].text.includes("[SibuJS]")).toBe(true);
+  }, 60_000);
+});
diff --git a/tests/warning-dedupe-cap.test.ts b/tests/warning-dedupe-cap.test.ts
new file mode 100644
index 0000000..389ef4d
--- /dev/null
+++ b/tests/warning-dedupe-cap.test.ts
@@ -0,0 +1,96 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { div } from "../src/core/rendering/html";
+import { sanitizeCSSValue } from "../src/utils/sanitize";
+
+// ---------------------------------------------------------------------------
+// The de-duplication caches are bounded, and the bound must not re-open the
+// flood it exists to prevent.
+//
+// Both caches were written as:
+//
+//     if (seen.has(key)) return "";
+//     if (seen.size < MAX) seen.add(key);
+//     return message;
+//
+// which is correct right up to the cap and wrong immediately after it. Once
+// `size` reaches MAX nothing more is inserted, so `has(key)` is permanently
+// false for every new key — and the message is still returned. The 101st
+// distinct mistake therefore warns on EVERY render, forever: precisely the
+// per-element flood the cache was added to stop, just deferred.
+//
+// Past the cap the caches now go quiet, after one notice saying so. Silence
+// that announces itself is honest; silence that does not is how this whole
+// class of bug started.
+//
+// This file lives on its own because filling a cache to its cap is global to
+// the module, and would leak into any other test in the same file.
+// ---------------------------------------------------------------------------
+
+const CAP = 100;
+
+let warn: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+});
+afterEach(() => {
+  warn.mockRestore();
+});
+
+const hits = (needle: string) => warn.mock.calls.map((c) => String(c[0])).filter((m) => m.includes(needle)).length;
+
+// Each cap can only be crossed ONCE per module instance, so each is exercised
+// in a single test. Splitting the crossing across two tests would leave the
+// second asserting against a cache another test had already filled — which is
+// how the first draft of this file passed for the wrong reason.
+describe("lone-string warning cache past its cap", () => {
+  it("goes quiet after the cap, announcing once instead of warning per render", () => {
+    // Fill the cache with CAP distinct mistakes. Each is a genuine
+    // two-utility-token class string, so each warns exactly once.
+    for (let i = 0; i < CAP; i++) div(`mt-${i} mb-${i}`);
+    expect(hits("looks like a class list")).toBeGreaterThanOrEqual(CAP);
+
+    // One more DISTINCT mistake, rendered repeatedly — a list of rows, say.
+    // Before the fix this produced one warning per render, forever.
+    warn.mockClear();
+    for (let i = 0; i < 50; i++) div("pt-9 pb-9");
+
+    expect(hits("looks like a class list")).toBe(0);
+    expect(hits("suppressing further")).toBe(1);
+
+    // And the notice itself does not repeat.
+    warn.mockClear();
+    for (let i = 0; i < 20; i++) div(`px-${i} py-${i}`);
+    expect(hits("suppressing further")).toBe(0);
+    expect(hits("looks like a class list")).toBe(0);
+  });
+});
+
+describe("style-sanitizer warning cache past its cap", () => {
+  it("goes quiet after the cap, announcing once instead of warning per recomputation", () => {
+    for (let i = 0; i < CAP; i++) sanitizeCSSValue(`url(/fill-${i}.png)`, { property: `background-image-${i}` });
+    expect(hits("was dropped by the style sanitizer")).toBeGreaterThanOrEqual(CAP);
+
+    // A reactive style recomputing every frame with a blocked value.
+    warn.mockClear();
+    for (let i = 0; i < 50; i++) sanitizeCSSValue("url(/overflow.png)", { property: "background-image" });
+
+    expect(hits("was dropped by the style sanitizer")).toBe(0);
+    expect(hits("suppressing further")).toBe(1);
+
+    warn.mockClear();
+    for (let i = 0; i < 20; i++) sanitizeCSSValue(`url(/more-${i}.png)`, { property: "background-image" });
+    expect(hits("suppressing further")).toBe(0);
+  });
+
+  it("still returns the empty string for every blocked value after the cap", () => {
+    // Reporting is capped; the SECURITY decision never is. Whatever happens to
+    // the warning, the dangerous declaration must still be dropped.
+    for (let i = 0; i < CAP + 10; i++) {
+      expect(sanitizeCSSValue(`url(/cap-${i}.png)`, { property: "background-image" })).toBe("");
+    }
+    expect(sanitizeCSSValue("url(/anything.png)")).toBe("");
+    // And a safe value is still returned untouched.
+    expect(sanitizeCSSValue("red")).toBe("red");
+  });
+});
diff --git a/tsup.cdn.config.ts b/tsup.cdn.config.ts
new file mode 100644
index 0000000..1b13076
--- /dev/null
+++ b/tsup.cdn.config.ts
@@ -0,0 +1,64 @@
+import { readFileSync } from "node:fs";
+import { defineConfig } from "tsup";
+
+// ---------------------------------------------------------------------------
+// CDN / IIFE builds.
+//
+// These are the ONLY outputs this package ships that a consumer cannot rebundle
+// — a `<script src="…/cdn.global.js">` tag runs exactly the bytes published
+// here. Every other entry point is handed to the consumer's bundler as ESM/CJS
+// with `__SIBU_DEV__` left undefined ON PURPOSE, so that bundler decides the
+// mode and folds the dev branches accordingly (see `src/core/dev.ts`).
+//
+// The CDN cannot delegate that decision, so it must be made here. Leaving it
+// undefined meant `cdn.global.js` shipped every diagnostic string in the
+// library as dead weight: with no define and no `process` in a browser, the dev
+// gate resolves to `false` at runtime, so a no-build consumer downloaded and
+// parsed thousands of bytes of warning text that could never print.
+//
+// Hence two artifacts, and they are NOT interchangeable:
+//
+//   dist/cdn.global.js      __SIBU_DEV__: false — production. Diagnostics are
+//                           compiled out, not merely disabled.
+//   dist/cdn.dev.global.js  __SIBU_DEV__: true  — development. Every warning is
+//                           live with no build step, which is the whole point
+//                           of having diagnostics in a no-build workflow.
+//
+// `tests/dist-artifacts.test.ts` asserts both properties against the real built
+// files, because a define that silently stops being applied is exactly the kind
+// of regression a source-level test cannot see.
+// ---------------------------------------------------------------------------
+
+const { version } = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")) as {
+  version: string;
+};
+
+const shared = {
+  format: ["iife"] as const,
+  globalName: "Sibu",
+  outDir: "dist",
+  dts: false,
+  minify: true,
+};
+
+export default defineConfig([
+  {
+    ...shared,
+    // Object entry form: the KEY is the output basename, so this emits
+    // `cdn.global.js` while the dev build below emits `cdn.dev.global.js` from
+    // the same source.
+    entry: { cdn: "cdn.ts" },
+    define: {
+      __SIBU_DEV__: "false",
+      __SIBU_VERSION__: JSON.stringify(version),
+    },
+  },
+  {
+    ...shared,
+    entry: { "cdn.dev": "cdn.ts" },
+    define: {
+      __SIBU_DEV__: "true",
+      __SIBU_VERSION__: JSON.stringify(version),
+    },
+  },
+]);
diff --git a/tsup.config.ts b/tsup.config.ts
index 600aa53..360149c 100644
--- a/tsup.config.ts
+++ b/tsup.config.ts
@@ -1,12 +1,20 @@
 import { readFileSync } from "node:fs";
 import { defineConfig } from "tsup";
 
+// Config for the ESM/CJS entry points. The CDN/IIFE builds use
+// `tsup.cdn.config.ts` instead.
+//
 // Read the package version so the reactive runtime can stamp it onto the
 // duplicate-instance registry (see src/reactivity/track.ts). `__SIBU_VERSION__`
 // is a bundler define — under raw ESM / the test runner it is undefined and the
-// runtime falls back to "dev". This config is auto-loaded by every `tsup`
-// invocation in the build script (main + CDN), so the stamp lands in all
-// outputs. Entry points / formats stay on the CLI; this only adds `define`.
+// runtime falls back to "dev". Entry points / formats stay on the CLI; this
+// only adds `define`.
+//
+// `__SIBU_DEV__` is deliberately NOT defined here. These outputs are handed to
+// the consumer's bundler, which defines it per build so dev diagnostics are
+// live in development and compiled out in production. Pinning it either way
+// here would take that choice away — and pinning it to `false` would silence
+// every warning in development, which is the opposite of what they are for.
 const { version } = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")) as {
   version: string;
 };