@stina/extension-api 0.52.0 → 0.56.0

package/dist/{types.tools-XpXCoPrJ.d.ts → types.tools-BL9WPsi_.d.ts}

@@ -430,6 +430,290 @@ interface ListProps extends ExtensionComponentData {
     /** Child components to render as list items. Supports iteration. */
     children: ExtensionComponentChildren;
 }
+/**
+ * A sky the DSL knows how to draw.
+ *
+ * A closed list rather than free text: the drawing has to be chosen from it, and
+ * an unrecognised string would leave a hole where the icon goes. Providers name
+ * conditions in wildly different vocabularies, so the caller maps theirs onto
+ * this list and passes the provider's own words as `conditionLabel` — the enum
+ * picks the picture, the label is what gets read.
+ */
+type WeatherCondition = 'clear' | 'partly-cloudy' | 'cloudy' | 'overcast' | 'fog' | 'light-rain' | 'rain' | 'heavy-rain' | 'sleet' | 'light-snow' | 'snow' | 'heavy-snow' | 'thunderstorm' | 'hail' | 'windy';
+/** Wind, as shown by the weather components. */
+interface WeatherWind {
+    speed: number;
+    /** Written after the speed. Defaults to `m/s`. */
+    unit?: string;
+    /** Compass direction as the caller words it, e.g. `NV` or `sydväst`. */
+    direction?: string;
+    /** Gust speed, in the same unit. Shown next to the sustained speed when present. */
+    gust?: number;
+}
+/** The extension API properties for the WeatherNow component. */
+interface WeatherNowProps extends ExtensionComponentData {
+    component: 'WeatherNow';
+    /** Where the reading is from. */
+    place: string;
+    condition: WeatherCondition;
+    /** The condition in the user's own language. Falls back to the host's wording for `condition`. */
+    conditionLabel?: string;
+    temperature: number;
+    /** What it feels like, when that differs enough to be worth saying. */
+    feelsLike?: number;
+    /** Written after every temperature. Defaults to `°`. */
+    unit?: string;
+    wind?: WeatherWind;
+    /** Draws the night variant of the icon. Only affects conditions that have one. */
+    night?: boolean;
+    /** One line of context under the numbers, e.g. "Regn från tretiden". */
+    summary?: string;
+}
+/**
+ * One step of a forecast.
+ *
+ * Deliberately the same shape whether the steps are hours or days — the only
+ * difference is what `label` says and whether there are two temperatures. A
+ * separate hourly component would have been the same component twice.
+ */
+interface WeatherForecastStep {
+    /** Short: `14`, `Tors`, `Nu`. */
+    label: string;
+    condition: WeatherCondition;
+    conditionLabel?: string;
+    /** The warmer of the two, or the only one for a single-temperature step. */
+    high: number;
+    /** The colder one. Absent when the step has a single temperature. */
+    low?: number;
+    night?: boolean;
+    /** Chance of precipitation as a percentage, 0–100. */
+    precipitation?: number;
+    /**
+     * The step the reader is at — this hour, today. Drawn larger than its
+     * neighbours, so the eye lands on it before reading the row.
+     *
+     * Same word as `TimelineEntry.current`, and the same meaning: mark one, and
+     * only one. Marking several is marking none.
+     */
+    current?: boolean;
+}
+/** The extension API properties for the WeatherForecast component. */
+interface WeatherForecastProps extends ExtensionComponentData {
+    component: 'WeatherForecast';
+    /** Heading above the row, e.g. "Kommande timmar". */
+    title?: string;
+    /** Icon shown to the left of the title. */
+    icon?: HugeIconName;
+    /** Written after every temperature. Defaults to `°`. */
+    unit?: string;
+    steps: WeatherForecastStep[];
+}
+/** How a chart draws its series. */
+type ChartKind = 'line' | 'bar' | 'area';
+/**
+ * One series of a chart.
+ *
+ * `points` lines up with the chart's `labels` by position. A `null` is a gap in
+ * the data and is drawn as one — a missing reading joined up as if it were a
+ * value is a lie the chart would tell on the caller's behalf.
+ */
+interface ChartSeries {
+    /** Named in the legend. Required in practice once there is more than one series. */
+    name?: string;
+    points: Array<number | null>;
+}
+/**
+ * The extension API properties for the Chart component.
+ *
+ * There is no colour option and no second axis, on purpose. Colours come from
+ * the host's categorical palette in slot order, so the same series keeps the
+ * same colour everywhere and the whole set stays legible to colour-blind
+ * readers. Two measurements of different magnitude are two charts.
+ */
+interface ChartProps extends ExtensionComponentData {
+    component: 'Chart';
+    /** Defaults to `line`. */
+    chart?: ChartKind;
+    /** At most eight. Past that the ninth would need a colour the palette does not have. */
+    series: ChartSeries[];
+    /** One per point, along the horizontal axis. */
+    labels?: string[];
+    /** Heading above the plot. With a single series this is what names it, so no legend is drawn. */
+    title?: string;
+    /** Icon shown to the left of the title. */
+    icon?: HugeIconName;
+    /** Written after every value, e.g. `°`, ` mm`, ` kr`. */
+    unit?: string;
+    /**
+     * Whether the value axis must include zero. Defaults to true for `bar` and
+     * `area`, where the fill's height is the reading, and false for `line`, where
+     * forcing zero can flatten the shape the chart exists to show.
+     */
+    zeroBaseline?: boolean;
+    /** Plot height in rem. Defaults to 9. */
+    height?: number;
+}
+/** Which way a stat tile's trend points. */
+type StatTrend = 'up' | 'down' | 'flat';
+/**
+ * The extension API properties for the StatTile component.
+ *
+ * For the single number that does not need a plot. A chart of one value is a
+ * chart that spends a lot of space saying very little.
+ */
+interface StatTileProps extends ExtensionComponentData {
+    component: 'StatTile';
+    /** What the number is, e.g. "Förbrukning i går". */
+    label: string;
+    value: string | number;
+    /** Written after the value in smaller type, e.g. `kWh`. */
+    unit?: string;
+    /** One quiet line under the number. */
+    caption?: string;
+    icon?: HugeIconName;
+    /** `flat` draws no arrow. */
+    trend?: StatTrend;
+    /** The change in words, e.g. "+12 % mot förra veckan". Shown beside the arrow. */
+    trendLabel?: string;
+    /**
+     * Whether up is the good direction. Defaults to true. Colours the trend;
+     * the arrow and the label carry the same meaning without it.
+     */
+    trendIsGood?: boolean;
+}
+/** One row of a KeyValueList. */
+interface KeyValueRow {
+    label: string;
+    value: string;
+    icon?: HugeIconName;
+}
+/**
+ * The extension API properties for the KeyValueList component.
+ *
+ * Facts in two columns, aligned. What a stack of `HorizontalStack`s was always
+ * being used for, without each caller having to get the alignment right.
+ */
+interface KeyValueListProps extends ExtensionComponentData {
+    component: 'KeyValueList';
+    rows: KeyValueRow[];
+}
+/** How much a timeline entry stands out. */
+type TimelineVariant = 'default' | 'accent' | 'success' | 'warning' | 'danger';
+/**
+ * One entry on a timeline.
+ *
+ * `time` is a string, not a timestamp, because the component draws order rather
+ * than duration: entries sit evenly on the rail whether they are minutes or
+ * decades apart. That is what makes the same component work for today's
+ * calendar and for a project's milestones, and it means the caller writes the
+ * time the way it should be read — `09:00`, `Tors 14 mar`, `2019`.
+ */
+interface TimelineEntry {
+    /** When it happens, worded as it should be read. */
+    time: string;
+    title: string;
+    /** A line under the title. */
+    description?: string;
+    icon?: HugeIconName;
+    /** How long it lasts, in the caller's own words: `1 h`, `3 dagar`. */
+    duration?: string;
+    /** Trailing badge, e.g. a place or a category. */
+    badge?: string;
+    /** Marks the entry the reader is at. Drawn with a filled marker and a heavier rule. */
+    current?: boolean;
+    /** Already behind us. Drawn recessive, so what is left to come reads first. */
+    past?: boolean;
+    variant?: TimelineVariant;
+}
+/**
+ * The extension API properties for the Timeline component.
+ *
+ * A vertical rail with one marker per entry. For a day's events, or for the
+ * order things happened in over a longer stretch.
+ */
+interface TimelineProps extends ExtensionComponentData {
+    component: 'Timeline';
+    /** Heading above the rail, e.g. "I dag". */
+    title?: string;
+    /** Icon shown to the left of the title. */
+    icon?: HugeIconName;
+    entries: TimelineEntry[];
+}
+/** How much a note stands out. */
+type NoteVariant = 'default' | 'accent' | 'success' | 'warning' | 'danger';
+/**
+ * The extension API properties for the Note component.
+ *
+ * A titled block of prose: a heading, markdown, and a quiet line at the bottom.
+ * For the answer that *is* text but wants a shape — one of five news summaries,
+ * one of three things worth doing this weekend — where a single long reply would
+ * run them all together and the reader would lose which sentence belonged to
+ * which item.
+ *
+ * The body is markdown rather than components because prose is what it is for.
+ * A note that wants a chart in it is a `Frame` with a `Note` and a `Chart`
+ * inside; keeping those separate is what stops this from becoming a second,
+ * worse layout system.
+ */
+interface NoteProps extends ExtensionComponentData {
+    component: 'Note';
+    title?: string;
+    /** Icon shown to the left of the title. */
+    icon?: HugeIconName;
+    /** Trailing badge next to the title: a source, a category, a time. */
+    badge?: string;
+    /** The body, as markdown. */
+    content: string;
+    /** One quiet line at the bottom: where it came from, when, or a caveat. */
+    footer?: string;
+    /** Colours the rail down the left edge. Defaults to none. */
+    variant?: NoteVariant;
+}
+/** Whether an event is going ahead. */
+type CalendarEventStatus = 'confirmed' | 'tentative' | 'cancelled';
+/**
+ * The extension API properties for the CalendarEvent component.
+ *
+ * One event, shown properly. It is the thing Stina most often has to say
+ * something *about* — a meeting starting shortly, a booking she is reminding you
+ * of — and a sentence carrying a time, a place and four names is a sentence
+ * nobody reads to the end.
+ *
+ * For a whole day, use `Timeline`. This is the single event that has the floor.
+ *
+ * `start` and `end` are timestamps rather than the worded strings `Timeline`
+ * takes, and that is the one place in the DSL where live computation is right:
+ * the card is *about* a moment, so the host works out "om tolv minuter" and
+ * "pågår nu" and keeps them true. A caller who wrote those as text would have
+ * written a card that lies the moment it is scrolled back to.
+ */
+interface CalendarEventProps extends ExtensionComponentData {
+    component: 'CalendarEvent';
+    title: string;
+    /** ISO 8601, with an offset. The host formats it in the reader's own locale. */
+    start: string;
+    /** ISO 8601, with an offset. Absent for an event with no stated end. */
+    end?: string;
+    /** Draws a day rather than a clock time. */
+    allDay?: boolean;
+    location?: string;
+    /** Who called it. */
+    organizer?: string;
+    /** Names as the calendar has them. Shown in full up to a few, then counted. */
+    attendees?: string[];
+    /** Which calendar it sits in. Shown as a badge. */
+    calendar?: string;
+    /** Defaults to `confirmed`. */
+    status?: CalendarEventStatus;
+    /**
+     * How it repeats, in words: `Varje tisdag`. The recurrence rule itself is not
+     * something this component parses — the caller already knows what it means,
+     * and a component guessing at an RRULE would get the exceptions wrong.
+     */
+    recurrence?: string;
+    /** One short line of context. */
+    notes?: string;
+}
 
 /**
  * What an extension can contribute to Stina
@@ -1551,7 +1835,21 @@ interface UserProfile {
  * User API for profile access
  */
 interface UserAPI {
-    getProfile(): Promise<UserProfile>;
+    /**
+     * Read a user's profile, including the timezone their clock times are written in.
+     *
+     * Pass the id of the user this work belongs to — `ctx.userId` in a background task,
+     * `context.userId` in a tool call, the fired job's `userId` in a scheduler callback.
+     * A host serving more than one user cannot guess which profile was meant, and answers
+     * with an empty profile when the id is left out.
+     *
+     * This matters most for `timezone`. An extension that turns a wall-clock time into an
+     * instant without it falls back to the machine's timezone, which on a server is UTC,
+     * and schedules the user's 11:30 for 11:30 UTC.
+     *
+     * @param userId The user whose profile to read. Optional only for single-user hosts.
+     */
+    getProfile(userId?: string): Promise<UserProfile>;
     listIds(): Promise<string[]>;
 }
 /**
@@ -1932,6 +2230,20 @@ interface ToolResult {
     message?: string;
     /** Error message if failed */
     error?: string;
+    /**
+     * Something to show the user that is not text.
+     *
+     * A component from the chat card profile — a chart, a weather reading, a
+     * timeline. It is rendered in the conversation where the tool ran, and it is
+     * *not* part of what goes back to the model: the model already knows what it
+     * asked to be shown, and sending the drawing back would spend the tokens
+     * twice and invite it to summarise its own picture.
+     *
+     * Validate with `validateChatCard` before returning one. A card that fails the
+     * profile is dropped by the host rather than half-rendered, so a tool that
+     * skips the check finds out from the user, which is the wrong end.
+     */
+    display?: ExtensionComponentData;
 }
 /**
  * Action implementation for UI interactions.
@@ -1959,4 +2271,4 @@ interface ActionResult {
     error?: string;
 }
 
-export { type BackgroundTaskHealth as $, type ActionResult as A, type EventsAPI as B, type ChatMessage as C, type Disposable as D, type ExtensionContributions as E, type SchedulerAPI as F, type GetModelsOptions as G, type HugeIconName as H, type SchedulerJobRequest as I, type SchedulerSchedule as J, type UserProfile as K, type LocalizedString as L, type ModelInfo as M, type NetworkAPI as N, type ChatAPI as O, type PanelDefinition as P, type ChatInstructionMessage as Q, type ConversationPresentation as R, type SchedulerFirePayload as S, type ToolResult as T, type UserAPI as U, type VoiceSessionOptions as V, type LogAPI as W, type BackgroundWorkersAPI as X, type BackgroundTaskConfig as Y, type BackgroundTaskCallback as Z, type BackgroundTaskContext as _, type ChatOptions as a, type BackgroundRestartPolicy as a0, type Query as a1, type QueryOptions as a2, type StorageAPI as a3, type SecretsAPI as a4, type StorageCollectionConfig as a5, type StorageContributions as a6, type AIProvider as a7, type ModelCapabilities as a8, type ChatImage as a9, type HorizontalStackProps as aA, type GridProps as aB, type DividerProps as aC, type IconProps as aD, type IconButtonType as aE, type IconButtonProps as aF, type PanelAction as aG, type PanelProps as aH, type ToggleProps as aI, type CollapsibleProps as aJ, type FrameVariant as aK, type FrameProps as aL, type ListProps as aM, type PillVariant as aN, type PillProps as aO, type CheckboxProps as aP, type MarkdownProps as aQ, type TextPreviewProps as aR, type ModalProps as aS, type ConditionalGroupProps as aT, type ExecutionContext as aU, type ToolCall as aa, type VoiceTransportRequest as ab, type Tool as ac, type Action as ad, type ExtensionModule as ae, type AllowedCSSProperty as af, type ExtensionComponentStyle as ag, type ExtensionComponentData as ah, type ExtensionComponentIterator as ai, type ExtensionComponentChildren as aj, type ExtensionActionCall as ak, type ExtensionActionRef as al, type ExtensionDataSource as am, type ExtensionPanelDefinition as an, type HeaderProps as ao, type LabelProps as ap, type ParagraphProps as aq, type ButtonProps as ar, type TextInputProps as as, type PasswordInputProps as at, type NumberInputProps as au, type TextAreaProps as av, type DateTimeInputProps as aw, type SelectProps as ax, type IconPickerProps as ay, type VerticalStackProps as az, type StreamEvent as b, type VoiceSessionDescriptor as c, type ToolSettingsViewDefinition as d, type ToolSettingsView as e, type ToolSettingsListView as f, type ToolSettingsListMapping as g, type ToolSettingsComponentView as h, type ToolSettingsActionDataSource as i, type PanelView as j, type PanelComponentView as k, type PanelActionDataSource as l, type PanelUnknownView as m, type ProviderDefinition as n, type ProviderConfigView as o, type PromptContribution as p, type PromptSection as q, resolveLocalizedString as r, type ToolDefinition as s, type ToolConfirmationConfig as t, type CommandDefinition as u, type ExtensionContext as v, type SettingsAPI as w, type ProvidersAPI as x, type ToolsAPI as y, type ActionsAPI as z };
+export { type BackgroundTaskHealth as $, type ActionResult as A, type EventsAPI as B, type ChatMessage as C, type Disposable as D, type ExtensionContributions as E, type SchedulerAPI as F, type GetModelsOptions as G, type HugeIconName as H, type SchedulerJobRequest as I, type SchedulerSchedule as J, type UserProfile as K, type LocalizedString as L, type ModelInfo as M, type NetworkAPI as N, type ChatAPI as O, type PanelDefinition as P, type ChatInstructionMessage as Q, type ConversationPresentation as R, type SchedulerFirePayload as S, type ToolResult as T, type UserAPI as U, type VoiceSessionOptions as V, type LogAPI as W, type BackgroundWorkersAPI as X, type BackgroundTaskConfig as Y, type BackgroundTaskCallback as Z, type BackgroundTaskContext as _, type ChatOptions as a, type ChartProps as a$, type BackgroundRestartPolicy as a0, type Query as a1, type QueryOptions as a2, type StorageAPI as a3, type SecretsAPI as a4, type StorageCollectionConfig as a5, type StorageContributions as a6, type AIProvider as a7, type ModelCapabilities as a8, type ChatImage as a9, type HorizontalStackProps as aA, type GridProps as aB, type DividerProps as aC, type IconProps as aD, type IconButtonType as aE, type IconButtonProps as aF, type PanelAction as aG, type PanelProps as aH, type ToggleProps as aI, type CollapsibleProps as aJ, type FrameVariant as aK, type FrameProps as aL, type ListProps as aM, type PillVariant as aN, type PillProps as aO, type CheckboxProps as aP, type MarkdownProps as aQ, type TextPreviewProps as aR, type ModalProps as aS, type ConditionalGroupProps as aT, type WeatherCondition as aU, type WeatherWind as aV, type WeatherNowProps as aW, type WeatherForecastStep as aX, type WeatherForecastProps as aY, type ChartKind as aZ, type ChartSeries as a_, type ToolCall as aa, type VoiceTransportRequest as ab, type Tool as ac, type Action as ad, type ExtensionModule as ae, type AllowedCSSProperty as af, type ExtensionComponentStyle as ag, type ExtensionComponentData as ah, type ExtensionComponentIterator as ai, type ExtensionComponentChildren as aj, type ExtensionActionCall as ak, type ExtensionActionRef as al, type ExtensionDataSource as am, type ExtensionPanelDefinition as an, type HeaderProps as ao, type LabelProps as ap, type ParagraphProps as aq, type ButtonProps as ar, type TextInputProps as as, type PasswordInputProps as at, type NumberInputProps as au, type TextAreaProps as av, type DateTimeInputProps as aw, type SelectProps as ax, type IconPickerProps as ay, type VerticalStackProps as az, type StreamEvent as b, type StatTrend as b0, type StatTileProps as b1, type KeyValueRow as b2, type KeyValueListProps as b3, type TimelineVariant as b4, type TimelineEntry as b5, type TimelineProps as b6, type NoteVariant as b7, type NoteProps as b8, type CalendarEventStatus as b9, type CalendarEventProps as ba, type ExecutionContext as bb, type VoiceSessionDescriptor as c, type ToolSettingsViewDefinition as d, type ToolSettingsView as e, type ToolSettingsListView as f, type ToolSettingsListMapping as g, type ToolSettingsComponentView as h, type ToolSettingsActionDataSource as i, type PanelView as j, type PanelComponentView as k, type PanelActionDataSource as l, type PanelUnknownView as m, type ProviderDefinition as n, type ProviderConfigView as o, type PromptContribution as p, type PromptSection as q, resolveLocalizedString as r, type ToolDefinition as s, type ToolConfirmationConfig as t, type CommandDefinition as u, type ExtensionContext as v, type SettingsAPI as w, type ProvidersAPI as x, type ToolsAPI as y, type ActionsAPI as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stina/extension-api",
-  "version": "0.52.0",
+  "version": "0.56.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/index.ts

@@ -192,4 +192,24 @@ export type {
   TextPreviewProps,
   ModalProps,
   ConditionalGroupProps,
+  // Purpose-built display components
+  WeatherCondition,
+  WeatherWind,
+  WeatherNowProps,
+  WeatherForecastStep,
+  WeatherForecastProps,
+  ChartKind,
+  ChartSeries,
+  ChartProps,
+  StatTrend,
+  StatTileProps,
+  KeyValueRow,
+  KeyValueListProps,
+  TimelineVariant,
+  TimelineEntry,
+  TimelineProps,
+  NoteVariant,
+  NoteProps,
+  CalendarEventStatus,
+  CalendarEventProps,
 } from './types.components.js'

package/src/runtime.ts

@@ -856,8 +856,8 @@ function buildContext(
   // Add user profile API if permitted
   if (hasPermission('user.profile.read')) {
     const userApi: UserAPI = {
-      async getProfile(): Promise<UserProfile> {
-        return sendRequest<UserProfile>('user.getProfile', {})
+      async getProfile(userId?: string): Promise<UserProfile> {
+        return sendRequest<UserProfile>('user.getProfile', userId ? { userId } : {})
       },
       async listIds(): Promise<string[]> {
         return sendRequest<string[]>('user.listIds', {})

package/src/schemas/card.schema.test.ts

@@ -0,0 +1,276 @@
+import { describe, it, expect } from 'vitest'
+import type { ChatCardComponent } from './card.schema.js'
+import { CHAT_CARD_COMPONENTS, describeChatCardProfile, validateChatCard } from './card.schema.js'
+
+describe('validateChatCard', () => {
+  it('accepts a chart written the way the profile describes it', () => {
+    const result = validateChatCard({
+      component: 'Chart',
+      chart: 'line',
+      title: 'Temperatur',
+      unit: '°',
+      labels: ['08', '09', '10'],
+      series: [{ name: 'Ute', points: [3, null, 7] }],
+    })
+
+    expect(result.ok).toBe(true)
+  })
+
+  it('accepts a note with markdown and a footer', () => {
+    const result = validateChatCard({
+      component: 'Note',
+      title: 'Strömavbrott i norra Uppsala',
+      icon: 'alert-02',
+      badge: 'Lokalt',
+      variant: 'warning',
+      content: 'Omkring **1 400** hushåll berörs.',
+      footer: 'UNT · för 40 minuter sedan',
+    })
+
+    expect(result.ok).toBe(true)
+  })
+
+  it('accepts an icon beside every heading that has one', () => {
+    for (const card of [
+      { component: 'Chart', icon: 'temperature', series: [{ points: [1] }] },
+      { component: 'Timeline', icon: 'calendar-03', entries: [{ time: '09:00', title: 'x' }] },
+      {
+        component: 'WeatherForecast',
+        icon: 'sun-cloud-02',
+        steps: [{ label: 'Nu', condition: 'clear', high: 4, current: true }],
+      },
+    ]) {
+      expect(validateChatCard(card).ok).toBe(true)
+    }
+  })
+
+  it('accepts a calendar event with timestamps', () => {
+    const result = validateChatCard({
+      component: 'CalendarEvent',
+      title: 'Avstämning med kunden',
+      start: '2026-09-01T14:00:00+02:00',
+      end: '2026-09-01T15:00:00+02:00',
+      location: 'Teams',
+      attendees: ['Anna', 'Jonte'],
+      calendar: 'Jobb',
+      status: 'tentative',
+    })
+
+    expect(result.ok).toBe(true)
+  })
+
+  it('refuses a calendar status outside the three that exist', () => {
+    const result = validateChatCard({
+      component: 'CalendarEvent',
+      title: 'Möte',
+      start: '2026-09-01T14:00:00+02:00',
+      status: 'maybe',
+    })
+
+    expect(result.ok).toBe(false)
+  })
+
+  it('accepts components nested through children', () => {
+    const result = validateChatCard({
+      component: 'VerticalStack',
+      children: [
+        { component: 'Header', level: 3, title: 'I dag' },
+        { component: 'Timeline', entries: [{ time: '09:00', title: 'Standup', current: true }] },
+      ],
+    })
+
+    expect(result.ok).toBe(true)
+  })
+
+  it('spaces every layout in the card, however deep it sits', () => {
+    const result = validateChatCard({
+      component: 'VerticalStack',
+      children: [
+        {
+          component: 'Grid',
+          columns: 2,
+          children: [
+            { component: 'HorizontalStack', children: [{ component: 'Label', text: 'A' }] },
+          ],
+        },
+      ],
+    })
+
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+
+    const grid = (result.card['children'] as ChatCardComponent[])[0]!
+    const row = (grid['children'] as ChatCardComponent[])[0]!
+
+    expect(result.card['gap']).toBe(0.75)
+    expect(grid['gap']).toBe(0.75)
+    expect(row['gap']).toBe(0.75)
+  })
+
+  it('refuses a gap the caller set itself', () => {
+    // The rhythm is the profile's. A number here is a model guessing at a unit
+    // it was never told — 14 meaning pixels renders as fourteen rem.
+    const result = validateChatCard({
+      component: 'VerticalStack',
+      gap: 14,
+      children: [{ component: 'Label', text: 'A' }],
+    })
+
+    expect(result.ok).toBe(false)
+  })
+
+  it('leaves gap out of the vocabulary the model is given', () => {
+    expect(describeChatCardProfile()).not.toContain('gap')
+  })
+
+  describe('refuses anything the user could act on', () => {
+    it.each([
+      ['Button', { component: 'Button', text: 'Spara', onClickAction: 'save' }],
+      ['TextInput', { component: 'TextInput', label: 'Namn' }],
+      ['Modal', { component: 'Modal', title: 'Hej' }],
+      ['IconButton', { component: 'IconButton', icon: 'x', tooltip: 't', onClickAction: 'a' }],
+    ])('%s', (_name, card) => {
+      // A card shows; it does not offer. Anything the user might want to do
+      // next, they ask for in words.
+      expect(validateChatCard(card).ok).toBe(false)
+    })
+  })
+
+  it('refuses an interactive prop smuggled onto a component that is allowed', () => {
+    const result = validateChatCard({ component: 'Label', text: 'Klicka', onClickAction: 'go' })
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.error).toContain('onClickAction')
+  })
+
+  it('refuses an iterator, since a card has no data source to expand', () => {
+    const result = validateChatCard({
+      component: 'VerticalStack',
+      children: { each: '$rows', as: 'row', items: [{ component: 'Label', text: '$row.name' }] },
+    })
+
+    expect(result.ok).toBe(false)
+  })
+
+  it('refuses a $-prefixed value rather than rendering it as nothing', () => {
+    // With no scope to resolve against, "$120" would silently disappear — which
+    // is precisely the failure a price is least able to survive.
+    const result = validateChatCard({ component: 'Label', text: '$120' })
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.error).toContain('$')
+  })
+
+  it('finds a $-prefixed value however deeply it is buried', () => {
+    const result = validateChatCard({
+      component: 'VerticalStack',
+      children: [
+        { component: 'KeyValueList', rows: [{ label: 'Pris', value: '$99' }] },
+      ],
+    })
+
+    expect(result.ok).toBe(false)
+  })
+
+  it('allows a dollar sign that is not leading', () => {
+    expect(validateChatCard({ component: 'Label', text: 'USD 120 ($)' }).ok).toBe(true)
+  })
+
+  it('refuses a chart whose series does not line up with its labels', () => {
+    // The chart would render, and every reading after the short series would
+    // sit under the wrong label — worse than not drawing it at all.
+    const result = validateChatCard({
+      component: 'Chart',
+      labels: ['mån', 'tis', 'ons'],
+      series: [{ points: [1, 2] }],
+    })
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.error).toContain('points')
+  })
+
+  it('accepts a chart whose gap is written out as null', () => {
+    expect(
+      validateChatCard({
+        component: 'Chart',
+        labels: ['mån', 'tis', 'ons'],
+        series: [{ points: [1, null, 3] }],
+      }).ok
+    ).toBe(true)
+  })
+
+  it('refuses a ninth series, which would need a colour the palette lacks', () => {
+    const nine = Array.from({ length: 9 }, () => ({ points: [1] }))
+
+    expect(validateChatCard({ component: 'Chart', series: nine }).ok).toBe(false)
+  })
+
+  it('refuses a card nested past the depth limit', () => {
+    let card: Record<string, unknown> = { component: 'Label', text: 'djupt' }
+    for (let i = 0; i < 10; i++) {
+      card = { component: 'VerticalStack', children: [card] }
+    }
+
+    const result = validateChatCard(card)
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.error).toContain('deep')
+  })
+
+  it('names the component in the error when the name itself is wrong', () => {
+    const result = validateChatCard({ component: 'BarGraph', series: [] })
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.error).toContain('component')
+  })
+
+  it('refuses a weather condition outside the list that has icons', () => {
+    const result = validateChatCard({
+      component: 'WeatherNow',
+      place: 'Uppsala',
+      condition: 'blizzard',
+      temperature: -4,
+    })
+
+    expect(result.ok).toBe(false)
+  })
+
+  it('rejects things that are not components at all', () => {
+    expect(validateChatCard(null).ok).toBe(false)
+    expect(validateChatCard('Chart').ok).toBe(false)
+    expect(validateChatCard([{ component: 'Label', text: 'x' }]).ok).toBe(false)
+  })
+})
+
+describe('describeChatCardProfile', () => {
+  it('documents every component the profile accepts', () => {
+    const described = describeChatCardProfile()
+
+    // The description is what a model reads as documentation. One that has
+    // drifted from the validator teaches it to write cards that are rejected.
+    for (const name of CHAT_CARD_COMPONENTS) {
+      expect(described).toContain(name)
+    }
+  })
+
+  it('names no component the profile would reject', () => {
+    const described = describeChatCardProfile()
+
+    expect(described).not.toContain('Button')
+    expect(described).not.toContain('TextInput')
+  })
+
+  it('spells out the enums a caller has to choose from', () => {
+    const described = describeChatCardProfile()
+
+    expect(described).toContain('line|bar|area')
+    expect(described).toContain('partly-cloudy')
+  })
+
+  it('marks which properties are required', () => {
+    const described = describeChatCardProfile()
+    const chart = described.split('\n').find((line) => line.startsWith('Chart'))!
+
+    expect(chart).toContain('series: ')
+    expect(chart).toContain('chart?: ')
+  })
+})