@page-speed/agent-everywhere 0.3.1 → 0.5.0

package/README.md

@@ -55,6 +55,7 @@ container. There are no per-surface forks of the conversation logic.
 | `fullscreen` | `FullscreenDashboard` | Full-screen chat + report sidebar. |
 | `split` | `SplitView` | Chat beside a live results/preview pane. |
 | `mobile` | `MobileShell` | Full-height mobile-optimized layout. |
+| `native` | `NativeSurface` | Host-placed, position-agnostic pieces — see [Native variant](#native-variant). |
 
 ```tsx
 import { AgentSurface } from '@page-speed/agent-everywhere';
@@ -71,6 +72,110 @@ import { AgentSurface } from '@page-speed/agent-everywhere';
 />;
 ```
 
+### Native variant
+
+The `native` variant is unlike the other placements: it has **no opinion on
+position**. The agent's composer and conversation renderer are native,
+fully-customizable pieces the host places anywhere — a docked bottom bar, a pane,
+a modal, a dashboard card — and styles itself. The two pieces work **disconnected
+from each other**, and a provider lets them **share one live session even when
+rendered in completely separate DOM regions**.
+
+**Simple, controlled case** — one component you position yourself:
+
+```tsx
+import { AgentSurface } from '@page-speed/agent-everywhere';
+
+<AgentSurface
+  mode="native"
+  messages={messages}
+  isLoading={isStreaming}
+  inputValue={draft}
+  onInputChange={setDraft}
+  onSubmit={() => send(draft)}
+/>;
+```
+
+**Decoupled case** — one shared session feeding pieces in separate regions of the
+page. The composer sits idle at the bottom; once the user submits, the host swaps
+its own content for the conversation surface:
+
+```tsx
+import {
+  NativeAgentProvider,
+  AgentComposer,
+  AgentConversation,
+  useNativeAgent,
+} from '@page-speed/agent-everywhere';
+
+function PagesDashboard() {
+  return (
+    <NativeAgentProvider
+      // Host supplies the socket URL (or a resolver) — never hardcoded here.
+      resolveSocketUrl={resolveSocketUrl}
+      websiteId={websiteId}
+      pageCategoryId="pages"
+      connectionStrategy="lazy" // default: no socket until the first submit
+    >
+      <Content />
+      {/* Place the composer anywhere — here, a docked bottom bar. */}
+      <AgentComposer
+        className="fixed inset-x-0 bottom-0 m-4"
+        footer="Grounded in your connected sources."
+      />
+    </NativeAgentProvider>
+  );
+}
+
+function Content() {
+  const { isActive } = useNativeAgent();
+  // The host owns the swap — render your own page until the agent is engaged.
+  return isActive ? <AgentConversation /> : <PagesTable />;
+}
+```
+
+Both `AgentComposer` and `AgentConversation` are **dual-mode**: inside a
+`NativeAgentProvider` they wire themselves to the shared session; given explicit
+`value`/`onChange`/`onSubmit` (composer) or `messages` (conversation) props they
+run fully controlled with no provider. For 100%-custom UI, read the session
+directly with `useNativeAgent()`. The connection is lazy by default
+(`connectionStrategy="eager"` to pre-connect on mount).
+
+### Inline confirmation / proposed-plan panels
+
+Confirmation and proposed-plan panels flow **inline in the transcript** — attach
+one to a message via `message.confirmation` and it renders after that message's
+content, never pinned over the response. The plan body reuses the same markdown
+rendering and spacing as assistant messages, so long multi-paragraph / bulleted
+plans stay readable. Wire `onConfirmAction` (or use `ConfirmationPanel`
+directly) to handle the action buttons.
+
+```tsx
+const messages = [
+  {
+    id: 'm1',
+    role: 'assistant',
+    content: 'Here is the response and the plan.',
+    timestamp: new Date(),
+    confirmation: {
+      title: 'Proposed plan',
+      summary: '3 pages to change',
+      body: '## What changes\n\n- Rebuild the platform page\n- Refresh OG images',
+      actions: [
+        { id: 'apply', label: 'Apply changes' },
+        { id: 'cancel', label: 'Cancel', variant: 'outline' },
+      ],
+    },
+  },
+];
+
+<AgentSurface
+  mode="widget"
+  messages={messages}
+  onConfirmAction={(messageId, actionId) => apply(messageId, actionId)}
+/>;
+```
+
 ## Artifacts
 
 Components an agent can render inside responses, grouped by category. All are
@@ -81,7 +186,7 @@ prop-driven and individually importable:
   `AnalyticsDashboard`, `ReportView`.
 - **Interactive** — `EntityCard`, `OptionCards`, `ListingFeed`, `ControlGrid`,
   `RecommendationCards`, `ScheduleTimeline`, `SettingsPanel`, `AgentHandoff`,
-  `PersonaSelector`.
+  `ConfirmationPanel`, `PersonaSelector`.
 - **Messages** — `MessageList`, `MessageWithReasoning`, `MessageWithSteps`,
   `MessageWithFeedback`, `MessageWithAttachments`, `ConversationArtifact`.
 - **Input** — `PromptInput`, `MultimodalInput`, `QuickReplies`,
@@ -131,9 +236,11 @@ function Designer({ websiteId, pageCategoryId, blocks, onBlocks }) {
 ```
 
 The hook returns `{ messages, connectionState, connectionError, statusLabel,
-isConnected, isStreaming, sendMessage, retry }` and manages connection
+isConnected, isStreaming, sendMessage, retry, reset }` and manages connection
 lifecycle, reconnect with backoff, the streaming message state machine, hidden
-(background) requests, and block-extraction fallbacks.
+(background) requests, and block-extraction fallbacks. Pass
+`seedWelcomeMessage: false` to start with an empty transcript (the `native`
+variant does this for its idle composer).
 
 ### Low-level client