@kitn.ai/ui 0.25.2 → 0.27.0

package/src/primitives/card-data-types.ts

@@ -207,6 +207,55 @@ export type FormField = {
     | 'switch';
   'x-kai-placeholder'?: string;
   'x-kai-step'?: number;
+  /**
+   * Display format for a string field. `tel` / `ssn` / `credit-card`
+   * apply that type's standard mask and submit digits only; `custom` masks with
+   * `x-kai-mask` and submits the formatted value.
+   *
+   * NOT the JSON Schema `format` keyword, and deliberately not an extension of it:
+   * `format` has a registered vocabulary with assertion semantics, `widgetFor()`
+   * already switches on it to pick a widget, and `toJsonSchema()` turns it into a
+   * validation pattern. This is a UI hint, so it lives in the `x-kai-*` namespace
+   * with the other UI hints — and it selects FORMATTING, never a widget.
+   *
+   * Typed as the semantic-type union for a consumer authoring a form definition by
+   * hand. A value arriving from a MODEL is untrusted and may be anything at all;
+   * `resolveFieldMask()` degrades an unrecognised one to an unmasked text field with
+   * a console warning rather than trusting this declaration.
+   *
+   * SPELLED OUT HERE RATHER THAN IMPORTED, and that is not laziness. `FieldSemanticType`
+   * is declared in `./field-semantics`, which carries the semantics TABLE and its
+   * `console.warn` — and this file's whole reason for existing is that a Node/no-DOM
+   * backend can name a card payload with `lib: ["ESNext"]` and `types: []`, where
+   * `console` does not exist (measured: TS2584, by
+   * `tests/schemas/card-data-types-node-safe.test.ts`, which is what caught the import).
+   * A type import still has to RESOLVE, so importing the union would drag the engine into
+   * the server-safe entry's graph.
+   *
+   * AN APP CANNOT PIN THIS ON THE MODEL TODAY.
+   * `cardTools({ require })` narrows a projected tool schema by dot-path, but there is
+   * no path that reaches a form FIELD: a form card's payload is itself a JSON Schema, so
+   * `form.schema.json` describes `properties` as a map of field definitions rather than
+   * as a node per field, and `require: { form: [{ path: 'properties.ticketId' }] }` is a
+   * TypeError naming a path that does not resolve. "Force the model to mask the ticket
+   * field" is therefore not expressible; the enum above is what makes it LIKELY, and an
+   * app that needs a guarantee validates the arriving envelope itself.
+   *
+   * It is therefore a REGISTERED COPY of `FIELD_SEMANTIC_TYPES`: the two are pinned
+   * mutually assignable at compile time in
+   * `tests/components/form-field-formats.test.tsx`, so adding a fifth token to the enum
+   * without adding it here fails `nx typecheck ui` rather than shipping a form card that
+   * cannot name it.
+   */
+  'x-kai-format'?: 'tel' | 'ssn' | 'credit-card' | 'custom';
+  /** The mask pattern, read only when `x-kai-format` is `custom`: `#` a digit, `@` an
+   *  alphanumeric, `*` an obscurable alphanumeric, everything else a literal
+   *  (`CHG-####`). Capped at the mask engine's own limit; a longer one is refused. */
+  'x-kai-mask'?: string;
+  /** Placeholder text for the mask's unfilled positions, aligned character for
+   *  character with the pattern (`mm/dd/yyyy`). Derived from the pattern when absent;
+   *  a misaligned one is dropped, loudly, and the mask survives. */
+  'x-kai-mask-guide'?: string;
 };
 
 /** The form definition = CardEnvelope.data for type:'form'. */

package/src/primitives/card-host.tsx

@@ -1,8 +1,10 @@
 // src/primitives/card-host.tsx
 // The native transport: a Solid context exposing a CardHost (context() + emit()).
 // emit() routes through the contract policy via the shared routeCardEvent. Cards
-// inside <kai-chat>/<CardProvider> use this; bare cards fall back to the bubbling
-// kai-card event (see card-routing.listenForCardEvents).
+// inside a <CardProvider> use this; cards inside <kai-chat>/<kai-message>/
+// <kai-thread> (and bare cards given a hostElement) fall back to the bubbling
+// kai-card event off the host element (see card-routing.listenForCardEvents and
+// CardRenderer's hostElement prop).
 import { createContext, useContext, type JSX } from 'solid-js';
 import type { CardContext, CardEvent, CardHost, CardPolicy } from './card-contract';
 import { routeCardEvent } from './card-routing';

package/src/primitives/card-routing.ts

@@ -3,6 +3,13 @@
 // policy router (used by BOTH the native listener and the remote transport), and a
 // host-side listener helper for the bare-element path.
 import type { CardEvent, CardPolicy } from './card-contract';
+// isSafeUrl/isScriptUrl live in their own DOM-free file so schema.ts
+// (agent-tooling/construct, checked under tsconfig.mcp.json's Node-only pass)
+// can import isSafeUrl without dragging this file's HTMLElement/window/
+// CustomEvent references into a no-DOM-lib compile. Re-exported here so this
+// module's own public surface is unchanged.
+import { isSafeUrl, isScriptUrl } from './url-scheme-policy';
+export { isSafeUrl, isScriptUrl } from './url-scheme-policy';
 
 /** The single contract event name. */
 export const CARD_EVENT_NAME = 'kai-card';
@@ -16,62 +23,6 @@ export function emitCardEvent(element: HTMLElement, event: CardEvent): void {
   );
 }
 
-const SAFE_SCHEMES = ['http:', 'https:', 'mailto:'];
-const SCRIPT_SCHEMES = ['javascript:', 'vbscript:'];
-
-/** The scheme the WHATWG parser reads out of `url`, resolved against a base so a
- *  relative input inherits `http:`. `undefined` when it will not parse at all.
- *
- *  ONE parser for the two questions below, deliberately: the parsing is where
- *  the subtlety lives (it strips embedded tabs/newlines and trims surrounding
- *  whitespace before reading the scheme, so `java\nscript:` and
- *  `  javascript:...  ` are both read as `javascript:` -- which a regex over the
- *  raw string would miss). Two predicates over one parse cannot drift on that;
- *  two hand-rolled parsers would. */
-function schemeOf(url: string): string | undefined {
-  try { return new URL(url, 'http://_invalid_base').protocol; } catch { return undefined; }
-}
-
-/** True when `url` is safe to put in an href / hand to `window.open`.
- *
- *  Exported so the MARKDOWN renderer and the ARTIFACT viewer reuse this exact
- *  guard rather than growing a second scheme list that can drift from this one.
- *
- *  Resolving against a base is deliberate and is what makes it correct for
- *  markdown: a relative or fragment link (`/docs`, `#section`, `./rel`) is
- *  ordinary markdown, and resolving it inherits the base's `http:` so it
- *  passes, while `javascript:`/`data:`/`vbscript:` keep their own protocol and
- *  fail. It is correct for the artifact viewer for the same reason: a file with
- *  no `src` to resolve against yields a bare relative path (`docs/report.pdf`),
- *  which is a legitimate artifact address. Contrast `isRenderableLink` in
- *  `primitives/link-preview.ts`, which takes NO base and so demands an absolute
- *  http(s) URL: that is the right guard for a model-supplied citation -- a
- *  reference to a page on the public web -- this one for markdown body links and
- *  artifact file addresses. */
-export function isSafeUrl(url: string): boolean {
-  const scheme = schemeOf(url);
-  return scheme !== undefined && SAFE_SCHEMES.includes(scheme);
-}
-
-/** True when navigating to `url` would EXECUTE it as script in the initiating
- *  document's origin.
- *
- *  Strictly narrower than `!isSafeUrl(url)`, and not a competing policy: it
- *  answers a different question, for the one sink where the allowlist is the
- *  wrong tool. An `<iframe src>` legitimately takes `data:` and `blob:` (a
- *  `data:` blob artifact is a documented `<kai-artifact>` use -- it is what
- *  `displayUrl` exists for) and both get an OPAQUE origin in every modern
- *  browser, so neither can reach the host page. `javascript:`/`vbscript:` are
- *  the schemes that run in the EMBEDDER's origin, and they are the whole risk:
- *  the default sandbox (no `allow-same-origin`) already makes the browser refuse
- *  them, but a consumer who sets `allow-same-origin` turns a model-supplied
- *  `src` into host-origin script execution. The artifact viewer used to suggest
- *  that setting for "an artifact you trust"; it no longer does, and this guard
- *  is what protects the consumers who took the old advice. */
-export function isScriptUrl(url: string): boolean {
-  const scheme = schemeOf(url);
-  return scheme !== undefined && SCRIPT_SCHEMES.includes(scheme);
-}
 function warnNoHandler(kind: string): void {
   // eslint-disable-next-line no-console
   console.warn(`[kai-card] no policy handler for "${kind}"`);

package/src/primitives/card-schemas/form.schema.json

@@ -11,7 +11,27 @@
     "description": { "type": "string" },
     "required": { "type": "array", "items": { "type": "string" } },
     "properties": {
-      "type": "object"
+      "type": "object",
+      "description": "The fields to collect, keyed by property name. Each value is a JSON Schema field definition (type, title, description, enum, minimum/maximum, minLength/maxLength, pattern, items) plus optional x-kai-* UI hints. Only the display-format hints are spelled out below; the rest of a field definition is ordinary JSON Schema.",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "x-kai-format": {
+            "description": "Display format for a string field. `tel`, `ssn` and `credit-card` apply that type's standard mask and submit digits only; `custom` masks with `x-kai-mask` and submits the formatted value. Omit it for a plain text field.",
+            "enum": ["tel", "ssn", "credit-card", "custom"]
+          },
+          "x-kai-mask": {
+            "description": "The mask pattern, used only with `x-kai-format: \"custom\"`: `#` one digit, `@` one letter or digit, `*` one letter or digit that may be obscured; every other character is a literal shown as typed, e.g. `CHG-####`.",
+            "type": "string",
+            "maxLength": 64
+          },
+          "x-kai-mask-guide": {
+            "description": "Placeholder text shown at the unfilled positions of the mask, aligned character for character with the pattern (`mm/dd/yyyy` for `##/##/####`). Derived from the pattern when omitted.",
+            "type": "string",
+            "maxLength": 64
+          }
+        }
+      }
     },
     "x-kai-order": { "type": "array", "items": { "type": "string" } },
     "x-kai-inlineMax": { "type": "integer", "minimum": 1 },

package/src/primitives/card-validate.ts

@@ -6,8 +6,16 @@
 export interface JsonSchema {
   type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
   const?: unknown;
-  enum?: unknown[];
-  required?: string[];
+  // `readonly`: a construct's card schema is emitted `as const` (codegen.ts,
+  // emitCardsRegistry) so its literal types survive into CardTools' input —
+  // that turns array-valued fields into readonly tuples, which a mutable
+  // `T[]` does not structurally accept even under a `Readonly<Record<...>>`
+  // wrapper. JsonSchema is read-only data everywhere it is consumed (no
+  // caller mutates `.required`/`.enum` in place — see the callers in
+  // tool-defs.ts and form.tsx, which all build a fresh array via spread/
+  // filter/Set before assigning), so widening these two costs nothing.
+  enum?: readonly unknown[];
+  required?: readonly string[];
   properties?: Record<string, JsonSchema>;
   items?: JsonSchema;
   minimum?: number; maximum?: number;

package/src/primitives/chat-config.tsx

@@ -55,22 +55,49 @@ export function useChatConfig(): ChatConfigValue {
   return useContext(ChatConfigContext)!;
 }
 
-/** Maps prose size to Tailwind prose class */
+/**
+ * Maps prose size to the Tailwind Typography *size modifier* for consumers who
+ * render their own `prose` block.
+ *
+ * The `prose-*` names are deliberately NOT re-pointed at the --kai-text-* scale.
+ * They are not font sizes: each is a plugin-generated bundle of proportional
+ * margins, list indents, heading ratios and line-heights for every nested
+ * element, keyed to hardcoded rems, and they only do anything alongside `prose`
+ * itself. There is no `prose-body` to alias them to, and collapsing them to a
+ * bare font-size would throw away the vertical rhythm that is their whole job.
+ * The kit's own markdown does not go through them at all — it renders through
+ * `.chat-markdown` (theme.css), which is em-relative and therefore already
+ * scales off whatever `textClass` sets.
+ *
+ * The one raw font-size here (`xs`) DOES join the semantic scale, so it stays in
+ * step with `textClass('xs')`.
+ */
 export function proseClass(size: ProseSize): string {
   switch (size) {
-    case 'xs': return 'prose-sm text-xs';
+    case 'xs': return 'prose-sm text-meta';
     case 'sm': return 'prose-sm';
     case 'base': return '';
     case 'lg': return 'prose-lg';
   }
 }
 
-/** Maps prose size to a text class for non-prose elements (sidebar, input) */
+/**
+ * Maps prose size to a text class for message content, markdown, and non-prose
+ * chrome (sidebar, input).
+ *
+ * These are the kit's SEMANTIC type-scale utilities, not Tailwind's raw scale:
+ * each resolves through a namespaced --kai-text-* token in theme.css, so a
+ * consumer setting `--kai-text-body` moves the reading text. The public
+ * `proseSize` strings ('xs' | 'sm' | 'base' | 'lg') are unchanged — this is an
+ * internal re-point only. Sizes are byte-identical to the Tailwind classes they
+ * replace (text-meta ≡ text-xs, text-body ≡ text-sm, text-title ≡ text-base),
+ * so nothing moves until a token is actually overridden.
+ */
 export function textClass(size: ProseSize): string {
   switch (size) {
-    case 'xs': return 'text-xs';
-    case 'sm': return 'text-sm';
-    case 'base': return 'text-base';
+    case 'xs': return 'text-meta';
+    case 'sm': return 'text-body';
+    case 'base': return 'text-title';
     case 'lg': return 'text-lg';
   }
 }

package/src/primitives/field-mask.ts

@@ -0,0 +1,256 @@
+// src/primitives/field-mask.ts
+// The pure format engine behind masked form fields: compile a `format` + display guide,
+// normalize arbitrary input to raw, format raw back, and map caret positions between the
+// two. No DOM, no Solid, no state -- the stateful masker (tier 2) and the widgets sit on
+// top of this. Spec: docs/superpowers/specs/2026-08-24-form-field-formats-design.md
+// (§2 tier 2, §3, deltas §5.4 and §5.7).
+//
+// Token vocabulary (a public contract, deliberately adopted rather than reinvented):
+//   `#` one digit  ·  `@` one alphanumeric  ·  `*` one alphanumeric, obscurable in display
+//   every OTHER character is a literal, identified by POSITION and not by character class.
+// That last clause is the load-bearing part: it is why `V-***` works, where a
+// character-class strip reads the literal `V` as user input (see normalizeToRaw).
+
+/** How `normalizeToRaw` folds accepted characters. */
+export type CaseMode = 'preserve' | 'upper' | 'lower';
+
+/** Why an edit was refused. Rejection decides LOUDLY: the stateful layer
+ *  surfaces this on a callback and, on the element facade, as `kai-input-rejected`. */
+export type RejectReason = 'full' | 'wrong-class' | 'over-capacity';
+
+/** A compiled `format` + aligned display guide. Fill positions are `#` `@` `*`;
+ *  every other index is a literal. */
+export interface MaskPattern {
+  readonly format: string;
+  readonly guide: string;          // same length as `format`
+  readonly fillIndexes: readonly number[];
+  readonly capacity: number;       // === fillIndexes.length
+}
+
+/** Thrown by `compileMask` only. Every other function in this module is total: it clamps
+ *  or discards rather than throwing, because it runs on every keystroke. */
+export class MaskError extends Error {}
+
+/** Formats longer than this are refused. A mask is a field format, not a document; the cap
+ *  bounds the per-keystroke walks below and makes a pasted "format" from an untrusted model
+ *  a loud failure instead of a slow one. Refused, NOT truncated -- silently shortening a
+ *  format changes what the field means (CLAUDE.md: decide loudly). */
+const MAX_FORMAT_LENGTH = 64;
+
+const DIGIT = /[0-9]/u;
+const ALPHANUMERIC = /[\p{L}\p{N}]/u;
+
+/** True when `token` is a fill position rather than a literal. */
+function isFillToken(token: string): boolean {
+  return token === '#' || token === '@' || token === '*';
+}
+
+/** The class test for a fill token. `*` is `@` for INPUT purposes -- the two differ only in
+ *  how the display layer renders what was typed, never in what is accepted. */
+function matchesToken(token: string, ch: string): boolean {
+  return token === '#' ? DIGIT.test(ch) : ALPHANUMERIC.test(ch);
+}
+
+/** Compile a format string, with an optional aligned display guide.
+ *
+ *  Without a guide, one is derived: literals keep their own character and every fill
+ *  position becomes a space, which is the alignment the display layer needs and is exactly
+ *  the `V-   ` a consumer would have written by hand for `V-***`. */
+export function compileMask(format: string, guide?: string): MaskPattern {
+  if (format.length > MAX_FORMAT_LENGTH) {
+    throw new MaskError(
+      `format is ${format.length} characters; the maximum is ${MAX_FORMAT_LENGTH}`,
+    );
+  }
+  if (guide !== undefined && guide.length !== format.length) {
+    throw new MaskError(
+      `guide is ${guide.length} characters but format is ${format.length}; they must align position for position`,
+    );
+  }
+
+  const fillIndexes: number[] = [];
+  let derivedGuide = '';
+  for (let i = 0; i < format.length; i += 1) {
+    const token = format[i]!;
+    if (isFillToken(token)) {
+      fillIndexes.push(i);
+      derivedGuide += ' ';
+    } else {
+      derivedGuide += token;
+    }
+  }
+
+  return {
+    format,
+    guide: guide ?? derivedGuide,
+    fillIndexes,
+    capacity: fillIndexes.length,
+  };
+}
+
+/** True when `ch` may occupy raw position `rawIndex`.
+ *
+ *  `ch` must be exactly one UTF-16 code unit. Astral code points (a lone surrogate half
+ *  cannot satisfy `\p{L}`) are outside this engine's model: one fill position holds one
+ *  code unit, which is what keeps `format`, `guide`, the formatted text and the caret
+ *  offsets a DOM input reports all in the same units. The target field family -- phone,
+ *  SSN, ticket numbers, names, postal codes -- is BMP. */
+export function acceptsAt(p: MaskPattern, rawIndex: number, ch: string): boolean {
+  if (rawIndex < 0 || rawIndex >= p.capacity) return false;
+  if (ch.length !== 1) return false;
+  return matchesToken(p.format[p.fillIndexes[rawIndex]!]!, ch);
+}
+
+function fold(ch: string, caseMode: CaseMode): string {
+  if (caseMode === 'upper') return ch.toUpperCase();
+  if (caseMode === 'lower') return ch.toLowerCase();
+  return ch;
+}
+
+/** Raw (fill-position-only) characters extracted from arbitrary input, with
+ *  positional literal consumption and case folding: literals are matched leniently.
+ *
+ *  LITERALS ARE MATCHED WHERE THEY SIT -- this is the fix for a real defect, and both halves
+ *  of it are watched failing in the test file. A strip-then-fill normalizer (drop every
+ *  non-alphanumeric, then fill positions in order) turns a pasted `V-123` under `V-***` into
+ *  raw `V12`, rendered `V-V12`: the literal `V` is alphanumeric, survives the strip, is eaten
+ *  by the first fill position, and the `3` falls off the end -- silently. Consuming only a
+ *  leading literal RUN fixes that one case and leaves the same shape alive one level deeper:
+ *  under `*-V-*`, `A-V-B` puts the interior literal `V` into the second fill position and
+ *  drops the `B`. So the walk below advances over the FORMAT, not over a stripped string,
+ *  and every literal -- leading, interior or trailing -- gets its chance to claim the input
+ *  character sitting in front of it.
+ *
+ *  The two branches, and why lenience is safe here:
+ *  - At a LITERAL, an input character equal to it (case-insensitively) is consumed as that
+ *    literal. A character that is not equal means the input simply omitted the literal, so
+ *    the format advances and the input does not -- which is what lets `chg4821`, `v123` and
+ *    a bare `AB` all normalize correctly.
+ *  - At a FILL, an input character of the right class is taken (folded per `caseMode`) and
+ *    both advance. One of the wrong class is discarded and the position WAITS for the next
+ *    one -- that is what absorbs separators, spaces and the browser's autofill formatting
+ *    (`chg 4821`, `CHG-4821`, `chg4821` all give the same raw).
+ *
+ *  Every iteration either consumes an input character or advances the format, so it
+ *  terminates. Input past the last fill position is clipped -- the caller compares lengths
+ *  to report `over-capacity`. */
+export function normalizeToRaw(p: MaskPattern, input: string, caseMode: CaseMode = 'preserve'): string {
+  let raw = '';
+  let read = 0;
+  let index = 0;
+
+  while (index < p.format.length && read < input.length) {
+    const token = p.format[index]!;
+    if (!isFillToken(token)) {
+      if (input[read]!.toLowerCase() === token.toLowerCase()) read += 1;
+      index += 1;
+      continue;
+    }
+    const folded = fold(input[read]!, caseMode);
+    if (matchesToken(token, folded)) {
+      raw += folded;
+      index += 1;
+    }
+    read += 1;
+  }
+  return raw;
+}
+
+/** Raw formatted for DATA purposes -- the canonical value a `custom` mask submits:
+ *  formatted, with trailing placeholders trimmed. Literals are re-inserted at their positions
+ *  and the string is cut at the first UNFILLED position, because that placeholder and
+ *  everything after it is not yet content.
+ *
+ *  A trailing literal run is NOT a placeholder, so a raw at capacity carries it: `##-END`
+ *  with raw `12` is `12-END`, the same way the literals of `CHG-4821` are part of the ticket
+ *  id rather than presentation. Cutting at `raw.length` instead would silently drop a fixed
+ *  suffix from the submitted datum.
+ *
+ *  Empty raw is `''`, never the bare skeleton (`V-`): an empty field submits `''`, never
+ *  the bare mask template. `formatForDisplay` is the other call site. */
+export function formatRaw(p: MaskPattern, raw: string): string {
+  if (raw.length === 0) return '';
+  let out = '';
+  let pending = ''; // a literal run whose content, if any, is still to come
+  let cursor = 0;
+  for (let i = 0; i < p.format.length; i += 1) {
+    if (!isFillToken(p.format[i]!)) {
+      pending += p.format[i]!;
+    } else if (cursor < raw.length) {
+      out += pending + raw[cursor]!;
+      pending = '';
+      cursor += 1;
+    } else {
+      return out; // an unfilled placeholder: trim it, and the literal run in front of it
+    }
+  }
+  // The format ran out with every position filled, so a literal run still pending is the
+  // format's trailing suffix and belongs to a COMPLETE value (`##-END` + `12` -> `12-END`).
+  return out + pending;
+}
+
+/** Raw formatted for DISPLAY purposes: every unfilled position shows its guide character,
+ *  so the text is always `format.length` long and stays aligned. Empty raw shows the guide
+ *  in full (`mm/dd/yyyy`, `V-   `). */
+export function formatForDisplay(p: MaskPattern, raw: string): string {
+  let out = '';
+  let cursor = 0;
+  for (let i = 0; i < p.format.length; i += 1) {
+    if (isFillToken(p.format[i]!) && cursor < raw.length) {
+      out += raw[cursor]!;
+      cursor += 1;
+    } else {
+      out += p.guide[i] ?? '';
+    }
+  }
+  return out;
+}
+
+/** Raw read back out of formatted text BY POSITION, which is what makes an alphanumeric
+ *  literal safe: the `V` of `V-123` sits at a literal index and is never read as content.
+ *  Stops at the first unfilled position, so a display string's guide characters -- which do
+ *  not satisfy their position's class -- are not mistaken for input. */
+export function rawFromFormatted(p: MaskPattern, formatted: string): string {
+  let raw = '';
+  for (const index of p.fillIndexes) {
+    const ch = formatted[index];
+    if (ch === undefined || !matchesToken(p.format[index]!, ch)) break;
+    raw += ch;
+  }
+  return raw;
+}
+
+/** Caret position in `formatted` -> caret position in raw: the number of FILLED fill
+ *  positions strictly before `pos`. */
+export function formattedToRawIndex(p: MaskPattern, formatted: string, pos: number): number {
+  const clamped = Math.max(0, Math.min(pos, formatted.length));
+  let rawPos = 0;
+  for (const index of p.fillIndexes) {
+    if (index >= clamped) break;
+    const ch = formatted[index];
+    if (ch === undefined || !matchesToken(p.format[index]!, ch)) break;
+    rawPos += 1;
+  }
+  return rawPos;
+}
+
+/** Caret position in raw -> caret position in `formatted`.
+ *
+ *  Raw 0 maps to the FIRST fill index, so the caret never lands inside a leading literal
+ *  prefix. Otherwise it lands just after the last consumed fill position and is then pulled
+ *  forward over any literal run that follows, so it rests where the next character will go
+ *  rather than in front of a separator -- finally clamped to the text that actually exists.
+ *
+ *  The pull-forward is why this is a left inverse of `formattedToRawIndex` on every caret
+ *  position EXCEPT the one immediately before a literal run: that position and the one after
+ *  it map to the same raw index by definition, and only one of the two can come back. The
+ *  post-literal one is canonical: the caret never rests inside a literal run. */
+export function rawToFormattedIndex(p: MaskPattern, formatted: string, rawPos: number): number {
+  if (p.capacity === 0) return Math.min(p.format.length, formatted.length);
+  const clamped = Math.max(0, Math.min(rawPos, p.capacity));
+  if (clamped === 0) return Math.min(p.fillIndexes[0]!, formatted.length);
+
+  let index = p.fillIndexes[clamped - 1]! + 1;
+  while (index < p.format.length && !isFillToken(p.format[index]!)) index += 1;
+  return Math.min(index, formatted.length);
+}

package/src/primitives/field-semantics.ts

@@ -0,0 +1,115 @@
+// src/primitives/field-semantics.ts
+// Tier 1: semantic input types. A semantic type derives the attributes a browser and an
+// assistive technology already know how to use -- `inputmode`, `autocomplete`,
+// `spellcheck`, `autocorrect`, `autocapitalize` -- and the canonical (submitted) form of
+// the field's value. No DOM, no Solid, no state. Spec:
+// docs/superpowers/specs/2026-08-24-form-field-formats-design.md (§2 tier 1, §4).
+//
+// `postal` is DROPPED from the spec's tier-1 table per decided O-2: the enum here is the
+// binding one, exported ONCE and read by the schema, the element facade and the tool
+// projection (CLAUDE.md "derive it, don't type it") -- no second copy of these four
+// strings anywhere else in the tree.
+import { formatRaw, rawFromFormatted, type MaskPattern } from './field-mask';
+
+export const FIELD_SEMANTIC_TYPES = ['tel', 'ssn', 'credit-card', 'custom'] as const;
+export type FieldSemanticType = (typeof FIELD_SEMANTIC_TYPES)[number];
+
+/** The tier-1 attribute bag for one semantic type. */
+export interface FieldSemantics {
+  readonly inputmode?: 'tel' | 'numeric';
+  readonly autocomplete?: string; // `ssn` sends 'off' -- no standard token, so this is a
+                                   // defensive marker against wrong autofill, not an omission
+  readonly spellcheck: false;
+  readonly autocorrect: 'off';
+  readonly autocapitalize: 'off';
+  /** The default tier-2 mask for this type, resolved only when the consumer opts in
+   *  (`mask="default"` / the form card's `x-kai-format`) -- NOT applied automatically
+   *  by a bare semantic type (decision 1). */
+  readonly defaultFormat?: string;
+  /** What the field submits: digit-only types strip separators, `custom`
+   *  keeps its formatted/literal value, `as-typed` is the unmasked fallback. */
+  readonly canonical: 'digits' | 'formatted' | 'as-typed';
+}
+
+const UNMASKED_FALLBACK: FieldSemantics = {
+  spellcheck: false,
+  autocorrect: 'off',
+  autocapitalize: 'off',
+  canonical: 'as-typed',
+};
+
+/** Resolve the tier-1 attribute bag for a semantic type.
+ *
+ *  Passing anything outside `FIELD_SEMANTIC_TYPES` is a TypeScript error at a typed call
+ *  site; a value crossing an untyped boundary (JSON Schema, model output) that turns out
+ *  not to be one of the four falls back to plain unmasked-text behavior at runtime, loudly
+ *  -- `console.warn`, never a silent guess. */
+export function fieldSemantics(type: FieldSemanticType): FieldSemantics {
+  switch (type) {
+    case 'tel':
+      return {
+        inputmode: 'tel',
+        autocomplete: 'tel',
+        spellcheck: false,
+        autocorrect: 'off',
+        autocapitalize: 'off',
+        defaultFormat: '###-###-####',
+        canonical: 'digits',
+      };
+    case 'ssn':
+      return {
+        inputmode: 'numeric',
+        // 'off' -- no standard autocomplete token exists for a Social Security number, and
+        // an absent attribute invites wrong autofill; 'off' is the defensive marker even
+        // where a browser honors it unevenly (spec §2 tier 1 table).
+        autocomplete: 'off',
+        spellcheck: false,
+        autocorrect: 'off',
+        autocapitalize: 'off',
+        defaultFormat: '###-##-####',
+        canonical: 'digits',
+      };
+    case 'credit-card':
+      return {
+        inputmode: 'numeric',
+        autocomplete: 'cc-number',
+        spellcheck: false,
+        autocorrect: 'off',
+        autocapitalize: 'off',
+        defaultFormat: '#### #### #### ####',
+        canonical: 'digits',
+      };
+    case 'custom':
+      // inputmode/autocomplete are INHERITED -- the consumer sets them directly, since a
+      // custom mask carries no semantic of its own. No default format: `mask` IS the format.
+      return {
+        spellcheck: false,
+        autocorrect: 'off',
+        autocapitalize: 'off',
+        canonical: 'formatted',
+      };
+    default: {
+      const unknown: string = type;
+      console.warn(
+        `fieldSemantics: unrecognized semantic type ${JSON.stringify(unknown)}; falling back to unmasked text`,
+      );
+      return UNMASKED_FALLBACK;
+    }
+  }
+}
+
+/** The canonical (submitted) value for a field, given its compiled mask, the current
+ *  FORMATTED text (`input.value`), and its semantic type.
+ *
+ *  Reads the raw value back out of `formatted` by position first -- an empty field is
+ *  always `''`, never the bare guide. From there the two canonical shapes are read, not
+ *  re-derived, per Task 1's handoff: `tel`/`ssn`/`credit-card` want the raw digits
+ *  directly (their formats carry no letters, so raw IS the digit string); `custom` wants
+ *  `formatRaw`, because a literal-terminated custom format (`##-END`) only carries its
+ *  trailing literal once every fill position is full, and `formatRaw` is what tracks that
+ *  -- `rawFromFormatted` gives raw characters only, with no literal reinsertion. */
+export function canonicalize(p: MaskPattern, formatted: string, type: FieldSemanticType): string {
+  const raw = rawFromFormatted(p, formatted);
+  if (raw.length === 0) return '';
+  return type === 'custom' ? formatRaw(p, raw) : raw;
+}