@agent-native/core 0.131.3 → 0.131.5

package/docs/content/docs-components.mdx

@@ -0,0 +1,491 @@
+---
+title: "Docs components"
+description: "Reference for every MDX component available in the Agent Native docs, with live rendered examples and copy-paste syntax."
+---
+
+# Docs components
+
+The docs site renders standard Markdown plus a set of MDX block components for
+richer content. Each section below shows a live rendered example followed by
+the exact MDX syntax that produced it.
+
+---
+
+## Callout
+
+<Callout tone="info">
+
+This is an `info` callout. Use it for background context or neutral notes. You can use **bold**, `inline code`, and [links](/docs/getting-started) inside.
+
+</Callout>
+
+<Callout tone="warning">
+
+This is a `warning` callout. Use it for potential data loss, breaking changes, or hard-to-reverse steps. For example: restart `pnpm dev` after adding a new route file — the router only picks up files present at startup.
+
+</Callout>
+
+<Callout tone="success">
+
+This is a `success` callout. Use it for the recommended path or to confirm a working approach.
+
+</Callout>
+
+<Callout tone="risk">
+
+This is a `risk` callout. Use it for security implications or production caveats.
+
+</Callout>
+
+<Callout tone="decision">
+
+This is a `decision` callout. Use it to surface a deliberate tradeoff the reader should understand.
+
+</Callout>
+
+```mdx
+<Callout tone="info">
+
+This is an `info` callout. Use it for background context or neutral notes. You can use **bold**, `inline code`, and [links](/docs/getting-started) inside.
+
+</Callout>
+
+<Callout tone="warning">
+
+This is a `warning` callout. Use it for potential data loss, breaking changes, or hard-to-reverse steps. For example: restart `pnpm dev` after adding a new route file — the router only picks up files present at startup.
+
+</Callout>
+
+<Callout tone="success">
+
+This is a `success` callout. Use it for the recommended path or to confirm a working approach.
+
+</Callout>
+
+<Callout tone="risk">
+
+This is a `risk` callout. Use it for security implications or production caveats.
+
+</Callout>
+
+<Callout tone="decision">
+
+This is a `decision` callout. Use it to surface a deliberate tradeoff the reader should understand.
+
+</Callout>
+```
+
+| Tone       | When to use                                                  |
+| ---------- | ------------------------------------------------------------ |
+| `info`     | Background context, neutral notes                            |
+| `warning`  | Potential data loss, breaking changes, hard-to-reverse steps |
+| `success`  | Recommended option, confirmed working path                   |
+| `risk`     | Security implications, production caveats                    |
+| `decision` | Deliberate tradeoffs the reader should understand            |
+
+Leave a blank line between the opening tag and the body, and another before the closing tag.
+
+---
+
+## Steps
+
+<Steps>
+
+### Install dependencies
+
+Run the following inside your project directory:
+
+```bash
+pnpm install
+```
+
+### Start the dev server
+
+```bash
+pnpm dev
+```
+
+Open `http://localhost:3000`. The app is ready when **VITE ready** appears in the terminal.
+
+### Sign in
+
+The first run shows a login screen. Use any credentials — local development does not send email.
+
+</Steps>
+
+````mdx
+<Steps>
+
+### Install dependencies
+
+Run the following inside your project directory:
+
+```bash
+pnpm install
+```
+
+### Start the dev server
+
+```bash
+pnpm dev
+```
+
+Open `http://localhost:3000`. The app is ready when **VITE ready** appears in the terminal.
+
+### Sign in
+
+The first run shows a login screen. Use any credentials — local development does not send email.
+
+</Steps>
+````
+
+Each step is a `###` heading followed by the body content. Steps work best for 3–8 items. For 2 items a numbered list is fine. For longer procedures, split into multiple `<Steps>` blocks with a prose bridge between them.
+
+---
+
+## Cards
+
+<Cards>
+
+### [Actions](/docs/actions)
+
+Typed operations callable from the agent, UI, CLI, and HTTP. Define once, call from anywhere.
+
+### [Database](/docs/database)
+
+SQL persistence with automatic migrations. SQLite locally, Postgres/Turso in production.
+
+### [Agent Surfaces](/docs/agent-surfaces)
+
+Configure where the agent appears: full-page chat, sidebar panel, or embedded in a route.
+
+### Skills
+
+Plain-text instruction files that give the agent domain knowledge and task-specific behavior without code changes.
+
+</Cards>
+
+```mdx
+<Cards>
+
+### [Actions](/docs/actions)
+
+Typed operations callable from the agent, UI, CLI, and HTTP. Define once, call from anywhere.
+
+### [Database](/docs/database)
+
+SQL persistence with automatic migrations. SQLite locally, Postgres/Turso in production.
+
+### [Agent Surfaces](/docs/agent-surfaces)
+
+Configure where the agent appears: full-page chat, sidebar panel, or embedded in a route.
+
+### Skills
+
+Plain-text instruction files that give the agent domain knowledge and task-specific behavior without code changes.
+
+</Cards>
+```
+
+Each card is a `###` heading (optionally linked) followed by the description. Cards without a link render as plain info boxes with no hover state or arrow.
+
+---
+
+## Comparison
+
+<Comparison>
+
+### Before
+
+Every feature needs a separate API endpoint, a separate React query, and manual wiring between the AI response and UI state.
+
+### After
+
+Define one action. The agent calls it as a tool, the UI calls it through a React hook, and both read the same validated output.
+
+</Comparison>
+
+```mdx
+<Comparison>
+
+### Before
+
+Every feature needs a separate API endpoint, a separate React query, and manual wiring between the AI response and UI state.
+
+### After
+
+Define one action. The agent calls it as a tool, the UI calls it through a React hook, and both read the same validated output.
+
+</Comparison>
+```
+
+Add more `###` sections to get 3 or 4 columns (max 4). The red/green label accent only applies to headings that exactly match `Before`, `Old`, `Without` (red) or `After`, `New`, `With` (green).
+
+---
+
+## kbd — keyboard shortcut
+
+Press [[⌘K]] to open the command palette. Save with [[Ctrl+S]] before running the dev server. Navigate fields with [[Tab]] and [[Shift+Tab]].
+
+```mdx
+Press [[⌘K]] to open the command palette. Save with [[Ctrl+S]] before running the dev server. Navigate fields with [[Tab]] and [[Shift+Tab]].
+```
+
+Double brackets around the key sequence; no MDX component needed. Works anywhere in regular Markdown paragraphs.
+
+---
+
+## Mermaid diagram
+
+```mermaid
+graph LR
+  A[defineAction] --> B[Agent calls it as a tool]
+  A --> C[UI calls it via useActionQuery]
+  A --> D[CLI calls it directly]
+  A --> E[HTTP API]
+```
+
+````mdx
+```mermaid
+graph LR
+  A[defineAction] --> B[Agent calls it as a tool]
+  A --> C[UI calls it via useActionQuery]
+  A --> D[CLI calls it directly]
+  A --> E[HTTP API]
+```
+````
+
+Use a fenced code block with the `mermaid` language tag. Mermaid supports flowcharts (`graph`), sequence diagrams (`sequenceDiagram`), entity-relationship diagrams (`erDiagram`), and more. See [mermaid.js.org](https://mermaid.js.org/intro/) for the full syntax reference.
+
+---
+
+## FileTree
+
+<FileTree
+  id="docs-components-filetree"
+  entries={[
+    {
+      path: "actions/analyze-text.ts",
+      change: "added",
+      note: "New action — callable from agent, UI, and CLI",
+    },
+    { path: "actions/list-text-analyses.ts", change: "added" },
+    { path: "app/routes/analyses.tsx", change: "modified" },
+    {
+      path: "app/config/nav.ts",
+      change: "modified",
+      note: "Add the new route to the sidebar nav",
+    },
+    { path: "db/migrations/001_analyses.sql" },
+  ]}
+/>
+
+```mdx
+<FileTree
+  id="docs-components-filetree"
+  entries={[
+    {
+      path: "actions/analyze-text.ts",
+      change: "added",
+      note: "New action — callable from agent, UI, and CLI",
+    },
+    { path: "actions/list-text-analyses.ts", change: "added" },
+    { path: "app/routes/analyses.tsx", change: "modified" },
+    {
+      path: "app/config/nav.ts",
+      change: "modified",
+      note: "Add the new route to the sidebar nav",
+    },
+    { path: "db/migrations/001_analyses.sql" },
+  ]}
+/>
+```
+
+FileTree is **self-closing** (`/>`). It does not accept Markdown children — if you use open/close tags with content inside you will get a parse error.
+
+Each entry in `entries` is an object with a `path` key (slash-delimited) and optional fields:
+
+| Field      | Values                                                  | Effect                               |
+| ---------- | ------------------------------------------------------- | ------------------------------------ |
+| `change`   | `"added"` \| `"modified"` \| `"removed"` \| `"renamed"` | Colored badge on the row             |
+| `note`     | any string                                              | Expandable annotation shown on hover |
+| `snippet`  | code string                                             | Expandable code preview              |
+| `language` | e.g. `"ts"`                                             | Syntax highlighting for the snippet  |
+
+---
+
+## Tabs
+
+<TabsBlock
+  id="docs-components-tabs"
+  tabs={[
+    {
+      id: "pnpm",
+      label: "pnpm",
+      blocks: [
+        {
+          type: "code",
+          id: "pnpm-install",
+          data: { code: "pnpm install", language: "bash" },
+        },
+      ],
+    },
+    {
+      id: "npm",
+      label: "npm",
+      blocks: [
+        {
+          type: "code",
+          id: "npm-install",
+          data: { code: "npm install", language: "bash" },
+        },
+      ],
+    },
+    {
+      id: "yarn",
+      label: "yarn",
+      blocks: [
+        {
+          type: "code",
+          id: "yarn-install",
+          data: { code: "yarn install", language: "bash" },
+        },
+      ],
+    },
+  ]}
+/>
+
+```mdx
+<TabsBlock
+  id="docs-components-tabs"
+  tabs={[
+    {
+      id: "pnpm",
+      label: "pnpm",
+      blocks: [
+        {
+          type: "code",
+          id: "pnpm-install",
+          data: { code: "pnpm install", language: "bash" },
+        },
+      ],
+    },
+    {
+      id: "npm",
+      label: "npm",
+      blocks: [
+        {
+          type: "code",
+          id: "npm-install",
+          data: { code: "npm install", language: "bash" },
+        },
+      ],
+    },
+    {
+      id: "yarn",
+      label: "yarn",
+      blocks: [
+        {
+          type: "code",
+          id: "yarn-install",
+          data: { code: "yarn install", language: "bash" },
+        },
+      ],
+    },
+  ]}
+/>
+```
+
+`TabsBlock` is self-closing. The entire structure is one JSON `tabs` attribute. Each tab's content is a `blocks` array where each item is a block object with `type`, `id`, and `data` matching that block's schema. Tabs works best for short parallel code snippets (one code block per tab). For richer multi-block content per tab, use a visual editor rather than hand-authoring the JSON.
+
+---
+
+## Columns
+
+<Columns
+  id="docs-components-columns"
+  columns={[
+    {
+      id: "col-manual",
+      label: "Manual approach",
+      blocks: [
+        {
+          type: "code",
+          id: "manual-code",
+          data: {
+            code: "const res = await fetch('/api/analyses')\nconst data = await res.json()",
+            language: "ts",
+          },
+        },
+      ],
+    },
+    {
+      id: "col-actions",
+      label: "With actions",
+      blocks: [
+        {
+          type: "code",
+          id: "action-code",
+          data: {
+            code: "const { data } = useActionQuery('list-text-analyses', {})",
+            language: "ts",
+          },
+        },
+      ],
+    },
+  ]}
+/>
+
+```mdx
+<Columns
+  id="docs-components-columns"
+  columns={[
+    {
+      id: "col-manual",
+      label: "Manual approach",
+      blocks: [
+        {
+          type: "code",
+          id: "manual-code",
+          data: {
+            code: "const res = await fetch('/api/analyses')\nconst data = await res.json()",
+            language: "ts",
+          },
+        },
+      ],
+    },
+    {
+      id: "col-actions",
+      label: "With actions",
+      blocks: [
+        {
+          type: "code",
+          id: "action-code",
+          data: {
+            code: "const { data } = useActionQuery('list-text-analyses', {})",
+            language: "ts",
+          },
+        },
+      ],
+    },
+  ]}
+/>
+```
+
+Like `TabsBlock`, `Columns` is self-closing with a single JSON `columns` attribute. Each column has an optional `label` header and a `blocks` array. For comparing prose rather than code, `Comparison` is easier to hand-author.
+
+---
+
+## When to use which component
+
+| Situation                                 | Component                            |
+| ----------------------------------------- | ------------------------------------ |
+| Reader must not miss something            | `Callout` (warning / info / success) |
+| Sequential procedure with titled steps    | `Steps`                              |
+| Navigation or feature overview grid       | `Cards`                              |
+| Before vs. after, old vs. new (prose)     | `Comparison`                         |
+| Same task in multiple tools or frameworks | `Tabs`                               |
+| Side-by-side code (labeled columns)       | `Columns`                            |
+| Project directory structure               | `FileTree`                           |
+| Inline keyboard shortcut                  | `[[Key]]`                            |
+| Architecture or flow diagram              | Mermaid fence                        |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.131.3",
+  "version": "0.131.5",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/src/client/AgentPanel.tsx

@@ -2585,47 +2585,71 @@ class AgentPanelErrorBoundary extends React.Component<
       assistantUiRecoverableRenderErrorKind(this.state.error) &&
       this.state.staleIndexRecoveryCount < 2
     ) {
-      return (
-        <div className="flex h-full items-center justify-center p-6 text-center text-xs text-muted-foreground">
-          Reloading chat UI...
-        </div>
-      );
+      return <AgentPanelReloadingNotice />;
     }
 
     return (
-      <div className="flex h-full flex-col items-center justify-center gap-3 p-6 text-center">
-        <div className="max-w-[260px] space-y-1">
-          <p className="text-sm font-medium text-foreground">
-            Agent panel hit an internal UI error.
-          </p>
-          <p className="text-xs leading-relaxed text-muted-foreground">
-            The app is still usable. Reset the panel to reload the chat UI.
-          </p>
-        </div>
-        <button
-          type="button"
-          className="rounded-md border border-border bg-background px-3 py-1.5 text-xs font-medium text-foreground hover:bg-accent"
-          onClick={() => {
-            this.setState({ error: null, staleIndexRecoveryCount: 0 });
-            this.props.onReset();
-          }}
-        >
-          Reset agent panel
-        </button>
-        <ErrorReportActions
-          appName="Agent panel"
-          title="Agent panel UI error"
-          details={this.state.error.message}
-          issueTitle="Agent panel UI error"
-          className="max-w-[260px]"
-          feedbackClassName="h-7"
-          githubClassName="h-7"
-        />
-      </div>
+      <AgentPanelErrorFallback
+        details={this.state.error.message}
+        onReset={() => {
+          this.setState({ error: null, staleIndexRecoveryCount: 0 });
+          this.props.onReset();
+        }}
+      />
     );
   }
 }
 
+// The boundary must stay a class (componentDidCatch), but its copy still has to
+// come from the catalog like every other string in this file — so the fallback
+// UI lives in function components that can call useT.
+function AgentPanelReloadingNotice() {
+  const t = useT();
+  return (
+    <div className="flex h-full items-center justify-center p-6 text-center text-xs text-muted-foreground">
+      {t("agentPanel.uiError.reloading")}
+    </div>
+  );
+}
+
+function AgentPanelErrorFallback({
+  details,
+  onReset,
+}: {
+  details: string;
+  onReset: () => void;
+}) {
+  const t = useT();
+  return (
+    <div className="flex h-full flex-col items-center justify-center gap-3 p-6 text-center">
+      <div className="max-w-[260px] space-y-1">
+        <p className="text-sm font-medium text-foreground">
+          {t("agentPanel.uiError.title")}
+        </p>
+        <p className="text-xs leading-relaxed text-muted-foreground">
+          {t("agentPanel.uiError.description")}
+        </p>
+      </div>
+      <button
+        type="button"
+        className="rounded-md border border-border bg-background px-3 py-1.5 text-xs font-medium text-foreground hover:bg-accent"
+        onClick={onReset}
+      >
+        {t("agentPanel.uiError.reset")}
+      </button>
+      <ErrorReportActions
+        appName="Agent panel"
+        title={t("agentPanel.uiError.title")}
+        details={details}
+        issueTitle="Agent panel UI error"
+        className="max-w-[260px]"
+        feedbackClassName="h-7"
+        githubClassName="h-7"
+      />
+    </div>
+  );
+}
+
 export function AgentPanel(props: AgentPanelProps) {
   const [resetKey, setResetKey] = useState(0);
   const resetPanel = useCallback(() => {

package/src/localization/default-messages.ts

@@ -336,6 +336,12 @@ const messages = {
     },
   },
   agentPanel: {
+    uiError: {
+      title: "Agent panel hit a glitch",
+      description: "The app's still usable. Reset to reload the chat.",
+      reset: "Reset agent panel",
+      reloading: "Reloading chat…",
+    },
     useBuilder: "Use Builder",
     openDesktopToEditCode: "Open Desktop to edit code",
     codeUnavailableDescription: