@stina/extension-api 0.51.0 → 0.53.1

package/src/schemas/card.schema.ts

@@ -0,0 +1,606 @@
+/**
+ * Chat Card Schema
+ *
+ * The subset of the component DSL that may appear *in a conversation*, as
+ * opposed to in a panel or a settings form.
+ *
+ * A panel is a place the user went to; a card arrives unbidden in the middle of
+ * a reply, and it is composed by a language model rather than by an extension
+ * author who tested it. So the card profile is narrower than the DSL in three
+ * ways, and each one is a rule about what a card *is*:
+ *
+ *  - **No interaction.** No buttons, no inputs, no modals. A card shows; it does
+ *    not offer. Everything the user might want to do next, they ask for in
+ *    words — which is the whole premise of talking to Stina rather than
+ *    operating her.
+ *  - **No data binding.** Panels pull from actions and iterate over the result;
+ *    a card is a finished value, written out in full. There is no scope for a
+ *    `$reference` to resolve against, so one is rejected rather than silently
+ *    rendered as nothing — see `findScopeReference`.
+ *  - **Strict props.** The panel schemas pass unknown properties through, on the
+ *    theory that a newer extension may know something this build does not. Cards
+ *    have no such future to protect: an unknown property here is a model that
+ *    invented one, and saying so is more useful than dropping it.
+ *
+ * The check runs where the card enters the system — in `core_show_card`, and in
+ * anything else that accepts a card from a tool — so a rejection comes back to
+ * the model as an error it can act on, in the same turn.
+ */
+
+import { z } from 'zod'
+import { ExtensionComponentStyleSchema } from './components.schema.js'
+import {
+  WeatherConditionSchema,
+  WeatherWindSchema,
+  ChartKindSchema,
+  StatTrendSchema,
+  TimelineVariantSchema,
+  NoteVariantSchema,
+  CalendarEventStatusSchema,
+  PillVariantSchema,
+  FrameVariantSchema,
+} from './components.schema.js'
+
+/** A card component and, recursively, everything it may contain. */
+export type ChatCardComponent = {
+  component: string
+  style?: Record<string, string>
+  [key: string]: unknown
+}
+
+const style = ExtensionComponentStyleSchema.optional()
+
+/**
+ * Children of a card component.
+ *
+ * An array only. The iterator form (`{ each, as, items }`) exists to expand a
+ * data source, and a card has none — the caller writes the rows out.
+ */
+const children: z.ZodType<ChatCardComponent[]> = z.lazy(() =>
+  z.array(ChatCardComponentSchema).max(40)
+)
+
+// -----------------------------------------------------------------------------
+// Layout
+// -----------------------------------------------------------------------------
+
+const VerticalStackCardSchema = z
+  .object({
+    component: z.literal('VerticalStack'),
+    gap: z.number().min(0).max(8).optional(),
+    children,
+    style,
+  })
+  .strict()
+
+const HorizontalStackCardSchema = z
+  .object({
+    component: z.literal('HorizontalStack'),
+    gap: z.number().min(0).max(8).optional(),
+    children,
+    style,
+  })
+  .strict()
+
+const GridCardSchema = z
+  .object({
+    component: z.literal('Grid'),
+    columns: z.number().min(1).max(6),
+    gap: z.number().min(0).max(8).optional(),
+    children,
+    style,
+  })
+  .strict()
+
+const FrameCardSchema = z
+  .object({
+    component: z.literal('Frame'),
+    // Only the string form: the components form of a title is for panels that
+    // put controls in their header, which a card has no business doing.
+    title: z.string().optional(),
+    collapsible: z.boolean().optional(),
+    defaultExpanded: z.boolean().optional(),
+    variant: FrameVariantSchema.optional(),
+    children,
+    style,
+  })
+  .strict()
+
+const ListCardSchema = z.object({ component: z.literal('List'), children, style }).strict()
+
+const DividerCardSchema = z.object({ component: z.literal('Divider'), style }).strict()
+
+// -----------------------------------------------------------------------------
+// Text
+// -----------------------------------------------------------------------------
+
+const HeaderCardSchema = z
+  .object({
+    component: z.literal('Header'),
+    level: z.number().min(1).max(6),
+    title: z.string(),
+    description: z.union([z.string(), z.array(z.string())]).optional(),
+    icon: z.string().optional(),
+    style,
+  })
+  .strict()
+
+const LabelCardSchema = z
+  .object({ component: z.literal('Label'), text: z.string(), style })
+  .strict()
+
+const ParagraphCardSchema = z
+  .object({ component: z.literal('Paragraph'), text: z.string(), style })
+  .strict()
+
+const MarkdownCardSchema = z
+  .object({ component: z.literal('Markdown'), content: z.string(), style })
+  .strict()
+
+// -----------------------------------------------------------------------------
+// Visual
+// -----------------------------------------------------------------------------
+
+const IconCardSchema = z
+  .object({
+    component: z.literal('Icon'),
+    name: z.string(),
+    title: z.string().optional(),
+    style,
+  })
+  .strict()
+
+const PillCardSchema = z
+  .object({
+    component: z.literal('Pill'),
+    text: z.string(),
+    icon: z.string().optional(),
+    variant: PillVariantSchema.optional(),
+    style,
+  })
+  .strict()
+
+// -----------------------------------------------------------------------------
+// Purpose-built
+// -----------------------------------------------------------------------------
+
+const WeatherNowCardSchema = z
+  .object({
+    component: z.literal('WeatherNow'),
+    place: z.string(),
+    condition: WeatherConditionSchema,
+    conditionLabel: z.string().optional(),
+    temperature: z.number(),
+    feelsLike: z.number().optional(),
+    unit: z.string().optional(),
+    wind: WeatherWindSchema.optional(),
+    night: z.boolean().optional(),
+    summary: z.string().optional(),
+    style,
+  })
+  .strict()
+
+const WeatherForecastCardSchema = z
+  .object({
+    component: z.literal('WeatherForecast'),
+    title: z.string().optional(),
+    icon: z.string().optional(),
+    unit: z.string().optional(),
+    steps: z
+      .array(
+        z
+          .object({
+            label: z.string(),
+            condition: WeatherConditionSchema,
+            conditionLabel: z.string().optional(),
+            high: z.number(),
+            low: z.number().optional(),
+            night: z.boolean().optional(),
+            precipitation: z.number().min(0).max(100).optional(),
+            current: z.boolean().optional(),
+          })
+          .strict()
+      )
+      .min(1)
+      .max(24),
+    style,
+  })
+  .strict()
+
+const ChartCardSchema = z
+  .object({
+    component: z.literal('Chart'),
+    chart: ChartKindSchema.optional(),
+    series: z
+      .array(
+        z
+          .object({
+            name: z.string().optional(),
+            points: z.array(z.number().nullable()).min(1).max(200),
+          })
+          .strict()
+      )
+      .min(1)
+      .max(8),
+    labels: z.array(z.string()).max(200).optional(),
+    title: z.string().optional(),
+    icon: z.string().optional(),
+    unit: z.string().optional(),
+    zeroBaseline: z.boolean().optional(),
+    height: z.number().min(4).max(24).optional(),
+    style,
+  })
+  .strict()
+
+const StatTileCardSchema = z
+  .object({
+    component: z.literal('StatTile'),
+    label: z.string(),
+    value: z.union([z.string(), z.number()]),
+    unit: z.string().optional(),
+    caption: z.string().optional(),
+    icon: z.string().optional(),
+    trend: StatTrendSchema.optional(),
+    trendLabel: z.string().optional(),
+    trendIsGood: z.boolean().optional(),
+    style,
+  })
+  .strict()
+
+const KeyValueListCardSchema = z
+  .object({
+    component: z.literal('KeyValueList'),
+    rows: z
+      .array(
+        z
+          .object({ label: z.string(), value: z.string(), icon: z.string().optional() })
+          .strict()
+      )
+      .min(1)
+      .max(40),
+    style,
+  })
+  .strict()
+
+const TimelineCardSchema = z
+  .object({
+    component: z.literal('Timeline'),
+    title: z.string().optional(),
+    icon: z.string().optional(),
+    entries: z
+      .array(
+        z
+          .object({
+            time: z.string(),
+            title: z.string(),
+            description: z.string().optional(),
+            icon: z.string().optional(),
+            duration: z.string().optional(),
+            badge: z.string().optional(),
+            current: z.boolean().optional(),
+            past: z.boolean().optional(),
+            variant: TimelineVariantSchema.optional(),
+          })
+          .strict()
+      )
+      .min(1)
+      .max(40),
+    style,
+  })
+  .strict()
+
+const NoteCardSchema = z
+  .object({
+    component: z.literal('Note'),
+    title: z.string().optional(),
+    icon: z.string().optional(),
+    badge: z.string().optional(),
+    content: z.string(),
+    footer: z.string().optional(),
+    variant: NoteVariantSchema.optional(),
+    style,
+  })
+  .strict()
+
+const CalendarEventCardSchema = z
+  .object({
+    component: z.literal('CalendarEvent'),
+    title: z.string(),
+    start: z.string(),
+    end: z.string().optional(),
+    allDay: z.boolean().optional(),
+    location: z.string().optional(),
+    organizer: z.string().optional(),
+    attendees: z.array(z.string()).max(40).optional(),
+    calendar: z.string().optional(),
+    status: CalendarEventStatusSchema.optional(),
+    recurrence: z.string().optional(),
+    notes: z.string().optional(),
+    style,
+  })
+  .strict()
+
+/** Every component name a card may use. Exported so the docs and the tool description stay in step. */
+export const CHAT_CARD_COMPONENTS = [
+  'VerticalStack',
+  'HorizontalStack',
+  'Grid',
+  'Frame',
+  'List',
+  'Divider',
+  'Header',
+  'Label',
+  'Paragraph',
+  'Markdown',
+  'Icon',
+  'Pill',
+  'WeatherNow',
+  'WeatherForecast',
+  'Chart',
+  'StatTile',
+  'KeyValueList',
+  'Timeline',
+  'Note',
+  'CalendarEvent',
+] as const
+
+/**
+ * Every component of the card profile, in the order they are documented.
+ *
+ * One list, used twice: it is what the union validates against and what
+ * `describeChatCardProfile` reads to write the vocabulary out. A component
+ * added here is legal *and* documented, in one edit — the alternative is a
+ * prose list that drifts, and a model reading a drifted list writes cards the
+ * validator then rejects.
+ */
+const CARD_MEMBERS = [
+  VerticalStackCardSchema,
+  HorizontalStackCardSchema,
+  GridCardSchema,
+  FrameCardSchema,
+  ListCardSchema,
+  DividerCardSchema,
+  HeaderCardSchema,
+  LabelCardSchema,
+  ParagraphCardSchema,
+  MarkdownCardSchema,
+  IconCardSchema,
+  PillCardSchema,
+  WeatherNowCardSchema,
+  WeatherForecastCardSchema,
+  ChartCardSchema,
+  StatTileCardSchema,
+  KeyValueListCardSchema,
+  TimelineCardSchema,
+  NoteCardSchema,
+  CalendarEventCardSchema,
+] as const
+
+/**
+ * One component of a chat card.
+ *
+ * Discriminated on `component` so a wrong property is reported against the
+ * component the author actually named, rather than as "no union member matched"
+ * across eighteen alternatives.
+ */
+export const ChatCardComponentSchema: z.ZodType<ChatCardComponent> = z.lazy(
+  () =>
+    z.discriminatedUnion(
+      'component',
+      CARD_MEMBERS as unknown as [(typeof CARD_MEMBERS)[number], (typeof CARD_MEMBERS)[number]]
+    ) as unknown as z.ZodType<ChatCardComponent>
+)
+
+/** The root of a card. Same profile as any component within it. */
+export const ChatCardSchema = ChatCardComponentSchema
+
+/** How deeply components may nest inside a card, root included. */
+const MAX_CARD_DEPTH = 8
+
+/**
+ * Rejects `$`-prefixed strings anywhere in the card.
+ *
+ * In a panel a leading `$` means "look this up in scope". A card has no scope,
+ * so the lookup would return nothing and the value would render as an empty
+ * space — a price written `$120` would simply disappear. Zod cannot see this,
+ * because to it the value is a perfectly good string; so it is checked
+ * separately, and the caller is told to write the value without the prefix.
+ *
+ * @returns The offending path, or null when the card is clean.
+ */
+function findScopeReference(value: unknown, path: string): string | null {
+  if (typeof value === 'string') {
+    return value.startsWith('$') ? path : null
+  }
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      const found = findScopeReference(value[i], `${path}[${i}]`)
+      if (found) return found
+    }
+    return null
+  }
+  if (value && typeof value === 'object') {
+    for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+      const found = findScopeReference(child, path ? `${path}.${key}` : key)
+      if (found) return found
+    }
+  }
+  return null
+}
+
+/** Depth of the deepest `children` chain, counting the root as 1. */
+function cardDepth(value: unknown): number {
+  if (!value || typeof value !== 'object') return 0
+  const kids = (value as { children?: unknown }).children
+  if (!Array.isArray(kids) || kids.length === 0) return 1
+  let deepest = 0
+  for (const child of kids) {
+    const depth = cardDepth(child)
+    if (depth > deepest) deepest = depth
+  }
+  return deepest + 1
+}
+
+/**
+ * Catch a chart whose series do not line up with its labels.
+ *
+ * Points map to labels by position, so a series one short does not fail to
+ * render — it renders the wrong reading against every label after the gap,
+ * which is worse than not drawing at all. Zod cannot express the relationship
+ * between two sibling arrays, so it is checked here.
+ *
+ * @returns A message naming the mismatch, or null when everything lines up.
+ */
+function findMisalignedChart(value: unknown): string | null {
+  if (!value || typeof value !== 'object') return null
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const found = findMisalignedChart(item)
+      if (found) return found
+    }
+    return null
+  }
+
+  const node = value as { component?: string; labels?: unknown; series?: unknown }
+  if (node.component === 'Chart' && Array.isArray(node.labels) && Array.isArray(node.series)) {
+    const expected = node.labels.length
+    for (let i = 0; i < node.series.length; i++) {
+      const points = (node.series[i] as { points?: unknown[] })?.points
+      if (Array.isArray(points) && points.length !== expected) {
+        return (
+          `Chart series ${i} has ${points.length} points but there are ${expected} labels. ` +
+          `Points line up with labels by position — use null for a reading you do not have.`
+        )
+      }
+    }
+  }
+
+  for (const child of Object.values(node as Record<string, unknown>)) {
+    const found = findMisalignedChart(child)
+    if (found) return found
+  }
+  return null
+}
+
+/** What came back from validating a card. */
+export type ChatCardValidation =
+  | { ok: true; card: ChatCardComponent }
+  | { ok: false; error: string }
+
+/**
+ * Validate a card against the chat profile.
+ *
+ * Returns a message rather than throwing, because the caller is almost always a
+ * tool that has to hand the reason back to the model — an exception would become
+ * "the tool failed", which is not something anyone can fix.
+ */
+export function validateChatCard(card: unknown): ChatCardValidation {
+  const parsed = ChatCardSchema.safeParse(card)
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0]
+    const where = issue?.path.length ? ` at ${issue.path.join('.')}` : ''
+    return { ok: false, error: `${issue?.message ?? 'Invalid card'}${where}` }
+  }
+
+  const depth = cardDepth(parsed.data)
+  if (depth > MAX_CARD_DEPTH) {
+    return {
+      ok: false,
+      error: `Card nests ${depth} levels deep; at most ${MAX_CARD_DEPTH} are allowed. Flatten it.`,
+    }
+  }
+
+  const misaligned = findMisalignedChart(parsed.data)
+  if (misaligned) {
+    return { ok: false, error: misaligned }
+  }
+
+  const reference = findScopeReference(parsed.data, '')
+  if (reference) {
+    return {
+      ok: false,
+      error:
+        `The value at ${reference} starts with "$", which the component system reads as a ` +
+        `reference to data that a card does not have, so it would render as nothing. ` +
+        `Write the value without the leading "$".`,
+    }
+  }
+
+  return { ok: true, card: parsed.data }
+}
+
+// -----------------------------------------------------------------------------
+// Describing the profile
+// -----------------------------------------------------------------------------
+
+/**
+ * Render one field's type compactly: `line|bar|area`, `number?`, `{a, b?}[]`.
+ *
+ * Enough for a reader to write a valid value, and short enough that the whole
+ * vocabulary fits in a tool description without crowding out everything else
+ * the model has to hold. Anything this cannot name falls back to the value's
+ * own kind rather than to nothing.
+ */
+function describeType(schema: z.ZodTypeAny): string {
+  const def = schema._def as { typeName?: string; [key: string]: unknown }
+
+  switch (def.typeName) {
+    case 'ZodOptional':
+    case 'ZodNullable':
+    case 'ZodDefault':
+      return describeType((schema as unknown as { unwrap(): z.ZodTypeAny }).unwrap())
+    case 'ZodLazy':
+      return 'component[]'
+    case 'ZodArray': {
+      const inner = describeType((def as { type: z.ZodTypeAny }).type)
+      return `${inner}[]`
+    }
+    case 'ZodObject': {
+      const shape = (schema as unknown as z.AnyZodObject).shape
+      const fields = Object.entries(shape).map(
+        ([key, value]) => `${key}${(value as z.ZodTypeAny).isOptional() ? '?' : ''}`
+      )
+      return `{${fields.join(', ')}}`
+    }
+    case 'ZodEnum':
+      return ((def as { values: readonly string[] }).values ?? []).join('|')
+    case 'ZodUnion':
+      return ((def as { options: z.ZodTypeAny[] }).options ?? []).map(describeType).join('|')
+    case 'ZodLiteral':
+      return String((def as { value: unknown }).value)
+    case 'ZodString':
+      return 'string'
+    case 'ZodNumber':
+      return 'number'
+    case 'ZodBoolean':
+      return 'boolean'
+    case 'ZodRecord':
+      return 'object'
+    default:
+      return 'value'
+  }
+}
+
+/**
+ * The card vocabulary, written out from the schemas themselves.
+ *
+ * This is what a language model is given as documentation, so it is generated
+ * rather than kept by hand: a description that has drifted from the validator
+ * teaches the model to write cards that are then rejected, and the model has no
+ * way to tell which of the two was wrong.
+ *
+ * `style` is left out of every line. It is legal everywhere and interesting
+ * almost nowhere — the components carry their own look, and a card that reaches
+ * for CSS is usually one that should have picked a different component.
+ */
+export function describeChatCardProfile(): string {
+  return CARD_MEMBERS.map((member) => {
+    const shape = (member as unknown as z.AnyZodObject).shape as Record<string, z.ZodTypeAny>
+    const name = (shape['component']!._def as { value: string }).value
+    const fields = Object.entries(shape)
+      .filter(([key]) => key !== 'component' && key !== 'style')
+      .map(([key, value]) => `${key}${value.isOptional() ? '?' : ''}: ${describeType(value)}`)
+    return fields.length ? `${name} — ${fields.join('; ')}` : name
+  }).join('\n')
+}