@mlola-ui/behavior 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mlola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @mlola-ui/behavior
+
+Framework-free interaction behavior for Mlola UI markup. Standard DOM only: no
+framework, no build step, no runtime peers, and no renderer of its own. Mark a
+root with `data-ml="<behaviour>"` and enhance it, or call `observe()` once and
+let new markup enhance itself.
+
+The decisions themselves — which index a key moves to, where focus goes, what a
+value snaps to — live in `@mlola-ui/behavior/logic` as pure functions, so React
+components and this runtime cannot drift apart.
+
+## Install
+
+```bash
+npm install @mlola-ui/behavior
+```
+
+## Use
+
+```html
+<link rel="stylesheet" href="@mlola-ui/engine" />
+
+<div data-theme="atelier" data-mode="light">
+  <div data-ml="tabs">…</div>
+</div>
+
+<script type="module">
+  import { observe } from "@mlola-ui/behavior";
+  observe();
+</script>
+```
+
+It is idempotent, so it is safe to call after a framework re-render, a turbo
+navigation, or an htmx swap.
+
+## Implemented behaviours
+
+`accordion`, `tabs`, `dropdown-menu`, `select`, `modal`, `sheet`, `tooltip`,
+`toast`, `switch`, `slider` — the same list the engine's `behavior-spec.mjs`
+specifies, checked by the contract audit.
+
+## Exports
+
+| Path | What it is |
+| --- | --- |
+| `@mlola-ui/behavior` | `enhance`, `observe`, `destroy`, `behaviors` |
+| `@mlola-ui/behavior/logic` | pure decisions shared with React |
+
+MIT licensed. Part of [Mlola UI](https://ui.mlola.com).

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@mlola-ui/behavior",
+  "version": "1.0.0",
+  "description": "Framework-free behavior for Mlola UI markup: standard DOM, no runtime peers",
+  "type": "module",
+  "main": "./src/index.js",
+  "sideEffects": false,
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./logic": "./src/logic.js",
+    "./document": "./src/document.js"
+  },
+  "license": "MIT",
+  "author": "Mlola",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mlolahq/mlola-ui.git",
+    "directory": "packages/behavior"
+  },
+  "homepage": "https://ui.mlola.com",
+  "bugs": {
+    "url": "https://github.com/mlolahq/mlola-ui/issues"
+  },
+  "keywords": [
+    "mlola",
+    "ui",
+    "behavior",
+    "framework-free",
+    "dom",
+    "vanilla",
+    "accessibility"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/document.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Lock page scrolling behind an overlay without shifting the layout. Locks
+ * nest and are shared by every copy of the package on the page. Returns an
+ * idempotent release function.
+ */
+export function lockScroll(doc?: Document): () => void;

package/src/document.js

@@ -0,0 +1,67 @@
+/**
+ * Document-level effects that both runtimes need, exactly once.
+ *
+ * A React modal and a framework-free sheet can be open at the same time, and
+ * a page can load two copies of this package. They must still agree on one
+ * scroll lock, so its state lives on <html> (under a registered symbol), not
+ * in a module variable that each copy would have its own of.
+ */
+
+const STATE = Symbol.for("mlola.scrollLock");
+
+/**
+ * Stop the page from scrolling behind an overlay, without the page moving.
+ *
+ * Hiding overflow removes a classic scrollbar, which widens the viewport and
+ * shifts everything sideways. The lock keeps the scrollbar's space instead:
+ * `scrollbar-gutter: stable`, or padding where the page still widened. While locked,
+ * <html> carries `data-ml-scroll-locked` and `--ml-scroll-lock-offset` (the
+ * padding added, 0px with a gutter) for any fixed element that must follow.
+ *
+ * Locks nest. Returns a release function; calling it twice is harmless.
+ */
+export function lockScroll(doc = globalThis.document) {
+  if (!doc?.documentElement) return () => {};
+  const root = doc.documentElement;
+  const state = root[STATE] ?? (root[STATE] = { count: 0, saved: null });
+
+  if (state.count === 0) {
+    const view = doc.defaultView;
+    const width = root.clientWidth;
+    state.saved = {
+      overflow: root.style.overflow,
+      scrollbarGutter: root.style.scrollbarGutter,
+      paddingInlineEnd: root.style.paddingInlineEnd,
+    };
+    root.style.scrollbarGutter = "stable";
+    root.style.overflow = "hidden";
+    // Not every engine keeps the gutter for every scrollbar (custom
+    // scrollbars, older engines), so measure instead of trusting it: if the
+    // page still widened, give the lost width back as padding.
+    const widened = root.clientWidth - width;
+    let offset = 0;
+    if (widened > 0 && view) {
+      root.style.scrollbarGutter = state.saved.scrollbarGutter;
+      const current = Number.parseFloat(view.getComputedStyle(root).paddingInlineEnd) || 0;
+      root.style.paddingInlineEnd = `${current + widened}px`;
+      offset = widened;
+    }
+    root.style.setProperty("--ml-scroll-lock-offset", `${offset}px`);
+    root.setAttribute("data-ml-scroll-locked", "");
+  }
+  state.count += 1;
+
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    state.count = Math.max(0, state.count - 1);
+    if (state.count > 0 || !state.saved) return;
+    root.style.overflow = state.saved.overflow;
+    root.style.scrollbarGutter = state.saved.scrollbarGutter;
+    root.style.paddingInlineEnd = state.saved.paddingInlineEnd;
+    root.style.removeProperty("--ml-scroll-lock-offset");
+    root.removeAttribute("data-ml-scroll-locked");
+    state.saved = null;
+  };
+}

package/src/index.js

@@ -0,0 +1,620 @@
+/**
+ * Mlola behaviour: the library's interactions without a framework.
+ *
+ * Built to still work in ten years, which drove every choice here:
+ *
+ *   - Standard DOM only. No framework, no bundler, no transpiler. This file is
+ *     a plain ES module and runs from a <script type="module"> as it is.
+ *   - Progressive enhancement over ownership. Markup comes first, from React,
+ *     Svelte, Rails, a Go template or a static file, and behaviour attaches to
+ *     it. Nothing here renders HTML, so nothing here can disagree with it.
+ *   - Attribute driven, matching the contract the stylesheet already reads.
+ *     Behaviour sets the same data-* and aria-* the CSS reacts to.
+ *   - Idempotent. Enhancing twice is a no-op, so it is safe to call after a
+ *     framework re-render, a turbo navigation or an htmx swap.
+ *
+ * Mark a root with data-ml="<behaviour>" and call enhance(), or call observe()
+ * once and let new markup enhance itself.
+ */
+
+import {
+  clampToStep,
+  focusTrapIndex,
+  percentOf,
+  rovingIndex,
+  sliderValueForKey,
+  valueFromRatio,
+} from "./logic.js";
+import { lockScroll } from "./document.js";
+
+const ENHANCED = "__mlolaEnhanced";
+
+const FOCUSABLE = [
+  "a[href]",
+  "button:not([disabled])",
+  "input:not([disabled]):not([type='hidden'])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  "[tabindex]:not([tabindex='-1'])",
+].join(",");
+
+function focusable(root) {
+  return [...root.querySelectorAll(FOCUSABLE)].filter(
+    (element) => element.offsetWidth > 0 || element.offsetHeight > 0 || element === document.activeElement,
+  );
+}
+
+function on(target, type, handler, options) {
+  target.addEventListener(type, handler, options);
+  return () => target.removeEventListener(type, handler, options);
+}
+
+/** Element-shaped wrapper over the shared rovingIndex decision. */
+function roving(items, index, key, options = {}) {
+  return rovingIndex(items.length, index, key, {
+    ...options,
+    enabled: (at) =>
+      !items[at].disabled && items[at].getAttribute("aria-disabled") !== "true",
+  });
+}
+
+const behaviors = {
+  accordion(root) {
+    const multiple = root.dataset.mlMultiple === "true";
+    const collapsible = root.dataset.mlCollapsible !== "false";
+    const items = () => [...root.querySelectorAll(".ml-accordion-item")];
+    const triggers = () => [...root.querySelectorAll(".ml-accordion-trigger")];
+
+    const setOpen = (item, open) => {
+      const trigger = item.querySelector(".ml-accordion-trigger");
+      const panel = item.querySelector(".ml-accordion-panel");
+      const state = open ? "open" : "closed";
+      item.dataset.state = state;
+      if (trigger) {
+        trigger.dataset.state = state;
+        trigger.setAttribute("aria-expanded", String(open));
+      }
+      if (panel) {
+        panel.dataset.state = state;
+        panel.hidden = !open;
+      }
+    };
+
+    const toggle = (item) => {
+      const open = item.dataset.state === "open";
+      if (open && !collapsible) return;
+      if (!multiple && !open) {
+        for (const other of items()) if (other !== item) setOpen(other, false);
+      }
+      setOpen(item, !open);
+    };
+
+    return [
+      on(root, "click", (event) => {
+        const trigger = event.target.closest(".ml-accordion-trigger");
+        if (trigger && root.contains(trigger)) toggle(trigger.closest(".ml-accordion-item"));
+      }),
+      on(root, "keydown", (event) => {
+        const trigger = event.target.closest(".ml-accordion-trigger");
+        if (!trigger) return;
+        const all = triggers();
+        const index = all.indexOf(trigger);
+        const target = roving(all, index, event.key, { horizontal: false });
+        if (target >= 0) {
+          event.preventDefault();
+          all[target].focus();
+        }
+      }),
+    ];
+  },
+
+  tabs(root) {
+    const horizontal = root.dataset.orientation !== "vertical";
+    const triggers = () => [...root.querySelectorAll(".ml-tabs-trigger")];
+
+    const select = (trigger) => {
+      for (const other of triggers()) {
+        const active = other === trigger;
+        other.dataset.state = active ? "active" : "inactive";
+        other.setAttribute("aria-selected", String(active));
+        other.tabIndex = active ? 0 : -1;
+        const panel = document.getElementById(other.getAttribute("aria-controls") ?? "");
+        if (panel) {
+          panel.dataset.state = active ? "active" : "inactive";
+          panel.hidden = !active;
+        }
+      }
+    };
+
+    return [
+      on(root, "click", (event) => {
+        const trigger = event.target.closest(".ml-tabs-trigger");
+        if (trigger && root.contains(trigger) && !trigger.disabled) select(trigger);
+      }),
+      on(root, "keydown", (event) => {
+        const trigger = event.target.closest(".ml-tabs-trigger");
+        if (!trigger) return;
+        const all = triggers();
+        const target = roving(all, all.indexOf(trigger), event.key, { horizontal });
+        if (target < 0) return;
+        event.preventDefault();
+        all[target].focus();
+        select(all[target]);
+      }),
+    ];
+  },
+
+  "dropdown-menu": (root) => {
+    const trigger = root.querySelector(".ml-dropdown-trigger");
+    const menu = root.querySelector(".ml-dropdown-menu");
+    if (!trigger || !menu) return [];
+    const items = () =>
+      [...menu.querySelectorAll(".ml-dropdown-item")].filter(
+        (item) => !item.disabled && item.getAttribute("aria-disabled") !== "true",
+      );
+
+    const setOpen = (open) => {
+      root.dataset.state = open ? "open" : "closed";
+      menu.dataset.state = open ? "open" : "closed";
+      menu.hidden = !open;
+      trigger.setAttribute("aria-expanded", String(open));
+      if (!open) for (const item of items()) delete item.dataset.highlighted;
+    };
+    const isOpen = () => root.dataset.state === "open";
+
+    const highlight = (item) => {
+      for (const other of items()) delete other.dataset.highlighted;
+      if (item) {
+        item.dataset.highlighted = "";
+        item.focus();
+      }
+    };
+
+    setOpen(false);
+
+    return [
+      on(trigger, "click", () => setOpen(!isOpen())),
+      on(root, "keydown", (event) => {
+        const all = items();
+        if (event.key === "Escape") {
+          setOpen(false);
+          trigger.focus();
+          return;
+        }
+        if (event.key === "Tab") {
+          setOpen(false);
+          return;
+        }
+        if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+          event.preventDefault();
+          if (!isOpen()) {
+            setOpen(true);
+            highlight(all[event.key === "ArrowDown" ? 0 : all.length - 1]);
+            return;
+          }
+          const current = all.findIndex((item) => "highlighted" in item.dataset);
+          const target = roving(all, current, event.key, { horizontal: false });
+          if (target >= 0) highlight(all[target]);
+        }
+      }),
+      on(menu, "pointermove", (event) => {
+        const item = event.target.closest(".ml-dropdown-item");
+        if (item && items().includes(item)) highlight(item);
+      }),
+      on(document, "pointerdown", (event) => {
+        if (isOpen() && !root.contains(event.target)) setOpen(false);
+      }),
+    ];
+  },
+
+  switch: (root) => {
+    const set = (on_) => {
+      root.setAttribute("aria-checked", String(on_));
+      root.dataset.state = on_ ? "checked" : "unchecked";
+    };
+    if (!root.hasAttribute("aria-checked")) set(false);
+    return [
+      on(root, "click", () => set(root.getAttribute("aria-checked") !== "true")),
+      on(root, "keydown", (event) => {
+        if (event.key !== "Enter" && event.key !== " ") return;
+        event.preventDefault();
+        set(root.getAttribute("aria-checked") !== "true");
+      }),
+    ];
+  },
+
+  /** Shared by modal and sheet: they differ only in which edge they sit on. */
+  modal(root) {
+    const closeOnEscape = root.dataset.mlEscape !== "false";
+    const closeOnOverlay = root.dataset.mlOverlay !== "false";
+    let opener = null;
+    let releaseScroll = () => {};
+
+    const overlay = () =>
+      document.querySelector(`.ml-modal-overlay[data-ml-for="${root.id}"], .ml-sheet-overlay[data-ml-for="${root.id}"]`);
+
+    const close = () => {
+      root.dataset.state = "closed";
+      root.hidden = true;
+      const layer = overlay();
+      if (layer) layer.hidden = true;
+      releaseScroll();
+      releaseScroll = () => {};
+      if (opener && document.contains(opener)) opener.focus();
+    };
+
+    const open = (from) => {
+      opener = from ?? document.activeElement;
+      root.dataset.state = "open";
+      root.hidden = false;
+      const layer = overlay();
+      if (layer) layer.hidden = false;
+      releaseScroll();
+      releaseScroll = lockScroll();
+      (focusable(root)[0] ?? root).focus();
+    };
+
+    root.mlolaDialog = { open, close };
+
+    return [
+      on(document, "click", (event) => {
+        const opener_ = event.target.closest(`[data-ml-opens="${root.id}"]`);
+        if (opener_) {
+          event.preventDefault();
+          open(opener_);
+          return;
+        }
+        if (root.querySelector(".ml-modal-close, .ml-sheet-close")?.contains(event.target)) close();
+        if (closeOnOverlay && event.target === overlay()) close();
+      }),
+      on(document, "keydown", (event) => {
+        if (root.hidden) return;
+        if (event.key === "Escape" && closeOnEscape) {
+          event.preventDefault();
+          close();
+          return;
+        }
+        if (event.key !== "Tab") return;
+        const items = focusable(root);
+        const target = focusTrapIndex(
+          items.length,
+          items.indexOf(document.activeElement),
+          event.shiftKey,
+        );
+        if (target < 0) return;
+        event.preventDefault();
+        items[target].focus();
+      }),
+    ];
+  },
+
+  select(root) {
+    const trigger = root.querySelector(".ml-select");
+    const popover = root.querySelector(".ml-select-popover");
+    const list = root.querySelector(".ml-select-list");
+    if (!trigger || !popover || !list) return [];
+    const multiple = list.getAttribute("aria-multiselectable") === "true";
+    const options = () =>
+      [...list.querySelectorAll(".ml-select-option")].filter(
+        (option) => option.getAttribute("aria-disabled") !== "true",
+      );
+
+    const setOpen = (open) => {
+      trigger.dataset.state = open ? "open" : "closed";
+      popover.hidden = !open;
+      trigger.setAttribute("aria-expanded", String(open));
+      if (!open) {
+        for (const option of options()) delete option.dataset.highlighted;
+        trigger.removeAttribute("aria-activedescendant");
+      }
+    };
+    const isOpen = () => trigger.dataset.state === "open";
+
+    const highlight = (option) => {
+      for (const other of options()) delete other.dataset.highlighted;
+      if (!option) return;
+      option.dataset.highlighted = "";
+      if (option.id) trigger.setAttribute("aria-activedescendant", option.id);
+    };
+
+    const choose = (option) => {
+      if (!option) return;
+      const chosen = option.getAttribute("aria-selected") === "true";
+      if (!multiple) {
+        for (const other of options()) {
+          other.setAttribute("aria-selected", "false");
+          other.dataset.state = "unchecked";
+        }
+      }
+      const next = multiple ? !chosen : true;
+      option.setAttribute("aria-selected", String(next));
+      option.dataset.state = next ? "checked" : "unchecked";
+      const value = root.querySelector(".ml-select-value");
+      if (value && !multiple) value.textContent = option.textContent.trim();
+      if (!multiple) {
+        setOpen(false);
+        trigger.focus();
+      }
+    };
+
+    setOpen(false);
+
+    return [
+      on(trigger, "click", () => setOpen(!isOpen())),
+      on(list, "click", (event) => choose(event.target.closest(".ml-select-option"))),
+      on(list, "pointermove", (event) => {
+        const option = event.target.closest(".ml-select-option");
+        if (option && options().includes(option)) highlight(option);
+      }),
+      on(root, "keydown", (event) => {
+        const all = options();
+        if (event.key === "Escape") {
+          setOpen(false);
+          trigger.focus();
+          return;
+        }
+        if (event.key === "Tab") {
+          setOpen(false);
+          return;
+        }
+        if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+          event.preventDefault();
+          if (!isOpen()) {
+            setOpen(true);
+            highlight(all[event.key === "ArrowDown" ? 0 : all.length - 1]);
+            return;
+          }
+          const current = all.findIndex((option) => "highlighted" in option.dataset);
+          const target = roving(all, current, event.key, { horizontal: false });
+          if (target >= 0) highlight(all[target]);
+          return;
+        }
+        if (event.key === "Home" || event.key === "End") {
+          if (!isOpen()) return;
+          event.preventDefault();
+          highlight(event.key === "Home" ? all[0] : all[all.length - 1]);
+          return;
+        }
+        if (event.key === "Enter" || (event.key === " " && event.target !== root.querySelector(".ml-select-search"))) {
+          event.preventDefault();
+          if (!isOpen()) {
+            setOpen(true);
+            return;
+          }
+          choose(all.find((option) => "highlighted" in option.dataset));
+        }
+      }),
+      on(document, "pointerdown", (event) => {
+        if (isOpen() && !root.contains(event.target)) setOpen(false);
+      }),
+    ];
+  },
+
+  slider(root) {
+    const track = root.querySelector(".ml-slider-track");
+    const range = root.querySelector(".ml-slider-range");
+    const thumb = root.querySelector(".ml-slider-thumb");
+    // The value lives on whichever element carries role="slider"; the React
+    // build puts it on the control, hand-written markup often uses the thumb.
+    const valued = root.querySelector('[role="slider"]');
+    if (!track || !valued) return [];
+
+    const bounds = () => ({
+      min: Number(valued.getAttribute("aria-valuemin") ?? 0),
+      max: Number(valued.getAttribute("aria-valuemax") ?? 100),
+      step: Number(root.dataset.mlStep ?? 1),
+    });
+    const disabled = root.dataset.disabled !== undefined || valued.getAttribute("aria-disabled") === "true";
+    const output = root.querySelector(".ml-slider-output");
+    const current = () => Number(valued.getAttribute("aria-valuenow") ?? bounds().min);
+
+    const set = (raw) => {
+      const box = bounds();
+      const next = clampToStep(raw, box);
+      valued.setAttribute("aria-valuenow", String(next));
+      const percent = percentOf(next, box);
+      if (range) range.style.width = `${percent}%`;
+      if (thumb) thumb.style.left = `${percent}%`;
+      if (output) output.textContent = String(next);
+      root.dispatchEvent(new CustomEvent("ml-change", { detail: { value: next }, bubbles: true }));
+    };
+
+    const fromPointer = (event) => {
+      const box = track.getBoundingClientRect();
+      if (!box.width) return current();
+      return valueFromRatio((event.clientX - box.left) / box.width, bounds());
+    };
+
+    let dragging = false;
+
+    return [
+      on(track, "pointerdown", (event) => {
+        if (disabled) return;
+        dragging = true;
+        track.setPointerCapture?.(event.pointerId);
+        set(fromPointer(event));
+        valued.focus();
+      }),
+      on(track, "pointermove", (event) => {
+        if (dragging && !disabled) set(fromPointer(event));
+      }),
+      on(track, "pointerup", (event) => {
+        dragging = false;
+        track.releasePointerCapture?.(event.pointerId);
+      }),
+      on(valued, "keydown", (event) => {
+        if (disabled) return;
+        const next = sliderValueForKey(event.key, current(), bounds());
+        if (next === undefined) return;
+        event.preventDefault();
+        set(next);
+      }),
+    ];
+  },
+
+  tooltip(root) {
+    const tip = root.querySelector(".ml-tooltip");
+    const trigger = root.firstElementChild;
+    if (!tip || !trigger) return [];
+    const delay = Number(root.dataset.mlDelay ?? 200);
+    let timer = null;
+
+    const show = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        tip.hidden = false;
+        tip.dataset.state = "open";
+        if (tip.id) trigger.setAttribute("aria-describedby", tip.id);
+      }, Math.max(0, delay));
+    };
+    const hide = () => {
+      clearTimeout(timer);
+      tip.hidden = true;
+      delete tip.dataset.state;
+      trigger.removeAttribute("aria-describedby");
+    };
+
+    hide();
+
+    return [
+      on(root, "pointerenter", show),
+      on(root, "pointerleave", hide),
+      on(root, "focusin", show),
+      on(root, "focusout", hide),
+      on(document, "keydown", (event) => {
+        if (event.key === "Escape") hide();
+      }),
+    ];
+  },
+
+  toast(root) {
+    const timers = new Map();
+    const durationOf = (toast) =>
+      Number(toast.dataset.mlDuration ?? root.dataset.mlDuration ?? 5000);
+
+    const dismiss = (toast) => {
+      const timer = timers.get(toast);
+      if (timer) clearTimeout(timer);
+      timers.delete(toast);
+      toast.remove();
+      if (!root.querySelector(".ml-toast")) {
+        root.dispatchEvent(new CustomEvent("ml-empty", { bubbles: true }));
+      }
+    };
+
+    const schedule = (toast) => {
+      if ("mlPaused" in toast.dataset) return;
+      const duration = durationOf(toast);
+      const existing = timers.get(toast);
+      if (existing) clearTimeout(existing);
+      if (!(duration > 0)) return;
+      timers.set(
+        toast,
+        setTimeout(() => dismiss(toast), duration),
+      );
+    };
+
+    const register = (toast) => {
+      if (toast.dataset.mlEnhanced !== undefined) return;
+      toast.dataset.mlEnhanced = "";
+      schedule(toast);
+    };
+
+    const existing = () => [...root.querySelectorAll(".ml-toast")];
+    if (!root.hasAttribute("role")) root.setAttribute("role", "region");
+    for (const toast of existing()) register(toast);
+
+    const observer = new MutationObserver((records) => {
+      for (const record of records) {
+        for (const node of record.addedNodes) {
+          if (node.nodeType !== 1) continue;
+          const added = node.matches?.(".ml-toast")
+            ? [node, ...node.querySelectorAll(".ml-toast")]
+            : [...node.querySelectorAll(".ml-toast")];
+          for (const toast of added) register(toast);
+        }
+      }
+    });
+    observer.observe(root, { childList: true, subtree: true });
+
+    return [
+      on(root, "click", (event) => {
+        const toast = event.target.closest(".ml-toast");
+        if (!toast || !root.contains(toast)) return;
+        if (event.target.closest(".ml-toast-close")) {
+          event.preventDefault();
+          dismiss(toast);
+        }
+      }),
+      on(root, "pointerenter", (event) => {
+        const toast = event.target.closest(".ml-toast");
+        if (toast) { toast.dataset.mlPaused = ""; schedule(toast); }
+      }, true),
+      on(root, "pointerleave", (event) => {
+        const toast = event.target.closest(".ml-toast");
+        if (toast) { delete toast.dataset.mlPaused; schedule(toast); }
+      }, true),
+      on(root, "focusin", (event) => {
+        const toast = event.target.closest(".ml-toast");
+        if (toast) { toast.dataset.mlPaused = ""; schedule(toast); }
+      }),
+      on(root, "focusout", (event) => {
+        const toast = event.target.closest(".ml-toast");
+        if (toast) { delete toast.dataset.mlPaused; schedule(toast); }
+      }),
+      () => {
+        observer.disconnect();
+        for (const timer of timers.values()) clearTimeout(timer);
+      },
+    ];
+  },
+};
+
+// A modal and a sheet differ only in which edge the panel sits on, so they
+// share one implementation rather than drifting apart.
+behaviors.sheet = behaviors.modal;
+
+/** Attach behaviour to every marked root inside `scope`. Safe to call again. */
+export function enhance(scope = document) {
+  const roots = [
+    ...(scope.matches?.("[data-ml]") ? [scope] : []),
+    ...scope.querySelectorAll("[data-ml]"),
+  ];
+  let count = 0;
+  for (const root of roots) {
+    if (root[ENHANCED]) continue;
+    const behavior = behaviors[root.dataset.ml];
+    if (!behavior) continue;
+    const teardown = behavior(root) ?? [];
+    root[ENHANCED] = () => {
+      for (const off of teardown) off();
+      delete root[ENHANCED];
+    };
+    count += 1;
+  }
+  return count;
+}
+
+/** Undo enhancement, for hot reloads and tests. */
+export function destroy(scope = document) {
+  for (const root of scope.querySelectorAll("[data-ml]")) root[ENHANCED]?.();
+}
+
+/** Enhance now and keep enhancing markup added later. Returns a stop function. */
+export function observe(scope = document) {
+  enhance(scope);
+  const observer = new MutationObserver((records) => {
+    for (const record of records) {
+      for (const node of record.addedNodes) {
+        if (node.nodeType === 1) enhance(node);
+      }
+    }
+  });
+  observer.observe(scope === document ? document.documentElement : scope, {
+    childList: true,
+    subtree: true,
+  });
+  return () => observer.disconnect();
+}
+
+export { behaviors };

package/src/logic.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Types for the shared decision functions.
+ *
+ * The implementation stays plain JavaScript on purpose: it must run from a
+ * script tag with no build step, in ten years, without a compiler. This
+ * declaration file gives TypeScript callers the same guarantees without
+ * making the runtime depend on a toolchain.
+ */
+
+export interface Bounds {
+  min?: number;
+  max?: number;
+  step?: number;
+}
+
+export interface RovingOptions {
+  horizontal?: boolean;
+  wrap?: boolean;
+  enabled?: (index: number) => boolean;
+}
+
+export interface DisclosureOptions {
+  multiple?: boolean;
+  collapsible?: boolean;
+}
+
+export function clampToStep(raw: number, bounds?: Bounds): number;
+export function valueFromRatio(ratio: number, bounds?: Bounds): number;
+export function percentOf(value: number, bounds?: Pick<Bounds, "min" | "max">): number;
+export function sliderValueForKey(
+  key: string,
+  current: number,
+  bounds?: Bounds,
+): number | undefined;
+export function rovingIndex(
+  count: number,
+  index: number,
+  key: string,
+  options?: RovingOptions,
+): number;
+export function focusTrapIndex(count: number, activeIndex: number, shiftKey: boolean): number;
+export function resolveDisclosure(
+  open: number[],
+  index: number,
+  options?: DisclosureOptions,
+): number[];
+
+export interface PasswordStrengthOptions {
+  /** Below this length the result is always "weak". */
+  min?: number;
+  /** At or above this length (with enough variety) the result is "strong". */
+  strong?: number;
+}
+
+export type PasswordStrength = "empty" | "weak" | "medium" | "strong";
+export function passwordStrength(
+  value: string,
+  options?: PasswordStrengthOptions,
+): PasswordStrength;
+
+/** Deliberately simple, non-authoritative shape check shared by every form. */
+export function isEmail(value: string): boolean;
+
+export interface RevealOptions {
+  /** Steady reading rate. */
+  charsPerSecond?: number;
+  /** The longest a backlog may take to clear, in milliseconds. */
+  catchUpMs?: number;
+}
+/** How much of a streamed text to show after `elapsedMs`. Fractional. */
+export function revealLength(shown: number, target: number, elapsedMs: number, options?: RevealOptions): number;
+
+export function isPinnedToEnd(scrollTop: number, scrollHeight: number, clientHeight: number, threshold?: number): boolean;
+
+export interface ComposerKey {
+  key: string;
+  shiftKey?: boolean;
+  metaKey?: boolean;
+  ctrlKey?: boolean;
+  altKey?: boolean;
+  isComposing?: boolean;
+  keyCode?: number;
+}
+export type ComposerSubmitOn = "enter" | "mod-enter";
+export function composerKeyAction(event: ComposerKey, options?: { submitOn?: ComposerSubmitOn }): "submit" | "newline" | null;
+
+export function smoothLevel(previous: number, next: number, options?: { attack?: number; release?: number }): number;
+export function spectrumToLevels(bins: ArrayLike<number>, count: number, options?: { floor?: number; gain?: number }): number[];
+
+export function formatDuration(ms: number): string;
+export function formatTokens(count: number): string;
+
+export type ConfidenceBand = "low" | "medium" | "high";
+export function confidenceBand(value: number, options?: { low?: number; high?: number }): ConfidenceBand;
+
+export interface ContextSegment {
+  id: string;
+  label: string;
+  tokens: number;
+}
+export interface ContextUsage<Segment extends ContextSegment = ContextSegment> {
+  used: number;
+  limit: number;
+  remaining: number;
+  ratio: number;
+  level: "ok" | "warning" | "critical";
+  segments: Array<Segment & { ratio: number }>;
+}
+export function contextUsage<Segment extends ContextSegment>(
+  segments: Segment[],
+  limit: number,
+  options?: { warning?: number; critical?: number },
+): ContextUsage<Segment>;

package/src/logic.js

@@ -0,0 +1,298 @@
+/**
+ * The decisions, with no DOM and no framework.
+ *
+ * A framework-free runtime mutates the DOM; React renders it from state. Those
+ * two cannot share mutations without fighting over who owns the document. What
+ * they can share — and must, or they drift — is the reasoning: which index a
+ * key moves to, what a value snaps to, where focus goes next.
+ *
+ * Everything here is a pure function over numbers and plain data. It runs in a
+ * browser, in Node, in a test, and it will keep running long after any
+ * particular framework stops being fashionable.
+ */
+
+/** Round to the precision the step implies, so 0.1 steps do not drift. */
+function toStepPrecision(value, step) {
+  const decimals = (String(step).split(".")[1] ?? "").length;
+  return Number(value.toFixed(Math.min(decimals, 10)));
+}
+
+/** Clamp into range and snap onto the step grid measured from `min`. */
+export function clampToStep(raw, { min = 0, max = 100, step = 1 } = {}) {
+  const low = Number.isFinite(min) ? min : 0;
+  const high = Number.isFinite(max) && max > low ? max : low + 100;
+  const increment = Number.isFinite(step) && step > 0 ? step : 1;
+  const value = Number.isFinite(raw) ? raw : low;
+  const clamped = Math.min(high, Math.max(low, value));
+  const snapped = low + Math.round((clamped - low) / increment) * increment;
+  return toStepPrecision(Math.min(high, Math.max(low, snapped)), increment);
+}
+
+/** Turn a 0..1 position along a track into a value in range. */
+export function valueFromRatio(ratio, { min = 0, max = 100, step = 1 } = {}) {
+  const low = Number.isFinite(min) ? min : 0;
+  const high = Number.isFinite(max) && max > low ? max : low + 100;
+  const safe = Number.isFinite(ratio) ? Math.min(1, Math.max(0, ratio)) : 0;
+  return clampToStep(low + safe * (high - low), { min: low, max: high, step });
+}
+
+/** Percentage along the track, for positioning a range fill and a thumb. */
+export function percentOf(value, { min = 0, max = 100 } = {}) {
+  const low = Number.isFinite(min) ? min : 0;
+  const high = Number.isFinite(max) && max > low ? max : low + 100;
+  if (high === low) return 0;
+  return ((Math.min(high, Math.max(low, value)) - low) / (high - low)) * 100;
+}
+
+/**
+ * The value a key produces, or undefined when the key means nothing here.
+ * Returning undefined rather than the current value lets a caller know whether
+ * to call preventDefault.
+ */
+export function sliderValueForKey(key, current, { min = 0, max = 100, step = 1 } = {}) {
+  const low = Number.isFinite(min) ? min : 0;
+  const high = Number.isFinite(max) && max > low ? max : low + 100;
+  const increment = Number.isFinite(step) && step > 0 ? step : 1;
+  const page = Math.max(increment, (high - low) / 10);
+  const moves = {
+    ArrowLeft: -increment,
+    ArrowDown: -increment,
+    ArrowRight: increment,
+    ArrowUp: increment,
+    PageDown: -page,
+    PageUp: page,
+  };
+  if (key === "Home") return clampToStep(low, { min: low, max: high, step: increment });
+  if (key === "End") return clampToStep(high, { min: low, max: high, step: increment });
+  const delta = moves[key];
+  if (delta === undefined) return undefined;
+  return clampToStep(current + delta, { min: low, max: high, step: increment });
+}
+
+/**
+ * Where a roving-focus key lands. `enabled` reports whether an index may take
+ * focus, so disabled entries are stepped over rather than landed on.
+ * Returns -1 when the key does not move focus.
+ */
+export function rovingIndex(
+  count,
+  index,
+  key,
+  { horizontal = true, wrap = true, enabled = () => true } = {},
+) {
+  if (count <= 0) return -1;
+  const firstEnabled = (from, direction) => {
+    let candidate = from;
+    for (let steps = 0; steps < count; steps += 1) {
+      if (enabled(candidate)) return candidate;
+      candidate += direction;
+      if (candidate < 0) candidate = count - 1;
+      if (candidate >= count) candidate = 0;
+    }
+    return -1;
+  };
+
+  if (key === "Home") return firstEnabled(0, 1);
+  if (key === "End") return firstEnabled(count - 1, -1);
+
+  const forward = horizontal ? "ArrowRight" : "ArrowDown";
+  const backward = horizontal ? "ArrowLeft" : "ArrowUp";
+  const step = key === forward ? 1 : key === backward ? -1 : 0;
+  if (!step) return -1;
+
+  let candidate = index;
+  for (let steps = 0; steps < count; steps += 1) {
+    candidate += step;
+    if (candidate < 0) {
+      if (!wrap) return -1;
+      candidate = count - 1;
+    }
+    if (candidate >= count) {
+      if (!wrap) return -1;
+      candidate = 0;
+    }
+    if (enabled(candidate)) return candidate;
+  }
+  return -1;
+}
+
+/**
+ * The index Tab should move to inside a trap, or -1 to let the browser handle
+ * it. Only the edges need intercepting; everything between them is natural.
+ */
+export function focusTrapIndex(count, activeIndex, shiftKey) {
+  if (count <= 0) return -1;
+  if (shiftKey && activeIndex <= 0) return count - 1;
+  if (!shiftKey && activeIndex === count - 1) return 0;
+  return -1;
+}
+
+/** Which items stay open after toggling `index`. */
+export function resolveDisclosure(open, index, { multiple = false, collapsible = true } = {}) {
+  const isOpen = open.includes(index);
+  if (isOpen && !collapsible && !multiple) return open;
+  if (multiple) {
+    return isOpen ? open.filter((entry) => entry !== index) : [...open, index].sort((a, b) => a - b);
+  }
+  if (isOpen) return collapsible ? [] : open;
+  return [index];
+}
+
+/**
+ * A coarse password-strength hint, deliberately not authoritative. It exists so
+ * React and framework-free markup show the same label for the same input, not
+ * to grade a real password. Length dominates; character variety nudges it.
+ */
+export function passwordStrength(value, { min = 8, strong = 12 } = {}) {
+  const text = typeof value === "string" ? value : "";
+  if (!text) return "empty";
+  const variety =
+    (/[a-z]/.test(text) ? 1 : 0) +
+    (/[A-Z]/.test(text) ? 1 : 0) +
+    (/\d/.test(text) ? 1 : 0) +
+    (/[^A-Za-z0-9]/.test(text) ? 1 : 0);
+  const score = text.length + variety * 2;
+  if (text.length < min) return "weak";
+  if (text.length < strong || score < strong + 2) return "medium";
+  return "strong";
+}
+
+/**
+ * A deliberately simple email shape check, shared by every form so the rule is
+ * one rule. It is not a validator: the server is the authority on deliverable
+ * addresses, and rejecting a valid-but-unusual address is worse than sending.
+ */
+export function isEmail(value) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(typeof value === "string" ? value.trim() : "");
+}
+
+/* ── AI interfaces ────────────────────────────────────────────────────── */
+
+/**
+ * How much of a streamed text to show after `elapsedMs`.
+ *
+ * Models deliver text in uneven bursts: nothing for 300 ms, then forty words.
+ * Rendering bursts as they land reads as stutter. The reveal instead moves at
+ * a steady reading rate, and speeds up only as far as needed to clear the
+ * backlog within `catchUpMs`, so a fast model is never made to look slow.
+ * Returns a fractional length; callers floor it when slicing.
+ */
+export function revealLength(shown, target, elapsedMs, { charsPerSecond = 80, catchUpMs = 1200 } = {}) {
+  const from = Math.max(0, Number.isFinite(shown) ? shown : 0);
+  const to = Math.max(0, Number.isFinite(target) ? target : 0);
+  if (from >= to) return to;
+  const seconds = Math.max(0, elapsedMs) / 1000;
+  const backlog = to - from;
+  const rate = Math.max(charsPerSecond, backlog / Math.max(0.05, catchUpMs / 1000));
+  return Math.min(to, from + rate * seconds);
+}
+
+/** Whether a scroller is close enough to its end to keep following new content. */
+export function isPinnedToEnd(scrollTop, scrollHeight, clientHeight, threshold = 48) {
+  return scrollHeight - clientHeight - scrollTop <= threshold;
+}
+
+/**
+ * What a key press in a prompt composer means.
+ *
+ * Enter must never send while an input method is composing: the Enter that
+ * commits a Japanese or Chinese word would otherwise send half a sentence.
+ * `submitOn: "mod-enter"` is for composers where Enter writes a new line.
+ */
+export function composerKeyAction(
+  { key, shiftKey = false, metaKey = false, ctrlKey = false, altKey = false, isComposing = false, keyCode } = {},
+  { submitOn = "enter" } = {},
+) {
+  if (key !== "Enter" || isComposing || keyCode === 229) return null;
+  const modifier = metaKey || ctrlKey;
+  if (submitOn === "mod-enter") return modifier ? "submit" : null;
+  if (shiftKey || altKey) return "newline";
+  return "submit";
+}
+
+/**
+ * An envelope follower for audio levels: rises fast, falls slowly, the way a
+ * VU meter does, so bars look alive instead of flickering on every frame.
+ */
+export function smoothLevel(previous, next, { attack = 0.55, release = 0.12 } = {}) {
+  const from = Number.isFinite(previous) ? previous : 0;
+  const to = Math.min(1, Math.max(0, Number.isFinite(next) ? next : 0));
+  const factor = to > from ? attack : release;
+  return from + (to - from) * factor;
+}
+
+/**
+ * Fold an FFT spectrum (0..255 per bin, as AnalyserNode gives) into `count`
+ * bars. Bands widen with frequency, as hearing does, so speech fills the
+ * middle of the wave instead of crowding into the first few bars.
+ */
+export function spectrumToLevels(bins, count, { floor = 0.02, gain = 1.4 } = {}) {
+  const size = bins?.length ?? 0;
+  const bars = Math.max(1, Math.floor(count));
+  if (!size) return Array.from({ length: bars }, () => 0);
+  // Speech lives in the lower half of the spectrum; the top is mostly hiss.
+  const usable = Math.max(bars, Math.floor(size * 0.5));
+  const levels = [];
+  for (let bar = 0; bar < bars; bar += 1) {
+    const start = Math.floor(usable * ((2 ** (bar / bars) - 1)));
+    const end = Math.max(start + 1, Math.floor(usable * ((2 ** ((bar + 1) / bars) - 1))));
+    let sum = 0;
+    for (let index = start; index < end && index < size; index += 1) sum += bins[index];
+    const average = sum / (end - start) / 255;
+    levels.push(Math.min(1, Math.max(0, (average - floor) * gain)));
+  }
+  return levels;
+}
+
+/** A duration for people: "0.8s", "12s", "1m 04s". */
+export function formatDuration(ms) {
+  const value = Math.max(0, Number.isFinite(ms) ? ms : 0);
+  if (value < 1000) return `${(value / 1000).toFixed(1)}s`;
+  const seconds = Math.round(value / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  return `${minutes}m ${String(seconds % 60).padStart(2, "0")}s`;
+}
+
+/** A token count for people: 812, 1.2k, 128k, 1M. */
+export function formatTokens(count) {
+  const value = Math.max(0, Math.round(Number.isFinite(count) ? count : 0));
+  if (value < 1000) return String(value);
+  if (value < 1_000_000) {
+    const thousands = value / 1000;
+    return `${thousands < 10 ? Number(thousands.toFixed(1)) : Math.round(thousands)}k`;
+  }
+  const millions = value / 1_000_000;
+  return `${millions < 10 ? Number(millions.toFixed(1)) : Math.round(millions)}M`;
+}
+
+/** Which band a model confidence (0..1) falls in. */
+export function confidenceBand(value, { low = 0.5, high = 0.8 } = {}) {
+  const confidence = Number.isFinite(value) ? value : 0;
+  if (confidence < low) return "low";
+  if (confidence < high) return "medium";
+  return "high";
+}
+
+/**
+ * How full a context window is, by segment. Levels: "ok" below `warning`,
+ * "warning" below `critical`, then "critical" — the point where the next
+ * long answer may not fit.
+ */
+export function contextUsage(segments, limit, { warning = 0.7, critical = 0.9 } = {}) {
+  const capacity = Math.max(1, Number.isFinite(limit) ? limit : 1);
+  const parts = (segments ?? []).map((segment) => ({
+    ...segment,
+    tokens: Math.max(0, Number.isFinite(segment.tokens) ? segment.tokens : 0),
+  }));
+  const used = parts.reduce((total, part) => total + part.tokens, 0);
+  const ratio = Math.min(1, used / capacity);
+  return {
+    used,
+    limit: capacity,
+    remaining: Math.max(0, capacity - used),
+    ratio,
+    level: ratio >= critical ? "critical" : ratio >= warning ? "warning" : "ok",
+    segments: parts.map((part) => ({ ...part, ratio: part.tokens / capacity })),
+  };
+}