{
  "slug": "pilot/sdk/solid",
  "title": "Pilot SolidJS SDK",
  "description": "SolidJS primitives and components for Cuitty Pilot — reactive playbook management, run control, and real-time event streaming.",
  "url": "https://cuitty.com/docs/pilot/sdk/solid",
  "markdown_url": "https://cuitty.com/docs/pilot/sdk/solid.md",
  "json_url": "https://cuitty.com/docs/pilot/sdk/solid.json",
  "frontmatter": {
    "title": "Pilot SolidJS SDK",
    "description": "SolidJS primitives and components for Cuitty Pilot — reactive playbook management, run control, and real-time event streaming.",
    "order": 13,
    "section": "Pilot",
    "updatedAt": "2026-06-01"
  },
  "headings": [
    {
      "depth": 1,
      "slug": "pilot-solidjs-sdk",
      "text": "Pilot SolidJS SDK"
    },
    {
      "depth": 2,
      "slug": "install",
      "text": "Install"
    },
    {
      "depth": 2,
      "slug": "quick-start",
      "text": "Quick start"
    },
    {
      "depth": 2,
      "slug": "pilotprovider",
      "text": "PilotProvider"
    },
    {
      "depth": 3,
      "slug": "usepilot",
      "text": "usePilot()"
    },
    {
      "depth": 2,
      "slug": "primitives",
      "text": "Primitives"
    },
    {
      "depth": 3,
      "slug": "createplaybooksoptions",
      "text": "createPlaybooks(options?)"
    },
    {
      "depth": 3,
      "slug": "createrun",
      "text": "createRun()"
    },
    {
      "depth": 3,
      "slug": "createruneventsrunid",
      "text": "createRunEvents(runId)"
    },
    {
      "depth": 2,
      "slug": "components",
      "text": "Components"
    },
    {
      "depth": 3,
      "slug": "runstatusbadge",
      "text": "RunStatusBadge"
    },
    {
      "depth": 3,
      "slug": "runtimeline",
      "text": "RunTimeline"
    },
    {
      "depth": 3,
      "slug": "playbookcard",
      "text": "PlaybookCard"
    },
    {
      "depth": 2,
      "slug": "error-handling",
      "text": "Error handling"
    },
    {
      "depth": 2,
      "slug": "see-also",
      "text": "See also"
    }
  ],
  "body_markdown": "# Pilot SolidJS SDK\n\n`@cuitty/pilot-solid` provides SolidJS primitives and components for the Pilot API. It wraps `@cuitty/pilot-sdk` with idiomatic Solid patterns — context providers, `createResource` for data fetching, signals for run state, and automatic SSE cleanup.\n\n## Install\n\n```bash\nsfw bun add @cuitty/pilot-solid\n# or\nsfw npm install @cuitty/pilot-solid\n```\n\nPeer dependencies: `solid-js>=1.8`, `@cuitty/pilot-sdk`.\n\n## Quick start\n\n```tsx\nimport { PilotProvider, createPlaybooks, createRun, createRunEvents } from \"@cuitty/pilot-solid\";\nimport { For, Show, createSignal } from \"solid-js\";\n\nfunction App() {\n  return (\n    <PilotProvider baseUrl=\"http://localhost:4320\" auth={{ apiKey: \"pk_...\" }}>\n      <Dashboard />\n    </PilotProvider>\n  );\n}\n\nfunction Dashboard() {\n  const [playbooks] = createPlaybooks();\n  const [run, { start }] = createRun();\n  const events = createRunEvents(() => run()?.id);\n\n  return (\n    <div>\n      <For each={playbooks()}>\n        {(pb) => (\n          <button onClick={() => start({ playbookId: pb.id, mode: \"autonomous\" })}>\n            {pb.title}\n          </button>\n        )}\n      </For>\n      <For each={events()}>\n        {(e) => <div>{e.type} {e.stepId}</div>}\n      </For>\n    </div>\n  );\n}\n```\n\n## PilotProvider\n\nWraps your component tree with a `PilotClient` instance. Accepts all `PilotClientConfig` props plus `children`. The client is closed automatically via `onCleanup`.\n\n```tsx\nimport { PilotProvider } from \"@cuitty/pilot-solid\";\n\n<PilotProvider\n  baseUrl=\"http://localhost:4320\"\n  auth={{ token: \"ey...\" }}\n  timeout={15000}\n>\n  {props.children}\n</PilotProvider>\n```\n\n| Prop | Type | Description |\n|------|------|-------------|\n| `baseUrl` | `string` | Pilot server URL |\n| `auth` | `{ token?: string; cookie?: string; apiKey?: string }` | Authentication credentials |\n| `timeout` | `number` | Per-request timeout in ms (default 30000) |\n| `children` | `JSX.Element` | Child components |\n\n### usePilot()\n\nReturns the `PilotClient` from context. Throws if used outside `<PilotProvider>`.\n\n```tsx\nimport { usePilot } from \"@cuitty/pilot-solid\";\n\nconst pilot = usePilot();\nconst health = await pilot.health();\n```\n\n## Primitives\n\n### createPlaybooks(options?)\n\nReactive resource for listing playbooks. Wraps Solid's `createResource` — re-fetches when the options accessor changes.\n\n```tsx\nconst [playbooks, { refetch }] = createPlaybooks();\nconst [cfOnly] = createPlaybooks(() => ({ target: \"cloudflare\" }));\n```\n\n| Param | Type | Description |\n|-------|------|-------------|\n| `opts` | `() => ListPlaybooksOptions \\| undefined` | Optional accessor returning filter options |\n\nReturns a Solid `Resource<PlaybookSummary[]>` tuple: `[accessor, { refetch, mutate }]`.\n\n### createRun()\n\nManages a single run lifecycle with signals for run state and loading.\n\n```tsx\nconst [run, { start, abort, loading }] = createRun();\n\n// Start a new run\nconst result = await start({\n  playbookId: \"cloudflare.dns.add-a-record\",\n  mode: \"interactive\",\n  inputs: { zone: \"example.com\", record_name: \"api\", ip_address: \"1.2.3.4\" },\n});\n\n// Abort the active run\nawait abort();\n```\n\n| Return | Type | Description |\n|--------|------|-------------|\n| `run` | `Accessor<Run \\| null>` | Signal with the current run object |\n| `start(req)` | `(StartRunRequest) => Promise<Run \\| null>` | Start a run and fetch its full details |\n| `abort()` | `() => Promise<void>` | Abort the current run |\n| `loading` | `Accessor<boolean>` | Signal, `true` while starting |\n\n### createRunEvents(runId)\n\nSubscribes to real-time SSE events for a run. Automatically unsubscribes via `onCleanup` and re-subscribes when `runId` changes.\n\n```tsx\nconst events = createRunEvents(() => run()?.id);\n\n// events is Accessor<RunEvent[]>\n<For each={events()}>\n  {(event) => <span>{event.type}</span>}\n</For>\n```\n\n| Param | Type | Description |\n|-------|------|-------------|\n| `runId` | `() => string \\| null \\| undefined` | Accessor returning the run ID; `null`/`undefined` pauses subscription |\n\nReturns `Accessor<RunEvent[]>` — accumulates all events since subscription started.\n\n## Components\n\n### RunStatusBadge\n\nRenders a colored pill badge for a run status.\n\n```tsx\nimport { RunStatusBadge } from \"@cuitty/pilot-solid\";\n\n<RunStatusBadge status=\"running\" />\n<RunStatusBadge status=\"completed\" />\n```\n\nSupported statuses: `queued`, `running`, `awaiting_approval`, `completed`, `failed`, `aborted`.\n\n### RunTimeline\n\nRenders a vertical timeline of run events using `<For>`, with color-coded borders (blue for in-progress, green for complete, red for failures). Uses `<Show>` for conditional step ID display.\n\n```tsx\nimport { RunTimeline } from \"@cuitty/pilot-solid\";\n\nconst events = createRunEvents(() => runId);\n<RunTimeline events={events()} />\n```\n\n### PlaybookCard\n\nDisplays a playbook summary card with an optional \"Run\" button. Uses `<Show>` to conditionally render the button.\n\n```tsx\nimport { PlaybookCard } from \"@cuitty/pilot-solid\";\n\n<PlaybookCard\n  playbook={playbook}\n  onRun={(pb) => start({ playbookId: pb.id, mode: \"autonomous\" })}\n/>\n```\n\n| Prop | Type | Description |\n|------|------|-------------|\n| `playbook` | `PlaybookSummary` | Playbook to display |\n| `onRun` | `(playbook: PlaybookSummary) => void` | Optional callback when \"Run\" is clicked |\n\n## Error handling\n\nErrors in `createPlaybooks` surface through the resource's error state. For `createRun`, errors thrown during `start()` propagate to the caller. For direct `PilotClient` usage via `usePilot()`, catch typed errors from `@cuitty/pilot-sdk`.\n\n```tsx\nimport { PilotApiError, PilotConnectionError } from \"@cuitty/pilot-sdk\";\n\nconst pilot = usePilot();\ntry {\n  await pilot.runs.start({ playbookId: \"nonexistent\" });\n} catch (err) {\n  if (err instanceof PilotApiError) {\n    console.error(`API ${err.status}: ${err.statusText}`, err.body);\n  } else if (err instanceof PilotConnectionError) {\n    console.error(\"Cannot reach Pilot:\", err.message);\n  }\n}\n```\n\n## See also\n\n- [JavaScript SDK](/docs/pilot/sdk/javascript) — underlying `PilotClient` API reference\n- [Playbook reference](/docs/pilot/playbook-reference) — YAML schema for playbook documents\n- [Quickstart](/docs/pilot/quickstart) — record and replay your first workflow",
  "links_out": [
    "/docs/pilot/sdk/javascript",
    "/docs/pilot/playbook-reference",
    "/docs/pilot/quickstart"
  ]
}