@jsenv/navi 0.29.404 → 0.29.407

package/dist/jsenv_navi.js

@@ -2,9 +2,8 @@
  * AI reading this file: read ../docs/AI_INSTRUCTIONS.md for context on
  * using @jsenv/navi as intended.
  */
-import { installImportMetaCssBuild, isSignal, getSignalType, findControlProxy, findControlRoot, isControl, findControlHost, isNumberInput, findControlProxyTargetController, findNearestControlHost, dispatchRequestSetUIState, getUIStateFromElement, getUIStateControllerById, windowHeightSignal, windowWidthSignal, visualViewportHeightSignal, visualViewportWidthSignal, getAppHeight, getAppWidth, PSEUDO_STATE_DEFAULT, PSEUDO_NAMED_STYLES_DEFAULT, initPseudoStyles, applyStyle, getParentControl, isControlRoot, readControlValue, dispatchRequestClearUIState, dispatchRequestResetUIState, findClosestControlWithAction, isEditableTarget, coarsePointerSignal, isKeyboardModality, onUIStateControllerDestroyed, getRadioSiblings, findProxyControllers, addInputEffect, findControlProxyTarget, isMatchingFocusVisible, onUIStateControllerCreated, toDomValue, PSEUDO_CLASSES, subscribeToPseudoState, resolveInputProps, smallTouchScreenSignal, timeStringToSeconds, parseTimeParts, formatTimeParts, seedDefaultValueFromSignal, minutesFromTime as minutesFromTime$1, timeFromMinutes } from "./jsenv_navi_side_effects.js";
-export { disableVirtualKeyboardOverlay, getNowHours, getNowHoursRoundedToStep, isToday } from "./jsenv_navi_side_effects.js";
-import { createPubSub, elementIsFocusable, createIterableWeakSet, getVisuallyVisibleInfo, getFirstVisuallyVisibleAncestor, getElementSignature, findEvent, createValueEffect, findFocusDelegateTarget, findFocusable, scrollIntoViewThroughScrollables, allowWheelThrough, dispatchPublicCustomEvent, resolveCSSColor, getScrollContainerSet, ELEMENT_SIZE_CHANGE, dispatchCustomEvent, findSelfOrAncestorFixedPosition, visibleRectEffect, pickPositionRelativeTo, getBorderSizes, getPaddingSizes, applyNewPosition, measureLongestVisualLineWidth, dispatchInternalCustomEvent, chainEvent, keepTouchRefusable, isPressDrivenClick, waitForTap, waitForPressHeld, suppressClickAfterGesture, startDragToTravel, dragSourceThatStoodDown, markDragSource, refuseDragTo, startDragTo, installPanZoom, createInternalCustomEvent, getKeyboardEventDefaultAction, activeElementSignal, normalizeStyle, mergeOneStyle, getPositionedParent, normalizeStyles, createGroupTransitionController, getBorderRadius, preventIntermediateScrollbar, createOpacityTransition, getScrollContainer, watchWheelTravel, scrollRoomTowards, isTouchDrivenEvent, scrollIntoViewScoped, closestOpenableAncestor, isAncestorOpen, isDisplayedDespiteClosedAncestor, observeAncestorOpenState, getAncestorOpenType, findBefore, findAfter, resolveCSSSize, hasCSSSizeUnit, releaseWheelGesture, getScrollIntoViewScopedOffsets, wheelGestureIsTakenFrom, claimWheelGesture, initFocusGroup, stringifyStyle as stringifyStyle$1, isScrollable, resolveOklchLightness, contrastColor, trapScrollInside, parsePositionArea, snapToPixel, trapFocusInside, onAncestorReopen, isPressDisputedByDrag, canScroll, measureWidestChildRow, performTabNavigation, dragAfterIntent, stickyAsRelativeCoords, createDragToMoveGestureController, getDropTargetInfo, setStyles, useActiveElement } from "@jsenv/dom";
+import { installImportMetaCssBuild, windowHeightSignal, windowWidthSignal, visualViewportHeightSignal, visualViewportWidthSignal, getAppHeight, getAppWidth, coarsePointerSignal, smallTouchScreenSignal } from "./jsenv_navi_side_effects.js";
+import { createPubSub, elementIsFocusable, createIterableWeakSet, dispatchInternalCustomEvent, dispatchCustomEvent, getVisuallyVisibleInfo, getFirstVisuallyVisibleAncestor, getElementSignature, findEvent, createValueEffect, findFocusDelegateTarget, findFocusable, scrollIntoViewThroughScrollables, allowWheelThrough, dispatchPublicCustomEvent, resolveCSSColor, getScrollContainerSet, ELEMENT_SIZE_CHANGE, findSelfOrAncestorFixedPosition, visibleRectEffect, pickPositionRelativeTo, getBorderSizes, getPaddingSizes, applyNewPosition, measureLongestVisualLineWidth, chainEvent, keepTouchRefusable, isPressDrivenClick, waitForTap, waitForPressHeld, suppressClickAfterGesture, startDragToTravel, dragSourceThatStoodDown, markDragSource, refuseDragTo, startDragTo, installPanZoom, createInternalCustomEvent, getKeyboardEventDefaultAction, activeElementSignal, normalizeStyle, mergeOneStyle, getPositionedParent, normalizeStyles, createGroupTransitionController, getBorderRadius, preventIntermediateScrollbar, createOpacityTransition, getScrollContainer, watchWheelTravel, scrollRoomTowards, isTouchDrivenEvent, scrollIntoViewScoped, closestOpenableAncestor, isAncestorOpen, isDisplayedDespiteClosedAncestor, observeAncestorOpenState, getAncestorOpenType, findBefore, findAfter, resolveCSSSize, hasCSSSizeUnit, releaseWheelGesture, getScrollIntoViewScopedOffsets, wheelGestureIsTakenFrom, claimWheelGesture, initFocusGroup, stringifyStyle as stringifyStyle$1, isScrollable, resolveOklchLightness, contrastColor, trapScrollInside, parsePositionArea, snapToPixel, trapFocusInside, onAncestorReopen, isPressDisputedByDrag, canScroll, measureWidestChildRow, performTabNavigation, dragAfterIntent, stickyAsRelativeCoords, createDragToMoveGestureController, getDropTargetInfo, setStyles, useActiveElement, setVirtualKeyboardOverlaysContent, subscribeVirtualKeyboardGeometryChange, getVirtualKeyboardOverlayHeight } from "@jsenv/dom";
 export { chainEvent, clickIsSuppressed, contrastColor, createDragGestureController, dragAfterIntent, findEvent, markDragSource, startDragTo } from "@jsenv/dom";
 import { signal, computed, effect, untracked, batch, useComputed, useSignal } from "@preact/signals";
 import { options, isValidElement, createContext, render, h, toChildArray, cloneElement, createElement, Fragment as Fragment$1 } from "preact";
@@ -12,7 +11,7 @@ import { useErrorBoundary, useLayoutEffect, useContext, useCallback, useRef, use
 import { humanizeI18n, setRuntimeLangSource, formatDuration, formatMonth, formatDay, resolveTimeRangePrecision, formatDatePlaceholder, toDate, getRelativeDay, formatDayRelative, formatMonthPlaceholder, formatWeekPlaceholder, formatDatetimePlaceholder, formatDatetime, toTimeOfDay, formatTimeOfDay, formatTime, formatMinuteDuration, formatSecondDuration, formatHourDuration, formatTimeRelative, formatNumber, interpolateText, installInterpolateJsx } from "@jsenv/humanize";
 export { createI18n, formatDatetime, formatDay, formatDayRelative, formatDuration, formatHourDuration, formatMinuteDuration, formatMonth, formatNumber, formatSecondDuration, formatTime, formatTimeOfDay, formatTimeRange, formatTimeRelative, interpolateText } from "@jsenv/humanize";
 import { jsxs, jsx, Fragment } from "preact/jsx-runtime";
-import { TYPE_RULE, durationContainsNaN, compareTwoDurations, durationToSeconds, DISPLAYABLE_RULE, MAX_LINE_BREAKS_RULE, NO_EMOJI_RULE, SINGLE_SPACE_RULE, createValidity, resolveCharClass, getCharClassMessageKey, compileCharClassAnchored, compileCharClass, parseDuration, durationToISOString } from "@jsenv/validity";
+import { CHAR_CLASS_PRESETS, TYPE_RULE, durationContainsNaN, compareTwoDurations, durationToSeconds, DISPLAYABLE_RULE, MAX_LINE_BREAKS_RULE, NO_EMOJI_RULE, SINGLE_SPACE_RULE, createValidity, resolveCharClass, getCharClassMessageKey, compileCharClassAnchored, compileCharClass, parseDuration, durationToISOString } from "@jsenv/validity";
 export { compareTwoDurations, durationContainsNaN, durationToHours, durationToISOString, durationToMinutes, durationToNumber, durationToSeconds, durationToString, parseDuration } from "@jsenv/validity";
 import { Suspense, createPortal, forwardRef } from "preact/compat";
 
@@ -1577,6 +1576,27 @@ naviI18n.addAll({
   },
 });
 
+const isSignal = (value) => {
+  return getSignalType(value) !== null;
+};
+
+const BRAND_SYMBOL = Symbol.for("preact-signals");
+const getSignalType = (value) => {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  if (value.brand !== BRAND_SYMBOL) {
+    return null;
+  }
+
+  if (typeof value._fn === "function") {
+    return "computed";
+  }
+
+  return "signal";
+};
+
 /*
  * The network policy: one declaration saying whether a request may go out,
  * read by the action layer rather than by every callback.
@@ -4736,6 +4756,1118 @@ const actionRunEffect = (
   return actionRunnedByThisEffect;
 };
 
+/**
+ * DOM utilities for navigating the control element hierarchy.
+ *
+ * A control is a self-contained interactive widget. Its DOM structure can be
+ * either flat (host only) or layered (wrapper + host):
+ *
+ * Flat — the element is both the root and the host:
+ * ```html
+ * <button navi-control navi-control-host>Click me</button>
+ * ```
+ *
+ * Layered — a visual wrapper surrounds a native input that is the real host:
+ * ```html
+ * <span navi-control>           ← wrapper: root of the control's DOM subtree
+ *   <input navi-control-host /> ← host: holds controlProps, value, UI state, constraints
+ * </span>
+ * ```
+ *
+ * Attribute roles:
+ *  - `navi-control`           boolean, on the wrapper/root; marks the control boundary
+ *  - `navi-control-host`      boolean, on the host; set automatically by `useInteractiveProps`
+ *
+ * See control_proxy.js for the `navi-control-proxy-for` pattern.
+ */
+
+/**
+ * Returns the host element inside `el` — the element that holds the control's
+ * value, UI state, and constraints (i.e. the element onto which
+ * `useInteractiveProps` spreads `controlProps` and its event handlers).
+ *
+ * Returns `null` when `el` is itself the host (no separate wrapper).
+ */
+const findControlHost = (el) => {
+  if (el.hasAttribute("navi-control-host")) {
+    return el;
+  }
+  return el.querySelector("[navi-control-host]");
+};
+/**
+ * The control this element belongs to, wherever it sits relative to it.
+ *
+ * `findControlHost` above answers for a control's own DOM (itself, or the native
+ * element it wraps). This one is for something that is not part of a control but
+ * has to reach one — an interaction declared on a box (see
+ * interaction/interactions.js), which may be the control, may sit inside it, or
+ * may be a wrapper around exactly one. Nearest wins in that order, and the answer
+ * is null when there is no control the box belongs to: not every box lives in
+ * one, and a box laying out several controls (a row of badges, a toolbar) is
+ * held by none of them — its interactions are its own, and a press on its empty
+ * part is not a press on the first control it happens to contain.
+ */
+const findNearestControlHost = (el) => {
+  // Itself, then upwards — the box is inside a button, or is one.
+  const selfOrAncestor = el.closest("[navi-control-host]");
+  if (selfOrAncestor) {
+    return selfOrAncestor;
+  }
+  // …then downwards, only when the box wraps a single control. Counted by
+  // control, not by host: a picker holds the hosts of its popup content, and a
+  // box around that one picker is still around one control.
+  let single = null;
+  for (const host of el.querySelectorAll("[navi-control-host]")) {
+    const controlRoot = host.closest("[navi-control]") || host;
+    const controlAbove = controlRoot.parentElement.closest("[navi-control]");
+    if (controlAbove && el.contains(controlAbove)) {
+      continue;
+    }
+    if (single && single !== controlRoot) {
+      return null;
+    }
+    single = controlRoot;
+  }
+  return single ? findControlHost(single) : null;
+};
+const isControlRoot = (el) => {
+  return el.hasAttribute("navi-control");
+};
+const isControlHost = (el) => {
+  return el.hasAttribute("navi-control-host");
+};
+const isControl = (el) => {
+  return isControlRoot(el) || isControlHost(el);
+};
+
+/**
+ * Returns the nearest ancestor of `el` (exclusive of `el`'s own control) that
+ * has a `[data-action]` attribute.
+ *
+ * The search walks up `parentElement` manually (rather than using `.closest()`)
+ * so it can stop at hard boundaries.
+ *
+ * **`[navi-control="picker"]` boundary**: a picker is a hard stop for what is
+ * inside its popup. Elements in there can reach the picker itself, but nothing
+ * above it — an input inside a picker must not submit the form around it. The
+ * picker's own trigger is not inside it: a picker pressed as a whole (a confirm
+ * picker sending the form around it, see picker_confirm.jsx) stands in that
+ * form like any control there, and reaches it.
+ *
+ * ```html
+ * <form data-action="outer">              ← found from the picker's own input,
+ *   <button navi-control="picker" data-action="p">  NOT from inside its popup
+ *     <input navi-control-host />         ← el (the picker's own input)
+ *     <div popover data-picker-content>
+ *       <input navi-control-host />       ← el (in picker popover): stops at the picker
+ *     </div>
+ *   </button>
+ * </form>
+ * ```
+ */
+const findClosestControlWithAction = (el) => {
+  let current = el;
+  while (current) {
+    if (current.hasAttribute("data-action")) {
+      return current;
+    }
+    if (isPickerBoundaryFor(current, el)) {
+      return undefined;
+    }
+    current = current.parentElement;
+  }
+  return undefined;
+};
+const isPickerBoundaryFor = (candidate, el) => {
+  if (candidate.getAttribute("navi-control") !== "picker") {
+    return false;
+  }
+  const content = el.closest("[data-picker-content]");
+  return Boolean(content) && candidate.contains(content);
+};
+
+/**
+ * Returns the closest ancestor control element of `el` — i.e. the nearest
+ * `[navi-control]` element that is not the control `el` belongs to.
+ *
+ * `navi-control` is only on wrapper elements, never on hosts. So
+ * `el.closest("[navi-control]")` from a host returns that host's own wrapper,
+ * and one more `.parentNode.closest("[navi-control]")` reaches a true ancestor:
+ *
+ * ```html
+ * <button navi-control>              ← outer control  (returned)
+ *   <span navi-control>              ← inner wrapper  (skipped via parentNode)
+ *     <input navi-control-host />    ← el
+ *   </span>
+ * </button>
+ * ```
+ */
+const getParentControl = (el) => {
+  const ownControlRoot = el.closest("[navi-control]");
+  const parentControlRoot = ownControlRoot.parentNode.closest("[navi-control]");
+  return parentControlRoot;
+};
+
+/**
+ * Returns the root element of the control that `el` belongs to, or `null` if
+ * `el` is not part of a control.
+ *
+ * Use this when you have an element that may be a host (inner input) and need
+ * the visual boundary of its control — e.g. to anchor a callout, track
+ * mousedown interactions, or measure the control's bounding box.
+ */
+const findControlRoot = (el) => {
+  if (el.hasAttribute("navi-control")) {
+    return el;
+  }
+  if (el.hasAttribute("navi-control-host")) {
+    return el.closest("[navi-control]");
+  }
+  return null;
+};
+
+/**
+ * Parses a time string into seconds.
+ * Accepts:
+ *   - number: returned as-is (already in seconds)
+ *   - "HH:MM" string: converted to seconds (e.g. "00:30" → 1800, "01:00" → 3600)
+ *   - undefined/null: returned as-is
+ */
+const timeStringToSeconds = (timeString) => {
+  if (typeof timeString !== "string") {
+    return timeString;
+  }
+  const colonIndex = timeString.indexOf(":");
+  if (colonIndex === -1) {
+    return Number(timeString);
+  }
+  const hours = parseInt(timeString.slice(0, colonIndex), 10);
+  const minutes = parseInt(timeString.slice(colonIndex + 1), 10);
+  return (hours * 60 + minutes) * 60;
+};
+
+const isToday = (value) => {
+  if (!value) {
+    return false;
+  }
+  const now = new Date();
+  const todayStr = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
+  if (typeof value === "string") {
+    return value === todayStr;
+  }
+  if (typeof value === "number") {
+    const d = new Date(value);
+    const s = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+    return s === todayStr;
+  }
+  if (value instanceof Date) {
+    const s = `${value.getFullYear()}-${String(value.getMonth() + 1).padStart(2, "0")}-${String(value.getDate()).padStart(2, "0")}`;
+    return s === todayStr;
+  }
+  return false;
+};
+
+/**
+ * Returns the current time as "HH:MM", with an optional minute offset.
+ *
+ * @param {number} [offsetMinutes=0] - Minutes to add (negative = subtract).
+ *   E.g. getNowHours(-5) returns "now minus 5 minutes".
+ *
+ * @example
+ * getNowHours()       // "14:30"
+ * getNowHours(-5)     // "14:25"
+ */
+const getNowHours = (offsetMinutes = 0) => {
+  const now = new Date();
+  const totalMinutes = now.getHours() * 60 + now.getMinutes() + offsetMinutes;
+  const clamped =
+    totalMinutes < 0
+      ? 0
+      : totalMinutes > 23 * 60 + 59
+        ? 23 * 60 + 59
+        : totalMinutes;
+  const h = Math.floor(clamped / 60);
+  const m = clamped % 60;
+  return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}`;
+};
+
+/**
+ * Returns the current time rounded up to the nearest step boundary,
+ * with an optional minute offset applied first.
+ *
+ * This is useful to compute a step-aligned `min` for a time picker:
+ * passing it ensures the first available slot is always on a step boundary.
+ *
+ * @param {number} stepMinutes - Step size in minutes (e.g. 30).
+ * @param {number} [offsetMinutes=0] - Minutes to add before rounding (negative = subtract).
+ *
+ * @example
+ * // At 9:32, step 30, offset -5 → raw = 9:27 → ceil to 30 → "09:30"
+ * // At 9:38, step 30, offset -5 → raw = 9:33 → ceil to 30 → "10:00"
+ * getNowHoursRoundedToStep(30, -5)
+ */
+const getNowHoursRoundedToStep = (stepMinutes, offsetMinutes = 0) => {
+  const now = new Date();
+  const totalMinutes = now.getHours() * 60 + now.getMinutes() + offsetMinutes;
+  const aligned = Math.ceil(totalMinutes / stepMinutes) * stepMinutes;
+  const clamped =
+    aligned < 0 ? 0 : aligned > 23 * 60 + 59 ? 23 * 60 + 59 : aligned;
+  const h = Math.floor(clamped / 60);
+  const m = clamped % 60;
+  return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}`;
+};
+
+/**
+ * "HH:MM" and its two numbers, in both directions — what any control made of an
+ * hour beside a minute (fields, wheels) aggregates to and is placed from. Held
+ * as numbers, written on two digits: how they are shown is each control's own
+ * business.
+ */
+const parseTimeParts = (time) => {
+  if (typeof time !== "string") {
+    return null;
+  }
+  const match = /^(\d{1,2}):(\d{1,2})/.exec(time);
+  if (!match) {
+    return null;
+  }
+  return { hour: Number(match[1]), minute: Number(match[2]) };
+};
+
+// Half a time is not a time: a control holding one of the two and nothing in
+// the other has no value at all, and a form has nothing to send about it.
+const formatTimeParts = (hour, minute) => {
+  if (
+    hour === "" ||
+    hour === undefined ||
+    minute === "" ||
+    minute === undefined
+  ) {
+    return undefined;
+  }
+  return `${padTwo$1(hour)}:${padTwo$1(minute)}`;
+};
+
+const minutesFromTime$1 = (time) => {
+  const parts = parseTimeParts(time);
+  if (!parts) {
+    return null;
+  }
+  return parts.hour * 60 + parts.minute;
+};
+
+// Not folded back into the day: 1440 is "24:00", the end of the day a span can
+// run into.
+const timeFromMinutes = (minutes) => {
+  return `${padTwo$1(Math.floor(minutes / 60))}:${padTwo$1(minutes % 60)}`;
+};
+
+const padTwo$1 = (value) => String(value).padStart(2, "0");
+
+// What a bound signal's type says is what its VALUE is (a validity type);
+// what a control's `type` says is what the control IS. This table is the whole
+// bridge between the two vocabularies: a value type with a row here asks for
+// that control, one without a row asks for nothing and the control keeps its
+// own default. "string" has no row on purpose — it is the value every typeless
+// control already holds — and a name only one side knows must never cross as
+// is: a control type nobody implements is a plain text field that writes an
+// object as "[object Object]" (see warnOnUnknownPickerType in picker.jsx).
+// Numeric value types map to navi_number rather than the native type="number"
+// (spinner buttons, poor UX).
+const CONTROL_TYPE_BY_SIGNAL_TYPE = {
+  boolean: "checkbox",
+  number: "navi_number",
+  integer: "navi_number",
+  float: "navi_number",
+  ratio: "navi_number",
+  longitude: "navi_number",
+  latitude: "navi_number",
+  second: "navi_number",
+  minute: "navi_number",
+  hour: "navi_number",
+  year: "navi_number",
+  percentage: "navi_percentage",
+  date: "date",
+  month: "month",
+  week: "week",
+  time: "time",
+  datetime: "datetime",
+  duration: "duration",
+  color: "color",
+  email: "email",
+  url: "url",
+  array: "array",
+  object: "object",
+};
+
+// Conceptual navi types: defaults, plus the host type they resolve to.
+// `navi-input-type` keeps the type the caller asked for once the host has
+// become something plainer — it is what says the value is a number (see
+// isNumberInput), and what lets constraint messages use domain-specific
+// wording instead of the generic "Ce nombre doit être...".
+// A type a picker preset draws (navi_time, navi_minute: see picker_preset.jsx)
+// has no row: resolveInputProps runs before the preset resolver, and a row
+// would turn the type into its host before the preset resolver reads it. The
+// preset hands the host type on itself.
+const NAVI_TYPE_DEFAULTS = {
+  navi_percentage: {
+    "type": "navi_number",
+    "navi-input-type": "percentage",
+    "min": 0,
+    "max": 100,
+    "step": 1,
+  },
+  navi_number: {
+    "type": "text",
+    "navi-input-type": "number",
+    "autoCorrect": "off",
+    "spellcheck": false,
+    "autoComplete": "off",
+  },
+};
+
+// The navi input types whose value IS a number.
+const NUMBER_NAVI_INPUT_TYPE_SET = new Set([
+  "number",
+  "percentage",
+  "hour",
+  "minute",
+  "second",
+]);
+
+/**
+ * Whether the control holds a number — asked of what the control IS, never of
+ * `inputMode`. In HTML `inputmode` picks the on-screen keyboard and says
+ * nothing about the value: a licence number, a postal code or a card number
+ * with a check letter all want the digit keypad while staying strings. What a
+ * number field is spelled `type="number"`, or a navi type that resolves to a
+ * text host and leaves `navi-input-type` behind to say what it was.
+ */
+const isNumberInput = (type, naviInputType) => {
+  if (type === "number") {
+    return true;
+  }
+  return NUMBER_NAVI_INPUT_TYPE_SET.has(naviInputType);
+};
+
+/**
+ * resolveInputProps — normalizes input-related props that are shared across
+ * `<Picker>`, `<Input>` (textual) and `<Range>`. Mutates the props object in place.
+ *
+ * Normalization is applied recursively: a navi type may resolve to another navi
+ * type (e.g. `navi_percentage` → `navi_number` → `text`), and each step applies its
+ * own formatters and defaults before moving to the next.
+ *
+ * Steps applied for each type:
+ * 1. Record the original navi type in `props["navi-input-type"]` (first call only).
+ * 2. Apply defaults for the current type (min, max, step, and any other props),
+ *    only when the prop is not already set.
+ * 3. Apply min/max formatters (e.g. HH:MM string → number for duration types,
+ *    Date → formatted string for date/time types).
+ * 4. Apply step formatter (same conversion rules).
+ * 5. Remap `props.type` to the target type defined by the current type's defaults,
+ *    then recurse.
+ *
+ * Supported navi types and their targets:
+ * - `navi_percentage` → `navi_number`  (0–100, step 1)
+ * - `navi_number`     → `text`         (inputMode="numeric", no spin buttons implied)
+ *
+ * Standard HTML input types with formatters:
+ * - `date`, `month`, `week`, `time`, `datetime-local`, `datetime`:
+ *   min/max accept `Date` instances or timestamps and are converted to the
+ *   string format expected by the native input.
+ * - `time`, `datetime-local`, `datetime`:
+ *   step accepts `"HH:MM"` and is converted to seconds.
+ */
+/**
+ * A bound signal that carries a default of its own says the same thing on every
+ * control: the control starts there, uncontrolled, and a reset goes back to it.
+ * Uncontrolled here is about where the control starts, not about whether it
+ * follows the signal — the binding stays two-way either way (see
+ * stateFromSignal in control_hooks.jsx) — nor about what a form counts as
+ * held: that is the signal's content (isUIStateHeld in held_ui_state.js), and a
+ * stateSignal holds its default. Written once and used by everything
+ * that takes a `signal`, so one signal cannot mean two different things
+ * depending on which control it was handed to.
+ */
+const seedDefaultValueFromSignal = (props) => {
+  const signalOptions = props.signal?.options;
+  if (!signalOptions) {
+    return;
+  }
+  if (Object.hasOwn(props, "defaultValue")) {
+    // explicit defaultValue prop prevails
+    return;
+  }
+  // Snapshot the signal's current default so that resetUIState restores to the
+  // original default — not the value the signal had at the time of the last
+  // re-render.
+  const defaultValue = signalOptions.getDefaultValue(false);
+  if (defaultValue !== undefined) {
+    props.defaultValue = defaultValue;
+  }
+};
+
+const resolveInputProps = (props, { controlType = "input" } = {}) => {
+  // `signal` carries a bound state signal. It is left on `props` on purpose:
+  // `createControlInfo` (control_hooks.jsx) reads it to seed the state and to
+  // follow it, and `onUIAction` (ui_state_controller.js) writes user
+  // interactions back into it. Here we only derive input defaults (type/min/max,
+  // defaultValue/defaultChecked) from the signal's `options`, so the control
+  // ends up uncontrolled-with-default while still bound to the signal.
+  const signal = props.signal;
+  if (signal) {
+    const signalOptions = signal.options;
+    if (signalOptions) {
+      for (const key of ["min", "max", "step"]) {
+        if (props[key] === undefined && signalOptions[key] !== undefined) {
+          props[key] = signalOptions[key];
+        }
+      }
+      if (props.type === undefined && signalOptions.type !== undefined) {
+        const typeFromSignal = CONTROL_TYPE_BY_SIGNAL_TYPE[signalOptions.type];
+        // A value type and the control for it usually agree — a date-typed
+        // signal wants a date field — but a boolean one maps to a checkbox, and
+        // a picker made into a checkbox is not a picker with a different look:
+        // it is another control, with no popup to open. A picker asked to hold
+        // a yes/no keeps its two rows and stays itself.
+        const wouldChangeWhatTheControlIs =
+          controlType === "picker" &&
+          (typeFromSignal === "checkbox" || typeFromSignal === "radio");
+        if (typeFromSignal !== undefined && !wouldChangeWhatTheControlIs) {
+          props.type = typeFromSignal;
+        }
+      }
+    }
+
+    const isCheckable = props.type === "checkbox" || props.type === "radio";
+    if (isCheckable) {
+      if (Object.hasOwn(props, "defaultChecked")) ; else {
+        // If no explicit defaultChecked, derive it from the signal's default
+        // value so that resetUIState restores to the original default.
+        // Only a stateSignal carries a default of its own; a plain signal has
+        // no `options` at all, hence the optional read.
+        const defaultVal = signalOptions?.getDefaultValue(false);
+        if (defaultVal === undefined) ; else if (props.type === "radio") {
+          if (defaultVal === true) {
+            props.defaultChecked = true;
+          } else if (
+            Object.hasOwn(props, "value") &&
+            defaultVal === props.value
+          ) {
+            props.defaultChecked = true;
+          }
+        } else if (typeof defaultVal === "boolean") {
+          // Standalone checkbox bound to a boolean signal.
+          props.defaultChecked = defaultVal;
+        } else {
+          // Checkbox is a group member: defaultVal is the array of
+          // selected item values.
+          const checkboxValue = props.value;
+          props.defaultChecked =
+            Array.isArray(defaultVal) && defaultVal.includes(checkboxValue);
+        }
+      }
+      return;
+    }
+
+    seedDefaultValueFromSignal(props);
+  }
+
+  const currentType = props.type;
+  // Apply min/max/step formatters before anything else — this must run even for
+  // standard HTML types (date, time, etc.) that have no NAVI_TYPE_DEFAULTS entry.
+  const currentTypeMinMaxFormatter = MIN_MAX_FORMATTER_BY_TYPE[currentType];
+  const currentTypeStepFormatter = STEP_FORMATTER_BY_TYPE[currentType];
+  if (currentTypeMinMaxFormatter) {
+    props.min = currentTypeMinMaxFormatter(props.min);
+    props.max = currentTypeMinMaxFormatter(props.max);
+  }
+  if (currentTypeStepFormatter) {
+    props.step = currentTypeStepFormatter(props.step);
+  }
+
+  // For navi_number: choose inputMode based on whether step/min/max suggest decimals.
+  // inputMode="numeric" (integer keyboard) vs "decimal" (keyboard with decimal separator).
+  if (currentType === "navi_number") {
+    if (props.inputMode === undefined) {
+      props.inputMode =
+        hasDecimalPlaces(props.step) ||
+        hasDecimalPlaces(props.min) ||
+        hasDecimalPlaces(props.max)
+          ? "decimal"
+          : "numeric";
+    }
+  }
+
+  const { charGuard } = props;
+  if (charGuard) {
+    if (charGuard === true || charGuard === "auto") {
+      // Auto-resolve charGuard from context.
+      let charGuardResolved;
+      const inputMode = props.inputMode;
+      if (inputMode === "numeric") {
+        charGuardResolved = "numeric";
+      } else if (inputMode === "decimal") {
+        charGuardResolved = "decimal";
+      } else if (currentType === "tel") {
+        charGuardResolved = "tel";
+      } else if (currentType === "email") {
+        charGuardResolved = "email";
+      }
+      if (charGuardResolved !== undefined) {
+        props.charGuard = charGuardResolved;
+      }
+    }
+    // charGuard is now resolved: derive inputMode from it if not already set.
+    if (props.inputMode === undefined && props.charGuard) {
+      const autoMode = INPUT_MODE_FROM_CHAR_GUARD[props.charGuard];
+      if (autoMode) {
+        props.inputMode = autoMode;
+      }
+    }
+    // Build pattern from the resolved charGuard (preset name → class, or raw class passthrough).
+    if (props.pattern === undefined && props.charGuard) {
+      const charClass = CHAR_CLASS_PRESETS[props.charGuard] ?? props.charGuard;
+      props.pattern = `${charClass}*`;
+    }
+  }
+
+  // Compute maxLength from max when inputMode is numeric/decimal.
+  // Done here (after inputMode is set) so controller.props has the resolved value.
+  if (props.maxLength === undefined) {
+    if (props.inputMode === "numeric") {
+      const { min, max } = props;
+      if (max === undefined) ; else {
+        const canBeNegative = min === undefined ? max < 0 : min < 0;
+        const signCharCount = canBeNegative ? 1 : 0;
+        const integerDigitCount = String(Math.floor(Math.abs(max))).length;
+        props.maxLength = signCharCount + integerDigitCount;
+      }
+    } else if (props.inputMode === "decimal") {
+      const { min, max, step } = props;
+      if (max === undefined) ; else if (step === undefined) ; else {
+        const canBeNegative = min === undefined ? max < 0 : min < 0;
+        const signCharCount = canBeNegative ? 1 : 0;
+        const integerDigitCount = String(Math.floor(Math.abs(max))).length;
+        const stepStr = String(step);
+        const dotIndex = stepStr.indexOf(".");
+        // integer step + decimal inputMode is an unusual combo, but we stay consistent:
+        // no decimal part in maxLength since valid values are whole numbers anyway
+        const isIntegerStep = dotIndex === -1;
+        const decimalSignCharCount = isIntegerStep ? 0 : 1;
+        const decimalDigitCount = isIntegerStep
+          ? 0
+          : stepStr.length - dotIndex - 1;
+        props.maxLength =
+          signCharCount +
+          integerDigitCount +
+          decimalSignCharCount +
+          decimalDigitCount;
+      }
+    }
+  }
+
+  // Resolve maxLengthGuard boolean/auto → the computed maxLength number.
+  if (props.maxLengthGuard === true || props.maxLengthGuard === "auto") {
+    props.maxLengthGuard =
+      typeof props.maxLength === "number" ? props.maxLength : undefined;
+  }
+
+  const currentTypeDefaults = NAVI_TYPE_DEFAULTS[currentType];
+  if (!currentTypeDefaults) {
+    return;
+  }
+
+  for (const key of Object.keys(currentTypeDefaults)) {
+    if (props[key] === undefined) {
+      props[key] = currentTypeDefaults[key];
+    }
+  }
+  const targetType = currentTypeDefaults.type;
+  props.type = targetType;
+  resolveInputProps(props);
+};
+
+// Presets that imply a specific mobile keyboard inputMode.
+const INPUT_MODE_FROM_CHAR_GUARD = {
+  numeric: "numeric",
+  pin: "numeric",
+  card: "numeric",
+  tel: "tel",
+  decimal: "decimal",
+};
+
+const normalizeToDate = (value) => {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  if (typeof value === "number") {
+    return new Date(value);
+  }
+  if (value instanceof Date) {
+    return value;
+  }
+  return null;
+};
+
+const toInputDate = (value) => {
+  const date = normalizeToDate(value);
+  if (!date) {
+    return value;
+  }
+  const yyyy = date.getFullYear();
+  const mm = String(date.getMonth() + 1).padStart(2, "0");
+  const dd = String(date.getDate()).padStart(2, "0");
+  return `${yyyy}-${mm}-${dd}`;
+};
+const toInputMonth = (value) => {
+  const date = normalizeToDate(value);
+  if (!date) {
+    return value;
+  }
+  const yyyy = date.getFullYear();
+  const mm = String(date.getMonth() + 1).padStart(2, "0");
+  return `${yyyy}-${mm}`;
+};
+const toInputWeek = (value) => {
+  const date = normalizeToDate(value);
+  if (!date) {
+    return value;
+  }
+  // ISO week number
+  const d = new Date(date);
+  d.setHours(0, 0, 0, 0);
+  d.setDate(d.getDate() + 3 - ((d.getDay() + 6) % 7));
+  const yearStart = new Date(d.getFullYear(), 0, 4);
+  const week =
+    Math.round(
+      ((d - yearStart) / 86400000 - 3 + ((yearStart.getDay() + 6) % 7)) / 7,
+    ) + 1;
+  return `${d.getFullYear()}-W${String(week).padStart(2, "0")}`;
+};
+const toInputTime = (value) => {
+  const date = normalizeToDate(value);
+  if (!date) {
+    return value;
+  }
+  const hh = String(date.getHours()).padStart(2, "0");
+  const mm = String(date.getMinutes()).padStart(2, "0");
+  return `${hh}:${mm}`;
+};
+const toInputDatetime = (value) => {
+  const date = normalizeToDate(value);
+  if (!date) {
+    return value;
+  }
+  const yyyy = date.getFullYear();
+  const mm = String(date.getMonth() + 1).padStart(2, "0");
+  const dd = String(date.getDate()).padStart(2, "0");
+  const hh = String(date.getHours()).padStart(2, "0");
+  const min = String(date.getMinutes()).padStart(2, "0");
+  return `${yyyy}-${mm}-${dd}T${hh}:${min}`;
+};
+
+const MIN_MAX_FORMATTER_BY_TYPE = {
+  "date": toInputDate,
+  "month": toInputMonth,
+  "week": toInputWeek,
+  "time": toInputTime,
+  "datetime-local": toInputDatetime,
+  "datetime": toInputDatetime,
+};
+const STEP_FORMATTER_BY_TYPE = {
+  "time": timeStringToSeconds,
+  "datetime-local": timeStringToSeconds,
+  "datetime": timeStringToSeconds,
+};
+
+const hasDecimalPlaces = (value) => {
+  if (value === undefined || value === null) {
+    return false;
+  }
+  const num = Number(value);
+  return !isNaN(num) && !Number.isInteger(num);
+};
+
+const dispatchRequestSetUIState = (element, value, detail) => {
+  const controlHost = findControlHost(element) || element;
+  return dispatchInternalCustomEvent(controlHost, "navi_set_ui_state", {
+    ...detail,
+    value,
+  });
+};
+const dispatchRequestClearUIState = (element, e) => {
+  const controlHost = findControlHost(element) || element;
+  return dispatchInternalCustomEvent(controlHost, "navi_clear_ui_state", {
+    event: e,
+  });
+};
+const dispatchRequestResetUIState = (element, e) => {
+  const controlHost = findControlHost(element) || element;
+  return dispatchInternalCustomEvent(controlHost, "navi_reset_ui_state", {
+    event: e,
+  });
+};
+/**
+ * @param {Element} el
+ * @param {{ own?: boolean }} [options] `own`: what the element holds BY ITSELF.
+ *   Only a button ever answers differently — one with no value of its own
+ *   inherits the value of the control around it, which is what makes
+ *   `--navi-send` on a form's button be about that form. Something asking what
+ *   THIS element says (a travel command reading what the travel is about) wants
+ *   the own value and would otherwise be handed the surrounding control's.
+ */
+const getUIStateFromElement = (el, { own } = {}) => {
+  let uiState;
+  dispatchInternalCustomEvent(el, "navi_get_ui_state", {
+    own,
+    respondWith: (v) => {
+      uiState = v;
+    },
+  });
+  return uiState;
+};
+
+/**
+ * Converts a JS value into the form expected by the browser DOM property for a
+ * given control type/input type combination.
+ *
+ * For example:
+ * - `datetime-local` inputs expect a local datetime string without timezone
+ * - `number`/`range` inputs expect a numeric string or number
+ * - `color` inputs require a non-empty hex string (falls back to `#000000`)
+ * - All other inputs receive the value as-is (undefined → "")
+ *
+ * Returns either the converted value directly, or a converter function when the
+ * conversion depends on the runtime value (e.g. plain inputs return `asInputValue`).
+ *
+ * @param {any} value - The JS value to convert.
+ * @param {{ controlType: string, type: string }} options
+ * @returns {any} The DOM-compatible value or a converter function.
+ */
+const asControlHostValue = (
+  jsValue,
+  { controlType, type, naviInputType, pad },
+) => {
+  if (controlType === "select") {
+    // A select holds one of its options, always a string; holding nothing is
+    // the empty option, which the element spells "".
+    return asInputValue(jsValue);
+  }
+  if (controlType === "input" || controlType === "picker") {
+    if (type === "datetime-local") {
+      return asDatetimeLocalString(jsValue);
+    }
+    if (type === "range" || isNumberInput(type, naviInputType)) {
+      return asNumberString(jsValue, pad);
+    }
+    if (type === "color") {
+      return asColorString(jsValue);
+    }
+    return asInputValue(jsValue);
+  }
+  return jsValue;
+};
+// As explained in https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/datetime-local#setting_timezones
+// datetime-local does not support timezones
+const asDatetimeLocalString = (dateTimeString) => {
+  const date = new Date(dateTimeString);
+  if (isNaN(date.getTime())) {
+    return dateTimeString;
+  }
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  const hours = String(date.getHours()).padStart(2, "0");
+  const minutes = String(date.getMinutes()).padStart(2, "0");
+  const seconds = String(date.getSeconds()).padStart(2, "0");
+  return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}`;
+};
+// `pad` is how many digits the number is WRITTEN on — an hour is held as 7 and
+// shown as "07". Held and shown are two things here, the way they are for a
+// datetime-local above: what the field says is derived from what the control
+// holds, and reading it back (readNumberFromInput) gives the number again.
+const asNumberString = (jsValue, pad) => {
+  if (jsValue === undefined) {
+    return "";
+  }
+  if (!pad || jsValue === "" || jsValue === null) {
+    return jsValue;
+  }
+  const number = Number(jsValue);
+  if (Number.isNaN(number)) {
+    return jsValue;
+  }
+  const negative = number < 0;
+  const digits = String(negative ? -number : number).padStart(Number(pad), "0");
+  return negative ? `-${digits}` : digits;
+};
+// Browser requires a non-empty value for <input type="color">.
+// When our logical value is empty we give it #000000 so it doesn't choke.
+// The UI uses the original (possibly empty) value to show the checkerboard.
+const asColorString = (jsValue) => {
+  return jsValue || "#000000";
+};
+const asInputValue = (jsValue) => {
+  if (jsValue === undefined) {
+    return "";
+  }
+  return jsValue;
+};
+
+/**
+ * Reads the current logical JS value from a control host DOM element.
+ *
+ * Handles all navi control host element types:
+ * - `<button>` — reads via `navi_get_value` custom event, falls back to `button.value`
+ * - `<input type="number|range">` — parses as a number, returns `undefined` when empty
+ * - `<input type="checkbox|radio">` — returns `undefined` when unchecked, otherwise reads
+ *   via `navi_get_value` custom event (to preserve the original JS type of the value prop)
+ * - `<input type="datetime-local">` — converts the local datetime string to an ISO 8601 string
+ * - `<input type="navi_picker">` — delegates to the controller via `navi_get_ui_state`
+ * - All other inputs — returns `input.value` as a string
+ *
+ * @param {HTMLElement} controlHost - The control host DOM element to read from.
+ * @returns {any} The current logical value of the control.
+ */
+const readControlValue = (controlHost) => {
+  if (
+    controlHost.tagName === "BUTTON" ||
+    controlHost.getAttribute("role") === "button"
+  ) {
+    return readValueFromButton(controlHost);
+  }
+  if (controlHost.tagName === "INPUT") {
+    // important: input.type = "navi_js"; followed by input.type; returns "text"
+    // so use getAttribute
+    const type = controlHost.getAttribute("type");
+
+    if (
+      type === "range" ||
+      isNumberInput(type, controlHost.getAttribute("navi-input-type"))
+    ) {
+      return readNumberFromInput(controlHost);
+    }
+    if (type === "color") {
+      return readValueFromControlHost(controlHost);
+    }
+    if (type === "checkbox" || type === "radio") {
+      return readValueFromCheckableInput(controlHost);
+    }
+    if (type === "datetime-local") {
+      return readDatetimeLocalFromInput(controlHost);
+    }
+    if (type === "navi_js") {
+      return getUIStateFromElement(controlHost);
+    }
+    return readValueFromInput(controlHost);
+  }
+  if (controlHost.hasAttribute("navi-control-host")) {
+    // Non-button, non-input navi controls (e.g. Badge.Button rendered as span)
+    return readValueFromControlHost(controlHost);
+  }
+  return readValueFromElement(controlHost);
+};
+const readValueFromControlHost = (controlHost) => {
+  return readValueFromNaviCustomEvent(controlHost, controlHost.value);
+};
+const readValueFromButton = (button) => {
+  return readValueFromControlHost(button);
+};
+const readDatetimeLocalFromInput = (input) => {
+  const localDateTimeString = input.value;
+  if (localDateTimeString === "") {
+    return "";
+  }
+  const localDate = new Date(localDateTimeString);
+  if (isNaN(localDate.getTime())) {
+    return localDateTimeString;
+  }
+  return localDate.toISOString();
+};
+const readNumberFromInput = (input) => {
+  const numberString = input.value;
+  if (numberString === "") {
+    return "";
+  }
+  const asNumber = Number(numberString);
+  if (isNaN(asNumber)) {
+    return numberString;
+  }
+  return asNumber;
+};
+const readValueFromCheckableInput = (input) => {
+  const checked = input.checked;
+  if (!checked) {
+    return undefined;
+  }
+  return readValueFromControlHost(input);
+};
+const readValueFromInput = (input) => {
+  const value = input.value;
+  return value;
+};
+const readValueFromElement = (element) => {
+  const value = element.value;
+  return value;
+};
+const readValueFromNaviCustomEvent = (field, fallback) => {
+  // prefer the value given as prop (respect original type, browser would convert to string)
+  let responded;
+  let value;
+  dispatchCustomEvent(field, "navi_get_value", {
+    respondWith: (jsValue) => {
+      responded = true;
+      value = jsValue;
+    },
+  });
+  if (responded) {
+    return value;
+  }
+  return fallback;
+};
+
+// In-memory registry of all mounted ui state controllers keyed by their id.
+// Allows direct controller access without dispatching DOM events — used by external
+// callers (e.g. selectable_list) to call setUIState by id instead of via the DOM.
+const controllersById = new Map();
+
+// In-memory registry for radio controllers, keyed by input name.
+// Allows radio sibling unchecking without querying the DOM — necessary when
+// items are virtualized and their DOM element may not exist at the time.
+// Form scoping is reproduced by comparing parentUIStateController references.
+const radioControllersByName = new Map();
+
+// Registry for non-serializable JS values that cannot be written to DOM attributes as-is.
+// When a value is an object/array, we store it here and write a reference string to the DOM
+// instead of "[object Object]". Console-inspectable via window.__navi_js('id').
+// The controller id is used as key — if the controller has no id, the value is not registered.
+const naviJsRegistry = new Map();
+
+const getUIStateControllerById = (id) => controllersById.get(id);
+const getRadioSiblings = (radioUIStateController) => {
+  const siblings = radioControllersByName.get(radioUIStateController.name);
+  return siblings;
+};
+
+const toDomValue = (
+  jsValue,
+  { controlType, id, type, naviInputType, pad },
+) => {
+  const domValue = asControlHostValue(jsValue, {
+    controlType,
+    type,
+    naviInputType,
+    pad,
+  });
+  if (isSerializableAsDomValue(domValue)) {
+    return domValue;
+  }
+  naviJsRegistry.set(id, domValue);
+  return `window.__navi_js('${id}')`;
+};
+
+window.__navi_js = (id) => naviJsRegistry.get(id);
+const isSerializableAsDomValue = (value) => {
+  if (value === null || value === undefined) {
+    return true;
+  }
+  const type = typeof value;
+  return type === "string" || type === "number" || type === "boolean";
+};
+
+const onUIStateControllerCreated = (uiStateController) => {
+  const { id, name, controlType } = uiStateController;
+  if (id) {
+    controllersById.set(id, uiStateController);
+  }
+  const proxyFor = uiStateController.props["navi-control-proxy-for"];
+  if (proxyFor) {
+    let proxySet = proxyControllersByRealInputId.get(proxyFor);
+    if (!proxySet) {
+      proxySet = new Set();
+      proxyControllersByRealInputId.set(proxyFor, proxySet);
+    }
+    proxySet.add(uiStateController);
+  }
+  if (
+    controlType === "input" &&
+    uiStateController.props.type === "radio" &&
+    name
+  ) {
+    let set = radioControllersByName.get(name);
+    if (!set) {
+      set = new Set();
+      radioControllersByName.set(name, set);
+    }
+    set.add(uiStateController);
+  }
+};
+const onUIStateControllerDestroyed = (uiStateController) => {
+  const { id, name, controlType } = uiStateController;
+  if (id) {
+    // Only the controller the id currently points at may take the entry away:
+    // when two controls share an id, the one leaving would otherwise unregister
+    // the one staying (see the warning in onUIStateControllerCreated), and the
+    // same holds while a control is being replaced by its successor, which
+    // registers during its render, before this cleanup runs.
+    if (controllersById.get(id) === uiStateController) {
+      controllersById.delete(id);
+      naviJsRegistry.delete(id);
+    }
+  }
+  const proxyFor = uiStateController.props["navi-control-proxy-for"];
+  if (proxyFor) {
+    const proxySet = proxyControllersByRealInputId.get(proxyFor);
+    if (proxySet) {
+      proxySet.delete(uiStateController);
+      if (proxySet.size === 0) {
+        proxyControllersByRealInputId.delete(proxyFor);
+      }
+    }
+  }
+  if (
+    controlType === "input" &&
+    uiStateController.controlHostProps.type === "radio" &&
+    name
+  ) {
+    const set = radioControllersByName.get(name);
+    if (set) {
+      set.delete(uiStateController);
+      if (set.size === 0) {
+        radioControllersByName.delete(name);
+      }
+    }
+  }
+};
+
+/**
+ * Controller-based equivalent of findControlProxyTarget.
+ * Given a proxy controller, returns the real control's controller.
+ * Finds the target by walking the parent controller's children — no DOM queries.
+ * Returns `null` when the controller is not a proxy or the target is not found.
+ */
+const findControlProxyTargetController = (controller) => {
+  const proxyFor = controller.controlHostProps["navi-control-proxy-for"];
+  if (!proxyFor) {
+    return null;
+  }
+  return getUIStateControllerById(proxyFor) ?? null;
+};
+
+// Reverse-lookup map: real-input id → the proxy controllers that reference it
+// via `navi-control-proxy-for`. A single control can be represented by several
+// proxies (an "enable"/"disable" button pair for one radio, for instance), so
+// each id holds a set. Maintained on create/destroy so lookup is O(1).
+const proxyControllersByRealInputId = new Map();
+const findProxyControllers = (realInputId) => {
+  if (!realInputId) {
+    return null;
+  }
+  return proxyControllersByRealInputId.get(realInputId) ?? null;
+};
+
 /**
  * The attributes constraints read, filled by each constraint module as it
  * evaluates. A constraint declares the attribute it wants (`"data-no-emoji"`)
@@ -5364,6 +6496,113 @@ const isInertOnClick = (element) => {
   return true;
 };
 
+/**
+ * DOM utilities for the proxy control pattern.
+ *
+ * Some components need a native `<input>` internally — for form submission,
+ * constraint validation, or browser autofill — but the user may not want to
+ * display that input at all. In those cases the input is hidden and a separate
+ * visible element (the proxy) takes over the visual and interactive role.
+ *
+ * The typical use case is `SelectableList`: each list item acts as a styled
+ * radio button, but an actual `<input type="radio">` lives hidden in the DOM
+ * so form submission and validation work natively.  When users DO want to
+ * display the input they want full control over its appearance, so they render
+ * their own element and link it to the real input via `navi-control-proxy-for`:
+ *
+ * ```html
+ *  <div>
+ *   <input id="color_red" type="radio" name="color" value="red"  /> ← real control (hidden, drives form/validation)
+ *   <input type="radio" name="proxy" value="red" />                 ← proxy (visible, delegates interactions to real input)
+ * </div>
+ * ```
+ *
+ * A press on a checkable proxy is dealt to the real control, and so is the
+ * focus: state management, validation and form submission then all happen
+ * where the value lives. A proxy that says what its press does — a button
+ * carrying `command="--navi-check"` — answers the press itself instead.
+ *
+ * Note: an alternative design would be to require users to always instantiate
+ * the input explicitly — e.g. `<Selectable.Input headless />` when they don't
+ * want to display it. That would remove the need for the proxy mechanism
+ * entirely. For now we keep the proxy pattern.
+ */
+
+
+/**
+ * Given a proxy element, returns the real control it represents.
+ * Returns `null` when `el` is not a proxy.
+ */
+const findControlProxyTarget = (el) => {
+  const proxyFor = el.getAttribute("navi-control-proxy-for");
+  if (!proxyFor) {
+    return null;
+  }
+  return document.getElementById(proxyFor);
+};
+
+// Shared: asked on every pseudo state change of every box, and almost always
+// empty.
+const NO_PROXIES = Object.freeze([]);
+/**
+ * Given a real control element, returns every proxy that visually represents
+ * it — a control can have more than one (an "enable"/"disable" button pair for
+ * one radio, for instance).
+ *
+ * Answered from the controller registry rather than the document: every proxy
+ * declares itself through the `navi-control-proxy-for` prop, so the registry
+ * knows them all, while asking the document means walking it in full for each
+ * of the (overwhelmingly many) controls that have no proxy at all.
+ *
+ * Returns an empty array when no proxy exists for `el`.
+ */
+const findControlProxies = (el) => {
+  if (!el.id) {
+    return NO_PROXIES;
+  }
+  const proxyControllerSet = findProxyControllers(el.id);
+  if (!proxyControllerSet) {
+    return NO_PROXIES;
+  }
+  const proxyElements = [];
+  for (const proxyController of proxyControllerSet) {
+    const proxyElement = proxyController.ref.current;
+    if (proxyElement) {
+      proxyElements.push(proxyElement);
+    }
+  }
+  return proxyElements;
+};
+
+/**
+ * Given a real control element, returns the proxy a gesture on the control
+ * lands on — the one thing said about the control is drawn on.
+ *
+ * Use when you need a single visible stand-in for the real control — anchoring
+ * a callout, for instance. Anything notifying proxies of a state change wants
+ * `findControlProxies` instead, so a control represented by several of them
+ * updates all of them.
+ *
+ * A proxy the pointer cannot reach is drawn for the control without standing
+ * for it: the surface around it takes the presses for everything it holds, so
+ * that surface is where a refusal about the control belongs — not a box inside
+ * it the finger never has to find. A selectable list row whose whole area is
+ * the click target is exactly that arrangement (see `selectableArea`), and it
+ * is read from the arrangement itself rather than from a flag repeating it:
+ * where a gesture can land IS pointer-events.
+ *
+ * Returns `null` when no proxy stands for `el`.
+ */
+const findControlProxy = (el) => {
+  for (const proxyElement of findControlProxies(el)) {
+    if (getComputedStyle(proxyElement).pointerEvents === "none") {
+      continue;
+    }
+    return proxyElement;
+  }
+  return null;
+};
+
 /**
  * Typography reset shared by the surfaces a control opens: callout, popover,
  * dialog.
@@ -19411,6 +20650,1453 @@ const getDefaultDisplay = (tagName) => {
   return TAG_NAME_TO_DEFAULT_DISPLAY.get(normalizedTagName) || "inline";
 };
 
+const addInputEffect = (
+  input,
+  callback,
+  { waitForChange = false, debounce = 0, debugInteraction = () => {} } = {},
+) => {
+  const getState =
+    input.type === "checkbox" || input.type === "radio"
+      ? () => input.checked
+      : () => input.value;
+
+  if (waitForChange) {
+    return listenInputStateChange(input, callback, { getState });
+  }
+
+  const [teardown, addTeardown] = createPubSub();
+  let currentState = getState();
+  let timeout;
+  let debounceTimeout;
+  let onEvent;
+  if (debounce) {
+    onEvent = (e, { skipDebounce } = {}) => {
+      clearTimeout(timeout);
+      clearTimeout(debounceTimeout);
+      const state = getState();
+      if (state === currentState) {
+        debugInteraction(
+          e,
+          `interaction ignored (state unchanged: "${state}")`,
+        );
+        return;
+      }
+
+      if (skipDebounce) {
+        debugInteraction(e, `skip debounce, callback called with "${state}"`);
+        if (callback(e) !== false) {
+          currentState = state;
+        }
+      } else {
+        debugInteraction(
+          e,
+          `debounced ${debounce}ms, pending callback with "${state}"`,
+        );
+        debounceTimeout = setTimeout(() => {
+          debugInteraction(
+            e,
+            `debounce elapsed, callback called with "${state}"`,
+          );
+          if (callback(e) !== false) {
+            currentState = state;
+          }
+        }, debounce);
+      }
+    };
+    // no need to wait for change events (blur, enter key)
+    // we consider this as strong interactions requesting an immediate response
+    const stop = listenInputStateChange(
+      input,
+      (e) => {
+        onEvent(e, { skipDebounce: true });
+      },
+      { getState, changeOnEnter: true },
+    );
+    addTeardown(() => {
+      stop();
+    });
+  } else {
+    onEvent = (e) => {
+      clearTimeout(timeout);
+      const state = getState();
+      if (state === currentState) {
+        debugInteraction(
+          e,
+          `interaction ignored (state unchanged: "${state}")`,
+        );
+        return;
+      }
+      debugInteraction(e, `callback called with "${state}"`);
+      if (callback(e) !== false) {
+        currentState = state;
+      }
+    };
+    // Autocomplete, programmatic changes, form restoration
+    input.addEventListener("change", onEvent);
+    addTeardown(() => {
+      input.removeEventListener("change", onEvent);
+    });
+  }
+
+  const onAsyncEvent = (e, options) => {
+    debugInteraction(e, `async event, scheduling callback`);
+    timeout = setTimeout(() => {
+      onEvent(e, options);
+    }, 0);
+  };
+
+  // Standard user input (typing)
+  const onInput = (e) => {
+    onEvent(e);
+  };
+  input.addEventListener("input", onInput);
+  addTeardown(() => {
+    input.removeEventListener("input", onInput);
+  });
+
+  // Form reset - need to check the form
+  const form = input.form;
+  if (form) {
+    // Form reset happens asynchronously, check value after reset completes
+    form.addEventListener("reset", onAsyncEvent);
+    addTeardown(() => {
+      form.removeEventListener("reset", onAsyncEvent);
+    });
+  }
+
+  // Paste events (some browsers need special handling)
+  input.addEventListener("paste", onEvent);
+  addTeardown(() => {
+    input.removeEventListener("paste", onEvent);
+  });
+
+  input.addEventListener("navi_ui_state_change", (e) => {
+    // radios are unchecked by an internal setUIState call when another radio is checked.
+    // navi_ui_state_change is dispatched whenever setUIState changes state, so we
+    // listen here to keep currentState in sync — otherwise input_effect thinks the
+    // radio is still checked and ignores the next user click as "state unchanged".
+    if (input.type === "radio") {
+      currentState = e.detail.value;
+    }
+    const clearEvent = findEvent(
+      e,
+      (eInChain) =>
+        eInChain.type === "navi_set_ui_state" && eInChain.detail.isClear,
+    );
+    const isClear = Boolean(clearEvent);
+    if (isClear) {
+      // "navi_clear" behaves like an async event
+      // a bit like form reset because
+      // our action will be updated async after the component re-renders
+      // and we need to wait that to happen to properly call action with the right value
+      debugInteraction(e, `navi_clear received, scheduling callback`);
+      onAsyncEvent(e, { skipDebounce: true });
+    }
+  });
+
+  return teardown;
+};
+
+const listenInputStateChange = (
+  input,
+  callback,
+  { getState, changeOnEnter },
+) => {
+  const [teardown, addTeardown] = createPubSub();
+
+  let stateAtInteraction;
+  const oninput = () => {
+    stateAtInteraction = undefined;
+  };
+  const onkeydown = (e) => {
+    if (e.key === "Enter") {
+      /**
+       * Browser trigger a "change" event right after the enter is pressed
+       * if the input value has changed.
+       * We need to prevent the next change event otherwise we would request action twice
+       */
+      stateAtInteraction = getState();
+      if (changeOnEnter) {
+        onchange(e);
+      }
+    }
+    if (e.key === "Escape") {
+      /**
+       * Browser trigger a "change" event right after the escape is pressed
+       * if the input value has changed.
+       * We need to prevent the next change event otherwise we would request action when
+       * we actually want to cancel
+       */
+      stateAtInteraction = getState();
+    }
+  };
+  const onchange = (e) => {
+    if (stateAtInteraction !== undefined && getState() === stateAtInteraction) {
+      stateAtInteraction = undefined;
+      return;
+    }
+    callback(e);
+  };
+  input.addEventListener("input", oninput);
+  input.addEventListener("keydown", onkeydown);
+  input.addEventListener("change", onchange);
+  addTeardown(() => {
+    input.removeEventListener("input", oninput);
+    input.removeEventListener("keydown", onkeydown);
+    input.removeEventListener("change", onchange);
+  });
+
+  {
+    // Handle programmatic value changes that don't trigger browser change events
+    //
+    // Problem: When input values are set programmatically (not by user typing),
+    // browsers don't fire the 'change' event. However, our application logic
+    // still needs to detect these changes.
+    //
+    // Example scenario:
+    // 1. User starts editing (letter key pressed, value set programmatically)
+    // 2. User doesn't type anything additional (this is the key part)
+    // 3. User clicks outside to finish editing
+    // 4. Without this code, no change event would fire despite the fact that the input value did change from its original state
+    //
+    // This distinction is crucial because:
+    //
+    // - If the user typed additional text after the initial programmatic value,
+    //   the browser would fire change events normally
+    // - But when they don't type anything else, the browser considers it as "no user interaction"
+    //   even though the programmatic initial value represents a meaningful change
+    //
+    // We achieve this by checking if the input value has changed between focus and blur without any user interaction
+    // if yes we fire the callback because input value did change
+    let stateAtStart = getState();
+    let interacted = false;
+
+    const onfocus = () => {
+      interacted = false;
+      stateAtStart = getState();
+    };
+    const oninput = (e) => {
+      if (!e.isTrusted) {
+        // non trusted "input" events will be ignored by the browser when deciding to fire "change" event
+        // we ignore them too
+        return;
+      }
+      interacted = true;
+    };
+    const onblur = (e) => {
+      if (interacted) {
+        return;
+      }
+      if (stateAtStart === getState()) {
+        return;
+      }
+      callback(e);
+    };
+
+    input.addEventListener("focus", onfocus);
+    input.addEventListener("input", oninput);
+    input.addEventListener("blur", onblur);
+    addTeardown(() => {
+      input.removeEventListener("focus", onfocus);
+      input.removeEventListener("input", oninput);
+      input.removeEventListener("blur", onblur);
+    });
+  }
+
+  return teardown;
+};
+
+const requestPseudoStateCheck = (element, detail) => {
+  dispatchInternalCustomEvent(
+    element,
+    "navi_pseudo_state_request_check",
+    detail,
+  );
+  // When a control has visible proxies mirroring its state (e.g. selectable
+  // radio with `navi-control-proxy-for`), re-check them too so they stay in
+  // sync with the real control.
+  for (const proxy of findControlProxies(element)) {
+    dispatchInternalCustomEvent(
+      proxy,
+      "navi_pseudo_state_request_check",
+      detail,
+    );
+  }
+};
+/**
+ * Called back whenever `element`'s pseudo state changes.
+ *
+ * Kept beside the element rather than announced to the DOM: an element that
+ * changes state has at most one or two interested parties, each known by name
+ * (the box drawing it, the accent color reading its computed style), and a
+ * CustomEvent costs its allocation and its capture/bubble walk whether anyone
+ * listens or not — paid on every element, on every state change. A lookup that
+ * finds nothing costs nothing.
+ *
+ * @param {Element} element
+ * @param {(pseudoState: object, oldPseudoState: object) => void} callback
+ * @returns {() => void} teardown
+ */
+const subscribeToPseudoState = (element, callback) => {
+  let subscriberSet = pseudoStateSubscriberSetWeakMap.get(element);
+  if (!subscriberSet) {
+    subscriberSet = new Set();
+    pseudoStateSubscriberSetWeakMap.set(element, subscriberSet);
+  }
+  subscriberSet.add(callback);
+  return () => {
+    subscriberSet.delete(callback);
+  };
+};
+const pseudoStateSubscriberSetWeakMap = new WeakMap();
+const notifyPseudoStateSubscribers = (element, value, oldValue) => {
+  const subscriberSet = pseudoStateSubscriberSetWeakMap.get(element);
+  if (!subscriberSet) {
+    return;
+  }
+  for (const subscriber of subscriberSet) {
+    subscriber(value, oldValue);
+  }
+};
+
+const PSEUDO_CLASSES = {};
+Object.assign(PSEUDO_CLASSES, {
+  ":valid": {
+    attribute: "data-valid",
+    test: (el) => el.matches(":valid"),
+  },
+  ":invalid": {
+    attribute: "data-invalid",
+    test: (el) => el.matches(":invalid"),
+  },
+  ":visited": {
+    attribute: "data-visited",
+  },
+  // Written by whoever knows the current url — a Link from its href, a Button
+  // from its route — so it lives here rather than with one of them.
+  ":-navi-href-current": {
+    attribute: "data-href-current",
+  },
+});
+const definePseudoClass = (pseudoClass, definition) => {
+  PSEUDO_CLASSES[pseudoClass] = definition;
+};
+
+// On touch devices (hover: none), browsers synthesize mouseenter/mouseleave
+// from touch events but never fire mouseleave when the finger lifts, leaving
+// el.matches(":hover") stuck at true. This causes hover styles (e.g. input
+// background highlight) to remain visible long after the user has stopped
+// touching the element. Checking (hover: hover) lets us skip hover tracking
+// entirely on touch-only devices where persistent hover makes no sense.
+const hoverSupported = window.matchMedia("(hover: hover)").matches;
+definePseudoClass(":hover", {
+  attribute: "data-hover",
+  setup: (el, callback) => {
+    if (!hoverSupported) {
+      return () => {};
+    }
+    const recheckProxy = (e) => {
+      for (const proxy of findControlProxies(el)) {
+        requestPseudoStateCheck(proxy, { event: e });
+      }
+    };
+    const recheckProxyTarget = (e) => {
+      const proxyTarget = findControlProxyTarget(el);
+      if (proxyTarget) {
+        requestPseudoStateCheck(proxyTarget, { event: e });
+      }
+    };
+    let onmouseenter = (e) => {
+      callback();
+      recheckProxy(e);
+      recheckProxyTarget(e);
+    };
+    let onmouseleave = (e) => {
+      callback();
+      recheckProxy(e);
+      recheckProxyTarget(e);
+    };
+
+    if (el.tagName === "LABEL") {
+      // input.matches(":hover") is true when hovering the label
+      // so when label is hovered/not hovered we need to recheck the input too
+      const recheckInput = (e) => {
+        if (el.htmlFor) {
+          const input = document.getElementById(el.htmlFor);
+          if (!input) {
+            // cannot find the input for this label in the DOM
+            return;
+          }
+          requestPseudoStateCheck(input, { event: e });
+          return;
+        }
+        const input = el.querySelector("input, textarea, select");
+        if (!input) {
+          // label does not contain an input
+          return;
+        }
+        requestPseudoStateCheck(input, { event: e });
+      };
+      const _onmouseenter = onmouseenter;
+      onmouseenter = (e) => {
+        recheckInput(e);
+        _onmouseenter(e);
+      };
+      const _onmouseleave = onmouseleave;
+      onmouseleave = (e) => {
+        recheckInput(e);
+        _onmouseleave(e);
+      };
+    }
+
+    el.addEventListener("mouseenter", onmouseenter);
+    el.addEventListener("mouseleave", onmouseleave);
+    return () => {
+      el.removeEventListener("mouseenter", onmouseenter);
+      el.removeEventListener("mouseleave", onmouseleave);
+    };
+  },
+  test: (el) => {
+    if (!hoverSupported) {
+      return false;
+    }
+    if (el.matches(":hover")) {
+      return true;
+    }
+    for (const proxy of findControlProxies(el)) {
+      if (proxy.matches(":hover")) {
+        return true;
+      }
+    }
+    return false;
+  },
+});
+definePseudoClass(":disabled", {
+  attribute: "data-disabled",
+  add: (el) => {
+    if (
+      el.tagName === "BUTTON" ||
+      el.tagName === "INPUT" ||
+      el.tagName === "SELECT" ||
+      el.tagName === "TEXTAREA"
+    ) {
+      el.disabled = true;
+    }
+  },
+  remove: (el) => {
+    if (
+      el.tagName === "BUTTON" ||
+      el.tagName === "INPUT" ||
+      el.tagName === "SELECT" ||
+      el.tagName === "TEXTAREA"
+    ) {
+      el.disabled = false;
+    }
+  },
+});
+definePseudoClass(":read-only", {
+  attribute: "data-readonly",
+  add: (el) => {
+    if (
+      el.tagName === "INPUT" ||
+      el.tagName === "SELECT" ||
+      el.tagName === "TEXTAREA"
+    ) {
+      if (el.type === "checkbox" || el.type === "radio") {
+        // there is no readOnly for checkboxes/radios
+        return;
+      }
+      // el.readOnly = true;
+    }
+  },
+  remove: (el) => {
+    if (
+      el.tagName === "INPUT" ||
+      el.tagName === "SELECT" ||
+      el.tagName === "TEXTAREA"
+    ) {
+      if (el.type === "checkbox" || el.type === "radio") {
+        // there is no readOnly for checkboxes/radios
+        return;
+      }
+      // el.readOnly = false;
+    }
+  },
+});
+definePseudoClass(":checked", {
+  attribute: "data-checked",
+  setup: (el, callback) => {
+    if (el.type === "checkbox") {
+      // Listen to user interactions
+      el.addEventListener("input", callback);
+      // Intercept programmatic changes to .checked property
+      const originalDescriptor = Object.getOwnPropertyDescriptor(
+        HTMLInputElement.prototype,
+        "checked",
+      );
+      Object.defineProperty(el, "checked", {
+        get: originalDescriptor.get,
+        set(value) {
+          originalDescriptor.set.call(this, value);
+          callback();
+        },
+        configurable: true,
+      });
+      return () => {
+        // Restore original property descriptor
+        Object.defineProperty(el, "checked", originalDescriptor);
+        el.removeEventListener("input", callback);
+      };
+    }
+    if (el.type === "radio") {
+      // Listen to changes on the radio
+      el.addEventListener("input", callback);
+      // Intercept programmatic changes to .checked property
+      const originalDescriptor = Object.getOwnPropertyDescriptor(
+        HTMLInputElement.prototype,
+        "checked",
+      );
+      Object.defineProperty(el, "checked", {
+        get: originalDescriptor.get,
+        set(value) {
+          originalDescriptor.set.call(this, value);
+          callback();
+        },
+        configurable: true,
+      });
+      return () => {
+        el.removeEventListener("input", callback);
+        // Restore original property descriptor
+        Object.defineProperty(el, "checked", originalDescriptor);
+      };
+    }
+    if (el.tagName === "INPUT") {
+      el.addEventListener("input", callback);
+      return () => {
+        el.removeEventListener("input", callback);
+      };
+    }
+    return () => {};
+  },
+  test: (el) => el.matches(":checked"),
+});
+definePseudoClass(":active", {
+  attribute: "data-active",
+  setup: (el, callback) => {
+    // I'ts recommended to use :-navi-pressed over :active for interactive elements.
+    const onPointerDown = () => {
+      const onRelease = () => {
+        document.removeEventListener("pointercancel", onRelease, true);
+        document.removeEventListener("pointerup", onRelease, true);
+        callback();
+      };
+      document.addEventListener("pointercancel", onRelease, true);
+      document.addEventListener("pointerup", onRelease, true);
+      callback();
+    };
+    el.addEventListener("pointerdown", onPointerDown);
+    return () => {
+      el.removeEventListener("pointerdown", onPointerDown);
+    };
+  },
+  test: (el) => el.matches(":active"),
+});
+
+// The current input modality: true after a keyboard navigation key (arrow keys,
+// Escape, Enter, Ctrl, Alt, Shift, Space — Space ignored on editable fields),
+// false after a pointer interaction. Updated by the listeners in the
+// focus_classes block below. At module scope so isMatchingFocusVisible (used
+// here and in control_hooks.jsx) can read it.
+let keyboardNavigationUsed = false;
+
+// HOW FOCUS-VISIBLE IS DECIDED (the details behind isMatchingFocusVisible)
+//
+// Two rules, depending on what `el` is:
+//
+// 1. An EDITABLE target (text-ish input, textarea, contenteditable — anything
+//    whose whole point is keyboard input, see isEditableTarget) shows its ring
+//    whenever it holds the focus, however the focus arrived — mouse,
+//    programmatic, even a focus({ focusVisible: false }). Being focused, for
+//    such a field, means being about to type, and that is what the ring
+//    announces. Its check is on :focus rather than :focus-visible on purpose:
+//    the native :focus-visible obeys the focusVisible option, which callers
+//    set from the modality without knowing what they are focusing.
+//
+// 2. Anything else needs BOTH the native :focus-visible match AND the current
+//    modality being keyboard (`keyboardNavigationUsed`).
+//
+//    The native match alone cannot be trusted, because we routinely take the
+//    pointer out of the browser's hands: a picker opens on mousedown and calls
+//    preventDefault() so the browser does not move focus itself (see
+//    picker_custom.jsx). The browser therefore never registers that a pointer
+//    was what moved focus, and whatever focus-visible state the previous
+//    keyboard interaction left behind stays true — even across the
+//    programmatic focus({ focusVisible: false }) that follows. Close a picker
+//    with Escape (ring on the trigger, rightly) and click it open again: the
+//    popup's own focusable would come up ringed, from a mouse press.
+//
+//    `keyboardNavigationUsed` has no such blind spot — it is set by navigation
+//    keydowns and cleared by pointerdown, whatever anyone prevents afterwards
+//    — so it is the authority for everything rule 1 does not cover.
+//
+// Ring INHERITANCE (a controlled element ringing because its aria-controls
+// controller is focused) stays gated on the keyboard modality even for an
+// editable controller — see hasIndirectFocus: propagating a ring promises
+// keyboard shortcuts will drive the controlled element, a promise that only
+// holds once a physical keyboard has actually been used.
+/**
+ * Whether `el` should currently show a focus ring — the enriched
+ * :focus-visible behind every [data-focus-visible] navi renders.
+ * Use this instead of a bare el.matches(":focus-visible") wherever
+ * focus-visible is evaluated; the comment above details the rules.
+ * @param {Element} el
+ * @returns {boolean}
+ */
+const isMatchingFocusVisible = (el) => {
+  if (isEditableTarget(el)) {
+    return el.matches(":focus");
+  }
+  if (!el.matches(":focus-visible")) {
+    return false;
+  }
+  if (!keyboardNavigationUsed) {
+    return false;
+  }
+  return true;
+};
+
+// Elements that invite keyboard input: focusing one — even with the mouse —
+// means the user is about to type, so they always warrant a visible focus.
+// Also used to ignore the Space key as a navigation key while typing, and by
+// programmatic focus (focus_transfer.js) to pass focusVisible: true so the
+// native :focus-visible agrees with the ring rule 1 above draws.
+const EDITABLE_INPUT_TYPE_SET = new Set([
+  "text",
+  "search",
+  "url",
+  "email",
+  "password",
+  "tel",
+  "number",
+  "date",
+  "time",
+  "datetime-local",
+  "month",
+  "week",
+]);
+const isEditableTarget = (target) => {
+  if (!target) {
+    return false;
+  }
+  const tag = target.tagName;
+  if (tag === "TEXTAREA") {
+    return !target.readOnly;
+  }
+  if (tag === "INPUT") {
+    if (!target.type || EDITABLE_INPUT_TYPE_SET.has(target.type)) {
+      return !target.readOnly;
+    }
+  }
+  if (target.isContentEditable) {
+    return true;
+  }
+  return false;
+};
+
+// The current modality, for code deciding whether something it is about to
+// focus should show a ring — a slide arriving, a popup opening. The question is
+// "was the user on the keyboard when this was asked for", which is what this
+// flag says; the element that happens to hold the focus right now says nothing
+// about it (it may have been focused programmatically, ring or no ring, by the
+// travel before this one).
+const isKeyboardModality = () => keyboardNavigationUsed;
+
+{
+  // We implement :focus and :focus-visible with enriched semantics:
+  // an element is considered focused not only when it natively has focus, but also
+  // when a "focus proxy" element has focus (e.g. a read-only range input delegates
+  // focus to a sibling span) or when a controlling element has focus (e.g. a combobox
+  // input with aria-controls pointing to a listbox — the listbox should appear focused
+  // while the input is focused).
+  //
+  // We intentionally reuse the native :focus / :focus-visible names rather than
+  // introducing new navi-specific pseudo-classes (e.g. :-navi-focus). This is a
+  // deliberate exception: all existing CSS and code written as [data-focus] or
+  // [data-focus-visible] automatically benefits from the enriched behavior without
+  // any changes. A separate navi-specific class would require updating every
+  // component.
+  //
+  // When a controller element (e.g. combobox input) gains or loses focus,
+  // notify the elements it controls via aria-controls so they re-check their
+  // focus state. `requestPseudoStateCheck` also re-checks the controlled
+  // element's proxy (if any), so the visible proxy mirrors the hidden real
+  // input's inherited focus.
+  const notifyAriaControlled = (el, e) => {
+    const controlledIds = el.getAttribute("aria-controls");
+    if (!controlledIds) {
+      return;
+    }
+    for (const id of controlledIds.split(" ")) {
+      const controlled = document.getElementById(id);
+      if (controlled) {
+        requestPseudoStateCheck(controlled, { event: e });
+      }
+    }
+  };
+  // Tracks whether the user has pressed a keyboard navigation key (arrow keys,
+  // Escape, Enter, Ctrl, Alt, Shift, Space) since the last pointer interaction.
+  // Space is ignored when the target is an editable field.
+  // This flag is used to gate focus-visible inheritance via aria-controls:
+  // on mobile (or when the user hasn't used keyboard nav yet) an input that
+  // controls a radio should not cause the radio to show a focus ring.
+  // (Declared at module scope — see keyboardNavigationUsed above.)
+  const NAVIGATION_KEY_SET = new Set([
+    "ArrowUp",
+    "ArrowDown",
+    "ArrowLeft",
+    "ArrowRight",
+    "Escape",
+    "Enter",
+    "Control",
+    "Alt",
+    "Shift",
+    " ",
+    "Tab",
+  ]);
+  document.addEventListener(
+    "keydown",
+    (e) => {
+      if (!NAVIGATION_KEY_SET.has(e.key)) {
+        return;
+      }
+      if (e.key === " " && isEditableTarget(e.target)) {
+        return;
+      }
+      keyboardNavigationUsed = true;
+    },
+    { capture: true },
+  );
+  document.addEventListener(
+    "pointerdown",
+    () => {
+      keyboardNavigationUsed = false;
+    },
+    { capture: true },
+  );
+
+  // A keystroke flips keyboardNavigationUsed, which can turn :focus-visible on —
+  // but only for the element that holds focus, directly or through aria-controls
+  // / a proxy. Pressing a key cannot reveal a focus ring on an unfocused element.
+  // So a single shared handler re-checks just that focus chain (the active
+  // element, what it controls, and its proxy — the last two via
+  // requestPseudoStateCheck / notifyAriaControlled). This runs in the bubble
+  // phase, after the capture-phase listener above has updated the flag.
+  //
+  // The alternative — each registered :focus-visible element adding its own
+  // document keydown listener that re-tests itself — makes one keypress cost
+  // O(number-of-boxes) full-document [aria-controls] / proxy queries, since every
+  // unfocused element falls through matches(":focus-visible") into hasIndirectFocus.
+  const recheckFocusChainOnKey = (e) => {
+    const active = document.activeElement;
+    if (!active || active === document.body) {
+      return;
+    }
+    requestPseudoStateCheck(active, { event: e });
+    notifyAriaControlled(active, e);
+  };
+  document.addEventListener("keydown", recheckFocusChainOnKey);
+  document.addEventListener("keyup", recheckFocusChainOnKey);
+
+  // Returns true when el holds focus indirectly — either because a controlling
+  // element (aria-controls) has focus, or because el is a proxy whose target
+  // is itself controlled by a focused element.
+  const hasIndirectFocus = (el, { requireFocusVisible = false } = {}) => {
+    // No ring inheritance without a keyboard: an editable target draws its own
+    // ring on any focus (see isMatchingFocusVisible), but propagating that ring
+    // to a controlled element (aria-controls) is a promise that keyboard
+    // shortcuts will drive it — a promise that holds only once a physical
+    // keyboard has actually been used. On touch devices the flag stays false
+    // and a focused search input keeps its ring to itself.
+    if (requireFocusVisible && !keyboardNavigationUsed) {
+      return false;
+    }
+    // A controller/proxy counts as focused for inheritance via the same rule
+    // used everywhere: :focus for plain inheritance, isMatchingFocusVisible for
+    // the focus-visible variant (so a mouse-focused controller doesn't propagate
+    // a ring).
+    const isFocusedTarget = (target) =>
+      requireFocusVisible
+        ? isMatchingFocusVisible(target)
+        : target.matches(":focus");
+    // Both branches of isFocusedTarget rest on :focus / :focus-visible, and only
+    // one element in the document can match those: document.activeElement. So
+    // the single controller worth testing is known upfront — asking the document
+    // for every [aria-controls] would collect candidates that cannot qualify,
+    // once per element and again on every re-check, on a document each new
+    // element makes bigger.
+    const isControlledBy = (target) => {
+      const id = target.id;
+      if (!id) {
+        return false;
+      }
+      const activeElement = document.activeElement;
+      if (!activeElement || activeElement === document.body) {
+        return false;
+      }
+      if (!activeElement.matches(`[aria-controls~="${id}"]`)) {
+        return false;
+      }
+      // A controller inside the element it controls means focus is already
+      // native (:focus-within) — nothing to inherit.
+      if (target.contains(activeElement)) {
+        return false;
+      }
+      return isFocusedTarget(activeElement);
+    };
+    if (isControlledBy(el)) {
+      return true;
+    }
+    const proxyTarget = findControlProxyTarget(el);
+    if (proxyTarget) {
+      if (isFocusedTarget(proxyTarget)) {
+        return true;
+      }
+      if (isControlledBy(proxyTarget)) {
+        return true;
+      }
+    }
+    return false;
+  };
+
+  // One registration per element for everything focus-related, shared by
+  // :focus, :focus-visible and :focus-within: they all react to the same
+  // focusin/focusout, and they all re-check through the same callback (see
+  // initPseudoStyles), which the Set turns into one call.
+  const focusTrackingWeakMap = new WeakMap();
+  const trackFocus = (el, callback) => {
+    let tracking = focusTrackingWeakMap.get(el);
+    if (!tracking) {
+      const callbackSet = new Set();
+      const onFocusChange = (e) => {
+        for (const trackedCallback of callbackSet) {
+          trackedCallback();
+        }
+        notifyAriaControlled(el, e);
+      };
+      el.addEventListener("focusin", onFocusChange);
+      el.addEventListener("focusout", onFocusChange);
+      tracking = {
+        callbackSet,
+        teardown: () => {
+          el.removeEventListener("focusin", onFocusChange);
+          el.removeEventListener("focusout", onFocusChange);
+          focusTrackingWeakMap.delete(el);
+        },
+      };
+      focusTrackingWeakMap.set(el, tracking);
+      observeAriaControls();
+    }
+    tracking.callbackSet.add(callback);
+    return () => {
+      tracking.callbackSet.delete(callback);
+      if (tracking.callbackSet.size === 0) {
+        tracking.teardown();
+      }
+    };
+  };
+  // When aria-controls changes on a focused element, what it used to control
+  // and what it controls now both re-check their inherited focus. One observer
+  // on the document rather than one per tracked element: the attribute changes
+  // rarely, on few elements, while thousands are tracked — and it can be set
+  // after the element was, so "has it at setup" would miss it.
+  let ariaControlsObserver = null;
+  const observeAriaControls = () => {
+    if (ariaControlsObserver) {
+      return;
+    }
+    ariaControlsObserver = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        const el = mutation.target;
+        if (!focusTrackingWeakMap.has(el)) {
+          continue;
+        }
+        if (!el.matches(":focus-within")) {
+          continue;
+        }
+        const oldIds = (mutation.oldValue || "").split(" ").filter(Boolean);
+        for (const id of oldIds) {
+          const controlled = document.getElementById(id);
+          if (controlled) {
+            requestPseudoStateCheck(controlled, {});
+          }
+        }
+        notifyAriaControlled(el, {});
+      }
+    });
+    ariaControlsObserver.observe(document.documentElement, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["aria-controls"],
+      attributeOldValue: true,
+    });
+  };
+
+  definePseudoClass(":focus", {
+    attribute: "data-focus",
+    setup: trackFocus,
+    test: (el) => {
+      if (el.matches(":focus")) {
+        return true;
+      }
+      if (hasIndirectFocus(el)) {
+        return true;
+      }
+      return false;
+    },
+  });
+  definePseudoClass(":focus-visible", {
+    attribute: "data-focus-visible",
+    // No per-element keydown/keyup listener: the shared recheckFocusChainOnKey
+    // handler re-checks the focused element (the only one a keystroke can turn
+    // focus-visible) so a keypress stays O(1), not O(number-of-boxes).
+    setup: trackFocus,
+    test: (el) => {
+      if (isMatchingFocusVisible(el)) {
+        return true;
+      }
+      if (hasIndirectFocus(el, { requireFocusVisible: true })) {
+        return true;
+      }
+      return false;
+    },
+  });
+  definePseudoClass(":focus-within", {
+    attribute: "data-focus-within",
+    setup: trackFocus,
+    test: (el) => {
+      if (el.matches(":focus-within")) {
+        return true;
+      }
+      if (hasIndirectFocus(el)) {
+        return true;
+      }
+      if (el.contains(document.activeElement)) {
+        // for some reason :focus-within sometimes is false while focus is within...
+        // (popover with chrome for some reason)
+        return true;
+      }
+      return false;
+    },
+  });
+}
+
+Object.assign(PSEUDO_CLASSES, {
+  ":-navi-pointed": {
+    attribute: "data-pointed",
+  },
+  ":-navi-pointed-by-mouse": {
+    attribute: "data-pointed-by-mouse",
+  },
+  ":-navi-pointed-by-keyboard": {
+    attribute: "data-pointed-by-keyboard",
+  },
+  ":-navi-pointed-by-proxy": {
+    attribute: "data-pointed-by-proxy",
+  },
+  ":-navi-selected": {
+    attribute: "data-selected",
+  },
+  ":-navi-loading": {
+    attribute: "data-loading",
+  },
+  ":-navi-status-info": {
+    attribute: "data-status-info",
+  },
+  ":-navi-status-success": {
+    attribute: "data-status-success",
+  },
+  ":-navi-status-warning": {
+    attribute: "data-status-warning",
+  },
+  ":-navi-status-error": {
+    attribute: "data-status-error",
+  },
+  ":-navi-expanded": {
+    attribute: "data-expanded",
+  },
+  ":-navi-void": {
+    attribute: "data-void",
+  },
+  "::highlight": {},
+});
+definePseudoClass(":-navi-has-value", {
+  attribute: "data-has-value",
+  setup: (el, callback) => {
+    const controlHost = findControlHost(el) || el;
+    return addInputEffect(controlHost, callback);
+  },
+  test: (el) => {
+    if (isControlHost(el)) {
+      const uiState = getUIStateFromElement(el);
+      if (uiState === undefined || uiState === "") {
+        return false;
+      }
+      return true;
+    }
+    if (el.value === "") {
+      return false;
+    }
+    return true;
+  },
+});
+{
+  const pressedElements = new WeakSet();
+  definePseudoClass(":-navi-pressed", {
+    attribute: "data-pressed",
+    setup: (el, callback) => {
+      // Prefer :-navi-pressed over :active for interactive elements because:
+      // - :active only tracks the primary (left) button; right-click and touch
+      //   long-press do not trigger :active reliably across browsers.
+      // - :-navi-pressed explicitly ignores non-primary buttons (e.g. right-click)
+      //   and correctly clears pressed state when a context menu opens on long-press,
+      //   which would otherwise leave the element stuck in a pressed appearance.
+
+      // Note: it might be tempting to use el.setPointerCapture() here so that pointerup
+      // always fires on el regardless of where the pointer is released. However,
+      // pointer capture routes all subsequent pointer events to the capturing element,
+      // which means any other element in the tree that expects to receive pointerup,
+      // mouseup, click, etc. after a pointerdown will silently not get them.
+      // For example a <label> that reacts to mousedown + click, or a third-party
+      // library that attaches its own listeners, would break because an ancestor
+      // grabbed the pointer out from under them.
+      // To avoid forcing every such element to declare an opt-out attribute
+      // (e.g. navi-own-pointer-capture) we simply listen on document instead,
+      // which is safe and does not interfere with anyone else's event flow.
+      const onPointerDown = (e) => {
+        if (e.button !== 0) {
+          // only left pointer (mouse left click, touch, pen)
+          return;
+        }
+        pressedElements.add(el);
+        const onRelease = () => {
+          pressedElements.delete(el);
+          document.removeEventListener("pointercancel", onRelease, true);
+          document.removeEventListener("pointerup", onRelease, true);
+          document.removeEventListener("contextmenu", onContextMenu, true);
+          callback();
+        };
+        const onContextMenu = (e) => {
+          // On touch devices, a long-press triggers the context menu.
+          // If the context menu is not prevented, it means it will open and the
+          // pointer events (pointerup, lostpointercapture) won't fire normally,
+          // leaving the element stuck in pressed state. We clear it manually.
+          // e.button === -1 means the event was synthesized from a long-press (not a real mouse click).
+          if (e.button === -1 && !e.defaultPrevented) {
+            pressedElements.delete(el);
+            document.removeEventListener("pointercancel", onRelease, true);
+            document.removeEventListener("pointerup", onRelease, true);
+            document.removeEventListener("contextmenu", onContextMenu, true);
+            callback();
+          }
+        };
+        document.addEventListener("pointercancel", onRelease, true);
+        document.addEventListener("pointerup", onRelease, true);
+        document.addEventListener("contextmenu", onContextMenu, true);
+        callback();
+      };
+      el.addEventListener("pointerdown", onPointerDown);
+      return () => {
+        el.removeEventListener("pointerdown", onPointerDown);
+        pressedElements.delete(el);
+      };
+    },
+    test: (el) => pressedElements.has(el),
+  });
+}
+
+{
+  definePseudoClass(":-navi-drag-grabbed", {
+    attribute: "navi-drag-grabbed",
+    setup: (el, callback) => {
+      const onGrab = () => {
+        callback();
+        const onRelease = () => {
+          el.removeEventListener("navi_drag_release", onRelease);
+          callback();
+        };
+        el.addEventListener("navi_drag_release", onRelease);
+      };
+      el.addEventListener("navi_drag_grab", onGrab);
+      return () => {
+        el.removeEventListener("navi_drag_grab", onGrab);
+      };
+    },
+    test: (el) => el.hasAttribute("data-drag-grabbed"),
+  });
+  definePseudoClass(":-navi-dragging", {
+    attribute: "navi-dragging",
+    setup: (el, callback) => {
+      const onStart = () => {
+        callback();
+        const onRelease = () => {
+          el.removeEventListener("navi_drag_release", onRelease);
+          callback();
+        };
+        el.addEventListener("navi_drag_release", onRelease);
+      };
+      el.addEventListener("navi_drag_start", onStart);
+      return () => {
+        el.removeEventListener("navi_drag_start", onStart);
+      };
+    },
+    test: (el) => el.hasAttribute("data-dragging"),
+  });
+}
+
+const EMPTY_STATE = {};
+const elementToImpactWeakMap = new WeakMap();
+const initPseudoStyles = (
+  element,
+  {
+    pseudoClasses,
+    pseudoState, // ":disabled", ":read-only", ":-navi-loading", etc...
+    effect,
+    elementToImpact = element,
+    elementListeningPseudoState,
+  },
+) => {
+  elementToImpactWeakMap.set(element, elementToImpact);
+  if (elementListeningPseudoState === element) {
+    console.warn(
+      `elementListeningPseudoState should not be the same as element to avoid infinite loop`,
+    );
+    elementListeningPseudoState = null;
+  }
+
+  const proxyTarget = findControlProxyTarget(element);
+
+  const onStateChange = (value, oldValue) => {
+    effect?.(value, oldValue);
+    if (elementListeningPseudoState) {
+      notifyPseudoStateSubscribers(
+        elementListeningPseudoState,
+        value,
+        oldValue,
+      );
+    }
+    // When this element's state changes, notify any proxy element that mirrors it
+    // so it can re-check and visually reflect the new state.
+    for (const proxy of findControlProxies(element)) {
+      requestPseudoStateCheck(proxy, {});
+    }
+  };
+
+  if (!pseudoClasses || pseudoClasses.length === 0) {
+    onStateChange(EMPTY_STATE);
+    return () => {};
+  }
+
+  const [teardown, addTeardown] = createPubSub();
+
+  let state;
+  const checkPseudoClasses = () => {
+    let someChange = false;
+    const currentState = {};
+    for (const pseudoClass of pseudoClasses) {
+      const pseudoClassDefinition = PSEUDO_CLASSES[pseudoClass];
+      if (!pseudoClassDefinition) {
+        console.warn(`Unknown pseudo class: ${pseudoClass}`);
+        continue;
+      }
+      let currentValue;
+      if (
+        pseudoState &&
+        Object.hasOwn(pseudoState, pseudoClass) &&
+        pseudoState[pseudoClass] !== undefined
+      ) {
+        currentValue = pseudoState[pseudoClass];
+      } else {
+        const { test } = pseudoClassDefinition;
+        if (test) {
+          currentValue = test(element, pseudoState);
+        }
+      }
+      // If this element is a proxy for another (navi-control-proxy-for="targetId"),
+      // inherit the target's active pseudo-state when the element itself isn't in that state.
+      // We check the target's elementToImpact (not the target itself) because the
+      // data-* attribute may be set on a different element (e.g. pseudoStateSelector).
+      if (!currentValue && proxyTarget) {
+        const { attribute } = pseudoClassDefinition;
+        if (attribute) {
+          const targetElementToImpact =
+            elementToImpactWeakMap.get(proxyTarget) || proxyTarget;
+          if (targetElementToImpact.hasAttribute(attribute)) {
+            currentValue = true;
+          }
+        }
+      }
+      currentState[pseudoClass] = currentValue;
+      const oldValue = state ? state[pseudoClass] : undefined;
+      if (oldValue !== currentValue || !state) {
+        someChange = true;
+        const { attribute, add, remove } = pseudoClassDefinition;
+        if (currentValue) {
+          if (attribute) {
+            elementToImpact.setAttribute(attribute, "");
+          }
+          add?.(element);
+        } else {
+          if (attribute) {
+            elementToImpact.removeAttribute(attribute);
+          }
+          remove?.(element);
+        }
+      }
+    }
+    if (!someChange) {
+      return;
+    }
+    const oldState = state;
+    state = currentState;
+    onStateChange(state, oldState);
+  };
+
+  addTeardown(
+    subscribeToPseudoState(element, (pseudoState, oldPseudoState) => {
+      state = pseudoState;
+      onStateChange(state, oldPseudoState);
+    }),
+  );
+  // One function for every way a re-check can be asked, so that setups
+  // registering it side by side (the focus tracking, for one) hold the same
+  // callback and call it once.
+  const requestCheck = () => {
+    checkPseudoClasses();
+  };
+  element.addEventListener("navi_pseudo_state_request_check", requestCheck);
+  addTeardown(() => {
+    element.removeEventListener(
+      "navi_pseudo_state_request_check",
+      requestCheck,
+    );
+  });
+
+  for (const pseudoClass of pseudoClasses) {
+    const pseudoClassDefinition = PSEUDO_CLASSES[pseudoClass];
+    if (!pseudoClassDefinition) {
+      console.warn(`Unknown pseudo class: ${pseudoClass}`);
+      continue;
+    }
+    const { setup } = pseudoClassDefinition;
+    if (setup) {
+      const cleanup = setup(element, requestCheck);
+      addTeardown(cleanup);
+    }
+  }
+  checkPseudoClasses();
+
+  return teardown;
+};
+
+const applyStyle = (
+  element,
+  style,
+  pseudoState,
+  pseudoNamedStyles,
+  preventInitialTransition,
+) => {
+  if (!element) {
+    return;
+  }
+  const styleToApply = getStyleToApply(style, pseudoState, pseudoNamedStyles);
+  // The same object comes back for every state change of a box whose inline
+  // style has no pseudo entry: nothing to write.
+  if (appliedStyleWeakMap.get(element) === styleToApply) {
+    return;
+  }
+  updateStyle(element, styleToApply, preventInitialTransition);
+};
+
+const PSEUDO_STATE_DEFAULT = {};
+const PSEUDO_NAMED_STYLES_DEFAULT = {};
+const getStyleToApply = (styles, pseudoState, pseudoNamedStyles) => {
+  if (
+    !pseudoState ||
+    pseudoState === PSEUDO_STATE_DEFAULT ||
+    !pseudoNamedStyles ||
+    pseudoNamedStyles === PSEUDO_NAMED_STYLES_DEFAULT
+  ) {
+    return styles;
+  }
+  let style = styles;
+  for (const pseudoKey of Object.keys(pseudoNamedStyles)) {
+    if (!hasEveryState(pseudoState, getPseudoKeyRequiredStates(pseudoKey))) {
+      continue;
+    }
+    if (style === styles) {
+      style = { ...styles };
+    }
+    // Both sides are already normalized for CSS by the box; only the
+    // properties that compose (a press scale on top of a translate) go through
+    // a merge, the rest is a plain override.
+    const styleToAdd = pseudoNamedStyles[pseudoKey];
+    for (const key of Object.keys(styleToAdd)) {
+      const value = styleToAdd[key];
+      if (value === undefined) {
+        continue;
+      }
+      if (key === "transform" || key === "willChange") {
+        style[key] = mergeOneStyle(style[key], value, key, "css");
+      } else {
+        style[key] = value;
+      }
+    }
+  }
+  return style;
+};
+
+// The state names a pseudo key asks for, parsed once: the same few keys come
+// back on every state change of every box that has them. "::x" alone always
+// matches; "::x:a:b" and ":a:b" ask for ":a" and ":b" — the state keys as
+// checkPseudoClasses writes them, colon included.
+const pseudoKeyRequiredStatesMap = new Map();
+const getPseudoKeyRequiredStates = (pseudoKey) => {
+  const cached = pseudoKeyRequiredStatesMap.get(pseudoKey);
+  if (cached) {
+    return cached;
+  }
+  let requiredStates;
+  if (pseudoKey.startsWith("::")) {
+    const nextColonIndex = pseudoKey.indexOf(":", 2);
+    requiredStates =
+      nextColonIndex === -1
+        ? []
+        : getPseudoKeyRequiredStates(pseudoKey.slice(nextColonIndex));
+  } else {
+    const nextColonIndex = pseudoKey.indexOf(":", 1);
+    requiredStates =
+      nextColonIndex === -1
+        ? [pseudoKey]
+        : pseudoKey
+            .slice(1)
+            .split(":")
+            .map((state) => `:${state}`);
+  }
+  pseudoKeyRequiredStatesMap.set(pseudoKey, requiredStates);
+  return requiredStates;
+};
+const hasEveryState = (pseudoState, states) => {
+  for (const state of states) {
+    if (!pseudoState[state]) {
+      return false;
+    }
+  }
+  return true;
+};
+
+// element → the style object last written to it, so the next one is written
+// as a difference: the values that changed, the keys it no longer has.
+const appliedStyleWeakMap = new WeakMap();
+const elementTransitionWeakMap = new WeakMap();
+const elementRenderedWeakSet = new WeakSet();
+const NO_STYLE = {};
+const updateStyle = (element, style, preventInitialTransition) => {
+  const styleToApply = style || NO_STYLE;
+  const styleApplied = appliedStyleWeakMap.get(element) || NO_STYLE;
+  // TRANSITION ANTI-FLICKER STRATEGY:
+  // Problem: When setting both transition and styled properties simultaneously
+  // (e.g., el.style.transition = "border-radius 0.3s ease"; el.style.borderRadius = "20px"),
+  // the browser will immediately perform a transition even if no transition existed before.
+  //
+  // Solution: Temporarily disable transitions during initial style application by setting
+  // transition to "none", then restore the intended transition after the frame completes.
+  // We handle multiple updateStyle calls in the same frame gracefully - only one
+  // requestAnimationFrame is scheduled per element, and the final transition value wins.
+  let skipTransition = false;
+  if (!elementRenderedWeakSet.has(element)) {
+    const hasTransition = Object.hasOwn(styleToApply, "transition");
+    if (hasTransition || preventInitialTransition) {
+      if (!elementTransitionWeakMap.has(element)) {
+        element.style.transition = "none";
+      }
+      elementTransitionWeakMap.set(element, styleToApply.transition);
+      // Stays "none" until the first frame puts the intended value back
+      skipTransition = true;
+    }
+    afterFirstFrame(element);
+  }
+
+  for (const key of Object.keys(styleToApply)) {
+    const value = styleToApply[key];
+    if (value === undefined || value === null) {
+      // a removal: handled below with the keys this style no longer has
+      continue;
+    }
+    if (skipTransition && key === "transition") {
+      continue;
+    }
+    if (styleApplied[key] === value) {
+      continue;
+    }
+    if (key.startsWith("--")) {
+      element.style.setProperty(key, value);
+    } else {
+      element.style[key] = value;
+    }
+  }
+
+  for (const key of Object.keys(styleApplied)) {
+    const previousValue = styleApplied[key];
+    if (previousValue === undefined || previousValue === null) {
+      continue;
+    }
+    const value = styleToApply[key];
+    if (value !== undefined && value !== null) {
+      continue;
+    }
+    if (key.startsWith("--")) {
+      element.style.removeProperty(key);
+    } else {
+      element.style[key] = "";
+    }
+  }
+
+  appliedStyleWeakMap.set(element, styleToApply);
+};
+
+// One frame for every element waiting for its first one, not one frame each.
+// What this owes each element — put back the transition suppressed above, and
+// remember it has now been painted once — is a few microseconds, while asking
+// the browser for a frame costs more than that, and a page mounting thousands of
+// boxes asks thousands of times in the same tick. A Set, so an element styled
+// twice before the frame arrives is still one entry.
+let elementSetWaitingFirstFrame = new Set();
+let firstFrameScheduled = false;
+const afterFirstFrame = (element) => {
+  elementSetWaitingFirstFrame.add(element);
+  if (firstFrameScheduled) {
+    return;
+  }
+  firstFrameScheduled = true;
+  requestAnimationFrame(() => {
+    firstFrameScheduled = false;
+    const elements = elementSetWaitingFirstFrame;
+    elementSetWaitingFirstFrame = new Set();
+    for (const element of elements) {
+      if (elementTransitionWeakMap.has(element)) {
+        const transitionToRestore = elementTransitionWeakMap.get(element);
+        if (transitionToRestore === undefined) {
+          element.style.transition = "";
+        } else {
+          element.style.transition = transitionToRestore;
+        }
+        elementTransitionWeakMap.delete(element);
+      }
+      elementRenderedWeakSet.add(element);
+    }
+  });
+};
+
 /**
  * Keeps a DOM element in sync with `syncElement(el)` whenever syncElement changes.
  * - If element is already mounted: runs syncElement immediately during render.
@@ -86628,6 +89314,105 @@ const createSlot = (SlotRenderer = Box) => {
   return [Slot, SlotFill];
 };
 
+/**
+ * The on-screen keyboard overlaying the app rather than resizing the viewport,
+ * for an app that asks for it (the VirtualKeyboard API — Chromium only). See
+ * virtual_keyboard.js in @jsenv/dom for what that trades away and what it
+ * gives back.
+ *
+ * Offered, never taken by default. Overlaying means redoing by hand what the
+ * browser does for a viewport that shrinks, and on a phone every piece of it
+ * hid a Chrome behavior nothing reports: the focused field left under the
+ * keyboard, a suggestion strip painted above the keyboard outside its
+ * geometry, geometrychange firing while the page is merely scrolled. Firefox
+ * and Safari shrink the viewport whatever the app wants, and navi follows that
+ * already (--navi-vvh), so the default is the path every browser shares.
+ *
+ * What the overlay buys: no reflow of the page underneath — a resizing
+ * viewport is a resize of everything, fired transiently every time focus goes
+ * from one input to the next — while navi still sizes what escapes normal flow
+ * against a rectangle the keyboard is subtracted from
+ * (--navi-keyboard-inset-bottom, safe_area.js).
+ *
+ * Taking the deal means taking over what the browser stops doing under it:
+ * bringing the focused field out from under the keyboard. A viewport that
+ * shrinks makes the browser scroll to the field; a keyboard that merely paints
+ * over the page leaves whatever is under it under it. So enabling the overlay
+ * also installs that scroll, with two things safe_area.js provides: a
+ * scroll-padding-bottom that counts the keyboard in, plus an allowance for the
+ * strip Chrome paints above it without reporting it
+ * (--navi-keyboard-strip-allowance), which bounds the band the field is brought
+ * into; and room at the end of the scroller, so a field near the end of the
+ * page has somewhere to go. All of it reads 0 while the keyboard does not
+ * overlay.
+ *
+ * Only the arrival is navi's: once the field is in view, Chrome keeps the caret
+ * there itself as typing grows a textarea, against that same
+ * scroll-padding-bottom.
+ */
+
+
+/**
+ * Makes the on-screen keyboard overlay the app instead of shrinking the
+ * viewport, and brings the focused field out from under it. A no-op on
+ * Firefox/Safari, which have no VirtualKeyboard API.
+ *
+ * @returns {() => void} Goes back to the viewport shrinking.
+ */
+const enableVirtualKeyboardOverlay = () => {
+  if (!setVirtualKeyboardOverlaysContent(true)) {
+    return () => {};
+  }
+  // The keyboard rising, or changing height (suggestion strip, emoji panel).
+  const unsubscribeGeometryChange =
+    subscribeVirtualKeyboardGeometryChange(revealFocusedField);
+  // From one field to the next with the keyboard up: when both want the same
+  // keyboard it does not move, and no geometrychange fires.
+  document.addEventListener("focusin", revealFocusedField, { capture: true });
+  return () => {
+    unsubscribeGeometryChange();
+    document.removeEventListener("focusin", revealFocusedField, {
+      capture: true,
+    });
+    setVirtualKeyboardOverlaysContent(false);
+  };
+};
+
+const revealFocusedField = () => {
+  if (getVirtualKeyboardOverlayHeight() === 0) {
+    return;
+  }
+  const field = document.activeElement;
+  if (!isEditableTarget(field)) {
+    return;
+  }
+  if (isInDocumentBand(field)) {
+    return;
+  }
+  // "center" rather than "nearest": nearest stops the field on the band's
+  // edge, clear of the strip only by the allowance. The middle of the band
+  // clears a strip taller than guessed too — and centering what is not fully
+  // visible is what Chrome does itself when the viewport shrinks.
+  scrollIntoViewThroughScrollables(field, {
+    block: "center",
+    behavior: "instant",
+  });
+};
+// The band the document leaves visible: inside its scroll-padding (the bars,
+// the keyboard and its strip, see safe_area.js). Against the window rather
+// than each scroller's own band: the keyboard covers the window, and a field
+// hidden inside its own scroller is what the browser's focus already scrolls
+// to.
+const isInDocumentBand = (field) => {
+  const documentElement = document.documentElement;
+  const style = getComputedStyle(documentElement);
+  const bandTop = parseFloat(style.scrollPaddingTop) || 0;
+  const bandBottom =
+    documentElement.clientHeight - (parseFloat(style.scrollPaddingBottom) || 0);
+  const { top, bottom } = field.getBoundingClientRect();
+  return top >= bandTop && bottom <= bandBottom;
+};
+
 /*
  * - Usage
  * useEffect(() => {
@@ -86791,5 +89576,5 @@ const UserSvg = () => jsx("svg", {
   })
 });
 
-export { ActionRenderer, ActiveKeyboardShortcuts, Address, Badge, BadgeCount, BadgeList, Binder, Box, Button, ButtonCopyToClipboard, CalloutStatusIcon, Caption, CardLayout, CheckSvg, CheckboxGroup, CloseSvg, Code, Col, Colgroup, Color, ConstructionSvg, ControlGroup, ControlSwap, DaySpin, Details, Dialog, Editable, ErrorBoundary, ErrorBoundaryContext, ExclamationSvg, Expandable, EyeClosedSvg, EyeSvg, Field, FixedBar, Form, Group, Head, HeartSvg, HomeSvg, Icon, Image, InfoSvg, Input, InputDuration, Interpolate, Label, Link, LinkAnchorSvg, LinkBlankTargetSvg, LinkCurrentSvg, List, ListItem, ListItemGroup, ListItems, Loading, LoadingDotsSvg, LoadingIndicator, LoadingIndicatorFluid, LoadingOutline, MessageBox, Meter, Nav, NaviDebug, NetworkPolicyError, NumberSpin, Paragraph, Picker, Popover, Popup, Quantity, RadioGroup, Route, RouteTransitionArea, RouteTravel, RowNumberCol, RowNumberTableCell, SVGMaskOverlay, SearchSvg, Select, SelectableInput, SelectionContext, Separator, SettingsSvg, SidePanel, Slide, SlideContainer, Spin, SpinGroup, SplitButton, StarSvg, Step, StepList, SummaryMarker, Svg, Table, TableCell, Tbody, Text, TextBox, Textarea, TextareaCharCount, Thead, Time, TimeRange, TimeRangeSpin, TimeRangeWheel, TimeSpin, TimeWheel, Title, Tr, UITransition, Unit, UserSvg, ViewportLayout, Wheel, WheelGroup, WheelItem, actionRunEffect, anyMatchingRouteSignal, applySearch, arraySignalMembership, canNavBackSignal, canNavForwardSignal, coarsePointerSignal, compareTwoJsValues, constraintFromValidityRule, createAction, createAvailableConstraint, createRequestCanceller, createSearch, createSelectionKeyboardShortcuts, createSlot, defineInteractionDetector, defineRouteDefaultTransition, defineRouteTransition, detectHorizontalOverflow, dispatchRequestSetUIState, enableDebugActions, enableDebugOnDocumentLoading, ensureDocumentStartViewTransition, errorIsDisplayed, filterTableSelection, isCellSelected, isColumnSelected, isNetworkPolicyError, isRowSelected, isScrolling, languagesSignal, localStorageSignal, markAsOutsideTextFlow, markErrorAsDisplayedBy, moveArrayItemByIndex, moveFocusTo, navBack, navForward, navIntegratedVia, navTo, naviI18n, openCallout, preloadUrl, rawUrlPart, registerGlobalConstraint, reload, rerunActions, resource, route, routeAction, routeFallback, scrollActivitySignal, setBaseUrl, setNetworkPolicy, setPreferredLanguage, setSupportedLanguages, setUrlTargetOptions, setupRoutes, smallTouchScreenSignal, stateSignal, stopLoad, stringifyTableSelectionValue, swapArrayItemByIndex, syncOwnedResourceToSignals, syncResourceToSignals, triggerNaviCommand, updateActions, useActionStatus, useArraySignalMembership, useAsyncData, useCalloutElement, useCalloutRequestClose, useCanNavBack, useCanNavForward, useCancelPrevious, useCellGridFromRows, useConstraintValidityState, useDependenciesDiff, useDisplayedLayoutEffect, useDocumentResource, useDocumentState, useDocumentUrl, useEditionController, useFocusGroup, useInputGroup, useKeyboardShortcuts, useNavState, useNetworkPolicyReason, useOrderedColumns, usePickerState, usePopupMode, useRouteStatus, useSearchText, useSelectableElement, useSelectionController, useSignalSync, useSlideContainer, useSlideValue, useStateArray, useTitleLevel, useTransitionCover, useUrlSearchParam, useUrlTargetId, valueInLocalStorage, windowWidthSignal };
+export { ActionRenderer, ActiveKeyboardShortcuts, Address, Badge, BadgeCount, BadgeList, Binder, Box, Button, ButtonCopyToClipboard, CalloutStatusIcon, Caption, CardLayout, CheckSvg, CheckboxGroup, CloseSvg, Code, Col, Colgroup, Color, ConstructionSvg, ControlGroup, ControlSwap, DaySpin, Details, Dialog, Editable, ErrorBoundary, ErrorBoundaryContext, ExclamationSvg, Expandable, EyeClosedSvg, EyeSvg, Field, FixedBar, Form, Group, Head, HeartSvg, HomeSvg, Icon, Image, InfoSvg, Input, InputDuration, Interpolate, Label, Link, LinkAnchorSvg, LinkBlankTargetSvg, LinkCurrentSvg, List, ListItem, ListItemGroup, ListItems, Loading, LoadingDotsSvg, LoadingIndicator, LoadingIndicatorFluid, LoadingOutline, MessageBox, Meter, Nav, NaviDebug, NetworkPolicyError, NumberSpin, Paragraph, Picker, Popover, Popup, Quantity, RadioGroup, Route, RouteTransitionArea, RouteTravel, RowNumberCol, RowNumberTableCell, SVGMaskOverlay, SearchSvg, Select, SelectableInput, SelectionContext, Separator, SettingsSvg, SidePanel, Slide, SlideContainer, Spin, SpinGroup, SplitButton, StarSvg, Step, StepList, SummaryMarker, Svg, Table, TableCell, Tbody, Text, TextBox, Textarea, TextareaCharCount, Thead, Time, TimeRange, TimeRangeSpin, TimeRangeWheel, TimeSpin, TimeWheel, Title, Tr, UITransition, Unit, UserSvg, ViewportLayout, Wheel, WheelGroup, WheelItem, actionRunEffect, anyMatchingRouteSignal, applySearch, arraySignalMembership, canNavBackSignal, canNavForwardSignal, coarsePointerSignal, compareTwoJsValues, constraintFromValidityRule, createAction, createAvailableConstraint, createRequestCanceller, createSearch, createSelectionKeyboardShortcuts, createSlot, defineInteractionDetector, defineRouteDefaultTransition, defineRouteTransition, detectHorizontalOverflow, dispatchRequestSetUIState, enableDebugActions, enableDebugOnDocumentLoading, enableVirtualKeyboardOverlay, ensureDocumentStartViewTransition, errorIsDisplayed, filterTableSelection, getNowHours, getNowHoursRoundedToStep, isCellSelected, isColumnSelected, isNetworkPolicyError, isRowSelected, isScrolling, isToday, languagesSignal, localStorageSignal, markAsOutsideTextFlow, markErrorAsDisplayedBy, moveArrayItemByIndex, moveFocusTo, navBack, navForward, navIntegratedVia, navTo, naviI18n, openCallout, preloadUrl, rawUrlPart, registerGlobalConstraint, reload, rerunActions, resource, route, routeAction, routeFallback, scrollActivitySignal, setBaseUrl, setNetworkPolicy, setPreferredLanguage, setSupportedLanguages, setUrlTargetOptions, setupRoutes, smallTouchScreenSignal, stateSignal, stopLoad, stringifyTableSelectionValue, swapArrayItemByIndex, syncOwnedResourceToSignals, syncResourceToSignals, triggerNaviCommand, updateActions, useActionStatus, useArraySignalMembership, useAsyncData, useCalloutElement, useCalloutRequestClose, useCanNavBack, useCanNavForward, useCancelPrevious, useCellGridFromRows, useConstraintValidityState, useDependenciesDiff, useDisplayedLayoutEffect, useDocumentResource, useDocumentState, useDocumentUrl, useEditionController, useFocusGroup, useInputGroup, useKeyboardShortcuts, useNavState, useNetworkPolicyReason, useOrderedColumns, usePickerState, usePopupMode, useRouteStatus, useSearchText, useSelectableElement, useSelectionController, useSignalSync, useSlideContainer, useSlideValue, useStateArray, useTitleLevel, useTransitionCover, useUrlSearchParam, useUrlTargetId, valueInLocalStorage, windowWidthSignal };
 //# sourceMappingURL=jsenv_navi.js.map