@appinternalleads/ui 0.2.0 → 0.4.0

package/spec/families/threshold-flow.schema.json

@@ -88,6 +88,7 @@
         },
         "copy": {
           "type": "object",
+          "description": "Every word the flow shows that is not a stage's own. All optional; a blank or absent key uses THRESHOLD_FLOW_COPY. Placeholders: {one} {other} {count} {title} {max} {previous} {value}.",
           "additionalProperties": false,
           "properties": {
             "action": { "type": "string" },
@@ -97,10 +98,25 @@
             "checking": { "type": "string" },
             "unit": { "type": "string" },
             "edit": { "type": "string" },
+            "add": { "type": "string" },
             "emptyTitle": { "type": "string" },
             "emptyBody": { "type": "string" },
             "emptyCta": { "type": "string" },
-            "errorTitle": { "type": "string" }
+            "errorTitle": { "type": "string" },
+            "statusLive": { "type": "string" },
+            "statusAttention": { "type": "string" },
+            "countOne": { "type": "string" },
+            "countOther": { "type": "string" },
+            "fixOne": { "type": "string" },
+            "fixOther": { "type": "string" },
+            "listLabel": { "type": "string" },
+            "remove": { "type": "string" },
+            "errorEmpty": { "type": "string" },
+            "errorOverMax": { "type": "string" },
+            "errorNotMore": { "type": "string" },
+            "loading": { "type": "string" },
+            "refused": { "type": "string" },
+            "untitled": { "type": "string" }
           }
         }
       }

package/src/agent/AgentComponent.tsx

@@ -0,0 +1,87 @@
+import { useMemo, useRef, type ComponentType } from 'react';
+import { ONBOARDING_VIEWS } from '../components/onboarding/views';
+import { InvalidConfig } from '../components/onboarding/shared/InvalidConfig';
+import { DirectoryView } from '../components/directory/DirectoryView';
+import { ChecklistView } from '../components/checklist/ChecklistView';
+import { ThresholdFlowView } from '../components/threshold-flow/ThresholdFlowView';
+import { describeComponent, isAgentComponent } from './catalog';
+import { RESULT_EVENTS, makeResult } from './result';
+import type { RenderResult } from './types';
+import { resolveRenderRequest, validateRenderRequest } from './validate';
+
+/**
+ * **The host registry — a component id to what draws it.** The agent protocol only ever says
+ * `"receipt-printer"`; this is the one place that id meets a React component. A host renders
+ * `<AgentComponent request={…} />` and never looks the component up itself.
+ */
+const RENDERERS: Record<string, ComponentType<Record<string, unknown>>> = {
+  ...Object.fromEntries(['receipt-printer', 'budget-tracker', 'activity-heatmap', 'criteria-spider', 'expandable-feed', 'fallback', 'seat-allocation', 'carousel', 'completion']
+    .map(id => [id, ONBOARDING_VIEWS[id as keyof typeof ONBOARDING_VIEWS] as unknown as ComponentType<Record<string, unknown>>])),
+  directory: DirectoryView as unknown as ComponentType<Record<string, unknown>>,
+  checklist: ChecklistView as unknown as ComponentType<Record<string, unknown>>,
+  'threshold-flow': ThresholdFlowView as unknown as ComponentType<Record<string, unknown>>,
+};
+
+/** The component ids this renderer draws — every approved one. */
+export const AGENT_RENDERABLE: readonly string[] = Object.keys(RENDERERS);
+
+export type AgentComponentProps = {
+  /** A `render/1` request, as the agent sent it. It is validated here too; an invalid one is refused out loud, never drawn half-right. */
+  request: unknown;
+  /** The host's name for this instance — every `result/1` carries it. */
+  instanceId: string;
+  /** Every result, as `result/1` data. */
+  onResult?: (result: RenderResult) => void;
+  /**
+   * What only the host decides, passed straight to the component: `operations` (print, save,
+   * loadDay, vote — the real work), `actions` (webhooks, links), `status`, `reload`, `density`, a
+   * native `stage`, a Checklist's `people` and `capabilities`, a Directory's `adapter`. The agent
+   * never sets these.
+   */
+  host?: Record<string, unknown>;
+  testID?: string;
+};
+
+/** Render a `render/1` request with the real component, and report its callbacks as `result/1`. */
+export function AgentComponent({ request, instanceId, onResult, host, testID }: AgentComponentProps) {
+  const key = JSON.stringify(request);
+  const check = useMemo(() => validateRenderRequest(request), [key]);
+  const resolved = useMemo(() => (check.valid ? resolveRenderRequest(request) : undefined), [key, check.valid]);
+  const sequence = useRef(0);
+  const latest = useRef(onResult);
+  latest.current = onResult;
+  const hostRef = useRef(host);
+  hostRef.current = host;
+
+  if (!check.valid || !resolved) {
+    const id = typeof (request as { component?: unknown })?.component === 'string' ? (request as { component: string }).component : '';
+    const name = isAgentComponent(id) ? describeComponent(id)!.name : 'Component';
+    const issues = check.valid ? [{ path: 'request', message: 'could not be resolved.' }] : check.issues.map(i => ({ path: i.path, message: i.message }));
+    return <InvalidConfig title={name} issues={issues} testID={testID} />;
+  }
+
+  const component = resolved.component;
+  const View = RENDERERS[component]!;
+  const emit = (event: string, data: Record<string, unknown>) => {
+    sequence.current += 1;
+    latest.current?.(makeResult(component, instanceId, sequence.current, event, data));
+  };
+  /* Each mapped callback reports a result, then calls the host's own, if it passed one. */
+  const callbacks = Object.fromEntries(Object.entries(RESULT_EVENTS[component] ?? {}).map(([prop, [event, map]]) => [prop, (...args: unknown[]) => {
+    let data = (map as (...a: unknown[]) => Record<string, unknown>)(...args);
+    if (component === 'directory' && resolved.family === 'classic') {
+      const rec = (resolved.props.records as { id: string; data: Record<string, string> }[]).find(r => r.id === args[0]);
+      data = { ...data, record: rec?.data ?? null };
+    }
+    emit(event, data);
+    const own = hostRef.current?.[prop];
+    if (typeof own === 'function') (own as (...a: unknown[]) => unknown)(...args);
+  }]));
+
+  if (resolved.family === 'new') {
+    const hostActions = (host?.actions as Record<string, unknown> | undefined) ?? {};
+    const actions = resolved.actions || Object.keys(hostActions).length ? { ...resolved.actions, ...hostActions } : undefined;
+    return <View {...host} config={resolved.config} {...(resolved.initial ? { initial: resolved.initial } : {})} {...(actions ? { actions } : {})} {...callbacks} testID={testID} />;
+  }
+  return <View {...host} {...resolved.props} {...callbacks} testID={testID} />;
+}

package/src/agent/base.ts

@@ -0,0 +1,17 @@
+/**
+ * **The agent contract without search** — describe, `render/1` validation, `result/1`, the types.
+ * Small and React-free. Both entry points carry it: `@appinternalleads/ui/agent` (`./core`) adds
+ * `searchComponents`; the main entry adds `AgentComponent`. Search is not here on purpose — its
+ * word-vector table is 2.8 MB, and an app that renders components must not bundle it.
+ */
+export {
+  AGENT_COMPONENTS, agentAvailability, describeComponent, isAgentComponent, listAgentComponents,
+} from './catalog';
+export { validateRenderRequest } from './validate';
+export { RESULT_EVENTS, makeResult } from './result';
+export {
+  CAPABILITY_SCHEMA, RENDER_SCHEMA, RESULT_SCHEMA,
+  type AgentButtonAction, type AgentCapability, type CapabilityAction, type CapabilityCard, type CapabilityEvent, type CapabilityKind,
+  type CopySpec as AgentCopySpec, type DataOrigin, type FieldSpec as AgentFieldSpec, type IssueCode, type IssueLayer, type Owner as AgentOwner,
+  type RenderCheck, type RenderIssue, type RenderPreview, type RenderRequest, type RenderResult, type Section as AgentSection,
+} from './types';

package/src/agent/catalog.ts

@@ -0,0 +1,100 @@
+import { ONBOARDING_PRESETS } from '../components/onboarding/presets';
+import { ONBOARDING_BUTTONS } from '../components/onboarding/shared/actions-data';
+import { ONBOARDING_COMPONENTS, presetsOf, resolveConfig } from '../components/onboarding/shared/contract';
+import { CLASSIC_MANIFESTS, type ClassicManifest } from './classic';
+import { NEW_MANIFESTS, type NewManifest } from './manifests';
+import { copySpecFrom } from './spec';
+import { CAPABILITY_SCHEMA, type AgentCapability, type CapabilityCard, type CopySpec } from './types';
+
+/**
+ * **The approved agent catalogue.** Twelve components, each an `AgentCapability` built from its
+ * manifest. Nothing else is agent-editable: the other New components are listed by
+ * `agentAvailability` as unavailable, with the reason, so an agent never assumes they share this
+ * contract.
+ */
+
+export type Manifest = NewManifest | ClassicManifest;
+const MANIFESTS: readonly Manifest[] = [...NEW_MANIFESTS, ...CLASSIC_MANIFESTS];
+const BY_ID = new Map<string, Manifest>(MANIFESTS.map(m => [m.component, m]));
+
+/** The approved components' ids, in catalogue order. */
+export const AGENT_COMPONENTS: readonly string[] = MANIFESTS.map(m => m.component);
+export const isAgentComponent = (id: unknown): id is string => typeof id === 'string' && BY_ID.has(id);
+export const manifestOf = (id: string): Manifest | undefined => BY_ID.get(id);
+
+/** Config keys a New manifest sets from the request (after renames) or clears — everything that is not copy. */
+export function nonCopyKeys(m: NewManifest): Set<string> {
+  const renamed = (section: 'data' | 'behavior' | 'presentation') => Object.keys(m[section]).map(k => m.rename?.[section]?.[k] ?? k);
+  return new Set([...renamed('data'), ...renamed('behavior'), ...renamed('presentation'), ...m.system]);
+}
+
+/** A New component's copy: every key of its presets that the manifest does not claim. */
+function newCopy(m: NewManifest): Record<string, CopySpec> {
+  const p = ONBOARDING_PRESETS[m.component];
+  const base = resolveConfig(p) as Record<string, unknown>;
+  const cases = presetsOf(p).map(k => resolveConfig(p, k) as Record<string, unknown>);
+  const skip = nonCopyKeys(m);
+  const out: Record<string, CopySpec> = {};
+  for (const [k, v] of Object.entries(base)) {
+    if (skip.has(k) || v === undefined || v === null) continue;
+    out[k] = copySpecFrom(k, v, cases.map(c => c[k]), m.copyExtra?.[k]);
+  }
+  return out;
+}
+
+function capabilityOf(m: Manifest): AgentCapability {
+  const isNew = m.family === 'new';
+  const buttons = isNew ? ONBOARDING_BUTTONS[m.component] : { operations: [], events: [] };
+  const p = isNew ? ONBOARDING_PRESETS[m.component] : null;
+  return {
+    schema: CAPABILITY_SCHEMA,
+    agentEditable: true,
+    component: m.component,
+    name: m.name,
+    kind: m.kind,
+    purpose: m.purpose,
+    signals: m.signals,
+    useWhen: m.useWhen,
+    avoidWhen: m.avoidWhen,
+    related: m.related,
+    states: m.states,
+    actions: m.actions,
+    events: m.events,
+    requiresInput: m.requiresInput,
+    presets: p ? presetsOf(p).map(k => ({ preset: k, title: p.meta[k]!.title, scenario: p.meta[k]!.scenario })) : [],
+    data: m.data,
+    copy: isNew ? newCopy(m) : m.copy,
+    behavior: m.behavior,
+    presentation: m.presentation,
+    actionButtons: isNew ? [...buttons.operations.map(o => o.id), ...buttons.events, 'reload'] : [],
+    rules: m.rules,
+    askFor: m.askFor,
+  };
+}
+
+const CAPABILITIES = new Map<string, AgentCapability>(MANIFESTS.map(m => [m.component, capabilityOf(m)]));
+
+/** Everything an agent needs to build a request for one component. A fresh copy — safe to serialise or change. */
+export function describeComponent(id: string): AgentCapability | undefined {
+  const c = CAPABILITIES.get(id);
+  return c ? structuredClone(c) : undefined;
+}
+
+const cardOf = (c: AgentCapability): CapabilityCard => ({ component: c.component, name: c.name, kind: c.kind, purpose: c.purpose, signals: c.signals });
+
+/** Every approved component as a short card. */
+export function listAgentComponents(): CapabilityCard[] {
+  return [...CAPABILITIES.values()].map(cardOf);
+}
+
+/**
+ * Is this component in the agent contract? The approved twelve are; the other New components are
+ * `unavailable` — they render, but their words, data and checks are not held to this contract.
+ */
+export function agentAvailability(id: string): { component: string; agentEditable: boolean; reason?: string } {
+  if (CAPABILITIES.has(id)) return { component: id, agentEditable: true };
+  if ((ONBOARDING_COMPONENTS as readonly string[]).includes(id)) {
+    return { component: id, agentEditable: false, reason: 'Not yet in the agent contract: some of its words, data and checks are not described or validated. Use one of the approved components.' };
+  }
+  return { component: id, agentEditable: false, reason: 'No such component.' };
+}

package/src/agent/classic.ts

@@ -0,0 +1,309 @@
+import { DATA_TYPES, HUES } from '../tokens/hue';
+import {
+  DIRECTORY_COPY, defaultConfigFor, inferColumns, normalizeDirectoryRules, validateDirectoryConfig,
+  type DirectoryConfig, type DirectorySchema,
+} from '../components/directory/contract';
+import {
+  CHECKLIST_COPY, allTasks, defaultChecklistConfig, validateChecklistConfig, validateChecklistRules,
+  type Checklist, type ChecklistConfig, type ChecklistRule,
+} from '../components/checklist/contract';
+import { MAX_STAGES, THRESHOLD_FLOW_COPY, THRESHOLD_FLOW_SCHEMA, validateThresholdFlow, type ThresholdFlowDocument } from '../components/threshold-flow/contract';
+import { bool, json, list, map, num, obj, text } from './spec';
+import type { Semantics } from './manifests';
+import type { CopySpec, FieldSpec, RenderIssue } from './types';
+
+/**
+ * **Directory, Checklist and Threshold Flow, in the same contract.** Their own document models stay
+ * as they are — a Directory is a source and a configuration, a Checklist is a document with a
+ * configuration and rules, a Threshold Flow is a `threshold-flow/1` document. Here each is split into
+ * the request's sections, and put back together by `build`, which runs the family's own validators.
+ */
+
+type Sections = { data: Record<string, unknown>; copy: Record<string, unknown>; behavior: Record<string, unknown>; presentation: Record<string, unknown> };
+export type ClassicBuild = { props: Record<string, unknown>; issues: Omit<RenderIssue, 'layer'>[]; preview: string[] };
+
+export type ClassicManifest = Semantics & {
+  family: 'classic';
+  component: 'directory' | 'checklist' | 'threshold-flow';
+  data: Record<string, FieldSpec>;
+  behavior: Record<string, FieldSpec>;
+  presentation: Record<string, FieldSpec>;
+  copy: Record<string, CopySpec>;
+  /** The component's own document from the request's sections, and what its validators say. */
+  build: (s: Sections) => ClassicBuild;
+};
+
+const owners = ['agent', 'builder', 'developer'] as CopySpec['owners'];
+const PLACEHOLDER = /\{(\w+)\}/g;
+const ph = (s: string) => [...new Set([...s.matchAll(PLACEHOLDER)].map(m => m[1]!))];
+function copyFrom(defaults: Record<string, string>, extra: Record<string, CopySpec> = {}): Record<string, CopySpec> {
+  const out: Record<string, CopySpec> = { ...extra };
+  for (const [k, v] of Object.entries(defaults)) {
+    const p = ph(v);
+    out[k] = { type: 'text', description: `Words: ${k}.`, default: v, ...(p.length ? { placeholders: { required: p, allowed: p } } : {}), owners };
+  }
+  return out;
+}
+const copyText = (description: string, d: string, o: Partial<CopySpec> = {}): CopySpec => ({ type: 'text', description, default: d, owners, ...o });
+const strings = (c: Record<string, unknown>, keys: string[]) => Object.fromEntries(keys.filter(k => typeof c[k] === 'string').map(k => [k, c[k] as string]));
+
+/* ── Directory ─────────────────────────────────────────────────────────────────────────────── */
+
+const DIRECTORY_BEHAVIOR_KEYS = ['primaryColumn', 'secondaryColumn', 'metaColumn', 'searchColumns', 'filterColumns', 'sortColumns', 'visibleColumns', 'detailColumns', 'pageSize', 'selection', 'sort'] as const;
+
+const directory: ClassicManifest = {
+  family: 'classic',
+  component: 'directory',
+  name: 'Directory',
+  kind: 'interactive-output',
+  purpose: 'Browse, search, filter and open records — configured from the records\' own columns.',
+  signals: ['directory', 'look up', 'lookup', 'find a', 'search records', 'browse', 'records', 'contacts', 'people list', 'catalogue', 'from my sheet', 'spreadsheet'],
+  useWhen: ['The person wants to find, filter or open records in a table of their own (people, products, places).'],
+  avoidWhen: ['A summary or a chart of the records — use a dashboard component.', 'A handful of entries to read — use expandable-feed.'],
+  related: [{ component: 'expandable-feed', distinction: 'A feed is a short list to read; a directory is records to search and filter.' }],
+  states: [
+    { state: 'default', description: 'The records, with search, filters and paging.' },
+    { state: 'noResults', description: 'Nothing matches the search or filters.' },
+    { state: 'detail', description: 'A record is open.' },
+    { state: 'empty', description: 'There are no records.' },
+  ],
+  actions: [{ id: 'search', description: 'Search.' }, { id: 'filter', description: 'Filter by a column.' }, { id: 'sort', description: 'Sort.' }, { id: 'open', description: 'Open a record.' }],
+  events: [{ event: 'selected', description: 'The person opened a record.', data: '{ id, record: { [column]: value } }' }],
+  requiresInput: false,
+  rules: ['Every column named in behavior must be one of the records\' columns, and able to do what it is used for (a searchable, filterable or sortable column).'],
+  askFor: { rows: 'Which records should it show? (A sheet, or the list itself.)' },
+  data: {
+    rows: list('The records — one object per record, column → value (all text).', map('A record.', text('A value.')), { required: true, minItems: 1, origin: 'external' }),
+    columns: list('The columns, in order. Default: every key of the rows, in the order first seen.', text('A column.'), { origin: 'derived' }),
+    idColumn: text('The column that identifies a record, reported when one is opened. Default: the row\'s position.', { origin: 'derived' }),
+  },
+  behavior: {
+    primaryColumn: text('The column a record is titled by.'),
+    secondaryColumn: text('A second line under the title.'),
+    metaColumn: text('One trailing value on the row.'),
+    searchColumns: list('Columns search looks in.', text('A column.')),
+    filterColumns: list('Columns offered as filters.', text('A column.')),
+    sortColumns: list('Columns it can sort by.', text('A column.')),
+    visibleColumns: list('Columns shown on the row.', text('A column.')),
+    detailColumns: list('Columns shown when a record is open.', text('A column.')),
+    pageSize: num('Records per page.', { integer: true, min: 1 }),
+    selection: text('Whether a record can be opened.', { enum: ['none', 'single'] }),
+    sort: obj('The starting sort.', { column: text('A column.', { required: true }), dir: text('Direction.', { required: true, enum: ['asc', 'desc'] }) }),
+    rules: list('Rules — when a column matches, filter or highlight. Each is { id, when: { column, op, value }, then, author }.', json('A rule.')),
+  },
+  presentation: {},
+  copy: copyFrom(DIRECTORY_COPY as unknown as Record<string, string>, {
+    title: copyText('The directory\'s heading.', 'Directory'),
+    description: copyText('A line under the heading.', ''),
+  }),
+  build({ data, copy, behavior }) {
+    const rows = (data.rows as Record<string, string>[]) ?? [];
+    const headers = (data.columns as string[] | undefined) ?? [...new Set(rows.flatMap(r => Object.keys(r)))];
+    const issues: ClassicBuild['issues'] = [];
+    const extra = rows.flatMap((r, i) => Object.keys(r).filter(k => !headers.includes(k)).map(k => ({ i, k })));
+    for (const { i, k } of extra) issues.push({ path: `data.rows[${i}].${k}`, code: 'UNKNOWN_KEY', section: 'data', message: `data.rows[${i}] has "${k}", which is not one of data.columns.`, expected: headers });
+    const idColumn = data.idColumn as string | undefined;
+    if (idColumn !== undefined && !headers.includes(idColumn)) issues.push({ path: 'data.idColumn', code: 'REFERENCE', section: 'data', message: `data.idColumn must be one of the columns (got "${idColumn}").`, expected: headers });
+    const schema: DirectorySchema = {
+      source: { kind: 'googleSheets', url: '', sheetName: String(copy.title ?? 'Directory'), title: String(copy.title ?? 'Directory') },
+      columns: inferColumns(headers, rows.map(r => headers.map(h => r[h] ?? ''))),
+      rowCount: rows.length,
+    };
+    const dirCopy = { ...DIRECTORY_COPY, ...strings(copy, Object.keys(DIRECTORY_COPY)) };
+    const config: DirectoryConfig = {
+      ...defaultConfigFor(schema),
+      ...Object.fromEntries(DIRECTORY_BEHAVIOR_KEYS.filter(k => behavior[k] !== undefined).map(k => [k, behavior[k]])),
+      title: String(copy.title ?? 'Directory'),
+      ...(copy.description ? { description: String(copy.description) } : {}),
+      copy: dirCopy,
+    } as DirectoryConfig;
+    for (const m of validateDirectoryConfig(config, schema)) issues.push({ path: 'behavior', code: 'SEMANTIC', section: 'behavior', message: m, expected: schema.columns.map(c => c.key) });
+    const { rules, rejected } = normalizeDirectoryRules(behavior.rules as never, schema);
+    rejected.forEach(r => issues.push({ path: 'behavior.rules', code: 'SEMANTIC', section: 'behavior', message: `Rule ${r.rule.id}: ${r.message}` }));
+    const records = rows.map((r, i) => ({ id: idColumn ? String(r[idColumn] ?? i) : String(i), data: r }));
+    return {
+      props: { schema, config, rules, records },
+      issues,
+      preview: [config.title, ...(config.description ? [config.description] : []), ...records.slice(0, 5).map(r => r.data[config.primaryColumn] ?? '')].filter(Boolean),
+    };
+  },
+};
+
+/* ── Checklist ─────────────────────────────────────────────────────────────────────────────── */
+
+const task = obj('A task.', {
+  id: text('Its id, unique in the checklist.', { required: true }),
+  title: text('The task.', { required: true }),
+  description: text('More about it.'),
+  done: bool('Done already.', { required: true }),
+  skipped: bool('Skipped (needs behavior.can.skip).'),
+  assigneeId: text('Who it is assigned to — a person id the host knows.'),
+  required: bool('Counts towards "all done". Default: true.'),
+});
+
+const checklist: ClassicManifest = {
+  family: 'classic',
+  component: 'checklist',
+  name: 'Checklist',
+  kind: 'interactive',
+  purpose: 'Shared, durable work — tasks people complete over time, in sections, with assignment, gates and sharing through the host.',
+  signals: ['checklist', 'to-do', 'todo', 'tasks', 'steps to complete', 'assign tasks', 'onboarding tasks', 'action items', 'track work'],
+  useWhen: ['Work that persists and gets done over time, possibly by several people.', 'Tasks to tick off, assign or gate on each other.'],
+  avoidWhen: ['Something to read in order — use carousel.', 'A finished process to confirm — use completion.'],
+  related: [
+    { component: 'carousel', distinction: 'A tour is read; a checklist is done.' },
+    { component: 'completion', distinction: 'Completion summarises finished work; a checklist tracks it.' },
+  ],
+  states: [
+    { state: 'default', description: 'Sections of tasks and progress.' },
+    { state: 'saving', description: 'A change is on its way to the host; it can fail and roll back.' },
+    { state: 'blocked', description: 'A task is gated by another.' },
+    { state: 'allDone', description: 'Every required task is done.' },
+  ],
+  actions: [
+    { id: 'complete', description: 'Tick a task.' }, { id: 'edit', description: 'Add, edit, remove or reorder tasks and sections (as allowed).' },
+    { id: 'assign', description: 'Assign a task.' }, { id: 'commit', description: 'Every change is committed by the host.', hostOperation: true },
+    { id: 'share', description: 'Share the checklist (when sharing is on).', hostOperation: true },
+  ],
+  events: [{ event: 'changed', description: 'The checklist changed.', data: '{ checklist, change: { kind, … } }' }],
+  requiresInput: true,
+  rules: ['Task ids are unique across sections; section ids are unique.', 'A skipped task needs skipping allowed; assigning needs assignees shown.'],
+  askFor: { checklist: 'What are the tasks, grouped how?' },
+  data: {
+    checklist: obj('The checklist itself.', {
+      id: text('Its id.', { required: true }),
+      title: text('Its title.', { required: true }),
+      description: text('A line under the title.'),
+      sections: list('Sections, in order.', obj('A section.', {
+        id: text('Its id.', { required: true, unique: true }),
+        title: text('Its heading.'),
+        tasks: list('Its tasks.', task, { required: true }),
+      }), { required: true, minItems: 1 }),
+    }, { required: true, origin: 'invent' }),
+  },
+  behavior: {
+    showDescription: bool('Show the checklist\'s description.'),
+    taskDescriptions: text('Task descriptions.', { enum: ['shown', 'hidden'] }),
+    assignees: text('Assignees.', { enum: ['hidden', 'shown', 'editable'] }),
+    progress: text('Progress display.', { enum: ['bar', 'count', 'both', 'none'] }),
+    sections: text('Section chrome.', { enum: ['grouped', 'flat'] }),
+    collapsibleSections: bool('Sections can collapse.'),
+    rules: list('Gates and filters — { id, author, … } (see the Checklist rules).', json('A rule.')),
+    /* They give other people power over the checklist: the builder's or the host's to decide. */
+    can: json('What the person may do: editChecklist, complete, skip, addTask, editTask, deleteTask, addSection, editSection, deleteSection, reorder, assign.', { owners: ['builder', 'developer'] }),
+    sharing: json('{ enabled }', { owners: ['builder', 'developer'] }),
+    notifications: json('{ enabled, channels }', { owners: ['builder', 'developer'] }),
+  },
+  presentation: {},
+  copy: copyFrom(CHECKLIST_COPY as unknown as Record<string, string>),
+  build({ data, copy, behavior }) {
+    const doc = data.checklist as Checklist;
+    const issues: ClassicBuild['issues'] = [];
+    const seen = new Set<string>();
+    doc.sections.forEach((s, si) => s.tasks.forEach((t, ti) => {
+      if (seen.has(t.id)) issues.push({ path: `data.checklist.sections[${si}].tasks[${ti}].id`, code: 'DUPLICATE', section: 'data', message: `Task id "${t.id}" is used twice.` });
+      seen.add(t.id);
+    }));
+    const d = defaultChecklistConfig();
+    const config: ChecklistConfig = {
+      ...d,
+      ...Object.fromEntries(['showDescription', 'taskDescriptions', 'assignees', 'progress', 'sections', 'collapsibleSections'].filter(k => behavior[k] !== undefined).map(k => [k, behavior[k]])),
+      copy: { ...d.copy, ...strings(copy, Object.keys(CHECKLIST_COPY)) },
+    } as ChecklistConfig;
+    const rules = (behavior.rules as ChecklistRule[] | undefined) ?? [];
+    for (const m of validateChecklistConfig(config, { checklist: doc, rules })) issues.push({ path: 'behavior', code: 'SEMANTIC', section: 'behavior', message: m });
+    for (const r of validateChecklistRules(rules, doc).rejected) issues.push({ path: 'behavior.rules', code: 'SEMANTIC', section: 'behavior', message: `Rule ${r.rule.id}: ${r.message}` });
+    return {
+      props: { checklist: doc, config, rules },
+      issues,
+      preview: [doc.title, ...(doc.description ? [doc.description] : []), ...doc.sections.flatMap(s => [s.title ?? '', ...s.tasks.map(t => t.title)]), ...(allTasks(doc).length ? [] : [config.copy.emptyLabel])].filter(Boolean),
+    };
+  },
+};
+
+/* ── Threshold Flow ────────────────────────────────────────────────────────────────────────── */
+
+const stage = (what: string) => obj(what, {
+  id: text('Its id — lower-case letters, digits and -.', { required: true, pattern: '^[a-z0-9-]+$', patternHint: 'uses lower-case letters, digits and -', unique: true }),
+  title: text('Its name.', { required: true }),
+  role: text('Who or what it involves.'),
+  value: num('Its threshold — more than the stage before.', { required: true, exclusiveMin: 0 }),
+  toggle: bool('Its switch (needs copy.toggleLabel).'),
+});
+
+const thresholdFlow: ClassicManifest = {
+  family: 'classic',
+  component: 'threshold-flow',
+  name: 'Threshold Flow',
+  kind: 'interactive',
+  purpose: 'Ordered stages with strictly rising thresholds and a switch each — approvals, escalations, usage limits — activated by the host.',
+  signals: ['threshold', 'thresholds', 'tiers', 'levels', 'escalation', 'escalate', 'approval limits', 'approval chain', 'usage limits', 'limits', 'stages'],
+  useWhen: ['Defining levels that start at a number — spend approvals, escalation after N minutes, usage tiers.'],
+  avoidWhen: ['Splitting a fixed total — use seat-allocation.', 'Numbers that are not cut-offs.'],
+  related: [{ component: 'seat-allocation', distinction: 'Seat Allocation shares a total; a threshold flow sets rising cut-offs.' }],
+  states: [
+    { state: 'editing', description: 'Stages to edit, each with its value and switch.' },
+    { state: 'invalid', description: 'A value is empty, over the maximum or not more than the one before.' },
+    { state: 'activating', description: 'The host is activating the flow.' },
+    { state: 'live', description: 'Activated.' },
+    { state: 'refused', description: 'The host refused it; the reason is shown.' },
+  ],
+  actions: [{ id: 'edit', description: 'Add, remove or edit stages (Add needs behavior.templates).' }, { id: 'activate', description: 'Activate — the host applies it.', hostOperation: true }],
+  events: [
+    { event: 'changed', description: 'The stages changed.', data: '{ stages: { id, title, role, value, toggle }[] }' },
+    { event: 'activated', description: 'The host activated them.', data: '{ stages }' },
+  ],
+  requiresInput: true,
+  rules: [`At most ${MAX_STAGES} stages.`, 'Each stage\'s value is more than the one before, and at most unit.max.', 'A stage with a switch needs copy.toggleLabel.'],
+  askFor: { stages: 'What are the levels, and the number each starts at?' },
+  data: {
+    stages: list('The stages, in order.', stage('A stage.'), { required: true, maxItems: MAX_STAGES, origin: 'user' }),
+    unit: obj('How values read.', { prefix: text('Before the value — "$".'), suffix: text('After the value — " min".'), max: num('The largest value allowed.', { exclusiveMin: 0 }) }, { origin: 'invent' }),
+  },
+  behavior: {
+    templates: list('What Add inserts, in order. Without it, Add is not offered.', obj('A template.', {
+      title: text('Its name.', { required: true }), role: text('Who or what.'), value: num('Its threshold.', { required: true, exclusiveMin: 0 }), toggle: bool('Its switch.'),
+    })),
+  },
+  presentation: {
+    type: text('The data type the colour stands for.', { enum: DATA_TYPES, owners: ['agent', 'builder', 'developer'] }),
+    hue: text('An explicit colour.', { enum: HUES, owners: ['builder', 'developer'] }),
+  },
+  copy: copyFrom(THRESHOLD_FLOW_COPY as unknown as Record<string, string>, {
+    title: copyText('The flow\'s heading.', '', { required: true }),
+    description: copyText('A line under the heading.', ''),
+    valueLabel: copyText('The label on every stage\'s value — "Over", "After".', '', { required: true }),
+    toggleLabel: copyText('The label on every stage\'s switch.', ''),
+    noun: { type: 'text-map', description: 'What a stage is called: { one, other }.', default: { one: 'stage', other: 'stages' }, owners },
+  }),
+  build({ data, copy, behavior, presentation }) {
+    const noun = copy.noun as { one?: string; other?: string } | undefined;
+    const doc: ThresholdFlowDocument = {
+      schema: THRESHOLD_FLOW_SCHEMA,
+      key: 'agent_flow',
+      props: {
+        ...(presentation.type ? { type: presentation.type as never } : {}),
+        ...(presentation.hue ? { hue: presentation.hue as never } : {}),
+        title: String(copy.title ?? ''),
+        ...(copy.description ? { description: String(copy.description) } : {}),
+        ...(data.unit ? { unit: data.unit as never } : {}),
+        valueLabel: String(copy.valueLabel ?? ''),
+        ...(copy.toggleLabel ? { toggleLabel: String(copy.toggleLabel) } : {}),
+        ...(noun ? { noun: { one: noun.one ?? 'stage', other: noun.other ?? 'stages' } } : {}),
+        defaultItems: data.stages as never,
+        ...(behavior.templates ? { templates: behavior.templates as never } : {}),
+        copy: strings(copy, Object.keys(THRESHOLD_FLOW_COPY)),
+      },
+    };
+    const issues: ClassicBuild['issues'] = validateThresholdFlow(doc).map(i => ({
+      path: i.code === 'toggle-without-label' ? 'copy.toggleLabel' : i.code.startsWith('template') ? 'behavior.templates' : 'id' in i && i.id ? `data.stages` : 'request',
+      code: 'SEMANTIC' as const,
+      section: i.code === 'toggle-without-label' ? 'copy' as const : i.code.startsWith('template') ? 'behavior' as const : 'data' as const,
+      message: i.message,
+    }));
+    const stages = (data.stages as { title: string; value: number }[]) ?? [];
+    return { props: { doc }, issues, preview: [doc.props.title, ...(doc.props.description ? [doc.props.description] : []), ...stages.map(s => `${s.title} · ${doc.props.valueLabel} ${s.value}`)] };
+  },
+};
+
+export const CLASSIC_MANIFESTS: readonly ClassicManifest[] = [directory, checklist, thresholdFlow];

package/src/agent/core.ts

@@ -0,0 +1,8 @@
+/**
+ * **`@appinternalleads/ui/agent` — the agent contract, with search, without React.** Search,
+ * describe, `render/1` validation and `result/1`: what a backend or an MCP server needs, all of it in
+ * plain Node. `searchComponents` lives only here (and its word-vector table with it); the renderer,
+ * `AgentComponent`, is in the main entry. `docs/AGENT-COMPONENT-CONTRACT.md`.
+ */
+export * from './base';
+export { searchComponents } from './search';

package/src/agent/index.ts

@@ -0,0 +1,10 @@
+/**
+ * **The agent contract, as the main entry carries it** — for the app that renders: `AgentComponent`,
+ * `AGENT_RENDERABLE`, and the small React-free contract they use (describe, validate, results).
+ *
+ * Not `searchComponents`: component search belongs to the agent, and its word-vector table must not
+ * reach an app's bundle. Import it from `@appinternalleads/ui/agent`. `tests/agent/boundary.test.ts`
+ * holds this line on the built package.
+ */
+export * from './base';
+export { AgentComponent, AGENT_RENDERABLE, type AgentComponentProps } from './AgentComponent';