ai-design-system 0.1.74 → 0.1.77

package/components/ai-elements/ExpoAppPreview/ExpoAppPreview.tsx

@@ -0,0 +1,112 @@
+import * as React from "react"
+import { cn } from "@/lib/utils"
+import type { ExpoAppPreviewProps } from "./interfaces"
+
+/**
+ * ExpoAppPreview Block
+ *
+ * A generic, full-bleed sandboxed iframe container for rendering an Expo /
+ * React Native app compiled to web. It is intentionally unopinionated about
+ * where the app is served from: `src` may point at a Metro dev server (live
+ * reload during development) or a static export (published app).
+ *
+ * ## Security model
+ * The default sandbox retains same-origin (`allow-same-origin`) per the
+ * waypoint preview contract. As documented on the props, `allow-scripts`
+ * combined with `allow-same-origin` is not a security boundary against the
+ * embedded app; pass a sandbox without `allow-same-origin` for untrusted
+ * content.
+ *
+ * ## Host <-> app messaging
+ * `onMessage` forwards `message` events whose `event.source` is this iframe's
+ * window. It is an optional passthrough of a browser primitive — standalone
+ * previews render without it.
+ */
+export const ExpoAppPreview = React.memo<ExpoAppPreviewProps>(
+  ({
+    src,
+    title = "App preview",
+    sandbox = "allow-scripts allow-same-origin allow-forms allow-popups",
+    allow,
+    loading = false,
+    loadingLabel = "Loading app…",
+    isEmpty = false,
+    emptyLabel = "No preview available",
+    error = null,
+    errorLabel = "Preview unavailable",
+    onLoad,
+    onError,
+    onMessage,
+    registerIframe,
+    className,
+    iframeClassName,
+    ...props
+  }) => {
+    const iframeRef = React.useRef<HTMLIFrameElement>(null)
+    const onMessageRef = React.useRef(onMessage)
+    onMessageRef.current = onMessage
+
+    React.useEffect(() => {
+      if (!registerIframe) return undefined
+      registerIframe(iframeRef.current)
+      return () => registerIframe(null)
+    }, [registerIframe])
+
+    React.useEffect(() => {
+      if (!onMessageRef.current) return undefined
+      const handler = (event: MessageEvent): void => {
+        if (event.source !== iframeRef.current?.contentWindow) return
+        onMessageRef.current?.(event)
+      }
+      window.addEventListener("message", handler)
+      return () => window.removeEventListener("message", handler)
+    }, [])
+
+    return (
+      <div
+        className={cn(
+          "relative h-full w-full min-h-0 overflow-hidden bg-background",
+          className,
+        )}
+        {...props}
+      >
+        <iframe
+          ref={iframeRef}
+          src={src}
+          title={title}
+          sandbox={sandbox}
+          allow={allow}
+          onLoad={onLoad}
+          onError={onError}
+          className={cn("h-full w-full border-0", iframeClassName)}
+        />
+
+        {loading && (
+          <div className="absolute inset-0 flex flex-col items-center justify-center gap-3 bg-background/80">
+            <div
+              className="h-8 w-8 animate-spin rounded-full border-2 border-primary/30 border-t-primary"
+              role="status"
+              aria-label={loadingLabel}
+            />
+            <span className="text-sm text-muted-foreground">{loadingLabel}</span>
+          </div>
+        )}
+
+        {!loading && isEmpty && (
+          <div className="absolute inset-0 flex flex-col items-center justify-center gap-1 bg-background/80">
+            <span className="text-sm font-medium text-foreground">{emptyLabel}</span>
+          </div>
+        )}
+
+        {!loading && !isEmpty && error && (
+          <div className="absolute inset-0 flex flex-col items-center justify-center gap-1 bg-background/80">
+            <span className="text-sm font-medium text-destructive">{errorLabel}</span>
+            <span className="max-w-md text-center text-sm text-muted-foreground">{error}</span>
+          </div>
+        )}
+      </div>
+    )
+  },
+)
+
+ExpoAppPreview.displayName = "ExpoAppPreview"

package/components/ai-elements/ExpoAppPreview/index.ts

@@ -0,0 +1,2 @@
+export { ExpoAppPreview } from "./ExpoAppPreview"
+export type { ExpoAppPreviewProps } from "./interfaces"

package/components/ai-elements/ExpoAppPreview/interfaces.ts

@@ -0,0 +1,58 @@
+import type * as React from "react"
+
+/**
+ * Props for the ExpoAppPreview Block.
+ *
+ * A generic, dependency-free container that renders a full-bleed sandboxed
+ * iframe pointing at an Expo/React Native app compiled to web (dev server or
+ * static export). It owns no knowledge of how the `src` is produced or served —
+ * consumers (e.g. waypoint) compute the URL and pass it in.
+ */
+export interface ExpoAppPreviewProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Absolute or same-origin URL of the app to render in the iframe. */
+  src: string
+  /** Accessible name for the iframe (default: "App preview"). */
+  title?: string
+  /**
+   * iframe `sandbox` attribute. Defaults to ADR-033's contract:
+   * `allow-scripts allow-same-origin allow-forms allow-popups`.
+   *
+   * Security note: `allow-scripts` combined with `allow-same-origin` lets the
+   * embedded app remove its own sandbox restrictions, so this is an isolation
+   * boundary for reliable rendering, not a security boundary against the
+   * embedded app. Omit `allow-same-origin` when the embedded app is untrusted.
+   */
+  sandbox?: string
+  /** iframe `allow` attribute (e.g. feature policy overrides). Optional. */
+  allow?: string
+  /** Show a loading overlay (spinner + label) while true. */
+  loading?: boolean
+  /** Label shown with the spinner while loading. */
+  loadingLabel?: string
+  /** Show an empty-state overlay when true (e.g. no build deployed yet). */
+  isEmpty?: boolean
+  /** Label shown in the empty state. */
+  emptyLabel?: string
+  /** When truthy, show an error overlay with this message. */
+  error?: string | null
+  /** Label shown above the error message. */
+  errorLabel?: string
+  /** Fired when the iframe finishes loading. */
+  onLoad?: () => void
+  /** Fired when the iframe errors. */
+  onError?: () => void
+  /**
+   * Receives the iframe element once mounted (and `null` on unmount).
+   * Lets consumers capture a screenshot (e.g. html-to-image) without the
+   * block owning capture tooling.
+   */
+  registerIframe?: (el: HTMLIFrameElement | null) => void
+  /**
+   * Receives host-side `message` events originating from the iframe window
+   * (browser postMessage primitive; optional passthrough — not required for
+   * standalone rendering).
+   */
+  onMessage?: (event: MessageEvent) => void
+  /** Extra classes for the iframe element. */
+  iframeClassName?: string
+}

package/components/ai-elements/checkpoint.tsx

@@ -0,0 +1,86 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import { Separator } from "@/components/ui/separator";
+import { cn } from "@/lib/utils";
+import { BookmarkIcon } from "lucide-react";
+import type { ComponentProps, HTMLAttributes } from "react";
+
+// ── Checkpoint ────────────────────────────────────────────────────────────────
+// Root container: renders [icon] [trigger] [Separator] in a flex row.
+// The Separator stretches to fill remaining width automatically.
+
+export type CheckpointProps = HTMLAttributes<HTMLDivElement>;
+
+export const Checkpoint = ({
+  className,
+  children,
+  ...props
+}: CheckpointProps) => (
+  <div
+    className={cn(
+      "flex items-center gap-0.5 overflow-hidden text-muted-foreground",
+      className
+    )}
+    {...props}
+  >
+    {children}
+    <Separator className="flex-1" />
+  </div>
+);
+
+// ── CheckpointIcon ────────────────────────────────────────────────────────────
+// Defaults to BookmarkIcon. Pass children to use a custom icon.
+
+export type CheckpointIconProps = ComponentProps<typeof BookmarkIcon>;
+
+export const CheckpointIcon = ({
+  className,
+  children,
+  ...props
+}: CheckpointIconProps) =>
+  children ? (
+    <span className={cn("size-4 shrink-0", className)}>{children}</span>
+  ) : (
+    <BookmarkIcon
+      aria-hidden="true"
+      className={cn("size-4 shrink-0", className)}
+      {...props}
+    />
+  );
+
+// ── CheckpointTrigger ─────────────────────────────────────────────────────────
+// The clickable restore button. Extends shadcn/ui Button.
+
+export type CheckpointTriggerProps = ComponentProps<typeof Button> & {
+  /** Optional tooltip shown on hover and used as aria-label when no children. */
+  tooltip?: string;
+};
+
+export const CheckpointTrigger = ({
+  children,
+  tooltip,
+  variant = "ghost",
+  size = "sm",
+  className,
+  ...props
+}: CheckpointTriggerProps) => (
+  <Button
+    aria-label={tooltip ?? "Restore checkpoint"}
+    className={cn(
+      "h-8 gap-1.5 px-3 text-muted-foreground hover:text-foreground",
+      className
+    )}
+    size={size}
+    title={tooltip}
+    type="button"
+    variant={variant}
+    {...props}
+  >
+    {children}
+  </Button>
+);
+
+Checkpoint.displayName = "Checkpoint";
+CheckpointIcon.displayName = "CheckpointIcon";
+CheckpointTrigger.displayName = "CheckpointTrigger";

package/components/ai-elements/edge.tsx

@@ -1,5 +1,6 @@
 import {
   BaseEdge,
+  EdgeLabelRenderer,
   type EdgeProps,
   getSimpleBezierPath,
   getSmoothStepPath,
@@ -45,18 +46,37 @@ const Strict = ({
   targetPosition,
   markerEnd,
   style,
+  label,
 }: EdgeProps) => {
-  const [edgePath] = getSmoothStepPath({
+  const [edgePath, labelX, labelY] = getSmoothStepPath({
     sourceX,
     sourceY,
     sourcePosition,
     targetX,
     targetY,
     targetPosition,
-    borderRadius: 0,
+    borderRadius: 8,
   });
 
-  return <BaseEdge id={id} markerEnd={markerEnd} path={edgePath} style={style} />;
+  return (
+    <>
+      <BaseEdge id={id} markerEnd={markerEnd} path={edgePath} style={style} />
+      {label && (
+        <EdgeLabelRenderer>
+          <div
+            style={{
+              position: "absolute",
+              transform: `translate(-50%, -50%) translate(${labelX}px,${labelY}px)`,
+              pointerEvents: "all",
+            }}
+            className="nodrag nopan rounded-md bg-secondary/90 px-2 py-0.5 text-[11px] font-medium text-secondary-foreground border border-border/80 shadow-xs backdrop-blur-xs"
+          >
+            {label}
+          </div>
+        </EdgeLabelRenderer>
+      )}
+    </>
+  );
 };
 
 const Animated = ({
@@ -69,15 +89,16 @@ const Animated = ({
   targetPosition,
   markerEnd,
   style,
+  label,
 }: EdgeProps) => {
-  const [edgePath] = getSmoothStepPath({
+  const [edgePath, labelX, labelY] = getSmoothStepPath({
     sourceX,
     sourceY,
     sourcePosition,
     targetX,
     targetY,
     targetPosition,
-    borderRadius: 0,
+    borderRadius: 8,
   });
 
   return (
@@ -86,6 +107,20 @@ const Animated = ({
       <circle fill="var(--primary)" r="4">
         <animateMotion dur="2s" path={edgePath} repeatCount="indefinite" />
       </circle>
+      {label && (
+        <EdgeLabelRenderer>
+          <div
+            style={{
+              position: "absolute",
+              transform: `translate(-50%, -50%) translate(${labelX}px,${labelY}px)`,
+              pointerEvents: "all",
+            }}
+            className="nodrag nopan rounded-md bg-secondary/90 px-2 py-0.5 text-[11px] font-medium text-secondary-foreground border border-border/80 shadow-xs backdrop-blur-xs"
+          >
+            {label}
+          </div>
+        </EdgeLabelRenderer>
+      )}
     </>
   );
 };
@@ -95,3 +130,4 @@ export const Edge = {
   Temporary,
   Animated,
 };
+

package/components/blocks/AIConversation/AIConversation.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react'
+import { fn } from '@storybook/test'
 import { AIConversation } from './AIConversation'
 
 const meta: Meta<typeof AIConversation> = {
@@ -161,4 +162,46 @@ export const UserOnly: Story = {
       },
     ],
   },
+}
+
+export const WithCheckpointRestore: Story = {
+  args: {
+    messages: [
+      {
+        id: '1',
+        type: 'human',
+        role: 'user',
+        content: 'What is React?',
+        avatarSrc: 'https://images.unsplash.com/photo-1494790108755-2616b612b786?w=32&h=32&fit=crop&crop=face',
+        avatarName: 'User',
+      },
+      {
+        id: '2',
+        type: 'ai',
+        role: 'orchestrator',
+        content: 'React is a JavaScript library for building user interfaces. It was developed by Facebook and is now maintained by Meta and a community of developers.',
+        avatarSrc: 'https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=32&h=32&fit=crop&crop=face',
+        avatarName: 'Coordinator',
+        checkpointId: 'cp-step-1',
+      },
+      {
+        id: '3',
+        type: 'human',
+        role: 'user',
+        content: 'How does component state work?',
+        avatarSrc: 'https://images.unsplash.com/photo-1494790108755-2616b612b786?w=32&h=32&fit=crop&crop=face',
+        avatarName: 'User',
+      },
+      {
+        id: '4',
+        type: 'ai',
+        role: 'orchestrator',
+        content: 'State in React represents values that can change over time and trigger component re-renders when updated.',
+        avatarSrc: 'https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=32&h=32&fit=crop&crop=face',
+        avatarName: 'Coordinator',
+        checkpointId: 'cp-step-2',
+      },
+    ],
+    onRestoreCheckpoint: fn(),
+  },
 }

package/components/blocks/AIConversation/AIConversation.tsx

@@ -6,6 +6,11 @@ import {
   ConversationScrollButton,
   type ConversationProps,
 } from "@/components/ai-elements/conversation"
+import {
+  Checkpoint,
+  CheckpointIcon,
+  CheckpointTrigger,
+} from "@/components/ai-elements/checkpoint"
 import type { ToolCall, SubAgent } from "@/components/composites"
 import { UserMessage } from "@/components/composites/UserMessage"
 import { SpecialistMessage } from "@/components/composites/SpecialistMessage"
@@ -40,6 +45,7 @@ interface AIMessage {
   subAgents?: SubAgent[];
   isLoading?: boolean;
   blocks?: AIMessageBlock[];
+  checkpointId?: string;
 }
 
 export interface AIConversationProps
@@ -77,6 +83,10 @@ export interface AIConversationProps
    * Receives the raw content string and returns a ReactNode.
    */
   renderSystemMessage?: (content: string) => React.ReactNode
+  /**
+   * Callback fired when user restores a conversation checkpoint
+   */
+  onRestoreCheckpoint?: (messageId: string, checkpointId: string) => void
 }
 
 /**
@@ -91,6 +101,7 @@ export const AIConversation = React.memo<AIConversationProps>(
     emptyState,
     onToolAction,
     renderSystemMessage,
+    onRestoreCheckpoint,
     ...conversationProps
   }) => {
     const isEmpty = React.useMemo(
@@ -209,6 +220,9 @@ export const AIConversation = React.memo<AIConversationProps>(
               }
               currentGroup.blocks = updatedBlocks;
             }
+            if (msg.checkpointId) {
+              currentGroup.checkpointId = msg.checkpointId;
+            }
             currentGroup.isLoading = msg.isLoading;
           } else {
             currentGroup = {
@@ -216,6 +230,7 @@ export const AIConversation = React.memo<AIConversationProps>(
               toolCalls: msg.toolCalls ? [...msg.toolCalls] : undefined,
               subAgents: msg.subAgents ? [...msg.subAgents] : undefined,
               blocks: msg.blocks ? [...msg.blocks] : undefined,
+              checkpointId: msg.checkpointId,
             };
             result.push(currentGroup);
           }
@@ -269,7 +284,7 @@ export const AIConversation = React.memo<AIConversationProps>(
             )
           }
 
-          if (message.role === "orchestrator") {
+          if (message.role === "orchestrator" || message.role === "assistant" || (!message.role && message.type === "ai")) {
             // Extract sub-agents from the message
             const subAgents = message.subAgents || []
 
@@ -296,39 +311,65 @@ export const AIConversation = React.memo<AIConversationProps>(
             const isStreaming = message.isLoading || reasoningCalls.some((tc) => tc.status === "pending") || subAgents.some(sa => sa.status === "active") || directToolCalls.some(tc => tc.status === "pending")
 
             return (
-              <OrchestratorMessage
-                key={message.id}
-                message={{
-                  id: message.id,
-                  content: displayContentStr,
-                  avatarSrc: message.avatarSrc,
-                  avatarName: message.avatarName,
-                  isLoading: message.isLoading && !hasReasoning,
-                }}
-                showAvatar={showAvatars && hasDisplayContent}
-              >
-                {/* Render reasoning-section for hidden tool results and subagents */}
-                {hasReasoning && (
-                  <ReasoningDisplay 
-                    content={reasoningText} 
-                    items={message.blocks && message.blocks.length > 0 ? [] : reasoningCalls} 
-                    isStreaming={isStreaming} 
-                    onToolAction={onToolAction}
-                    defaultOpen={isStreaming || index === groupedMessages.length - 1}
-                  >
-                    {message.blocks && message.blocks.length > 0 ? (
-                      message.blocks.map((block, i) => {
-                        if (block.type === 'text') {
-                          return block.text && block.text.trim() ? (
-                            <div key={`text-${i}`} className="mb-4 text-muted-foreground whitespace-pre-wrap">
-                              {block.text}
-                            </div>
-                          ) : null;
-                        } else if (block.type === 'toolCall' && block.toolCall && block.toolCall.name !== 'ask_user' && block.toolCall.name !== 'ask_question') {
-                          return <ToolCallDisplay key={block.id} toolCall={block.toolCall} onToolAction={onToolAction} />;
-                        } else if (block.type === 'subAgent' && block.subAgent) {
-                          const subAgent = block.subAgent;
-                          return (
+              <React.Fragment key={message.id}>
+                <OrchestratorMessage
+                  message={{
+                    id: message.id,
+                    content: displayContentStr,
+                    avatarSrc: message.avatarSrc,
+                    avatarName: message.avatarName,
+                    isLoading: message.isLoading && !hasReasoning,
+                  }}
+                  showAvatar={showAvatars && hasDisplayContent}
+                >
+                  {/* Render reasoning-section for hidden tool results and subagents */}
+                  {hasReasoning && (
+                    <ReasoningDisplay 
+                      content={reasoningText} 
+                      items={message.blocks && message.blocks.length > 0 ? [] : reasoningCalls} 
+                      isStreaming={isStreaming} 
+                      onToolAction={onToolAction}
+                      defaultOpen={isStreaming || index === groupedMessages.length - 1}
+                    >
+                      {message.blocks && message.blocks.length > 0 ? (
+                        message.blocks.map((block, i) => {
+                          if (block.type === 'text') {
+                            return block.text && block.text.trim() ? (
+                              <div key={`text-${i}`} className="mb-4 text-muted-foreground whitespace-pre-wrap">
+                                {block.text}
+                              </div>
+                            ) : null;
+                          } else if (block.type === 'toolCall' && block.toolCall && block.toolCall.name !== 'ask_user' && block.toolCall.name !== 'ask_question') {
+                            return <ToolCallDisplay key={block.id} toolCall={block.toolCall} onToolAction={onToolAction} />;
+                          } else if (block.type === 'subAgent' && block.subAgent) {
+                            const subAgent = block.subAgent;
+                            return (
+                              <SpecialistMessage
+                                key={subAgent.id}
+                                message={{
+                                  id: subAgent.id,
+                                  name: subAgent.subAgentName,
+                                  description: undefined,
+                                  input: subAgent.input,
+                                  content: typeof subAgent.output === 'string' ? subAgent.output : (subAgent.output ? JSON.stringify(subAgent.output) : ''),
+                                  status: subAgent.status,
+                                  toolCalls: [],
+                                }}
+                                isNested={true}
+                              />
+                            );
+                          }
+                          return null;
+                        })
+                      ) : (
+                        <>
+                          {/* Render direct tool calls fallback */}
+                          {directToolCalls.map((tc) => (
+                            <ToolCallDisplay key={tc.id} toolCall={tc} onToolAction={onToolAction} />
+                          ))}
+
+                          {/* Render specialist sub-agents fallback */}
+                          {subAgents.map((subAgent) => (
                             <SpecialistMessage
                               key={subAgent.id}
                               message={{
@@ -342,57 +383,57 @@ export const AIConversation = React.memo<AIConversationProps>(
                               }}
                               isNested={true}
                             />
-                          );
-                        }
-                        return null;
-                      })
-                    ) : (
-                      <>
-                        {/* Render direct tool calls fallback */}
-                        {directToolCalls.map((tc) => (
-                          <ToolCallDisplay key={tc.id} toolCall={tc} onToolAction={onToolAction} />
-                        ))}
-
-                        {/* Render specialist sub-agents fallback */}
-                        {subAgents.map((subAgent) => (
-                          <SpecialistMessage
-                            key={subAgent.id}
-                            message={{
-                              id: subAgent.id,
-                              name: subAgent.subAgentName,
-                              description: undefined,
-                              input: subAgent.input,
-                              content: typeof subAgent.output === 'string' ? subAgent.output : (subAgent.output ? JSON.stringify(subAgent.output) : ''),
-                              status: subAgent.status,
-                              toolCalls: [],
-                            }}
-                            isNested={true}
-                          />
-                        ))}
-                      </>
-                    )}
-                  </ReasoningDisplay>
+                          ))}
+                        </>
+                      )}
+                    </ReasoningDisplay>
+                  )}
+                </OrchestratorMessage>
+                {message.checkpointId && onRestoreCheckpoint && !message.isLoading && !hasReasoning && (
+                  <Checkpoint>
+                    <CheckpointIcon />
+                    <CheckpointTrigger
+                      onClick={() =>
+                        onRestoreCheckpoint(message.id, message.checkpointId!)
+                      }
+                    >
+                      Restore checkpoint
+                    </CheckpointTrigger>
+                  </Checkpoint>
                 )}
-              </OrchestratorMessage>
+              </React.Fragment>
             )
           }
 
           // Default to specialist message for any other AI messages
           return (
-            <SpecialistMessage
-              key={message.id}
-              message={{
-                id: message.id,
-                name: message.avatarName || "Agent",
-                content: contentStr,
-                toolCalls: message.toolCalls?.filter((tc) => tc.name !== "task"),
-                status: "completed",
-              }}
-              isNested={false}
-            />
+            <React.Fragment key={message.id}>
+              <SpecialistMessage
+                message={{
+                  id: message.id,
+                  name: message.avatarName || "Agent",
+                  content: contentStr,
+                  toolCalls: message.toolCalls?.filter((tc) => tc.name !== "task"),
+                  status: "completed",
+                }}
+                isNested={false}
+              />
+              {message.checkpointId && onRestoreCheckpoint && !message.isLoading && (
+                <Checkpoint>
+                  <CheckpointIcon />
+                  <CheckpointTrigger
+                    onClick={() =>
+                      onRestoreCheckpoint(message.id, message.checkpointId!)
+                    }
+                  >
+                    Restore checkpoint
+                  </CheckpointTrigger>
+                </Checkpoint>
+              )}
+            </React.Fragment>
           )
         }),
-      [groupedMessages, showAvatars, onToolAction]
+      [groupedMessages, showAvatars, onToolAction, onRestoreCheckpoint]
     )
 
     return (

package/components/blocks/PreviewCanvas/index.ts

@@ -0,0 +1,2 @@
+export * from './interfaces';
+export * from './preview-layout';