@page-speed/agent-everywhere 0.1.0

package/README.md

@@ -0,0 +1,186 @@
+# @page-speed/agent-everywhere
+
+A composable, vendor-neutral UI engine for AI agent conversations. It ships the
+React building blocks an AI agent needs to render a conversation **anywhere** —
+across multiple **placements** and with a rich library of **artifacts** — plus a
+streaming WebSocket transport and an orchestration manifest/registry an agent can
+use to pick and render components at runtime.
+
+The package is intentionally self-contained and host-agnostic:
+
+- **No framework lock-in** — pure React + `motion` + `lucide-react`; no `next/*`
+  imports. Works in Next.js (App or Pages Router), Vite, Remix, CRA, etc.
+- **No embedded backend** — the transport layer contains **no API origin and no
+  route**. The host application always supplies its own socket URL (typically
+  from an environment variable), so nothing about any specific deployment is
+  baked into this public package.
+- **SSR-safe** — browser-only access is guarded; the entry is marked
+  `"use client"` for React Server Component frameworks.
+- **Tree-shakable** — ESM + CJS builds with full TypeScript types.
+
+## Installation
+
+```bash
+pnpm add @page-speed/agent-everywhere
+```
+
+### Peer dependencies
+
+Provided by the consuming app (versions are intentionally wide so the package
+slots into existing projects):
+
+| Package | Range |
+| --- | --- |
+| `react` / `react-dom` | `^18.2 || ^19` |
+| `motion` | `>=11` |
+| `lucide-react` | `>=0.460 <2` |
+| `recharts` | `>=2.13 <4` (optional — only needed for chart artifacts) |
+| `@radix-ui/react-*` | `>=1.1` (avatar, collapsible, progress, scroll-area, slot, tooltip) |
+
+Tailwind CSS (v3 or v4) is expected in the host app. Components use CSS-variable
+design tokens (`bg-background`, `text-foreground`, `bg-primary`, …) so they adopt
+the consumer's theme/skin automatically.
+
+## Placements
+
+A single `AgentSurface` renders the same conversation into any layout — pick a
+`mode` and the messages, input, and data region flow into the matching
+container. There are no per-surface forks of the conversation logic.
+
+| Mode | Container | Use |
+| --- | --- | --- |
+| `panel` | `ChatPanel` | Inline conversation embedded in a dashboard. |
+| `widget` | `FloatingWidget` | Embeddable launcher + chat (CMS, client sites, third-party pages). |
+| `overlay` | `OverlayModal` | Centered modal conversation. |
+| `fullscreen` | `FullscreenDashboard` | Full-screen chat + report sidebar. |
+| `split` | `SplitView` | Chat beside a live results/preview pane. |
+| `mobile` | `MobileShell` | Full-height mobile-optimized layout. |
+
+```tsx
+import { AgentSurface } from '@page-speed/agent-everywhere';
+
+<AgentSurface
+  mode="split"
+  title="Page Designer"
+  messages={messages}
+  isLoading={isStreaming}
+  inputValue={draft}
+  onInputChange={setDraft}
+  onSubmit={() => send(draft)}
+  dataPanel={<LivePreview />}
+/>;
+```
+
+## Artifacts
+
+Components an agent can render inside responses, grouped by category. All are
+prop-driven and individually importable:
+
+- **Data display** — `ChartContainer`, `MetricsGrid`, `DataTable`,
+  `ProgressTracker`, `SentimentDisplay`, `MediaGallery`, `AllocationBreakdown`,
+  `AnalyticsDashboard`, `ReportView`.
+- **Interactive** — `EntityCard`, `OptionCards`, `ListingFeed`, `ControlGrid`,
+  `RecommendationCards`, `ScheduleTimeline`, `SettingsPanel`, `AgentHandoff`,
+  `PersonaSelector`.
+- **Messages** — `MessageList`, `MessageWithReasoning`, `MessageWithSteps`,
+  `MessageWithFeedback`, `MessageWithAttachments`, `ConversationArtifact`.
+- **Input** — `PromptInput`, `MultimodalInput`, `QuickReplies`,
+  `TemplateSelector`, `InlineSuggestionsInput`, `FileDropZone`, `PromptLibrary`.
+- **Specialty** — `ImageGenerator`, `WritingAssistant`, `OnboardingWizard`,
+  `QuizCard`, `GuidedLessonFlow`, `MediaEditorCanvas`.
+
+## Streaming transport
+
+The transport layer speaks a small, camelCase WebSocket envelope protocol for
+streaming chat: `assistant_message_start` → `*_delta` / `*_thinking_delta` →
+`assistant_message_blocks` → `assistant_message_complete`, with an `error`
+envelope and a `connection_ready` handshake.
+
+> The package embeds **no origin and no route**. Supply your own socket URL (or
+> a resolver). The path below is an illustrative placeholder — substitute the
+> route your own backend exposes, ideally read from an environment variable.
+
+### `useSemanticBuilder` (drop-in hook)
+
+```tsx
+import {
+  useSemanticBuilder,
+  buildSocketUrl,
+} from '@page-speed/agent-everywhere';
+
+function Designer({ websiteId, pageCategoryId, blocks, onBlocks }) {
+  const conversation = useSemanticBuilder({
+    // Host supplies the URL — never hardcode it in shared code.
+    resolveSocketUrl: ({ websiteId, pageCategoryId }) =>
+      buildSocketUrl(
+        process.env.NEXT_PUBLIC_API_BASE_URL!, // e.g. https://api.your-app.example
+        '/your/backend/route/{websiteId}/{pageCategoryId}/chat',
+        { websiteId, pageCategoryId },
+      ),
+    websiteId,
+    pageCategoryId,
+    pageName: 'Home',
+    blocks,
+    enabled: true,
+    onGeneratedBlocks: onBlocks,
+  });
+
+  const { messages, isStreaming, statusLabel, sendMessage } = conversation;
+  // …render with <AgentSurface mode="split" … />
+}
+```
+
+The hook returns `{ messages, connectionState, connectionError, statusLabel,
+isConnected, isStreaming, sendMessage, retry }` and manages connection
+lifecycle, reconnect with backoff, the streaming message state machine, hidden
+(background) requests, and block-extraction fallbacks.
+
+### Low-level client
+
+For non-React hosts or custom integrations, use the client directly:
+
+```ts
+import { SemanticBuilderSocketClient } from '@page-speed/agent-everywhere';
+
+const client = new SemanticBuilderSocketClient({
+  websiteId: 42,
+  pageCategoryId: 'home',
+  socketUrl: makeYourWssUrl(), // host-provided
+  onEnvelope: (e) => { /* handle assistant_* / blocks / complete / error */ },
+  onStateChange: (s) => { /* idle | connecting | ready | streaming | error */ },
+});
+client.connect();
+```
+
+## Orchestration
+
+A data-only manifest describes every component an orchestrator (or LLM) can
+select, plus a runtime registry to resolve a manifest name to a real component.
+
+```tsx
+import {
+  registerAllComponents,
+  componentManifest,
+  findComponentsByCapability,
+  DynamicRenderer,
+} from '@page-speed/agent-everywhere';
+
+registerAllComponents(); // once at startup
+
+const [entry] = findComponentsByCapability('chart');
+<DynamicRenderer instruction={{ component: entry.name, props: { data } }} />;
+```
+
+## Local development
+
+```bash
+pnpm install
+pnpm type-check
+pnpm test
+pnpm build
+```
+
+## License
+
+UNLICENSED — private package. Distributed for use within OpenSite/Toastability
+applications.