@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/flow/assistant/visual.ts

@@ -0,0 +1,205 @@
+// Assistant visual payloads → report blocks. The producer is a language model,
+// so the reader is lenient about key names (English, Portuguese and Spanish aliases)
+// and strict about what each type needs.
+
+import type { ReportSection, ReportSpec, ValueFormat } from '../report/ReportView'
+
+export type VisualType = 'figures' | 'bar' | 'line' | 'area' | 'table' | 'sections' | 'prose' | 'region-map' | 'flow'
+
+export interface VisualEnvelope {
+  type: VisualType
+  title: string
+  subtitle?: string
+  rows: Array<Record<string, unknown>>
+  xKey?: string
+  yKeys?: string[]
+  format?: ValueFormat
+  columnFormats?: Record<string, ValueFormat>
+  country?: string
+  graph?: Record<string, unknown>
+  body?: string
+}
+
+const TYPE_ALIASES: Record<string, VisualType> = {
+  figures: 'figures', figure: 'figures', kpi: 'figures', kpis: 'figures', numbers: 'figures', figuras: 'figures', numeros: 'figures', números: 'figures', indicadores: 'figures', cifras: 'figures',
+  bar: 'bar', bars: 'bar', column: 'bar', columns: 'bar', barra: 'bar', barras: 'bar', colunas: 'bar', columnas: 'bar',
+  line: 'line', lines: 'line', linha: 'line', linhas: 'line', linea: 'line', línea: 'line', lineas: 'line', líneas: 'line',
+  area: 'area', área: 'area',
+  table: 'table', tabela: 'table', tabla: 'table', grid: 'table',
+  sections: 'sections', secoes: 'sections', seções: 'sections', report: 'sections', relatorio: 'sections', relatório: 'sections', secciones: 'sections', informe: 'sections',
+  prose: 'prose', text: 'prose', texto: 'prose', md: 'prose', markdown: 'prose', note: 'prose', nota: 'prose', prosa: 'prose',
+  'region-map': 'region-map', region_map: 'region-map', regionmap: 'region-map', map: 'region-map', mapa: 'region-map', choropleth: 'region-map', regions: 'region-map', regioes: 'region-map', regiões: 'region-map', coropletico: 'region-map', coroplético: 'region-map', regiones: 'region-map',
+  flow: 'flow', graph: 'flow', grafo: 'flow', fluxo: 'flow', workflow: 'flow', flujo: 'flow', flow_graph: 'flow', 'flow-graph': 'flow',
+}
+
+const KEYS = {
+  type: ['type', 'tipo', 'chart', 'grafico', 'gráfico', 'visual'],
+  title: ['title', 'titulo', 'título', 'name', 'nome', 'nombre'],
+  subtitle: ['subtitle', 'subtitulo', 'subtítulo', 'description', 'descricao', 'descrição', 'descripcion', 'descripción'],
+  data: ['data', 'dados', 'rows', 'linhas', 'items', 'itens', 'values', 'valores', 'datos', 'filas', 'elementos'],
+  x: ['xKey', 'x_key', 'x', 'eixoX', 'eixo_x', 'category', 'categoria'],
+  y: ['yKeys', 'y_keys', 'y', 'series', 'séries', 'eixoY', 'eixo_y'],
+  format: ['valueFormat', 'value_format', 'format', 'formato'],
+  columnFormats: ['columnFormats', 'column_formats', 'formats', 'formatos'],
+  country: ['country', 'pais', 'país', 'countryCode', 'country_code'],
+  graph: ['graph', 'grafo', 'flow', 'fluxo', 'flujo'],
+  body: ['body', 'markdown', 'corpo', 'content', 'conteudo', 'conteúdo', 'contenido', 'cuerpo', 'text', 'texto'],
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
+
+function pick(o: Record<string, unknown>, keys: readonly string[]): unknown {
+  for (const k of keys) if (o[k] !== undefined && o[k] !== null) return o[k]
+  return undefined
+}
+
+function asFormat(v: unknown): ValueFormat | undefined {
+  const s = typeof v === 'string' ? v.toLowerCase() : ''
+  if (['number', 'numero', 'número', 'integer'].includes(s)) return 'number'
+  if (['currency', 'moeda', 'moneda', 'money', 'dinero'].includes(s)) return 'currency'
+  if (['percent', 'percentage', 'porcentagem', 'percentual', 'porcentaje', '%'].includes(s)) return 'percent'
+  return undefined
+}
+
+/**
+ * Reads a visualization tool output. Accepts an object (or its JSON text)
+ * marked as a visualization or carrying a type; returns null when it is not a
+ * usable visual (the chat then shows the tool's text summary instead).
+ */
+export function parseAssistantVisual(output: unknown): VisualEnvelope | null {
+  let o = output
+  if (typeof o === 'string') {
+    try {
+      o = JSON.parse(o)
+    } catch {
+      return null
+    }
+  }
+  if (!isRecord(o)) return null
+  // A wrapper such as { visualization: {...} } is unwrapped.
+  if (isRecord(o.visualization)) o = o.visualization
+  if (!isRecord(o)) return null
+  const rawType = pick(o, KEYS.type)
+  if (typeof rawType !== 'string') return null
+  const type = TYPE_ALIASES[rawType.trim().toLowerCase()]
+  if (!type) return null
+  const title = pick(o, KEYS.title)
+  if (typeof title !== 'string' || !title.trim()) return null
+
+  const data = pick(o, KEYS.data)
+  const rows = (Array.isArray(data) ? data : []).filter(isRecord)
+  const env: VisualEnvelope = { type, title: title.trim(), rows }
+
+  const subtitle = pick(o, KEYS.subtitle)
+  if (typeof subtitle === 'string' && subtitle.trim()) env.subtitle = subtitle.trim()
+  const x = pick(o, KEYS.x)
+  if (typeof x === 'string') env.xKey = x
+  const y = pick(o, KEYS.y)
+  if (typeof y === 'string') env.yKeys = [y]
+  else if (Array.isArray(y)) env.yKeys = y.filter((k): k is string => typeof k === 'string')
+  const format = asFormat(pick(o, KEYS.format))
+  if (format) env.format = format
+  const cf = pick(o, KEYS.columnFormats)
+  if (isRecord(cf)) {
+    const out: Record<string, ValueFormat> = {}
+    for (const [k, v] of Object.entries(cf)) {
+      const f = asFormat(v)
+      if (f) out[k] = f
+    }
+    env.columnFormats = out
+  }
+  const country = pick(o, KEYS.country)
+  if (typeof country === 'string') env.country = country
+
+  if (type === 'flow') {
+    const graph = pick(o, KEYS.graph)
+    if (!isRecord(graph)) return null
+    env.graph = graph
+    return env
+  }
+  if (type === 'prose') {
+    const body = pick(o, KEYS.body)
+    if (typeof body !== 'string' || !body.trim()) return null
+    env.body = body
+    return env
+  }
+  return rows.length ? env : null
+}
+
+const isNumeric = (v: unknown) => typeof v === 'number' && Number.isFinite(v)
+
+/** x key and series keys: from the envelope, else the first non-numeric column and the numeric ones. */
+export function inferAxes(env: Pick<VisualEnvelope, 'rows' | 'xKey' | 'yKeys'>): { x: string; y: string[] } {
+  const first = env.rows[0] ?? {}
+  const keys = Object.keys(first)
+  const x = env.xKey ?? keys.find((k) => !isNumeric(first[k])) ?? keys[0] ?? 'x'
+  const y = env.yKeys?.length ? env.yKeys : keys.filter((k) => k !== x && isNumeric(first[k]))
+  return { x, y }
+}
+
+const REGION_KEYS = ['region', 'regiao', 'região', 'región', 'code', 'codigo', 'código', 'uf', 'state', 'estado', 'iso']
+const LABEL_KEYS = ['label', 'title', 'titulo', 'título', 'name', 'nome', 'nombre', 'rotulo', 'rótulo', 'etiqueta']
+const VALUE_KEYS = ['value', 'valor', 'total', 'count', 'contagem', 'conteo', 'n']
+
+export interface EnvelopeToReportOptions {
+  /** Country used by region maps without one (from the host configuration). */
+  defaultCountry?: string
+}
+
+/** Converts a parsed envelope into a ReportView definition. */
+export function envelopeToReport(env: VisualEnvelope, options: EnvelopeToReportOptions = {}): ReportSpec {
+  const base: Pick<ReportSpec, 'title' | 'subtitle'> = { title: env.title, ...(env.subtitle ? { subtitle: env.subtitle } : {}) }
+  const sections: ReportSection[] = []
+  switch (env.type) {
+    case 'figures':
+      sections.push({
+        type: 'figures',
+        data: {
+          items: env.rows.map((r) => {
+            const label = pick(r, LABEL_KEYS)
+            const value = pick(r, VALUE_KEYS)
+            const format = asFormat(pick(r, KEYS.format)) ?? env.format
+            return { label: typeof label === 'string' ? label : '', value: isNumeric(value) || typeof value === 'string' ? (value as number | string) : '', ...(format ? { format } : {}) }
+          }),
+        },
+      })
+      break
+    case 'sections':
+      for (const r of env.rows) {
+        if (typeof r.type === 'string' && isRecord(r.data)) sections.push({ ...(r as object), type: r.type, data: r.data } as ReportSection)
+      }
+      break
+    case 'prose':
+      sections.push({ type: 'markdown', data: { body: env.body ?? '' } })
+      break
+    case 'region-map': {
+      const items = env.rows.flatMap((r) => {
+        const region = pick(r, REGION_KEYS)
+        if (typeof region !== 'string' || !region.trim()) return []
+        const label = pick(r, LABEL_KEYS)
+        const value = pick(r, VALUE_KEYS)
+        return [{ region: region.trim(), label: typeof label === 'string' ? label : region.trim(), value: isNumeric(value) ? (value as number) : Number(value) || 0 }]
+      })
+      const country = env.country ?? options.defaultCountry
+      sections.push({ type: 'region-map', data: { items, ...(country ? { country } : {}), ...(env.format ? { format: env.format } : {}) } })
+      break
+    }
+    case 'table': {
+      const first = env.rows[0] ?? {}
+      const columns = Object.keys(first).map((key) => {
+        const format = env.columnFormats?.[key] ?? (isNumeric(first[key]) ? 'number' : undefined)
+        return { key, label: key, ...(format ? { format } : {}) }
+      })
+      sections.push({ type: 'table', data: { rows: env.rows, columns } })
+      break
+    }
+    case 'flow':
+      sections.push({ type: 'flow', data: { graph: env.graph } })
+      break
+    default: {
+      const { x, y } = inferAxes(env)
+      sections.push({ type: env.type, data: { rows: env.rows, x, y, ...(env.format ? { format: env.format } : {}) } })
+    }
+  }
+  return { ...base, sections }
+}

package/src/flow/catalog/RenderCatalog.tsx

@@ -0,0 +1,98 @@
+// How a node kind is presented (label, icon, tone, ports, per-node identity).
+// By default the installed NodeKindCatalog answers; a host can swap any single
+// answer for a subtree with <NodeKindCatalogProvider>.
+
+import { createContext, useContext, useMemo, useSyncExternalStore, type ReactNode } from 'react'
+import type { IconComponent } from '../../index'
+import { FALLBACK_KIND_ICONS, resolveIcon } from './icons'
+import { nodeKindCatalog, type NodeKindCatalogStore, type PortTopology } from './kindCatalog'
+import { kindTone, type ToneName } from './palette'
+
+/** Per-instance presentation that wins over the per-kind catalog data. */
+export interface NodeIdentity {
+  icon?: IconComponent
+  title?: string
+  description?: string
+}
+
+export interface RenderCatalog {
+  /** Label and category for a kind (label falls back to a humanised kind key only when nothing else exists). */
+  entry(kind: string): { label: string; category: string; description?: string } | undefined
+  icon(kind: string): IconComponent
+  tone(kind: string): ToneName
+  ports(kind: string): PortTopology | undefined
+  identity(kind: string, data: Record<string, unknown>): NodeIdentity | null
+  badgeTone(kind: string): ToneName
+  /** Connectors attach to node borders; ports become invisible (ids kept). */
+  floatingConnections: boolean
+}
+
+export interface RenderCatalogOverrides extends Partial<Omit<RenderCatalog, 'floatingConnections'>> {
+  floatingConnections?: boolean
+}
+
+/** Answers read straight from a catalog store. */
+export function catalogFromStore(store: NodeKindCatalogStore, floatingConnections = false): RenderCatalog {
+  return {
+    entry: (kind) => {
+      const found = store.entry(kind)
+      if (!found) return undefined
+      const { label, category, description } = found
+      return description ? { label, category, description } : { label, category }
+    },
+    icon: (kind) => resolveIcon(store.entry(kind)?.icon ?? FALLBACK_KIND_ICONS[kind]),
+    tone: kindTone,
+    badgeTone: kindTone,
+    ports: (kind) => store.entry(kind)?.ports,
+    identity: () => null,
+    floatingConnections,
+  }
+}
+
+const ANSWER_KEYS = ['entry', 'icon', 'tone', 'ports', 'identity', 'badgeTone'] as const
+
+/** Base answers with every defined override laid on top. */
+function layered(base: RenderCatalog, patch: RenderCatalogOverrides): RenderCatalog {
+  const out = { ...base, floatingConnections: patch.floatingConnections ?? false }
+  for (const key of ANSWER_KEYS) {
+    const replacement = patch[key]
+    if (replacement) (out as Record<string, unknown>)[key] = replacement
+  }
+  return out
+}
+
+/** Re-renders when a new catalog is installed into the store. */
+const useStoreVersion = (store: NodeKindCatalogStore) => useSyncExternalStore(store.subscribe, store.getVersion, store.getVersion)
+
+const CatalogContext = createContext<RenderCatalog | null>(null)
+
+export interface NodeKindCatalogProviderProps extends RenderCatalogOverrides {
+  store?: NodeKindCatalogStore
+  children: ReactNode
+}
+
+/** Lets a host replace any resolver (icon, tone, identity …) for the subtree. */
+export function NodeKindCatalogProvider({ store = nodeKindCatalog, children, ...patch }: NodeKindCatalogProviderProps) {
+  const version = useStoreVersion(store)
+  const deps = [store, version, patch.floatingConnections, ...ANSWER_KEYS.map((k) => patch[k])]
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const catalog = useMemo(() => layered(catalogFromStore(store, patch.floatingConnections ?? false), patch), deps)
+  return <CatalogContext.Provider value={catalog}>{children}</CatalogContext.Provider>
+}
+
+/** The catalog in effect: a provider's, else the installed store's. */
+export function useRenderCatalog(): RenderCatalog {
+  const provided = useContext(CatalogContext)
+  const version = useStoreVersion(nodeKindCatalog)
+  return useMemo(() => provided ?? catalogFromStore(nodeKindCatalog), [provided, version])
+}
+
+/** Readable fallback for a kind key when no catalog label exists ("if-else" → "If else"). */
+export function humaniseKey(key: string): string {
+  const spaced = key
+    .split(/(?<=[a-z0-9])(?=[A-Z])|[_-]+/)
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase()
+  return spaced ? spaced.charAt(0).toUpperCase() + spaced.slice(1) : key
+}

package/src/flow/catalog/catalog.test.tsx

@@ -0,0 +1,162 @@
+import { render, screen } from '@testing-library/react'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { Star } from 'lucide-react'
+import { afterEach, describe, expect, it } from 'vitest'
+import { cssOf } from '../../../test/css'
+import { GENERIC_ICON, resolveIcon } from './icons'
+import { NodeKindCatalogStore, nodeKindCatalog, type NodeKindEntry } from './kindCatalog'
+import { nodeStateAttributes } from './nodeState'
+import { connectorTokens, kindTone, kindTokens, overrideKindTones, resetKindTones } from './palette'
+import { NodeKindCatalogProvider, useRenderCatalog } from './RenderCatalog'
+
+const entries: NodeKindEntry[] = [
+  { kind: 'start', label: 'Start', category: 'Control flow', icon: 'play' },
+  { kind: 'code', label: 'Compute', category: 'Data processing', icon: 'code', defaultConfig: { id: '', steps: [{ stepId: '', name: 'a' }] } },
+  { kind: 'if-else', label: 'Branch', category: 'Control flow', icon: 'git-branch' },
+  { kind: 'agent', label: 'Agent', category: 'AI', defaultConfig: { agentRef: '' } },
+]
+
+afterEach(() => {
+  nodeKindCatalog.reset()
+  resetKindTones()
+})
+
+describe('NodeKindCatalog', () => {
+  it('answers nothing before a catalog is installed', () => {
+    const s = new NodeKindCatalogStore()
+    expect(s.entry('code')).toBeUndefined()
+    expect(s.exists('code')).toBe(false)
+    expect(s.kinds()).toEqual([])
+  })
+
+  it('groups kinds by category in catalog order', () => {
+    const s = new NodeKindCatalogStore()
+    s.install(entries)
+    expect(s.byCategory().map((g) => [g.category, g.entries.map((e) => e.kind)])).toEqual([
+      ['Control flow', ['start', 'if-else']],
+      ['Data processing', ['code']],
+      ['AI', ['agent']],
+    ])
+  })
+
+  it('fills empty ids with new unique ids and leaves the stored default unchanged', () => {
+    const s = new NodeKindCatalogStore()
+    s.install(entries)
+    const a = s.createDefaultConfig('code') as { id: string; steps: Array<{ stepId: string }> }
+    const b = s.createDefaultConfig('code') as { id: string; steps: Array<{ stepId: string }> }
+    expect(a.id).not.toBe('')
+    expect(a.id).not.toBe(b.id)
+    expect(a.steps[0]!.stepId).not.toBe(b.steps[0]!.stepId)
+    expect(s.defaultConfig('code')).toEqual({ id: '', steps: [{ stepId: '', name: 'a' }] })
+    expect(s.createDefaultConfig('agent')).toBeUndefined()
+  })
+
+  it('resolves unknown icon keys to the neutral icon', () => {
+    expect(resolveIcon('does-not-exist')).toBe(GENERIC_ICON)
+  })
+
+  it('lets a host provider override the icon resolver and per-node identity', () => {
+    nodeKindCatalog.install(entries)
+    function Probe({ kind, data }: { kind: string; data: Record<string, unknown> }) {
+      const c = useRenderCatalog()
+      const id = c.identity(kind, data)
+      const Icon = c.icon(kind)
+      return (
+        <p>
+          <Icon data-testid={`icon-${kind}`} />
+          {id?.title ?? c.entry(kind)?.label}
+        </p>
+      )
+    }
+    render(
+      <NodeKindCatalogProvider icon={() => Star} identity={(_k, d) => (d.special ? { title: 'Special title' } : null)}>
+        <Probe kind="code" data={{ special: true }} />
+        <Probe kind="code" data={{}} />
+      </NodeKindCatalogProvider>,
+    )
+    expect(screen.getByText('Special title')).toBeInTheDocument()
+    expect(screen.getByText('Compute')).toBeInTheDocument()
+    expect(screen.getAllByTestId('icon-code')[0]!.getAttribute('class')).toContain('star')
+  })
+})
+
+describe('FlowPaletteTokens', () => {
+  it('uses neutral for a kind absent from catalog and defaults', () => {
+    expect(kindTone('something-new')).toBe('neutral')
+    expect(kindTone('agent')).toBe('categorical-4')
+  })
+
+  it('prefers the catalog tone, and host overrides over both', () => {
+    nodeKindCatalog.install([{ kind: 'agent', label: 'Agent', category: 'AI', tone: 'categorical-6' }])
+    expect(kindTone('agent')).toBe('categorical-6')
+    overrideKindTones({ agent: 'categorical-2' })
+    expect(kindTone('agent')).toBe('categorical-2')
+    expect(kindTokens('agent').bubble).toBe('var(--ty-flow-tone-categorical-2)')
+  })
+
+  it('throws a descriptive error for an unknown tone override', () => {
+    expect(() => overrideKindTones({ agent: 'purple' })).toThrow(/purple.*not a tone name/)
+  })
+
+  it('has no gradient in any canvas token and runs use the state contract colours', () => {
+    // The canvas tokens are generated by @datatechsolutions/tympan-tokens (src/flow.ts).
+    const built = readFileSync(join(__dirname, '../../../../tokens/dist/tokens.css'), 'utf8')
+    const tokens = built.slice(built.indexOf('/* component tokens */'), built.indexOf('/* theme: '))
+    expect(tokens).toContain('--ty-flow-connector:')
+    expect(tokens).not.toMatch(/gradient/i)
+    // "em execução" (running) is info/cyan, "aguardando" (suspended) is warning/amber.
+    expect(tokens).toMatch(/--ty-flow-ring-running:\s*var\(--ty-info\)/)
+    expect(tokens).toMatch(/--ty-flow-ring-suspended:\s*var\(--ty-warning\)/)
+    expect(tokens).toMatch(/--ty-flow-connector-active:\s*var\(--ty-info\)/)
+    expect(tokens).toMatch(/--ty-flow-connector-traversed:\s*var\(--ty-success\)/)
+    expect(tokens).toMatch(/--ty-flow-connector-blocked:\s*var\(--ty-warning\)/)
+    expect(tokens).toMatch(/--ty-flow-connector-pending:\s*var\(--ty-neutral\)/)
+    expect(tokens).toMatch(/--ty-flow-cursor-now:\s*var\(--ty-cursor-now\)/)
+    for (const tone of ['categorical-1', 'categorical-8', 'neutral']) expect(tokens).toContain(`[data-tone="${tone}"]`)
+    expect(cssOf('flow/styles.css')).not.toMatch(/@import\s+'\.\/tokens\.css'/)
+    expect(connectorTokens.false).toBe('var(--ty-flow-connector-false)')
+    expect(connectorTokens.traversed).toBe('var(--ty-flow-connector-traversed)')
+  })
+
+  it('keeps every categorical tone at ≥ 3:1 against the node surface in light and dark (static check)', () => {
+    const css = readFileSync(join(__dirname, '../../../../tokens/dist/tokens.css'), 'utf8')
+    const pick = (block: string, name: string) => new RegExp(`--ty-${name}:\\s*(#[0-9a-f]{6})`, 'i').exec(block)?.[1]
+    const light = css.slice(css.indexOf('[data-ty-theme="tympan"],'))
+    const dark = css.slice(css.indexOf('[data-ty-mode="dark"],'))
+    const lum = (hex: string) => {
+      const c = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255).map((v) => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4))
+      return 0.2126 * c[0]! + 0.7152 * c[1]! + 0.0722 * c[2]!
+    }
+    const ratio = (a: string, b: string) => {
+      const [x, y] = [lum(a), lum(b)].sort((m, n) => n - m)
+      return (x! + 0.05) / (y! + 0.05)
+    }
+    for (const block of [light, dark]) {
+      const surface = pick(block, 'surface-raised-solid')!
+      for (let i = 1; i <= 8; i++) expect(ratio(pick(block, `categorical-${i}`)!, surface)).toBeGreaterThanOrEqual(3)
+    }
+  })
+})
+
+describe('NodeStateStyles', () => {
+  it('returns idle, unselected, unlocked, undimmed attributes by default', () => {
+    expect(nodeStateAttributes()).toEqual({ 'data-selected': 'false', 'data-run-state': 'idle', 'data-locked': 'false', 'data-dimmed': 'false' })
+  })
+
+  it('maps proof state to a line style: pending is dashed', () => {
+    expect(nodeStateAttributes({ proofState: 'pending' })['data-proof-state']).toBe('pending')
+    expect(cssOf('flow/nodes/GraphNodeCard.css')).toMatch(/\[data-proof-state='pending'\]\s*\{[^}]*dashed/)
+  })
+
+  it('shows hover as the strong line token only', () => {
+    expect(cssOf('flow/nodes/GraphNodeCard.css')).toMatch(/\.ty-node-card:hover\s*\{\s*--ty-node-border-color:\s*var\(--ty-flow-node-border-hover\);\s*\}/)
+  })
+
+  it('in forced colours, running is a dashed system-text border', () => {
+    const css = cssOf('flow/nodes/GraphNodeCard.css')
+    const forced = css.slice(css.indexOf('@media (forced-colors: active)'))
+    expect(forced).toMatch(/\[data-run-state='running'\]\s*\{[^}]*dashed CanvasText/)
+    expect(forced).toMatch(/\[data-selected='true'\]\s*\{[^}]*Highlight/)
+  })
+})

package/src/flow/catalog/icons.ts

@@ -0,0 +1,116 @@
+// Icon registry: catalog icon keys (kebab-case lucide names) → components.
+// Unknown keys resolve to a neutral generic glyph (design direction §4.4).
+
+import {
+  BookOpen,
+  Bot,
+  Box,
+  Braces,
+  ChartColumn,
+  ClipboardCheck,
+  Code,
+  Database,
+  Dices,
+  FileChartColumn,
+  FileSearch,
+  FileText,
+  Fingerprint,
+  Flag,
+  GitBranch,
+  Group,
+  Landmark,
+  Library,
+  MessageSquare,
+  Newspaper,
+  Play,
+  Quote,
+  Repeat,
+  Scale,
+  ScrollText,
+  Search,
+  Split,
+  SquareFunction,
+  StickyNote,
+  Target,
+  Workflow,
+} from 'lucide-react'
+import type { IconComponent } from '../../index'
+
+export const GENERIC_ICON: IconComponent = Box
+
+const builtIn: Record<string, IconComponent> = {
+  play: Play,
+  flag: Flag,
+  'git-branch': GitBranch,
+  split: Split,
+  code: Code,
+  braces: Braces,
+  'square-function': SquareFunction,
+  repeat: Repeat,
+  bot: Bot,
+  'message-square': MessageSquare,
+  'file-chart-column': FileChartColumn,
+  'chart-column': ChartColumn,
+  database: Database,
+  'sticky-note': StickyNote,
+  group: Group,
+  dices: Dices,
+  scale: Scale,
+  target: Target,
+  workflow: Workflow,
+  // Provenance kinds.
+  search: Search,
+  fingerprint: Fingerprint,
+  'file-search': FileSearch,
+  'file-text': FileText,
+  quote: Quote,
+  'clipboard-check': ClipboardCheck,
+  'book-open': BookOpen,
+  library: Library,
+  newspaper: Newspaper,
+  'scroll-text': ScrollText,
+  landmark: Landmark,
+  box: Box,
+}
+
+let registry = new Map<string, IconComponent>(Object.entries(builtIn))
+
+/** Adds or replaces icons (host icons for its own kinds). */
+export function registerIcons(map: Record<string, IconComponent>): void {
+  registry = new Map([...registry, ...Object.entries(map)])
+}
+
+export function resolveIcon(key: string | undefined | null): IconComponent {
+  return (key && registry.get(key)) || GENERIC_ICON
+}
+
+/** Default icon key per kind when the catalog is not loaded. */
+export const FALLBACK_KIND_ICONS: Readonly<Record<string, string>> = Object.freeze({
+  start: 'play',
+  end: 'flag',
+  'if-else': 'git-branch',
+  branch: 'git-branch',
+  switch: 'split',
+  code: 'code',
+  compute: 'square-function',
+  iteration: 'repeat',
+  loop: 'repeat',
+  simulation: 'dices',
+  agent: 'bot',
+  answer: 'message-square',
+  rule: 'scale',
+  decision: 'target',
+  'report-output': 'file-chart-column',
+  datasource: 'database',
+  note: 'sticky-note',
+  group: 'group',
+  query: 'search',
+  retrieval: 'fingerprint',
+  source: 'file-text',
+  assertion: 'quote',
+  record: 'clipboard-check',
+  analysis: 'chart-column',
+  edition: 'library',
+  manuscript: 'scroll-text',
+  verification: 'scale',
+})