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 "kalpjs";

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

Props

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

Bridge server HTTP API

The kalp command serves a small JSON API on localhost (default range 42424–42443, 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": 42424,
  "project": {
    "name": "your-app",         // from the project's package.json (fallback: folder name)
    "cwd": "/path/to/your/project"
  },
  "claude": {
    "installed": true,          // claude CLI found on PATH
    "credentialed": "yes"       // "yes" | "no" | "unknown"
  }
}

The project field is how a server identifies itself during discovery — it's what the multi-project picker shows, and what the component verifies a remembered binding against. 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": 42424,
  "version": "0.2.0",
  "project": { "name": "your-app", "cwd": "/path/to/your/project" },
  "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.

{
  "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
  "expectedCwd": "/path/to/your/project"        // optional identity check (see 409 below)
}

At least one edit or a non-empty prompt is required, otherwise the server answers 400. expectedCwd is the project folder the client believes this server serves — the component always sends it, so an apply can never land in the wrong project even if ports got shuffled between page load and click.

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.

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

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