@greensecurity/javascript-sdk 0.46.0-beta.1 → 0.46.0-beta.11

package/src/apps/components.ts

@@ -0,0 +1,824 @@
+/*
+ * Hand-written (not generated by Speakeasy). Part of the third-party app platform contract;
+ * see docs/third-party-apps/plan.md.
+ *
+ * The closed set of elements an app can render. The SDK wraps each entry with
+ * `createRemoteComponent` (remote side) and web-mobile-client maps each tag to a component from
+ * `components/ui` (host side); both read their prop names, events and slots from here.
+ *
+ * Styling is tokens only. There is no `style`, `className` or colour value an app can pass, and
+ * every URL-shaped prop is typed so the host can refuse what the manifest did not grant.
+ */
+
+import { isHttpsUrl } from "./url.js";
+import { isRouteDescriptor, type RouteDescriptor } from "./route.js";
+
+// ---------------------------------------------------------------------------------------------
+// Tokens
+
+export const SPACING = ["0", "xxsmall", "xsmall", "small", "medium", "large", "xlarge", "xxlarge"] as const;
+export const TEXT_COLORS = ["primary", "secondary", "disabled", "info", "success", "attention", "critical", "brand"] as const;
+export const FONTS = ["body", "bodyEmphasized", "caption", "heading", "kicker", "lead", "subheading", "subtitle", "title"] as const;
+export const FONT_WEIGHTS = ["regular", "semibold", "bold"] as const;
+export const WIDTHS = ["fill", "fit", "1/2", "1/3", "2/3", "1/4", "3/4"] as const;
+export const SIZES = ["small", "medium", "large"] as const;
+export const ALIGN_X = ["start", "center", "end", "stretch"] as const;
+export const ALIGN_Y = ["top", "center", "baseline", "bottom", "stretch"] as const;
+
+/** Icons an app may name. The host maps each to an icon it already ships. */
+export const ICON_NAMES = [
+  "add", "alert", "arrowLeft", "arrowRight", "calendar", "check", "chevronDown", "chevronRight",
+  "clipboard", "close", "copy", "credential", "delete", "document", "download", "edit", "external",
+  "facility", "filter", "info", "link", "lock", "mail", "more", "person", "phone", "refresh",
+  "search", "settings", "star", "upload", "warning",
+] as const;
+
+// ---------------------------------------------------------------------------------------------
+// Spec builders
+
+export type PropSpec =
+  /** `format: "date"` additionally requires an ISO 8601 calendar date (`YYYY-MM-DD`) that exists. */
+  | { readonly type: "string"; readonly required?: boolean; readonly maxLength?: number; readonly format?: "date" }
+  /** A finite number, optionally an integer and within `[min, max]`. */
+  | { readonly type: "number"; readonly required?: boolean; readonly integer?: boolean; readonly min?: number; readonly max?: number }
+  | { readonly type: "boolean"; readonly required?: boolean }
+  | { readonly type: "enum"; readonly values: readonly string[]; readonly required?: boolean }
+  /** A `RouteDescriptor`, or an https URL the host opens through `HostApi.openExternalUrl`. */
+  | { readonly type: "href"; readonly required?: boolean }
+  /** An https or `data:image/` URL; the host additionally requires it to match the manifest's `image_src`. */
+  | { readonly type: "imageSrc"; readonly required?: boolean }
+  /** A plain JSON value of a fixed shape, checked by `check`. */
+  | { readonly type: "json"; readonly required?: boolean; readonly check: (v: unknown) => boolean; readonly __t?: unknown };
+
+type Req<R extends boolean> = R extends true ? { readonly required: true } : {};
+
+const p = {
+  string: <R extends boolean = false>(o: { required?: R; maxLength?: number; format?: "date" } = {}) =>
+    ({ type: "string", ...o }) as { readonly type: "string"; readonly maxLength?: number; readonly format?: "date" } & Req<R>,
+  number: <R extends boolean = false>(o: { required?: R; integer?: boolean; min?: number; max?: number } = {}) =>
+    ({ type: "number", ...o }) as { readonly type: "number"; readonly integer?: boolean; readonly min?: number; readonly max?: number } & Req<R>,
+  boolean: () => ({ type: "boolean" }) as const,
+  enum: <const V extends readonly string[], R extends boolean = false>(values: V, o: { required?: R } = {}) =>
+    ({ type: "enum", values, ...o }) as { readonly type: "enum"; readonly values: V } & Req<R>,
+  href: () => ({ type: "href" }) as const,
+  imageSrc: <R extends boolean = false>(o: { required?: R } = {}) =>
+    ({ type: "imageSrc", ...o }) as { readonly type: "imageSrc" } & Req<R>,
+  json: <T, R extends boolean = false>(check: (v: unknown) => v is T, o: { required?: R } = {}) =>
+    ({ type: "json", check, ...o }) as { readonly type: "json"; readonly check: (v: unknown) => boolean; readonly __t?: T } & Req<R>,
+};
+
+/** An event the host dispatches. `detail` is the single argument the app's handler receives. */
+export interface EventSpec<Detail = void> {
+  readonly event: string;
+  readonly __detail?: Detail;
+}
+const ev = <Detail = void>(event: string): EventSpec<Detail> => ({ event });
+
+export interface ComponentSpec {
+  readonly tagName: string;
+  readonly props: Readonly<Record<string, PropSpec>>;
+  readonly events: Readonly<Record<string, EventSpec<unknown>>>;
+  readonly slots: readonly string[];
+  /** Whether bare text children are allowed. The host wraps them in its text component. */
+  readonly text: boolean;
+  /** Tag names allowed as direct children; `null` means any non-root component. */
+  readonly children: readonly string[] | null;
+  readonly root?: true;
+}
+
+// The defaults matter: when an entry omits `props`, `events` or `slots`, inference would otherwise
+// fall back to the constraint (`Record<string, …>`), whose string index signature turns into a
+// catch-all key in `ComponentProps` that every real prop conflicts with.
+function spec<
+  const P extends Record<string, PropSpec> = {},
+  const E extends Record<string, EventSpec<unknown>> = {},
+  const S extends readonly string[] = [],
+>(tagName: string, def: { props?: P; events?: E; slots?: S; text?: boolean; children?: readonly string[] | null; root?: true }) {
+  return {
+    tagName,
+    props: (def.props ?? {}) as P,
+    events: (def.events ?? {}) as E,
+    slots: (def.slots ?? []) as unknown as S,
+    text: def.text ?? false,
+    children: def.children === undefined ? null : def.children,
+    ...(def.root ? { root: true as const } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Shared prop groups
+
+const layout = {
+  stack: p.enum(["x", "y"] as const),
+  gap: p.enum(SPACING),
+  padding: p.enum(SPACING),
+  paddingX: p.enum(SPACING),
+  paddingY: p.enum(SPACING),
+  marginTop: p.enum(SPACING),
+  marginBottom: p.enum(SPACING),
+  alignX: p.enum(ALIGN_X),
+  alignY: p.enum(ALIGN_Y),
+  distribute: p.enum(["packed", "space-between"] as const),
+  wrap: p.boolean(),
+  width: p.enum(WIDTHS),
+  background: p.enum(["container", "surface"] as const),
+  border: p.enum(["none", "neutral", "critical"] as const),
+  radius: p.enum(["none", "small", "medium", "large", "rounded"] as const),
+};
+
+const typography = {
+  font: p.enum(FONTS),
+  color: p.enum(TEXT_COLORS),
+  fontWeight: p.enum(FONT_WEIGHTS),
+  align: p.enum(["start", "center", "end"] as const),
+};
+
+// Every form control needs an accessible name, so `label` is required. `hideLabel` hides it
+// visually while the host still exposes it to assistive technology.
+const field = {
+  label: p.string({ required: true, maxLength: 200 }),
+  hideLabel: p.boolean(),
+  description: p.string({ maxLength: 500 }),
+  error: p.string({ maxLength: 500 }),
+  name: p.string({ maxLength: 100 }),
+  disabled: p.boolean(),
+  required: p.boolean(),
+};
+
+const isStringRecord = (v: unknown): v is Record<string, string> =>
+  typeof v === "object" && v !== null && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");
+
+export interface ExternalLink { href: string; label: string }
+// Text a user reads or presses must be non-blank, or the control has no accessible name.
+const isVisibleText = (v: unknown, maxLength: number): boolean =>
+  typeof v === "string" && v.trim().length > 0 && v.length <= maxLength;
+
+const isExternalLink = (v: unknown): v is ExternalLink =>
+  isStringRecord(v) && isHttpsUrl(v["href"]) && isVisibleText(v["label"], 100);
+
+export interface ConfirmCloseMessages { title: string; description: string; cancelAction: string; exitAction: string }
+const isConfirmCloseMessages = (v: unknown): v is ConfirmCloseMessages =>
+  isStringRecord(v) && isVisibleText(v["title"], 100) && isVisibleText(v["description"], 500) &&
+  isVisibleText(v["cancelAction"], 50) && isVisibleText(v["exitAction"], 50);
+
+const TABLE_CELL = { align: p.enum(["start", "center", "end"] as const), width: p.enum(WIDTHS) };
+
+// ---------------------------------------------------------------------------------------------
+// Charts
+//
+// Charts take data only. Colours come from a named `theme`; there are no colour, font, size or
+// style props. Every value is a finite number >= 0 (v1 draws no negative axis), and every label
+// and series name is visible text the host draws on an axis, legend or tooltip.
+
+/** Named palettes the host draws charts with. The host uses `"green"` when `theme` is omitted. */
+export const CHART_THEMES = ["green", "grayscale", "vibrant"] as const;
+
+/** Most series a stacked, line or area chart may draw: one per palette colour. */
+export const MAX_CHART_SERIES = 6;
+/**
+ * Largest accepted chart value. Every chart caps its item and series counts, so with each value at
+ * most this, any total a chart computes (a stack, a pie) stays finite; two values near
+ * `Number.MAX_VALUE` would otherwise sum to `Infinity`.
+ */
+export const MAX_CHART_VALUE = Number.MAX_SAFE_INTEGER;
+
+/** Longest label or series name, in characters. */
+export const MAX_CHART_LABEL_LENGTH = 60;
+
+/** One bar or slice: `label` names it, `value` is its size. */
+export interface ChartDatum { label: string; value: number }
+/** A named series with one value per label of the chart it belongs to. */
+export interface ChartSeries { name: string; values: number[] }
+/** Labels along the category axis and the series drawn against them. */
+export interface SeriesChartData { labels: string[]; series: ChartSeries[] }
+/** Bars and a line drawn over the same labels. */
+export interface ComboChartData { labels: string[]; bars: ChartSeries; line: ChartSeries }
+/**
+ * The detail of a chart's `onClick`: the position and label of the pressed bar, point or slice,
+ * its value, and, on a multi-series chart, the name of its series.
+ */
+export interface ChartClickEvent { index: number; label: string; value: number; series?: string }
+
+/** Item-count bounds for {@link isChartData}. */
+export interface ChartDataLimits { minItems: number; maxItems: number }
+/** Label- and series-count bounds for {@link isSeriesChartData}; `maxSeries` defaults to {@link MAX_CHART_SERIES}. */
+export interface SeriesChartDataLimits { minLabels: number; maxLabels: number; maxSeries?: number }
+/** Label-count bounds for {@link isComboChartData}. */
+export interface ComboChartDataLimits { minLabels: number; maxLabels: number }
+
+/** The bounds each chart component's `data` is checked against. */
+export const CHART_DATA_LIMITS = {
+  BarChart: { minItems: 1, maxItems: 31 },
+  HorizontalBarChart: { minItems: 1, maxItems: 25 },
+  StackedBarChart: { minLabels: 1, maxLabels: 31, maxSeries: MAX_CHART_SERIES },
+  LineChart: { minLabels: 2, maxLabels: 60, maxSeries: MAX_CHART_SERIES },
+  AreaChart: { minLabels: 2, maxLabels: 60, maxSeries: MAX_CHART_SERIES },
+  ComboChart: { minLabels: 1, maxLabels: 31 },
+  // The host folds everything past the sixth slice into one "Other" slice.
+  PieChart: { minItems: 1, maxItems: 50 },
+} as const satisfies Record<string, ChartDataLimits | SeriesChartDataLimits | ComboChartDataLimits>;
+
+// Plain data only, as JSON and remote-dom carry it: no class instances (Date, Map, a subclassed
+// Array) whose prototype the host would otherwise have to trust.
+const isPlainObject = (v: unknown): v is Record<string, unknown> => {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
+  const proto: unknown = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+};
+const isPlainArray = (v: unknown): v is unknown[] => Array.isArray(v) && Object.getPrototypeOf(v) === Array.prototype;
+// Exactly these keys: the shapes are closed, which also bounds their nesting depth.
+const hasExactKeys = (v: Record<string, unknown>, keys: readonly string[]): boolean => {
+  const own = Object.keys(v);
+  return own.length === keys.length && keys.every((k) => Object.prototype.hasOwnProperty.call(v, k));
+};
+const isChartValue = (v: unknown): v is number =>
+  typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= MAX_CHART_VALUE;
+const isChartLabel = (v: unknown): v is string => isVisibleText(v, MAX_CHART_LABEL_LENGTH);
+
+// Indexed loops rather than `every`, which skips the holes of a sparse array.
+function isLabelList(v: unknown, min: number, max: number): v is string[] {
+  if (!isPlainArray(v) || v.length < min || v.length > max) return false;
+  const seen = new Set<string>();
+  for (let i = 0; i < v.length; i++) {
+    const label = v[i];
+    if (!isChartLabel(label) || seen.has(label)) return false;
+    seen.add(label);
+  }
+  return true;
+}
+
+function isChartSeries(v: unknown, length: number): v is ChartSeries {
+  if (!isPlainObject(v) || !hasExactKeys(v, ["name", "values"]) || !isChartLabel(v["name"])) return false;
+  const values = v["values"];
+  if (!isPlainArray(values) || values.length !== length) return false;
+  for (let i = 0; i < values.length; i++) if (!isChartValue(values[i])) return false;
+  return true;
+}
+
+/**
+ * `ChartDatum[]` with between `minItems` and `maxItems` items, each a visible, unique label of at
+ * most {@link MAX_CHART_LABEL_LENGTH} characters and a value from 0 to {@link MAX_CHART_VALUE}.
+ */
+export function isChartData(value: unknown, limits: ChartDataLimits): value is ChartDatum[] {
+  if (!isPlainArray(value) || value.length < limits.minItems || value.length > limits.maxItems) return false;
+  const seen = new Set<string>();
+  for (let i = 0; i < value.length; i++) {
+    const item = value[i];
+    if (!isPlainObject(item) || !hasExactKeys(item, ["label", "value"])) return false;
+    const label = item["label"];
+    if (!isChartLabel(label) || seen.has(label) || !isChartValue(item["value"])) return false;
+    seen.add(label);
+  }
+  return true;
+}
+
+/** Label of the slice a pie chart creates when it combines items beyond {@link MAX_CHART_SERIES}. */
+export const CHART_OTHER_LABEL = "Other";
+
+/**
+ * Pie chart data: {@link isChartData} with `CHART_DATA_LIMITS.PieChart`. When there are more
+ * items than {@link MAX_CHART_SERIES}, the host combines the extras into a {@link CHART_OTHER_LABEL}
+ * slice, so a caller's own `Other` label (any case, ignoring surrounding spaces) is rejected:
+ * the chart would show two slices with that name and their click events could not be told apart.
+ */
+export function isPieChartData(value: unknown): value is ChartDatum[] {
+  if (!isChartData(value, CHART_DATA_LIMITS.PieChart)) return false;
+  if (value.length <= MAX_CHART_SERIES) return true;
+  const reserved = CHART_OTHER_LABEL.toLowerCase();
+  return value.every((item) => item.label.trim().toLowerCase() !== reserved);
+}
+
+/**
+ * `SeriesChartData` with between `minLabels` and `maxLabels` unique labels and between 1 and
+ * `maxSeries` uniquely named series, each with exactly one value from 0 to {@link MAX_CHART_VALUE} per label.
+ */
+export function isSeriesChartData(value: unknown, limits: SeriesChartDataLimits): value is SeriesChartData {
+  if (!isPlainObject(value) || !hasExactKeys(value, ["labels", "series"])) return false;
+  const labels = value["labels"];
+  const series = value["series"];
+  const maxSeries = limits.maxSeries ?? MAX_CHART_SERIES;
+  if (!isLabelList(labels, limits.minLabels, limits.maxLabels)) return false;
+  if (!isPlainArray(series) || series.length < 1 || series.length > maxSeries) return false;
+  const names = new Set<string>();
+  for (let i = 0; i < series.length; i++) {
+    const s = series[i];
+    if (!isChartSeries(s, labels.length) || names.has(s.name)) return false;
+    names.add(s.name);
+  }
+  return true;
+}
+
+/**
+ * `ComboChartData` with between `minLabels` and `maxLabels` unique labels, and a `bars` and a
+ * `line` series with different names, each with exactly one value from 0 to {@link MAX_CHART_VALUE} per label.
+ */
+export function isComboChartData(value: unknown, limits: ComboChartDataLimits): value is ComboChartData {
+  if (!isPlainObject(value) || !hasExactKeys(value, ["labels", "bars", "line"])) return false;
+  const labels = value["labels"];
+  const bars = value["bars"];
+  const line = value["line"];
+  return isLabelList(labels, limits.minLabels, limits.maxLabels) &&
+    isChartSeries(bars, labels.length) && isChartSeries(line, labels.length) && bars.name !== line.name;
+}
+
+const chart = <T>(check: (v: unknown) => v is T) => ({
+  props: { data: p.json(check, { required: true }), theme: p.enum(CHART_THEMES), interactive: p.boolean() },
+  events: { onClick: ev<ChartClickEvent>("click") },
+  children: [] as const,
+});
+
+// ---------------------------------------------------------------------------------------------
+// Catalog
+
+export const COMPONENTS = {
+  // View roots. An app's view component must render exactly one of these at its top level:
+  // ContextView on a surface, SettingsView on the settings page, PageView on an app page.
+  ContextView: spec("ui-context-view", {
+    root: true,
+    props: { title: p.string({ required: true, maxLength: 100 }), description: p.string({ maxLength: 300 }), externalLink: p.json(isExternalLink) },
+    slots: ["actions", "banner", "footerContent", "primaryAction", "secondaryAction"] as const,
+  }),
+  FocusView: spec("ui-focus-view", {
+    props: {
+      title: p.string({ required: true, maxLength: 100 }),
+      shown: p.boolean(),
+      size: p.enum(["small", "large"] as const),
+      confirmCloseMessages: p.json(isConfirmCloseMessages),
+    },
+    // The host asks to close (backdrop, back gesture, close button); the app owns `shown`.
+    events: { onShownChange: ev<boolean>("shownchange") },
+    slots: ["footerContent", "primaryAction", "secondaryAction"] as const,
+  }),
+  SettingsView: spec("ui-settings-view", {
+    root: true,
+    props: { statusMessage: p.string({ maxLength: 100 }) },
+    // `values` maps every form field's `name` to its current value.
+    events: { onSave: ev<Record<string, string>>("save") },
+  }),
+  // An app page (`ui_extensions.routes`), rendered full width inside the portal's own chrome. The
+  // title is the page header; `actions` join the portal header's actions, `banner` sits above the body.
+  PageView: spec("ui-page-view", {
+    root: true,
+    props: { title: p.string({ required: true, maxLength: 100 }), description: p.string({ maxLength: 300 }) },
+    slots: ["actions", "banner"] as const,
+  }),
+
+  // Layout
+  Box: spec("ui-box", { props: { ...layout, ...typography }, text: true }),
+  // Rendered inside the host's native text element, where only text-level children are valid
+  // (a View-backed child such as a Button crashes React Native), so children are restricted.
+  Inline: spec("ui-inline", { props: typography, text: true, children: ["ui-inline", "ui-link"] }),
+  Divider: spec("ui-divider", { props: { orientation: p.enum(["horizontal", "vertical"] as const) }, children: [] }),
+  Card: spec("ui-card", { props: { variant: p.enum(["elevated", "outline", "ghost", "filled"] as const), padding: p.enum(SPACING) } }),
+
+  // Text and status
+  Text: spec("ui-text", { props: { ...typography, truncate: p.boolean() }, text: true, children: ["ui-inline", "ui-link"] }),
+  Heading: spec("ui-heading", { props: { size: p.enum(SIZES) }, text: true, children: [] }),
+  Badge: spec("ui-badge", { props: { type: p.enum(["neutral", "info", "positive", "negative", "warning", "urgent"] as const) }, text: true, children: [] }),
+  Banner: spec("ui-banner", {
+    props: { type: p.enum(["default", "caution", "critical"] as const), title: p.string({ maxLength: 200 }), description: p.string({ maxLength: 1000 }) },
+    events: { onDismiss: ev("dismiss") },
+    slots: ["actions"] as const,
+    children: [],
+  }),
+  Spinner: spec("ui-spinner", { props: { size: p.enum(SIZES) }, children: [] }),
+  Progress: spec("ui-progress", { props: { value: p.number({ required: true, min: 0, max: 100 }), label: p.string({ maxLength: 200 }) }, children: [] }),
+  Icon: spec("ui-icon", { props: { name: p.enum(ICON_NAMES, { required: true }), size: p.enum(SIZES), color: p.enum(TEXT_COLORS) }, children: [] }),
+  Img: spec("ui-img", {
+    props: { src: p.imageSrc({ required: true }), alt: p.string({ required: true, maxLength: 300 }), width: p.number({ integer: true, min: 1, max: 4096 }), height: p.number({ integer: true, min: 1, max: 4096 }) },
+    children: [],
+  }),
+  Avatar: spec("ui-avatar", { props: { name: p.string({ required: true, maxLength: 100 }), src: p.imageSrc(), size: p.enum(SIZES) }, children: [] }),
+
+  // Actions
+  // A Button or Link whose only content is an icon has no visible text, so `accessibilityLabel`
+  // names it for assistive technology. The host renders neither control without a non-blank
+  // text child or `accessibilityLabel`.
+  Button: spec("ui-button", {
+    props: {
+      type: p.enum(["primary", "secondary", "destructive"] as const),
+      size: p.enum(SIZES),
+      disabled: p.boolean(),
+      pending: p.boolean(),
+      href: p.href(),
+      width: p.enum(WIDTHS),
+      accessibilityLabel: p.string({ maxLength: 200 }),
+    },
+    events: { onPress: ev("press") },
+    text: true,
+    children: ["ui-icon"],
+  }),
+  ButtonGroup: spec("ui-button-group", { props: { direction: p.enum(["row", "column"] as const) }, children: ["ui-button"] }),
+  Link: spec("ui-link", {
+    props: {
+      type: p.enum(["primary", "secondary"] as const),
+      href: p.href(),
+      disabled: p.boolean(),
+      accessibilityLabel: p.string({ maxLength: 200 }),
+    },
+    events: { onPress: ev("press") },
+    text: true,
+    children: ["ui-icon"],
+  }),
+  Menu: spec("ui-menu", { events: { onAction: ev<string>("action") }, slots: ["trigger"] as const, children: ["ui-menu-item", "ui-menu-group"] }),
+  MenuGroup: spec("ui-menu-group", { props: { title: p.string({ maxLength: 100 }) }, children: ["ui-menu-item"] }),
+  MenuItem: spec("ui-menu-item", {
+    props: { id: p.string({ required: true, maxLength: 100 }), disabled: p.boolean() },
+    events: { onPress: ev("press") },
+    text: true,
+    children: [],
+  }),
+
+  // Content
+  Accordion: spec("ui-accordion", { children: ["ui-accordion-item"] }),
+  AccordionItem: spec("ui-accordion-item", {
+    props: { title: p.string({ required: true, maxLength: 200 }), subtitle: p.string({ maxLength: 200 }), defaultOpen: p.boolean() },
+  }),
+  List: spec("ui-list", { events: { onAction: ev<string>("action") }, children: ["ui-list-item"] }),
+  ListItem: spec("ui-list-item", {
+    props: {
+      id: p.string({ required: true, maxLength: 100 }),
+      title: p.string({ required: true, maxLength: 200 }),
+      secondaryTitle: p.string({ maxLength: 200 }),
+      icon: p.enum(ICON_NAMES),
+      size: p.enum(["default", "large"] as const),
+    },
+    slots: ["value"] as const,
+    children: [],
+  }),
+  PropertyList: spec("ui-property-list", { props: { orientation: p.enum(["vertical", "horizontal"] as const) }, children: ["ui-property-list-item"] }),
+  PropertyListItem: spec("ui-property-list-item", {
+    props: { label: p.string({ required: true, maxLength: 200 }), value: p.string({ maxLength: 1000 }) },
+    slots: ["value"] as const,
+    children: [],
+  }),
+  Table: spec("ui-table", { children: ["ui-table-head", "ui-table-body"] }),
+  TableHead: spec("ui-table-head", { children: ["ui-table-row"] }),
+  TableBody: spec("ui-table-body", { children: ["ui-table-row"] }),
+  TableRow: spec("ui-table-row", { children: ["ui-table-header-cell", "ui-table-cell"] }),
+  TableHeaderCell: spec("ui-table-header-cell", { props: TABLE_CELL, text: true }),
+  TableCell: spec("ui-table-cell", { props: TABLE_CELL, text: true }),
+  Tabs: spec("ui-tabs", {
+    props: { selectedKey: p.string({ maxLength: 100 }), fitted: p.boolean() },
+    events: { onSelectionChange: ev<string>("selectionchange") },
+    children: ["ui-tab-list", "ui-tab-panels"],
+  }),
+  TabList: spec("ui-tab-list", { children: ["ui-tab"] }),
+  Tab: spec("ui-tab", { props: { id: p.string({ required: true, maxLength: 100 }), disabled: p.boolean() }, text: true, children: [] }),
+  TabPanels: spec("ui-tab-panels", { children: ["ui-tab-panel"] }),
+  TabPanel: spec("ui-tab-panel", { props: { id: p.string({ required: true, maxLength: 100 }) } }),
+
+  // Forms. Uncontrolled use (`defaultValue` + `onChange`) is recommended: every keystroke of a
+  // controlled `value` makes a round trip through the sandbox.
+  TextField: spec("ui-text-field", {
+    props: {
+      ...field,
+      placeholder: p.string({ maxLength: 200 }),
+      value: p.string({ maxLength: 10000 }),
+      defaultValue: p.string({ maxLength: 10000 }),
+      type: p.enum(["text", "number", "email", "tel", "url", "password", "search"] as const),
+      readOnly: p.boolean(),
+      maxLength: p.number({ integer: true, min: 1, max: 10000 }),
+      autoFocus: p.boolean(),
+    },
+    events: { onChange: ev<string>("change"), onBlur: ev("blur"), onFocus: ev("focus") },
+    children: [],
+  }),
+  TextArea: spec("ui-text-area", {
+    props: {
+      ...field,
+      placeholder: p.string({ maxLength: 200 }),
+      value: p.string({ maxLength: 50000 }),
+      defaultValue: p.string({ maxLength: 50000 }),
+      rows: p.number({ integer: true, min: 1, max: 50 }),
+      readOnly: p.boolean(),
+      maxLength: p.number({ integer: true, min: 1, max: 50000 }),
+    },
+    events: { onChange: ev<string>("change"), onBlur: ev("blur"), onFocus: ev("focus") },
+    children: [],
+  }),
+  Select: spec("ui-select", {
+    props: { ...field, placeholder: p.string({ maxLength: 200 }), value: p.string({ maxLength: 500 }), defaultValue: p.string({ maxLength: 500 }) },
+    events: { onChange: ev<string>("change") },
+    children: ["ui-select-option"],
+  }),
+  SelectOption: spec("ui-select-option", {
+    props: { value: p.string({ required: true, maxLength: 500 }), label: p.string({ required: true, maxLength: 200 }), disabled: p.boolean() },
+    children: [],
+  }),
+  Checkbox: spec("ui-checkbox", {
+    props: { ...field, checked: p.boolean(), defaultChecked: p.boolean(), invalid: p.boolean() },
+    events: { onChange: ev<boolean>("change") },
+    children: [],
+  }),
+  RadioGroup: spec("ui-radio-group", {
+    props: { ...field, value: p.string({ maxLength: 500 }), defaultValue: p.string({ maxLength: 500 }) },
+    events: { onChange: ev<string>("change") },
+    children: ["ui-radio"],
+  }),
+  Radio: spec("ui-radio", {
+    props: { value: p.string({ required: true, maxLength: 500 }), label: p.string({ required: true, maxLength: 200 }), disabled: p.boolean() },
+    children: [],
+  }),
+  Switch: spec("ui-switch", {
+    props: { ...field, checked: p.boolean(), defaultChecked: p.boolean() },
+    events: { onChange: ev<boolean>("change") },
+    children: [],
+  }),
+  DateField: spec("ui-date-field", {
+    props: {
+      ...field,
+      // ISO 8601 calendar dates (YYYY-MM-DD) that exist: 2026-02-31 is refused.
+      value: p.string({ maxLength: 10, format: "date" }),
+      defaultValue: p.string({ maxLength: 10, format: "date" }),
+      min: p.string({ maxLength: 10, format: "date" }),
+      max: p.string({ maxLength: 10, format: "date" }),
+    },
+    events: { onChange: ev<string>("change") },
+    children: [],
+  }),
+  FormFieldGroup: spec("ui-form-field-group", {
+    props: { legend: p.string({ maxLength: 200 }), description: p.string({ maxLength: 500 }), layout: p.enum(["row", "column"] as const) },
+  }),
+
+  // Charts. Data only: `theme` picks the palette, `interactive` turns on press feedback and
+  // tooltips, and `onClick` receives a `ChartClickEvent`. Bounds are in `CHART_DATA_LIMITS`.
+  BarChart: spec("ui-bar-chart", chart((v): v is ChartDatum[] => isChartData(v, CHART_DATA_LIMITS.BarChart))),
+  HorizontalBarChart: spec("ui-horizontal-bar-chart", chart((v): v is ChartDatum[] => isChartData(v, CHART_DATA_LIMITS.HorizontalBarChart))),
+  StackedBarChart: spec("ui-stacked-bar-chart", chart((v): v is SeriesChartData => isSeriesChartData(v, CHART_DATA_LIMITS.StackedBarChart))),
+  LineChart: spec("ui-line-chart", chart((v): v is SeriesChartData => isSeriesChartData(v, CHART_DATA_LIMITS.LineChart))),
+  AreaChart: spec("ui-area-chart", chart((v): v is SeriesChartData => isSeriesChartData(v, CHART_DATA_LIMITS.AreaChart))),
+  ComboChart: spec("ui-combo-chart", chart((v): v is ComboChartData => isComboChartData(v, CHART_DATA_LIMITS.ComboChart))),
+  PieChart: spec("ui-pie-chart", chart(isPieChartData)),
+} as const;
+
+// Checked by assignment rather than `satisfies`: `satisfies` would hand `ComponentSpec` to every
+// `spec()` call as a contextual return type, and inference would then widen each entry's props,
+// events and slots to the constraint, erasing the literal types `ComponentProps` is built from.
+const catalogIsComponentSpecs: Readonly<Record<string, ComponentSpec>> = COMPONENTS;
+void catalogIsComponentSpecs;
+
+export type ComponentName = keyof typeof COMPONENTS;
+export type TagName = (typeof COMPONENTS)[ComponentName]["tagName"];
+
+// ---------------------------------------------------------------------------------------------
+// Types derived from the catalog
+
+type ValueOf<S> =
+  S extends { type: "string" } ? string :
+  S extends { type: "number" } ? number :
+  S extends { type: "boolean" } ? boolean :
+  S extends { type: "enum"; values: readonly (infer V)[] } ? V :
+  S extends { type: "href" } ? RouteDescriptor | string :
+  S extends { type: "imageSrc" } ? string :
+  S extends { type: "json"; __t?: infer T } ? T :
+  never;
+
+type RequiredKeys<P> = { [K in keyof P]: P[K] extends { required: true } ? K : never }[keyof P];
+type OptionalKeys<P> = Exclude<keyof P, RequiredKeys<P>>;
+
+type DataProps<P> =
+  { [K in RequiredKeys<P>]: ValueOf<P[K]> } &
+  { [K in OptionalKeys<P>]?: ValueOf<P[K]> };
+
+// `[D] extends [void]` rather than `D extends void`: a bare conditional distributes over unions,
+// so a `boolean` detail would become `((detail: true) => …) | ((detail: false) => …)`.
+type EventProps<E> = { [K in keyof E]?: E[K] extends EventSpec<infer D> ? ([D] extends [void] ? () => unknown : (detail: D) => unknown) : never };
+
+type SlotNames<S> = S extends readonly (infer N extends string)[] ? N : never;
+
+// A slot may share its name with a data prop (`PropertyListItem.value` is a string or slotted
+// content). Such a key accepts either, instead of intersecting the two down to the data type.
+type SlotProps<P, S, Node> = {
+  [K in SlotNames<S>]?: Node | (K extends keyof P ? ValueOf<P[K]> : never);
+};
+
+/**
+ * Props an app passes to a component. `Node` is the app's element type (React's `ReactNode` in
+ * the SDK). `children` is always accepted here; which children a tag may hold is enforced at
+ * runtime by the host from `children` / `text` in the catalog.
+ */
+export type ComponentProps<Name extends ComponentName, Node = unknown> =
+  Omit<DataProps<(typeof COMPONENTS)[Name]["props"]>, SlotNames<(typeof COMPONENTS)[Name]["slots"]>> &
+  EventProps<(typeof COMPONENTS)[Name]["events"]> &
+  SlotProps<(typeof COMPONENTS)[Name]["props"], (typeof COMPONENTS)[Name]["slots"], Node> &
+  { children?: Node };
+
+// ---------------------------------------------------------------------------------------------
+// Runtime helpers for the host
+
+const COMPONENTS_BY_TAG: ReadonlyMap<string, ComponentSpec> = new Map(
+  Object.values(COMPONENTS as Record<string, ComponentSpec>).map((c) => [c.tagName, c]),
+);
+
+export function getComponentByTag(tagName: string): ComponentSpec | undefined {
+  return COMPONENTS_BY_TAG.get(tagName);
+}
+
+export function isValidHref(value: unknown): value is RouteDescriptor | string {
+  return isRouteDescriptor(value) || isHttpsUrl(value);
+}
+
+/**
+ * Largest `data:image/` URL an app may pass, in characters (~64 KB decoded). This bounds the work of
+ * reading it, not the memory of drawing it: a small compressed image can declare huge dimensions,
+ * so {@link isValidImageSrc} also checks the dimensions in its header.
+ */
+export const DATA_IMAGE_MAX_CHARS = 90_000;
+
+/** Largest width or height of a `data:` image, in pixels. */
+export const DATA_IMAGE_MAX_EDGE = 2048;
+
+/** Largest area of a `data:` image, in pixels: 4 MB once decoded to RGBA. */
+export const DATA_IMAGE_MAX_PIXELS = 1024 * 1024;
+
+// GIF is left out: every frame carries its own size, independent of the header's, so the header
+// alone does not bound what a decoder allocates.
+const DATA_IMAGE_RE = /^data:image\/(png|jpeg|webp);base64,([A-Za-z0-9+/]+={0,2})$/;
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+/** Decodes base64 without `atob`, which older JS engines lack. Returns null for invalid input. */
+function decodeBase64(data: string): Uint8Array | null {
+  if (data.length % 4 !== 0) return null;
+  const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+  const bytes = new Uint8Array((data.length / 4) * 3 - padding);
+  let out = 0;
+  for (let i = 0; i < data.length; i += 4) {
+    let chunk = 0;
+    for (let j = 0; j < 4; j++) {
+      const c = data.charAt(i + j);
+      const v = c === "=" ? 0 : BASE64_ALPHABET.indexOf(c);
+      if (v < 0) return null;
+      chunk = (chunk << 6) | v;
+    }
+    for (const shift of [16, 8, 0]) {
+      if (out < bytes.length) bytes[out++] = (chunk >> shift) & 0xff;
+    }
+  }
+  return bytes;
+}
+
+interface Dimensions { width: number; height: number }
+
+const u16be = (b: Uint8Array, i: number): number => ((b[i] ?? 0) << 8) | (b[i + 1] ?? 0);
+const u16le = (b: Uint8Array, i: number): number => (b[i] ?? 0) | ((b[i + 1] ?? 0) << 8);
+const u24le = (b: Uint8Array, i: number): number => u16le(b, i) | ((b[i + 2] ?? 0) << 16);
+const u32be = (b: Uint8Array, i: number): number => u16be(b, i) * 0x10000 + u16be(b, i + 2);
+const ascii = (b: Uint8Array, i: number, n: number): string => String.fromCharCode(...b.subarray(i, i + n));
+
+/**
+ * The dimensions an image's header declares, which is what a decoder allocates for. Null when the
+ * bytes are not a well-formed header of the declared type.
+ */
+function imageDimensions(type: string, b: Uint8Array): Dimensions | null {
+  switch (type) {
+    case "png":
+      if (b.length < 24 || u32be(b, 0) !== 0x89504e47 || u32be(b, 4) !== 0x0d0a1a0a || ascii(b, 12, 4) !== "IHDR") return null;
+      return { width: u32be(b, 16), height: u32be(b, 20) };
+    case "webp": {
+      if (b.length < 30 || ascii(b, 0, 4) !== "RIFF" || ascii(b, 8, 4) !== "WEBP") return null;
+      const chunk = ascii(b, 12, 4);
+      if (chunk === "VP8 ") return { width: u16le(b, 26) & 0x3fff, height: u16le(b, 28) & 0x3fff };
+      if (chunk === "VP8L") {
+        const bits = (b[21] ?? 0) | ((b[22] ?? 0) << 8) | ((b[23] ?? 0) << 16) | ((b[24] ?? 0) << 24);
+        return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
+      }
+      if (chunk === "VP8X") return { width: u24le(b, 24) + 1, height: u24le(b, 27) + 1 };
+      return null;
+    }
+    case "jpeg": {
+      if (u16be(b, 0) !== 0xffd8) return null;
+      let i = 2;
+      while (i + 9 <= b.length) {
+        if (b[i] !== 0xff) return null;
+        const marker = b[i + 1] ?? 0;
+        // Fill bytes before a marker.
+        if (marker === 0xff) { i++; continue; }
+        const length = u16be(b, i + 2);
+        // SOF0–SOF15 carry the frame size; C4 (DHT), C8 (JPG) and CC (DAC) share the range but do not.
+        if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+          return { height: u16be(b, i + 5), width: u16be(b, i + 7) };
+        }
+        if (length < 2) return null;
+        i += 2 + length;
+      }
+      return null;
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * An https URL, or a base64 `data:` PNG, JPEG or WebP no longer than
+ * {@link DATA_IMAGE_MAX_CHARS} whose header declares a non-empty size within
+ * {@link DATA_IMAGE_MAX_EDGE} and {@link DATA_IMAGE_MAX_PIXELS}. The host additionally requires an
+ * https URL to match the manifest's `image_src`.
+ */
+export function isValidImageSrc(value: unknown): value is string {
+  if (isHttpsUrl(value)) return true;
+  if (typeof value !== "string" || value.length > DATA_IMAGE_MAX_CHARS) return false;
+
+  const match = DATA_IMAGE_RE.exec(value);
+  const bytes = match?.[2] === undefined ? null : decodeBase64(match[2]);
+  const size = match?.[1] === undefined || bytes === null ? null : imageDimensions(match[1], bytes);
+  return size !== null && size.width > 0 && size.height > 0 &&
+    size.width <= DATA_IMAGE_MAX_EDGE && size.height <= DATA_IMAGE_MAX_EDGE &&
+    size.width * size.height <= DATA_IMAGE_MAX_PIXELS;
+}
+
+/** An ISO 8601 calendar date, `YYYY-MM-DD`, naming a day that exists (leap years included). */
+export function isCalendarDate(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (match === null) return false;
+  const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  const date = new Date(Date.UTC(year, month - 1, day));
+  // `Date.UTC` maps years 0-99 to 1900-1999, so set the full year explicitly.
+  date.setUTCFullYear(year);
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+
+function propIsValid(spec: PropSpec, value: unknown): boolean {
+  switch (spec.type) {
+    // A required string must also be non-blank: an empty `label` or `title` would leave a control
+    // or view without an accessible name while still satisfying "present".
+    case "string": return typeof value === "string" &&
+      (spec.maxLength === undefined || value.length <= spec.maxLength) &&
+      (!spec.required || value.trim().length > 0) &&
+      (spec.format !== "date" || isCalendarDate(value));
+    case "number": return typeof value === "number" && Number.isFinite(value) &&
+      (spec.integer !== true || Number.isInteger(value)) &&
+      (spec.min === undefined || value >= spec.min) && (spec.max === undefined || value <= spec.max);
+    case "boolean": return typeof value === "boolean";
+    case "enum": return typeof value === "string" && spec.values.includes(value);
+    case "href": return isValidHref(value);
+    case "imageSrc": return isValidImageSrc(value);
+    case "json": return spec.check(value);
+  }
+}
+
+export interface SanitizedProps {
+  props: Record<string, unknown>;
+  /** Names of props that were unknown or failed their type check. */
+  dropped: string[];
+  /** Required props that were missing or invalid; the host should not render the element. */
+  missing: string[];
+}
+
+/**
+ * Keeps only the props the catalog declares for a tag, each of the declared type. Event and slot
+ * props are not handled here: remote-dom delivers them separately (event listeners and slotted
+ * children). An unknown tag keeps nothing.
+ */
+export function sanitizeProps(tagName: string, raw: Readonly<Record<string, unknown>>): SanitizedProps {
+  const component = COMPONENTS_BY_TAG.get(tagName);
+  const result: SanitizedProps = { props: {}, dropped: [], missing: [] };
+  if (!component) {
+    result.dropped = Object.keys(raw);
+    return result;
+  }
+
+  for (const [name, value] of Object.entries(raw)) {
+    const propSpec = component.props[name];
+    if (propSpec && value !== undefined && propIsValid(propSpec, value)) result.props[name] = value;
+    else if (value !== undefined) result.dropped.push(name);
+  }
+
+  for (const [name, propSpec] of Object.entries(component.props)) {
+    if (propSpec.required && !(name in result.props)) result.missing.push(name);
+  }
+
+  return result;
+}
+
+/** A JSON-safe description of the catalog, for docs and the CLI. */
+export function componentsCatalogJson(): Array<{
+  name: string; tagName: string; root: boolean; text: boolean; children: readonly string[] | null; slots: readonly string[];
+  props: Record<string, {
+    type: string; required: boolean; values?: readonly string[]; maxLength?: number; minLength?: number; format?: "date";
+    integer?: boolean; minimum?: number; maximum?: number;
+  }>;
+  events: Record<string, string>;
+}> {
+  return Object.entries(COMPONENTS as Record<string, ComponentSpec>).map(([name, c]) => ({
+    name,
+    tagName: c.tagName,
+    root: c.root === true,
+    text: c.text,
+    children: c.children,
+    slots: c.slots,
+    props: Object.fromEntries(Object.entries(c.props).map(([k, s]) => [k, {
+      type: s.type,
+      required: s.required === true,
+      ...(s.type === "enum" ? { values: s.values } : {}),
+      ...(s.type === "string" && s.maxLength !== undefined ? { maxLength: s.maxLength } : {}),
+      ...(s.type === "string" && s.required === true ? { minLength: 1 } : {}),
+      ...(s.type === "string" && s.format !== undefined ? { format: s.format } : {}),
+      ...(s.type === "number" && s.integer === true ? { integer: true } : {}),
+      ...(s.type === "number" && s.min !== undefined ? { minimum: s.min } : {}),
+      ...(s.type === "number" && s.max !== undefined ? { maximum: s.max } : {}),
+    }])),
+    events: Object.fromEntries(Object.entries(c.events).map(([k, e]) => [k, e.event])),
+  }));
+}