@appinternalleads/ui 0.2.0 → 0.4.0

package/src/agent/spec.ts

@@ -0,0 +1,229 @@
+import type { CopySpec, FieldSpec, Owner, RenderIssue, Section } from './types';
+
+/**
+ * **Field specs, and the one checker that reads them.** A manifest declares each setting with these
+ * builders; `checkSection` holds a request's section to them — unknown keys, kinds, required,
+ * ranges, formats, enums, uniqueness — and `checkRefs` to the values they must name.
+ */
+
+type Opts<T> = Omit<Extract<FieldSpec, { type: T }>, 'type' | 'description'>;
+export const text = (description: string, o: Opts<'text'> = {}): FieldSpec => ({ type: 'text', description, ...o });
+export const num = (description: string, o: Opts<'number'> = {}): FieldSpec => ({ type: 'number', description, ...o });
+export const bool = (description: string, o: Opts<'boolean'> = {}): FieldSpec => ({ type: 'boolean', description, ...o });
+export const list = (description: string, item: FieldSpec, o: Omit<Opts<'list'>, 'item'> = {}): FieldSpec => ({ type: 'list', description, item, ...o });
+export const obj = (description: string, fields: Record<string, FieldSpec>, o: Omit<Opts<'object'>, 'fields'> = {}): FieldSpec => ({ type: 'object', description, fields, ...o });
+export const map = (description: string, value: FieldSpec, o: Omit<Opts<'map'>, 'value'> = {}): FieldSpec => ({ type: 'map', description, value, ...o });
+export const json = (description: string, o: Opts<'json'> = {}): FieldSpec => ({ type: 'json', description, ...o });
+
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+/** A real calendar date: `2026-02-30` is not one. */
+export function isRealDate(s: string): boolean {
+  const m = ISO_DATE.exec(s);
+  if (!m) return false;
+  const d = new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])));
+  return d.getUTCFullYear() === Number(m[1]) && d.getUTCMonth() === Number(m[2]) - 1 && d.getUTCDate() === Number(m[3]);
+}
+
+const kindOf = (v: unknown) => (v === null ? 'null' : Array.isArray(v) ? 'list' : typeof v === 'object' ? 'object' : typeof v);
+const WANT: Record<FieldSpec['type'], string> = { text: 'text', number: 'a number', boolean: 'true or false', list: 'a list', object: 'an object', map: 'an object', json: 'any JSON value' };
+
+type Ctx = { section: Section; issues: RenderIssue[] };
+const push = (c: Ctx, path: string, code: RenderIssue['code'], layer: RenderIssue['layer'], message: string, expected?: RenderIssue['expected']) =>
+  c.issues.push({ path, code, layer, section: c.section, message, ...(expected !== undefined ? { expected } : {}) });
+
+/** One value against its spec. `path` is the request path. */
+export function checkValue(spec: FieldSpec, v: unknown, path: string, c: Ctx): void {
+  if (v === undefined) return;
+  if (v === null) { if (!spec.nullable) push(c, path, 'TYPE', 'shape', `${path} must be ${WANT[spec.type]}, not null.`, WANT[spec.type]); return; }
+  switch (spec.type) {
+    case 'json': return;
+    case 'text': {
+      if (typeof v !== 'string') { push(c, path, 'TYPE', 'shape', `${path} must be text (got ${kindOf(v)}).`, 'text'); return; }
+      const layer = c.section === 'data' ? 'data' : 'configuration';
+      if (spec.required && !v.trim()) push(c, path, 'REQUIRED', layer, `${path} must not be empty.`);
+      if (spec.minLength !== undefined && v.trim().length < spec.minLength) push(c, path, 'MIN_LENGTH', layer, `${path} needs at least ${spec.minLength} characters.`);
+      if (spec.maxLength !== undefined && v.trim().length > spec.maxLength) push(c, path, 'MAX_LENGTH', layer, `${path} is ${v.trim().length} characters; at most ${spec.maxLength} fit.`, `≤ ${spec.maxLength} characters`);
+      if (spec.format === 'date' && v && !isRealDate(v)) push(c, path, 'FORMAT', layer, `${path} must be a real date, YYYY-MM-DD (got "${v}").`, 'YYYY-MM-DD');
+      if (spec.pattern && v && !new RegExp(spec.pattern).test(v)) push(c, path, 'PATTERN', layer, `${path} ${spec.patternHint ?? `must match ${spec.pattern}`} (got "${v}").`, spec.pattern);
+      if (spec.enum && !spec.enum.includes(v)) push(c, path, 'ENUM', layer, `${path} must be one of the allowed values (got "${v}").`, [...spec.enum]);
+      return;
+    }
+    case 'number': {
+      if (typeof v !== 'number' || !Number.isFinite(v)) { push(c, path, 'TYPE', 'shape', `${path} must be a finite number (got ${kindOf(v)}).`, 'number'); return; }
+      const layer = c.section === 'data' ? 'data' : 'configuration';
+      if (spec.integer && !Number.isInteger(v)) push(c, path, 'INTEGER', layer, `${path} must be a whole number (got ${v}).`);
+      if (spec.min !== undefined && v < spec.min) push(c, path, 'MIN', layer, `${path} must be at least ${spec.min} (got ${v}).`, `≥ ${spec.min}`);
+      if (spec.exclusiveMin !== undefined && v <= spec.exclusiveMin) push(c, path, 'MIN', layer, `${path} must be more than ${spec.exclusiveMin} (got ${v}).`, `> ${spec.exclusiveMin}`);
+      if (spec.max !== undefined && v > spec.max) push(c, path, 'MAX', layer, `${path} must be at most ${spec.max} (got ${v}).`, `≤ ${spec.max}`);
+      return;
+    }
+    case 'boolean':
+      if (typeof v !== 'boolean') push(c, path, 'TYPE', 'shape', `${path} must be true or false (got ${kindOf(v)}).`, 'boolean');
+      return;
+    case 'list': {
+      if (!Array.isArray(v)) { push(c, path, 'TYPE', 'shape', `${path} must be a list (got ${kindOf(v)}).`, 'list'); return; }
+      const layer = c.section === 'data' ? 'data' : 'configuration';
+      if (spec.minItems !== undefined && v.length < spec.minItems) push(c, path, 'MIN_ITEMS', layer, `${path} needs at least ${spec.minItems} (has ${v.length}).`, `≥ ${spec.minItems} items`);
+      if (spec.maxItems !== undefined && v.length > spec.maxItems) push(c, path, 'MAX_ITEMS', layer, `${path} holds at most ${spec.maxItems} (has ${v.length}).`, `≤ ${spec.maxItems} items`);
+      v.forEach((x, i) => checkValue(spec.item, x, `${path}[${i}]`, c));
+      /* A unique field inside the items: ids, keys. */
+      if (spec.item.type === 'object') {
+        for (const [k, f] of Object.entries(spec.item.fields)) {
+          if (f.type !== 'text' || !f.unique) continue;
+          const seen = new Set<string>();
+          v.forEach((x, i) => {
+            const val = (x as Record<string, unknown> | null)?.[k];
+            if (typeof val !== 'string') return;
+            if (seen.has(val)) push(c, `${path}[${i}].${k}`, 'DUPLICATE', layer, `${path}[${i}].${k} "${val}" is used twice.`);
+            seen.add(val);
+          });
+        }
+      }
+      return;
+    }
+    case 'object': {
+      if (kindOf(v) !== 'object') { push(c, path, 'TYPE', 'shape', `${path} must be an object (got ${kindOf(v)}).`, 'object'); return; }
+      checkFields(spec.fields, v as Record<string, unknown>, path, c);
+      return;
+    }
+    case 'map': {
+      if (kindOf(v) !== 'object') { push(c, path, 'TYPE', 'shape', `${path} must be an object (got ${kindOf(v)}).`, 'object'); return; }
+      for (const [k, x] of Object.entries(v as Record<string, unknown>)) checkValue(spec.value, x, `${path}.${k}`, c);
+      return;
+    }
+  }
+}
+
+/** An object's keys: unknown ones are errors, required ones must be present. */
+export function checkFields(fields: Record<string, FieldSpec>, v: Record<string, unknown>, path: string, c: Ctx): void {
+  const expected = Object.keys(fields);
+  for (const k of Object.keys(v)) {
+    if (!(k in fields)) push(c, `${path}.${k}`, 'UNKNOWN_KEY', 'schema', `${path} has no "${k}". It takes: ${expected.join(', ') || 'nothing'}.`, expected);
+  }
+  for (const [k, f] of Object.entries(fields)) {
+    if (f.required && v[k] === undefined) push(c, `${path}.${k}`, 'REQUIRED', c.section === 'data' ? 'data' : 'configuration', `${path}.${k} is required: ${f.description}`);
+    else checkValue(f, v[k], `${path}.${k}`, c);
+  }
+}
+
+/** A section's settings the agent may not send (`owners` without `agent`). */
+export function checkOwners(fields: Record<string, FieldSpec>, v: Record<string, unknown>, path: string, c: Ctx): void {
+  for (const [k, f] of Object.entries(fields)) {
+    if (v[k] !== undefined && f.owners && !f.owners.includes('agent')) {
+      push(c, `${path}.${k}`, 'NOT_ALLOWED', 'configuration', `${path}.${k} is set by the ${f.owners.join(' or ')}, not by an agent.`, f.owners);
+    }
+  }
+}
+
+/* ── References: `data.items[].id` ─────────────────────────────────────────────────────────── */
+
+/** Every value at a reference path, in a resolved request: `data.items[].id` → the ids. */
+export function valuesAt(root: Record<string, unknown>, ref: string): unknown[] {
+  let cur: unknown[] = [root];
+  for (const part of ref.split('.')) {
+    const many = part.endsWith('[]');
+    const key = many ? part.slice(0, -2) : part;
+    cur = cur.flatMap(x => {
+      const v = x && typeof x === 'object' ? (x as Record<string, unknown>)[key] : undefined;
+      return many ? (Array.isArray(v) ? v : []) : v === undefined ? [] : [v];
+    });
+  }
+  return cur;
+}
+
+/** Every `ref` in `fields` (recursively), checked against `root`. */
+export function checkRefs(fields: Record<string, FieldSpec>, v: Record<string, unknown>, path: string, root: Record<string, unknown>, c: Ctx): void {
+  for (const [k, f] of Object.entries(fields)) visitRef(f, v?.[k], `${path}.${k}`, root, c);
+}
+function visitRef(f: FieldSpec, v: unknown, path: string, root: Record<string, unknown>, c: Ctx) {
+  if (v === undefined || v === null) return;
+  if (f.ref && (typeof v === 'string' || typeof v === 'number')) {
+    const allowed = valuesAt(root, f.ref).filter(x => typeof x === 'string' || typeof x === 'number') as (string | number)[];
+    if (!allowed.includes(v)) {
+      push(c, path, 'REFERENCE', c.section === 'data' ? 'data' : 'configuration', `${path} must name one of ${f.ref} (got "${v}").`, allowed.map(String));
+    }
+  }
+  if (f.type === 'list' && Array.isArray(v)) v.forEach((x, i) => visitRef(f.item, x, `${path}[${i}]`, root, c));
+  if (f.type === 'object' && v && typeof v === 'object') for (const [k, g] of Object.entries(f.fields)) visitRef(g, (v as Record<string, unknown>)[k], `${path}.${k}`, root, c);
+}
+
+/** Fill in each field's `default` where the value is missing — never for required ones. */
+export function withDefaults(fields: Record<string, FieldSpec>, v: Record<string, unknown> = {}): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...v };
+  for (const [k, f] of Object.entries(fields)) if (out[k] === undefined && f.default !== undefined) out[k] = structuredClone(f.default);
+  return out;
+}
+
+/* ── Copy ─────────────────────────────────────────────────────────────────────────────────── */
+
+const PLACEHOLDER = /\{(\w+)\}/g;
+export const placeholdersOf = (s: string) => [...new Set([...s.matchAll(PLACEHOLDER)].map(m => m[1]!))];
+
+/**
+ * A copy spec from a default and every case study's value: the placeholders the default uses are
+ * required; any a case uses are allowed too.
+ */
+export function copySpecFrom(key: string, base: unknown, variants: unknown[], extra: Partial<CopySpec> = {}): CopySpec {
+  const owners: Owner[] = ['agent', 'builder', 'developer'];
+  if (typeof base === 'string') {
+    const all = [base, ...variants.filter((x): x is string => typeof x === 'string')];
+    const required = placeholdersOf(base);
+    const allowed = [...new Set(all.flatMap(placeholdersOf))];
+    return { type: 'text', description: `Words: ${key}.`, default: base, ...(allowed.length ? { placeholders: { required, allowed } } : {}), owners, ...extra };
+  }
+  if (Array.isArray(base)) return { type: 'text-list', description: `Words: ${key}, one per entry.`, default: base as string[], length: base.length, owners, ...extra };
+  const entries = base as Record<string, string>;
+  const entryPlaceholders: Record<string, { required: string[]; allowed: string[] }> = {};
+  for (const [k, s] of Object.entries(entries)) {
+    const vs = variants.map(x => (x && typeof x === 'object' ? (x as Record<string, unknown>)[k] : undefined)).filter((x): x is string => typeof x === 'string');
+    const allowed = [...new Set([s, ...vs].flatMap(placeholdersOf))];
+    if (allowed.length) entryPlaceholders[k] = { required: placeholdersOf(s), allowed };
+  }
+  return { type: 'text-map', description: `Words: ${key}, by entry.`, default: entries, partial: true, ...(Object.keys(entryPlaceholders).length ? { entryPlaceholders } : {}), owners, ...extra };
+}
+
+function checkTemplate(s: string, p: { required: string[]; allowed: string[] } | undefined, path: string, c: Ctx) {
+  if (!p) {
+    const extra = placeholdersOf(s);
+    if (extra.length) push(c, path, 'PLACEHOLDER_UNKNOWN', 'copy', `${path} has {${extra.join('}, {')}}, which nothing fills — it would show as written.`, []);
+    return;
+  }
+  const have = placeholdersOf(s);
+  const missing = p.required.filter(x => !have.includes(x));
+  const unknown = have.filter(x => !p.allowed.includes(x));
+  if (missing.length) push(c, path, 'PLACEHOLDER_MISSING', 'copy', `${path} must keep {${missing.join('}, {')}} — the component fills it in.`, p.required.map(x => `{${x}}`));
+  if (unknown.length) push(c, path, 'PLACEHOLDER_UNKNOWN', 'copy', `${path} has {${unknown.join('}, {')}}, which nothing fills — use ${p.allowed.map(x => `{${x}}`).join(', ')}.`, p.allowed.map(x => `{${x}}`));
+}
+
+/** A request's `copy` against the capability's copy specs. */
+export function checkCopy(specs: Record<string, CopySpec>, copy: Record<string, unknown>, c: Ctx): void {
+  const expected = Object.keys(specs);
+  for (const [k, s] of Object.entries(specs)) {
+    if (s.required && copy[k] === undefined) push(c, `copy.${k}`, 'REQUIRED', 'copy', `copy.${k} is required: ${s.description}`);
+  }
+  for (const [k, v] of Object.entries(copy)) {
+    const s = specs[k];
+    const path = `copy.${k}`;
+    if (!s) { push(c, path, 'UNKNOWN_KEY', 'schema', `copy has no "${k}". It takes: ${expected.join(', ')}.`, expected); continue; }
+    if (s.type === 'text') {
+      if (typeof v !== 'string') { push(c, path, 'TYPE', 'shape', `${path} must be text (got ${kindOf(v)}).`, 'text'); continue; }
+      if (!v.trim()) push(c, path, 'REQUIRED', 'copy', `${path} must not be empty — leave it out to keep "${s.default}".`);
+      if (s.maxLength !== undefined && v.length > s.maxLength) push(c, path, 'MAX_LENGTH', 'copy', `${path} is ${v.length} characters; at most ${s.maxLength} fit.`, `≤ ${s.maxLength} characters`);
+      checkTemplate(v, s.placeholders, path, c);
+    } else if (s.type === 'text-list') {
+      if (!Array.isArray(v) || !v.every(x => typeof x === 'string')) { push(c, path, 'TYPE', 'shape', `${path} must be a list of text.`, 'list of text'); continue; }
+      if (s.length !== undefined && v.length !== s.length) push(c, path, 'LENGTH', 'copy', `${path} must have exactly ${s.length} entries (has ${v.length}).`, `${s.length} entries`);
+      v.forEach((x, i) => { if (!x.trim()) push(c, `${path}[${i}]`, 'REQUIRED', 'copy', `${path}[${i}] must not be empty.`); });
+    } else {
+      if (kindOf(v) !== 'object') { push(c, path, 'TYPE', 'shape', `${path} must be an object of text (got ${kindOf(v)}).`, 'object'); continue; }
+      const keys = Object.keys(s.default as Record<string, string>);
+      for (const [ek, ev] of Object.entries(v as Record<string, unknown>)) {
+        const ep = `${path}.${ek}`;
+        if (!keys.includes(ek) && !s.open) { push(c, ep, 'UNKNOWN_KEY', 'schema', `${path} has no "${ek}".`, keys); continue; }
+        if (typeof ev !== 'string') { push(c, ep, 'TYPE', 'shape', `${ep} must be text.`, 'text'); continue; }
+        if (!ev.trim()) push(c, ep, 'REQUIRED', 'copy', `${ep} must not be empty.`);
+        if (keys.includes(ek)) checkTemplate(ev, s.entryPlaceholders?.[ek], ep, c);
+      }
+    }
+  }
+}

package/src/agent/types.ts

@@ -0,0 +1,191 @@
+/**
+ * **The agent component contract — its types.** Pure: no React, no component code.
+ *
+ * An agent reasons about a *capability* (`AgentCapability`), sends a *render request* (`render/1`),
+ * and gets back *results* (`result/1`). None of the three names a React component, a prop, a hook,
+ * a file or an animation: the package maps them onto its components (`resolveRenderRequest`,
+ * `AgentComponent`), and that mapping may change without the contract changing.
+ * See `docs/AGENT-COMPONENT-CONTRACT.md`.
+ */
+
+export const RENDER_SCHEMA = 'render/1' as const;
+export const RESULT_SCHEMA = 'result/1' as const;
+export const CAPABILITY_SCHEMA = 'capability/1' as const;
+
+/**
+ * What the host should expect once it renders the component.
+ * - `output` — shows what it is given; the person may look around (open a row, switch a tab) but produces nothing.
+ * - `interactive-output` — shows what it is given and the person acts on it (a vote, Copy, a period); results are events.
+ * - `input-output` — a form whose submission produces the output (Receipt Printer: fill in, Print, receipt).
+ * - `interactive` — the person does work in it (allocate, tick, edit stages); results are the changed data.
+ */
+export type CapabilityKind = 'output' | 'interactive-output' | 'input-output' | 'interactive';
+
+/** The four sections of a render request, and who may write each setting. */
+export type Section = 'data' | 'copy' | 'behavior' | 'presentation';
+export type Owner = 'agent' | 'builder' | 'developer' | 'system' | 'runtime-user';
+
+/** Where a data value must come from. `invent` — the agent may write it; `user` — ask the person; `external` — a real source (a tool, a sheet, an API), never made up; `derived` — computed from other values. */
+export type DataOrigin = 'user' | 'external' | 'invent' | 'derived';
+
+type Base = {
+  description: string;
+  /** Required in the request. A missing required value is an error — nothing is filled in from demo data. */
+  required?: boolean;
+  /** `null` is accepted and means "none". */
+  nullable?: boolean;
+  /** The value used when the request leaves this out (behaviour, presentation, optional data). Never demo content. */
+  default?: unknown;
+  /** Who may set it. The agent may send a setting only if this includes `agent`. */
+  owners?: Owner[];
+  /** Data only: where the value must come from. */
+  origin?: DataOrigin;
+  /** Must equal a value found elsewhere in the request: `data.items[].id`, `behavior.currencies[].code`. */
+  ref?: string;
+};
+
+export type FieldSpec =
+  | Base & { type: 'text'; maxLength?: number; minLength?: number; pattern?: string; patternHint?: string; format?: 'date'; enum?: readonly string[]; unique?: boolean }
+  | Base & { type: 'number'; integer?: boolean; min?: number; max?: number; exclusiveMin?: number }
+  | Base & { type: 'boolean' }
+  | Base & { type: 'list'; item: FieldSpec; minItems?: number; maxItems?: number }
+  | Base & { type: 'object'; fields: Record<string, FieldSpec> }
+  | Base & { type: 'map'; value: FieldSpec }
+  | Base & { type: 'json' };
+
+/**
+ * One piece of copy. `placeholders` are the `{names}` the component fills in: `required` ones must
+ * stay (removing `{count}` from "{count} free" loses the number), and none outside `allowed` may be
+ * added (it would show as literal braces).
+ */
+export type CopySpec = {
+  type: 'text' | 'text-list' | 'text-map';
+  description: string;
+  default: string | string[] | Record<string, string>;
+  placeholders?: { required: string[]; allowed: string[] };
+  /** For `text-map`: the placeholders of each entry, by key. */
+  entryPlaceholders?: Record<string, { required: string[]; allowed: string[] }>;
+  maxLength?: number;
+  /** Must be sent — there is no default worth showing (a flow's title). */
+  required?: boolean;
+  /** `text-list`: exactly this many. */
+  length?: number;
+  /** `text-map`: send only the entries you change — the rest keep their defaults. */
+  partial?: boolean;
+  /** `text-map`: keys are not a fixed set (names for the data's own keys, say). */
+  open?: boolean;
+  owners: Owner[];
+};
+
+/** Something the person can do, and what the host hears when they do. */
+export type CapabilityAction = { id: string; description: string; hostOperation?: boolean };
+/** A `result/1` event the component emits, and what its `data` holds. */
+export type CapabilityEvent = { event: string; description: string; data: string };
+
+/** The semantic card — what `search_components` returns. Small on purpose. */
+export type CapabilityCard = {
+  component: string;
+  name: string;
+  kind: CapabilityKind;
+  purpose: string;
+  signals: string[];
+};
+
+/**
+ * **One component, as an agent sees it.** Serialisable — everything here is data. `describeComponent`
+ * returns it; the builder's panel and the HTTP API read the same object.
+ */
+export type AgentCapability = CapabilityCard & {
+  schema: typeof CAPABILITY_SCHEMA;
+  agentEditable: true;
+  useWhen: string[];
+  avoidWhen: string[];
+  /** Components an agent might confuse this with, and how to tell them apart. */
+  related: { component: string; distinction: string }[];
+  states: { state: string; description: string }[];
+  actions: CapabilityAction[];
+  events: CapabilityEvent[];
+  /** What the person has to do before there is a result: nothing, look, fill in a form, or work in it. */
+  requiresInput: boolean;
+  /** Case studies whose copy (and presentation) a request may start from: `preset`. Their data is never used. */
+  presets: { preset: string; title: string; scenario: string }[];
+  data: Record<string, FieldSpec>;
+  copy: Record<string, CopySpec>;
+  behavior: Record<string, FieldSpec>;
+  presentation: Record<string, FieldSpec>;
+  /** Button ids a request's `actions` may name. */
+  actionButtons: string[];
+  /** Plain-words rules that span fields — the ones a schema cannot say. */
+  rules: string[];
+  /** Questions to ask the person when required data is missing, by data key. */
+  askFor: Record<string, string>;
+};
+
+/** Actions an agent may attach to a button: no URLs — a webhook or a link is the host's to configure. */
+export type AgentButtonAction = { type: 'post-message' } | { type: 'succeed' } | { type: 'fail'; message?: string };
+
+/** **`render/1`** — what an agent sends. Serialisable, versioned, and validated by `validateRenderRequest`. */
+export type RenderRequest = {
+  schema: typeof RENDER_SCHEMA;
+  component: string;
+  /** Start the copy and presentation from a case study (a translated one, say). Its data is never used. */
+  preset?: string;
+  /** The runtime data. Every required key must be here — nothing falls back to demo content. */
+  data: Record<string, unknown>;
+  copy?: Record<string, unknown>;
+  behavior?: Record<string, unknown>;
+  presentation?: Record<string, unknown>;
+  actions?: Record<string, AgentButtonAction>;
+};
+
+export type IssueLayer =
+  /** The request envelope: `schema`, `component`, unknown sections, unknown keys. */
+  | 'schema'
+  /** A value of the wrong kind. */
+  | 'shape'
+  /** Runtime data breaks a rule: required, range, format, enum, reference. */
+  | 'data'
+  /** Copy breaks a rule: placeholders, length, list length. */
+  | 'copy'
+  /** A setting the agent may not set, a bad action. */
+  | 'configuration'
+  /** The component's own validator refused the resolved component. */
+  | 'semantic'
+  /** The component would render, but its submit would be refused (Receipt Printer's Print). */
+  | 'interaction';
+
+export type IssueCode =
+  | 'UNKNOWN_KEY' | 'UNKNOWN_COMPONENT' | 'UNKNOWN_PRESET' | 'BAD_SCHEMA' | 'TYPE' | 'REQUIRED' | 'MIN' | 'MAX'
+  | 'MIN_LENGTH' | 'MAX_LENGTH' | 'MIN_ITEMS' | 'MAX_ITEMS' | 'LENGTH' | 'ENUM' | 'FORMAT' | 'PATTERN' | 'INTEGER'
+  | 'REFERENCE' | 'DUPLICATE' | 'PLACEHOLDER_MISSING' | 'PLACEHOLDER_UNKNOWN' | 'NOT_ALLOWED' | 'INVALID_ACTION'
+  | 'SEMANTIC' | 'INTERACTION';
+
+export type RenderIssue = {
+  /** Where, in the request: `data.items[0].amount`, `copy.totalLabel`. */
+  path: string;
+  code: IssueCode;
+  layer: IssueLayer;
+  /** Which section of the request to fix. */
+  section: Section | 'actions' | 'request';
+  message: string;
+  /** What would have been accepted — keys, choices, a range. */
+  expected?: string | string[];
+};
+
+/** What the person would see, in words: headings, labels, the data, the printed lines. */
+export type RenderPreview = { component: string; visibleText: string[] };
+
+export type RenderCheck =
+  | { valid: true; issues: []; request: RenderRequest; preview: RenderPreview }
+  | { valid: false; issues: RenderIssue[] };
+
+/** **`result/1`** — what the component reports back, as data. */
+export type RenderResult = {
+  schema: typeof RESULT_SCHEMA;
+  component: string;
+  instanceId: string;
+  /** Counts up per instance, so a host can order and de-duplicate. */
+  sequence: number;
+  event: string;
+  data: Record<string, unknown>;
+};