From 75772101770fdab7562efeadf399518eec0dc1c9 Mon Sep 17 00:00:00 2001
From: MarioCadenas <MarioCadenas@users.noreply.github.com>
Date: Tue, 20 Oct 2026 14:26:08 +0200
Subject: [PATCH 1/6] feat(appkit): add dev-only design plugin and ui-only
 template

- design() plugin (beta): in development serves a /design canvas that
  renders every PascalCase export under client/src/design/, and injects a
  click-to-select picker into the canvas and every app page. Picks are traced
  via the existing data-source transform plus the React fiber (component,
  owner stack, props), screenshotted, and persisted with an optional note to
  .appkit/design-selection.json (GET/POST/DELETE /api/design/selection).
  Outside development it mounts nothing and /design returns 404.
- Plugins can contribute dev-server Vite plugins via an optional
  vitePlugins() hook.
- appkit-ui/react/beta: DesignCanvas, DesignPicker, mountDesignPicker.
- Template: gated client/src/design example, .appkit/ gitignored, and a
  ui-only app template (server + design).

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
---
 docs/docs/api/appkit/Variable.design.md       |   5 +
 docs/docs/api/appkit/index.md                 |   1 +
 docs/docs/api/appkit/typedoc-sidebar.ts       |   5 +
 docs/docs/plugins/design.md                   |  84 ++++++
 docs/static/appkit-ui/styles.gen.css          |  18 ++
 packages/appkit-ui/src/react/beta.ts          |   6 +
 .../src/react/design/design-canvas.tsx        |  74 ++++++
 .../src/react/design/design-picker.tsx        | 240 ++++++++++++++++++
 .../appkit-ui/src/react/design/inspect.ts     | 140 ++++++++++
 .../src/plugins/beta-exports.generated.ts     |   1 +
 packages/appkit/src/plugins/design/index.ts   |  97 +++++++
 .../appkit/src/plugins/design/manifest.json   |  11 +
 packages/appkit/src/plugins/design/store.ts   | 141 ++++++++++
 .../src/plugins/design/tests/design.test.ts   |  93 +++++++
 .../appkit/src/plugins/design/vite-plugin.ts  |  84 ++++++
 packages/appkit/src/plugins/server/index.ts   |   5 +
 .../src/plugins/server/vite-dev-server.ts     |   4 +-
 packages/shared/src/plugin.ts                 |   3 +
 template/README.md.tmpl                       |   3 +
 template/_gitignore                           |   1 +
 template/appkit.plugins.json                  |  11 +
 template/client/src/design/Example.tsx        |  22 ++
 tools/generate-app-templates.ts               |   6 +
 23 files changed, 1054 insertions(+), 1 deletion(-)
 create mode 100644 docs/docs/api/appkit/Variable.design.md
 create mode 100644 docs/docs/plugins/design.md
 create mode 100644 packages/appkit-ui/src/react/design/design-canvas.tsx
 create mode 100644 packages/appkit-ui/src/react/design/design-picker.tsx
 create mode 100644 packages/appkit-ui/src/react/design/inspect.ts
 create mode 100644 packages/appkit/src/plugins/design/index.ts
 create mode 100644 packages/appkit/src/plugins/design/manifest.json
 create mode 100644 packages/appkit/src/plugins/design/store.ts
 create mode 100644 packages/appkit/src/plugins/design/tests/design.test.ts
 create mode 100644 packages/appkit/src/plugins/design/vite-plugin.ts
 create mode 100644 template/client/src/design/Example.tsx

diff --git a/docs/docs/api/appkit/Variable.design.md b/docs/docs/api/appkit/Variable.design.md
new file mode 100644
index 000000000..eed131b5d
--- /dev/null
+++ b/docs/docs/api/appkit/Variable.design.md
@@ -0,0 +1,5 @@
+# Variable: design
+
+```ts
+const design: ToPlugin<typeof DesignPlugin, BasePluginConfig, "design">;
+```
diff --git a/docs/docs/api/appkit/index.md b/docs/docs/api/appkit/index.md
index ee6db8b67..fab63f199 100644
--- a/docs/docs/api/appkit/index.md
+++ b/docs/docs/api/appkit/index.md
@@ -190,6 +190,7 @@ surface with `@databricks/appkit/beta`. Not meant for application imports.
 | ------ | ------ |
 | [agents](Variable.agents.md) | Plugin factory for the agents plugin. Discovers agents from `server/agents/<id>/agent.{ts,md}` by default (markdown still in `config/agents/` is read as a deprecated fallback), resolves toolkits/tools from registered plugins, exposes the `appkit.agents.*` runtime API and mounts `POST /invocations` and `POST /responses` (aliased non-streaming invoke endpoints) plus `POST /chat` (streaming, HITL-capable). |
 | [aiSearch](Variable.aiSearch.md) | - |
+| [design](Variable.design.md) | - |
 | [READ\_ACTIONS](Variable.READ_ACTIONS.md) | Actions that only read data. |
 | [sql](Variable.sql.md) | SQL helper namespace |
 | [SUPERVISOR\_EXTENSION\_KEY](Variable.SUPERVISOR_EXTENSION_KEY.md) | Namespace key under which the adapter reads its hosted-tool payload from [AgentInput.extensions](Interface.AgentInput.md#extensions). Exported so the agents plugin and standalone `runAgent` (the producers) can write under the same key the adapter reads. |
diff --git a/docs/docs/api/appkit/typedoc-sidebar.ts b/docs/docs/api/appkit/typedoc-sidebar.ts
index dca9af23b..8f7b03f36 100644
--- a/docs/docs/api/appkit/typedoc-sidebar.ts
+++ b/docs/docs/api/appkit/typedoc-sidebar.ts
@@ -847,6 +847,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Variable.aiSearch",
           label: "aiSearch"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Variable.design",
+          label: "design"
+        },
         {
           type: "doc",
           id: "api/appkit/Variable.READ_ACTIONS",
diff --git a/docs/docs/plugins/design.md b/docs/docs/plugins/design.md
new file mode 100644
index 000000000..0fabca338
--- /dev/null
+++ b/docs/docs/plugins/design.md
@@ -0,0 +1,84 @@
+---
+sidebar_position: 20
+---
+
+# Design plugin
+
+<!-- AUTO-GENERATED: stability-banner-start -->
+:::warning Beta plugin
+This plugin is currently **beta**. APIs may change between minor releases. Import from `@databricks/appkit/beta`. See [Plugin Stability Tiers](./stability.md).
+:::
+<!-- AUTO-GENERATED: stability-banner-end -->
+
+A dev-only design canvas and element picker for working with a coding agent. It only runs with `NODE_ENV=development`. In any other environment it does nothing, and `/design` returns 404.
+
+## Basic usage
+
+```ts
+import { createApp, server } from "@databricks/appkit";
+import { design } from "@databricks/appkit/beta";
+
+await createApp({
+  plugins: [server(), design()],
+});
+```
+
+## The `/design` canvas
+
+`/design` renders every PascalCase export of every file under `client/src/design/`, with no props, one frame each. Put two kinds of components there:
+
+- **Drafts**: design-only UI that may later be moved into the real app.
+- **Previews**: wrappers that render the app's real components with mock data.
+
+```tsx
+// client/src/design/OrderCard.preview.tsx
+import { OrderCard } from "../components/OrderCard";
+
+export function OrderCardShipped() {
+  return <OrderCard order={{ id: "42", status: "shipped", total: 99 }} />;
+}
+```
+
+A frame that throws shows its error in place. It doesn't break the rest of the canvas.
+
+## Selecting elements
+
+In development, a **Select** button appears in the bottom-right corner of the canvas and of every app page. Click it, then click elements to add or remove them (Escape stops selecting). Add an optional note and click **Send to agent**.
+
+Each element is traced back to its source through the `data-source="file:line:col"` attribute that the dev server adds to native JSX elements. The nearest React component and its props come from React's fiber tree.
+
+## Handing selections to the agent
+
+Each send is appended to `.appkit/design-selection.json`, so selections survive restarts. Add `.appkit/` to `.gitignore`.
+
+```json
+{
+  "selections": [
+    {
+      "id": "80b453fd-…",
+      "ts": "2026-10-20T12:22:45.026Z",
+      "note": "make the button primary",
+      "url": "/design",
+      "elements": [
+        {
+          "component": "Button",
+          "stack": ["Button", "ProbeCard"],
+          "source": "client/src/design/Probe.tsx:5:4",
+          "props": { "variant": "secondary" },
+          "tag": "button",
+          "text": "Probe button",
+          "screenshot": ".appkit/design-screenshots/80b453fd-…-0.jpeg"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Screenshots are saved as image files next to it, so an agent can open them directly. The agent can read the file itself, or use these routes:
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| `GET` | `/api/design/selection` | Read all pending selections |
+| `POST` | `/api/design/selection` | Add a selection (used by the picker) |
+| `DELETE` | `/api/design/selection` | Clear selections and screenshots once applied |
diff --git a/docs/static/appkit-ui/styles.gen.css b/docs/static/appkit-ui/styles.gen.css
index 0cc301c72..145f8db68 100644
--- a/docs/static/appkit-ui/styles.gen.css
+++ b/docs/static/appkit-ui/styles.gen.css
@@ -467,6 +467,9 @@
   .mb-4 {
     margin-bottom: calc(var(--spacing) * 4);
   }
+  .mb-6 {
+    margin-bottom: calc(var(--spacing) * 6);
+  }
   .-ml-1 {
     margin-left: calc(var(--spacing) * -1);
   }
@@ -711,6 +714,9 @@
   .min-h-\[100vh\] {
     min-height: 100vh;
   }
+  .min-h-screen {
+    min-height: 100vh;
+  }
   .min-h-svh {
     min-height: 100svh;
   }
@@ -1011,6 +1017,9 @@
   .touch-none {
     touch-action: none;
   }
+  .resize {
+    resize: both;
+  }
   .resize-none {
     resize: none;
   }
@@ -1119,6 +1128,9 @@
   .gap-7 {
     gap: calc(var(--spacing) * 7);
   }
+  .gap-8 {
+    gap: calc(var(--spacing) * 8);
+  }
   .gap-\[--spacing\(var\(--gap\)\)\] {
     gap: calc(var(--spacing) * var(--gap));
   }
@@ -1374,6 +1386,12 @@
       background-color: color-mix(in oklab, var(--muted) 30%, transparent);
     }
   }
+  .bg-muted\/40 {
+    background-color: var(--muted);
+    @supports (color: color-mix(in lab, red, red)) {
+      background-color: color-mix(in oklab, var(--muted) 40%, transparent);
+    }
+  }
   .bg-muted\/50 {
     background-color: var(--muted);
     @supports (color: color-mix(in lab, red, red)) {
diff --git a/packages/appkit-ui/src/react/beta.ts b/packages/appkit-ui/src/react/beta.ts
index 5b1053b14..762a0c7b1 100644
--- a/packages/appkit-ui/src/react/beta.ts
+++ b/packages/appkit-ui/src/react/beta.ts
@@ -75,3 +75,9 @@ export type {
   UseDatabaseWriteOptions,
   UseDatabaseWriteState,
 } from "./hooks/use-database-write";
+
+// Design canvas + element picker. Track the dev-only `design` plugin, which
+// ships at beta from '@databricks/appkit/beta' and mounts both for you.
+export { DesignCanvas, type DesignCanvasProps } from "./design/design-canvas";
+export { DesignPicker, mountDesignPicker } from "./design/design-picker";
+export type { DesignElementInfo } from "./design/inspect";
diff --git a/packages/appkit-ui/src/react/design/design-canvas.tsx b/packages/appkit-ui/src/react/design/design-canvas.tsx
new file mode 100644
index 000000000..1b89a49f5
--- /dev/null
+++ b/packages/appkit-ui/src/react/design/design-canvas.tsx
@@ -0,0 +1,74 @@
+import { Component, type ComponentType, type ReactNode } from "react";
+
+/** Props for {@link DesignCanvas}. */
+export interface DesignCanvasProps {
+  /** `import.meta.glob` result: module path → module exports. */
+  modules: Record<string, Record<string, unknown>>;
+}
+
+class Boundary extends Component<{ children: ReactNode }, { error?: Error }> {
+  state: { error?: Error } = {};
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+  render() {
+    if (this.state.error) {
+      return (
+        <pre className="text-destructive text-xs whitespace-pre-wrap">
+          {this.state.error.message}
+        </pre>
+      );
+    }
+    return this.props.children;
+  }
+}
+
+/**
+ * Renders every PascalCase export of every module under `client/src/design/`
+ * with no props, one frame each. Drafts and previews (real components wrapped
+ * with mock data) are both just zero-prop components in that folder.
+ *
+ * Served by the `design()` plugin at `/design` in development.
+ */
+export function DesignCanvas({ modules }: DesignCanvasProps) {
+  const frames = Object.entries(modules)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .flatMap(([file, mod]) =>
+      Object.entries(mod)
+        .filter(
+          ([name, value]) => /^[A-Z]/.test(name) && typeof value === "function",
+        )
+        .map(([name, value]) => ({
+          id: `${file}#${name}`,
+          label: `${file.replace(/^\/src\/design\//, "")} · ${name}`,
+          Frame: value as ComponentType,
+        })),
+    );
+
+  return (
+    <div className="min-h-screen bg-muted/40 p-8">
+      <h1 className="mb-6 text-lg font-semibold">Design canvas</h1>
+      {frames.length === 0 ? (
+        <p className="text-muted-foreground text-sm">
+          No designs yet. Export components from files in{" "}
+          <code>client/src/design/</code> and they show up here.
+        </p>
+      ) : (
+        <div className="flex flex-col gap-8">
+          {frames.map(({ id, label, Frame }) => (
+            <section key={id}>
+              <h2 className="text-muted-foreground mb-2 font-mono text-xs">
+                {label}
+              </h2>
+              <div className="bg-background rounded-lg border p-6">
+                <Boundary>
+                  <Frame />
+                </Boundary>
+              </div>
+            </section>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/appkit-ui/src/react/design/design-picker.tsx b/packages/appkit-ui/src/react/design/design-picker.tsx
new file mode 100644
index 000000000..027f3ae27
--- /dev/null
+++ b/packages/appkit-ui/src/react/design/design-picker.tsx
@@ -0,0 +1,240 @@
+import { type CSSProperties, useEffect, useReducer, useState } from "react";
+import { createRoot } from "react-dom/client";
+
+import {
+  captureElement,
+  type DesignElementInfo,
+  inspectElement,
+} from "./inspect";
+
+/** Endpoint the `design()` plugin mounts in development. */
+const SELECTION_ENDPOINT = "/api/design/selection";
+const ROOT_ID = "appkit-design-picker";
+/** Same violet as the `<Variants>` picker, so dev chrome reads as dev chrome. */
+const ACCENT = "#8b5cf6";
+
+type Status = "idle" | "sending" | "sent" | "error";
+
+interface Picked {
+  el: Element;
+  info: DesignElementInfo;
+}
+
+function box(el: Element, style: CSSProperties, key?: number) {
+  const r = el.getBoundingClientRect();
+  return (
+    <div
+      key={key}
+      style={{
+        position: "fixed",
+        top: r.top,
+        left: r.left,
+        width: r.width,
+        height: r.height,
+        pointerEvents: "none",
+        borderRadius: 2,
+        ...style,
+      }}
+    />
+  );
+}
+
+const panel: CSSProperties = {
+  position: "fixed",
+  right: 16,
+  bottom: 64,
+  width: 320,
+  maxHeight: "60vh",
+  overflow: "auto",
+  background: "#fff",
+  color: "#111",
+  border: `1px solid ${ACCENT}`,
+  borderRadius: 8,
+  padding: 12,
+  font: "12px/1.4 system-ui, sans-serif",
+  boxShadow: "0 8px 24px rgba(0,0,0,.18)",
+};
+
+const button: CSSProperties = {
+  background: ACCENT,
+  color: "#fff",
+  border: 0,
+  borderRadius: 6,
+  padding: "6px 12px",
+  font: "600 12px system-ui, sans-serif",
+  cursor: "pointer",
+};
+
+/**
+ * Dev-only click-to-select overlay. Toggle it with the floating button (or
+ * Escape to stop), click elements to add/remove them, add a note, and send the
+ * selection to the `design()` plugin for the coding agent to pick up.
+ *
+ * Injected into every page by the design plugin's dev server; you don't
+ * render it yourself.
+ */
+export function DesignPicker() {
+  const [active, setActive] = useState(false);
+  const [hovered, setHovered] = useState<Element | null>(null);
+  const [picked, setPicked] = useState<Picked[]>([]);
+  const [note, setNote] = useState("");
+  const [status, setStatus] = useState<Status>("idle");
+  // Outlines are positioned from live rects; re-render when the page moves.
+  const [, rerender] = useReducer((n: number) => n + 1, 0);
+
+  useEffect(() => {
+    window.addEventListener("scroll", rerender, true);
+    window.addEventListener("resize", rerender);
+    return () => {
+      window.removeEventListener("scroll", rerender, true);
+      window.removeEventListener("resize", rerender);
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!active) return;
+    const own = (t: EventTarget | null) =>
+      !(t instanceof Element) || !!t.closest(`#${ROOT_ID}`);
+    const onMove = (e: MouseEvent) =>
+      setHovered(own(e.target) ? null : (e.target as Element));
+    const onClick = (e: MouseEvent) => {
+      if (own(e.target)) return;
+      e.preventDefault();
+      e.stopPropagation();
+      const el = e.target as Element;
+      setStatus("idle");
+      setPicked((prev) =>
+        prev.some((p) => p.el === el)
+          ? prev.filter((p) => p.el !== el)
+          : [...prev, { el, info: inspectElement(el) }],
+      );
+    };
+    const onKey = (e: KeyboardEvent) => e.key === "Escape" && setActive(false);
+    document.addEventListener("mousemove", onMove, true);
+    document.addEventListener("click", onClick, true);
+    document.addEventListener("keydown", onKey, true);
+    return () => {
+      document.removeEventListener("mousemove", onMove, true);
+      document.removeEventListener("click", onClick, true);
+      document.removeEventListener("keydown", onKey, true);
+      setHovered(null);
+    };
+  }, [active]);
+
+  async function send() {
+    setStatus("sending");
+    try {
+      const elements = await Promise.all(
+        picked.map(async ({ el, info }) => ({
+          ...info,
+          screenshot: await captureElement(el),
+        })),
+      );
+      const res = await fetch(SELECTION_ENDPOINT, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          elements,
+          note: note.trim() || undefined,
+          url: location.pathname,
+        }),
+      });
+      if (!res.ok) throw new Error(String(res.status));
+      setPicked([]);
+      setNote("");
+      setActive(false);
+      setStatus("sent");
+    } catch {
+      setStatus("error");
+    }
+  }
+
+  return (
+    <>
+      {active && hovered && box(hovered, { outline: `2px dashed ${ACCENT}` })}
+      {picked.map((p, i) =>
+        box(
+          p.el,
+          { outline: `2px solid ${ACCENT}`, background: `${ACCENT}22` },
+          i,
+        ),
+      )}
+      {(picked.length > 0 || status !== "idle") && (
+        <div style={panel}>
+          {picked.map((p, i) => (
+            <div
+              key={`${p.info.source}-${i}`}
+              style={{ display: "flex", gap: 8, marginBottom: 6 }}
+            >
+              <div style={{ flex: 1, minWidth: 0 }}>
+                <strong>{p.info.component ?? `<${p.info.tag}>`}</strong>
+                <div style={{ color: "#666", wordBreak: "break-all" }}>
+                  {p.info.source ?? "no source location"}
+                </div>
+              </div>
+              <button
+                type="button"
+                aria-label="Remove"
+                style={{ ...button, background: "transparent", color: "#666" }}
+                onClick={() =>
+                  setPicked((prev) => prev.filter((x) => x.el !== p.el))
+                }
+              >
+                ×
+              </button>
+            </div>
+          ))}
+          {picked.length > 0 && (
+            <>
+              <textarea
+                placeholder="Note for the agent (optional)"
+                value={note}
+                onChange={(e) => setNote(e.target.value)}
+                rows={3}
+                style={{
+                  width: "100%",
+                  boxSizing: "border-box",
+                  margin: "6px 0",
+                }}
+              />
+              <button
+                type="button"
+                style={button}
+                disabled={status === "sending"}
+                onClick={send}
+              >
+                {status === "sending"
+                  ? "Sending…"
+                  : `Send ${picked.length} to agent`}
+              </button>
+            </>
+          )}
+          {status === "sent" && <div>Sent. Ask your agent to apply it.</div>}
+          {status === "error" && (
+            <div style={{ color: "#b91c1c" }}>
+              Couldn't send. Is the design() plugin registered?
+            </div>
+          )}
+        </div>
+      )}
+      <button
+        type="button"
+        style={{ ...button, position: "fixed", right: 16, bottom: 16 }}
+        aria-pressed={active}
+        onClick={() => setActive((a) => !a)}
+      >
+        {active ? "Selecting… (Esc)" : "Select"}
+      </button>
+    </>
+  );
+}
+
+/** Mounts {@link DesignPicker} into its own root on `document.body`, once. */
+export function mountDesignPicker() {
+  if (document.getElementById(ROOT_ID)) return;
+  const host = document.createElement("div");
+  host.id = ROOT_ID;
+  host.style.cssText = "position:relative;z-index:2147483647";
+  document.body.appendChild(host);
+  createRoot(host).render(<DesignPicker />);
+}
diff --git a/packages/appkit-ui/src/react/design/inspect.ts b/packages/appkit-ui/src/react/design/inspect.ts
new file mode 100644
index 000000000..a25bf9ceb
--- /dev/null
+++ b/packages/appkit-ui/src/react/design/inspect.ts
@@ -0,0 +1,140 @@
+/** What the picker records for one selected DOM element. */
+export interface DesignElementInfo {
+  /** Nearest React component owning the element. */
+  component?: string;
+  /** Owning components, innermost first (up to {@link STACK_DEPTH}). */
+  stack?: string[];
+  /** `file:line:col` injected by AppKit's dev-server `data-source` transform. */
+  source?: string;
+  /** Serialized props of {@link component}. */
+  props?: Record<string, unknown>;
+  tag: string;
+  text?: string;
+}
+
+const STACK_DEPTH = 6;
+
+interface Fiber {
+  type: unknown;
+  return: Fiber | null;
+  memoizedProps?: Record<string, unknown>;
+}
+
+type ComponentType = {
+  displayName?: string;
+  name?: string;
+  render?: { name?: string };
+  type?: { name?: string };
+};
+
+function fiberOf(el: Element): Fiber | undefined {
+  const key = Object.keys(el).find((k) => k.startsWith("__reactFiber$"));
+  return key ? (el as unknown as Record<string, Fiber>)[key] : undefined;
+}
+
+/** Name of a function / memo / forwardRef component fiber, else undefined. */
+function componentName(type: unknown): string | undefined {
+  if (!type || (typeof type !== "function" && typeof type !== "object")) {
+    return undefined;
+  }
+  const t = type as ComponentType;
+  if (typeof type === "object" && !t.render && !t.type) return undefined;
+  return (
+    t.displayName || t.name || t.render?.name || t.type?.name || "Anonymous"
+  );
+}
+
+/** JSON-safe, size-bounded copy of component props (children dropped). */
+function serializeProps(value: unknown, depth = 0): unknown {
+  if (value == null || typeof value === "boolean" || typeof value === "number")
+    return value;
+  if (typeof value === "string") return value.slice(0, 200);
+  if (typeof value === "function") return "[function]";
+  if (typeof value !== "object") return String(value);
+  if ("$$typeof" in value) return "[element]";
+  if (depth >= 3) return "[…]";
+  if (Array.isArray(value))
+    return value.slice(0, 20).map((v) => serializeProps(v, depth + 1));
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (k === "children") continue;
+    out[k] = serializeProps(v, depth + 1);
+  }
+  return out;
+}
+
+export function inspectElement(el: Element): DesignElementInfo {
+  const stack: string[] = [];
+  let props: Record<string, unknown> | undefined;
+  for (let f = fiberOf(el) ?? null; f && stack.length < STACK_DEPTH;) {
+    const name = componentName(f.type);
+    if (name) {
+      if (stack.length === 0) {
+        props = serializeProps(f.memoizedProps ?? {}) as Record<
+          string,
+          unknown
+        >;
+      }
+      stack.push(name);
+    }
+    f = f.return;
+  }
+  const text = el.textContent?.trim().replace(/\s+/g, " ").slice(0, 120);
+  return {
+    component: stack[0],
+    ...(stack.length ? { stack } : {}),
+    source:
+      el.closest("[data-source]")?.getAttribute("data-source") ?? undefined,
+    ...(props ? { props } : {}),
+    tag: el.tagName.toLowerCase(),
+    ...(text ? { text } : {}),
+  };
+}
+
+function inlineStyles(src: Element, dst: Element) {
+  const cs = getComputedStyle(src);
+  let css = "";
+  for (let i = 0; i < cs.length; i++) {
+    css += `${cs[i]}:${cs.getPropertyValue(cs[i])};`;
+  }
+  dst.setAttribute("style", css);
+  for (let i = 0; i < src.children.length; i++) {
+    inlineStyles(src.children[i], dst.children[i]);
+  }
+}
+
+/**
+ * Rasterizes an element via an SVG `<foreignObject>` with inlined computed
+ * styles, as a JPEG data URL. Best-effort: returns undefined when the browser
+ * refuses (e.g. cross-origin images taint the canvas).
+ */
+// ponytail: no external images/fonts are embedded; add html-to-image if screenshots need pixel fidelity
+export async function captureElement(
+  el: Element,
+  maxWidth = 800,
+): Promise<string | undefined> {
+  try {
+    const { width, height } = el.getBoundingClientRect();
+    if (!width || !height) return undefined;
+    const clone = el.cloneNode(true) as Element;
+    inlineStyles(el, clone);
+    const xml = new XMLSerializer().serializeToString(clone);
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><foreignObject width="100%" height="100%">${xml}</foreignObject></svg>`;
+    const img = new Image();
+    img.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+    await img.decode();
+    const scale =
+      Math.min(1, maxWidth / width) * (window.devicePixelRatio || 1);
+    const canvas = document.createElement("canvas");
+    canvas.width = Math.ceil(width * scale);
+    canvas.height = Math.ceil(height * scale);
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return undefined;
+    ctx.fillStyle = "#fff";
+    ctx.fillRect(0, 0, canvas.width, canvas.height);
+    ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+    return canvas.toDataURL("image/jpeg", 0.85);
+  } catch {
+    return undefined;
+  }
+}
diff --git a/packages/appkit/src/plugins/beta-exports.generated.ts b/packages/appkit/src/plugins/beta-exports.generated.ts
index 7e556ebd9..aab6fb478 100644
--- a/packages/appkit/src/plugins/beta-exports.generated.ts
+++ b/packages/appkit/src/plugins/beta-exports.generated.ts
@@ -7,3 +7,4 @@
 
 export { agents } from "./agents";
 export { aiSearch } from "./ai-search";
+export { design } from "./design";
diff --git a/packages/appkit/src/plugins/design/index.ts b/packages/appkit/src/plugins/design/index.ts
new file mode 100644
index 000000000..b520a2096
--- /dev/null
+++ b/packages/appkit/src/plugins/design/index.ts
@@ -0,0 +1,97 @@
+import type { BasePluginConfig, IAppRouter } from "shared";
+
+import { createLogger } from "../../logging/logger";
+import { Plugin, toPlugin } from "../../plugin";
+import { defineManifest } from "../../registry";
+import manifest from "./manifest.json";
+import { type DesignSelectionInput, DesignSelectionStore } from "./store";
+import { designVitePlugin } from "./vite-plugin";
+
+const logger = createLogger("design");
+
+const isDev = () => process.env.NODE_ENV === "development";
+
+/**
+ * Dev-only design canvas.
+ *
+ * In development it contributes a Vite plugin that serves `/design` (a canvas
+ * rendering every component exported from `client/src/design/`) and injects
+ * the click-to-select picker into every page of the app. Picked elements are
+ * POSTed to `/api/design/selection` and persisted to
+ * `.appkit/design-selection.json`, where a coding agent picks them up.
+ *
+ * In any other environment it does nothing except answer `/design` with 404.
+ * The manifest is deliberately not `devOnly`: a dropped plugin couldn't claim
+ * `/design`, and the SPA fallback would serve the app's index.html for it.
+ */
+class DesignPlugin extends Plugin<BasePluginConfig> {
+  static manifest = defineManifest<"design">(manifest);
+
+  protected static description =
+    "Dev-only design canvas and element picker for coding agents";
+
+  private readonly store = new DesignSelectionStore();
+
+  async setup() {
+    if (isDev()) return;
+    this.context?.addMiddleware("/design", (_req, res) => {
+      res.status(404).end();
+    });
+  }
+
+  /** Consumed by the server plugin when it starts the Vite dev server. */
+  vitePlugins() {
+    return isDev() ? [designVitePlugin()] : [];
+  }
+
+  injectRoutes(router: IAppRouter): void {
+    if (!isDev()) return;
+
+    this.route(router, {
+      name: "selection",
+      method: "get",
+      path: "/selection",
+      handler: async (_req, res) => {
+        res.json(await this.store.read());
+      },
+    });
+
+    this.route(router, {
+      name: "addSelection",
+      method: "post",
+      path: "/selection",
+      handler: async (req, res) => {
+        const body = (req.body ?? {}) as Partial<DesignSelectionInput>;
+        if (!Array.isArray(body.elements) || body.elements.length === 0) {
+          res.status(400).json({
+            ok: false,
+            message: "`elements` (non-empty array) is required",
+          });
+          return;
+        }
+        const selection = await this.store.add({
+          elements: body.elements,
+          note: typeof body.note === "string" ? body.note : undefined,
+          url: typeof body.url === "string" ? body.url : undefined,
+        });
+        logger.info("Recorded design selection", {
+          id: selection.id,
+          elements: selection.elements.length,
+        });
+        res.json({ ok: true, id: selection.id, file: this.store.filePath });
+      },
+    });
+
+    this.route(router, {
+      name: "clearSelection",
+      method: "delete",
+      path: "/selection",
+      handler: async (_req, res) => {
+        await this.store.clear();
+        res.json({ ok: true });
+      },
+    });
+  }
+}
+
+export const design = toPlugin(DesignPlugin);
diff --git a/packages/appkit/src/plugins/design/manifest.json b/packages/appkit/src/plugins/design/manifest.json
new file mode 100644
index 000000000..d54d984c1
--- /dev/null
+++ b/packages/appkit/src/plugins/design/manifest.json
@@ -0,0 +1,11 @@
+{
+  "$schema": "https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json",
+  "name": "design",
+  "displayName": "Design Plugin",
+  "description": "Dev-only design canvas at /design: renders components from client/src/design, lets you click-select elements in the canvas or the running app and hand them to a coding agent",
+  "stability": "beta",
+  "resources": {
+    "required": [],
+    "optional": []
+  }
+}
diff --git a/packages/appkit/src/plugins/design/store.ts b/packages/appkit/src/plugins/design/store.ts
new file mode 100644
index 000000000..35228ed4c
--- /dev/null
+++ b/packages/appkit/src/plugins/design/store.ts
@@ -0,0 +1,141 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/** Selection file, relative to the app's working directory. */
+const SELECTION_FILE = ".appkit/design-selection.json";
+const SCREENSHOT_DIR = ".appkit/design-screenshots";
+
+const DATA_URL = /^data:image\/(png|jpeg);base64,([A-Za-z0-9+/=]+)$/;
+
+/** One picked element, as sent by the browser picker. */
+export interface DesignElement {
+  /** Nearest React component name owning the element. */
+  component?: string;
+  /** Owning components, innermost first. */
+  stack?: string[];
+  /** `file:line:col` from the element's `data-source` attribute. */
+  source?: string;
+  /** Serialized props of that component. */
+  props?: Record<string, unknown>;
+  /** Tag name of the picked DOM element. */
+  tag?: string;
+  /** Text content (truncated) of the picked element. */
+  text?: string;
+  /** PNG/JPEG data URL on input; path of the saved image file on output. */
+  screenshot?: string;
+}
+
+export interface DesignSelectionInput {
+  elements: DesignElement[];
+  note?: string;
+  /** Page the elements were picked on (`/design` or an app route). */
+  url?: string;
+}
+
+interface DesignSelection extends DesignSelectionInput {
+  id: string;
+  ts: string;
+}
+
+interface DesignSelectionFile {
+  selections: DesignSelection[];
+}
+
+const str = (v: unknown) => (typeof v === "string" ? v : undefined);
+
+/**
+ * Append-only store of design selections. Writes are serialized so concurrent
+ * sends can't interleave their read-modify-write.
+ *
+ * @internal
+ */
+export class DesignSelectionStore {
+  readonly filePath: string;
+  private readonly root: string;
+  private queue: Promise<unknown> = Promise.resolve();
+
+  constructor(root: string = process.cwd()) {
+    this.root = root;
+    this.filePath = path.resolve(root, SELECTION_FILE);
+  }
+
+  async read(): Promise<DesignSelectionFile> {
+    try {
+      return JSON.parse(await fs.readFile(this.filePath, "utf-8"));
+    } catch {
+      return { selections: [] };
+    }
+  }
+
+  add(input: DesignSelectionInput): Promise<DesignSelection> {
+    return this.enqueue(async () => {
+      const id = randomUUID();
+      const elements = await Promise.all(
+        input.elements.map((el, i) => this.toElement(el, `${id}-${i}`)),
+      );
+      const selection: DesignSelection = {
+        id,
+        ts: new Date().toISOString(),
+        ...(input.note ? { note: input.note } : {}),
+        ...(input.url ? { url: input.url } : {}),
+        elements,
+      };
+      const file = await this.read();
+      file.selections.push(selection);
+      await this.write(file);
+      return selection;
+    });
+  }
+
+  clear(): Promise<void> {
+    return this.enqueue(async () => {
+      await fs.rm(path.resolve(this.root, SCREENSHOT_DIR), {
+        recursive: true,
+        force: true,
+      });
+      await this.write({ selections: [] });
+    });
+  }
+
+  private enqueue<T>(fn: () => Promise<T>): Promise<T> {
+    const run = this.queue.then(fn);
+    this.queue = run.catch(() => {});
+    return run;
+  }
+
+  private async write(file: DesignSelectionFile) {
+    await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+    await fs.writeFile(this.filePath, `${JSON.stringify(file, null, 2)}\n`);
+  }
+
+  /** Keeps only known fields and moves the screenshot out to an image file. */
+  private async toElement(
+    raw: DesignElement,
+    name: string,
+  ): Promise<DesignElement> {
+    const el: DesignElement = {
+      component: str(raw.component),
+      stack: Array.isArray(raw.stack)
+        ? raw.stack.filter((s) => typeof s === "string")
+        : undefined,
+      source: str(raw.source),
+      tag: str(raw.tag),
+      text: str(raw.text),
+      props: raw.props && typeof raw.props === "object" ? raw.props : undefined,
+    };
+    const match = str(raw.screenshot)?.match(DATA_URL);
+    if (match) {
+      const rel = path.join(SCREENSHOT_DIR, `${name}.${match[1]}`);
+      await fs.mkdir(path.resolve(this.root, SCREENSHOT_DIR), {
+        recursive: true,
+      });
+      await fs.writeFile(
+        path.resolve(this.root, rel),
+        Buffer.from(match[2], "base64"),
+      );
+      el.screenshot = rel;
+    }
+    return el;
+  }
+}
diff --git a/packages/appkit/src/plugins/design/tests/design.test.ts b/packages/appkit/src/plugins/design/tests/design.test.ts
new file mode 100644
index 000000000..856f1cf06
--- /dev/null
+++ b/packages/appkit/src/plugins/design/tests/design.test.ts
@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, test } from "vitest";
+
+import { createTestApp, type TestApp } from "../../../testing";
+import { server } from "../../server";
+import { design } from "../index";
+import { DesignSelectionStore } from "../store";
+
+const PIXEL =
+  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
+
+const tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), "appkit-design-"));
+
+describe("DesignSelectionStore", () => {
+  test("persists selections and writes screenshots as image files", async () => {
+    const root = tmp();
+    const store = new DesignSelectionStore(root);
+
+    const saved = await store.add({
+      note: "make it bigger",
+      elements: [
+        {
+          component: "Card",
+          source: "client/src/design/Example.tsx:10:4",
+          props: { title: "x" },
+          screenshot: PIXEL,
+          // unknown fields are dropped
+          ...({ evil: true } as object),
+        },
+      ],
+    });
+
+    const file = JSON.parse(
+      fs.readFileSync(
+        path.join(root, ".appkit/design-selection.json"),
+        "utf-8",
+      ),
+    );
+    expect(file.selections).toHaveLength(1);
+    expect(file.selections[0]).toMatchObject({
+      id: saved.id,
+      note: "make it bigger",
+    });
+    const [el] = file.selections[0].elements;
+    expect(el).not.toHaveProperty("evil");
+    expect(el.screenshot).toBe(`.appkit/design-screenshots/${saved.id}-0.png`);
+    expect(fs.existsSync(path.join(root, el.screenshot))).toBe(true);
+
+    // survives a "restart"
+    expect(
+      (await new DesignSelectionStore(root).read()).selections,
+    ).toHaveLength(1);
+
+    await store.clear();
+    expect((await store.read()).selections).toEqual([]);
+    expect(fs.existsSync(path.join(root, ".appkit/design-screenshots"))).toBe(
+      false,
+    );
+  });
+});
+
+describe("design plugin outside development", () => {
+  let app: TestApp<never> | undefined;
+  afterEach(async () => {
+    await app?.close();
+    app = undefined;
+  });
+
+  function staticDir() {
+    const dir = tmp();
+    fs.writeFileSync(
+      path.join(dir, "index.html"),
+      "<html><body></body></html>",
+    );
+    return dir;
+  }
+
+  test("/design is 404 and no selection API is mounted", async () => {
+    app = (await createTestApp({
+      nodeEnv: "production",
+      plugins: [server({ staticPath: staticDir(), port: 0 }), design()],
+    })) as unknown as TestApp<never>;
+
+    expect((await app.get("/design")).status).toBe(404);
+    expect((await app.get("/design/")).status).toBe(404);
+    expect((await app.get("/api/design/selection")).status).not.toBe(200);
+    // The SPA fallback still serves everything else.
+    expect((await app.get("/anything")).status).toBe(200);
+  });
+});
diff --git a/packages/appkit/src/plugins/design/vite-plugin.ts b/packages/appkit/src/plugins/design/vite-plugin.ts
new file mode 100644
index 000000000..1706fa1b3
--- /dev/null
+++ b/packages/appkit/src/plugins/design/vite-plugin.ts
@@ -0,0 +1,84 @@
+import type { Plugin } from "vite";
+
+const CANVAS_ID = "virtual:appkit-design-canvas";
+const PICKER_ID = "virtual:appkit-design-picker";
+const url = (id: string) => `/@id/__x00__${id}`;
+
+// Globs are root-relative (root = the client dir), so `/src/design` is
+// `client/src/design`. `index.css` is optional; an empty glob is a no-op.
+const CANVAS_MODULE = `
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { DesignCanvas } from "@databricks/appkit-ui/react/beta";
+import.meta.glob("/src/index.css", { eager: true });
+const modules = import.meta.glob("/src/design/**/*.{tsx,jsx}", { eager: true });
+createRoot(document.getElementById("root")).render(createElement(DesignCanvas, { modules }));
+`;
+
+const PICKER_MODULE = `
+import { mountDesignPicker } from "@databricks/appkit-ui/react/beta";
+mountDesignPicker();
+`;
+
+const CANVAS_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Design canvas</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="${url(CANVAS_ID)}"></script>
+  </body>
+</html>
+`;
+
+/**
+ * Serves the `/design` canvas and injects the element picker into every HTML
+ * page Vite transforms (the app and the canvas alike).
+ *
+ * @internal
+ */
+export function designVitePlugin(): Plugin {
+  return {
+    name: "appkit-design",
+    apply: "serve",
+
+    resolveId(id) {
+      if (id === CANVAS_ID || id === PICKER_ID) return `\0${id}`;
+    },
+
+    load(id) {
+      if (id === `\0${CANVAS_ID}`) return CANVAS_MODULE;
+      if (id === `\0${PICKER_ID}`) return PICKER_MODULE;
+    },
+
+    transformIndexHtml() {
+      return [
+        {
+          tag: "script",
+          attrs: { type: "module", src: url(PICKER_ID) },
+          injectTo: "body",
+        },
+      ];
+    },
+
+    configureServer(server) {
+      server.middlewares.use(async (req, res, next) => {
+        const pathname = req.url?.split("?")[0];
+        if (pathname !== "/design" && pathname !== "/design/") return next();
+        try {
+          const html = await server.transformIndexHtml(
+            req.url ?? "/design",
+            CANVAS_HTML,
+          );
+          res.setHeader("Content-Type", "text/html");
+          res.end(html);
+        } catch (error) {
+          next(error);
+        }
+      });
+    },
+  };
+}
diff --git a/packages/appkit/src/plugins/server/index.ts b/packages/appkit/src/plugins/server/index.ts
index ff8efcd0d..e10323c9b 100644
--- a/packages/appkit/src/plugins/server/index.ts
+++ b/packages/appkit/src/plugins/server/index.ts
@@ -7,6 +7,7 @@ import express from "express";
 import getPort, { portNumbers } from "get-port";
 import type { PluginClientConfigs, PluginPhase } from "shared";
 import { camelToKebab } from "shared";
+import type { PluginOption } from "vite";
 
 import { AppKitError, ServerError } from "../../errors";
 import { httpStatusOf } from "../../errors/http-status";
@@ -344,10 +345,14 @@ export class ServerPlugin extends Plugin {
 
     // auto-detection based on environment
     if (isDev) {
+      const vitePlugins = [
+        ...(this.context?.getPlugins().values() ?? []),
+      ].flatMap((plugin) => plugin.vitePlugins?.() ?? []);
       this.viteDevServer = new ViteDevServer(
         this.serverApplication,
         endpoints,
         pluginConfigs,
+        vitePlugins as PluginOption[],
       );
       await this.viteDevServer.setup();
       return;
diff --git a/packages/appkit/src/plugins/server/vite-dev-server.ts b/packages/appkit/src/plugins/server/vite-dev-server.ts
index 22c29cea0..1709380e7 100644
--- a/packages/appkit/src/plugins/server/vite-dev-server.ts
+++ b/packages/appkit/src/plugins/server/vite-dev-server.ts
@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import type express from "express";
-import type { ViteDevServer as ViteDevServerType } from "vite";
+import type { PluginOption, ViteDevServer as ViteDevServerType } from "vite";
 
 import { ServerError } from "../../errors";
 import { createLogger } from "../../logging/logger";
@@ -34,6 +34,7 @@ export class ViteDevServer extends BaseServer {
     app: express.Application,
     endpoints: PluginEndpoints = {},
     pluginConfigs: PluginClientConfigs = {},
+    private readonly extraPlugins: PluginOption[] = [],
   ) {
     super(app, endpoints, pluginConfigs);
     this.vite = null;
@@ -88,6 +89,7 @@ export class ViteDevServer extends BaseServer {
         reactSourceLocPlugin({ projectRoot }),
         appKitTypesPlugin(),
         appKitServingTypesPlugin(),
+        ...this.extraPlugins,
       ],
       appType: "custom",
     };
diff --git a/packages/shared/src/plugin.ts b/packages/shared/src/plugin.ts
index 1a4e1306f..a56045b42 100644
--- a/packages/shared/src/plugin.ts
+++ b/packages/shared/src/plugin.ts
@@ -51,6 +51,9 @@ export interface BasePlugin {
 
   clientConfig?(): Record<string, unknown>;
 
+  /** Vite plugins added to the dev server (development only). Typed loosely so `shared` doesn't depend on `vite`. */
+  vitePlugins?(): unknown[];
+
   /**
    * Binds runtime dependencies (telemetry, cache, plugin context) after the
    * plugin has been constructed. Called by the AppKit core before `setup()`.
diff --git a/template/README.md.tmpl b/template/README.md.tmpl
index c21dc1cc0..11994839b 100644
--- a/template/README.md.tmpl
+++ b/template/README.md.tmpl
@@ -15,6 +15,9 @@ A Databricks App powered by [AppKit](https://developers.databricks.com/docs/appk
 {{- if .plugins.genie}}
 - **Genie** -- AI/BI Genie conversational interface for natural language data queries
 {{- end}}
+{{- if .plugins.design}}
+- **Design** -- Dev-only design canvas at `/design`: renders components from `client/src/design/`; click **Select** (on the canvas or any app page) to pick elements and send them to your coding agent via `.appkit/design-selection.json`
+{{- end}}
 - **Server** -- Express HTTP server with static file serving and Vite dev mode
 
 ## Prerequisites
diff --git a/template/_gitignore b/template/_gitignore
index 29895e7c0..cb3013bfb 100644
--- a/template/_gitignore
+++ b/template/_gitignore
@@ -5,6 +5,7 @@ dist/
 build/
 .env
 .databricks/
+.appkit/
 .smoke-test/
 test-results/
 playwright-report/
diff --git a/template/appkit.plugins.json b/template/appkit.plugins.json
index db53b96b7..84a82c9e8 100644
--- a/template/appkit.plugins.json
+++ b/template/appkit.plugins.json
@@ -196,6 +196,17 @@
         }
       }
     },
+    "design": {
+      "name": "design",
+      "displayName": "Design Plugin",
+      "description": "Dev-only design canvas at /design: renders components from client/src/design, lets you click-select elements in the canvas or the running app and hand them to a coding agent",
+      "package": "@databricks/appkit",
+      "resources": {
+        "required": [],
+        "optional": []
+      },
+      "stability": "beta"
+    },
     "files": {
       "name": "files",
       "displayName": "Files Plugin",
diff --git a/template/client/src/design/Example.tsx b/template/client/src/design/Example.tsx
new file mode 100644
index 000000000..f3c61ba40
--- /dev/null
+++ b/template/client/src/design/Example.tsx
@@ -0,0 +1,22 @@
+{{if .plugins.design -}}
+import { Button, Card, CardContent, CardHeader, CardTitle } from '@databricks/appkit-ui/react';
+
+/*
+ * Every PascalCase export in this folder is rendered with no props on the
+ * design canvas at /design (dev only). Put design-only drafts here, or
+ * previews that render your real components with mock data.
+ */
+export function ExampleCard() {
+  return (
+    <Card className="max-w-sm">
+      <CardHeader>
+        <CardTitle>Example draft</CardTitle>
+      </CardHeader>
+      <CardContent className="flex flex-col gap-3">
+        <p className="text-sm text-muted-foreground">Click Select, pick elements, add a note and send them to your agent.</p>
+        <Button>Primary action</Button>
+      </CardContent>
+    </Card>
+  );
+}
+{{- end}}
diff --git a/tools/generate-app-templates.ts b/tools/generate-app-templates.ts
index d78a0e34b..93f2fb567 100644
--- a/tools/generate-app-templates.ts
+++ b/tools/generate-app-templates.ts
@@ -121,6 +121,12 @@ const APP_TEMPLATES: AppTemplate[] = [
     description:
       "Node.js app with Lakebase Autoscaling (Postgres) CRUD operations",
   },
+  {
+    name: "ui-only",
+    features: ["design"],
+    description:
+      "Empty UI-only app (server + dev-only design canvas) for quick PoCs",
+  },
 ];
 
 function run(cmd: string, args: string[], opts?: { cwd?: string }): number {

From f3cb5e1962c304c2db576afe90d79860b751c098 Mon Sep 17 00:00:00 2001
From: MarioCadenas <MarioCadenas@users.noreply.github.com>
Date: Tue, 20 Oct 2026 14:43:34 +0200
Subject: [PATCH 2/6] fix(appkit): make design selections accurate and reliable

- Source locations for library components: the design plugin adds a
  components-mode pass of the source-loc transform (data-appkit-source on
  component call sites), and the picker reads source from fiber props.
- Props are read from the committed fiber chain, not the possibly stale
  DOM-attached alternate.
- Screenshots embed <img> sources, canvas pixels and CSS background images.
- The canvas renders memo and forwardRef exports.
- Selection writes are atomic (temp file + rename) and reads no longer
  turn a parse failure into an empty list.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
---
 docs/docs/plugins/design.md                   |   2 +-
 .../react/design/__tests__/design.test.tsx    |  78 +++++++++++
 .../src/react/design/design-canvas.tsx        |  19 ++-
 .../appkit-ui/src/react/design/inspect.ts     | 125 +++++++++++++++---
 packages/appkit/src/plugins/design/index.ts   |   9 +-
 packages/appkit/src/plugins/design/store.ts   |  20 ++-
 .../src/plugins/design/tests/design.test.ts   |  18 +++
 .../server/react-source-loc-vite-plugin.ts    |  30 ++++-
 .../react-source-loc-vite-plugin.test.ts      |  37 ++++++
 9 files changed, 304 insertions(+), 34 deletions(-)
 create mode 100644 packages/appkit-ui/src/react/design/__tests__/design.test.tsx

diff --git a/docs/docs/plugins/design.md b/docs/docs/plugins/design.md
index 0fabca338..d290164d1 100644
--- a/docs/docs/plugins/design.md
+++ b/docs/docs/plugins/design.md
@@ -45,7 +45,7 @@ A frame that throws shows its error in place. It doesn't break the rest of the c
 
 In development, a **Select** button appears in the bottom-right corner of the canvas and of every app page. Click it, then click elements to add or remove them (Escape stops selecting). Add an optional note and click **Send to agent**.
 
-Each element is traced back to its source through the `data-source="file:line:col"` attribute that the dev server adds to native JSX elements. The nearest React component and its props come from React's fiber tree.
+Each element is traced back to its source `file:line:col`: the dev server tags native JSX elements with `data-source`, and the design plugin also tags component call sites (such as `<Button>` from a library) with `data-appkit-source`. The picker reads these, plus the nearest React component and its current props, from React's fiber tree. Screenshots include images, canvases, and CSS background images. Web fonts and cross-origin resources served without CORS are not embedded.
 
 ## Handing selections to the agent
 
diff --git a/packages/appkit-ui/src/react/design/__tests__/design.test.tsx b/packages/appkit-ui/src/react/design/__tests__/design.test.tsx
new file mode 100644
index 000000000..bab4915d6
--- /dev/null
+++ b/packages/appkit-ui/src/react/design/__tests__/design.test.tsx
@@ -0,0 +1,78 @@
+import { act, cleanup, render, screen } from "@testing-library/react";
+import { forwardRef, memo, useState } from "react";
+import { afterEach, describe, expect, test } from "vitest";
+
+import { DesignCanvas } from "../design-canvas";
+import { inspectElement } from "../inspect";
+
+afterEach(cleanup);
+
+function LiveCard({ count }: { count: number }) {
+  return <button type="button">Count: {count}</button>;
+}
+
+function Parent() {
+  const [count, setCount] = useState(0);
+  return (
+    <div>
+      <button type="button" onClick={() => setCount((c) => c + 1)}>
+        inc
+      </button>
+      <LiveCard count={count} />
+    </div>
+  );
+}
+
+describe("inspectElement", () => {
+  test("reports the committed props after every update", () => {
+    render(<Parent />);
+    for (let i = 1; i <= 5; i++) {
+      act(() => screen.getByText("inc").click());
+      const info = inspectElement(screen.getByText(`Count: ${i}`));
+      expect(info.component).toBe("LiveCard");
+      expect(info.props).toEqual({ count: i });
+    }
+  });
+
+  test("takes the source of a component that never forwards it to the DOM", () => {
+    // Stand-in for a dependency component the dev transform tags at its call site.
+    const LibButton = ({ label }: { label: string }) => (
+      <button type="button">{label}</button>
+    );
+    const props = { "data-appkit-source": "client/src/App.tsx:7:4" };
+    render(
+      <main data-source="client/src/App.tsx:3:2">
+        <LibButton label="Library button" {...props} />
+      </main>,
+    );
+    const info = inspectElement(screen.getByText("Library button"));
+    expect(info.source).toBe("client/src/App.tsx:7:4");
+    expect(info.props).toEqual({ label: "Library button" });
+  });
+});
+
+describe("DesignCanvas", () => {
+  test("renders function, memo and forwardRef exports", () => {
+    const MemoDraft = memo(() => <p>memo draft</p>);
+    const RefDraft = forwardRef<HTMLParagraphElement>((_, ref) => (
+      <p ref={ref}>ref draft</p>
+    ));
+    render(
+      <DesignCanvas
+        modules={{
+          "/src/design/Drafts.tsx": {
+            Plain: () => <p>plain draft</p>,
+            MemoDraft,
+            RefDraft,
+            helper: () => null,
+            CONSTANT: 1,
+          },
+        }}
+      />,
+    );
+    expect(screen.getByText("plain draft")).toBeTruthy();
+    expect(screen.getByText("memo draft")).toBeTruthy();
+    expect(screen.getByText("ref draft")).toBeTruthy();
+    expect(screen.getAllByRole("heading", { level: 2 })).toHaveLength(3);
+  });
+});
diff --git a/packages/appkit-ui/src/react/design/design-canvas.tsx b/packages/appkit-ui/src/react/design/design-canvas.tsx
index 1b89a49f5..43f7340de 100644
--- a/packages/appkit-ui/src/react/design/design-canvas.tsx
+++ b/packages/appkit-ui/src/react/design/design-canvas.tsx
@@ -6,6 +6,21 @@ export interface DesignCanvasProps {
   modules: Record<string, Record<string, unknown>>;
 }
 
+/** memo / forwardRef components are objects, not functions. */
+const WRAPPED_COMPONENTS = new Set([
+  Symbol.for("react.memo"),
+  Symbol.for("react.forward_ref"),
+]);
+
+function isComponent(value: unknown): boolean {
+  if (typeof value === "function") return true;
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    WRAPPED_COMPONENTS.has((value as { $$typeof?: symbol }).$$typeof as symbol)
+  );
+}
+
 class Boundary extends Component<{ children: ReactNode }, { error?: Error }> {
   state: { error?: Error } = {};
   static getDerivedStateFromError(error: Error) {
@@ -35,9 +50,7 @@ export function DesignCanvas({ modules }: DesignCanvasProps) {
     .sort(([a], [b]) => a.localeCompare(b))
     .flatMap(([file, mod]) =>
       Object.entries(mod)
-        .filter(
-          ([name, value]) => /^[A-Z]/.test(name) && typeof value === "function",
-        )
+        .filter(([name, value]) => /^[A-Z]/.test(name) && isComponent(value))
         .map(([name, value]) => ({
           id: `${file}#${name}`,
           label: `${file.replace(/^\/src\/design\//, "")} · ${name}`,
diff --git a/packages/appkit-ui/src/react/design/inspect.ts b/packages/appkit-ui/src/react/design/inspect.ts
index a25bf9ceb..fabf55f0f 100644
--- a/packages/appkit-ui/src/react/design/inspect.ts
+++ b/packages/appkit-ui/src/react/design/inspect.ts
@@ -15,11 +15,18 @@ export interface DesignElementInfo {
 const STACK_DEPTH = 6;
 
 interface Fiber {
+  tag: number;
   type: unknown;
   return: Fiber | null;
+  child: Fiber | null;
+  sibling: Fiber | null;
+  alternate: Fiber | null;
+  stateNode: unknown;
   memoizedProps?: Record<string, unknown>;
 }
 
+const HOST_ROOT = 3;
+
 type ComponentType = {
   displayName?: string;
   name?: string;
@@ -32,6 +39,30 @@ function fiberOf(el: Element): Fiber | undefined {
   return key ? (el as unknown as Record<string, Fiber>)[key] : undefined;
 }
 
+/**
+ * The element's fiber and its ancestors, innermost first, each resolved to its
+ * *current* (committed) version. The DOM-attached fiber and its `return` links
+ * can belong to the previous render, whose props are stale; the current tree
+ * is the one reachable through `child` links from the root's `current`.
+ */
+function currentChain(el: Element): Fiber[] {
+  const chain: Fiber[] = [];
+  for (let f = fiberOf(el) ?? null; f; f = f.return) chain.push(f);
+  const root = chain[chain.length - 1];
+  if (root?.tag !== HOST_ROOT) return chain;
+  let cur = (root.stateNode as { current: Fiber }).current;
+  const resolved = [cur];
+  for (let i = chain.length - 2; i >= 0; i--) {
+    const want = chain[i];
+    let c = cur.child;
+    while (c && c !== want && c.alternate !== want) c = c.sibling;
+    if (!c) return chain;
+    cur = c;
+    resolved.push(c);
+  }
+  return resolved.reverse();
+}
+
 /** Name of a function / memo / forwardRef component fiber, else undefined. */
 function componentName(type: unknown): string | undefined {
   if (!type || (typeof type !== "function" && typeof type !== "object")) {
@@ -64,51 +95,104 @@ function serializeProps(value: unknown, depth = 0): unknown {
 }
 
 export function inspectElement(el: Element): DesignElementInfo {
+  const chain = currentChain(el);
   const stack: string[] = [];
   let props: Record<string, unknown> | undefined;
-  for (let f = fiberOf(el) ?? null; f && stack.length < STACK_DEPTH;) {
+  let source: string | undefined;
+  for (const f of chain) {
+    // Native elements carry `data-source`; component call sites (including
+    // library components that never reach the DOM) carry `data-appkit-source`.
+    const loc =
+      f.memoizedProps?.["data-source"] ??
+      f.memoizedProps?.["data-appkit-source"];
+    if (!source && typeof loc === "string") source = loc;
     const name = componentName(f.type);
-    if (name) {
-      if (stack.length === 0) {
-        props = serializeProps(f.memoizedProps ?? {}) as Record<
-          string,
-          unknown
-        >;
-      }
-      stack.push(name);
+    if (!name || stack.length >= STACK_DEPTH) continue;
+    if (stack.length === 0) {
+      props = serializeProps(f.memoizedProps ?? {}) as Record<string, unknown>;
+      delete props["data-appkit-source"];
     }
-    f = f.return;
+    stack.push(name);
   }
+  source ??=
+    el.closest("[data-source]")?.getAttribute("data-source") ?? undefined;
   const text = el.textContent?.trim().replace(/\s+/g, " ").slice(0, 120);
   return {
     component: stack[0],
     ...(stack.length ? { stack } : {}),
-    source:
-      el.closest("[data-source]")?.getAttribute("data-source") ?? undefined,
+    ...(source ? { source } : {}),
     ...(props ? { props } : {}),
     tag: el.tagName.toLowerCase(),
     ...(text ? { text } : {}),
   };
 }
 
-function inlineStyles(src: Element, dst: Element) {
+async function toDataUrl(url: string): Promise<string> {
+  const blob = await (await fetch(url)).blob();
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result as string);
+    reader.onerror = reject;
+    reader.readAsDataURL(blob);
+  });
+}
+
+/**
+ * Copies computed styles onto the clone and embeds what an SVG image can't
+ * load by itself: canvas pixels, `<img>` sources and CSS background images
+ * (as data URLs). Resources that can't be fetched (CORS) are left as-is.
+ */
+function prepareClone(src: Element, dst: Element, tasks: Promise<unknown>[]) {
   const cs = getComputedStyle(src);
   let css = "";
   for (let i = 0; i < cs.length; i++) {
     css += `${cs[i]}:${cs.getPropertyValue(cs[i])};`;
   }
   dst.setAttribute("style", css);
+
+  if (src instanceof HTMLCanvasElement) {
+    try {
+      const img = document.createElement("img");
+      img.setAttribute("style", css);
+      img.src = src.toDataURL();
+      dst.replaceWith(img);
+    } catch {
+      // tainted canvas: keep the empty clone
+    }
+    return;
+  }
+  if (src instanceof HTMLImageElement && src.currentSrc) {
+    dst.removeAttribute("srcset");
+    tasks.push(
+      toDataUrl(src.currentSrc)
+        .then((u) => dst.setAttribute("src", u))
+        .catch(() => {}),
+    );
+  }
+  const bg = cs.getPropertyValue("background-image");
+  const urls = [...bg.matchAll(/url\("?([^")]+)"?\)/g)].map((m) => m[1]);
+  if (urls.length) {
+    tasks.push(
+      Promise.all(urls.map((u) => toDataUrl(u).catch(() => u))).then((data) => {
+        let out = bg;
+        urls.forEach((u, i) => {
+          out = out.replace(u, data[i]);
+        });
+        (dst as HTMLElement).style.setProperty("background-image", out);
+      }),
+    );
+  }
   for (let i = 0; i < src.children.length; i++) {
-    inlineStyles(src.children[i], dst.children[i]);
+    prepareClone(src.children[i], dst.children[i], tasks);
   }
 }
 
 /**
  * Rasterizes an element via an SVG `<foreignObject>` with inlined computed
  * styles, as a JPEG data URL. Best-effort: returns undefined when the browser
- * refuses (e.g. cross-origin images taint the canvas).
+ * refuses to rasterize.
  */
-// ponytail: no external images/fonts are embedded; add html-to-image if screenshots need pixel fidelity
+// ponytail: web fonts and cross-origin resources without CORS aren't embedded; add html-to-image if that matters
 export async function captureElement(
   el: Element,
   maxWidth = 800,
@@ -117,8 +201,13 @@ export async function captureElement(
     const { width, height } = el.getBoundingClientRect();
     if (!width || !height) return undefined;
     const clone = el.cloneNode(true) as Element;
-    inlineStyles(el, clone);
-    const xml = new XMLSerializer().serializeToString(clone);
+    // A parent so the root itself can be swapped (a selected <canvas>).
+    const wrap = document.createElement("div");
+    wrap.appendChild(clone);
+    const tasks: Promise<unknown>[] = [];
+    prepareClone(el, clone, tasks);
+    await Promise.all(tasks);
+    const xml = new XMLSerializer().serializeToString(wrap);
     const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><foreignObject width="100%" height="100%">${xml}</foreignObject></svg>`;
     const img = new Image();
     img.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
diff --git a/packages/appkit/src/plugins/design/index.ts b/packages/appkit/src/plugins/design/index.ts
index b520a2096..b27984c52 100644
--- a/packages/appkit/src/plugins/design/index.ts
+++ b/packages/appkit/src/plugins/design/index.ts
@@ -3,6 +3,7 @@ import type { BasePluginConfig, IAppRouter } from "shared";
 import { createLogger } from "../../logging/logger";
 import { Plugin, toPlugin } from "../../plugin";
 import { defineManifest } from "../../registry";
+import { reactSourceLocPlugin } from "../server/react-source-loc-vite-plugin";
 import manifest from "./manifest.json";
 import { type DesignSelectionInput, DesignSelectionStore } from "./store";
 import { designVitePlugin } from "./vite-plugin";
@@ -41,7 +42,13 @@ class DesignPlugin extends Plugin<BasePluginConfig> {
 
   /** Consumed by the server plugin when it starts the Vite dev server. */
   vitePlugins() {
-    return isDev() ? [designVitePlugin()] : [];
+    if (!isDev()) return [];
+    return [
+      designVitePlugin(),
+      // Locates component call sites (`<Button>`), which the server's own
+      // transform skips because it only tags native elements.
+      reactSourceLocPlugin({ projectRoot: process.cwd(), components: true }),
+    ];
   }
 
   injectRoutes(router: IAppRouter): void {
diff --git a/packages/appkit/src/plugins/design/store.ts b/packages/appkit/src/plugins/design/store.ts
index 35228ed4c..6f5b7e9b2 100644
--- a/packages/appkit/src/plugins/design/store.ts
+++ b/packages/appkit/src/plugins/design/store.ts
@@ -46,7 +46,8 @@ const str = (v: unknown) => (typeof v === "string" ? v : undefined);
 
 /**
  * Append-only store of design selections. Writes are serialized so concurrent
- * sends can't interleave their read-modify-write.
+ * sends can't interleave their read-modify-write, and each write replaces the
+ * file atomically.
  *
  * @internal
  */
@@ -61,11 +62,16 @@ export class DesignSelectionStore {
   }
 
   async read(): Promise<DesignSelectionFile> {
+    let raw: string;
     try {
-      return JSON.parse(await fs.readFile(this.filePath, "utf-8"));
-    } catch {
-      return { selections: [] };
+      raw = await fs.readFile(this.filePath, "utf-8");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return { selections: [] };
+      }
+      throw error;
     }
+    return JSON.parse(raw);
   }
 
   add(input: DesignSelectionInput): Promise<DesignSelection> {
@@ -106,7 +112,11 @@ export class DesignSelectionStore {
 
   private async write(file: DesignSelectionFile) {
     await fs.mkdir(path.dirname(this.filePath), { recursive: true });
-    await fs.writeFile(this.filePath, `${JSON.stringify(file, null, 2)}\n`);
+    // Write-then-rename is atomic, so concurrent reads never see a truncated
+    // file (reads don't go through the queue).
+    const tmp = `${this.filePath}.${randomUUID()}.tmp`;
+    await fs.writeFile(tmp, `${JSON.stringify(file, null, 2)}\n`);
+    await fs.rename(tmp, this.filePath);
   }
 
   /** Keeps only known fields and moves the screenshot out to an image file. */
diff --git a/packages/appkit/src/plugins/design/tests/design.test.ts b/packages/appkit/src/plugins/design/tests/design.test.ts
index 856f1cf06..6ef4e19bd 100644
--- a/packages/appkit/src/plugins/design/tests/design.test.ts
+++ b/packages/appkit/src/plugins/design/tests/design.test.ts
@@ -60,6 +60,24 @@ describe("DesignSelectionStore", () => {
       false,
     );
   });
+
+  test("concurrent reads never see a partially written file", async () => {
+    const store = new DesignSelectionStore(tmp());
+    await store.add({ elements: [{ tag: "div" }] });
+
+    let writing = true;
+    const counts: number[] = [];
+    const readers = Array.from({ length: 4 }, async () => {
+      while (writing) counts.push((await store.read()).selections.length);
+    });
+    for (let i = 0; i < 100; i++) await store.add({ elements: [{ tag: "p" }] });
+    writing = false;
+    await Promise.all(readers);
+
+    expect(counts.length).toBeGreaterThan(0);
+    expect(counts.every((n) => n >= 1)).toBe(true);
+    expect((await store.read()).selections).toHaveLength(101);
+  });
 });
 
 describe("design plugin outside development", () => {
diff --git a/packages/appkit/src/plugins/server/react-source-loc-vite-plugin.ts b/packages/appkit/src/plugins/server/react-source-loc-vite-plugin.ts
index 8aca4e3b2..3803e671e 100644
--- a/packages/appkit/src/plugins/server/react-source-loc-vite-plugin.ts
+++ b/packages/appkit/src/plugins/server/react-source-loc-vite-plugin.ts
@@ -16,6 +16,17 @@ const JSX_ELEMENT_MATCHER = {
 interface ReactSourceLocPluginOptions {
   /** Absolute app root used for data-source relative paths (typically `process.cwd()`). */
   projectRoot: string;
+  /**
+   * Tag component elements (`<Button>`, `<Ui.Card>`) with
+   * `data-appkit-source` instead of native ones. Components needn't forward
+   * it to the DOM: the design picker reads it from the React fiber props.
+   */
+  components?: boolean;
+}
+
+/** Fragments reject unknown props, so they're never tagged. */
+function isFragmentTag(name: SgNode): boolean {
+  return /(^|\.)Fragment$/.test(name.text());
 }
 
 function cleanModuleId(id: string): string {
@@ -40,11 +51,11 @@ function isNativeJsxTag(name: SgNode): boolean {
   return false;
 }
 
-function hasDataSourceAttribute(node: SgNode): boolean {
+function hasAttribute(node: SgNode, attrName: string): boolean {
   for (const attr of node.fieldChildren("attribute")) {
     if (!attr.is("jsx_attribute")) continue;
     for (const child of attr.children()) {
-      if (child.is("property_identifier") && child.text() === "data-source") {
+      if (child.is("property_identifier") && child.text() === attrName) {
         return true;
       }
     }
@@ -60,9 +71,11 @@ export function reactSourceLocPlugin(
   options: ReactSourceLocPluginOptions,
 ): Plugin {
   const projectRoot = path.resolve(options.projectRoot);
+  const components = options.components === true;
+  const attrName = components ? "data-appkit-source" : "data-source";
 
   return {
-    name: "react-source-loc",
+    name: components ? "react-source-loc-components" : "react-source-loc",
     enforce: "pre",
     apply: "serve",
 
@@ -76,12 +89,17 @@ export function reactSourceLocPlugin(
 
       for (const node of root.findAll(JSX_ELEMENT_MATCHER)) {
         const name = node.field("name");
-        if (!name || !isNativeJsxTag(name)) continue;
-        if (hasDataSourceAttribute(node)) continue;
+        if (!name || isNativeJsxTag(name) !== !components) continue;
+        if (
+          components &&
+          (name.kind() === "jsx_namespace_name" || isFragmentTag(name))
+        )
+          continue;
+        if (hasAttribute(node, attrName)) continue;
 
         const nodeRange = node.range();
         const value = `${relPath}:${nodeRange.start.line + 1}:${nodeRange.start.column}`;
-        s.appendLeft(name.range().end.index, ` data-source="${value}"`);
+        s.appendLeft(name.range().end.index, ` ${attrName}="${value}"`);
       }
 
       if (!s.hasChanged()) return;
diff --git a/packages/appkit/src/plugins/server/tests/react-source-loc-vite-plugin.test.ts b/packages/appkit/src/plugins/server/tests/react-source-loc-vite-plugin.test.ts
index 91e192aab..89f9e0dd9 100644
--- a/packages/appkit/src/plugins/server/tests/react-source-loc-vite-plugin.test.ts
+++ b/packages/appkit/src/plugins/server/tests/react-source-loc-vite-plugin.test.ts
@@ -27,9 +27,11 @@ async function transformSource(
   root: string = clientRoot,
   id: string = moduleId,
   rootForPaths: string = projectRoot,
+  components = false,
 ): Promise<string> {
   const { transform } = reactSourceLocPlugin({
     projectRoot: rootForPaths,
+    components,
   }) as unknown as TestableHooks;
 
   const result = await transform?.(code, id);
@@ -57,6 +59,41 @@ describe("reactSourceLocPlugin", () => {
     expect(output).not.toContain("motion.div data-source");
   });
 
+  it("components mode tags component call sites only, never fragments", async () => {
+    const code = `export function App() {
+  return (
+    <Fragment>
+      <React.Fragment>
+        <Button variant="x" />
+        <Ui.Card>
+          <div />
+        </Ui.Card>
+        <>
+          <svg:rect />
+        </>
+      </React.Fragment>
+    </Fragment>
+  );
+}
+`;
+    const output = await transformSource(
+      code,
+      clientRoot,
+      moduleId,
+      projectRoot,
+      true,
+    );
+    expect(output).toMatch(
+      /<Button data-appkit-source="client\/src\/Example\.tsx:5:8" variant="x" \/>/,
+    );
+    expect(output).toMatch(/<Ui\.Card data-appkit-source="[^"]+">/);
+    expect(output).toContain("<Fragment>");
+    expect(output).toContain("<React.Fragment>");
+    expect(output).toContain("<div />");
+    expect(output).toContain("<svg:rect />");
+    expect(output).not.toContain("data-source=");
+  });
+
   it("skips components, fragments, namespaced tags, and existing data-source", async () => {
     const code = `export function App() {
   return (

From acf5c0f9097726f3fa7f4c40fd70692b41e3643c Mon Sep 17 00:00:00 2001
From: MarioCadenas <MarioCadenas@users.noreply.github.com>
Date: Tue, 20 Oct 2026 16:20:32 +0200
Subject: [PATCH 3/6] fix(appkit-ui): keep positioned elements inside their
 design screenshot

The clone kept the root's absolute/fixed offsets, margins and transforms, so
it rendered outside the element-sized crop and the saved image was blank.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
---
 packages/appkit-ui/src/react/design/inspect.ts | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/packages/appkit-ui/src/react/design/inspect.ts b/packages/appkit-ui/src/react/design/inspect.ts
index fabf55f0f..e23354b24 100644
--- a/packages/appkit-ui/src/react/design/inspect.ts
+++ b/packages/appkit-ui/src/react/design/inspect.ts
@@ -187,6 +187,16 @@ function prepareClone(src: Element, dst: Element, tasks: Promise<unknown>[]) {
   }
 }
 
+const ROOT_RESET: Record<string, string> = {
+  position: "relative",
+  inset: "auto",
+  margin: "0",
+  transform: "none",
+  translate: "none",
+  rotate: "none",
+  scale: "none",
+};
+
 /**
  * Rasterizes an element via an SVG `<foreignObject>` with inlined computed
  * styles, as a JPEG data URL. Best-effort: returns undefined when the browser
@@ -207,6 +217,14 @@ export async function captureElement(
     const tasks: Promise<unknown>[] = [];
     prepareClone(el, clone, tasks);
     await Promise.all(tasks);
+    // The crop is the element's own box, so its placement in the page
+    // (absolute/fixed offsets, margins, transforms) must not move it out.
+    const root = wrap.firstElementChild as HTMLElement | null;
+    if (root) {
+      for (const [prop, value] of Object.entries(ROOT_RESET)) {
+        root.style.setProperty(prop, value);
+      }
+    }
     const xml = new XMLSerializer().serializeToString(wrap);
     const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><foreignObject width="100%" height="100%">${xml}</foreignObject></svg>`;
     const img = new Image();

From 0a8dfa8814f51e0a49ff80363ca0b4041e7b567c Mon Sep 17 00:00:00 2001
From: MarioCadenas <MarioCadenas@users.noreply.github.com>
Date: Wed, 21 Oct 2026 10:34:40 +0200
Subject: [PATCH 4/6] fix(appkit-ui): keep the design picker usable over
 dialogs and during sends

- The picker host re-enables pointer events and keeps its presses and focus
  from reaching a modal's outside-dismiss and focus-trap listeners; while
  selecting, presses on the page are swallowed so a pick inside a dialog
  doesn't close it.
- A finished send clears only the picks (and note) it actually sent, so picks
  added while the request was in flight are kept.
- Screenshots carry live form state: input values, checked state, textarea
  text and selected options.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
---
 .../react/design/__tests__/design.test.tsx    | 55 ++++++++++++++++++-
 .../src/react/design/design-picker.tsx        | 47 ++++++++++++++--
 .../appkit-ui/src/react/design/inspect.ts     | 15 +++++
 3 files changed, 109 insertions(+), 8 deletions(-)

diff --git a/packages/appkit-ui/src/react/design/__tests__/design.test.tsx b/packages/appkit-ui/src/react/design/__tests__/design.test.tsx
index bab4915d6..64a012a23 100644
--- a/packages/appkit-ui/src/react/design/__tests__/design.test.tsx
+++ b/packages/appkit-ui/src/react/design/__tests__/design.test.tsx
@@ -1,8 +1,16 @@
-import { act, cleanup, render, screen } from "@testing-library/react";
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from "@testing-library/react";
 import { forwardRef, memo, useState } from "react";
-import { afterEach, describe, expect, test } from "vitest";
+import { afterEach, describe, expect, test, vi } from "vitest";
 
 import { DesignCanvas } from "../design-canvas";
+import { DesignPicker } from "../design-picker";
 import { inspectElement } from "../inspect";
 
 afterEach(cleanup);
@@ -76,3 +84,46 @@ describe("DesignCanvas", () => {
     expect(screen.getAllByRole("heading", { level: 2 })).toHaveLength(3);
   });
 });
+
+describe("DesignPicker", () => {
+  test("a finished send keeps picks added while it was in flight", async () => {
+    let release!: () => void;
+    const fetchMock = vi.fn(
+      () =>
+        new Promise<Response>((resolve) => {
+          release = () => resolve(new Response("{}", { status: 200 }));
+        }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    render(
+      <>
+        <button type="button">First action</button>
+        <button type="button">Second action</button>
+        <div id="appkit-design-picker">
+          <DesignPicker />
+        </div>
+      </>,
+    );
+
+    fireEvent.click(screen.getByText("Select"));
+    fireEvent.click(screen.getByText("First action"));
+    fireEvent.click(screen.getByText("Send 1 to agent"));
+    await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
+    fireEvent.click(screen.getByText("Second action"));
+    expect(screen.getByText("Send 2 to agent")).toBeTruthy();
+
+    await act(async () => release());
+
+    const body = JSON.parse(
+      (fetchMock.mock.calls[0] as unknown as [string, RequestInit])[1]
+        .body as string,
+    );
+    expect(body.elements.map((e: { text: string }) => e.text)).toEqual([
+      "First action",
+    ]);
+    await waitFor(() =>
+      expect(screen.getByText("Send 1 to agent")).toBeTruthy(),
+    );
+    vi.unstubAllGlobals();
+  });
+});
diff --git a/packages/appkit-ui/src/react/design/design-picker.tsx b/packages/appkit-ui/src/react/design/design-picker.tsx
index 027f3ae27..af4c3b933 100644
--- a/packages/appkit-ui/src/react/design/design-picker.tsx
+++ b/packages/appkit-ui/src/react/design/design-picker.tsx
@@ -109,23 +109,37 @@ export function DesignPicker() {
           : [...prev, { el, info: inspectElement(el) }],
       );
     };
+    // A pick mustn't act on the page either: e.g. a pointerdown would let an
+    // open dialog dismiss itself before the click selects its content.
+    const swallow = (e: Event) => {
+      if (own(e.target)) return;
+      e.preventDefault();
+      e.stopPropagation();
+    };
     const onKey = (e: KeyboardEvent) => e.key === "Escape" && setActive(false);
+    const PRESS = ["pointerdown", "mousedown", "pointerup", "mouseup"];
     document.addEventListener("mousemove", onMove, true);
     document.addEventListener("click", onClick, true);
     document.addEventListener("keydown", onKey, true);
+    for (const t of PRESS) window.addEventListener(t, swallow, true);
     return () => {
       document.removeEventListener("mousemove", onMove, true);
       document.removeEventListener("click", onClick, true);
       document.removeEventListener("keydown", onKey, true);
+      for (const t of PRESS) window.removeEventListener(t, swallow, true);
       setHovered(null);
     };
   }, [active]);
 
   async function send() {
     setStatus("sending");
+    // Picks and the note can change while the request is in flight; only
+    // what was actually sent is cleared afterwards.
+    const sending = picked;
+    const sentNote = note;
     try {
       const elements = await Promise.all(
-        picked.map(async ({ el, info }) => ({
+        sending.map(async ({ el, info }) => ({
           ...info,
           screenshot: await captureElement(el),
         })),
@@ -135,14 +149,18 @@ export function DesignPicker() {
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
           elements,
-          note: note.trim() || undefined,
+          note: sentNote.trim() || undefined,
           url: location.pathname,
         }),
       });
       if (!res.ok) throw new Error(String(res.status));
-      setPicked([]);
-      setNote("");
-      setActive(false);
+      setPicked((prev) => {
+        const remaining = prev.filter((p) => !sending.includes(p));
+        // Idempotent, so safe in an updater that StrictMode may run twice.
+        if (remaining.length === 0) setActive(false);
+        return remaining;
+      });
+      setNote((n) => (n === sentNote ? "" : n));
       setStatus("sent");
     } catch {
       setStatus("error");
@@ -234,7 +252,24 @@ export function mountDesignPicker() {
   if (document.getElementById(ROOT_ID)) return;
   const host = document.createElement("div");
   host.id = ROOT_ID;
-  host.style.cssText = "position:relative;z-index:2147483647";
+  // Modal dialogs set `pointer-events: none` on <body> and dismiss on any
+  // outside press; the picker must stay usable and not count as "outside".
+  host.style.cssText =
+    "position:relative;z-index:2147483647;pointer-events:auto";
+  for (const t of ["pointerdown", "mousedown", "focusin", "touchstart"]) {
+    host.addEventListener(t, (e) => e.stopPropagation());
+  }
+  // Focus traps also watch `focusout` on the document and pull focus back when
+  // it leaves the dialog; let it move into the picker (e.g. the note box).
+  window.addEventListener(
+    "focusout",
+    (e) => {
+      if (e.relatedTarget instanceof Node && host.contains(e.relatedTarget)) {
+        e.stopPropagation();
+      }
+    },
+    true,
+  );
   document.body.appendChild(host);
   createRoot(host).render(<DesignPicker />);
 }
diff --git a/packages/appkit-ui/src/react/design/inspect.ts b/packages/appkit-ui/src/react/design/inspect.ts
index e23354b24..e6617deec 100644
--- a/packages/appkit-ui/src/react/design/inspect.ts
+++ b/packages/appkit-ui/src/react/design/inspect.ts
@@ -150,6 +150,21 @@ function prepareClone(src: Element, dst: Element, tasks: Promise<unknown>[]) {
   }
   dst.setAttribute("style", css);
 
+  // Live form state lives in DOM properties, which serialization drops.
+  if (src instanceof HTMLInputElement) {
+    if (src.type === "checkbox" || src.type === "radio") {
+      dst.toggleAttribute("checked", src.checked);
+    } else {
+      dst.setAttribute("value", src.value);
+    }
+  } else if (src instanceof HTMLTextAreaElement) {
+    dst.textContent = src.value;
+  } else if (src instanceof HTMLSelectElement) {
+    dst.querySelectorAll("option").forEach((o, i) => {
+      o.toggleAttribute("selected", src.options[i]?.selected ?? false);
+    });
+  }
+
   if (src instanceof HTMLCanvasElement) {
     try {
       const img = document.createElement("img");

From 7f252c80c15175a8278da64a16b92eea6546d177 Mon Sep 17 00:00:00 2001
From: MarioCadenas <MarioCadenas@users.noreply.github.com>
Date: Wed, 21 Oct 2026 18:44:19 +0200
Subject: [PATCH 5/6] feat(appkit): design canvas posts selections to an
 embedding app builder

- The picker lives only on /design; app pages are no longer touched.
- Sends are posted with window.postMessage to the embedding window
  (window.parent, else window.opener) as a typed, versioned
  `appkit:design-selection` message, targeted only at the origins set in the
  new `builderOrigin` plugin option (bare origins only, "*" rejected).
  Screenshots are inline (data URL) and as a URL served by the new
  GET /api/design/screenshots/:name route. The .appkit/design-selection.json
  store and the selection API are unchanged.
- Redesigned canvas using appkit-ui components and theme tokens: sticky
  header with the Select toggle, frame sidebar, frames on cards over a dotted
  backdrop, numbered selection outlines matching a card-based send panel.
- Docs: builderOrigin, the message shape and a builder-side listener.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
---
 docs/docs/api/appkit/Variable.design.md       |   2 +-
 docs/docs/plugins/design.md                   |  47 ++-
 docs/static/appkit-ui/styles.gen.css          |  72 +++-
 packages/appkit-ui/src/react/beta.ts          |   9 +-
 .../react/design/__tests__/design.test.tsx    | 112 ++++-
 .../src/react/design/design-canvas.tsx        | 170 ++++++--
 .../src/react/design/design-picker.tsx        | 387 +++++++++++-------
 .../appkit-ui/src/react/design/message.ts     |  52 +++
 packages/appkit/src/plugins/design/index.ts   |  72 +++-
 .../appkit/src/plugins/design/manifest.json   |  14 +
 packages/appkit/src/plugins/design/store.ts   |   5 +
 .../src/plugins/design/tests/design.test.ts   |  22 +
 .../appkit/src/plugins/design/vite-plugin.ts  |  42 +-
 template/README.md.tmpl                       |   2 +-
 14 files changed, 782 insertions(+), 226 deletions(-)
 create mode 100644 packages/appkit-ui/src/react/design/message.ts

diff --git a/docs/docs/api/appkit/Variable.design.md b/docs/docs/api/appkit/Variable.design.md
index eed131b5d..755e09049 100644
--- a/docs/docs/api/appkit/Variable.design.md
+++ b/docs/docs/api/appkit/Variable.design.md
@@ -1,5 +1,5 @@
 # Variable: design
 
 ```ts
-const design: ToPlugin<typeof DesignPlugin, BasePluginConfig, "design">;
+const design: ToPlugin<typeof DesignPlugin, DesignConfig | undefined, "design">;
 ```
diff --git a/docs/docs/plugins/design.md b/docs/docs/plugins/design.md
index d290164d1..aaf068031 100644
--- a/docs/docs/plugins/design.md
+++ b/docs/docs/plugins/design.md
@@ -23,6 +23,12 @@ await createApp({
 });
 ```
 
+## Configuration
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `builderOrigin` | `string \| string[]` | Origin(s) of the app builder that embeds the app, for example `"https://builder.example.com"`. When `/design` runs inside that window, each send is also posted to it (see [Embedding in an app builder](#embedding-in-an-app-builder)). Must be a bare origin; `"*"` is rejected. |
+
 ## The `/design` canvas
 
 `/design` renders every PascalCase export of every file under `client/src/design/`, with no props, one frame each. Put two kinds of components there:
@@ -43,7 +49,7 @@ A frame that throws shows its error in place. It doesn't break the rest of the c
 
 ## Selecting elements
 
-In development, a **Select** button appears in the bottom-right corner of the canvas and of every app page. Click it, then click elements to add or remove them (Escape stops selecting). Add an optional note and click **Send to agent**.
+Selecting only happens on `/design`; app pages are left untouched. Click **Select** in the canvas header, then click elements to add or remove them (Escape stops selecting). Each selected element gets a numbered outline that matches its row in the send panel. Add an optional note and click **Send to agent**.
 
 Each element is traced back to its source `file:line:col`: the dev server tags native JSX elements with `data-source`, and the design plugin also tags component call sites (such as `<Button>` from a library) with `data-appkit-source`. The picker reads these, plus the nearest React component and its current props, from React's fiber tree. Screenshots include images, canvases, and CSS background images. Web fonts and cross-origin resources served without CORS are not embedded.
 
@@ -82,3 +88,42 @@ Screenshots are saved as image files next to it, so an agent can open them direc
 | `GET` | `/api/design/selection` | Read all pending selections |
 | `POST` | `/api/design/selection` | Add a selection (used by the picker) |
 | `DELETE` | `/api/design/selection` | Clear selections and screenshots once applied |
+| `GET` | `/api/design/screenshots/:name` | A saved screenshot image |
+
+## Embedding in an app builder
+
+When the app runs inside an app builder (in an iframe, or in a window it opened) and `builderOrigin` is set, each send is also posted to that window (`window.parent`, else `window.opener`) with `window.postMessage`. The message is targeted at exactly the configured origins, so the browser drops it if the window is on any other origin. The file and the routes above work the same either way.
+
+```ts
+import type { DesignSelectionMessage } from "@databricks/appkit-ui/react/beta";
+
+// In the app builder:
+window.addEventListener("message", (event) => {
+  if (event.origin !== "http://localhost:8000") return; // the app's dev server
+  const message = event.data as DesignSelectionMessage;
+  if (message?.type !== "appkit:design-selection" || message.version !== 1) return;
+  // message.note, message.selections[i].source, .props, .screenshot, ...
+});
+```
+
+```ts
+interface DesignSelectionMessage {
+  type: "appkit:design-selection";
+  version: 1;
+  id?: string;      // id in .appkit/design-selection.json
+  url: string;      // page the elements were picked on
+  note?: string;
+  selections: Array<{
+    component?: string;   // nearest React component
+    stack?: string[];     // owning components, innermost first
+    source?: string;      // "file:line:col"
+    props?: Record<string, unknown>;
+    tag: string;
+    text?: string;
+    screenshot?: string;    // JPEG data URL
+    screenshotUrl?: string; // same image, GET from the dev server
+  }>;
+}
+```
+
+The screenshot is inline as a data URL. `screenshotUrl` points at `GET /api/design/screenshots/:name` on the app's dev server.
diff --git a/docs/static/appkit-ui/styles.gen.css b/docs/static/appkit-ui/styles.gen.css
index 145f8db68..6e741b421 100644
--- a/docs/static/appkit-ui/styles.gen.css
+++ b/docs/static/appkit-ui/styles.gen.css
@@ -17,6 +17,7 @@
     --container-sm: 24rem;
     --container-md: 28rem;
     --container-lg: 32rem;
+    --container-7xl: 80rem;
     --text-xs: 0.75rem;
     --text-xs--line-height: calc(1 / 0.75);
     --text-sm: 0.875rem;
@@ -216,6 +217,9 @@
     container-type: inline-size;
     container-name: field-group;
   }
+  .pointer-events-auto {
+    pointer-events: auto;
+  }
   .pointer-events-none {
     pointer-events: none;
   }
@@ -266,6 +270,9 @@
   .-top-1 {
     top: calc(var(--spacing) * -1);
   }
+  .-top-2\.5 {
+    top: calc(var(--spacing) * -2.5);
+  }
   .-top-3 {
     top: calc(var(--spacing) * -3);
   }
@@ -287,6 +294,9 @@
   .top-4 {
     top: calc(var(--spacing) * 4);
   }
+  .top-22 {
+    top: calc(var(--spacing) * 22);
+  }
   .top-\[1px\] {
     top: 1px;
   }
@@ -320,12 +330,21 @@
   .right-4 {
     right: calc(var(--spacing) * 4);
   }
+  .right-6 {
+    right: calc(var(--spacing) * 6);
+  }
   .-bottom-12 {
     bottom: calc(var(--spacing) * -12);
   }
   .bottom-0 {
     bottom: calc(var(--spacing) * 0);
   }
+  .bottom-6 {
+    bottom: calc(var(--spacing) * 6);
+  }
+  .-left-2\.5 {
+    left: calc(var(--spacing) * -2.5);
+  }
   .-left-12 {
     left: calc(var(--spacing) * -12);
   }
@@ -356,6 +375,9 @@
   .z-\[1\] {
     z-index: 1;
   }
+  .z-\[2147483647\] {
+    z-index: 2147483647;
+  }
   .order-first {
     order: -9999;
   }
@@ -449,6 +471,9 @@
   .mt-4 {
     margin-top: calc(var(--spacing) * 4);
   }
+  .mt-24 {
+    margin-top: calc(var(--spacing) * 24);
+  }
   .mt-auto {
     margin-top: auto;
   }
@@ -467,9 +492,6 @@
   .mb-4 {
     margin-bottom: calc(var(--spacing) * 4);
   }
-  .mb-6 {
-    margin-bottom: calc(var(--spacing) * 6);
-  }
   .-ml-1 {
     margin-left: calc(var(--spacing) * -1);
   }
@@ -569,6 +591,10 @@
     width: calc(var(--spacing) * 4);
     height: calc(var(--spacing) * 4);
   }
+  .size-5 {
+    width: calc(var(--spacing) * 5);
+    height: calc(var(--spacing) * 5);
+  }
   .size-6 {
     width: calc(var(--spacing) * 6);
     height: calc(var(--spacing) * 6);
@@ -639,6 +665,9 @@
   .h-12 {
     height: calc(var(--spacing) * 12);
   }
+  .h-14 {
+    height: calc(var(--spacing) * 14);
+  }
   .h-16 {
     height: calc(var(--spacing) * 16);
   }
@@ -675,6 +704,9 @@
   .h-auto {
     height: auto;
   }
+  .h-fit {
+    height: fit-content;
+  }
   .h-full {
     height: 100%;
   }
@@ -693,6 +725,9 @@
   .max-h-\(--radix-select-content-available-height\) {
     max-height: var(--radix-select-content-available-height);
   }
+  .max-h-48 {
+    max-height: calc(var(--spacing) * 48);
+  }
   .max-h-80 {
     max-height: calc(var(--spacing) * 80);
   }
@@ -783,6 +818,9 @@
   .w-48 {
     width: calc(var(--spacing) * 48);
   }
+  .w-52 {
+    width: calc(var(--spacing) * 52);
+  }
   .w-56 {
     width: calc(var(--spacing) * 56);
   }
@@ -795,6 +833,9 @@
   .w-80 {
     width: calc(var(--spacing) * 80);
   }
+  .w-\[22rem\] {
+    width: 22rem;
+  }
   .w-\[40px\] {
     width: 40px;
   }
@@ -846,6 +887,9 @@
   .max-w-\(--skeleton-width\) {
     max-width: var(--skeleton-width);
   }
+  .max-w-7xl {
+    max-width: var(--container-7xl);
+  }
   .max-w-\[80\%\] {
     max-width: 80%;
   }
@@ -1026,6 +1070,9 @@
   .scroll-my-1 {
     scroll-margin-block: calc(var(--spacing) * 1);
   }
+  .scroll-mt-20 {
+    scroll-margin-top: calc(var(--spacing) * 20);
+  }
   .scroll-py-1 {
     scroll-padding-block: calc(var(--spacing) * 1);
   }
@@ -1338,6 +1385,12 @@
   .bg-background {
     background-color: var(--background);
   }
+  .bg-background\/80 {
+    background-color: var(--background);
+    @supports (color: color-mix(in lab, red, red)) {
+      background-color: color-mix(in oklab, var(--background) 80%, transparent);
+    }
+  }
   .bg-background\/95 {
     background-color: var(--background);
     @supports (color: color-mix(in lab, red, red)) {
@@ -1524,6 +1577,9 @@
   .py-2 {
     padding-block: calc(var(--spacing) * 2);
   }
+  .py-2\.5 {
+    padding-block: calc(var(--spacing) * 2.5);
+  }
   .py-3 {
     padding-block: calc(var(--spacing) * 3);
   }
@@ -4166,6 +4222,11 @@
       display: flex;
     }
   }
+  .sm\:inline {
+    @media (width >= 40rem) {
+      display: inline;
+    }
+  }
   .sm\:max-w-\[425px\] {
     @media (width >= 40rem) {
       max-width: 425px;
@@ -4367,6 +4428,11 @@
       }
     }
   }
+  .lg\:flex {
+    @media (width >= 64rem) {
+      display: flex;
+    }
+  }
   .lg\:w-\[500px\] {
     @media (width >= 64rem) {
       width: 500px;
diff --git a/packages/appkit-ui/src/react/beta.ts b/packages/appkit-ui/src/react/beta.ts
index 762a0c7b1..3439a4cc2 100644
--- a/packages/appkit-ui/src/react/beta.ts
+++ b/packages/appkit-ui/src/react/beta.ts
@@ -77,7 +77,12 @@ export type {
 } from "./hooks/use-database-write";
 
 // Design canvas + element picker. Track the dev-only `design` plugin, which
-// ships at beta from '@databricks/appkit/beta' and mounts both for you.
+// ships at beta from '@databricks/appkit/beta' and serves the canvas for you.
 export { DesignCanvas, type DesignCanvasProps } from "./design/design-canvas";
-export { DesignPicker, mountDesignPicker } from "./design/design-picker";
+export { DesignPicker, type DesignPickerProps } from "./design/design-picker";
 export type { DesignElementInfo } from "./design/inspect";
+export {
+  DESIGN_SELECTION_MESSAGE,
+  type DesignSelectionMessage,
+  type DesignSelectionMessageElement,
+} from "./design/message";
diff --git a/packages/appkit-ui/src/react/design/__tests__/design.test.tsx b/packages/appkit-ui/src/react/design/__tests__/design.test.tsx
index 64a012a23..9c6f8974b 100644
--- a/packages/appkit-ui/src/react/design/__tests__/design.test.tsx
+++ b/packages/appkit-ui/src/react/design/__tests__/design.test.tsx
@@ -10,7 +10,6 @@ import { forwardRef, memo, useState } from "react";
 import { afterEach, describe, expect, test, vi } from "vitest";
 
 import { DesignCanvas } from "../design-canvas";
-import { DesignPicker } from "../design-picker";
 import { inspectElement } from "../inspect";
 
 afterEach(cleanup);
@@ -85,27 +84,51 @@ describe("DesignCanvas", () => {
   });
 });
 
+function renderCanvas(builderOrigins?: string[]) {
+  render(
+    <DesignCanvas
+      builderOrigins={builderOrigins}
+      modules={{
+        "/src/design/Actions.tsx": {
+          Actions: () => (
+            <>
+              <button type="button">First action</button>
+              <button type="button">Second action</button>
+            </>
+          ),
+        },
+      }}
+    />,
+  );
+}
+
+const okResponse = () =>
+  new Response(
+    JSON.stringify({
+      ok: true,
+      selection: {
+        id: "sel-1",
+        elements: [{ screenshot: ".appkit/design-screenshots/sel-1-0.jpeg" }],
+      },
+    }),
+    { status: 200 },
+  );
+
 describe("DesignPicker", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
   test("a finished send keeps picks added while it was in flight", async () => {
     let release!: () => void;
     const fetchMock = vi.fn(
       () =>
         new Promise<Response>((resolve) => {
-          release = () => resolve(new Response("{}", { status: 200 }));
+          release = () => resolve(okResponse());
         }),
     );
     vi.stubGlobal("fetch", fetchMock);
-    render(
-      <>
-        <button type="button">First action</button>
-        <button type="button">Second action</button>
-        <div id="appkit-design-picker">
-          <DesignPicker />
-        </div>
-      </>,
-    );
+    renderCanvas();
 
-    fireEvent.click(screen.getByText("Select"));
+    fireEvent.click(screen.getByRole("button", { name: /Select/ }));
     fireEvent.click(screen.getByText("First action"));
     fireEvent.click(screen.getByText("Send 1 to agent"));
     await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
@@ -124,6 +147,69 @@ describe("DesignPicker", () => {
     await waitFor(() =>
       expect(screen.getByText("Send 1 to agent")).toBeTruthy(),
     );
-    vi.unstubAllGlobals();
+  });
+
+  test("posts the selection to the embedding builder, only to its origin", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => okResponse()),
+    );
+    const postMessage = vi.fn();
+    const parent = Object.getOwnPropertyDescriptor(window, "parent");
+    Object.defineProperty(window, "parent", {
+      configurable: true,
+      value: { postMessage },
+    });
+    try {
+      renderCanvas(["https://builder.example.com"]);
+      fireEvent.click(screen.getByRole("button", { name: /Select/ }));
+      fireEvent.click(screen.getByText("First action"));
+      fireEvent.change(screen.getByPlaceholderText(/What should change/), {
+        target: { value: "make it primary" },
+      });
+      fireEvent.click(screen.getByText("Send 1 to agent"));
+      await screen.findByText("Sent to the app builder.");
+
+      expect(postMessage).toHaveBeenCalledTimes(1);
+      const [message, origin] = postMessage.mock.calls[0];
+      expect(origin).toBe("https://builder.example.com");
+      expect(message).toMatchObject({
+        type: "appkit:design-selection",
+        version: 1,
+        id: "sel-1",
+        note: "make it primary",
+        selections: [
+          {
+            text: "First action",
+            screenshotUrl: `${location.origin}/api/design/screenshots/sel-1-0.jpeg`,
+          },
+        ],
+      });
+    } finally {
+      if (parent) Object.defineProperty(window, "parent", parent);
+    }
+  });
+
+  test("without a builder origin it only saves to the file", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => okResponse()),
+    );
+    const postMessage = vi.fn();
+    const parent = Object.getOwnPropertyDescriptor(window, "parent");
+    Object.defineProperty(window, "parent", {
+      configurable: true,
+      value: { postMessage },
+    });
+    try {
+      renderCanvas();
+      fireEvent.click(screen.getByRole("button", { name: /Select/ }));
+      fireEvent.click(screen.getByText("First action"));
+      fireEvent.click(screen.getByText("Send 1 to agent"));
+      await screen.findByText(/Saved to/);
+      expect(postMessage).not.toHaveBeenCalled();
+    } finally {
+      if (parent) Object.defineProperty(window, "parent", parent);
+    }
   });
 });
diff --git a/packages/appkit-ui/src/react/design/design-canvas.tsx b/packages/appkit-ui/src/react/design/design-canvas.tsx
index 43f7340de..d0d1e7e4f 100644
--- a/packages/appkit-ui/src/react/design/design-canvas.tsx
+++ b/packages/appkit-ui/src/react/design/design-canvas.tsx
@@ -1,9 +1,30 @@
-import { Component, type ComponentType, type ReactNode } from "react";
+import { LayoutTemplate, MousePointerClick } from "lucide-react";
+import {
+  Component,
+  type ComponentType,
+  type ReactNode,
+  useCallback,
+  useState,
+} from "react";
+
+import { Badge } from "../ui/badge";
+import { Button } from "../ui/button";
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from "../ui/empty";
+import { Kbd } from "../ui/kbd";
+import { DesignPicker } from "./design-picker";
 
 /** Props for {@link DesignCanvas}. */
 export interface DesignCanvasProps {
   /** `import.meta.glob` result: module path → module exports. */
   modules: Record<string, Record<string, unknown>>;
+  /** Origins an embedding app builder may be on (the plugin's `builderOrigin`). */
+  builderOrigins?: string[];
 }
 
 /** memo / forwardRef components are objects, not functions. */
@@ -38,50 +59,143 @@ class Boundary extends Component<{ children: ReactNode }, { error?: Error }> {
   }
 }
 
+/** Dotted backdrop so frame content reads as "on the canvas". */
+const CANVAS_BACKDROP = {
+  backgroundImage:
+    "radial-gradient(color-mix(in oklch, var(--border) 90%, transparent) 1px, transparent 1px)",
+  backgroundSize: "16px 16px",
+};
+
 /**
  * Renders every PascalCase export of every module under `client/src/design/`
- * with no props, one frame each. Drafts and previews (real components wrapped
- * with mock data) are both just zero-prop components in that folder.
+ * with no props, one frame each, plus the element picker. Drafts and previews
+ * (real components wrapped with mock data) are both just zero-prop components
+ * in that folder.
  *
  * Served by the `design()` plugin at `/design` in development.
  */
-export function DesignCanvas({ modules }: DesignCanvasProps) {
-  const frames = Object.entries(modules)
+export function DesignCanvas({ modules, builderOrigins }: DesignCanvasProps) {
+  const [selecting, setSelecting] = useState(false);
+  const onActiveChange = useCallback((v: boolean) => setSelecting(v), []);
+
+  const files = Object.entries(modules)
     .sort(([a], [b]) => a.localeCompare(b))
-    .flatMap(([file, mod]) =>
-      Object.entries(mod)
+    .map(([path, mod]) => ({
+      file: path.replace(/^\/src\/design\//, ""),
+      frames: Object.entries(mod)
         .filter(([name, value]) => /^[A-Z]/.test(name) && isComponent(value))
         .map(([name, value]) => ({
-          id: `${file}#${name}`,
-          label: `${file.replace(/^\/src\/design\//, "")} · ${name}`,
+          id: `${path}#${name}`,
+          name,
           Frame: value as ComponentType,
         })),
-    );
+    }))
+    .filter((f) => f.frames.length > 0);
+  const count = files.reduce((n, f) => n + f.frames.length, 0);
 
   return (
-    <div className="min-h-screen bg-muted/40 p-8">
-      <h1 className="mb-6 text-lg font-semibold">Design canvas</h1>
-      {frames.length === 0 ? (
-        <p className="text-muted-foreground text-sm">
-          No designs yet. Export components from files in{" "}
-          <code>client/src/design/</code> and they show up here.
+    <div className="bg-muted/40 text-foreground min-h-screen">
+      <header
+        data-design-chrome
+        className="bg-background/80 sticky top-0 z-10 flex h-14 items-center gap-3 border-b px-6 backdrop-blur"
+      >
+        <LayoutTemplate className="text-muted-foreground size-5" />
+        <h1 className="text-sm font-semibold">Design canvas</h1>
+        <Badge variant="secondary">
+          {count} {count === 1 ? "frame" : "frames"}
+        </Badge>
+        <p className="text-muted-foreground ml-2 hidden text-xs md:block">
+          Pick the parts you want changed and send them to your agent.
         </p>
+        <div className="ml-auto flex items-center gap-2">
+          {selecting && (
+            <span className="text-muted-foreground hidden text-xs sm:inline">
+              <Kbd>Esc</Kbd> to stop
+            </span>
+          )}
+          <Button
+            size="sm"
+            variant={selecting ? "default" : "outline"}
+            aria-pressed={selecting}
+            onClick={() => setSelecting((s) => !s)}
+          >
+            <MousePointerClick className="size-4" />
+            {selecting ? "Selecting" : "Select"}
+          </Button>
+        </div>
+      </header>
+
+      {count === 0 ? (
+        <Empty className="mx-auto mt-24 max-w-md">
+          <EmptyHeader>
+            <EmptyMedia variant="icon">
+              <LayoutTemplate />
+            </EmptyMedia>
+            <EmptyTitle>No designs yet</EmptyTitle>
+            <EmptyDescription>
+              Export components from files in <code>client/src/design/</code>{" "}
+              and they show up here.
+            </EmptyDescription>
+          </EmptyHeader>
+        </Empty>
       ) : (
-        <div className="flex flex-col gap-8">
-          {frames.map(({ id, label, Frame }) => (
-            <section key={id}>
-              <h2 className="text-muted-foreground mb-2 font-mono text-xs">
-                {label}
-              </h2>
-              <div className="bg-background rounded-lg border p-6">
-                <Boundary>
-                  <Frame />
-                </Boundary>
+        <div className="mx-auto flex max-w-7xl gap-8 px-6 py-8">
+          <nav
+            data-design-chrome
+            className="sticky top-22 hidden h-fit w-52 shrink-0 flex-col gap-4 lg:flex"
+          >
+            {files.map(({ file, frames }) => (
+              <div key={file} className="flex flex-col gap-1">
+                <div className="text-muted-foreground px-2 font-mono text-[11px]">
+                  {file}
+                </div>
+                {frames.map(({ id, name }) => (
+                  <a
+                    key={id}
+                    href={`#${encodeURIComponent(id)}`}
+                    className="hover:bg-accent hover:text-accent-foreground truncate rounded-md px-2 py-1 text-sm"
+                  >
+                    {name}
+                  </a>
+                ))}
               </div>
-            </section>
-          ))}
+            ))}
+          </nav>
+
+          <main className="flex min-w-0 flex-1 flex-col gap-8">
+            {files.flatMap(({ file, frames }) =>
+              frames.map(({ id, name, Frame }) => (
+                <section
+                  key={id}
+                  id={encodeURIComponent(id)}
+                  className="bg-card scroll-mt-20 overflow-hidden rounded-xl border shadow-sm"
+                >
+                  <div
+                    data-design-chrome
+                    className="flex items-center gap-2 border-b px-4 py-2.5"
+                  >
+                    <h2 className="text-sm font-medium">{name}</h2>
+                    <span className="text-muted-foreground font-mono text-xs">
+                      {file}
+                    </span>
+                  </div>
+                  <div className="p-8" style={CANVAS_BACKDROP}>
+                    <Boundary>
+                      <Frame />
+                    </Boundary>
+                  </div>
+                </section>
+              )),
+            )}
+          </main>
         </div>
       )}
+
+      <DesignPicker
+        active={selecting}
+        onActiveChange={onActiveChange}
+        builderOrigins={builderOrigins}
+      />
     </div>
   );
 }
diff --git a/packages/appkit-ui/src/react/design/design-picker.tsx b/packages/appkit-ui/src/react/design/design-picker.tsx
index af4c3b933..7eb4985fd 100644
--- a/packages/appkit-ui/src/react/design/design-picker.tsx
+++ b/packages/appkit-ui/src/react/design/design-picker.tsx
@@ -1,80 +1,110 @@
-import { type CSSProperties, useEffect, useReducer, useState } from "react";
-import { createRoot } from "react-dom/client";
+import { MousePointerClick, Send, X } from "lucide-react";
+import {
+  type CSSProperties,
+  useEffect,
+  useReducer,
+  useRef,
+  useState,
+} from "react";
 
+import { Badge } from "../ui/badge";
+import { Button } from "../ui/button";
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from "../ui/card";
+import { Textarea } from "../ui/textarea";
 import {
   captureElement,
   type DesignElementInfo,
   inspectElement,
 } from "./inspect";
+import {
+  DESIGN_SELECTION_MESSAGE,
+  type DesignSelectionMessage,
+  postDesignSelection,
+} from "./message";
 
-/** Endpoint the `design()` plugin mounts in development. */
+/** Endpoints the `design()` plugin mounts in development. */
 const SELECTION_ENDPOINT = "/api/design/selection";
+const SCREENSHOT_ENDPOINT = "/api/design/screenshots";
 const ROOT_ID = "appkit-design-picker";
-/** Same violet as the `<Variants>` picker, so dev chrome reads as dev chrome. */
-const ACCENT = "#8b5cf6";
 
-type Status = "idle" | "sending" | "sent" | "error";
+type Status = "idle" | "sending" | "sent-builder" | "sent-file" | "error";
 
 interface Picked {
   el: Element;
   info: DesignElementInfo;
 }
 
-function box(el: Element, style: CSSProperties, key?: number) {
+/** Props for {@link DesignPicker}. */
+export interface DesignPickerProps {
+  /** Whether clicks select elements. */
+  active: boolean;
+  onActiveChange: (active: boolean) => void;
+  /** Origins an embedding app builder may be on (the plugin's `builderOrigin`). */
+  builderOrigins?: string[];
+}
+
+function Outline({
+  el,
+  style,
+  label,
+}: {
+  el: Element;
+  style: CSSProperties;
+  label?: number;
+}) {
   const r = el.getBoundingClientRect();
   return (
     <div
-      key={key}
+      className="pointer-events-none fixed rounded-sm"
       style={{
-        position: "fixed",
         top: r.top,
         left: r.left,
         width: r.width,
         height: r.height,
-        pointerEvents: "none",
-        borderRadius: 2,
         ...style,
       }}
-    />
+    >
+      {label !== undefined && (
+        <span className="bg-primary text-primary-foreground absolute -top-2.5 -left-2.5 flex size-5 items-center justify-center rounded-full text-[10px] font-semibold shadow">
+          {label}
+        </span>
+      )}
+    </div>
   );
 }
 
-const panel: CSSProperties = {
-  position: "fixed",
-  right: 16,
-  bottom: 64,
-  width: 320,
-  maxHeight: "60vh",
-  overflow: "auto",
-  background: "#fff",
-  color: "#111",
-  border: `1px solid ${ACCENT}`,
-  borderRadius: 8,
-  padding: 12,
-  font: "12px/1.4 system-ui, sans-serif",
-  boxShadow: "0 8px 24px rgba(0,0,0,.18)",
+const HOVER_STYLE: CSSProperties = {
+  outline: "2px dashed var(--primary)",
+  outlineOffset: 2,
 };
-
-const button: CSSProperties = {
-  background: ACCENT,
-  color: "#fff",
-  border: 0,
-  borderRadius: 6,
-  padding: "6px 12px",
-  font: "600 12px system-ui, sans-serif",
-  cursor: "pointer",
+const SELECTED_STYLE: CSSProperties = {
+  outline: "2px solid var(--primary)",
+  outlineOffset: 2,
+  background: "color-mix(in oklch, var(--primary) 10%, transparent)",
 };
 
 /**
- * Dev-only click-to-select overlay. Toggle it with the floating button (or
- * Escape to stop), click elements to add/remove them, add a note, and send the
- * selection to the `design()` plugin for the coding agent to pick up.
+ * Click-to-select overlay and send panel of the design canvas. While
+ * `active`, clicks select or deselect elements (Escape stops). Sends are
+ * persisted by the `design()` plugin and, when the canvas is embedded by an
+ * allowed app builder, posted to it as a {@link DesignSelectionMessage}.
  *
- * Injected into every page by the design plugin's dev server; you don't
- * render it yourself.
+ * Rendered by {@link DesignCanvas}; you don't mount it yourself.
  */
-export function DesignPicker() {
-  const [active, setActive] = useState(false);
+export function DesignPicker({
+  active,
+  onActiveChange,
+  builderOrigins = [],
+}: DesignPickerProps) {
+  const rootRef = useRef<HTMLDivElement>(null);
   const [hovered, setHovered] = useState<Element | null>(null);
   const [picked, setPicked] = useState<Picked[]>([]);
   const [note, setNote] = useState("");
@@ -91,10 +121,34 @@ export function DesignPicker() {
     };
   }, []);
 
+  // Modal dialogs set `pointer-events: none` on <body>, dismiss on any outside
+  // press and trap focus. The picker (outside the dialog) must stay usable and
+  // must not count as "outside".
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root) return;
+    const stop = (e: Event) => e.stopPropagation();
+    const PRESS = ["pointerdown", "mousedown", "focusin", "touchstart"];
+    for (const t of PRESS) root.addEventListener(t, stop);
+    // Focus traps watch `focusout` on the document and pull focus back when
+    // it leaves the dialog; let it move into the picker (e.g. the note box).
+    const onFocusOut = (e: FocusEvent) => {
+      if (e.relatedTarget instanceof Node && root.contains(e.relatedTarget)) {
+        e.stopPropagation();
+      }
+    };
+    window.addEventListener("focusout", onFocusOut, true);
+    return () => {
+      for (const t of PRESS) root.removeEventListener(t, stop);
+      window.removeEventListener("focusout", onFocusOut, true);
+    };
+  }, []);
+
   useEffect(() => {
     if (!active) return;
     const own = (t: EventTarget | null) =>
-      !(t instanceof Element) || !!t.closest(`#${ROOT_ID}`);
+      !(t instanceof Element) ||
+      !!t.closest(`#${ROOT_ID}, [data-design-chrome]`);
     const onMove = (e: MouseEvent) =>
       setHovered(own(e.target) ? null : (e.target as Element));
     const onClick = (e: MouseEvent) => {
@@ -116,7 +170,8 @@ export function DesignPicker() {
       e.preventDefault();
       e.stopPropagation();
     };
-    const onKey = (e: KeyboardEvent) => e.key === "Escape" && setActive(false);
+    const onKey = (e: KeyboardEvent) =>
+      e.key === "Escape" && onActiveChange(false);
     const PRESS = ["pointerdown", "mousedown", "pointerup", "mouseup"];
     document.addEventListener("mousemove", onMove, true);
     document.addEventListener("click", onClick, true);
@@ -129,14 +184,14 @@ export function DesignPicker() {
       for (const t of PRESS) window.removeEventListener(t, swallow, true);
       setHovered(null);
     };
-  }, [active]);
+  }, [active, onActiveChange]);
 
   async function send() {
     setStatus("sending");
     // Picks and the note can change while the request is in flight; only
     // what was actually sent is cleared afterwards.
     const sending = picked;
-    const sentNote = note;
+    const sentNote = note.trim() || undefined;
     try {
       const elements = await Promise.all(
         sending.map(async ({ el, info }) => ({
@@ -149,127 +204,171 @@ export function DesignPicker() {
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
           elements,
-          note: sentNote.trim() || undefined,
+          note: sentNote,
           url: location.pathname,
         }),
       });
       if (!res.ok) throw new Error(String(res.status));
+      const { selection } = (await res.json()) as {
+        selection?: { id: string; elements: { screenshot?: string }[] };
+      };
+
+      const message: DesignSelectionMessage = {
+        type: DESIGN_SELECTION_MESSAGE,
+        version: 1,
+        id: selection?.id,
+        url: location.pathname,
+        ...(sentNote ? { note: sentNote } : {}),
+        selections: elements.map((el, i) => {
+          const saved = selection?.elements[i]?.screenshot;
+          return saved
+            ? {
+                ...el,
+                screenshotUrl: `${location.origin}${SCREENSHOT_ENDPOINT}/${saved.split("/").pop()}`,
+              }
+            : el;
+        }),
+      };
+      const posted = postDesignSelection(message, builderOrigins);
+
       setPicked((prev) => {
         const remaining = prev.filter((p) => !sending.includes(p));
         // Idempotent, so safe in an updater that StrictMode may run twice.
-        if (remaining.length === 0) setActive(false);
+        if (remaining.length === 0) onActiveChange(false);
         return remaining;
       });
-      setNote((n) => (n === sentNote ? "" : n));
-      setStatus("sent");
+      setNote((n) => (n.trim() === (sentNote ?? "") ? "" : n));
+      setStatus(posted ? "sent-builder" : "sent-file");
     } catch {
       setStatus("error");
     }
   }
 
+  const showPanel = active || picked.length > 0 || status !== "idle";
+
   return (
-    <>
-      {active && hovered && box(hovered, { outline: `2px dashed ${ACCENT}` })}
-      {picked.map((p, i) =>
-        box(
-          p.el,
-          { outline: `2px solid ${ACCENT}`, background: `${ACCENT}22` },
-          i,
-        ),
-      )}
-      {(picked.length > 0 || status !== "idle") && (
-        <div style={panel}>
-          {picked.map((p, i) => (
-            <div
-              key={`${p.info.source}-${i}`}
-              style={{ display: "flex", gap: 8, marginBottom: 6 }}
-            >
-              <div style={{ flex: 1, minWidth: 0 }}>
-                <strong>{p.info.component ?? `<${p.info.tag}>`}</strong>
-                <div style={{ color: "#666", wordBreak: "break-all" }}>
-                  {p.info.source ?? "no source location"}
-                </div>
-              </div>
-              <button
-                type="button"
-                aria-label="Remove"
-                style={{ ...button, background: "transparent", color: "#666" }}
-                onClick={() =>
-                  setPicked((prev) => prev.filter((x) => x.el !== p.el))
-                }
-              >
-                ×
-              </button>
-            </div>
-          ))}
+    <div
+      ref={rootRef}
+      id={ROOT_ID}
+      className="pointer-events-auto relative z-[2147483647]"
+    >
+      {active && hovered && <Outline el={hovered} style={HOVER_STYLE} />}
+      {picked.map((p, i) => (
+        <Outline key={i} el={p.el} style={SELECTED_STYLE} label={i + 1} />
+      ))}
+      {showPanel && (
+        <Card className="fixed right-6 bottom-6 w-[22rem] gap-4 py-4 shadow-lg">
+          <CardHeader className="px-4">
+            <CardTitle className="text-sm">
+              {picked.length > 0
+                ? `${picked.length} selected`
+                : active
+                  ? "Selecting"
+                  : "Selection"}
+            </CardTitle>
+            <CardDescription className="text-xs">
+              {active
+                ? "Click elements to add or remove them. Esc to stop."
+                : "Turn on Select to pick more elements."}
+            </CardDescription>
+            {picked.length > 0 && (
+              <CardAction>
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  onClick={() => setPicked([])}
+                  disabled={status === "sending"}
+                >
+                  Clear
+                </Button>
+              </CardAction>
+            )}
+          </CardHeader>
+
           {picked.length > 0 && (
-            <>
-              <textarea
-                placeholder="Note for the agent (optional)"
+            <CardContent className="flex flex-col gap-3 px-4">
+              <ul className="flex max-h-48 flex-col gap-1 overflow-y-auto">
+                {picked.map((p, i) => (
+                  <li
+                    key={i}
+                    className="hover:bg-muted flex items-center gap-2 rounded-md px-1.5 py-1"
+                  >
+                    <span className="bg-primary text-primary-foreground flex size-5 shrink-0 items-center justify-center rounded-full text-[10px] font-semibold">
+                      {i + 1}
+                    </span>
+                    <div className="min-w-0 flex-1">
+                      <div className="flex items-center gap-1.5">
+                        <span className="truncate text-sm font-medium">
+                          {p.info.component ?? `<${p.info.tag}>`}
+                        </span>
+                        <Badge
+                          variant="secondary"
+                          className="px-1.5 py-0 font-mono text-[10px]"
+                        >
+                          {p.info.tag}
+                        </Badge>
+                      </div>
+                      <div className="text-muted-foreground truncate font-mono text-[11px]">
+                        {p.info.source ?? "no source location"}
+                      </div>
+                    </div>
+                    <Button
+                      variant="ghost"
+                      size="icon"
+                      className="size-7"
+                      aria-label="Remove"
+                      onClick={() =>
+                        setPicked((prev) => prev.filter((x) => x.el !== p.el))
+                      }
+                    >
+                      <X className="size-3.5" />
+                    </Button>
+                  </li>
+                ))}
+              </ul>
+              <Textarea
+                placeholder="What should change? (optional)"
                 value={note}
                 onChange={(e) => setNote(e.target.value)}
                 rows={3}
-                style={{
-                  width: "100%",
-                  boxSizing: "border-box",
-                  margin: "6px 0",
-                }}
+                className="resize-none text-sm"
               />
-              <button
-                type="button"
-                style={button}
-                disabled={status === "sending"}
-                onClick={send}
-              >
+            </CardContent>
+          )}
+
+          <CardFooter className="flex-col items-stretch gap-2 px-4">
+            {picked.length > 0 ? (
+              <Button disabled={status === "sending"} onClick={send}>
+                <Send className="size-4" />
                 {status === "sending"
                   ? "Sending…"
                   : `Send ${picked.length} to agent`}
-              </button>
-            </>
-          )}
-          {status === "sent" && <div>Sent. Ask your agent to apply it.</div>}
-          {status === "error" && (
-            <div style={{ color: "#b91c1c" }}>
-              Couldn't send. Is the design() plugin registered?
-            </div>
-          )}
-        </div>
+              </Button>
+            ) : (
+              active && (
+                <div className="text-muted-foreground flex items-center gap-2 text-xs">
+                  <MousePointerClick className="size-4" />
+                  Nothing selected yet
+                </div>
+              )
+            )}
+            {status === "sent-builder" && (
+              <p className="text-xs">Sent to the app builder.</p>
+            )}
+            {status === "sent-file" && (
+              <p className="text-xs">
+                Saved to <code>.appkit/design-selection.json</code>. Ask your
+                agent to apply it.
+              </p>
+            )}
+            {status === "error" && (
+              <p className="text-destructive text-xs">
+                Couldn't send. Is the design() plugin registered?
+              </p>
+            )}
+          </CardFooter>
+        </Card>
       )}
-      <button
-        type="button"
-        style={{ ...button, position: "fixed", right: 16, bottom: 16 }}
-        aria-pressed={active}
-        onClick={() => setActive((a) => !a)}
-      >
-        {active ? "Selecting… (Esc)" : "Select"}
-      </button>
-    </>
-  );
-}
-
-/** Mounts {@link DesignPicker} into its own root on `document.body`, once. */
-export function mountDesignPicker() {
-  if (document.getElementById(ROOT_ID)) return;
-  const host = document.createElement("div");
-  host.id = ROOT_ID;
-  // Modal dialogs set `pointer-events: none` on <body> and dismiss on any
-  // outside press; the picker must stay usable and not count as "outside".
-  host.style.cssText =
-    "position:relative;z-index:2147483647;pointer-events:auto";
-  for (const t of ["pointerdown", "mousedown", "focusin", "touchstart"]) {
-    host.addEventListener(t, (e) => e.stopPropagation());
-  }
-  // Focus traps also watch `focusout` on the document and pull focus back when
-  // it leaves the dialog; let it move into the picker (e.g. the note box).
-  window.addEventListener(
-    "focusout",
-    (e) => {
-      if (e.relatedTarget instanceof Node && host.contains(e.relatedTarget)) {
-        e.stopPropagation();
-      }
-    },
-    true,
+    </div>
   );
-  document.body.appendChild(host);
-  createRoot(host).render(<DesignPicker />);
 }
diff --git a/packages/appkit-ui/src/react/design/message.ts b/packages/appkit-ui/src/react/design/message.ts
new file mode 100644
index 000000000..4ca2317bf
--- /dev/null
+++ b/packages/appkit-ui/src/react/design/message.ts
@@ -0,0 +1,52 @@
+import type { DesignElementInfo } from "./inspect";
+
+/** `type` of the message the design canvas posts to an embedding app builder. */
+export const DESIGN_SELECTION_MESSAGE = "appkit:design-selection";
+
+/** One selected element in a {@link DesignSelectionMessage}. */
+export interface DesignSelectionMessageElement extends DesignElementInfo {
+  /** JPEG data URL of the element, when it could be captured. */
+  screenshot?: string;
+  /** Absolute URL of the same image, served by the app's dev server. */
+  screenshotUrl?: string;
+}
+
+/**
+ * Posted with `window.postMessage` to the app builder that embeds the app
+ * (`window.parent`, else `window.opener`) each time the user sends a
+ * selection from `/design`. Only posted to the `builderOrigin`s configured on
+ * the `design()` plugin.
+ *
+ * Bump `version` on any incompatible change to this shape.
+ */
+export interface DesignSelectionMessage {
+  type: typeof DESIGN_SELECTION_MESSAGE;
+  version: 1;
+  /** Id of the selection in `.appkit/design-selection.json`. */
+  id?: string;
+  /** Page the elements were picked on. */
+  url: string;
+  note?: string;
+  selections: DesignSelectionMessageElement[];
+}
+
+/** The window embedding this one: the iframe parent, else the opener. */
+function builderWindow(): Window | null {
+  if (window.parent !== window) return window.parent;
+  return window.opener as Window | null;
+}
+
+/**
+ * Posts the message to the embedding window once per allowed origin. The
+ * browser drops it for any origin the window isn't on, so it never reaches an
+ * unexpected page. Returns whether there was a window and an origin to post to.
+ */
+export function postDesignSelection(
+  message: DesignSelectionMessage,
+  builderOrigins: string[],
+): boolean {
+  const target = builderWindow();
+  if (!target || builderOrigins.length === 0) return false;
+  for (const origin of builderOrigins) target.postMessage(message, origin);
+  return true;
+}
diff --git a/packages/appkit/src/plugins/design/index.ts b/packages/appkit/src/plugins/design/index.ts
index b27984c52..d2273d67b 100644
--- a/packages/appkit/src/plugins/design/index.ts
+++ b/packages/appkit/src/plugins/design/index.ts
@@ -1,3 +1,5 @@
+import path from "node:path";
+
 import type { BasePluginConfig, IAppRouter } from "shared";
 
 import { createLogger } from "../../logging/logger";
@@ -5,33 +7,71 @@ import { Plugin, toPlugin } from "../../plugin";
 import { defineManifest } from "../../registry";
 import { reactSourceLocPlugin } from "../server/react-source-loc-vite-plugin";
 import manifest from "./manifest.json";
-import { type DesignSelectionInput, DesignSelectionStore } from "./store";
+import {
+  type DesignSelectionInput,
+  DesignSelectionStore,
+  SCREENSHOT_NAME,
+} from "./store";
 import { designVitePlugin } from "./vite-plugin";
 
 const logger = createLogger("design");
 
 const isDev = () => process.env.NODE_ENV === "development";
 
+interface DesignConfig extends BasePluginConfig {
+  /**
+   * Origin(s) of the app builder that embeds the app, e.g.
+   * `"https://builder.example.com"`. When `/design` runs inside that window
+   * (as an iframe, or opened by it), each send is also posted to it with
+   * `window.postMessage`, targeted at exactly these origins. `"*"` and
+   * anything that isn't a bare origin are rejected.
+   */
+  builderOrigin?: string | string[];
+}
+
+function parseOrigins(value: DesignConfig["builderOrigin"]): string[] {
+  const list = value === undefined ? [] : [value].flat();
+  return list.map((origin) => {
+    let parsed: URL | undefined;
+    try {
+      parsed = new URL(origin);
+    } catch {}
+    if (!parsed || parsed.origin === "null" || parsed.origin !== origin) {
+      throw new Error(
+        `design(): builderOrigin "${origin}" must be a bare origin like "https://builder.example.com" ("*" is not allowed)`,
+      );
+    }
+    return origin;
+  });
+}
+
 /**
  * Dev-only design canvas.
  *
  * In development it contributes a Vite plugin that serves `/design` (a canvas
- * rendering every component exported from `client/src/design/`) and injects
- * the click-to-select picker into every page of the app. Picked elements are
- * POSTed to `/api/design/selection` and persisted to
- * `.appkit/design-selection.json`, where a coding agent picks them up.
+ * rendering every component exported from `client/src/design/`, with a
+ * click-to-select picker). Each send is persisted through
+ * `/api/design/selection` to `.appkit/design-selection.json`, and, when the
+ * canvas is embedded by an allowed app builder (`builderOrigin`), also posted
+ * to that window as an `appkit:design-selection` message.
  *
  * In any other environment it does nothing except answer `/design` with 404.
  * The manifest is deliberately not `devOnly`: a dropped plugin couldn't claim
  * `/design`, and the SPA fallback would serve the app's index.html for it.
  */
-class DesignPlugin extends Plugin<BasePluginConfig> {
+class DesignPlugin extends Plugin<DesignConfig> {
   static manifest = defineManifest<"design">(manifest);
 
   protected static description =
     "Dev-only design canvas and element picker for coding agents";
 
   private readonly store = new DesignSelectionStore();
+  private readonly builderOrigins: string[];
+
+  constructor(config: DesignConfig = {} as DesignConfig) {
+    super(config);
+    this.builderOrigins = parseOrigins(config.builderOrigin);
+  }
 
   async setup() {
     if (isDev()) return;
@@ -44,7 +84,7 @@ class DesignPlugin extends Plugin<BasePluginConfig> {
   vitePlugins() {
     if (!isDev()) return [];
     return [
-      designVitePlugin(),
+      designVitePlugin({ builderOrigins: this.builderOrigins }),
       // Locates component call sites (`<Button>`), which the server's own
       // transform skips because it only tags native elements.
       reactSourceLocPlugin({ projectRoot: process.cwd(), components: true }),
@@ -85,7 +125,23 @@ class DesignPlugin extends Plugin<BasePluginConfig> {
           id: selection.id,
           elements: selection.elements.length,
         });
-        res.json({ ok: true, id: selection.id, file: this.store.filePath });
+        res.json({ ok: true, selection, file: this.store.filePath });
+      },
+    });
+
+    this.route(router, {
+      name: "screenshot",
+      method: "get",
+      path: "/screenshots/:name",
+      handler: async (req, res) => {
+        const name = String(req.params.name);
+        if (!SCREENSHOT_NAME.test(name)) {
+          res.status(404).end();
+          return;
+        }
+        res.sendFile(path.join(this.store.screenshotDir, name), (error) => {
+          if (error && !res.headersSent) res.status(404).end();
+        });
       },
     });
 
diff --git a/packages/appkit/src/plugins/design/manifest.json b/packages/appkit/src/plugins/design/manifest.json
index d54d984c1..f872bdca4 100644
--- a/packages/appkit/src/plugins/design/manifest.json
+++ b/packages/appkit/src/plugins/design/manifest.json
@@ -7,5 +7,19 @@
   "resources": {
     "required": [],
     "optional": []
+  },
+  "config": {
+    "schema": {
+      "type": "object",
+      "properties": {
+        "builderOrigin": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Origins of the app builder that embeds the app (e.g. [\"https://builder.example.com\"]; a single string is also accepted). When /design runs inside that window (iframe parent or opener), each send is also posted to it with window.postMessage. '*' is not allowed."
+        }
+      }
+    }
   }
 }
diff --git a/packages/appkit/src/plugins/design/store.ts b/packages/appkit/src/plugins/design/store.ts
index 6f5b7e9b2..89516d72b 100644
--- a/packages/appkit/src/plugins/design/store.ts
+++ b/packages/appkit/src/plugins/design/store.ts
@@ -6,6 +6,9 @@ import path from "node:path";
 const SELECTION_FILE = ".appkit/design-selection.json";
 const SCREENSHOT_DIR = ".appkit/design-screenshots";
 
+/** File names the store writes into {@link SCREENSHOT_DIR}. */
+export const SCREENSHOT_NAME = /^[A-Za-z0-9-]+\.(png|jpeg)$/;
+
 const DATA_URL = /^data:image\/(png|jpeg);base64,([A-Za-z0-9+/=]+)$/;
 
 /** One picked element, as sent by the browser picker. */
@@ -53,12 +56,14 @@ const str = (v: unknown) => (typeof v === "string" ? v : undefined);
  */
 export class DesignSelectionStore {
   readonly filePath: string;
+  readonly screenshotDir: string;
   private readonly root: string;
   private queue: Promise<unknown> = Promise.resolve();
 
   constructor(root: string = process.cwd()) {
     this.root = root;
     this.filePath = path.resolve(root, SELECTION_FILE);
+    this.screenshotDir = path.resolve(root, SCREENSHOT_DIR);
   }
 
   async read(): Promise<DesignSelectionFile> {
diff --git a/packages/appkit/src/plugins/design/tests/design.test.ts b/packages/appkit/src/plugins/design/tests/design.test.ts
index 6ef4e19bd..aab9999e9 100644
--- a/packages/appkit/src/plugins/design/tests/design.test.ts
+++ b/packages/appkit/src/plugins/design/tests/design.test.ts
@@ -80,6 +80,28 @@ describe("DesignSelectionStore", () => {
   });
 });
 
+describe("builderOrigin", () => {
+  const construct = (builderOrigin: string | string[]) => {
+    const { plugin: DesignPlugin, config } = design({ builderOrigin });
+    return new DesignPlugin(config);
+  };
+
+  test("accepts bare origins", () => {
+    expect(() =>
+      construct(["https://builder.example.com", "http://localhost:3000"]),
+    ).not.toThrow();
+  });
+
+  test.each([
+    "*",
+    "https://builder.example.com/path",
+    "builder.example.com",
+    "null",
+  ])("rejects %s", (origin) => {
+    expect(() => construct(origin)).toThrow(/bare origin/);
+  });
+});
+
 describe("design plugin outside development", () => {
   let app: TestApp<never> | undefined;
   afterEach(async () => {
diff --git a/packages/appkit/src/plugins/design/vite-plugin.ts b/packages/appkit/src/plugins/design/vite-plugin.ts
index 1706fa1b3..c54a8fb60 100644
--- a/packages/appkit/src/plugins/design/vite-plugin.ts
+++ b/packages/appkit/src/plugins/design/vite-plugin.ts
@@ -1,23 +1,22 @@
 import type { Plugin } from "vite";
 
 const CANVAS_ID = "virtual:appkit-design-canvas";
-const PICKER_ID = "virtual:appkit-design-picker";
 const url = (id: string) => `/@id/__x00__${id}`;
 
 // Globs are root-relative (root = the client dir), so `/src/design` is
-// `client/src/design`. `index.css` is optional; an empty glob is a no-op.
-const CANVAS_MODULE = `
+// `client/src/design`. appkit-ui's stylesheet gives the canvas its theme even
+// if the app doesn't import it; the app's `index.css` (optional, an empty glob
+// is a no-op) brings the app's own theme and Tailwind build.
+const canvasModule = (builderOrigins: string[]) => `
 import { createElement } from "react";
 import { createRoot } from "react-dom/client";
+import "@databricks/appkit-ui/styles.css";
 import { DesignCanvas } from "@databricks/appkit-ui/react/beta";
 import.meta.glob("/src/index.css", { eager: true });
 const modules = import.meta.glob("/src/design/**/*.{tsx,jsx}", { eager: true });
-createRoot(document.getElementById("root")).render(createElement(DesignCanvas, { modules }));
-`;
-
-const PICKER_MODULE = `
-import { mountDesignPicker } from "@databricks/appkit-ui/react/beta";
-mountDesignPicker();
+createRoot(document.getElementById("root")).render(
+  createElement(DesignCanvas, { modules, builderOrigins: ${JSON.stringify(builderOrigins)} }),
+);
 `;
 
 const CANVAS_HTML = `<!doctype html>
@@ -35,33 +34,26 @@ const CANVAS_HTML = `<!doctype html>
 `;
 
 /**
- * Serves the `/design` canvas and injects the element picker into every HTML
- * page Vite transforms (the app and the canvas alike).
+ * Serves the `/design` canvas. The element picker lives only there; app pages
+ * are left untouched.
  *
  * @internal
  */
-export function designVitePlugin(): Plugin {
+export function designVitePlugin({
+  builderOrigins,
+}: {
+  builderOrigins: string[];
+}): Plugin {
   return {
     name: "appkit-design",
     apply: "serve",
 
     resolveId(id) {
-      if (id === CANVAS_ID || id === PICKER_ID) return `\0${id}`;
+      if (id === CANVAS_ID) return `\0${id}`;
     },
 
     load(id) {
-      if (id === `\0${CANVAS_ID}`) return CANVAS_MODULE;
-      if (id === `\0${PICKER_ID}`) return PICKER_MODULE;
-    },
-
-    transformIndexHtml() {
-      return [
-        {
-          tag: "script",
-          attrs: { type: "module", src: url(PICKER_ID) },
-          injectTo: "body",
-        },
-      ];
+      if (id === `\0${CANVAS_ID}`) return canvasModule(builderOrigins);
     },
 
     configureServer(server) {
diff --git a/template/README.md.tmpl b/template/README.md.tmpl
index 11994839b..fa39ee51d 100644
--- a/template/README.md.tmpl
+++ b/template/README.md.tmpl
@@ -16,7 +16,7 @@ A Databricks App powered by [AppKit](https://developers.databricks.com/docs/appk
 - **Genie** -- AI/BI Genie conversational interface for natural language data queries
 {{- end}}
 {{- if .plugins.design}}
-- **Design** -- Dev-only design canvas at `/design`: renders components from `client/src/design/`; click **Select** (on the canvas or any app page) to pick elements and send them to your coding agent via `.appkit/design-selection.json`
+- **Design** -- Dev-only design canvas at `/design`: renders components from `client/src/design/`; click **Select** there to pick elements and send them to your coding agent (saved to `.appkit/design-selection.json`, and posted to an embedding app builder when `builderOrigin` is set)
 {{- end}}
 - **Server** -- Express HTTP server with static file serving and Vite dev mode
 

From 9bdf7b96a8d6562960fd7845e8169dbbbace154a Mon Sep 17 00:00:00 2001
From: MarioCadenas <MarioCadenas@users.noreply.github.com>
Date: Wed, 21 Oct 2026 19:19:50 +0200
Subject: [PATCH 6/6] chore: acknowledge bundle size growth from the design
 canvas

The appkit-ui tarball grows ~23 KB (+5.9%) and react/beta ~6.4 KB gzip with
the dev-only design canvas and picker UI; refresh the baseline as earlier
feature PRs did.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
---
 bundle-size-baseline.json | 90 +++++++++++++++++++--------------------
 1 file changed, 45 insertions(+), 45 deletions(-)

diff --git a/bundle-size-baseline.json b/bundle-size-baseline.json
index dfbb5295c..64069ba0a 100644
--- a/bundle-size-baseline.json
+++ b/bundle-size-baseline.json
@@ -3,25 +3,25 @@
     {
       "name": "@databricks/appkit",
       "tarball": {
-        "packed": 1297373,
-        "unpacked": 4453717
+        "packed": 1307872,
+        "unpacked": 4486933
       },
       "dist": {
         "total": {
-          "raw": 4438327,
-          "gzip": 1520942
+          "raw": 4471543,
+          "gzip": 1534838
         },
         "js": {
-          "raw": 1320443,
-          "gzip": 468638
+          "raw": 1331429,
+          "gzip": 473518
         },
         "types": {
-          "raw": 474763,
-          "gzip": 172113
+          "raw": 477100,
+          "gzip": 173213
         },
         "maps": {
-          "raw": 2632326,
-          "gzip": 876373
+          "raw": 2652219,
+          "gzip": 884289
         },
         "css": {
           "raw": 0,
@@ -31,22 +31,22 @@
           "raw": 10795,
           "gzip": 3818
         },
-        "fileCount": 895
+        "fileCount": 905
       },
       "entries": [
         {
           "id": ".",
-          "gzip": 111090,
+          "gzip": 111208,
           "composition": {
-            "initialGzip": 108517,
+            "initialGzip": 108635,
             "lazyGzip": 2573,
-            "totalGzip": 111090,
-            "own": 351738,
+            "totalGzip": 111208,
+            "own": 352050,
             "nodeModules": null,
             "chunks": [
               {
                 "label": "index.js",
-                "gzip": 103847,
+                "gzip": 103965,
                 "kind": "initial"
               },
               {
@@ -64,17 +64,17 @@
         },
         {
           "id": "./beta",
-          "gzip": 105499,
+          "gzip": 108126,
           "composition": {
-            "initialGzip": 105014,
+            "initialGzip": 107641,
             "lazyGzip": 485,
-            "totalGzip": 105499,
-            "own": 316145,
+            "totalGzip": 108126,
+            "own": 323071,
             "nodeModules": null,
             "chunks": [
               {
                 "label": "beta.js",
-                "gzip": 84463,
+                "gzip": 87090,
                 "kind": "initial"
               },
               {
@@ -127,12 +127,12 @@
         },
         {
           "id": "./testing",
-          "gzip": 79051,
+          "gzip": 79171,
           "composition": {
-            "initialGzip": 45993,
-            "lazyGzip": 33058,
-            "totalGzip": 79051,
-            "own": 228781,
+            "initialGzip": 45994,
+            "lazyGzip": 33177,
+            "totalGzip": 79171,
+            "own": 229093,
             "nodeModules": null,
             "chunks": [
               {
@@ -142,7 +142,7 @@
               },
               {
                 "label": "index.js",
-                "gzip": 10286,
+                "gzip": 10287,
                 "kind": "initial"
               },
               {
@@ -152,7 +152,7 @@
               },
               {
                 "label": "index.js",
-                "gzip": 28625,
+                "gzip": 28744,
                 "kind": "lazy"
               },
               {
@@ -209,25 +209,25 @@
     {
       "name": "@databricks/appkit-ui",
       "tarball": {
-        "packed": 406741,
-        "unpacked": 1606513
+        "packed": 430550,
+        "unpacked": 1680523
       },
       "dist": {
         "total": {
-          "raw": 1602568,
-          "gzip": 546534
+          "raw": 1676578,
+          "gzip": 574683
         },
         "js": {
-          "raw": 439037,
-          "gzip": 150094
+          "raw": 463670,
+          "gzip": 159291
         },
         "types": {
-          "raw": 273603,
-          "gzip": 100719
+          "raw": 277992,
+          "gzip": 102934
         },
         "maps": {
-          "raw": 873530,
-          "gzip": 292465
+          "raw": 918518,
+          "gzip": 309202
         },
         "css": {
           "raw": 16398,
@@ -237,7 +237,7 @@
           "raw": 0,
           "gzip": 0
         },
-        "fileCount": 554
+        "fileCount": 570
       },
       "entries": [
         {
@@ -316,17 +316,17 @@
         },
         {
           "id": "./react/beta",
-          "gzip": 4994,
+          "gzip": 11530,
           "composition": {
-            "initialGzip": 4994,
+            "initialGzip": 21461,
             "lazyGzip": 0,
-            "totalGzip": 4994,
-            "own": 12631,
-            "nodeModules": 0,
+            "totalGzip": 21461,
+            "own": 31792,
+            "nodeModules": 30230,
             "chunks": [
               {
                 "label": "beta.js",
-                "gzip": 4994,
+                "gzip": 21461,
                 "kind": "initial"
               }
             ]