@tailor-platform/app-shell 1.19.0 → 1.20.0

package/skills/app-shell-patterns/references/api/router/use-params.md

@@ -182,7 +182,7 @@ function ProductEdit() {
 
   return (
     <form>
-      <h1>Edit Product {id}</h1>
+      <Text.h1>Edit Product {id}</Text.h1>
       {/* form fields */}
     </form>
   );
@@ -203,7 +203,7 @@ function DeleteConfirmation() {
 
   return (
     <div>
-      <p>Delete product {id}?</p>
+      <Text.p>Delete product {id}?</Text.p>
       <button onClick={handleDelete}>Confirm</button>
     </div>
   );

package/skills/app-shell-patterns/references/api/use-ai-chat.md

@@ -1,19 +1,24 @@
 ---
 title: useAIChat
-description: Simple text-only chat hook for AI Gateway
+description: AI Gateway chat hook with optional local tools
 ---
 
 <!-- GENERATED by docs-kit from docs-src/hooks/use-ai-chat.docs.outline.md — do not edit by hand. -->
 
 # useAIChat
 
-React hook for simple text-only chat on top of `createAIGatewayClient`.
+React hook for AI Gateway chat on top of `createAIGatewayClient`, with optional local tool support.
 
 ## Signature
 
 ```typescript
-const useAIChat: (config: { client: AIGatewayClient; model: string }) => {
+const useAIChat: (config: {
+  client: AIGatewayClient;
+  model: string;
+  tools?: Record<string, AILocalTool>;
+}) => {
   messages: AIChatMessage[];
+  toolCalls: { id: string; name: string }[];
   status: "ready" | "submitted" | "streaming" | "error";
   error?: Error;
   sendMessage: (message: string) => Promise<boolean>;
@@ -33,10 +38,17 @@ interface AIChatMessage {
 }
 ```
 
+### `toolCalls`
+
+- **Type:** `{ id: string; name: string }[]`
+- **Description:** Tool calls requested by the model in the active flow, including earlier tool rounds of the current request. This transient list is cleared when the response finishes, is stopped, or fails; it is never added to `messages` or conversation history.
+
+Calls become available before local tool execution. They record requested tool names, not successful execution. Arguments and results remain internal.
+
 ### `status`
 
 - **Type:** `"ready" | "submitted" | "streaming" | "error"`
-- **Description:** Current request state
+- **Description:** Current request state. `submitted` covers waiting for the first text, local tool execution, and waiting for the model's next reply after a tool result. `streaming` begins when text arrives. `AIChat.Conversation` automatically shows a waiting indicator while `submitted`.
 
 ### `error`
 
@@ -54,10 +66,20 @@ interface AIChatMessage {
 - **Type:** `() => void`
 - **Description:** Aborts the current request if one is in progress
 
+### `tools`
+
+Register local tools under a single object using `defineAIChatTool(...)`. Their schemas must implement both [Standard Schema](https://standardschema.dev/) validation and Standard JSON Schema generation (for example, Zod 4). Provider-native tools are not supported.
+
 ## Usage
 
 ```tsx
-import { createAuthClient, createAIGatewayClient, useAIChat } from "@tailor-platform/app-shell";
+import {
+  createAuthClient,
+  createAIGatewayClient,
+  defineAIChatTool,
+  useAIChat,
+} from "@tailor-platform/app-shell";
+import { z } from "zod/v4";
 
 const authClient = createAuthClient({
   clientId: "your-client-id",
@@ -69,10 +91,23 @@ const aiClient = createAIGatewayClient({
   authClient,
 });
 
+const lookupCustomer = defineAIChatTool({
+  description: "Look up a customer in the current workspace",
+  schema: z.object({
+    customerId: z.string(),
+  }),
+  async execute({ customerId }) {
+    return { customerId, name: "Acme Corp" };
+  },
+});
+
 export function ChatScreen() {
-  const { messages, sendMessage, status, stop, error } = useAIChat({
+  const { messages, toolCalls, sendMessage, status, stop, error } = useAIChat({
     client: aiClient,
     model: "gpt-5-mini",
+    tools: {
+      lookupCustomer,
+    },
   });
 
   return (
@@ -82,6 +117,9 @@ export function ChatScreen() {
           {message.role}: {message.content}
         </div>
       ))}
+      {toolCalls.map((call) => (
+        <div key={call.id}>Tool call: {call.name}</div>
+      ))}
 
       <button
         onClick={() => void sendMessage("Hello")}
@@ -101,9 +139,9 @@ export function ChatScreen() {
 ## Notes
 
 - AppShell chooses the appropriate AI Gateway transport automatically
-- The hook is intentionally text-only
+- Public messages stay user/assistant text-first; tool calls and results never become conversation messages
 - System prompts and custom history shaping should use the low-level client directly
-- `stop()` keeps any already-streamed assistant text and ignores late chunks from the stopped request
+- `stop()` keeps already-streamed assistant text, clears the active `toolCalls`, and ignores late events from the stopped request
 
 ## Related
 

package/skills/app-shell-patterns/references/api/use-app-shell-config.md

@@ -56,15 +56,15 @@ const useAppShellConfig: () => {
 ### Display App Info
 
 ```typescript
-import { useAppShellConfig } from "@tailor-platform/app-shell";
+import { Text, useAppShellConfig } from "@tailor-platform/app-shell";
 
 function AppInfo() {
   const { title, configurations } = useAppShellConfig();
 
   return (
     <div>
-      <h2>{title}</h2>
-      <p>Base: {configurations.basePath}</p>
+      <Text.h2>{title}</Text.h2>
+      <Text.p>Base: {configurations.basePath}</Text.p>
     </div>
   );
 }
@@ -96,7 +96,7 @@ function SettingsMenu() {
 
   return (
     <div>
-      <h3>Settings</h3>
+      <Text.h3>Settings</Text.h3>
       {configurations.settingsResources.map((resource) => (
         <button key={resource.path}>{resource.path}</button>
       ))}

package/skills/app-shell-patterns/references/api/use-app-shell-data.md

@@ -28,15 +28,15 @@ const useAppShellData: () => {
 ### Basic Access
 
 ```typescript
-import { useAppShellData } from "@tailor-platform/app-shell";
+import { Text, useAppShellData } from "@tailor-platform/app-shell";
 
 function UserProfile() {
   const { contextData } = useAppShellData();
 
   return (
     <div>
-      <p>Welcome, {contextData.currentUser?.name}</p>
-      <p>Role: {contextData.currentUser?.role}</p>
+      <Text.p>Welcome, {contextData.currentUser?.name}</Text.p>
+      <Text.p>Role: {contextData.currentUser?.role}</Text.p>
     </div>
   );
 }
@@ -54,8 +54,8 @@ function UserInfo() {
 
   return (
     <div>
-      <h2>{contextData.currentUser.name}</h2>
-      <p>{contextData.currentUser.email}</p>
+      <Text.h2>{contextData.currentUser.name}</Text.h2>
+      <Text.p>{contextData.currentUser.email}</Text.p>
     </div>
   );
 }

package/skills/app-shell-patterns/references/api/use-app-shell.md

@@ -120,8 +120,8 @@ function UserInfo() {
 
   return (
     <div>
-      <h2>{contextData.currentUser.name}</h2>
-      <p>{contextData.currentUser.email}</p>
+      <Text.h2>{contextData.currentUser.name}</Text.h2>
+      <Text.p>{contextData.currentUser.email}</Text.p>
     </div>
   );
 }

package/skills/app-shell-patterns/references/api/use-auth.md

@@ -59,7 +59,7 @@ const useAuth: () => {
 ### Basic Authentication Flow
 
 ```typescript
-import { useAuth } from "@tailor-platform/app-shell";
+import { Text, useAuth } from "@tailor-platform/app-shell";
 
 function MyComponent() {
   const { isAuthenticated, isReady, login, logout } = useAuth();
@@ -74,7 +74,7 @@ function MyComponent() {
 
   return (
     <div>
-      <p>You are logged in!</p>
+      <Text.p>You are logged in!</Text.p>
       <button onClick={logout}>Log Out</button>
     </div>
   );
@@ -108,7 +108,7 @@ function AuthStatus() {
   if (error) {
     return (
       <div>
-        <p>Authentication failed: {error}</p>
+        <Text.p>Authentication failed: {error}</Text.p>
         <button onClick={login}>Retry</button>
       </div>
     );

package/skills/app-shell-patterns/references/api/use-route-error.md

@@ -26,7 +26,7 @@ const useRouteError: () => unknown;
 ### Basic Error Boundary
 
 ```typescript
-import { useRouteError } from "@tailor-platform/app-shell";
+import { Text, useRouteError } from "@tailor-platform/app-shell";
 
 function ErrorBoundary() {
   const error = useRouteError();
@@ -37,8 +37,8 @@ function ErrorBoundary() {
 
   return (
     <div>
-      <h1>Something went wrong</h1>
-      <p>{message}</p>
+      <Text.h1>Something went wrong</Text.h1>
+      <Text.p>{message}</Text.p>
       <button onClick={() => window.location.reload()}>
         Try Again
       </button>
@@ -79,7 +79,7 @@ const productsModule = defineModule({
 ### Advanced Error Handling
 
 ```typescript
-import { isRouteErrorResponse, useRouteError } from "@tailor-platform/app-shell";
+import { isRouteErrorResponse, Text, useRouteError } from "@tailor-platform/app-shell";
 
 function ErrorBoundary() {
   const error = useRouteError();
@@ -88,8 +88,8 @@ function ErrorBoundary() {
   if (isRouteErrorResponse(error)) {
     return (
       <div>
-        <h1>{error.status} {error.statusText}</h1>
-        <p>{error.data}</p>
+        <Text.h1>{error.status} {error.statusText}</Text.h1>
+        <Text.p>{error.data}</Text.p>
       </div>
     );
   }
@@ -98,8 +98,8 @@ function ErrorBoundary() {
   if (error instanceof Error) {
     return (
       <div>
-        <h1>Error</h1>
-        <p>{error.message}</p>
+        <Text.h1>Error</Text.h1>
+        <Text.p>{error.message}</Text.p>
         <pre>{error.stack}</pre>
       </div>
     );
@@ -108,8 +108,8 @@ function ErrorBoundary() {
   // Handle unknown errors
   return (
     <div>
-      <h1>Unknown Error</h1>
-      <p>Something went wrong</p>
+      <Text.h1>Unknown Error</Text.h1>
+      <Text.p>Something went wrong</Text.p>
     </div>
   );
 }
@@ -129,8 +129,8 @@ function ErrorBoundary() {
 
   return (
     <div>
-      <h1>Error</h1>
-      <p>We've been notified and will fix this soon.</p>
+      <Text.h1>Error</Text.h1>
+      <Text.p>We've been notified and will fix this soon.</Text.p>
     </div>
   );
 }

package/skills/app-shell-patterns/references/components/action-panel.md

@@ -94,8 +94,10 @@ function CustomEmptyContent() {
       actions={[]}
       emptyContent={
         <div>
-          <p>利用可能な操作はありません</p>
-          <p>ステータスが変わると、操作が表示されます。</p>
+          <Text.p className="text-muted-foreground">利用可能な操作はありません</Text.p>
+          <Text.p className="text-muted-foreground">
+            ステータスが変わると、操作が表示されます。
+          </Text.p>
         </div>
       }
     />

package/skills/app-shell-patterns/references/components/activity-card.md

@@ -105,7 +105,7 @@ import { ActivityCard, type ActivityCardBaseItem } from "@tailor-platform/app-sh
 ### Example
 
 ```tsx
-import { ActivityCard, type ActivityCardBaseItem } from "@tailor-platform/app-shell";
+import { ActivityCard, Text, type ActivityCardBaseItem } from "@tailor-platform/app-shell";
 
 interface MyItem extends ActivityCardBaseItem {
   kind: "approval" | "update";
@@ -123,11 +123,11 @@ const items: MyItem[] = [
     {(item) =>
       item.kind === "approval" ? (
         <ActivityCard.Item indicator={<ApprovedIcon />}>
-          <p>{item.label}</p>
+          <Text.p>{item.label}</Text.p>
         </ActivityCard.Item>
       ) : (
         <ActivityCard.Item>
-          <p>{item.message}</p>
+          <Text.p>{item.message}</Text.p>
         </ActivityCard.Item>
       )
     }

package/skills/app-shell-patterns/references/components/ai-chat.md

@@ -84,6 +84,17 @@ Other props spread onto the root `<div>`.
 
 Other props spread onto the region's outer `<div>`.
 
+While the root's `status` is `"submitted"`, the conversation automatically appends a [`Spinner`](./spinner.md) and localized “Thinking…” status at the end. This covers the initial reply wait, tool execution, and the next reply wait after a tool result. The indicator disappears when text starts streaming, or when the request finishes, fails, or is stopped. It participates in the conversation's normal auto-scroll behavior; no separate loader state is needed.
+
+### `AIChat.ToolCall`
+
+A compact label for one model-requested tool call. Each label occupies its own row, so multiple calls stack vertically. It does not imply execution success, render tool arguments/results, or manage history.
+
+| Prop        | Type                           | Default  | Description                                      |
+| ----------- | ------------------------------ | -------- | ------------------------------------------------ |
+| `call`      | `{ id: string; name: string }` | required | A `toolCalls` element returned by `useAIChat()`. |
+| `className` | `string`                       | -        | Merged onto the outer row, not the badge.        |
+
 ### `AIChat.Composer`
 
 | Prop            | Type                        | Default  | Description                                                                      |
@@ -112,17 +123,18 @@ Most props stay inside their region. These `AIChat.Composer` props land on **ano
 
 `onValueChange` is wrapped rather than forwarded — it is called from the `Textarea`'s `onChange`, and again with `""` after a submit. `defaultValue` seeds the composer's own state and is never forwarded. Nothing on `AIChat`, `AIChat.Header`, or `AIChat.Conversation` reaches another AppShell component.
 
-Three attached parts wrap an AppShell component. They expose only the props the part's job needs rather than inheriting the wrapped component's surface, so its visual treatment is fixed and not yours to change:
+Four attached parts wrap an AppShell component. They expose only the props the part's job needs rather than inheriting the wrapped component's surface, so its visual treatment is fixed and not yours to change:
 
 | Part                                | Wraps                                                      | Accepts                                                       | Fixed                              |
 | ----------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------- |
 | `AIChat.Suggestion`                 | [`Button`](./button.md)                                    | `suggestion`, `onSelect`, `className`, `disabled`, `children` | `variant="secondary"`, `size="sm"` |
 | `AIChat.Action`                     | [`Button`](./button.md) inside a [`Tooltip`](./tooltip.md) | `label`, `onClick`, `className`, `disabled`, `children`       | `variant="ghost"`, `size="icon"`   |
 | `AIChat.ChainOfThoughtSearchResult` | [`Badge`](./badge.md)                                      | `className`, `children`, `variant`                            | —                                  |
+| `AIChat.ToolCall`                   | [`Badge`](./badge.md)                                      | `call`, `className`                                           | `variant="neutral"`                |
 
 `variant` stays open on `ChainOfThoughtSearchResult` because conveying status is what a `Badge` is for. `AIChat.Action`'s `label` becomes both the accessible name and the tooltip text.
 
-One thing to know about `className` on these: it is merged with `cn()`, which is not configured for AppShell's internal prefix, so it cannot reliably override a base utility from the wrapped component. Add properties the component doesn't set, and reach for the wrapped component's own props or variants to change ones it does — see [Styling AppShell components](../concepts/styling-theming.md#styling-appshell-components).
+`ToolCall` applies `className` to its outer row, not the inner badge. For `Suggestion`, `Action`, and `ChainOfThoughtSearchResult`, `className` is merged with `cn()`, which is not configured for AppShell's internal prefix, so it cannot reliably override a base utility from the wrapped component. Add properties the component doesn't set, and reach for the wrapped component's own props or variants to change ones it does — see [Styling AppShell components](../concepts/styling-theming.md#styling-appshell-components).
 
 ## Filling the page
 
@@ -261,6 +273,28 @@ Structured step timeline for agentic turns — the discrete plan being executed,
 
 `status` is `"complete" | "active" | "pending"`.
 
+### Tool calls during the active flow
+
+`useAIChat()` returns a transient `toolCalls` list separately from `messages`. Render it with `AIChat.ToolCall` after the message history inside `AIChat.Conversation`:
+
+```tsx
+{
+  toolCalls.length > 0 ? (
+    <AIChat.Message from="assistant">
+      {toolCalls.map((call) => (
+        <AIChat.ToolCall key={call.id} call={call} />
+      ))}
+    </AIChat.Message>
+  ) : null;
+}
+```
+
+Each call renders on its own row, in the order supplied. Labels are localized automatically.
+
+The list clears when the response finishes, is stopped, or fails. It does not create tool messages or persist in the conversation log.
+
+These names record model requests, not execution success. Tool arguments and results stay internal. Do not infer a `ToolHeader` success or running state from name-only metadata.
+
 ### Tool
 
 Collapsible tool-call card. Maps 1:1 to the AI SDK's tool-part lifecycle, so a streaming loop can update a call in place as parts arrive.
@@ -279,7 +313,7 @@ Collapsible tool-call card. Maps 1:1 to the AI SDK's tool-part lifecycle, so a s
 
 ### Sources
 
-Compact "Used N sources" citation trigger under a grounded answer.
+Compact "Used N sources" citation trigger under a grounded answer. Supply source data from your application; `useAIChat()` does not return citation metadata.
 
 ```tsx
 <AIChat.Sources>

package/skills/app-shell-patterns/references/components/app-shell.md

@@ -232,14 +232,14 @@ Access the configured timezone in components using [`useTimeZone`](../api/use-ti
 - **Description:** Global error boundary component applied to all routes
 
 ```tsx
-import { useRouteError } from "@tailor-platform/app-shell";
+import { Text, useRouteError } from "@tailor-platform/app-shell";
 
 const GlobalErrorBoundary = () => {
   const error = useRouteError() as Error;
   return (
     <div className="p-8">
-      <h1 className="text-xl font-bold mb-4">Something went wrong</h1>
-      <p className="text-red-600">{error.message}</p>
+      <Text.h1 className="mb-4">Something went wrong</Text.h1>
+      <Text.p className="text-danger-text">{error.message}</Text.p>
     </div>
   );
 };
@@ -432,6 +432,7 @@ import {
   SidebarLayout,
   defineModule,
   defineResource,
+  Text,
   useRouteError,
 } from "@tailor-platform/app-shell";
 import { Building } from "lucide-react";
@@ -450,8 +451,8 @@ const ErrorBoundary = () => {
   const error = useRouteError() as Error;
   return (
     <div className="p-8">
-      <h1 className="text-xl font-bold">Error</h1>
-      <p>{error.message}</p>
+      <Text.h1>Error</Text.h1>
+      <Text.p>{error.message}</Text.p>
     </div>
   );
 };

package/skills/app-shell-patterns/references/components/card.md

@@ -25,7 +25,7 @@ function BasicUsage() {
     <Card.Root>
       <Card.Header title="Order Details" description="Summary of order #1234" />
       <Card.Content>
-        <p>Content goes here</p>
+        <Text.p>Content goes here</Text.p>
       </Card.Content>
     </Card.Root>
   );
@@ -154,7 +154,7 @@ For a scrollable list, put the overflow on `Card.Content`. Rows supply their own
 ```tsx
 <Card.Root>
   <Card.Content>
-    <p>No header needed for this card.</p>
+    <Text.p>No header needed for this card.</Text.p>
   </Card.Content>
 </Card.Root>
 ```