@kitn.ai/ui 0.27.0 → 0.29.0

package/src/primitives/embed-providers.ts

@@ -1,254 +0,0 @@
-// src/primitives/embed-providers.ts
-// Pure provider resolution for <kai-embed>: map an EmbedCardData → an embeddable
-// player URL + poster + iframe sandbox/allow. Covers youtube (privacy-enhanced
-// youtube-nocookie), vimeo (dnt=1), and generic (https-only, ORIGIN-ALLOWLISTED).
-// No network, no DOM. See docs/superpowers/specs/2026-06-13-kc-link-embed-cards-design.md.
-import type { CardEnvelope } from './card-contract';
-
-/** Media provider for an embed card. */
-export type EmbedProvider = 'youtube' | 'vimeo' | 'generic';
-
-/** Lazy media-embed payload (YouTube / Vimeo / generic player URL). */
-export interface EmbedCardData {
-  /** Media provider. 'generic' frames `url` directly. */
-  provider: EmbedProvider;
-  /** Provider video id (youtube/vimeo) when not parsing from `url`. */
-  id?: string;
-  /** Full media/watch/embed URL. */
-  url?: string;
-  /** Accessible iframe title + poster label. */
-  title?: string;
-  /** Thumbnail before play; derived for youtube/vimeo when omitted. */
-  poster?: string;
-  /** Start offset, seconds. */
-  start?: number;
-  /** Player aspect ratio. Default '16:9'. */
-  aspectRatio?: '16:9' | '4:3' | '1:1' | '9:16';
-}
-
-/** The full envelope an agent/server emits for an embed card. */
-export type EmbedCardEnvelope = CardEnvelope<'embed', EmbedCardData>;
-
-/** The `type` discriminator for embed cards. */
-export const EMBED_CARD_TYPE = 'embed' as const;
-
-export interface ResolvedEmbed {
-  /** The iframe src loaded on play (already including autoplay/start params). */
-  embedUrl: string;
-  /** Poster/thumbnail to show before play (derived when not supplied). */
-  posterUrl?: string;
-  /** sandbox attribute for the player iframe. */
-  sandbox: string;
-  /** allow attribute (fullscreen, encrypted-media, picture-in-picture, …). */
-  allow: string;
-}
-
-// A provider player NEEDS allow-scripts + allow-same-origin (its OWN origin) to run.
-// That is safe here because the framed origin is a KNOWN, trusted video provider on a
-// DIFFERENT origin than the host — same-origin policy still isolates the host page from
-// the provider. allow-popups(-to-escape-sandbox) lets "watch on YouTube" work. The
-// `allow` attribute (not sandbox) governs autoplay/fullscreen/encrypted-media.
-// Contrast <kai-artifact> (allow-scripts allow-forms, NO allow-same-origin) which frames
-// arbitrary consumer HTML and so trusts nothing.
-const PLAYER_SANDBOX =
-  'allow-scripts allow-same-origin allow-presentation allow-popups allow-popups-to-escape-sandbox';
-const PLAYER_ALLOW =
-  'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen';
-
-// --- generic origin allowlist (security decision) -------------------------
-//
-// A `generic` embed frames an ARBITRARY https URL. An agent-supplied generic URL is a
-// supply-chain risk, so it is REJECTED unless the app has explicitly allowlisted its
-// origin. The allowlist defaults to EMPTY: out of the box, `generic` embeds are blocked.
-const allowedGenericOrigins = new Set<string>();
-
-/**
- * App opt-in: allow `generic` embeds whose origin is in this list. Origins are
- * normalized via the URL parser (scheme + host + port). Only https origins are
- * accepted (a non-https origin is ignored). Call once at app startup.
- */
-export function configureEmbedAllowlist(origins: string[]): void {
-  for (const o of origins) {
-    const origin = normalizeOrigin(o);
-    if (origin) allowedGenericOrigins.add(origin);
-  }
-}
-
-/** True when `url`'s origin has been allowlisted for `generic` embeds. */
-export function isGenericOriginAllowed(url: string): boolean {
-  const origin = originOf(url);
-  return origin !== undefined && allowedGenericOrigins.has(origin);
-}
-
-/** Test-only: clear the generic allowlist so tests stay isolated. */
-export function __resetEmbedAllowlistForTests(): void {
-  allowedGenericOrigins.clear();
-}
-
-/** Normalize an allowlist entry (a URL or bare origin) to a canonical https origin, or undefined. */
-function normalizeOrigin(input: string): string | undefined {
-  const origin = originOf(input) ?? originOf(`https://${input}`);
-  if (!origin) return undefined;
-  return origin.startsWith('https://') ? origin : undefined;
-}
-
-/** The `scheme://host[:port]` origin of a URL, or undefined when unparseable. */
-function originOf(url: string): string | undefined {
-  try {
-    return new URL(url).origin;
-  } catch {
-    return undefined;
-  }
-}
-
-// --- id parsing -----------------------------------------------------------
-
-/** Extract a YouTube id from a watch / youtu.be / shorts / embed URL. */
-export function parseYouTubeId(url: string): string | undefined {
-  let parsed: URL;
-  try {
-    parsed = new URL(url);
-  } catch {
-    return undefined;
-  }
-  const host = parsed.hostname.replace(/^www\./, '');
-  if (host === 'youtu.be') {
-    return cleanId(parsed.pathname.slice(1));
-  }
-  if (host === 'youtube.com' || host === 'm.youtube.com' || host === 'youtube-nocookie.com') {
-    const v = parsed.searchParams.get('v');
-    if (v) return cleanId(v);
-    // /shorts/<id>, /embed/<id>, /v/<id>
-    const m = parsed.pathname.match(/^\/(?:shorts|embed|v)\/([^/?#]+)/);
-    if (m) return cleanId(m[1]);
-  }
-  return undefined;
-}
-
-/** Extract a Vimeo id from a vimeo.com/<id> (or player.vimeo.com/video/<id>) URL. */
-export function parseVimeoId(url: string): string | undefined {
-  let parsed: URL;
-  try {
-    parsed = new URL(url);
-  } catch {
-    return undefined;
-  }
-  const host = parsed.hostname.replace(/^www\./, '');
-  if (host !== 'vimeo.com' && host !== 'player.vimeo.com') return undefined;
-  const m = parsed.pathname.match(/(?:^|\/)(\d+)(?:\/|$)/);
-  return m ? m[1] : undefined;
-}
-
-/** A provider video id must be the [A-Za-z0-9_-] alphabet (matches the schema pattern). */
-function cleanId(id: string): string | undefined {
-  return /^[A-Za-z0-9_-]+$/.test(id) ? id : undefined;
-}
-
-// --- resolution -----------------------------------------------------------
-
-/**
- * Resolve an EmbedCardData to an embeddable player URL + poster + sandbox/allow.
- * Throws (with a human message) on a missing/invalid provider id, a non-https
- * generic URL, or a generic origin not in the app allowlist — the card turns these
- * into an inline error + an `error` event.
- */
-export function resolveEmbed(data: EmbedCardData): ResolvedEmbed {
-  const start = data.start ? `&start=${data.start}` : '';
-  switch (data.provider) {
-    case 'youtube': {
-      const id = data.id ?? (data.url ? parseYouTubeId(data.url) : undefined);
-      if (!id) throw new Error('youtube embed: missing or unparseable id/url');
-      return {
-        embedUrl: `https://www.youtube-nocookie.com/embed/${id}?autoplay=1&rel=0${start}`,
-        posterUrl: data.poster ?? `https://i.ytimg.com/vi/${id}/hqdefault.jpg`,
-        sandbox: PLAYER_SANDBOX,
-        allow: PLAYER_ALLOW,
-      };
-    }
-    case 'vimeo': {
-      const id = data.id ?? (data.url ? parseVimeoId(data.url) : undefined);
-      if (!id) throw new Error('vimeo embed: missing or unparseable id/url');
-      return {
-        embedUrl: `https://player.vimeo.com/video/${id}?autoplay=1&dnt=1${
-          data.start ? `#t=${data.start}s` : ''
-        }`,
-        // Vimeo has no static thumbnail URL; rely on a supplied poster (or placeholder).
-        posterUrl: data.poster,
-        sandbox: PLAYER_SANDBOX,
-        allow: PLAYER_ALLOW,
-      };
-    }
-    case 'generic': {
-      if (!data.url) throw new Error('generic embed: missing url');
-      assertHttpsEmbeddable(data.url);
-      if (!isGenericOriginAllowed(data.url)) {
-        throw new Error(
-          `generic embed: origin not allowlisted — call configureEmbedAllowlist([...]) to permit ${
-            originOf(data.url) ?? data.url
-          }`,
-        );
-      }
-      return { embedUrl: data.url, posterUrl: data.poster, sandbox: PLAYER_SANDBOX, allow: PLAYER_ALLOW };
-    }
-  }
-}
-
-/** Reject non-https or javascript:/data: player URLs (defense in depth). */
-function assertHttpsEmbeddable(url: string): void {
-  let protocol: string;
-  try {
-    protocol = new URL(url).protocol;
-  } catch {
-    throw new Error(`generic embed: invalid url "${url}"`);
-  }
-  if (protocol !== 'https:') {
-    throw new Error(`generic embed: only https player URLs are allowed (got ${protocol})`);
-  }
-}
-
-/**
- * The canonical "watch on the provider" URL for the optional fallback affordance
- * (emitted as `open`/target:'tab' when an embed is blocked). Returns `undefined`
- * when there is nothing useful to link to.
- */
-export function watchUrl(data: EmbedCardData): string | undefined {
-  switch (data.provider) {
-    case 'youtube': {
-      const id = data.id ?? (data.url ? parseYouTubeId(data.url) : undefined);
-      return id ? `https://www.youtube.com/watch?v=${id}` : data.url;
-    }
-    case 'vimeo': {
-      const id = data.id ?? (data.url ? parseVimeoId(data.url) : undefined);
-      return id ? `https://vimeo.com/${id}` : data.url;
-    }
-    case 'generic':
-      return data.url;
-  }
-}
-
-/** Human-readable provider label for the fallback affordance ("Open on YouTube"). */
-export function providerLabel(provider: EmbedProvider): string {
-  switch (provider) {
-    case 'youtube':
-      return 'YouTube';
-    case 'vimeo':
-      return 'Vimeo';
-    case 'generic':
-      return 'site';
-  }
-}
-
-/** CSS aspect-ratio value for a card's aspectRatio (default 16:9). */
-export function aspectRatioValue(aspectRatio: EmbedCardData['aspectRatio']): string {
-  switch (aspectRatio) {
-    case '4:3':
-      return '4 / 3';
-    case '1:1':
-      return '1 / 1';
-    case '9:16':
-      return '9 / 16';
-    case '16:9':
-    default:
-      return '16 / 9';
-  }
-}

package/src/primitives/field-mask.ts

@@ -1,256 +0,0 @@
-// 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

@@ -1,115 +0,0 @@
-// 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;
-}