flet-box 1.1.0 → 1.1.2

package/src/utils/fieldFont.js

@@ -0,0 +1,77 @@
+/**
+ * @file fieldFont.js
+ * @description
+ * Keeps a focused text field from zooming the page on iOS.
+ *
+ * WebKit magnifies the whole viewport when a text control whose computed
+ * `font-size` is below 16px takes focus, so typing in a compiled iOS app made
+ * the screen grow and stay deformed. The design sizes here are framework units
+ * (12 / 14 / 16 for `small` / `medium` / `large`), and two of them sit under
+ * that threshold.
+ *
+ * The fix is a floor, not a new size: on iOS the field text is at least 16px
+ * while everything else keeps its rem value. The widget writes the length it
+ * paints with into `--fb-field-font`, so a reader who raises the browser font
+ * still gets a larger field (medium becomes 17.5px at a 20px root) — a flat
+ * `16px` would have shrunk that field instead of merely flooring it.
+ *
+ * The rule arrives in a stylesheet because an inline `font-size` outranks one,
+ * and it is scoped to `html[data-fb-ios]` so every other platform keeps the
+ * design's own sizes. That attribute also gives the regression harness a switch
+ * it can flip without an iPhone.
+ *
+ * @module fieldFont
+ */
+
+/** `id` of the injected tag, so the guard reaches it after HMR or a `document.write`. */
+const STYLE_ID = "fletbox-field-font";
+
+/** WebKit's auto-zoom threshold: a focused control under 16px scales the page. */
+const MIN_FIELD_PX = 16;
+
+/**
+ * Whether these navigator values describe iOS.
+ *
+ * iPadOS 13 and later report a desktop Mac user agent, so the touch points are
+ * what separate an iPad from a MacBook: a Mac reports 0, an iPad reports 5.
+ *
+ * @param {string} [ua] - `navigator.userAgent`.
+ * @param {string} [platform] - `navigator.platform`.
+ * @param {number} [touchPoints] - `navigator.maxTouchPoints`.
+ * @returns {boolean}
+ */
+export const looksLikeIOS = (ua = "", platform = "", touchPoints = 0) => {
+  if (/iPad|iPhone|iPod/.test(ua)) return true;
+  return platform === "MacIntel" && touchPoints > 1;
+};
+
+const runningOnIOS = () =>
+  typeof navigator !== "undefined" &&
+  looksLikeIOS(navigator.userAgent || "", navigator.platform || "", navigator.maxTouchPoints || 0);
+
+const FIELD_FONT_RULE = `html[data-fb-ios] [data-fb-field] input,
+html[data-fb-ios] [data-fb-field] textarea {
+  font-size: max(${MIN_FIELD_PX}px, var(--fb-field-font, 1rem)) !important;
+}`;
+
+/**
+ * Marks the document as iOS and injects the field floor, once.
+ *
+ * The attribute is re-checked on every call because it is what the rule keys
+ * on; the `<style>` tag is the part that must not be duplicated. No-ops outside
+ * a browser, so the package stays importable in Node.
+ *
+ * @returns {void}
+ */
+export function ensureFieldFont() {
+  if (typeof document === "undefined") return;
+  if (runningOnIOS()) document.documentElement.setAttribute("data-fb-ios", "");
+  if (document.getElementById(STYLE_ID)) return;
+
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = FIELD_FONT_RULE;
+  document.head.appendChild(style);
+}
+
+export default ensureFieldFont;

package/src/utils/focusRing.js

@@ -0,0 +1,73 @@
+/**
+ * @file focusRing.js
+ * @description
+ * The one focus indicator the framework paints, injected once per document.
+ *
+ * A ring cannot be an inline style: `:focus-visible` is a *state*, and a state
+ * only exists in a stylesheet. So this module plays the same role for the
+ * keyboard that `styleInjector.js` plays for `@keyframes` and `motion.js` plays
+ * for reduced motion — one owned `<style>` tag in `<head>`, inserted the first
+ * time a widget is created and never again.
+ *
+ * The color is `var(--color-focusRing)`, which `applyPalette` already writes for
+ * every theme token, so the ring moves with the theme without this module
+ * knowing anything about themes. The literal after the comma is the boot
+ * palette's value: it is what a page shows before the first `setTheme`.
+ *
+ * Two deliberate choices:
+ * - `:where(...)` keeps specificity at zero, so a widget or an app that wants a
+ *   different ring overrides it with one class instead of an `!important`.
+ * - The widths are pixels, not rem, and belong with `SHADOW_LEVELS` and the
+ *   hairline `borderWidth` on the list of honest pixels: a 1px ring is invisible
+ *   and a 6px one is a blob, whatever the reader's font size is.
+ *
+ * @module focusRing
+ */
+
+/** `id` of the injected tag, so the guard reaches it after HMR or a `document.write`. */
+const STYLE_ID = "fletbox-focus-ring";
+
+/**
+ * The rule. `[tabindex]:not([tabindex="-1"])` is what makes an element the
+ * engine turned pressable show up here; `-1` is an element that can be focused
+ * by script but is not a stop on the Tab path, and must not announce one.
+ *
+ * The second pair belongs to a composite field (`Input`). Its native `<input>`
+ * is the thing that holds focus, but it is not the thing a person sees: the
+ * field is a wrapper with a border, an icon and maybe a trailing button, and a
+ * ring drawn around the text box alone cuts across that control. So the ring
+ * moves to the wrapper — which is what `data-fb-field` marks — and the inner
+ * box is silenced by a rule, never by an inline `outline` an app could never
+ * override.
+ */
+const FOCUS_RULE = `:where(a[href], button, input, select, textarea, summary, [tabindex]:not([tabindex="-1"])):focus-visible {
+  outline: 2px solid var(--color-focusRing, #1d4ed8);
+  outline-offset: 2px;
+}
+:where([data-fb-field]):has(> input:focus-visible) {
+  outline: 2px solid var(--color-focusRing, #1d4ed8);
+  outline-offset: 2px;
+}
+:where([data-fb-field]) > input:focus-visible {
+  outline: none;
+}`;
+
+/**
+ * Appends the focus rule to `<head>` unless it is already there.
+ *
+ * No-ops outside a browser, like every other document-touching utility here, so
+ * the package stays importable in Node.
+ *
+ * @returns {void}
+ */
+export function ensureFocusRing() {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(STYLE_ID)) return;
+
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = FOCUS_RULE;
+  document.head.appendChild(style);
+}
+
+export default ensureFocusRing;

package/src/utils/focusScope.js

@@ -0,0 +1,113 @@
+/**
+ * @file focusScope.js
+ * @description
+ * The keyboard half of a modal: while a panel is open, Tab walks around *inside*
+ * it, and when it closes focus goes back where it came from.
+ *
+ * Escape already exists in the three overlays — the mouse can dismiss them. What
+ * none of them did was hold the Tab key, so a keyboard user pressing Tab on an
+ * open Modal walked out of the dialog, behind the scrim, into the page they could
+ * no longer see or reach, and had no way back except tabbing through the whole
+ * document. That is the defect this module closes, and it is the reason the three
+ * overlays share one implementation instead of each writing its own listener.
+ *
+ * Deliberately **not** handled here: Escape. Every overlay already listens for it
+ * on `document`, and a second listener would fire the close twice — an `onClose`
+ * that runs twice is a state update that happens twice.
+ *
+ * @module focusScope
+ */
+
+/**
+ * What the browser would let a person land on: HTML's own reachable elements,
+ * plus whatever the engine put on the Tab path. `tabindex="-1"` is excluded —
+ * that is the document's own words for "focusable by script, not a stop".
+ *
+ * @type {string}
+ */
+export const FOCUSABLE_SELECTOR = [
+  "a[href]",
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "summary",
+  '[tabindex]:not([tabindex="-1"])',
+].join(",");
+
+/**
+ * Traps the Tab key inside `container` until the returned function is called.
+ *
+ * @param {HTMLElement} container - The open panel to keep the keyboard in.
+ * @returns {function(): void} Idempotent release: removes the listener and puts
+ *   focus back on whatever was focused before the panel opened. Call it from the
+ *   widget's `onUnmount` disposer like every other registered resource.
+ */
+export function trapFocus(container) {
+  if (typeof document === "undefined" || !container) return () => {};
+
+  const previous = document.activeElement;
+  let released = false;
+
+  // `offsetParent` is null for a `position: fixed` element, which is what every
+  // overlay is, so the usual visibility test would filter out the whole panel.
+  // A box that renders has client rects, hidden or not.
+  const reachable = () =>
+    [...container.querySelectorAll(FOCUSABLE_SELECTOR)].filter(
+      (el) => el.getClientRects().length > 0,
+    );
+
+  const onKeyDown = (event) => {
+    if (event.key !== "Tab") return;
+    const stops = reachable();
+    if (stops.length === 0) {
+      // Nothing to reach: keep the panel itself focused rather than let Tab
+      // escape to the page behind it.
+      event.preventDefault();
+      return;
+    }
+    const first = stops[0];
+    const last = stops[stops.length - 1];
+    const active = document.activeElement;
+
+    if (event.shiftKey && (active === first || active === container)) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && active === last) {
+      event.preventDefault();
+      first.focus();
+    }
+  };
+
+  container.addEventListener("keydown", onKeyDown);
+
+  // A panel with no control in it (an alert with two lines of text) still has to
+  // take the keyboard, or the trap has nothing to hold. `-1` is the honest value:
+  // it is focusable because the dialog is open, not a stop on the Tab path.
+  const stops = reachable();
+  if (stops.length > 0) {
+    stops[0].focus();
+  } else if (!container.hasAttribute("tabindex")) {
+    container.tabIndex = -1;
+    container._focusScopeMadeTabbable = true;
+    container.focus();
+  }
+
+  return () => {
+    if (released) return;
+    released = true;
+    container.removeEventListener("keydown", onKeyDown);
+    if (container._focusScopeMadeTabbable) {
+      container.removeAttribute("tabindex");
+      delete container._focusScopeMadeTabbable;
+    }
+    // Only hand focus back if the element it came from is still there: a route
+    // change that replaced the page while the dialog was open has nothing to go
+    // back to, and focusing a detached node is a silent no-op at best.
+    if (previous && previous.isConnected && typeof previous.focus === "function") {
+      previous.focus();
+    }
+  };
+}
+
+export default trapFocus;

package/src/utils/markdownParser.js

@@ -6,6 +6,7 @@ import { Row } from "../widgets/Row.js";
 import { Icon } from "../widgets/Icon.js";
 import { CodeViewer } from "../widgets/CodeViewer.js";
 import { colors } from "./themes.js";
+import { escapeHtml } from "../helpers/html.js";
 
 // ========== TABLES ==========
 const isTableLine = (line) => {
@@ -346,16 +347,13 @@ export const parseInlineMarkdown = (text) => text;
 /**
  * Escapes HTML special characters to prevent injection when inserting into innerHTML.
  * Converts `& < > " '` to their corresponding HTML entities.
- * @param {string} text - Raw text to escape.
- * @returns {string} HTML-safe string.
+ *
+ * Re-exported from the shared escaper so this module and the widgets that build
+ * HTML share one implementation; the name stays public here because
+ * `parseMarkdown` has always published it.
+ * @type {import("../helpers/html.js").escapeHtml}
  */
-export const escapeHtml = (text) =>
-  String(text)
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&#39;");
+export { escapeHtml };
 
 // Default export
 export default {

package/src/utils/readableInk.js

@@ -1,7 +1,13 @@
 import { color } from "../tools/color.js";
 
+// A fill this code can measure: a hex, an opaque `rgb()`/`hsl()`, or a named color.
+// The `$` anchors the whole alternation, so each branch has to match the *entire*
+// value — the `rgba?\(\s*\d` this file used to carry could only ever match the
+// three-character string "rgb", which made every functional color fall through to
+// the caller's default. An alpha'd fill stays unmeasured on purpose: what reads on
+// it depends on what is behind it.
 const SOLID_COLOR =
-  /^(#[0-9a-f]{3,8}|rgba?\(\s*\d|hsla?\(\s*\d|black|white|red|green|blue|yellow|cyan|magenta|gray|darkgray|lightgray)$/i;
+  /^(#[0-9a-f]{3,8}|rgb\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*\)|hsl\(\s*[\d.]+(?:deg)?\s*,\s*[\d.]+%\s*,\s*[\d.]+%\s*\)|black|white|red|green|blue|yellow|cyan|magenta|gray|darkgray|lightgray)$/i;
 
 /**
  * Black or white, whichever reads better on `background` by WCAG contrast.

package/src/utils/stackLayout.js

@@ -0,0 +1,55 @@
+/**
+ * @file stackLayout.js
+ * @description Makes a `Stack` paint its children in the same box.
+ *
+ * `Stack` is documented as the overlay container and `alignment` as the corner
+ * every child is anchored to. Neither was true: the children arrived in normal
+ * flow, so the second one landed under the first and the only way to actually
+ * layer them was for each child to declare a `position` of its own.
+ *
+ * The rule takes every child but the first out of the flow. The first stays in
+ * it because a Stack with no explicit `width`/`height` has to be sized by
+ * something: with every child floating the box collapses to 0px and the overlay
+ * disappears, which is the same bug wearing a different symptom.
+ *
+ * A floating child that names no edge is placed at the container's `alignment`
+ * point for free — an absolutely positioned child of a flex container takes its
+ * static position from that container's own `justify-content`/`align-items`, so
+ * the nine-point map in `Stack.js` anchors the layers without a second set of
+ * rules. A child that does name an edge (`top`, `right`, …) keeps its own
+ * declaration, and one that declares `position` inline outranks this rule, so
+ * opting back into the flow is possible.
+ *
+ * It lives in a stylesheet instead of on each child because `update({ children })`
+ * rebuilds them: styles written onto the nodes would leave with the nodes, and a
+ * rule reaches whatever arrives next.
+ *
+ * @module stackLayout
+ */
+
+/** `id` of the injected tag, so a guard can count it after HMR. */
+const STYLE_ID = "fletbox-stack";
+
+/** One rule, no lengths: nothing here scales with the root font size. */
+const STACK_RULE = `[data-fb-stack] > :not(:first-child) {
+  position: absolute;
+}`;
+
+/**
+ * Inject the overlay rule, once per document.
+ *
+ * No-ops outside a browser, so the package stays importable in Node.
+ *
+ * @returns {void}
+ */
+export function ensureStackLayout() {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(STYLE_ID)) return;
+
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = STACK_RULE;
+  document.head.appendChild(style);
+}
+
+export default ensureStackLayout;

package/src/utils/styleInjector.js

@@ -14,6 +14,31 @@
 /** Animation names already injected in this document. */
 const injected = new Set();
 
+/**
+ * Stable name derived from a keyframe body.
+ *
+ * `@keyframes` is global, so two effects that build their body from their own
+ * options must not share a name: the first injection would win for both, and a
+ * glow in red would come out blue. Hashing the body gives every distinct
+ * animation its own name and lets identical ones reuse a single `<style>` — the
+ * same rule that keeps `AnimatedText` (one animation per letter) from appending
+ * a tag per letter.
+ *
+ * @param {string} prefix - Human-readable head, e.g. `"glow-pulse"`.
+ * @param {string} frames - The keyframe body that determines the motion.
+ * @returns {string} A CSS-safe identifier, e.g. `"glow-pulse-1a2b3c4d5e"`.
+ */
+export const animationName = (prefix, frames) => {
+  let h1 = 0x811c9dc5;
+  let h2 = 0x01000193;
+  for (let i = 0; i < frames.length; i++) {
+    const c = frames.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 0x01000193);
+    h2 = Math.imul(h2 + c, 0x85ebca6b) ^ (h2 >>> 13);
+  }
+  return `${prefix}-${(h1 >>> 0).toString(36)}${(h2 >>> 0).toString(36)}`;
+};
+
 /**
  * Injects `@keyframes <name> { <frames> }` into `<head>` the first time the
  * given name is requested. Subsequent calls for the same name are no-ops.

package/src/utils/syntaxHighlight.js

@@ -1,6 +1,7 @@
 // utils/syntaxHighlight.js
 import { color } from "../tools/color.js";
 import { getTheme } from "./themes.js";
+import { escapeHtml } from "../helpers/html.js";
 
 // ========== FLETBOX COLORS ==========
 const fletboxColors = {
@@ -387,21 +388,4 @@ export const generateHighlightedHtml = (
   return html;
 };
 
-// ========== ESCAPE HTML ==========
-/**
- * Escapes HTML special characters so that token values can be safely inserted
- * into a `<span>` element's content.
- * @param {string} text - Raw token text.
- * @returns {string} HTML-safe string.
- * @private
- */
-const escapeHtml = (text) => {
-  return text
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&#39;");
-};
-
 export default { tokenize, generateHighlightedHtml, highlightColors, highlightPalettes, syntaxPaletteFor };

package/src/utils/themes.js

@@ -55,6 +55,14 @@ const DEFAULT_COLORS = {
   glass: "rgba(255, 255, 255, 0.66)",
   glassBorder: "rgba(255, 255, 255, 0.75)",
   border: "#e2e8f0",
+  // The ring around whatever the keyboard is on. It is a token for the same
+  // reason the rim is one: the theme has to be able to move it. It answers to
+  // WCAG 2.2's 3:1 against the surface it is drawn on, which `#1d4ed8` clears at
+  // 6.4:1 on this boot page and 6.4:1 on its `surface`. It is deliberately not
+  // `primary`: in both shipped palettes the brand plate is neutral zinc, so a
+  // brand-coloured ring would read as "this is selected" instead of "this is
+  // where my keys are".
+  focusRing: "#1d4ed8",
   gray50: "#f8fafc",
   gray100: "#f1f5f9",
   gray200: "#e2e8f0",
@@ -135,6 +143,10 @@ export const palettes = {
     textSecondary: "#52525b",
     textDisabled: "#a1a1aa",
     border: "#e4e4e7",
+    // The blue is this palette's own `infoStrong`, measured 6.70:1 on the page,
+    // 6.42:1 on `surface` and 6.10:1 on `primaryBg` — over the 3:1 a focus
+    // indicator needs wherever it lands, and never mistaken for the zinc plate.
+    focusRing: "#1d4ed8",
     gray50: "#fafafa",
     gray100: "#f4f4f5",
     gray200: "#e4e4e7",
@@ -211,6 +223,9 @@ export const palettes = {
     textSecondary: "#a1a1aa",
     textDisabled: "#52525b",
     border: "#27272a",
+    // Points the other way down the ladder like every other token here: this is
+    // dark's `infoStrong`, 11.03:1 on the page and 9.82:1 on a card.
+    focusRing: "#93c5fd",
     gray50: "#111111",
     gray100: "#1f1f1f",
     gray200: "#27272a",

package/src/utils/visualEffects.js

@@ -4,21 +4,15 @@
  * @module utils/visualEffects
  */
 
-// Cache for injected keyframes
-const injectedKeyframes = new Set();
+import { prefersReducedMotion, markMotionLoop } from "../animations/motion.js";
+import { injectKeyframes, animationName } from "./styleInjector.js";
 
 /**
- * Inject CSS keyframes if not already injected
- * @param {string} name - Animation name
- * @param {string} keyframes - CSS keyframes
+ * Re-exported for callers that imported it from here before the injection was
+ * centralised: the implementation and the dedupe set are the shared ones in
+ * `utils/styleInjector.js`, never a second set local to this file.
  */
-export const injectKeyframes = (name, keyframes) => {
-  if (injectedKeyframes.has(name)) return;
-  const style = document.createElement("style");
-  style.textContent = `@keyframes ${name} { ${keyframes} }`;
-  document.head.appendChild(style);
-  injectedKeyframes.add(name);
-};
+export { injectKeyframes };
 
 /**
  * Apply stripe pattern to an element
@@ -46,15 +40,20 @@ export const applyStripes = (element, options = {}) => {
   element.style.backgroundSize = `${size * 2}px ${size * 2}px`;
 
   if (animated) {
-    element.style.animation = `progress-stripes ${duration} linear infinite`;
-
-    injectKeyframes(
-      "progress-stripes",
-      `
+    // The body depends on `size`, so the name is derived from it: two stripe
+    // widths are two animations, not one animation whose first width wins.
+    const frames = `
             0% { background-position: 0 0; }
             100% { background-position: ${size * 2}px 0; }
-        `,
-    );
+        `;
+    const name = animationName("stripes", frames);
+    element.style.animation = `${name} ${duration} linear infinite`;
+    // A `infinite` CSS loop is stopped by the media rule, not by a JS check: the
+    // check reads the preference when the effect is applied, so a loop already
+    // running when the reader flips the OS setting would keep running.
+    markMotionLoop(element);
+
+    injectKeyframes(name, frames);
   }
 };
 
@@ -85,15 +84,15 @@ export const applyShimmer = (element, options = {}) => {
         ${baseColor} 100%
     )`;
   element.style.backgroundSize = "200% 100%";
-  element.style.animation = `shimmer ${duration} ease-in-out infinite`;
-
-  injectKeyframes(
-    "shimmer",
-    `
+  const frames = `
         0% { background-position: 200% 0; }
         100% { background-position: -200% 0; }
-    `,
-  );
+    `;
+  const name = animationName("shimmer", frames);
+  element.style.animation = `${name} ${duration} ease-in-out infinite`;
+  markMotionLoop(element);
+
+  injectKeyframes(name, frames);
 };
 
 /**
@@ -107,16 +106,16 @@ export const applyGlow = (element, options = {}) => {
   } = options;
 
   element.style.transition = "box-shadow 0.2s ease";
-  element.style.animation = `glow-pulse ${duration} ease-in-out infinite`;
-
-  injectKeyframes(
-    "glow-pulse",
-    `
+  const frames = `
         0% { box-shadow: 0 0 0 ${color}; }
         50% { box-shadow: 0 0 ${intensity}px ${color}; }
         100% { box-shadow: 0 0 0 ${color}; }
-    `,
-  );
+    `;
+  const name = animationName("glow-pulse", frames);
+  element.style.animation = `${name} ${duration} ease-in-out infinite`;
+  markMotionLoop(element);
+
+  injectKeyframes(name, frames);
 };
 
 /**
@@ -127,16 +126,16 @@ export const applyIndeterminate = (element, options = {}) => {
 
   element.style.position = "relative";
   element.style.width = width;
-  element.style.animation = `indeterminate-progress ${duration} ease-in-out infinite`;
-
-  injectKeyframes(
-    "indeterminate-progress",
-    `
+  const frames = `
         0% { transform: translateX(-100%); }
         50% { transform: translateX(0%); }
         100% { transform: translateX(100%); }
-    `,
-  );
+    `;
+  const name = animationName("indeterminate-progress", frames);
+  element.style.animation = `${name} ${duration} ease-in-out infinite`;
+  markMotionLoop(element);
+
+  injectKeyframes(name, frames);
 };
 
 /**
@@ -145,17 +144,20 @@ export const applyIndeterminate = (element, options = {}) => {
 export const applyPulse = (element, options = {}) => {
   const { scale = 1.05, duration = "0.3s" } = options;
 
-  element.style.transition = `transform ${duration} ease`;
-  element.style.animation = `pulse ${duration} ease-in-out`;
+  // A pulse is decoration saying "look here", so reduced motion removes it rather
+  // than shortening it — the element is left exactly as it was.
+  if (prefersReducedMotion()) return;
 
-  injectKeyframes(
-    "pulse",
-    `
+  element.style.transition = `transform ${duration} ease`;
+  const frames = `
         0% { transform: scale(1); }
         50% { transform: scale(${scale}); }
         100% { transform: scale(1); }
-    `,
-  );
+    `;
+  const name = animationName("pulse", frames);
+  element.style.animation = `${name} ${duration} ease-in-out`;
+
+  injectKeyframes(name, frames);
 };
 
 export default {

package/src/widget-factory/createWidget.js

@@ -1,5 +1,8 @@
 // core/createWidget.js
 
+import { ensureFocusRing } from "../utils/focusRing.js";
+import { ensureFieldFont } from "../utils/fieldFont.js";
+
 /**
  * Creates a bare DOM element for use as a widget.
  *
@@ -8,12 +11,22 @@
  * rely on for listener tracking. No props are applied here — that is the
  * responsibility of `assignProps`.
  *
- * @param {string} tag - HTML tag name for the element (e.g. `'div'`, `'button'`).
+ * It is also where the document gets its focus rule: this is the one step every
+ * widget passes through, and a ring has to be in the stylesheet before anyone
+ * can press Tab.
+ *
+ * The field-font floor rides along for the same reason: it is a document-level
+ * rule about text fields, and this is the only step that runs exactly once per
+ * widget without being owned by any of them.
+ *
+ * @param {string} tag - HTML tag name for the widget.
  *   Defaults to `'div'` when the value is not a string.
- * @param {Object} props - Reserved for future use; currently unused.
  * @returns {HTMLElement} The newly created DOM element with `_events` initialised.
  */
-export const createWidget = (tag, props) => {
+export const createWidget = (tag) => {
+  ensureFocusRing();
+  ensureFieldFont();
+
   // Validateste that tag is a string; fall back to 'div' when it is not.
   let finalTag = tag;
   if (typeof finalTag !== "string") {