@kitn.ai/ui 0.26.0 → 0.27.0

package/src/ui/dock.tsx

@@ -42,6 +42,19 @@ export interface DockProps {
   unread?: boolean;
   /** Disable the launcher. */
   disabled?: boolean;
+  /** Suppress the dock's own built-in mobile `[part="close"]` X. Off (rendered) by
+   *  default — the built-in X is the FALLBACK close route for panel content with no
+   *  header of its own, which is the general case the dock has to cover since it
+   *  never reads what it holds. Set `true` when the slotted/composed content
+   *  supplies its own close affordance in its own header row (e.g. `ChatThread`'s
+   *  `headerEndContent`) — with both present the two X's stack, one floating over
+   *  the other's row, which is exactly the "doesn't look intentional" feedback this
+   *  prop exists to let a caller avoid. TRADEOFF: the mobile panel reserves a
+   *  padding band above its content so the built-in X never paints over it; that
+   *  band stays reserved unless you set `hideClose` true, so only set it once your
+   *  own control is actually in place — otherwise you get the band with no X to
+   *  justify it. */
+  hideClose?: boolean;
   /** Where focus lands on open. Defaults to `content`. */
   focusOnOpen?: DockFocusOnOpen;
   /** Controlled open state. When set, the component never changes it itself — drive it
@@ -139,7 +152,12 @@ const DOCK_CSS = `
   /* ABOVE the panel, always. At <=480px the panel goes fixed/inset:0 and it comes
      after the launcher in DOM order, so at z-index:auto it painted OVER the launcher
      and a touch user lost every pointer route to closing. Both reference
-     implementations stacked the launcher over the panel for the same reason. */
+     implementations stacked the launcher over the panel for the same reason. The
+     launcher itself is now HIDDEN while the panel is open at that width (see the
+     <=480px block below) in favour of the in-panel [part="close"] X, but this
+     z-index still matters for the moment between "open" landing and the panel's
+     own transition finishing, and for any consumer CSS that reintroduces the
+     launcher there. */
   z-index: 1;
   flex: none;
   display: inline-flex;
@@ -168,6 +186,58 @@ const DOCK_CSS = `
 [data-kai-dock] [part="launcher"]:focus-visible { outline: 2px solid var(--color-ring); outline-offset: 2px; }
 [data-kai-dock] [part="launcher"]:disabled { opacity: 0.55; cursor: not-allowed; }
 
+/* The mobile-only close affordance rendered INSIDE the panel. Hidden by default and
+   only switched on inside the <=480px media block below, alongside the rule that
+   hides the launcher while the panel is open at that width — same query drives both,
+   CSS-only, no JS viewport logic. Absolutely positioned against the panel, which is
+   the panel's own containing block once the narrow-viewport rule below sets it to
+   position: fixed.
+
+   The inset is a CONSUMER-OVERRIDABLE TOKEN, same idiom as every other geometry
+   value in this file (--kai-dock-width and friends). The dock is content-agnostic —
+   it never reads what is slotted into the panel — so it cannot know whether that
+   content renders its own trailing controls (a ChatThread header-end slot with
+   share/settings icons, say) in the same top-right corner.
+
+   The mobile block below reserves a BAND of the panel's own padding above whatever
+   is slotted, sized to this button's own footprint, so nothing paints under this X
+   by default -- verified fix (round 1) against a real ChatThread header-end slot
+   colliding with it at 375px. Owner feedback on the real widget (round 2): for a
+   construct with only a title in the header, that band read as a dead empty strip
+   with the X floating alone in it -- "that doesn't look like the empty component
+   either, lets do better." The actual fix composes instead of reserving space:
+   ChatThread now has its own headerEndContent escape hatch (see its prop doc) so a
+   caller puts the close control INSIDE the header row, sharing it with the title --
+   zero collision by construction, no band needed. hideClose on this component (see
+   its prop doc) then suppresses this built-in X for exactly that case, and the
+   band above is scoped to :not([data-hide-close]) so it comes off ONLY there --
+   every other consumer (anyone who hasn't opted into hideClose, including a
+   hand-authored dock with real header-end content) keeps the band, same as round 1
+   shipped, so the collision it fixed stays fixed for them. What remains here for
+   that default case is a plain absolute overlay, top-right of the panel, with
+   these consumer-overridable inset tokens for the rare case it should deliberately
+   sit in front of something (e.g. a single small badge). */
+[data-kai-dock] [part="close"] {
+  display: none;
+  position: absolute;
+  inset-block-start: var(--kai-dock-close-inset-block, 0.75rem);
+  inset-inline-end: var(--kai-dock-close-inset-inline, 0.75rem);
+  z-index: 1;
+  align-items: center;
+  justify-content: center;
+  inline-size: 2.25rem;
+  block-size: 2.25rem;
+  padding: 0;
+  border: 0;
+  border-radius: 9999px;
+  background: var(--color-background);
+  color: var(--color-foreground);
+  box-shadow: 0 2px 8px -2px rgb(0 0 0 / 0.3);
+  cursor: pointer;
+}
+[data-kai-dock] [part="close"]:hover { background: var(--color-muted, var(--color-background)); }
+[data-kai-dock] [part="close"]:focus-visible { outline: 2px solid var(--color-ring); outline-offset: 2px; }
+
 [data-kai-dock] [part="badge"] {
   position: absolute;
   inset-block-start: 3px;
@@ -222,10 +292,12 @@ const DOCK_CSS = `
 [data-kai-dock][data-position^="top"] [part="panel"][data-closed] { transform: translateY(-0.5rem); }
 
 /* Narrow viewports take the panel full-bleed. A SHIPPED DEFAULT, not a prop: both
-   references wrote this rule independently, which makes it a HOW. The launcher stays
-   in its corner and ON TOP of the full-bleed panel — that is the z-index: 1 in the
-   launcher rule above, not anything in this block, and without it a phone user has no
-   pointer route to closing at all (Escape alone strands exactly the touch user). */
+   references wrote this rule independently, which makes it a HOW. While the panel is
+   OPEN at this width the launcher hides and the panel's own [part="close"] X becomes
+   the pointer close route instead — a FAB floating over a full-bleed panel read as
+   wrong (owner feedback) and Escape alone strands a touch user with no visible
+   affordance at all. Closed, the launcher is unaffected: it is the panel's own
+   [data-expanded] state that gates both rules below, not the media query alone. */
 @media (max-width: 480px) {
   [data-kai-dock] [part="panel"] {
     position: fixed;
@@ -237,6 +309,41 @@ const DOCK_CSS = `
     border: 0;
     border-radius: 0;
   }
+
+  /* Reserve a band for the built-in [part="close"] X ABOVE whatever is slotted,
+     rather than overlaying it on top of the panel's own content — the fix round 1
+     collision protection (verified against a real ChatThread header-end slot at
+     375px: without this, the X painted directly over trailing icon buttons).
+     DERIVED from the button's own inset + size tokens, not a second hand-typed
+     number.
+
+     SCOPED to :not([data-hide-close]) — round 2 (owner feedback: the band read as
+     a dead strip when nothing but the X occupied it) removed this UNCONDITIONALLY
+     and reintroduced the very collision round 1 fixed, for every consumer who
+     never opted into hideClose. hideClose is only true for a caller that supplies
+     its OWN close control in its own header row (ChatThread's headerEndContent is
+     the one that does today) — the built-in X and this band both come off
+     together for that case, since there is nothing left for the band to protect.
+     Every other consumer -- including a hand-authored kai-dock with real
+     slot="header-end" content and no opinion on hideClose -- keeps the band, the
+     same as round 1 shipped. */
+  [data-kai-dock]:not([data-hide-close]) [part="panel"] {
+    padding-block-start: calc(2 * var(--kai-dock-close-inset-block, 0.75rem) + 2.25rem);
+  }
+
+  /* The full-bleed panel gets its own close affordance instead of relying on the
+     launcher, which is hidden below while the panel is open at this width — a FAB
+     floating over a full-bleed panel with no other visible close route is exactly
+     what the owner flagged. Escape and the X both still work; the launcher comes
+     back the instant the panel closes because data-expanded is gone by then.
+     Absolutely positioned, so the padding-block-start above (a content-box
+     concern) does not shift IT — only the in-flow slotted content. Content that
+     supplies its own close control passes hideClose, which drops the button from
+     the render tree entirely (see the component body) rather than being gated
+     here — so this rule stays a plain, unconditional width-query switch; the band
+     above is what actually varies with hideClose. */
+  [data-kai-dock] [part="close"] { display: inline-flex; }
+  [data-kai-dock]:has([part="panel"][data-expanded]) [part="launcher"] { display: none; }
 }
 
 @media (prefers-reduced-motion: reduce) {
@@ -310,6 +417,15 @@ function isWithin(root: Node, node: Node | null): boolean {
  *   own menus; swallowing a key from a page you are a guest on is a decide-quietly move.
  * - **No focus trap**, deliberately, unlike `kai-dialog`. The page staying usable is
  *   the whole point of "docked", which is also why the panel is `aria-modal="false"`.
+ * - **Mobile close route.** At <=480px the panel goes full-bleed and the launcher
+ *   hides while it is open — a floating launcher over a full-bleed panel is not an
+ *   obvious close affordance. The panel gets its own `[part="close"]` X, top-right,
+ *   CSS-gated by the SAME media query and `[data-expanded]`, so it needs no viewport
+ *   JS. Desktop is unaffected: the launcher keeps toggling and no X ever renders.
+ *   This is the FALLBACK route, for panel content with no header of its own to hold
+ *   a close control — content that does (a `ChatThread` using `headerEndContent`,
+ *   say) passes `hideClose` to drop this X instead of stacking a second one over
+ *   its own header row.
  *
  * WHAT IT REFUSES: it never aborts a request, never persists its own open state, never
  * decides what "unread" means, and never clears `unread` on open — writing over a
@@ -393,7 +509,17 @@ export function Dock(props: DockProps) {
   return (
     <>
       <style>{DOCK_CSS}</style>
-      <div data-kai-dock data-position={props.position ?? 'bottom-end'} onKeyDown={onKeyDown}>
+      <div
+        data-kai-dock
+        data-position={props.position ?? 'bottom-end'}
+        // Drives the mobile panel's reserved-band rule below: present only when the
+        // built-in [part="close"] X is ACTUALLY suppressed (hideClose true), so the
+        // band stays on for every consumer who hasn't opted into their own close
+        // control — see the [part="close"]/reserved-band comments for why removing
+        // it unconditionally regressed the collision it existed to prevent.
+        bool:data-hide-close={!!props.hideClose}
+        onKeyDown={onKeyDown}
+      >
         <button
           ref={(el) => { launcher = el; props.launcherRef?.(el); }}
           part="launcher"
@@ -437,6 +563,19 @@ export function Dock(props: DockProps) {
             'pointer-events': isOpen() ? 'auto' : 'none',
           }}
         >
+          {/* Mobile-only (see the <=480px rule in DOCK_CSS): the full-bleed panel's
+              own close affordance, since the launcher is hidden by the same query
+              while the panel is open. Reuses the launcher's derived close name
+              rather than a new prop — same string, same i18n override. Dropped
+              from the render tree entirely (not just hidden) when `hideClose` is
+              set — the panel content supplies its own, in its own header, and a
+              second X floating over that row is the exact "doesn't look
+              intentional" feedback `hideClose` exists to avoid. */}
+          <Show when={!props.hideClose}>
+            <button type="button" part="close" aria-label={launcherName()} onClick={() => setOpen(false)}>
+              <DockCloseGlyph />
+            </button>
+          </Show>
           {props.children}
         </div>
       </div>

package/src/ui/icon.tsx

@@ -9,6 +9,16 @@ import {
   Archive, ArrowUp, Bookmark, Copy, Ellipsis, ExternalLink, Flag,
   GitBranch, GitPullRequest, ListFilter, RotateCw,
   Moon, Sun,
+  // Device / viewport glyphs.
+  Tablet, Smartphone, Laptop,
+  // Direction glyphs completing the chevron + arrow quartets.
+  ChevronRight, ChevronUp, ArrowRight, ArrowDown, PanelRight,
+  // Status glyphs (kai-notice / kai-toast / kai-tool render these already).
+  Check, Info, TriangleAlert, CircleCheck, CircleAlert, CircleX,
+  // Action glyphs the kit performs but could not be named.
+  Trash2, Download, Upload, Link, RotateCcw,
+  // Pane / media chrome.
+  Maximize2, Minimize2, Eye, EyeOff, Bell, Square, Minus, Play,
 } from 'lucide-solid';
 
 type IconComponent = Component<{ class?: string }>;
@@ -68,8 +78,51 @@ const NAMED_ICONS: Record<string, IconComponent> = {
   // Theme / appearance glyphs.
   moon: Moon,
   sun: Sun,
+  // Device / viewport glyphs. `desktop` and `mobile` are aliases onto the same
+  // components as `monitor`/`smartphone` — lucide's names are not the words a
+  // consumer reaches for, and an alias costs nothing in the bundle.
+  desktop: Monitor,
+  laptop: Laptop,
+  tablet: Tablet,
+  smartphone: Smartphone,
+  mobile: Smartphone,
+  // Direction glyphs — chevron-down/left and arrow-left/up were here without
+  // their opposites; both quartets are now complete.
+  'chevron-right': ChevronRight,
+  'chevron-up': ChevronUp,
+  'arrow-right': ArrowRight,
+  'arrow-down': ArrowDown,
+  'panel-right': PanelRight,
+  // Status glyphs. kai-notice / kai-toast / kai-tool already paint these, so a
+  // host building matching UI needs to be able to name them.
+  check: Check,
+  info: Info,
+  'triangle-alert': TriangleAlert,
+  'circle-check': CircleCheck,
+  'circle-alert': CircleAlert,
+  'circle-x': CircleX,
+  // Action glyphs. `trash`/`download`/`link` match the keys action-icons.ts
+  // already uses for message actions; `upload` is download's missing sibling.
+  trash: Trash2,
+  download: Download,
+  upload: Upload,
+  link: Link,
+  'rotate-ccw': RotateCcw,
+  // Pane / media chrome (kai-pane, kai-artifact, kai-embed, kai-agent-card).
+  'maximize-2': Maximize2,
+  'minimize-2': Minimize2,
+  eye: Eye,
+  'eye-off': EyeOff,
+  bell: Bell,
+  square: Square,
+  minus: Minus,
+  play: Play,
 };
 
+/** Every curated icon name, sorted. Derived from `NAMED_ICONS` so a gallery,
+ *  a story control or a test can never drift from the map itself. */
+export const ICON_NAMES: readonly string[] = Object.keys(NAMED_ICONS).sort();
+
 /** Render an item icon.
  *
  *  Resolution order:

package/src/ui/input.tsx

@@ -1,5 +1,13 @@
-import { type JSX, Show, splitProps, createUniqueId } from 'solid-js';
+import { type JSX, Show, splitProps, createUniqueId, createEffect, onCleanup, untrack } from 'solid-js';
 import { cn } from '../utils/cn';
+import type { CaseMode } from '../primitives/field-mask';
+import { fieldSemantics, type FieldSemanticType } from '../primitives/field-semantics';
+import {
+  createInputMask,
+  type CopyPolicy,
+  type InputMask,
+  type InputMaskRejectReason,
+} from '../primitives/input-mask';
 
 export interface InputProps extends Omit<JSX.InputHTMLAttributes<HTMLInputElement>, 'onInput' | 'onChange' | 'size'> {
   /** Field label rendered above the control and linked via `for`/`id`. */
@@ -16,12 +24,58 @@ export interface InputProps extends Omit<JSX.InputHTMLAttributes<HTMLInputElemen
   leading?: JSX.Element;
   /** Trailing affix (icon, inline button). Rendered inside the field row, after the input. */
   trailing?: JSX.Element;
-  /** Fires per keystroke with the current value. */
+  /** Fires per keystroke with the current value — the CANONICAL value when a mask is
+   *  active (digits for `tel`/`ssn`/`credit-card`, the formatted text for
+   *  `custom`), and the raw text of the field otherwise. */
   onValueInput?: (value: string) => void;
-  /** Fires on commit (blur) with the current value. */
+  /** Fires on commit (blur) with the current value; canonical when a mask is active. */
   onValueChange?: (value: string) => void;
+
+  // --- Form-field formats (spec §7.2). All five are SCALARS, which is what lets them
+  // survive as HTML attributes on the `<kai-input>` facade. Absent `format` AND absent
+  // `semantic` is the behavior of today, byte for byte (owner decision 1 / spec §1.1): no mask,
+  // no extra attributes, nothing.
+
+  /** Tier-2 mask pattern: `#` a digit, `@` an alphanumeric, `*` an obscurable
+   *  alphanumeric, everything else a positional literal (`@@@-####`).
+   *
+   *  The literal `default` is the OPT-IN sentinel: it resolves to the default format of
+   *  `semantic` (`tel` → `###-###-####`). It cannot collide with a real pattern — `default`
+   *  as a format is eight literals with no fill position, i.e. a field that can hold
+   *  nothing — and an opt-in token is needed because decision 1 forbids a bare semantic
+   *  type from starting to mask on its own. */
+  format?: string;
+  /** The placeholder guide shown at unfilled positions, aligned position-for-position
+   *  with `format` (`   -   -    `, `mm/dd/yyyy`). Without it the field shows only up
+   *  to the last typed character. */
+  guide?: string;
+  /** Tier-1 semantic type. On its own it applies `inputmode` / `autocomplete` /
+   *  `spellcheck` / `autocorrect` / `autocapitalize` and decides the canonical value —
+   *  it never starts masking by itself. */
+  semantic?: FieldSemanticType;
+  /** Case folding applied to typed and pasted text. Defaults to `preserve`. */
+  caseMode?: CaseMode;
+  /** What a copy or cut of a masked field puts on the clipboard. Defaults to `canonical`. */
+  copyPolicy?: CopyPolicy;
+  /** A mask refused, or partly refused, some content — `full`, `wrong-class`,
+   *  `over-capacity`, or `format-change-clipped`. Not a scalar and therefore not an
+   *  attribute: the facade projects this onto its `kai-input-rejected` event.
+   *
+   *  NOT an error state. `format-change-clipped` in particular fires on a routine
+   *  reactive `format` change, so this widget deliberately does not touch `invalid` —
+   *  validity belongs to the consumer, and stays there. */
+  onMaskReject?: (detail: { reason: InputMaskRejectReason; data: string }) => void;
 }
 
+/** The `format` value that means: resolve the default format of the semantic type.
+ *
+ *  EXPORTED because `src/elements/input.tsx` has to recognise the same sentinel when it
+ *  resolves a seeded value ahead of the masker, and a restated literal there would fail
+ *  SILENTLY if this string ever changed: `format === 'default'` would simply go false and
+ *  `compileMask('default')` would compile seven literals, garbling the seed with no error
+ *  anywhere. One exported constant instead of two copies of a magic string. */
+export const DEFAULT_FORMAT = 'default';
+
 // The single source of the field shell styling — lifted verbatim from the
 // `inputBase` constant that used to live in `src/components/form-widgets.tsx`.
 // `Input` now owns it; the form widgets render `Input` rather than re-pasting it.
@@ -37,7 +91,12 @@ const ROW_INPUT =
   'min-w-0 flex-1 bg-transparent text-sm text-foreground placeholder:text-muted-foreground focus-visible:outline-none disabled:cursor-not-allowed';
 
 const SIZE_SM = 'px-2.5 py-1';
-const INVALID = 'border-destructive dark:border-red-400/70';
+// The invalid-state border, EXPORTED because `src/ui/select.tsx` renders the same
+// field box and a second hand-typed copy of this string is exactly the kind of
+// restatement that rots (`docs/coupling-map.md` §4). `INVALID` stays as the local
+// alias so the three call sites below read unchanged.
+export const FIELD_INVALID = 'border-destructive dark:border-red-400/70';
+const INVALID = FIELD_INVALID;
 
 // Suppress the native search affordances Chrome/WebKit render for `type="search"`.
 // Without this the browser's `::-webkit-search-cancel-button` (×) stacks on top of
@@ -61,6 +120,7 @@ export function Input(props: InputProps): JSX.Element {
   const [local, rest] = splitProps(props, [
     'class', 'label', 'hint', 'error', 'size', 'invalid',
     'leading', 'trailing', 'onValueInput', 'onValueChange', 'onBlur', 'id', 'disabled',
+    'format', 'guide', 'semantic', 'caseMode', 'copyPolicy', 'onMaskReject',
   ]);
 
   const id = local.id ?? createUniqueId();
@@ -69,6 +129,138 @@ export function Input(props: InputProps): JSX.Element {
   const hasHint = () => !!local.error || !!local.hint;
   const hasAffix = () => local.leading != null || local.trailing != null;
 
+  // -------------------------------------------------------------------------------
+  // Form-field formats (spec §7.2). Tier 1 is a handful of attributes; tier 2 is one
+  // `createInputMask` bound to whichever `<input>` node is currently mounted.
+  // -------------------------------------------------------------------------------
+
+  const semantics = () => (local.semantic === undefined ? undefined : fieldSemantics(local.semantic));
+
+  // Both warn paths below run from a TRACKED accessor or from a reconfigure, i.e. from a
+  // routine reactive render, and both interpolate a value that reaches this widget from
+  // the form card and therefore from MODEL output. So: report each distinct bad value
+  // ONCE per widget, and clip what gets interpolated. The console is not a sink — this is
+  // about a 500-character pattern printing 500 characters on every keystroke, not about
+  // injection.
+  const warned = new Set<string>();
+  const warnOnce = (key: string, message: string): void => {
+    if (warned.has(key)) return;
+    warned.add(key);
+    console.warn(message);
+  };
+  const clip = (text: string): string =>
+    text.length <= 32 ? text : `${text.slice(0, 32)}… (${text.length} chars)`;
+
+  /** The pattern to mask with, or `undefined` for no mask at all. */
+  const maskFormat = (): string | undefined => {
+    const format = local.format;
+    if (format === undefined || format === '') return undefined;
+    if (format !== DEFAULT_FORMAT) return format;
+    const resolved = semantics()?.defaultFormat;
+    if (resolved === undefined) {
+      // Loud, never a silent no-mask: the consumer asked for a mask and is not getting
+      // one. `custom` has no default by design (its `format` IS the pattern), and a
+      // semantic type that never arrived is the more likely mistake.
+      warnOnce(
+        `default:${String(local.semantic)}`,
+        `Input: format=${DEFAULT_FORMAT} resolves the default format of a semantic type, and ` +
+          `semantic=${JSON.stringify(local.semantic)} has none. Rendering unmasked.`,
+      );
+    }
+    return resolved;
+  };
+
+  let plainEl: HTMLInputElement | undefined;
+  let rowEl: HTMLInputElement | undefined;
+  let mask: InputMask | undefined;
+  /** The node `mask` is bound to. The affix toggle is the one thing that changes it. */
+  let maskedEl: HTMLInputElement | undefined;
+
+  const detachMask = (): void => {
+    mask?.detach();
+    mask = undefined;
+    maskedEl = undefined;
+  };
+
+  const warnBadFormat = (format: string, err: unknown, kept: boolean): void => {
+    const reason = err instanceof Error ? err.message : String(err);
+    warnOnce(
+      `format:${format}`,
+      `Input: format ${JSON.stringify(clip(format))} did not compile (${reason}); ` +
+        (kept ? 'the field keeps its previous format.' : 'rendering unmasked.'),
+    );
+  };
+
+  createEffect(() => {
+    // Everything reactive is read HERE, so the effect re-runs on a config change or an
+    // affix toggle and on nothing else.
+    const format = maskFormat();
+    const config = {
+      guide: local.guide,
+      semantic: local.semantic,
+      caseMode: local.caseMode,
+      copyPolicy: local.copyPolicy,
+    };
+    // WHICH NODE IS MOUNTED. `Input` caches two `<input>`s and `<Show>` swaps between
+    // them when a leading/trailing affix appears or disappears — the one legitimate node
+    // change in this file (spec §8.1). The `ref` of a node fires only when it is BUILT, and
+    // the cached node is built once, so a toggle back to an existing node notifies
+    // nobody. Re-attachment therefore has to be explicit, and this read is what makes it
+    // happen. Everything else about this widget is pinned to keeping the SAME node alive
+    // (`tests/ui/input-node-identity.test.tsx`), which is the only reason a long-lived
+    // masker on it is safe at all.
+    //
+    // THE ASSUMPTION THIS RELIES ON, stated: `plainEl`/`rowEl` are plain mutable refs, so
+    // this reads a node only because Solid runs the `<Show>` render effect that BUILDS it
+    // (and its `ref`) before this user effect. If that ever stopped holding, `el` would be
+    // `undefined` on the toggle and the branch below would detach with nothing queued to
+    // re-attach — silently. The affix tests in the node-identity file are what would catch it.
+    const el = hasAffix() ? rowEl : plainEl;
+
+    untrack(() => {
+      if (format === undefined || el === undefined) {
+        detachMask();
+        return;
+      }
+
+      if (mask !== undefined && maskedEl === el) {
+        // Same node, new configuration: RE-CONFIGURE. Re-creating would drop the undo
+        // stack and re-seed from the DOM text. `update()` is atomic — a format that
+        // fails to compile leaves the masker exactly as it was — so a half-typed
+        // reactive pattern cannot corrupt the field.
+        try {
+          mask.update({ format, ...config });
+        } catch (err) {
+          warnBadFormat(format, err, true);
+        }
+        return;
+      }
+
+      // First attach, or the affix toggle. Carry the value across: the incoming node is
+      // a different element and knows nothing about what the user typed into the old one.
+      const carried = mask?.getFormattedValue() ?? el.value;
+      detachMask();
+      try {
+        mask = createInputMask(el, {
+          ...config,
+          format,
+          initialValue: carried,
+          // The callback of the masker, not the DOM `input` event, is the emission point: a
+          // canceled `beforeinput` means a real browser never fires `input` at all for a
+          // typed character.
+          onInput: ({ canonical }) => local.onValueInput?.(canonical),
+          onReject: (detail) => local.onMaskReject?.(detail),
+        });
+        maskedEl = el;
+      } catch (err) {
+        // A bad pattern falls back to a plain text field, loudly (spec §7.3).
+        warnBadFormat(format, err, false);
+      }
+    });
+  });
+
+  onCleanup(detachMask);
+
   // The class arrives as an ACCESSOR, not a string, and this is load-bearing.
   //
   // Solid evaluates a `<Show>` `fallback` inside the Show's own memo. When the
@@ -83,20 +275,57 @@ export function Input(props: InputProps): JSX.Element {
   // Solid compiles it into a nested effect that sets the attribute on the
   // EXISTING node. Same reason the affix branch was always fine: it inserts the
   // input through a function. Pinned by `tests/ui/input-node-identity.test.tsx`.
-  const inputEl = (cls: () => string, part: string): JSX.Element => (
+  // Tier-1 attributes (spec §2). Each is a DEFAULT the semantic type supplies: an
+  // explicit prop always wins, because the consumer knows something the enum does not.
+  // With no `semantic` every one of these is `undefined` — the attribute is simply not
+  // set, which is what byte-for-byte parity with the behavior of today means here.
+  const inputmodeAttr = () => rest.inputmode ?? semantics()?.inputmode;
+  const autocompleteAttr = () =>
+    (rest.autocomplete ?? semantics()?.autocomplete) as JSX.InputHTMLAttributes<HTMLInputElement>['autocomplete'];
+  const spellcheckAttr = () => {
+    const explicit = rest.spellcheck;
+    // Normalized to the attribute spelling so both forms land as an attribute rather
+    // than one of them as a property: `spellcheck={false}` is a real value, not an
+    // absent one, and it must stay visible in the DOM.
+    if (explicit !== undefined) return explicit === true || explicit === 'true' ? 'true' : 'false';
+    const semantic = semantics();
+    if (semantic === undefined) return undefined;
+    return semantic.spellcheck ? 'true' : 'false';
+  };
+  const autocorrectAttr = () => rest.autocorrect ?? semantics()?.autocorrect;
+  const autocapitalizeAttr = () => rest.autocapitalize ?? semantics()?.autocapitalize;
+
+  const inputEl = (
+    cls: () => string,
+    part: string,
+    register: (el: HTMLInputElement) => void,
+  ): JSX.Element => (
     <input
       {...rest}
+      ref={register}
       id={id}
       part={part}
       disabled={local.disabled}
       aria-invalid={isInvalid() ? 'true' : undefined}
       aria-describedby={hasHint() ? hintId : undefined}
+      inputmode={inputmodeAttr()}
+      autocomplete={autocompleteAttr()}
+      spellcheck={spellcheckAttr()}
+      autocorrect={autocorrectAttr()}
+      autocapitalize={autocapitalizeAttr()}
       class={cn(SEARCH_RESET, cls())}
-      onInput={(e) => local.onValueInput?.(e.currentTarget.value)}
+      // When a mask is active the masker owns the emission (see its `onInput` above) and
+      // this handler stands down — otherwise a jsdom-style `input` event, which reaches
+      // both, would emit twice, and the raw text it reads is the FORMATTED value rather
+      // than the canonical one.
+      onInput={(e) => {
+        if (mask !== undefined) return;
+        local.onValueInput?.(e.currentTarget.value);
+      }}
       onBlur={(e) => {
         const handler = local.onBlur;
         if (typeof handler === 'function') handler(e);
-        local.onValueChange?.(e.currentTarget.value);
+        local.onValueChange?.(mask?.getCanonicalValue() ?? e.currentTarget.value);
       }}
     />
   );
@@ -107,10 +336,21 @@ export function Input(props: InputProps): JSX.Element {
   // Created on first use and then REUSED, so toggling an affix on or off does
   // not discard a focused input either. The lazy cache also keeps the unused
   // branch's node (and its effects) from being built at all.
+  //
+  // KEEP PROSE IN THIS FILE FREE OF STRAY QUOTE CHARACTERS. The part-name guard in
+  // `src/elements/slots.test.ts` scans this source with a naive quote regex, so one
+  // apostrophe in a comment shifts its parity and swallows the part literals below —
+  // that guard then reddens over a comment, naming a part that is still right there.
+  //
+  // Each branch registers its node so the mask effect above can find whichever one is
+  // mounted; `ref` fires once per node, at construction, which is exactly when a node
+  // first becomes findable.
   let plainNode: JSX.Element;
-  const plainInput = () => (plainNode ??= inputEl(fieldClass, 'field input'));
+  const plainInput = () =>
+    (plainNode ??= inputEl(fieldClass, 'field input', (el) => (plainEl = el)));
   let rowNode: JSX.Element;
-  const rowInput = () => (rowNode ??= inputEl(() => ROW_INPUT, 'input'));
+  const rowInput = () =>
+    (rowNode ??= inputEl(() => ROW_INPUT, 'input', (el) => (rowEl = el)));
 
   return (
     <div class="flex w-full flex-col gap-1.5">

package/src/ui/kbd.tsx

@@ -70,7 +70,7 @@ function glyph(token: string, mac: boolean): string {
 }
 
 const SIZE: Record<'sm' | 'md', string> = {
-  sm: 'h-5 min-w-5 px-1 text-[11px]',
+  sm: 'h-5 min-w-5 px-1 text-caption',
   md: 'h-6 min-w-6 px-1.5 text-xs',
 };
 

package/src/ui/nav.tsx

@@ -221,7 +221,7 @@ function NavRows(props: NavRowsProps) {
                   </span>
                 </Show>
                 <Show when={item.badge}>
-                  <Badge variant="default" class="px-1.5 py-0 text-[0.625rem] font-medium uppercase tracking-wide">{item.badge}</Badge>
+                  <Badge variant="default" class="px-1.5 py-0 text-micro font-medium uppercase tracking-wide">{item.badge}</Badge>
                 </Show>
                 <Show when={item.trailing}>{renderIcon(item.trailing, { class: 'size-4 shrink-0 opacity-0 transition-opacity group-hover:opacity-60' })}</Show>
               </button>

package/src/ui/pane-group.tsx

@@ -201,7 +201,7 @@ export function PaneGroup(props: PaneGroupProps) {
             </Show>
             <span
               class={cn(
-                'relative flex size-[18px] items-center justify-center rounded text-[11px] font-bold leading-none tabular-nums',
+                'relative flex size-[18px] items-center justify-center rounded text-caption font-bold leading-none tabular-nums',
                 TONE_BG[tone()],
                 TONE_BADGE_FG[tone()],
               )}
@@ -215,7 +215,7 @@ export function PaneGroup(props: PaneGroupProps) {
           <Show when={tab().status?.label}>
             <span
               class={cn(
-                'truncate text-[10px] font-medium',
+                'truncate text-micro font-medium',
                 TONE_TEXT[tone()],
                 alwaysWord() ? 'inline' : 'hidden group-hover/tab:inline',
               )}