Reference

API Reference

Everything the package exports, and the HTTP endpoints the bridge server exposes on localhost.

<Kalp /> component

The main export. Render it once, anywhere in your React tree, in development only. It draws its own floating UI in a portal-like way (fixed-position elements on top of your app) and renders nothing inside your layout.

import { Kalp } from "@deval2498/kalp";

<Kalp onSelect={(results) => console.log(results)} />

Props

Prop	Type	Required	Description
`onSelect`	`(results: SelectionResult[]) => void`	no	Called every time the selection changes. Each result describes one selected element: the DOM element, the React component that rendered it, and its props. Useful if you want to build your own tooling on top of kalp's selection.

A SelectionResult contains the fields of a WalkedFiber (the matched React component's componentName, its props, and the fiber node) plus the selected DOM element.

Other exports

Export	Kind	Description
`Kalp`	component	The visual editor described throughout these docs.
`WalkedFiber`	type	The shape kalp produces when it resolves a DOM element to a React component. Exported so `onSelect` callbacks can be typed.

Bridge server HTTP API

The kalp command serves a small JSON API on localhost (default port 3001, see port discovery). The <Kalp /> component is its only intended client, but the API is plain HTTP — you can call it yourself, for example from a script. All endpoints allow cross-origin requests so your dev server's page can reach them.

GET /kalp/port

The discovery endpoint the component probes on mount. Cheap enough to call often; the claude status is cached for about ten seconds.

{
  "ok": true,
  "port": 3001,
  "claude": {
    "installed": true,          // claude CLI found on PATH
    "credentialed": "yes"       // "yes" | "no" | "unknown"
  }
}

credentialed is "unknown" when no credential source is visible but one may still exist (on macOS the login can live in the keychain, which kalp does not open). The component only warns on "no".

GET /kalp/health

Like /kalp/port, plus the server version and a human-readable detail of what the credential check found.

{
  "ok": true,
  "port": 3001,
  "version": "0.1.0",
  "claude": {
    "installed": true,
    "credentialed": "yes",
    "detail": "oauth credentials file"
  }
}

POST /kalp/edits

The endpoint behind the apply to code button. Takes the edit log and an optional free-form prompt, builds the instruction, and runs Claude Code. The request stays open until the run finishes.

Request body

{
  "edits": [
    {
      "componentName": "PricingCard",
      "domPath": "div > button:nth-child(2)",   // element position inside the component
      "property": "border-radius",
      "before": "8px",
      "after": "16px"
    }
  ],
  "prompt": "also make the label say Save",     // optional
  "selectedComponent": "PricingCard"            // which component the prompt applies to
}

At least one edit or a non-empty prompt is required, otherwise the server answers 400.

Responses

Status	Body	Meaning
`200`	`{ "ok": true }`	Claude Code finished and the edits are in your source files.
`400`	`{ "ok": false, "error": "no edits or prompt provided" }`	Empty request.
`503`	`{ "ok": false, "error": "claude code cli not found — …" }`	Pre-flight check failed — Claude Code is not installed or has no credentials. Nothing was run.
`500`	`{ "ok": false, "code": 1, "error": "claude code is not logged in — …" }`	Claude Code ran but failed. `error` carries the readable reason (taken from Claude's own output); `code` is its exit code.

POST /kalp/prompt

A simpler, prompt-only variant: no recorded edits, just an instruction and the currently selected components. Responses and error handling are identical to /kalp/edits.

Request body

{
  "prompt": "make the primary button green",
  "components": [
    { "componentName": "PricingCard", "props": { "plan": "pro" } }
  ]
}

Requires a non-empty prompt and at least one component, otherwise 400.