kerfjs 5.0.0-beta.9 → 5.0.0-beta.91

package/dist/{delegate-CL9VTZFb.d.ts → delegate--CrfgYtC.d.ts}

@@ -1,37 +1,3 @@
-/**
- * Tiny event-delegation helpers. Replace per-element `addEventListener` calls
- * (which don't survive morph re-renders for nodes the diff creates) with one
- * listener at the morph-root that dispatches via `closest()`.
- *
- * Three-tier listener model:
- *
- *   - Tier 1 (bubbling events) — use `delegate()`.
- *     click, input, change, submit, mousedown/up, keydown/up, pointerdown/up/move,
- *     drag*, drop, contextmenu, wheel, copy/paste/cut, focusin/focusout.
- *
- *     `delegate()` also auto-promotes the well-known non-bubbling event
- *     types (`focus`, `blur`, `scroll`, `load`, `error`, `mouseenter`,
- *     `mouseleave`) to the capture phase under the hood, so the call site
- *     looks identical for "interactive thing happens on a descendant"
- *     regardless of whether that event bubbles. Selector matching stays
- *     `closest()`-style — the same as for bubbling events — so a wrapper
- *     selector like `'.field-row'` still matches when the event fires on
- *     a descendant `<input>`.
- *
- *   - Tier 2 (explicit capture) — use `delegateCapture()`.
- *     The escape hatch for cases the auto-promotion list doesn't cover
- *     (custom non-bubbling events) or when you want capture-phase
- *     interception. Selector matching is `closest()`-style by default —
- *     the same walk-up as `delegate()`, and it passes the matched ancestor
- *     (not the raw target) to the handler — so a click on any descendant of
- *     the selected element climbs to it. Pass `{ match: 'direct' }` to opt
- *     into strict `matches()`-style matching (fire only when the event lands
- *     on the exact element the selector identifies).
- *
- *   - Tier 3 (per-element instances / library-owned subtrees) — mark the
- *     host element with `data-morph-skip` and manage the library's
- *     lifecycle directly. No delegation helper applies.
- */
 /**
  * How the selector is matched against the event's target:
  *

package/dist/dev.d.ts

@@ -137,7 +137,9 @@ interface DevHooks {
     signalFactory?: <T>(value: T) => Signal<T>;
     /**
      * Wraps an `effect()` body so `delegate()` can detect that it is running
-     * inside one. Returns the body to actually run.
+     * inside one. Returns the body to actually run. Resolved at effect-CREATION
+     * time (the delegate-in-effect switch too), so an effect created before the
+     * install or the opt-in is never wrapped.
      */
     wrapEffect?: (fn: () => void | (() => void)) => () => void | (() => void);
     delegateInEffect?: (fn: 'delegate' | 'delegateCapture') => void;
@@ -146,6 +148,12 @@ interface DevHooks {
     storeReadonly?: <T extends object>(state: T) => T;
     /** Unwraps a proxy handed back through `set({ ...get() })`. */
     storeToRaw?: <T>(next: T) => T;
+    /**
+     * Attaches the rebuilt-listeners observer to a mount root. Called once per
+     * `mount()`, at creation — and it returns `null` when the warning is switched
+     * off then — so a mount created before the install or the opt-in is never
+     * observed.
+     */
     listenerRebuild?: (rootEl: Element) => MutationObserver | null;
     listIdShift?: (id: string) => void;
     parserRepair?: (html: string) => void;
@@ -164,6 +172,8 @@ interface DevHooks {
     duplicateCacheKeys?: (id: string, segItems: readonly {
         cacheKey: unknown;
     }[]) => void;
+    /** A surface opened over a modal `<dialog>` could not be made fully usable. */
+    overlayBlockedByModal?: (reason: 'hidden' | 'inert') => void;
     /**
      * When installed, a screened URL throws instead of warning-and-dropping.
      * A slot rather than a boolean so the check stays uniform with the rest.
@@ -282,17 +292,23 @@ interface DevWarningOptions {
  *
  * ## Install ordering
  *
- * Every hook except one is read at CALL time (render, reconcile, `set()`,
- * `delegate()`), so installing any time before your first `mount()` is enough.
+ * Most hooks are read at CALL time (render, reconcile, `set()`, `delegate()`).
+ * Three are decided once, when their host is CREATED, so both installation and
+ * the warning's switch must precede it:
+ *
+ *  - `signalFactory` — `signal()` picks its constructor (untracked signals).
+ *  - `wrapEffect` — `effect()` decides whether to wrap its body with the
+ *    effect-depth counter (delegate-in-effect).
+ *  - `listenerRebuild` — `mount()` decides whether to attach its
+ *    rebuilt-listeners `MutationObserver`.
  *
- * The exception is `signalFactory`: `signal()` picks its constructor when the
- * signal is CREATED. Static imports are hoisted above a top-level
- * `await import()`, so module-scope signals in imported modules are created
- * before this module runs and the untracked-signal warning will not see them.
- * To cover those, make `import 'kerfjs/dev'` the FIRST STATIC import of a
- * dev-only entry file, then load the rest of your app.
+ * Static imports are hoisted above a top-level `await import()`, so
+ * module-scope signals and effects in imported modules are created before this
+ * module runs. To cover those, make `import 'kerfjs/dev'` the FIRST STATIC
+ * import of a dev-only entry file (calling `enableWarnings()` there), then load
+ * the rest of your app.
  *
- * Opting into that warning prints this boundary once, so the gap is loud
+ * Opting into the untracked-signal warning prints its boundary once, so the gap is loud
  * rather than silent. It cannot be closed by retro-fitting existing signals:
  * `Signal.prototype`'s `value` accessor is non-configurable, and reaching live
  * instances would require a per-signal registry that production would pay for.
@@ -326,9 +342,11 @@ interface DevWarningOptions {
  * goes through `globalThis.process` into a local binding), so the environment
  * variables are unreachable there.
  *
- * Call it as early as you can. Every diagnostic reads its switch at call time
- * except the untracked-signal warning, which is chosen when a signal is
- * CREATED — enabling that one prints its coverage boundary once.
+ * Call it as early as you can. Most diagnostics read their switch at call
+ * time, but three are decided when their host is CREATED: `untrackedSignals`
+ * per `signal()`, `delegateInEffect` per `effect()`, and `rebuiltListeners` per
+ * `mount()`. A signal, effect, or mount created before this call stays
+ * uncovered. Enabling `untrackedSignals` prints its coverage boundary once.
  */
 declare function enableWarnings(options: DevWarningOptions): void;
 /**

package/dist/dev.js

@@ -1,7 +1,7 @@
-import { truncateRowHtml } from './chunk-V46JKE44.js';
-import { LIST_MARKER_PREFIX } from './chunk-GY4XV2UV.js';
-import { installDevHooks } from './chunk-HW7KSM2Y.js';
-export { clearDevHooks, devHooks, installDevHooks } from './chunk-HW7KSM2Y.js';
+import { truncateRowHtml } from './chunk-WKIPLNVO.js';
+import { LIST_MARKER_PREFIX, OVERLAY_HOST_SELECTOR, isOverlayHost } from './chunk-4TX6YJDM.js';
+import { installDevHooks } from './chunk-3C6F6NM4.js';
+export { clearDevHooks, devHooks, installDevHooks } from './chunk-3C6F6NM4.js';
 import { signal, Signal } from '@preact/signals-core';
 
 // src/dev-warn-config.ts
@@ -24,7 +24,10 @@ function applyWarningOptions(options) {
   for (const [key, value] of Object.entries(options)) {
     const envName = ENV_NAME[key];
     if (envName === void 0 || value === void 0) continue;
-    overrides.set(envName, value === false ? false : value === true ? "1" : value);
+    overrides.set(
+      envName,
+      value === false ? false : value === true ? "1" : value
+    );
   }
 }
 function devFlag(envName) {
@@ -33,6 +36,9 @@ function devFlag(envName) {
   const proc = globalThis.process;
   return proc?.env?.[envName];
 }
+function silenceHint(key) {
+  return `Silence it with enableWarnings({ ${key}: false }) from kerfjs/dev, or set ${ENV_NAME[key]}=0 (or unset it) under Node.`;
+}
 
 // src/dev-binding-warn.ts
 var warnedHoles = /* @__PURE__ */ new Set();
@@ -51,7 +57,7 @@ function maybeWarnStaleBinding(prevWired, current) {
     if (warnedHoles.has(cur.id)) continue;
     warnedHoles.add(cur.id);
     console.warn(
-      `kerf: fine-grained binding ${describeHole(cur)} switched to a different signal instance on a render whose static-surrounds HTML was byte-for-byte unchanged. On that fast path kerf keeps the original binding effect and does NOT re-bind, so this hole is now stale \u2014 it still tracks the FIRST signal instance and will not reflect the new one. Bind one computed that switches internally (e.g. class={computed(() => cond.value ? sigA.value : sigB.value)}) instead of switching which signal instance you bind (see docs/2-reactivity \xA72.9). Set KERF_DEV_WARN_STALE_BINDING=0 (or unset it) to silence this warning.`
+      `kerf: fine-grained binding ${describeHole(cur)} switched to a different signal instance on a render whose static-surrounds HTML was byte-for-byte unchanged. On that fast path kerf keeps the original binding effect and does NOT re-bind, so this hole is now stale \u2014 it still tracks the FIRST signal instance and will not reflect the new one. Bind one computed that switches internally (e.g. class={computed(() => cond.value ? sigA.value : sigB.value)}) instead of switching which signal instance you bind (see docs/2-reactivity \xA72.9). ` + silenceHint("staleBinding")
     );
   }
 }
@@ -77,7 +83,7 @@ function warnIfInsideEffect(fn) {
   if (warned) return;
   warned = true;
   console.warn(
-    `kerf: ${fn}() was called inside an effect() body. Every effect re-run installs a fresh root listener; the effect disposer cleans up the reactive subscription but not the listeners, so listener count grows linearly with signal churn and each listener pins its handler closure. Register the delegate once at module or setup scope and gate behavior on the signal *inside the handler* where the read is free. See docs/5-event-delegation.md \xA75.3 "When capturing the disposer still isn't enough". Set KERF_DEV_WARN_DELEGATE_IN_EFFECT=0 (or unset it) to silence this warning.`
+    `kerf: ${fn}() was called inside an effect() body. Every effect re-run installs a fresh root listener; the effect disposer cleans up the reactive subscription but not the listeners, so listener count grows linearly with signal churn and each listener pins its handler closure. Register the delegate once at module or setup scope and gate behavior on the signal *inside the handler* where the read is free. See docs/5-event-delegation.md \xA75.3 "When capturing the disposer still isn't enough". ` + silenceHint("delegateInEffect")
   );
 }
 
@@ -100,7 +106,7 @@ function maybeWarnEachInMorphSkip(id, liveParent, rootEl) {
   if (!hasMorphSkipAncestor(liveParent, rootEl)) return;
   warnedIds.add(id);
   console.warn(
-    `kerf: each() list '${id}' is inside a data-morph-skip subtree. The keyed reconciler still updates the list rows, but any static signal-reactive JSX inside the same skipped ancestor (e.g. <p>{count.value}</p>) is frozen \u2014 the morph never visits it. Remove data-morph-skip from any element that contains reactive JSX content and reserve it for truly library-owned hosts. Set KERF_DEV_WARN_EACH_IN_MORPH_SKIP=0 (or unset it) to silence this warning.`
+    `kerf: each() list '${id}' is inside a data-morph-skip subtree. The keyed reconciler still updates the list rows, but any static signal-reactive JSX inside the same skipped ancestor (e.g. <p>{count.value}</p>) is frozen \u2014 the morph never visits it. Remove data-morph-skip from any element that contains reactive JSX content and reserve it for truly library-owned hosts. ` + silenceHint("eachInMorphSkip")
   );
 }
 var warnedDupIds = /* @__PURE__ */ new Set();
@@ -115,7 +121,7 @@ function maybeWarnDuplicateCacheKeys(id, segItems) {
     if (seen.has(si.cacheKey)) {
       warnedDupIds.add(id);
       console.warn(
-        `kerf: each() list '${id}' has duplicate cacheKey values (duplicate: ${String(si.cacheKey)}). The cacheKey function should return a unique value per row so kerf can tell apart items for memoization \u2014 duplicate values cause some rows to return stale cached HTML when external state that affects their render changes. Set KERF_DEV_WARN_DUPLICATE_EACH_KEYS=0 (or unset it) to silence this warning.`
+        `kerf: each() list '${id}' has duplicate cacheKey values (duplicate: ${String(si.cacheKey)}). The cacheKey function should return a unique value per row so kerf can tell apart items for memoization \u2014 duplicate values cause some rows to return stale cached HTML when external state that affects their render changes. ` + silenceHint("duplicateEachKeys")
       );
       return;
     }
@@ -157,18 +163,38 @@ function findListInvariantViolations(rootEl, bindings, expectedCounts) {
     const { marker, liveParent, items } = binding;
     const expected = expectedCounts?.get(id);
     if (expected !== void 0 && items.length !== expected) {
-      problems.push(describe(id, `holds ${items.length} row(s) but its source has ${expected} \u2014 the reconcile dropped or duplicated rows`));
+      problems.push(
+        describe(
+          id,
+          `holds ${items.length} row(s) but its source has ${expected} \u2014 the reconcile dropped or duplicated rows`
+        )
+      );
     }
     if (!rootEl.contains(marker)) {
-      problems.push(describe(id, "its marker comment is no longer inside the mount root, so every future reconcile would mutate a detached tree"));
+      problems.push(
+        describe(
+          id,
+          "its marker comment is no longer inside the mount root, so every future reconcile would mutate a detached tree"
+        )
+      );
       continue;
     }
     if (marker.data !== `${LIST_MARKER_PREFIX}${id}`) {
-      problems.push(describe(id, `its marker reads '${marker.data}' \u2014 the id is carried by a different marker node, so this binding describes another list`));
+      problems.push(
+        describe(
+          id,
+          `its marker reads '${marker.data}' \u2014 the id is carried by a different marker node, so this binding describes another list`
+        )
+      );
     }
     const markerIndex = indexIn(liveParent, marker);
     if (markerIndex === -1) {
-      problems.push(describe(id, "its marker is not a child of the parent the binding records"));
+      problems.push(
+        describe(
+          id,
+          "its marker is not a child of the parent the binding records"
+        )
+      );
       continue;
     }
     let previousIndex = markerIndex;
@@ -177,28 +203,46 @@ function findListInvariantViolations(rootEl, bindings, expectedCounts) {
       const node = items[i].node;
       const index = indexIn(liveParent, node);
       if (index === -1) {
-        problems.push(describe(id, `bound row ${i} is not a child of the list's parent (<${liveParent.tagName.toLowerCase()}>)${node.isConnected ? " \u2014 it is attached elsewhere in the document" : " \u2014 it is detached"}`));
+        problems.push(
+          describe(
+            id,
+            `bound row ${i} is not a child of the list's parent (<${liveParent.tagName.toLowerCase()}>)${node.isConnected ? " \u2014 it is attached elsewhere in the document" : " \u2014 it is detached"}`
+          )
+        );
         continue;
       }
       if (index <= previousIndex) {
-        problems.push(describe(id, `bound row ${i} appears at child position ${index}, which is not after the previous one (${previousIndex}) \u2014 the rows are out of order or have crossed the marker`));
+        problems.push(
+          describe(
+            id,
+            `bound row ${i} appears at child position ${index}, which is not after the previous one (${previousIndex}) \u2014 the rows are out of order or have crossed the marker`
+          )
+        );
       }
       previousIndex = index;
       if (first === -1) first = index;
       const owner = owners.get(node);
       if (owner !== void 0) {
-        problems.push(describe(id, `bound row ${i} is also claimed by list '${owner}'`));
+        problems.push(
+          describe(id, `bound row ${i} is also claimed by list '${owner}'`)
+        );
       } else {
         owners.set(node, id);
       }
     }
-    if (first !== -1) spans.push({ id, parent: liveParent, from: first, to: previousIndex });
+    if (first !== -1)
+      spans.push({ id, parent: liveParent, from: first, to: previousIndex });
   }
   for (let a = 0; a < spans.length; a++) {
     for (let b = a + 1; b < spans.length; b++) {
       if (spans[a].parent !== spans[b].parent) continue;
       if (spans[a].from <= spans[b].to && spans[b].from <= spans[a].to) {
-        problems.push(describe(spans[a].id, `its rows (child positions ${spans[a].from}-${spans[a].to}) overlap those of list '${spans[b].id}' (${spans[b].from}-${spans[b].to}) in the same parent`));
+        problems.push(
+          describe(
+            spans[a].id,
+            `its rows (child positions ${spans[a].from}-${spans[a].to}) overlap those of list '${spans[b].id}' (${spans[b].from}-${spans[b].to}) in the same parent`
+          )
+        );
       }
     }
   }
@@ -207,7 +251,11 @@ function findListInvariantViolations(rootEl, bindings, expectedCounts) {
 function maybeCheckListInvariants(rootEl, bindings, expectedCounts) {
   const level = mode();
   if (level === "off") return;
-  const problems = findListInvariantViolations(rootEl, bindings, expectedCounts);
+  const problems = findListInvariantViolations(
+    rootEl,
+    bindings,
+    expectedCounts
+  );
   if (problems.length === 0) return;
   const report = `${problems.join("\n")}
 This is a kerf bug, not an application one \u2014 please report it with the markup that produced it. Set KERF_DEV_INVARIANTS=1 to warn instead of throw, or unset it to disable these checks.`;
@@ -224,7 +272,7 @@ function maybeWarnStaleIndex(id) {
   if (warnedIds2.has(id)) return;
   warnedIds2.add(id);
   console.warn(
-    `kerf: each() list '${id}' reused a memoized row at a new index this render, but its render function takes an \`index\` argument. Rows are memoized by object identity, not by position, so a reorder or an insert/remove ahead of a surviving row serves that row's cached HTML \u2014 computed at its OLD index. A numbered list, zebra striping, or an "N of M" label will silently show the wrong value. If the row output depends on the index, fold it into the memo key: each(items, render, { cacheKey: (_, i) => i }) (combine with your own key if you have one). If the index is not used in the output, ignore this. Set KERF_DEV_WARN_STALE_INDEX=0 (or unset it) to silence this warning.`
+    `kerf: each() list '${id}' reused a memoized row at a new index this render, but its render function takes an \`index\` argument. Rows are memoized by object identity, not by position, so a reorder or an insert/remove ahead of a surviving row serves that row's cached HTML \u2014 computed at its OLD index. A numbered list, zebra striping, or an "N of M" label will silently show the wrong value. If the row output depends on the index, fold it into the memo key: each(items, render, { cacheKey: (_, i) => i }) (combine with your own key if you have one). If the index is not used in the output, ignore this. ` + silenceHint("staleIndex")
   );
 }
 
@@ -245,14 +293,13 @@ function maybeWarnListRebind(id, liveParent) {
   if (warnedIds3.has(id)) return;
   warnedIds3.add(id);
   console.warn(
-    `kerf: each() list '${id}' had its container (<${liveParent.tagName.toLowerCase()}>) rebuilt by the morph this render \u2014 an ancestor's tag changed so the subtree was replaced, or a same-tag sibling positionally took the container's place. The list re-binds and repopulates automatically, but its rows were re-created from scratch: focus, scroll positions, in-progress IME composition, and any imperative listeners on the old row nodes are lost. If the rows should survive, give the LIST'S OWN container a stable id/data-key (keying the conditional sibling instead only helps when it is removed, not when it reappears) and keep the tags of the list's ancestors stable across renders. Set KERF_DEV_WARN_LIST_REBIND=0 (or unset it) to silence this warning.`
+    `kerf: each() list '${id}' had its container (<${liveParent.tagName.toLowerCase()}>) rebuilt by the morph this render \u2014 an ancestor's tag changed so the subtree was replaced, or a same-tag sibling positionally took the container's place. The list re-binds and repopulates automatically, but its rows were re-created from scratch: focus, scroll positions, in-progress IME composition, and any imperative listeners on the old row nodes are lost. If the rows should survive, give the LIST'S OWN container a stable id/data-key (keying the conditional sibling instead only helps when it is removed, not when it reappears) and keep the tags of the list's ancestors stable across renders. ` + silenceHint("listRebind")
   );
 }
 
 // src/dev-listener-warn.ts
 var LISTENER_MARKER = /* @__PURE__ */ Symbol.for("kerfjs.devListener");
 var patched = false;
-var warned2 = false;
 function isOptedIn5() {
   return devFlag("KERF_DEV_WARN_REBUILT_LISTENERS") === "1";
 }
@@ -277,33 +324,38 @@ function patchAddEventListenerOnce() {
   };
 }
 function hasMarkedListener(el) {
-  if (el[LISTENER_MARKER] === true) return true;
-  const stack = [];
-  for (let i = 0; i < el.children.length; i++) stack.push(el.children[i]);
+  const stack = [el];
   while (stack.length > 0) {
     const cur = stack.pop();
-    if (cur[LISTENER_MARKER] === true) return true;
+    if (cur[LISTENER_MARKER] === true)
+      return true;
+    if (isOverlayHost(cur)) continue;
     for (let i = 0; i < cur.children.length; i++) stack.push(cur.children[i]);
   }
   return false;
 }
+function insideHostSlot(target, rootEl) {
+  const host = target.closest(OVERLAY_HOST_SELECTOR);
+  return host !== null && host !== rootEl && rootEl.contains(host);
+}
 function emitWarning() {
-  if (warned2) return;
-  warned2 = true;
   console.warn(
-    "kerf: a node inside a mount()-managed tree was removed/rebuilt while carrying an imperative addEventListener listener. The listener is gone with the old node. Use `delegate(rootEl, 'click', '[data-action=\"...\"]', handler)` so the listener lives on a stable ancestor and survives re-renders, or wrap the host in `data-morph-skip` if the subtree is library-owned (Monaco, xterm, D3 charts). Set KERF_DEV_WARN_REBUILT_LISTENERS=0 (or unset it) to silence this warning."
+    "kerf: a node inside a mount()-managed tree was removed/rebuilt while carrying an imperative addEventListener listener. The listener is gone with the old node. Use `delegate(rootEl, 'click', '[data-action=\"...\"]', handler)` so the listener lives on a stable ancestor and survives re-renders, or wrap the host in `data-morph-skip` if the subtree is library-owned (Monaco, xterm, D3 charts). " + silenceHint("rebuiltListeners")
   );
 }
 function installListenerRebuildWarn(rootEl) {
   if (!isOptedIn5()) return null;
   patchAddEventListenerOnce();
+  let warned3 = false;
   const observer = new MutationObserver((mutations) => {
-    if (warned2) return;
+    if (warned3) return;
     for (const m of mutations) {
+      if (insideHostSlot(m.target, rootEl)) continue;
       for (let i = 0; i < m.removedNodes.length; i++) {
         const removed = m.removedNodes[i];
         if (!(removed instanceof Element)) continue;
         if (hasMarkedListener(removed)) {
+          warned3 = true;
           emitWarning();
           return;
         }
@@ -314,6 +366,18 @@ function installListenerRebuildWarn(rootEl) {
   return observer;
 }
 
+// src/dev-overlay-warn.ts
+var warned2 = /* @__PURE__ */ new Set();
+var MESSAGES = {
+  hidden: "kerf overlay(): a surface was opened while a modal <dialog> is open, and this engine lacks the <dialog>.showModal() / Popover API needed to lift it into the top layer. It renders beneath the dialog and is inert, so the user can neither see nor use it. Render the content inside the dialog's own markup, or open the dialog without `native: true`.",
+  inert: "kerf overlay(): a non-modal surface opened while a modal <dialog> is open was lifted into the top layer so it is visible, but browsers keep everything outside a modal dialog inert \u2014 its focusable controls cannot be focused or clicked. Anchor the popover inside the dialog and give the dialog a `data-kerf-overlay-host` element (dialogs kerf opens get one automatically), or pass a `container` inside the dialog."
+};
+function maybeWarnOverlayBlockedByModal(reason) {
+  if (warned2.has(reason)) return;
+  warned2.add(reason);
+  console.warn(MESSAGES[reason]);
+}
+
 // src/dev-parser-repair-warn.ts
 var BLOCK_TAGS = [
   "address",
@@ -378,7 +442,7 @@ function maybeWarnParserRepair(html) {
   if (warnedPairs.has(pair)) return;
   warnedPairs.add(pair);
   console.warn(
-    `kerf: a <${tag}> inside a <p> will not survive parsing. <p> may contain only phrasing content, so the HTML parser closes it before a block-level child \u2014 your <p> ends up EMPTY and the <${tag}> (plus everything after it) becomes its sibling instead of its child. kerf then reconciles that repaired tree correctly, so updates still work; what you lose is the structure you wrote, along with any CSS or querySelector that assumed it. Use a <div> (or a phrasing element like <span>) in place of the <p>, or move the block content outside it. Set KERF_DEV_WARN_PARSER_REPAIR=0 (or unset it) to silence this warning.`
+    `kerf: a <${tag}> inside a <p> will not survive parsing. <p> may contain only phrasing content, so the HTML parser closes it before a block-level child \u2014 your <p> ends up EMPTY and the <${tag}> (plus everything after it) becomes its sibling instead of its child. kerf then reconciles that repaired tree correctly, so updates still work; what you lose is the structure you wrote, along with any CSS or querySelector that assumed it. Use a <div> (or a phrasing element like <span>) in place of the <p>, or move the block content outside it. ` + silenceHint("parserRepair")
   );
 }
 
@@ -417,7 +481,7 @@ function maybeWarnValueOnlyRerender(prevHtml, nextHtml, ctx) {
   if (!_isValueOnlyDiff(a.content, b.content)) return;
   ctx.warned = true;
   console.warn(
-    "kerf: this re-render changed only text content and attribute values \u2014 no structural change \u2014 so every changed hole could be a fine-grained binding instead. Values bind, structure re-renders: pass the signal/computed itself ({count}, class={sig}) rather than reading .value in the hole, and each change updates just that node with no render re-run (a mount whose render reads no .value never re-renders at all). See docs/2-reactivity \xA72.9. Set KERF_DEV_WARN_VALUE_ONLY_RERENDER=0 (or unset it) to silence this warning."
+    "kerf: this re-render changed only text content and attribute values \u2014 no structural change \u2014 so every changed hole could be a fine-grained binding instead. Values bind, structure re-renders: pass the signal/computed itself ({count}, class={sig}) rather than reading .value in the hole, and each change updates just that node with no render re-run (a mount whose render reads no .value never re-renders at all). See docs/2-reactivity \xA72.9. " + silenceHint("valueOnlyRerender")
   );
 }
 
@@ -430,7 +494,7 @@ function maybeWarnMissingRowKey(rowEl, rowHtml, binding) {
     `kerf each(): the first row has no \`id\` or \`data-key\` attribute. Without one, rows match positionally \u2014 an insert/remove at the head shifts every row's identity, so focused inputs jump to the wrong row, mid-edit textareas swap content with their neighbor, and any per-row state silently follows the wrong item. Add \`data-key={item.id}\` (or set \`id\`) to the top-level element returned by the row render. Row HTML: ${JSON.stringify(truncateRowHtml(rowHtml))}`
   );
 }
-var WARNING_MESSAGE = "kerf: signal was written but has no subscribers. Did you read `.value` outside of a render fn / effect()? Hoisted reads do not subscribe, so subsequent writes will not re-render. Move the read inside mount()'s render fn or effect() callback. Set KERF_DEV_WARN_UNTRACKED_SIGNALS=0 (or unset it) to silence this warning.";
+var WARNING_MESSAGE = "kerf: signal was written but has no subscribers. Did you read `.value` outside of a render fn / effect()? Hoisted reads do not subscribe, so subsequent writes will not re-render. Move the read inside mount()'s render fn or effect() callback. " + silenceHint("untrackedSignals");
 var DevSignal = class extends Signal {
   __hasSubscriber = false;
   __warned = false;
@@ -462,13 +526,13 @@ function noteUntrackedCoverage() {
   if (coverageNoticeShown) return;
   coverageNoticeShown = true;
   console.warn(
-    "kerf: KERF_DEV_WARN_UNTRACKED_SIGNALS only covers signals created AFTER kerfjs/dev is installed. Static imports are hoisted above `await import('kerfjs/dev')`, so module-scope signals in the modules you import are created first and this warning cannot see them \u2014 you may get no warnings even where the bug exists. To cover them, make `import 'kerfjs/dev'` the FIRST STATIC import of a dev-only entry file (static imports evaluate in order), then load the rest of your app. Set KERF_DEV_WARN_UNTRACKED_SIGNALS=0 (or unset it) to silence this warning."
+    "kerf: KERF_DEV_WARN_UNTRACKED_SIGNALS only covers signals created AFTER kerfjs/dev is installed. Static imports are hoisted above `await import('kerfjs/dev')`, so module-scope signals in the modules you import are created first and this warning cannot see them \u2014 you may get no warnings even where the bug exists. To cover them, make `import 'kerfjs/dev'` the FIRST STATIC import of a dev-only entry file (static imports evaluate in order), then load the rest of your app. " + silenceHint("untrackedSignals")
   );
 }
 
 // src/dev-store-warn.ts
 var WARNING_PREFIX = "kerf: defineStore.set() called with keys missing from the current state \u2014 ";
-var WARNING_SUFFIX = ". set() REPLACES state; the missing keys will be undefined after this call. Use `set({ ...get(), ...next })` to merge instead, or update each call site to pass the full state. Set KERF_DEV_WARN_NARROW_SET=0 (or unset it) to silence this warning.";
+var WARNING_SUFFIX = ". set() REPLACES state; the missing keys will be undefined after this call. Use `set({ ...get(), ...next })` to merge instead, or update each call site to pass the full state. " + silenceHint("narrowSet");
 function isOptedIn8() {
   return devFlag("KERF_DEV_WARN_NARROW_SET") === "1";
 }
@@ -594,6 +658,8 @@ var DEV_HOOKS = {
   staleIndexEnabled: isOptedInStaleIndex,
   staleIndex: maybeWarnStaleIndex,
   duplicateCacheKeys: maybeWarnDuplicateCacheKeys,
+  // --- overlay ----------------------------------------------------------
+  overlayBlockedByModal: maybeWarnOverlayBlockedByModal,
   // --- urlScreen --------------------------------------------------------
   urlScreenThrow: (message) => {
     throw new Error(message);