@copilotkit/bot-ui 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) Atai Barkai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# @copilotkit/bot-ui
+
+A pure **JSX runtime + intermediate representation (IR) + cross-platform
+component vocabulary** for authoring rich bot messages. No React, no agent
+runtime, no Slack — `@copilotkit/bot-ui` depends on nothing in the repo
+except `@copilotkit/shared` (for `StandardSchemaV1` types). That's what lets
+a platform adapter (e.g. `@copilotkit/bot-slack`) translate the same UI into
+Block Kit, while keeping the component layer tree-shakeable and testable in
+isolation.
+
+You author UI as JSX, it normalizes to one serializable IR (`BotNode[]`), and
+behavior props (`onClick` / `onSelect` / `onSubmit`) ride along on the nodes
+for the engine (`@copilotkit/bot`) to bind.
+
+## Install
+
+```sh
+pnpm add @copilotkit/bot-ui
+```
+
+To author components as JSX, point the TypeScript JSX factory at this package
+in the consuming project's `tsconfig.json`:
+
+```jsonc
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@copilotkit/bot-ui",
+  },
+}
+```
+
+This package ships `@copilotkit/bot-ui/jsx-runtime` (and
+`/jsx-dev-runtime`) exporting `jsx` / `jsxs` / `Fragment`. Author component
+files as `.tsx`.
+
+## Example
+
+```tsx
+import {
+  Message,
+  Header,
+  Section,
+  Actions,
+  Button,
+  renderToIR,
+} from "@copilotkit/bot-ui";
+
+function Greeting({ name }: { name: string }) {
+  return (
+    <Message>
+      <Header>Hello {name}</Header>
+      <Section>Pick an option — **bold** and `code` work too.</Section>
+      <Actions>
+        <Button
+          style="primary"
+          onClick={(ctx) => ctx.thread.post("you clicked!")}
+        >
+          Continue
+        </Button>
+      </Actions>
+    </Message>
+  );
+}
+
+const ir = renderToIR(<Greeting name="Ada" />);
+// ir is BotNode[] — hand it to an adapter, or let @copilotkit/bot post it.
+```
+
+`renderToIR(ui: Renderable): BotNode[]` recursively invokes any component
+function (passing its props) until only intrinsic string-typed nodes remain;
+strings in children become `{ type: "text", props: { value } }`; `Fragment`
+flattens its children. Components must be **pure functions of serializable
+props** — same props in, same tree out — which is what makes content-stable
+action binding and re-render rehydration possible in `@copilotkit/bot`.
+
+`Renderable` also accepts a `{ raw }` escape hatch, which `renderToIR` passes
+through as `{ type: "raw", props: { value } }` for adapters that want to
+short-circuit to a native payload.
+
+## Component vocabulary
+
+Each component is a thin function returning a `BotNode` with a stable
+intrinsic `type` string. An adapter maps these to native primitives.
+
+Every component has a fully-typed prop interface (`MessageProps`,
+`ButtonProps`, …, all exported), and the package ships its own `JSX` namespace
+(resolved via `jsxImportSource: "@copilotkit/bot-ui"`). So JSX is statically
+checked: unknown attributes, wrong prop values, and bad children are
+compile-time errors — `<Section bogus={1} />` or `<Button style="nope">` won't
+type-check. There are no lowercase intrinsic tags; the vocabulary is the
+capitalized component set below.
+
+| Component  | Purpose                                                           |
+| ---------- | ----------------------------------------------------------------- | ---------- |
+| `Message`  | Root container for a single posted message.                       |
+| `Header`   | Bold header / title row.                                          |
+| `Section`  | A block of (markdown) body text.                                  |
+| `Markdown` | Explicit markdown text block.                                     |
+| `Field`    | One label/value cell inside `Fields`.                             |
+| `Fields`   | A grid of `Field`s (two-column key/value layout).                 |
+| `Context`  | Small, muted secondary text (footnotes, metadata).                |
+| `Actions`  | Row container for interactive controls.                           |
+| `Button`   | Clickable button — `onClick`, `value`, `style: "primary"          | "danger"`. |
+| `Select`   | Dropdown — `onSelect`, `placeholder`, `options: {label,value}[]`. |
+| `Input`    | Text input — `onSubmit`, `placeholder`, `multiline`, `name`.      |
+| `Image`    | An image block.                                                   |
+| `Divider`  | A horizontal rule.                                                |
+
+### Behavior props
+
+Interactive components carry handler props typed as `ClickHandler`:
+
+- `Button` → `onClick`
+- `Select` → `onSelect`
+- `Input` → `onSubmit`
+
+A `ClickHandler` receives an `InteractionContext`, both generic over the
+clicked control's value type:
+
+```ts
+type ClickHandler<TValue = unknown> = (
+  ctx: InteractionContext<TValue>,
+) => void | Promise<void>;
+
+interface InteractionContext<TValue = unknown> {
+  thread: Thread;
+  message: IncomingMessage;
+  action: { id: string; value?: TValue };
+  values: Record<string, unknown>;
+  user: PlatformUser;
+  platform: string;
+}
+```
+
+`Button` is generic over its `value` prop, so `ctx.action.value` is **inferred**
+from `value` — `<Button value={{ confirmed: true }} onClick={(ctx) => ctx.action.value?.confirmed}>`
+type-checks with no cast. `Select`/`Input` resolve the value to `string`.
+
+The structural types `Thread`, `IncomingMessage`, `PlatformUser`,
+`MessageRef`, and `ClickHandler` are declared here for handler typing only —
+they're implemented at runtime by `@copilotkit/bot` and its adapters.
+`@copilotkit/bot-ui` has no runtime dependency on them.
+
+## `bind()` — the Tier-2 escape hatch
+
+Inline `onClick` handlers are bound by content (component identity + path +
+serializable props), so a handler can be re-derived after a restart by
+re-rendering the component. When a handler closes over data that **can't** be
+reconstructed from props, wrap it with `bind()` so the engine persists that
+small payload explicitly alongside the minted action id:
+
+```tsx
+import { bind } from "@copilotkit/bot-ui";
+
+<Button onClick={bind(handleChoice, { choiceId: "abc123" })}>Choose</Button>;
+```
+
+`bind(handler, args)` returns a tagged handler; the action registry stores
+`args` so a cold-path dispatch passes them back via `ctx.action.value`. Keep
+`args` small — it's the only handler-specific state that survives a restart.
+
+## Exports
+
+Runtime: `renderToIR`, `Fragment`, `bind`, and the vocabulary
+(`Message`, `Header`, `Section`, `Markdown`, `Field`, `Fields`, `Context`,
+`Actions`, `Button`, `Select`, `Input`, `Image`, `Divider`).
+Types: `BotNode`, `BotChildren`, `ComponentFn`, `Renderable`, `Thread`,
+`InteractionContext`, `PlatformUser`, `IncomingMessage`, `MessageRef`,
+`ClickHandler`, and the per-component prop types (`MessageProps`,
+`ButtonProps`, `SelectProps`, `TableProps`, `TableColumn`, …).

package/dist/bind.d.ts

@@ -0,0 +1,6 @@
+import type { ClickHandler } from "./types.js";
+export declare function bind(handler: ClickHandler, args: unknown): ClickHandler;
+export declare function isBound(h: unknown): boolean;
+export declare function getBoundArgs(h: unknown): unknown;
+export declare function getBoundHandler(h: unknown): ClickHandler | undefined;
+//# sourceMappingURL=bind.d.ts.map

package/dist/bind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind.d.ts","sourceRoot":"","sources":["../src/bind.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAsB,MAAM,YAAY,CAAC;AAMnE,wBAAgB,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,GAAG,YAAY,CAQvE;AACD,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAE3C;AACD,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAEhD;AACD,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAEpE"}

package/dist/bind.js

@@ -0,0 +1,18 @@
+const BOUND = Symbol.for("copilotkit.bot-ui.bound");
+export function bind(handler, args) {
+    const wrapped = ((ctx) => handler({
+        ...ctx,
+        action: { ...ctx.action, value: args },
+    }));
+    wrapped[BOUND] = { handler, args };
+    return wrapped;
+}
+export function isBound(h) {
+    return typeof h === "function" && !!h[BOUND];
+}
+export function getBoundArgs(h) {
+    return h[BOUND]?.args;
+}
+export function getBoundHandler(h) {
+    return h[BOUND]?.handler;
+}

package/dist/bind.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bind.test.d.ts.map

package/dist/bind.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind.test.d.ts","sourceRoot":"","sources":["../src/bind.test.ts"],"names":[],"mappings":""}

package/dist/bind.test.js

@@ -0,0 +1,14 @@
+import { describe, it, expect } from "vitest";
+import { bind, isBound, getBoundArgs, getBoundHandler } from "./bind.js";
+describe("bind", () => {
+    it("tags a handler with serializable args", () => {
+        const h = () => { };
+        const b = bind(h, { flightId: "x1" });
+        expect(isBound(b)).toBe(true);
+        expect(getBoundArgs(b)).toEqual({ flightId: "x1" });
+        expect(getBoundHandler(b)).toBe(h);
+    });
+    it("plain handler is not bound", () => {
+        expect(isBound(() => { })).toBe(false);
+    });
+});

package/dist/components.d.ts

@@ -0,0 +1,98 @@
+import type { BotNode } from "./ir.js";
+import type { ClickHandler } from "./types.js";
+/**
+ * Anything that can appear as a child in the component tree: nested elements,
+ * text, numbers, and conditionals (`false` / `null` / `undefined` render
+ * nothing), plus arrays thereof.
+ */
+export type BotChildren = BotNode | string | number | boolean | null | undefined | BotChildren[];
+/** Mixin for the container components that wrap children. */
+interface WithChildren {
+    children?: BotChildren;
+}
+export interface MessageProps extends WithChildren {
+    /** Accent color (hex, e.g. `#27AE60`) for the message's colored rail. */
+    accent?: string;
+}
+export interface HeaderProps extends WithChildren {
+}
+export interface SectionProps extends WithChildren {
+}
+export interface MarkdownProps extends WithChildren {
+}
+export interface FieldsProps extends WithChildren {
+}
+export interface FieldProps extends WithChildren {
+}
+export interface ContextProps extends WithChildren {
+}
+export interface ActionsProps extends WithChildren {
+}
+export interface ImageProps {
+    /** Image URL. */
+    url: string;
+    /** Alternative text for accessibility. */
+    alt?: string;
+}
+/** `<Divider />` takes no props or children. */
+export type DividerProps = {
+    children?: never;
+};
+export interface ButtonProps<TValue = unknown> extends WithChildren {
+    /**
+     * Inline handler run when the button is clicked (bound by the action
+     * registry). Its `ctx.action.value` is typed as `TValue`, inferred from
+     * `value`.
+     */
+    onClick?: ClickHandler<TValue>;
+    /** Value echoed back to `onClick`/`awaitChoice` on click; drives `TValue`. */
+    value?: TValue;
+    /** Slack button accent. */
+    style?: "primary" | "danger";
+}
+export interface SelectOption {
+    label: string;
+    value: string;
+}
+export interface SelectProps {
+    /** Handler run on selection; `ctx.action.value` is the chosen option's `value`. */
+    onSelect?: ClickHandler<string>;
+    placeholder?: string;
+    options: SelectOption[];
+}
+export interface InputProps {
+    /** Handler run on submit; `ctx.action.value` is the entered text. */
+    onSubmit?: ClickHandler<string>;
+    placeholder?: string;
+    multiline?: boolean;
+    name?: string;
+}
+export interface TableColumn {
+    header: string;
+    align?: "left" | "center" | "right";
+}
+export interface TableProps extends WithChildren {
+    columns?: TableColumn[];
+}
+export interface RowProps extends WithChildren {
+}
+export interface CellProps extends WithChildren {
+}
+export declare const Message: (props: MessageProps) => BotNode;
+export declare const Header: (props: HeaderProps) => BotNode;
+export declare const Section: (props: SectionProps) => BotNode;
+export declare const Markdown: (props: MarkdownProps) => BotNode;
+export declare const Field: (props: FieldProps) => BotNode;
+export declare const Fields: (props: FieldsProps) => BotNode;
+export declare const Context: (props: ContextProps) => BotNode;
+export declare const Actions: (props: ActionsProps) => BotNode;
+export declare const Image: (props: ImageProps) => BotNode;
+export declare const Divider: (props: DividerProps) => BotNode;
+export declare const Row: (props: RowProps) => BotNode;
+export declare const Cell: (props: CellProps) => BotNode;
+export declare function Button<TValue = unknown>(props: ButtonProps<TValue>): BotNode;
+export declare function Select(props: SelectProps): BotNode;
+export declare function Input(props: InputProps): BotNode;
+export declare function Table(props: TableProps): BotNode;
+export {};
+//# sourceMappingURL=components.d.ts.map

package/dist/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../src/components.tsx"],"names":[],"mappings":"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"}

package/dist/components.js

@@ -0,0 +1,31 @@
+// ---- Components ----------------------------------------------------------
+// `intrinsic` produces a typed component that lowers `<X .../>` to an IR node
+// of the given `type`; the generic `P` is what gives each tag its prop type.
+const intrinsic = (type) => (props) => ({
+    type,
+    props: (props ?? {}),
+});
+export const Message = intrinsic("message");
+export const Header = intrinsic("header");
+export const Section = intrinsic("section");
+export const Markdown = intrinsic("markdown");
+export const Field = intrinsic("field");
+export const Fields = intrinsic("fields");
+export const Context = intrinsic("context");
+export const Actions = intrinsic("actions");
+export const Image = intrinsic("image");
+export const Divider = intrinsic("divider");
+export const Row = intrinsic("row");
+export const Cell = intrinsic("cell");
+export function Button(props) {
+    return { type: "button", props: props };
+}
+export function Select(props) {
+    return { type: "select", props: props };
+}
+export function Input(props) {
+    return { type: "input", props: props };
+}
+export function Table(props) {
+    return { type: "table", props: props };
+}

package/dist/components.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=components.test.d.ts.map

package/dist/components.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.test.d.ts","sourceRoot":"","sources":["../src/components.test.tsx"],"names":[],"mappings":""}

package/dist/components.test.js

@@ -0,0 +1,71 @@
+import { jsx as _jsx, jsxs as _jsxs } from "@copilotkit/bot-ui/jsx-runtime";
+import { describe, it, expect } from "vitest";
+import { renderToIR } from "./render.js";
+import { Message, Header, Section, Actions, Button, Divider, Table, Row, Cell, Image, Select, } from "./components.js";
+/**
+ * Compile-time prop type guards. This arrow is never invoked — the assertions
+ * are validated by `tsc` (build / check-types). Each `@ts-expect-error` fails
+ * the type-check if the props ever stop being enforced (regression guard); the
+ * trailing valid cases fail if a legitimate usage is wrongly rejected.
+ */
+const __typeGuards = () => {
+    // @ts-expect-error unknown prop on a container component
+    _jsx(Section, { bogus: 1 });
+    // @ts-expect-error invalid Button.style value
+    _jsx(Button, { style: "nope", children: "x" });
+    // @ts-expect-error excess prop on Button
+    _jsx(Button, { extra: true, children: "x" });
+    // @ts-expect-error Message.accent must be a string
+    _jsx(Message, { accent: 1 });
+    // @ts-expect-error Divider takes no children
+    _jsx(Divider, { children: "x" });
+    // @ts-expect-error Image.url is required
+    _jsx(Image, { alt: "x" });
+    // @ts-expect-error Select.options is required
+    _jsx(Select, { placeholder: "p" });
+    // Valid usages — must type-check cleanly.
+    _jsxs(Section, { children: ["hello ", 42] });
+    _jsx(Message, { accent: "#27AE60", children: _jsx(Header, { children: "Title" }) });
+    _jsx(Button, { style: "primary", value: { ok: true }, onClick: () => { }, children: "Go" });
+    _jsx(Image, { url: "https://example.com/x.png", alt: "x" });
+    // Button.value flows into onClick: ctx.action.value is inferred, not unknown.
+    _jsx(Button, { value: { confirmed: true }, onClick: (ctx) => {
+            ctx.action.value?.confirmed;
+            // @ts-expect-error 'nope' is not on the inferred value type
+            ctx.action.value?.nope;
+        }, children: "Confirm" });
+};
+void __typeGuards;
+describe("component vocabulary", () => {
+    it("Message wraps children with intrinsic type 'message'", () => {
+        const out = renderToIR(_jsx(Message, { children: _jsx(Header, { children: "Hi" }) }));
+        expect(out[0].type).toBe("message");
+    });
+    it("Button carries onClick and style in props", () => {
+        const fn = () => { };
+        const out = renderToIR(_jsx(Actions, { children: _jsx(Button, { onClick: fn, style: "primary", children: "Go" }) }));
+        const actions = out[0];
+        const button = actions.props.children[0];
+        expect(button.type).toBe("button");
+        expect(button.props.onClick).toBe(fn);
+        expect(button.props.style).toBe("primary");
+    });
+    it("Divider renders with no children", () => {
+        const out = renderToIR(_jsx(Divider, {}));
+        expect(out[0]).toMatchObject({ type: "divider" });
+    });
+    it("Table carries columns and nests Row→Cell→text children", () => {
+        const out = renderToIR(_jsx(Table, { columns: [{ header: "Name" }, { header: "Status", align: "center" }], children: _jsxs(Row, { children: [_jsx(Cell, { children: "Ana" }), _jsx(Cell, { children: "Active" })] }) }));
+        const table = out[0];
+        expect(table.type).toBe("table");
+        expect(table.props.columns.length).toBe(2);
+        const rows = table.props.children;
+        const row = rows[0];
+        expect(row.type).toBe("row");
+        const cells = row.props.children;
+        expect(cells.length).toBe(2);
+        expect(cells[0].type).toBe("cell");
+        const cellText = cells[0].props.children[0];
+        expect(cellText).toMatchObject({ type: "text", props: { value: "Ana" } });
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./ir.js";
+export * from "./render.js";
+export * from "./types.js";
+export * from "./bind.js";
+export * from "./components.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./ir.js";
+export * from "./render.js";
+export * from "./types.js";
+export * from "./bind.js";
+export * from "./components.js";

package/dist/ir.d.ts

@@ -0,0 +1,11 @@
+export type ComponentFn = (props: Record<string, unknown>) => BotNode | BotNode[] | string | null;
+export interface BotNode {
+    type: string | ComponentFn | symbol;
+    props: Record<string, unknown>;
+    key?: string | number;
+}
+export type Renderable = string | BotNode | BotNode[] | {
+    raw: unknown;
+};
+export declare const Fragment: unique symbol;
+//# sourceMappingURL=ir.d.ts.map

package/dist/ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.d.ts","sourceRoot":"","sources":["../src/ir.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,CACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC3B,OAAO,GAAG,OAAO,EAAE,GAAG,MAAM,GAAG,IAAI,CAAC;AACzC,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IACpC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AACD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,EAAE,GAAG;IAAE,GAAG,EAAE,OAAO,CAAA;CAAE,CAAC;AACzE,eAAO,MAAM,QAAQ,EAAE,OAAO,MAAiD,CAAC"}

package/dist/ir.js

@@ -0,0 +1 @@
+export const Fragment = Symbol.for("copilotkit.bot-ui.Fragment");

package/dist/jsx-dev-runtime.d.ts

@@ -0,0 +1,7 @@
+export { jsx, jsxs, Fragment } from "./jsx-runtime.js";
+export declare function jsxDEV(type: any, props: any, key?: any): {
+    type: any;
+    props: any;
+    key: any;
+};
+//# sourceMappingURL=jsx-dev-runtime.d.ts.map

package/dist/jsx-dev-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-dev-runtime.d.ts","sourceRoot":"","sources":["../src/jsx-dev-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACvD,wBAAgB,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG;;;;EAEtD"}

package/dist/jsx-dev-runtime.js

@@ -0,0 +1,4 @@
+export { jsx, jsxs, Fragment } from "./jsx-runtime.js";
+export function jsxDEV(type, props, key) {
+    return { type, props: props ?? {}, key };
+}

package/dist/jsx-runtime.d.ts

@@ -0,0 +1,30 @@
+import { Fragment, type BotNode } from "./ir.js";
+export { Fragment };
+export declare function jsx(type: string | ((props: never) => unknown) | symbol, props: Record<string, unknown> | null, key?: string | number): BotNode;
+export declare const jsxs: typeof jsx;
+/**
+ * The JSX type contract for this runtime. Declaring it here (rather than
+ * relying on a global `JSX` namespace) is what makes the compiler actually
+ * check element props: unknown attributes and bad children are errors, and
+ * every element returns an {@link BotNode}.
+ *
+ * Resolved by TypeScript because `jsxImportSource` points at this package, so
+ * `<Section foo={1} />` is checked against `SectionProps` with excess-property
+ * checking — there are no lowercase intrinsic tags.
+ */
+export declare namespace JSX {
+    /** The result of evaluating a JSX expression. */
+    type Element = BotNode;
+    /** Tells TypeScript which prop receives nested children. */
+    interface ElementChildrenAttribute {
+        children: {};
+    }
+    /** Props implicitly accepted by every element. */
+    interface IntrinsicAttributes {
+        key?: string | number;
+    }
+    /** No lowercase intrinsic tags — the vocabulary is the capitalized components. */
+    interface IntrinsicElements {
+    }
+}
+//# sourceMappingURL=jsx-runtime.d.ts.map

package/dist/jsx-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-runtime.d.ts","sourceRoot":"","sources":["../src/jsx-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,CAAC;AAEpB,wBAAgB,GAAG,CACjB,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,GAAG,MAAM,EACnD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACrC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GACpB,OAAO,CAET;AACD,eAAO,MAAM,IAAI,YAAM,CAAC;AAExB;;;;;;;;;GASG;AACH,yBAAiB,GAAG,CAAC;IACnB,iDAAiD;IACjD,KAAY,OAAO,GAAG,OAAO,CAAC;IAC9B,4DAA4D;IAC5D,UAAiB,wBAAwB;QACvC,QAAQ,EAAE,EAAE,CAAC;KACd;IACD,kDAAkD;IAClD,UAAiB,mBAAmB;QAClC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KACvB;IACD,kFAAkF;IAClF,UAAiB,iBAAiB;KAAG;CACtC"}

package/dist/jsx-runtime.js

@@ -0,0 +1,6 @@
+import { Fragment } from "./ir.js";
+export { Fragment };
+export function jsx(type, props, key) {
+    return { type: type, props: props ?? {}, key };
+}
+export const jsxs = jsx;

package/dist/jsx-runtime.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=jsx-runtime.test.d.ts.map

package/dist/jsx-runtime.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-runtime.test.d.ts","sourceRoot":"","sources":["../src/jsx-runtime.test.ts"],"names":[],"mappings":""}

package/dist/jsx-runtime.test.js

@@ -0,0 +1,17 @@
+import { describe, it, expect } from "vitest";
+import { jsx, jsxs, Fragment } from "./jsx-runtime.js";
+describe("jsx factory", () => {
+    it("builds an BotNode with type and props", () => {
+        const node = jsx("section", { children: "hi" });
+        expect(node.type).toBe("section");
+        expect(node.props.children).toBe("hi");
+    });
+    it("jsxs keeps array children", () => {
+        const node = jsxs("actions", { children: ["a", "b"] });
+        expect(Array.isArray(node.props.children)).toBe(true);
+    });
+    it("Fragment is a stable sentinel", () => {
+        const node = jsx(Fragment, { children: ["a", "b"] });
+        expect(node.type).toBe(Fragment);
+    });
+});

package/dist/render.d.ts

@@ -0,0 +1,3 @@
+import { type BotNode, type Renderable } from "./ir.js";
+export declare function renderToIR(ui: Renderable): BotNode[];
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAkClE,wBAAgB,UAAU,CAAC,EAAE,EAAE,UAAU,GAAG,OAAO,EAAE,CAKpD"}

package/dist/render.js

@@ -0,0 +1,37 @@
+import { Fragment } from "./ir.js";
+function isBotNode(v) {
+    return typeof v === "object" && v !== null && "type" in v && "props" in v;
+}
+function expand(node) {
+    if (node == null || node === false || node === true)
+        return [];
+    if (typeof node === "string" || typeof node === "number") {
+        return [{ type: "text", props: { value: String(node) } }];
+    }
+    if (Array.isArray(node))
+        return node.flatMap(expand);
+    if (!isBotNode(node))
+        return [];
+    if (node.type === Fragment)
+        return expand(node.props.children);
+    if (typeof node.type === "function") {
+        return expand(node.type(node.props));
+    }
+    const { children, ...rest } = node.props;
+    const expandedChildren = children === undefined ? undefined : expand(children);
+    return [
+        {
+            type: node.type,
+            props: expandedChildren === undefined
+                ? rest
+                : { ...rest, children: expandedChildren },
+            key: node.key,
+        },
+    ];
+}
+export function renderToIR(ui) {
+    if (typeof ui === "object" && ui !== null && "raw" in ui) {
+        return [{ type: "raw", props: { value: ui.raw } }];
+    }
+    return expand(ui);
+}

package/dist/render.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=render.test.d.ts.map

package/dist/render.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.test.d.ts","sourceRoot":"","sources":["../src/render.test.tsx"],"names":[],"mappings":""}

package/dist/render.test.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "@copilotkit/bot-ui/jsx-runtime";
+import { describe, it, expect } from "vitest";
+import { renderToIR } from "./render.js";
+function Card(props) {
+    return { type: "section", props: { children: props.title } };
+}
+describe("renderToIR", () => {
+    it("wraps a bare string into a text node", () => {
+        expect(renderToIR("hi")).toEqual([
+            { type: "text", props: { value: "hi" } },
+        ]);
+    });
+    it("expands a component function with its props", () => {
+        const out = renderToIR(_jsx(Card, { title: "Flights" }));
+        expect(out).toEqual([
+            {
+                type: "section",
+                props: { children: [{ type: "text", props: { value: "Flights" } }] },
+            },
+        ]);
+    });
+    it("flattens Fragment children and nested components", () => {
+        const out = renderToIR(_jsxs(_Fragment, { children: [_jsx(Card, { title: "A" }), _jsx(Card, { title: "B" })] }));
+        expect(out.map((n) => n.type)).toEqual(["section", "section"]);
+    });
+    it("wraps string children inside intrinsic nodes recursively", () => {
+        const out = renderToIR({ type: "actions", props: { children: ["x"] } });
+        const actions = out[0];
+        expect(actions.props.children[0]).toEqual({
+            type: "text",
+            props: { value: "x" },
+        });
+    });
+    it("passes {raw} through as a raw node", () => {
+        expect(renderToIR({ raw: [{ block: 1 }] })).toEqual([
+            { type: "raw", props: { value: [{ block: 1 }] } },
+        ]);
+    });
+});

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+export interface MessageRef {
+    id: string;
+    [k: string]: unknown;
+}
+export interface PlatformUser {
+    id: string;
+    name?: string;
+    handle?: string;
+    email?: string;
+}
+export interface IncomingMessage {
+    text: string;
+    user: PlatformUser;
+    ref: MessageRef;
+    platform: string;
+}
+export interface ThreadMessage {
+    user?: PlatformUser;
+    text: string;
+    ts?: string;
+    isBot?: boolean;
+}
+export interface Thread {
+    readonly platform: string;
+    post(ui: unknown): Promise<MessageRef>;
+    update(ref: MessageRef, ui: unknown): Promise<MessageRef>;
+    delete(ref: MessageRef): Promise<void>;
+    /**
+     * Post a picker and block until an interaction resolves it to the clicked
+     * button's `value`. Pass the expected value type, e.g.
+     * `awaitChoice<{ confirmed: boolean }>(<Picker/>)`.
+     */
+    awaitChoice<T = unknown>(ui: unknown): Promise<T>;
+    runAgent(input?: unknown): Promise<MessageRef | undefined>;
+    resume(value: unknown): Promise<MessageRef | undefined>;
+    stream(src: string | AsyncIterable<string>): Promise<MessageRef>;
+    postFile(args: {
+        bytes: Uint8Array;
+        filename: string;
+        title?: string;
+        altText?: string;
+    }): Promise<{
+        ok: boolean;
+        fileId?: string;
+        error?: string;
+    }>;
+    /** Read the conversation's messages (capability-gated; returns `[]` when the adapter can't read history). */
+    getMessages(): Promise<ThreadMessage[]>;
+    /** Resolve a platform user by a free-form query (capability-gated; returns `undefined` when unsupported). */
+    lookupUser(query: string): Promise<PlatformUser | undefined>;
+}
+export interface InteractionContext<TValue = unknown> {
+    thread: Thread;
+    message: IncomingMessage;
+    /** The clicked control: its opaque `id` and the `value` it carried (typed as `TValue`). */
+    action: {
+        id: string;
+        value?: TValue;
+    };
+    values: Record<string, unknown>;
+    user: PlatformUser;
+    platform: string;
+}
+export type ClickHandler<TValue = unknown> = (ctx: InteractionContext<TValue>) => void | Promise<void>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AACD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,GAAG,EAAE,UAAU,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AACD,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,IAAI,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACvC,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1D,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC;;;;OAIG;IACH,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IAC3D,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IACxD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACjE,QAAQ,CAAC,IAAI,EAAE;QACb,KAAK,EAAE,UAAU,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9D,6GAA6G;IAC7G,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACxC,6GAA6G;IAC7G,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;CAC9D;AACD,MAAM,WAAW,kBAAkB,CAAC,MAAM,GAAG,OAAO;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,eAAe,CAAC;IACzB,2FAA2F;IAC3F,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,MAAM,YAAY,CAAC,MAAM,GAAG,OAAO,IAAI,CAC3C,GAAG,EAAE,kBAAkB,CAAC,MAAM,CAAC,KAC5B,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@copilotkit/bot-ui",
+  "version": "0.0.1",
+  "description": "JSX runtime, IR, and cross-platform component vocabulary for CopilotKit bots.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CopilotKit/CopilotKit.git"
+  },
+  "homepage": "https://github.com/CopilotKit/CopilotKit",
+  "keywords": [
+    "ai",
+    "agent",
+    "bot",
+    "jsx",
+    "block-kit",
+    "ui",
+    "copilotkit",
+    "ag-ui"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./jsx-runtime": {
+      "types": "./dist/jsx-runtime.d.ts",
+      "import": "./dist/jsx-runtime.js"
+    },
+    "./jsx-dev-runtime": {
+      "types": "./dist/jsx-dev-runtime.d.ts",
+      "import": "./dist/jsx-dev-runtime.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@copilotkit/shared": "^1.59.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.3",
+    "@copilotkit/typescript-config": "^1.55.0-next.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check-types": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.check.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "publint": "publint .",
+    "attw": "attw --pack . --profile esm-only"
+  }
+}