@page-speed/agent-everywhere 0.4.0 → 0.6.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,125 @@ 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).
+
+### AgentWorkspace — the page-level AI layout wrapper
+
+`AgentWorkspace` composes the native pieces into a full workspace layout: an
+optional left panel, the host's page content in a growing center column with the
+prompt composer docked at the bottom, an optional right panel, and a
+conversation layer that **slides in over the center content** when the shared
+session activates (and slides away on `reset()`).
+
+```tsx
+import {
+  NativeAgentProvider,
+  AgentWorkspace,
+  AgentWorkspacePanelToggle,
+} from '@page-speed/agent-everywhere';
+
+<NativeAgentProvider resolveSocketUrl={resolveSocketUrl} websiteId={id} pageCategoryId="pages">
+  <AgentWorkspace
+    className="h-dvh"
+    leftPanel={<KnowledgePanel />}      // omit → no panel, no toggle
+    rightPanel={<AnalyticsPanel />}     // widths via left/rightPanelWidth
+    composerPlaceholder="Describe a site-wide change…"
+    composerHint="Agents render live, interactive artifacts inline."
+  >
+    <YourPage />
+  </AgentWorkspace>
+</NativeAgentProvider>;
+```
+
+Every region is independently optional and controllable:
+
+- **Panels** collapse/expand with a smooth width-collapse animation (the
+  outer rail animates to `0` while the inner wrapper keeps its open width, so
+  content clips out instead of reflowing). Uncontrolled by default;
+  controlled via `leftPanelOpen`/`onLeftPanelOpenChange` (and the right-side
+  equivalents). Built-in floating toggles render in the top corners
+  (`showPanelToggles={false}` to place `<AgentWorkspacePanelToggle side="…"/>`
+  in your own chrome). Panels are gated to `lg:` viewports.
+- **Conversation layer** auto-opens on the first submit (or `activate()`),
+  can be minimized back to the page without ending the session (a
+  "View conversation" chip appears in the dock), and accepts a custom node via
+  `conversation` for decorated transcripts. Controlled via `conversationOpen`.
+- **Composer dock** renders `AgentWorkspaceComposer` — a pill input with an
+  auto-growing textarea (Enter submits, Shift+Enter inserts a newline), an
+  optional attach affordance (`onAttach`), and a circular send button. Pass
+  `composer={false}` to drop it, a node to replace it, or `onComposerSubmit`
+  to intercept submits.
+- **Programmatic control** from anywhere inside: `useAgentWorkspace()` exposes
+  `toggleLeftPanel`, `setRightPanelOpen`, `openConversation`,
+  `closeConversation`, and friends for dynamic layout scenarios.
+
 ### Inline confirmation / proposed-plan panels
 
 Confirmation and proposed-plan panels flow **inline in the transcript** — attach
@@ -166,9 +286,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