@appinternalleads/ui 0.2.0 → 0.4.0

package/src/agent/manifests.ts

@@ -0,0 +1,534 @@
+import { DATA_TYPES } from '../tokens/hue';
+import { ONBOARDING_ICONS, type OnboardingComponent } from '../components/onboarding/shared/contract';
+import { ONBOARDING_PRESETS } from '../components/onboarding/presets';
+import { FIELD_KEY, RECEIPT_MAX_AMOUNT, RECEIPT_MAX_FIELDS, RECEIPT_MAX_ITEMS, RECEIPT_MAX_LENGTH, RECEIPT_MAX_QUANTITY } from '../components/onboarding/receipt-printer/contract';
+import { HEATMAP_REVEALS } from '../components/onboarding/activity-heatmap/contract';
+import { FEED_BLOCK_KINDS } from '../components/onboarding/expandable-feed/contract';
+import { MAX_SLIDES } from '../components/onboarding/carousel/contract';
+import { bool, json, list, map, num, obj, text } from './spec';
+import type { AgentCapability, CapabilityAction, CapabilityCard, CapabilityEvent, CopySpec, FieldSpec } from './types';
+
+/**
+ * **What each approved New component is, for an agent** — written once, here. The semantic text is
+ * drawn from the component's catalogue blurb, its case studies and its contract; the data rules are
+ * the component's own (its validator, its engine's limits), named where they live. Copy is not
+ * listed by hand: it is every other key of the component's presets, so a word added to a component
+ * is copy until a manifest says otherwise (and `tests/agent/catalog.test.ts` checks every copy key
+ * holds words).
+ */
+
+export type Semantics = Omit<CapabilityCard, 'component'> & Pick<AgentCapability, 'useWhen' | 'avoidWhen' | 'related' | 'states' | 'requiresInput' | 'rules' | 'askFor'> & {
+  actions: CapabilityAction[];
+  events: CapabilityEvent[];
+};
+
+export type NewManifest = Semantics & {
+  family: 'new';
+  component: OnboardingComponent;
+  data: Record<string, FieldSpec>;
+  behavior: Record<string, FieldSpec>;
+  presentation: Record<string, FieldSpec>;
+  /** Config keys that are not copy but are not set from the request either — demo and internal. They are cleared, never inherited from a preset. */
+  system: string[];
+  /** Copy details a preset cannot say: layout limits. */
+  copyExtra?: Record<string, Partial<CopySpec>>;
+  /** Request key → config key, where they differ (`data.byPeriod` → `data`). */
+  rename?: Partial<Record<'data' | 'behavior' | 'presentation', Record<string, string>>>;
+};
+
+const base = (c: OnboardingComponent) => ({ ...ONBOARDING_PRESETS[c].baseCopy, ...ONBOARDING_PRESETS[c].base }) as Record<string, unknown>;
+const presentation = (c: OnboardingComponent): Record<string, FieldSpec> => ({
+  type: text('The data type the header tile\'s colour stands for.', { enum: DATA_TYPES, default: base(c).type, owners: ['agent', 'builder', 'developer'] }),
+  icon: text('The header icon.', { enum: ONBOARDING_ICONS, default: base(c).icon, owners: ['agent', 'builder', 'developer'] }),
+});
+const tileType = (d: string) => text(`${d} tile colour, by data type.`, { enum: DATA_TYPES });
+const tileIcon = (d: string) => text(`${d} icon.`, { enum: ONBOARDING_ICONS });
+/* A card's heading and its subtitle describe what it shows — the case study's "Split your 15 seats across teams." is not a default for someone else's data. */
+const HEADER: Record<string, Partial<CopySpec>> = { title: { required: true }, subtitle: { default: '' } };
+const LOAD_STATES = [
+  { state: 'loading', description: 'The host is still loading the step (status="loading").' },
+  { state: 'empty', description: 'Nothing to show yet (status="empty"); the empty copy and its button.' },
+  { state: 'error', description: 'The step failed to load (status="error"); Retry calls the host\'s reload.' },
+];
+
+const receiptPrinter: NewManifest = {
+  family: 'new',
+  component: 'receipt-printer',
+  name: 'Receipt Printer',
+  kind: 'input-output',
+  purpose: 'Record and print a proof of one payment: a form for what was paid, how, when and for whom, and a printer that feeds out a receipt with exactly those values.',
+  signals: ['receipt', 'proof of payment', 'payment proof', 'paid', 'bill', 'transaction receipt', 'print a receipt', 'till', 'sale', 'purchase'],
+  useWhen: [
+    'The person wants a receipt or proof for one payment that has happened.',
+    'The payment\'s items or amount, currency, method and date are known or can be asked.',
+    'The person should see — and may correct — the values before the receipt is printed.',
+  ],
+  avoidWhen: [
+    'A formal invoice asking for a future payment (due dates, terms): this prints what was paid.',
+    'Several transactions or a statement over time — use budget-tracker or a list.',
+    'The person needs a PDF or image file: the receipt is printed on screen and reported as data, not exported.',
+  ],
+  related: [
+    { component: 'completion', distinction: 'Completion confirms a finished setup; a receipt proves a payment.' },
+    { component: 'budget-tracker', distinction: 'Budget Tracker sums spend by category over a period; a receipt is one payment.' },
+  ],
+  states: [
+    { state: 'editing', description: 'The form, with a live preview on the idle printer.' },
+    { state: 'invalid', description: 'Print was pressed with problems; each field says what is wrong.' },
+    { state: 'printing', description: 'The form is locked; the host\'s print runs while the paper feeds.' },
+    { state: 'printed', description: 'The receipt is at rest; the result is reported.' },
+    { state: 'failed', description: 'The host\'s print failed; the paper retracts and Print again retries.' },
+    ...LOAD_STATES,
+  ],
+  actions: [
+    { id: 'print', description: 'Checks the form and prints. The host\'s print operation records or sends the receipt.', hostOperation: true },
+    { id: 'printAgain', description: 'Prints the form as it now stands.' },
+    { id: 'reset', description: 'Puts the form and the printer back to the request\'s values.' },
+    { id: 'editFields', description: 'The person adds, removes, renames or re-keys fields.' },
+  ],
+  events: [
+    { event: 'printed', description: 'The receipt is printed and at rest.', data: '{ receipt: { fields: { [key]: value }, items: { name, quantity, amount }[], currency, paymentMethod, date, message }, lines: { title, total, meta, details: { label, value }[], items: { line, amount }[], paymentLabel, paymentMethod, totalLabel, message } }' },
+    { event: 'reset', description: 'The person pressed Reset.', data: '{}' },
+    { event: 'fieldsChanged', description: 'The person redefined the fields.', data: '{ fields: { key, label, value, heading }[] }' },
+  ],
+  requiresInput: true,
+  rules: [
+    'currency must be one of behavior.currencies[].code; paymentMethod one of behavior.paymentMethods[].id.',
+    'An item\'s amount has at most as many decimals as its currency allows (0 for JPY, 2 for INR/USD/EUR/GBP).',
+    'A field\'s value is at most 24 characters, or 28 for the heading field; a label at most 16.',
+    'Field keys are unique; the first field with heading: true prints large at the top.',
+  ],
+  askFor: {
+    items: 'What was paid for, how many, and the price of each?',
+    currency: 'Which currency was it paid in?',
+    paymentMethod: 'How was it paid?',
+    date: 'On what date was it paid?',
+    fields: 'Who is the receipt for (or from), and any reference number to print on it?',
+  },
+  data: {
+    fields: list('The receipt\'s own fields — name them for this business ("Book name", "Recipient"). Printed as label/value rows; the value is what the person can edit.', obj('A field.', {
+      key: text('How the value is reported in the result — letters, digits and _.', { required: true, pattern: FIELD_KEY.source, patternHint: 'starts with a letter and uses letters, digits and _', unique: true, origin: 'invent' }),
+      label: text('What the form and the receipt call it.', { required: true, maxLength: RECEIPT_MAX_LENGTH.fieldLabel, origin: 'invent' }),
+      value: text('The value printed.', { required: true, maxLength: RECEIPT_MAX_LENGTH.heading, origin: 'user' }),
+      heading: bool('Print this field large at the top (a business or shop name).'),
+    }), { required: true, maxItems: RECEIPT_MAX_FIELDS, origin: 'user' }),
+    items: list('The lines of the receipt.', obj('A line.', {
+      name: text('What was paid for.', { required: true, maxLength: RECEIPT_MAX_LENGTH.itemName!, origin: 'user' }),
+      quantity: num('How many.', { required: true, integer: true, min: 1, max: RECEIPT_MAX_QUANTITY, origin: 'user' }),
+      amount: num('The price of one, in the currency.', { required: true, exclusiveMin: 0, max: RECEIPT_MAX_AMOUNT, origin: 'user' }),
+    }), { required: true, minItems: 1, maxItems: RECEIPT_MAX_ITEMS, origin: 'user' }),
+    currency: text('The currency code.', { required: true, ref: 'behavior.currencies[].code', origin: 'user' }),
+    paymentMethod: text('How it was paid — an id.', { required: true, ref: 'behavior.paymentMethods[].id', origin: 'user' }),
+    date: text('When it was paid.', { required: true, format: 'date', origin: 'user' }),
+    message: text('A line printed at the foot. Optional.', { maxLength: RECEIPT_MAX_LENGTH.message, default: '', origin: 'invent' }),
+  },
+  behavior: {
+    currencies: list('The currencies the form offers.', obj('A currency.', {
+      code: text('ISO code, e.g. INR.', { required: true, unique: true }),
+      symbol: text('Printed before amounts, e.g. ₹.', { required: true }),
+      decimals: num('Its minor unit: 2 for ₹ and $, 0 for ¥.', { required: true, integer: true, min: 0, max: 4 }),
+    }), { minItems: 1, default: base('receipt-printer').currencies, owners: ['agent', 'builder', 'developer'] }),
+    paymentMethods: list('The payment methods the form offers.', obj('A method.', {
+      id: text('Its id — what paymentMethod names.', { required: true, unique: true }),
+      label: text('What the form and the receipt call it.', { required: true }),
+    }), { minItems: 1, default: base('receipt-printer').paymentMethods, owners: ['agent', 'builder', 'developer'] }),
+  },
+  presentation: presentation('receipt-printer'),
+  system: ['ship'],
+  /* The total and the payment print in the same label column as a field's label (ReceiptPaper `row`, the Rive `details` rows). */
+  copyExtra: {
+    totalLabel: { maxLength: RECEIPT_MAX_LENGTH.fieldLabel },
+    paymentLabel: { maxLength: RECEIPT_MAX_LENGTH.fieldLabel },
+  },
+};
+
+const budgetTracker: NewManifest = {
+  family: 'new',
+  component: 'budget-tracker',
+  name: 'Budget Tracker',
+  kind: 'interactive-output',
+  purpose: 'Show spend against allocation, by category, for a period — which categories are over, near the limit or under.',
+  signals: ['budget', 'spent', 'spend', 'spending', 'money spent', 'allocated', 'over budget', 'remaining budget', 'costs', 'expenses'],
+  useWhen: [
+    'The question is how much was spent against what was budgeted, per category.',
+    'The person wants to see which categories are over or close to their budget.',
+  ],
+  avoidWhen: [
+    'There is no budget per category — only spend (a plain list or chart fits better).',
+    'The question is how often, per day — use activity-heatmap.',
+    'One payment — use receipt-printer.',
+  ],
+  related: [
+    { component: 'activity-heatmap', distinction: 'Heatmap counts events per day; Budget Tracker compares money with a limit per category.' },
+    { component: 'criteria-spider', distinction: 'Spider scores items across criteria; Budget Tracker is money against allocation.' },
+  ],
+  states: [
+    { state: 'default', description: 'The summary and a bar per category, revealed once.' },
+    { state: 'someOver', description: 'Some categories are over budget, said in words.' },
+    { state: 'switchPeriod', description: 'The person picked another period.' },
+    ...LOAD_STATES,
+  ],
+  actions: [
+    { id: 'switchPeriod', description: 'Choose another period, when there are several.' },
+    { id: 'openCategory', description: 'Open a category.' },
+  ],
+  events: [
+    { event: 'periodChanged', description: 'The person picked a period.', data: '{ period }' },
+    { event: 'categoryOpened', description: 'The person opened a category.', data: '{ id }' },
+  ],
+  requiresInput: false,
+  rules: ['With more than one period, period must be one of periods.', 'Spend and allocation come from real records — never invent them.'],
+  askFor: { period: 'Which period should it cover?', categories: 'What is the budget and the spend for each category?' },
+  data: {
+    currency: text('ISO 4217 currency code of every amount.', { required: true, pattern: '^[A-Z]{3}$', patternHint: 'is a three-letter ISO currency code', origin: 'external' }),
+    period: text('The period shown, e.g. "September 2026".', { required: true, origin: 'external' }),
+    periods: list('Periods the person can switch between.', text('A period.'), { default: [], origin: 'external' }),
+    categories: list('The categories.', obj('A category.', {
+      id: text('Its id, reported when it is opened.', { unique: true }),
+      name: text('The category.', { required: true }),
+      allocated: num('Budgeted amount.', { required: true, min: 0 }),
+      spent: num('Spent so far.', { required: true, min: 0 }),
+      period: text('The period this row belongs to, when there are several.'),
+    }), { required: true, origin: 'external' }),
+    byPeriod: map('Categories per period, when each period has its own list.', list('Categories.', obj('A category.', {
+      id: text('Its id.'), name: text('The category.', { required: true }), allocated: num('Budgeted.', { required: true, min: 0 }), spent: num('Spent.', { required: true, min: 0 }),
+    })), { origin: 'external' }),
+  },
+  behavior: {
+    attentionAt: num('Warn when spend reaches this share of the allocation (0–1]; null for off.', { exclusiveMin: 0, max: 1, nullable: true, default: null, owners: ['agent', 'builder', 'developer'] }),
+  },
+  presentation: presentation('budget-tracker'),
+  copyExtra: HEADER,
+  system: ['ship'],
+  rename: { data: { byPeriod: 'data' } },
+};
+
+const activityHeatmap: NewManifest = {
+  family: 'new',
+  component: 'activity-heatmap',
+  name: 'Activity Heatmap',
+  kind: 'interactive-output',
+  purpose: 'Show how often something happened on each day over a range — totals, the peak day and streaks — and a day\'s items on click.',
+  signals: ['per day', 'daily', 'activity', 'how often', 'frequency', 'streak', 'calendar', 'consistency', 'contributions', 'each day'],
+  useWhen: ['The question is how often something happened, day by day, over weeks or months.', 'Streaks, busy days or quiet days matter.'],
+  avoidWhen: ['Money against a budget — use budget-tracker.', 'Comparing items on several criteria — use criteria-spider.', 'A single day or a handful of events — a list says it better.'],
+  related: [
+    { component: 'budget-tracker', distinction: 'Budget Tracker is money per category; the heatmap is a count per day.' },
+    { component: 'expandable-feed', distinction: 'A feed lists entries; the heatmap shows how many there were each day.' },
+  ],
+  states: [
+    { state: 'default', description: 'Stats, the week grid and the legend.' },
+    { state: 'popover', description: 'A day is open, with its items (loaded by the host).' },
+    { state: 'zeroDay', description: 'An open day with nothing on it.' },
+    ...LOAD_STATES,
+  ],
+  actions: [
+    { id: 'selectDay', description: 'Open a day.' },
+    { id: 'loadDay', description: 'Load a day\'s items — the host answers with data.', hostOperation: true },
+    { id: 'open', description: 'Open everything for a day ("View all").' },
+  ],
+  events: [
+    { event: 'daySelected', description: 'A day was opened or closed.', data: '{ date: string | null }' },
+    { event: 'opened', description: 'The person asked for everything on a day.', data: '{ date }' },
+  ],
+  requiresInput: false,
+  rules: ['range spans at most about two years, and ends on or after it starts.', 'Counts come from real records — never invent them.'],
+  askFor: { days: 'Which activity should it count, and over what dates?' },
+  data: {
+    days: list('One count per day.', obj('A day.', {
+      date: text('The day.', { required: true, format: 'date' }),
+      count: num('How many that day.', { required: true, min: 0 }),
+    }), { required: true, origin: 'external' }),
+    noun: text('What is counted, plural — "deploys".', { required: true, origin: 'invent' }),
+    nounOne: text('The same, singular — "deploy".', { required: true, origin: 'invent' }),
+    periodLabel: text('The range in words — "Jan–Mar 2026".', { required: true, origin: 'derived' }),
+    range: obj('The dates shown; null to use the days given.', {
+      start: text('First day.', { required: true, format: 'date' }),
+      end: text('Last day.', { required: true, format: 'date' }),
+    }, { nullable: true, default: null, origin: 'derived' }),
+    today: text('Today, for "today" and upcoming days; null for the real today.', { format: 'date', nullable: true, default: null, origin: 'derived' }),
+  },
+  behavior: {
+    reveal: text('How the grid appears.', { enum: HEATMAP_REVEALS, default: base('activity-heatmap').reveal, owners: ['agent', 'builder', 'developer'] }),
+  },
+  presentation: presentation('activity-heatmap'),
+  /* The presets' empty state speaks of their case study's reviews; an agent's card is about its own data. */
+  copyExtra: { ...HEADER, emptyTitle: { default: 'Nothing in this period' }, emptyBody: { default: 'Try a longer range.' } },
+  system: ['sample', 'ship'],
+};
+
+const criteriaSpider: NewManifest = {
+  family: 'new',
+  component: 'criteria-spider',
+  name: 'Criteria Spider',
+  kind: 'interactive-output',
+  purpose: 'Compare items scored on the same criteria as a radar — each item\'s strongest and weakest criteria, and two items side by side.',
+  signals: ['compare', 'comparison', 'versus', 'vs', 'scorecard', 'rate', 'rating on', 'strengths and weaknesses', 'evaluate', 'criteria', 'options'],
+  useWhen: ['Several options are scored on the same three or more criteria.', 'The person wants to see where each option is strong or weak, or compare two.'],
+  avoidWhen: ['One number per item — a list or table is clearer.', 'Money against a budget — use budget-tracker.', 'Fewer than three criteria: a radar needs three.'],
+  related: [
+    { component: 'expandable-feed', distinction: 'A feed shows reviews as text; the spider shows scores per criterion.' },
+    { component: 'budget-tracker', distinction: 'Budget Tracker is spend per category; the spider is scores per criterion.' },
+  ],
+  states: [
+    { state: 'default', description: 'The first item\'s radar, its criteria and summary.' },
+    { state: 'next', description: 'Another item, the shape morphing to it.' },
+    { state: 'compare', description: 'Two items on one radar.' },
+    ...LOAD_STATES,
+  ],
+  actions: [{ id: 'switchItem', description: 'Show another item.' }, { id: 'compare', description: 'Compare with another item.' }],
+  events: [
+    { event: 'itemChanged', description: 'The person switched item.', data: '{ id }' },
+    { event: 'compared', description: 'Compare turned on or off.', data: '{ id: string | null }' },
+  ],
+  requiresInput: false,
+  rules: ['Every item has one value per criterion, in criteria order (0 or more; the scale tops out at max).', 'At least three criteria.', 'Scores come from a real evaluation — never invent them.'],
+  askFor: { criteria: 'Which criteria should the options be scored on?', items: 'Which options, and their scores on each criterion?' },
+  data: {
+    max: num('The top of the scale, e.g. 10.', { required: true, exclusiveMin: 0, origin: 'external' }),
+    criteria: list('The criteria, in order.', obj('A criterion.', {
+      id: text('Its id.', { unique: true }),
+      label: text('Its name.', { required: true }),
+    }), { required: true, minItems: 3, origin: 'external' }),
+    items: list('The items.', obj('An item.', {
+      id: text('Its id — what activeId and compareId name, and what is reported.', { unique: true }),
+      name: text('The item.', { required: true }),
+      score: num('Its overall score.', { required: true }),
+      values: list('One value per criterion, in criteria order.', num('A value.', { min: 0 }), { required: true }),
+      category: text('A line under its name.'),
+      reviews: text('A note beside the score, e.g. "124 reviews".'),
+      strongest: list('What it does best.', text('A point.')),
+      weakest: list('Where it falls short.', text('A point.')),
+      summary: text('A paragraph about it.'),
+      chips: list('Short tags.', text('A tag.')),
+    }), { required: true, minItems: 1, origin: 'external' }),
+  },
+  behavior: {
+    activeId: text('The item shown first.', { nullable: true, default: null, ref: 'data.items[].id', owners: ['agent', 'builder', 'developer'] }),
+    compareId: text('An item to compare with from the start.', { nullable: true, default: null, ref: 'data.items[].id', owners: ['agent', 'builder', 'developer'] }),
+  },
+  presentation: presentation('criteria-spider'),
+  /* The presets' empty state speaks of their case study's reviews; an agent's card is about its own data. */
+  copyExtra: { ...HEADER, emptyBody: { default: 'Scores appear once they are in.' }, emptyCta: { default: 'Refresh' } },
+  system: ['ship'],
+};
+
+const expandableFeed: NewManifest = {
+  family: 'new',
+  component: 'expandable-feed',
+  name: 'Expandable Feed',
+  kind: 'interactive-output',
+  purpose: 'A list of entries — reviews, a changelog, tickets, runs, an FAQ — each opening to its detail, one at a time.',
+  signals: ['reviews', 'changelog', 'release notes', 'what changed', 'history', 'log', 'tickets', 'faq', 'questions', 'entries', 'feed'],
+  useWhen: ['A readable list of entries where each has more to say when opened.', 'Reviews with ratings, release notes, support tickets, a run log, an FAQ.'],
+  avoidWhen: ['Numbers to compare — use criteria-spider, budget-tracker or activity-heatmap.', 'A guided tour of a few highlights — use carousel.'],
+  related: [
+    { component: 'carousel', distinction: 'A carousel walks through a few slides in order; a feed is a list read in any order.' },
+    { component: 'criteria-spider', distinction: 'The spider scores items; a feed shows their text.' },
+  ],
+  states: [
+    { state: 'default', description: 'The list, one row open if defaultOpenId says so.' },
+    { state: 'oneOpen', description: 'A row is open showing its detail.' },
+    { state: 'showMore', description: 'A long text expanded.' },
+    ...LOAD_STATES,
+  ],
+  actions: [{ id: 'open', description: 'Open or close a row.' }, { id: 'vote', description: 'Mark an entry helpful — the host records it.', hostOperation: true }],
+  events: [
+    { event: 'openChanged', description: 'A row opened or closed.', data: '{ id: string | null }' },
+    { event: 'feedback', description: 'The person voted Helpful.', data: '{ id, pressed }' },
+  ],
+  requiresInput: false,
+  rules: [`A row's detail is a list of blocks; each block's kind is one of ${FEED_BLOCK_KINDS.join(', ')}.`, 'A rating is from 0 to 5.'],
+  askFor: {},
+  data: {
+    items: list('The entries.', obj('An entry.', {
+      id: text('Its id — what defaultOpenId names and what is reported.', { unique: true }),
+      title: text('The entry.', { required: true }),
+      verified: bool('Shows a verified check.'),
+      initials: text('A person\'s initials, in a circle.'),
+      icon: tileIcon('An icon instead of initials:'),
+      iconType: tileType('The icon'),
+      rating: num('Stars, 0–5.', { min: 0, max: 5 }),
+      meta: list('Short facts after the rating, joined by "·".', text('A fact.')),
+      detail: list(`What it opens to — blocks: ${FEED_BLOCK_KINDS.map(k => `{ kind: "${k}", … }`).join(', ')}.`, json('A block.')),
+    }), { required: true, origin: 'external' }),
+    summary: obj('The header\'s right side.', {
+      rating: num('An average rating.', { nullable: true }),
+      items: list('Up to three short facts.', text('A fact.'), { maxItems: 3 }),
+    }, { nullable: true, default: null, origin: 'derived' }),
+    count: text('A chip beside the title, e.g. "5 reviews".', { nullable: true, default: null, origin: 'derived' }),
+    footer: list('The footer strip: one line left, one right.', text('A line.'), { maxItems: 2, default: [], origin: 'derived' }),
+  },
+  behavior: {
+    defaultOpenId: text('The row open on arrival.', { nullable: true, default: null, ref: 'data.items[].id', owners: ['agent', 'builder', 'developer'] }),
+  },
+  presentation: presentation('expandable-feed'),
+  /* The presets' empty state speaks of their case study's reviews; an agent's card is about its own data. */
+  copyExtra: { ...HEADER, emptyTitle: { default: 'Nothing here yet' }, emptyBody: { default: 'Entries appear here once there are some.' }, emptyCta: { default: 'Refresh' }, verifiedLabel: { default: 'Verified' } },
+  system: ['moreId', 'ship'],
+};
+
+const fallback: NewManifest = {
+  family: 'new',
+  component: 'fallback',
+  name: 'Fallback',
+  kind: 'interactive-output',
+  purpose: 'Show data that failed its declared format as readable label/value rows — never raw text or JSON — and let the person copy it.',
+  signals: ['failed to render', 'invalid output', 'schema mismatch', 'raw data', 'could not display', 'unstructured result'],
+  useWhen: ['A result could not be shown in the component it was meant for, and it should still be readable.'],
+  avoidWhen: ['The data fits a real component — use that. Fallback is recovery, never a first choice.'],
+  related: [{ component: 'expandable-feed', distinction: 'A feed is a designed list; Fallback is what shows when a design could not be used.' }],
+  states: [
+    { state: 'default', description: 'The data as label/value rows, with a note saying it is simplified.' },
+    { state: 'nullData', description: 'The data came back empty.' },
+    ...LOAD_STATES,
+  ],
+  actions: [{ id: 'copy', description: 'Copy the data as text.' }],
+  events: [{ event: 'copied', description: 'The person copied the data.', data: '{ text }' }],
+  requiresInput: false,
+  rules: ['declared names the type the data was meant to be (stats, table, comparison…).'],
+  askFor: {},
+  data: {
+    data: json('The payload that failed — any JSON; null for none.', { required: true, nullable: true, origin: 'external' }),
+    declared: text('The type it was declared as — "stats", "table".', { required: true, origin: 'external' }),
+    failure: text('Why it did not match, in a few words.', { required: true, origin: 'external' }),
+  },
+  behavior: {
+    showNote: bool('Show the "simplified view" note.', { default: true, owners: ['agent', 'builder', 'developer'] }),
+  },
+  presentation: presentation('fallback'),
+  system: ['samples', 'ship'],
+  copyExtra: {
+    ...HEADER,
+    fieldLabels: { open: true, description: 'Display names for the data\'s own keys ("averageOrder" → "Average order"). A key not listed is humanised.' },
+    typeLabels: { open: true, description: 'How the note names each declared type ("keyvalue" → "key-value").' },
+  },
+};
+
+const seatAllocation: NewManifest = {
+  family: 'new',
+  component: 'seat-allocation',
+  name: 'Seat Allocation',
+  kind: 'interactive',
+  purpose: 'Split a fixed number of seats, licences or tickets across groups, each with a minimum, and save the split.',
+  signals: ['allocate', 'split', 'distribute', 'seats', 'licences', 'licenses', 'tickets', 'per team', 'assign seats', 'divide'],
+  useWhen: ['The person must decide how a fixed total of whole units is shared between groups.'],
+  avoidWhen: ['Only showing usage — nothing to decide.', 'Money across categories — this counts whole units.'],
+  related: [{ component: 'budget-tracker', distinction: 'Budget Tracker shows spend; Seat Allocation is a decision about a fixed total.' }],
+  states: [
+    { state: 'default', description: 'A stepper per group and the seats left.' },
+    { state: 'atMin', description: 'A group is at its minimum.' },
+    { state: 'allUsed', description: 'Every seat is given out; every + is off.' },
+    { state: 'saving', description: 'The host is saving the split.' },
+    { state: 'saved', description: 'Saved.' },
+    { state: 'failed', description: 'The save failed; retry.' },
+    ...LOAD_STATES,
+  ],
+  actions: [{ id: 'change', description: 'Change a group\'s seats.' }, { id: 'save', description: 'Save the split — the host stores it.', hostOperation: true }],
+  events: [
+    { event: 'changed', description: 'The split changed.', data: '{ groups: { name, seats }[] }' },
+    { event: 'saved', description: 'The split was saved.', data: '{ groups: { name, seats }[] }' },
+  ],
+  requiresInput: true,
+  rules: ['Each group starts at or above its minimum.', 'The groups\' seats add up to at most totalSeats.'],
+  askFor: { totalSeats: 'How many seats are there in total?', groups: 'Which groups share them, and the minimum each needs?' },
+  data: {
+    totalSeats: num('The fixed total.', { required: true, integer: true, exclusiveMin: 0, origin: 'external' }),
+    groups: list('The groups.', obj('A group.', {
+      name: text('The group.', { required: true, unique: true }),
+      seats: num('Seats it starts with.', { required: true, integer: true, min: 0 }),
+      min: num('The fewest it may have.', { required: true, integer: true, min: 0 }),
+      detail: text('A line under its name.', { default: '' }),
+      type: tileType('Its'),
+      icon: tileIcon('Its'),
+    }), { required: true, minItems: 1, origin: 'external' }),
+  },
+  behavior: {},
+  presentation: presentation('seat-allocation'),
+  copyExtra: { ...HEADER, unitHint: { default: '' } },
+  system: ['ship'],
+};
+
+const carousel: NewManifest = {
+  family: 'new',
+  component: 'carousel',
+  name: 'Carousel',
+  kind: 'interactive',
+  purpose: 'A short guided tour, one slide at a time, ending in a done panel.',
+  signals: ['tour', 'walkthrough', 'introduce', 'onboarding tour', "what's new", 'highlights', 'slides', 'guide me', 'show me around'],
+  useWhen: ['Introducing a product, a feature or a permission in a few steps the person reads in order.'],
+  avoidWhen: [`More than ${MAX_SLIDES} steps — a tour that long is a manual.`, 'The person must do something at each step — use checklist.', 'A list to read in any order — use expandable-feed.'],
+  related: [
+    { component: 'checklist', distinction: 'A checklist is work to do; a tour is something to read.' },
+    { component: 'completion', distinction: 'Completion ends a flow; a tour explains one.' },
+  ],
+  states: [
+    { state: 'default', description: 'The first slide.' },
+    { state: 'middle', description: 'A slide in the middle.' },
+    { state: 'last', description: 'The last slide, with the final button.' },
+    { state: 'done', description: 'Finished, with Replay.' },
+    ...LOAD_STATES,
+  ],
+  actions: [{ id: 'next', description: 'Next slide.' }, { id: 'previous', description: 'Previous slide.' }, { id: 'skip', description: 'Skip the tour (if skippable).' }, { id: 'finish', description: 'Finish the tour.' }],
+  events: [{ event: 'finished', description: 'The tour ended.', data: '{ how: "done" | "skipped" }' }],
+  requiresInput: false,
+  rules: [`At most ${MAX_SLIDES} slides.`],
+  askFor: {},
+  data: {
+    slides: list('The slides, in order.', obj('A slide.', {
+      title: text('Its heading.', { required: true }),
+      body: text('Its text.', { required: true }),
+      type: tileType('Its'),
+      icon: tileIcon('Its'),
+    }), { required: true, minItems: 1, maxItems: MAX_SLIDES, origin: 'invent' }),
+  },
+  behavior: {
+    skippable: bool('Offer "Skip tour".', { default: base('carousel').skippable, owners: ['agent', 'builder', 'developer'] }),
+  },
+  presentation: presentation('carousel'),
+  copyExtra: HEADER,
+  system: [],
+};
+
+const completion: NewManifest = {
+  family: 'new',
+  component: 'completion',
+  name: 'Completion',
+  kind: 'output',
+  purpose: 'The end-of-flow success screen: what was set up, three stats, and what was skipped for later.',
+  signals: ['done', 'all set', 'finished', 'setup complete', 'ready', "you're ready", 'summary of setup', 'wrap up', 'success'],
+  useWhen: ['A multi-step setup, import or configuration has finished, fully or partly, and the person should see what happened.'],
+  avoidWhen: ['Proof of a payment — use receipt-printer.', 'Work that is still ongoing — use checklist.'],
+  related: [
+    { component: 'receipt-printer', distinction: 'A receipt proves a payment; Completion confirms a finished process.' },
+    { component: 'checklist', distinction: 'A checklist tracks ongoing work; Completion summarises finished work.' },
+  ],
+  states: [
+    { state: 'success', description: 'Everything was set up.' },
+    { state: 'partial', description: 'Some things were skipped — listed for later (when data.skipped has entries).' },
+    ...LOAD_STATES,
+  ],
+  actions: [{ id: 'continue', description: 'Go on.' }, { id: 'finishLater', description: 'Come back to what was skipped (partial only).' }],
+  events: [
+    { event: 'continued', description: 'The person continued.', data: '{}' },
+    { event: 'finishLater', description: 'The person chose to finish later.', data: '{}' },
+  ],
+  requiresInput: false,
+  rules: ['Exactly three stats.', 'With skipped entries the screen is the partial one, with "Finish later".'],
+  askFor: {},
+  data: {
+    items: list('What was set up.', text('A thing set up.'), { required: true, origin: 'derived' }),
+    stats: list('Three figures.', obj('A stat.', {
+      label: text('What it counts.', { required: true }),
+      value: text('The figure, as shown.', { required: true }),
+      unit: text('After the figure.', { default: '' }),
+    }), { required: true, minItems: 3, maxItems: 3, origin: 'derived' }),
+    skipped: list('What was skipped for later.', text('A skipped thing.'), { default: [], origin: 'derived' }),
+  },
+  behavior: {},
+  presentation: presentation('completion'),
+  copyExtra: HEADER,
+  system: ['partialStats', 'successStats', 'partialItems', 'successItems', 'demoSkipped', 'ship'],
+};
+
+export const NEW_MANIFESTS: readonly NewManifest[] = [receiptPrinter, budgetTracker, activityHeatmap, criteriaSpider, expandableFeed, fallback, seatAllocation, carousel, completion];

package/src/agent/result.ts

@@ -0,0 +1,56 @@
+import { RESULT_SCHEMA, type RenderResult } from './types';
+
+/**
+ * **`result/1`** — a component's callbacks, as data. Each approved component's callbacks map to named
+ * events (`printed`, `saved`, `finished`…) whose `data` is plain JSON: no functions, no React events.
+ * The renderer (`AgentComponent`) uses these; a host can too, if it renders the components itself.
+ */
+
+type Mapper = (...args: never[]) => Record<string, unknown>;
+/** For each component: its callback prop → [event, the data it carries]. The capability's `events` describe the same. */
+export const RESULT_EVENTS: Record<string, Record<string, [string, Mapper]>> = {
+  'receipt-printer': {
+    onPrinted: ['printed', ((receipt: unknown, lines: unknown) => ({ receipt, lines })) as Mapper],
+    onReset: ['reset', (() => ({})) as Mapper],
+    onFieldsChange: ['fieldsChanged', ((fields: unknown) => ({ fields })) as Mapper],
+  },
+  'budget-tracker': {
+    onPeriodChange: ['periodChanged', ((period: string) => ({ period })) as Mapper],
+    onOpen: ['categoryOpened', ((id: string) => ({ id })) as Mapper],
+  },
+  'activity-heatmap': {
+    onDaySelect: ['daySelected', ((date: string | null) => ({ date })) as Mapper],
+    onOpen: ['opened', ((date: string) => ({ date })) as Mapper],
+  },
+  'criteria-spider': {
+    onItemChange: ['itemChanged', ((id: string) => ({ id })) as Mapper],
+    onCompare: ['compared', ((id: string | null) => ({ id })) as Mapper],
+  },
+  'expandable-feed': {
+    onOpenChange: ['openChanged', ((id: string | null) => ({ id })) as Mapper],
+    onFeedback: ['feedback', ((id: string, pressed: boolean) => ({ id, pressed })) as Mapper],
+  },
+  fallback: { onCopy: ['copied', ((text: string) => ({ text })) as Mapper] },
+  'seat-allocation': {
+    onChange: ['changed', ((groups: unknown) => ({ groups })) as Mapper],
+    onSave: ['saved', ((groups: unknown) => ({ groups })) as Mapper],
+  },
+  carousel: { onFinish: ['finished', ((how: string) => ({ how })) as Mapper] },
+  completion: {
+    onContinue: ['continued', (() => ({})) as Mapper],
+    onFinishLater: ['finishLater', (() => ({})) as Mapper],
+  },
+  directory: { onSelect: ['selected', ((id: string) => ({ id })) as Mapper] },
+  checklist: { onChange: ['changed', ((checklist: unknown, change: unknown) => ({ checklist, change })) as Mapper] },
+  'threshold-flow': {
+    onChange: ['changed', ((stages: unknown) => ({ stages })) as Mapper],
+    onActivate: ['activated', ((stages: unknown) => ({ stages })) as Mapper],
+  },
+};
+
+/** Plain JSON only — what survives a wire. */
+const plain = (v: unknown): Record<string, unknown> => JSON.parse(JSON.stringify(v ?? {})) as Record<string, unknown>;
+
+export function makeResult(component: string, instanceId: string, sequence: number, event: string, data: Record<string, unknown>): RenderResult {
+  return { schema: RESULT_SCHEMA, component, instanceId, sequence, event, data: plain(data) };
+}

package/src/agent/search/document.ts

@@ -0,0 +1,46 @@
+import type { AgentCapability, FieldSpec } from '../types';
+import type { FieldType, SearchDocument } from './types';
+
+/**
+ * **A component's search document, derived from its capability.** It says what problem the
+ * component solves — purpose, when to use it, its selection signals, its case studies' scenarios,
+ * what a person can do with it, what it shows and what it reports — and, separately, what it is not
+ * for (`avoidWhen`). Nothing is written for search alone, so a new approved component is searchable
+ * the moment it has a capability. No source, no implementation, no runtime values.
+ */
+
+/** "…statement over time — use budget-tracker or a list." → "…statement over time": the pointer to another component is advice, not meaning. */
+function ownMeaning(text: string, ids: readonly string[]): string {
+  let t = text.replace(/\s[—–-]+\s*use\s.*$/i, '').replace(/:\s*use\s.*$/i, '');
+  for (const id of ids) t = t.split(id).join(' ');
+  return t.replace(/\s+/g, ' ').trim();
+}
+
+const describeData = (key: string, spec: FieldSpec): string => {
+  const words = key.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
+  return `${words}: ${spec.description}`;
+};
+
+export function searchDocumentOf(c: AgentCapability, order: number, allIds: readonly string[]): SearchDocument {
+  const positive: { type: FieldType; text: string }[] = [];
+  const add = (type: FieldType, text: string | undefined) => { const t = text && ownMeaning(text, allIds); if (t) positive.push({ type, text: t }); };
+  add('name', c.name);
+  add('purpose', c.purpose);
+  c.signals.forEach(s => add('signal', s));
+  c.useWhen.forEach(s => add('useWhen', s));
+  c.presets.forEach(p => add('scenario', `${p.title}. ${p.scenario}`));
+  c.actions.forEach(a => add('action', a.description));
+  c.states.forEach(s => add('state', s.description));
+  c.events.forEach(e => add('event', e.description));
+  for (const [k, spec] of Object.entries(c.data)) add('data', describeData(k, spec));
+  const negative = c.avoidWhen.map(t => ownMeaning(t, allIds)).filter(Boolean).map(text => ({ text }));
+  return { component: c.component, order, positive, negative };
+}
+
+/** FNV-1a over the documents: the catalogue's search version. Any change to what search reads changes it. */
+export function versionOf(value: unknown): string {
+  const s = JSON.stringify(value);
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193); }
+  return (h >>> 0).toString(16).padStart(8, '0');
+}