\n );\n}\n```\n\n### Render an artifact block\n\n```tsx\nimport { renderArtifactBlock } from \"@adam2go/tilo-react\";\n\n// Works with any AIP v1 block (chart, diff, code, timeline, kanban, …)\nconst block = {\n id: \"chart-1\",\n type: \"chart\",\n props: {\n chart_type: \"bar\",\n labels: [\"Q1\", \"Q2\", \"Q3\", \"Q4\"],\n datasets: [{ label: \"Revenue\", data: [120, 180, 150, 220] }],\n },\n};\n\n
{renderArtifactBlock(block)}
\n```\n\n### Override a block renderer\n\n```tsx\nimport { TiloRenderer } from \"@adam2go/tilo-react\";\nimport type { BlockProps } from \"@adam2go/tilo-react\";\n\nfunction MyDecision({ block, fire }: BlockProps<\"decision\">) {\n return (\n
\n {block.data.options.map((opt) => (\n \n ))}\n
\n );\n}\n\n\n```\n\n## Block types\n\n### Surface blocks (`TiloRenderer`)\n\n| Type | Description |\n|---|---|\n| `heading` | Section header with severity badge |\n| `text` | Plain text paragraph |\n| `evidence` | Quoted excerpt with source reference |\n| `comparison` | Side-by-side or table comparison |\n| `decision` | Choice buttons (single / multi) |\n| `form` | Input fields + submit |\n| `progress` | Steps, percent bar, or status |\n| `list` | Ordered / unordered list with severity |\n| `link` | Link with external indicator |\n| `editable` | Editable textarea with save action |\n| `artifact_link` | Clickable card that opens a rich artifact |\n| `fallback` | Graceful fallback for unknown types |\n\n### Artifact blocks (`renderArtifactBlock`)\n\nThese match the block types produced by `tilo.generate()` and the\nzero-setup Python viewer (`tilo.view`), so React rendering looks identical.\n\n| Type | Description |\n|---|---|\n| `heading` | Section header with severity color |\n| `markdown` | Plain text / markdown |\n| `card` | Titled card with severity |\n| `metric` | Single KPI value (label + value + delta) |\n| `table` | Data table with header row |\n| `list` | Bullet list with severity |\n| `code` | Monospace code block with language label |\n| `chart` | Bar, line, pie, or radar chart via Recharts |\n| `diff` | Unified diff (color-coded) or before/after |\n| `timeline` | Vertical dot-and-line timeline |\n| `kanban` | Horizontal column board |\n| `progress` | Progress bar |\n| `checklist` | Interactive checkboxes |\n| `rating` | Interactive star rating |\n| `button_group` | Action buttons (primary / default) |\n| `form` | Input fields + submit |\n| `confirmation` | Human-approval gate with risk badge |\n| `tool_preview` | Tool call result with status badge |\n| `memory_card` | Memory candidate with confidence % |\n| + custom | Unknown types fall back gracefully |\n\n## Tailwind CSS\n\n`@adam2go/tilo-react` components use Tailwind CSS utility classes. Add the package to your `tailwind.config.js` content scan:\n\n```js\n// tailwind.config.js\nmodule.exports = {\n content: [\n \"./src/**/*.{js,ts,jsx,tsx}\",\n \"./node_modules/@adam2go/tilo-react/dist/**/*.{js,mjs}\",\n ],\n};\n```\n\n## Peer dependencies\n\n| Package | Version |\n|---|---|\n| `react` | ≥ 18 |\n| `react-dom` | ≥ 18 |\n| `recharts` | ≥ 2 (for chart blocks) |\n| `lucide-react` | ≥ 0.400 (for icons) |\n\n## API\n\n### ``\n\n| Prop | Type | Description |\n|---|---|---|\n| `surface` | `SurfaceSpec` | The surface spec to render |\n| `onAction` | `(event: TiloAction) => void \\| Promise` | Action callback |\n| `components` | `BlockOverrides` | Per-type visual overrides |\n| `blockWrapper` | `(block, child) => ReactNode` | Wrapper around each block |\n\n### `createTiloClient(options)`\n\nReturns a `TiloClient` with:\n- `fetchRunSurfaceTurns(runId)` → `SurfaceTurn[]`\n- `fetchSessionSurfaceTurns(sessionId, limit?)` → `SurfaceTurn[]`\n- `executeSurfaceAction(params)` → `SurfaceActionResult`\n\n### `useTiloSurface(options)`\n\n| Option | Type | Description |\n|---|---|---|\n| `client` | `TiloClient` | Client from `createTiloClient` |\n| `runId` | `string \\| null` | Fetch turns for a specific run |\n| `sessionId` | `string \\| null` | Fetch turns for a conversation |\n| `pollingMs` | `number` | Auto-refresh interval (0 = off) |\n| `enabled` | `boolean` | Enable/disable fetching |\n\nReturns `{ turns, loading, error, refresh }`.\n\n## License\n\nMIT — part of [Tilo Framework](https://github.com/adam2go/tilo-framework)\n","readmeFilename":"README.md"}