@kitn.ai/ui 0.26.0 → 0.28.0

package/src/primitives/conversation-store.ts

@@ -0,0 +1,248 @@
+/**
+ * The conversations data contract (C-3, C-5, C-7): a JS-property interface,
+ * never REST/events baked into the format. The kit owns the interface, the
+ * payload types (ConversationSummary/ConversationGroup from ../types,
+ * ChatMessage from ../elements/chat-types — reused, never duplicated), and
+ * the lifecycle (list() on mount + list-view open, load() on row select,
+ * save() on message-array change). The dev owns invocation, retrieval,
+ * transport, auth, retention.
+ *
+ * Two built-ins ship: localStorageStore (auto-wired for history: local) and
+ * fetchStore (the recast of codegen.ts's emitHistorySetup endpoint behavior —
+ * same key shapes, same x-kai-user-id header, same decide-loudly failure
+ * mode, now reusable instead of inlined per-construct).
+ */
+import type { ConversationSummary } from '../types';
+import type { ChatMessage } from '../elements/chat-types';
+
+export interface ConversationStore {
+  // `list()`/`load()` implementations MUST return a fresh array (and, for any
+  // item whose content actually differs, a fresh object) on every call —
+  // `ChatThread`'s conversation list and the message array it hands back
+  // through `onConversationLoad` are both reference-keyed `<For>`s, and a
+  // reused array/object reads as "nothing changed" (kai- contract).
+  list(): Promise<ConversationSummary[]>;
+  load(id: string): Promise<ChatMessage[]>;
+  save(id: string, messages: ChatMessage[]): Promise<void>;
+  /** OPTIONAL — unread indicators (owner round, 2026-08-26). Persist
+   *  `ConversationSummary.lastReadAt` (that field's own doc has the exact
+   *  shape) for `id`, called by `ChatThread` whenever that conversation
+   *  counts as "seen": it's the active conversation, the chat view (not the
+   *  list) is showing, and the host is open — on the select/restore
+   *  transition into that state AND on every new message arriving while it
+   *  holds (see `ChatThread`'s `hostOpen` prop doc for the third leg, which
+   *  `ChatThread` cannot know on its own).
+   *
+   *  This is the concept's OPT-IN switch, not a nice-to-have: omit it and no
+   *  summary this store returns ever gets a `lastReadAt`, so every unread
+   *  computation reads "not unread" (that field's absent-means-not-unread
+   *  default) for every conversation, always. That is a DELIBERATE decide-
+   *  loudly default, not a gap — a store that never implements `markRead`
+   *  is read as never supporting the concept at all, and the UI goes quiet
+   *  about it rather than guessing "probably unread" from a comparison it
+   *  has no real signal for. `localStorageStore` implements it below.
+   *  `fetchStore` deliberately does NOT (see its own doc) — it passes
+   *  through whatever `lastReadAt` the backend's own summaries carry, same
+   *  as every other field on `ConversationSummary`, rather than assuming a
+   *  mark-read endpoint the recast contract never defined. */
+  markRead?(id: string): Promise<void>;
+}
+
+export const LEGACY_THREAD_MIGRATED_TITLE = 'Conversation 1';
+
+/** Newest-first ordering over `updatedAt`; rows with a missing or unparsable
+ *  timestamp sort last (stable, so ties keep declaration order). The ONE
+ *  recency rule — the list panel, ChatThread's restore pick, and the home
+ *  screen's recent card all sort with this (issue #335). */
+export function byRecency(
+  a: Pick<ConversationSummary, 'updatedAt'>,
+  b: Pick<ConversationSummary, 'updatedAt'>,
+): number {
+  const at = Date.parse(a.updatedAt ?? '');
+  const bt = Date.parse(b.updatedAt ?? '');
+  return (Number.isNaN(bt) ? -Infinity : bt) - (Number.isNaN(at) ? -Infinity : at);
+}
+
+function threadKey(name: string, userId: string | undefined, id: string): string {
+  return userId ? `kai:${name}:${userId}:thread:${id}` : `kai:${name}:thread:${id}`;
+}
+
+function indexKey(name: string, userId: string | undefined): string {
+  return userId ? `kai:${name}:${userId}:threads` : `kai:${name}:threads`;
+}
+
+/** The legacy pre-conversations single-thread key (codegen.ts's emitHistorySetup). */
+function legacyKey(name: string, userId: string | undefined): string {
+  return userId ? `kai:${name}:${userId}:thread` : `kai:${name}:thread`;
+}
+
+/** ~80-char truncation for the row preview (`ConversationSummary.trailing`,
+ *  widget-box list-view reading), an ellipsis appended only when text was
+ *  actually cut. Mask nothing — the preview is the model/user's own text,
+ *  same trust boundary as the rest of the thread. */
+const PREVIEW_LENGTH = 80;
+function truncatePreview(text: string): string {
+  const trimmed = text.trim();
+  if (trimmed.length <= PREVIEW_LENGTH) return trimmed;
+  return `${trimmed.slice(0, PREVIEW_LENGTH).trimEnd()}…`;
+}
+
+export function localStorageStore(name: string, userId?: string): ConversationStore {
+  const idxKey = indexKey(name, userId);
+
+  function readIndex(): ConversationSummary[] {
+    const raw = localStorage.getItem(idxKey);
+    if (!raw) return [];
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (!Array.isArray(parsed)) throw new Error('index was not an array');
+      return parsed as ConversationSummary[];
+    } catch {
+      console.warn(`[${idxKey}] stored conversation index was corrupt; ignoring and starting fresh`);
+      return [];
+    }
+  }
+
+  function writeIndex(entries: ConversationSummary[]): void {
+    try {
+      localStorage.setItem(idxKey, JSON.stringify(entries));
+    } catch {
+      /* storage unavailable: this browser session runs without persistence */
+    }
+  }
+
+  /** C-7, one-way: an existing legacy single-thread key becomes conversation
+   *  #1 in the index. Runs at most once — the legacy key is deleted after a
+   *  successful migration, so nobody's thread disappears on upgrade and no
+   *  second migration can ever fire. */
+  function migrateLegacyThread(): void {
+    const legacy = legacyKey(name, userId);
+    const raw = localStorage.getItem(legacy);
+    if (!raw) return;
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (!Array.isArray(parsed)) throw new Error('legacy thread was not an array');
+      const messages = parsed as ChatMessage[];
+      const id = crypto.randomUUID();
+      localStorage.setItem(threadKey(name, userId, id), raw);
+      writeIndex([
+        ...readIndex(),
+        {
+          id,
+          title: LEGACY_THREAD_MIGRATED_TITLE,
+          messageCount: messages.length,
+          updatedAt: new Date().toISOString(),
+        },
+      ]);
+      localStorage.removeItem(legacy);
+    } catch {
+      console.warn(`[${legacy}] legacy thread was corrupt; leaving it in place, unmigrated`);
+    }
+  }
+
+  return {
+    async list() {
+      migrateLegacyThread();
+      return readIndex();
+    },
+    async load(id) {
+      const raw = localStorage.getItem(threadKey(name, userId, id));
+      if (!raw) return [];
+      try {
+        const parsed: unknown = JSON.parse(raw);
+        if (!Array.isArray(parsed)) throw new Error('stored thread was not an array');
+        return parsed as ChatMessage[];
+      } catch {
+        console.warn(`[${threadKey(name, userId, id)}] stored thread was corrupt; starting empty`);
+        return [];
+      }
+    },
+    async save(id, messages) {
+      try {
+        localStorage.setItem(threadKey(name, userId, id), JSON.stringify(messages));
+        const entries = readIndex();
+        const now = new Date().toISOString();
+        const existing = entries.find((e) => e.id === id);
+        const lastText = messages.length
+          ? (messages[messages.length - 1].parts.find((p) => p.type === 'text') as { text?: string } | undefined)?.text
+          : undefined;
+        const next: ConversationSummary = {
+          id,
+          title: existing?.title ?? lastText?.slice(0, 60) ?? 'New conversation',
+          messageCount: messages.length,
+          updatedAt: now,
+          // The widget-box list view's one-line preview (Task rework,
+          // 2026-08-26): unlike `title`, re-derived on EVERY save from the
+          // latest message so the preview always reflects where the
+          // conversation actually is, not just where it started.
+          trailing: lastText ? truncatePreview(lastText) : existing?.trailing,
+          // Carried forward unconditionally — save() is a CONTENT event, not
+          // a viewing event, so it must never touch lastReadAt itself. Without
+          // this, every save() (including one for a conversation the visitor
+          // isn't even looking at) would silently wipe its lastReadAt back to
+          // undefined, which reads as "not unread" (see that field's own
+          // doc) — permanently hiding the exact case unread indicators exist
+          // for: a message landing in a conversation nobody is currently
+          // seeing. markRead() below is the only writer of this field.
+          lastReadAt: existing?.lastReadAt,
+        };
+        writeIndex([...entries.filter((e) => e.id !== id), next]);
+      } catch {
+        /* storage unavailable: run in-memory for this tab's lifetime */
+      }
+    },
+    async markRead(id) {
+      try {
+        const entries = readIndex();
+        const idx = entries.findIndex((e) => e.id === id);
+        if (idx === -1) return; // nothing to mark yet (e.g. raced ahead of save()'s first write)
+        const next = [...entries];
+        next[idx] = { ...next[idx], lastReadAt: new Date().toISOString() };
+        writeIndex(next);
+      } catch {
+        /* storage unavailable: run in-memory for this tab's lifetime */
+      }
+    },
+  };
+}
+
+/** The recast of codegen.ts's emitHistorySetup endpoint behavior: the
+ *  consumer's own conversation routes. GET {url} -> ConversationSummary[];
+ *  GET {url}/:id -> ChatMessage[]; PUT {url}/:id with { messages } -> stored.
+ *  x-kai-user-id carries userId on every request, matching the header
+ *  codegen.ts already emits for the endpoint provider and the endpoint
+ *  history persistence mode. Decide loudly: no request here catches its own
+ *  rejection — a caller (ChatThread's lifecycle, Task 2) decides how to
+ *  degrade, exactly as the spec's degradation section requires.
+ *
+ *  No `markRead` (unread indicators, 2026-08-26): the recast contract above
+ *  has no mark-read endpoint, and inventing a fourth request shape here
+ *  would be this adapter deciding a backend behavior rather than passing one
+ *  through. `list()`/`load()` already forward whatever `lastReadAt` the
+ *  backend's own summaries carry, same as any other `ConversationSummary`
+ *  field — a consumer who wants writes needs their own store (or their own
+ *  endpoint plus a thin wrapper), same as any other capability this recast
+ *  doesn't cover. */
+export function fetchStore(url: string, userId?: string): ConversationStore {
+  const headers: Record<string, string> = userId ? { 'x-kai-user-id': userId } : {};
+  return {
+    async list() {
+      const res = await fetch(url, { headers });
+      if (!res.ok) throw new Error(`GET ${url} responded ${res.status}`);
+      return (await res.json()) as ConversationSummary[];
+    },
+    async load(id) {
+      const res = await fetch(`${url}/${id}`, { headers });
+      if (!res.ok) throw new Error(`GET ${url}/${id} responded ${res.status}`);
+      return (await res.json()) as ChatMessage[];
+    },
+    async save(id, messages) {
+      const res = await fetch(`${url}/${id}`, {
+        method: 'PUT',
+        headers: { ...headers, 'content-type': 'application/json' },
+        body: JSON.stringify({ messages }),
+      });
+      if (!res.ok) throw new Error(`PUT ${url}/${id} responded ${res.status}`);
+    },
+  };
+}

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;
+}