@page-speed/agent-everywhere 0.5.0 → 0.7.0

package/README.md

@@ -141,6 +141,64 @@ 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:
+
+- **Workspace header** is persistent across the page and conversation states
+  so the chrome stays uniform: the left panel toggle, icon, title
+  (`conversationTitle`), and status line on the left; `headerActions` (your
+  page's primary action, e.g. a "+ New" button), the session reset, the
+  conversation chevron, and the right panel toggle on the right. Override the
+  status line with `headerStatus` (useful disconnected), or hide the bar with
+  `showHeader={false}`.
+- **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). The header hosts a toggle at each end; opt into extra
+  floating toggles with `showPanelToggles`, or 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

package/dist/index.cjs

@@ -8552,6 +8552,465 @@ function AgentConversation({
     )
   ] });
 }
+var AgentWorkspaceContext = React4.createContext(null);
+function useAgentWorkspace() {
+  const ctx = React4.useContext(AgentWorkspaceContext);
+  if (!ctx) {
+    throw new Error(
+      "useAgentWorkspace must be used within an <AgentWorkspace>."
+    );
+  }
+  return ctx;
+}
+function useAgentWorkspaceOptional() {
+  return React4.useContext(AgentWorkspaceContext);
+}
+var noop2 = () => {
+};
+function warnDev2(message) {
+  const env = globalThis.process?.env;
+  if (env && env.NODE_ENV !== "production") {
+    console.warn(`[AgentWorkspaceComposer] ${message}`);
+  }
+}
+var LINE_HEIGHT_PX2 = 20;
+var VERTICAL_PADDING_PX2 = 16;
+function AgentWorkspaceComposer({
+  value: valueProp,
+  onChange,
+  onSubmit,
+  loading: loadingProp,
+  disabled = false,
+  placeholder = "Ask anything\u2026",
+  onAttach,
+  leftActions,
+  minRows = 1,
+  maxRows = 6,
+  autoFocus = false,
+  className,
+  inputClassName
+}) {
+  const agent = useNativeAgentOptional();
+  const workspace = useAgentWorkspaceOptional();
+  const [draft, setDraft] = React4.useState("");
+  const textareaRef = React4.useRef(null);
+  const propsControlEditing = valueProp !== void 0 || onChange !== void 0;
+  const value = propsControlEditing ? valueProp ?? "" : agent ? agent.input : draft;
+  const handleChange = propsControlEditing ? onChange ?? noop2 : agent ? agent.setInput : setDraft;
+  const loading = loadingProp ?? agent?.isResponding ?? false;
+  const resize = React4.useCallback(() => {
+    const el = textareaRef.current;
+    if (!el) return;
+    el.style.height = "auto";
+    const maxHeight = maxRows * LINE_HEIGHT_PX2 + VERTICAL_PADDING_PX2;
+    const minHeight = minRows * LINE_HEIGHT_PX2 + VERTICAL_PADDING_PX2;
+    const next = Math.min(Math.max(el.scrollHeight, minHeight), maxHeight);
+    el.style.height = `${next}px`;
+    el.style.overflowY = el.scrollHeight > maxHeight ? "auto" : "hidden";
+  }, [maxRows, minRows]);
+  React4.useLayoutEffect(() => {
+    resize();
+  }, [value, resize]);
+  const handleSubmit = React4.useCallback(
+    (e) => {
+      e?.preventDefault();
+      if (!value.trim() || disabled || loading) return;
+      workspace?.openConversation();
+      if (onSubmit) {
+        onSubmit(value);
+        return;
+      }
+      if (!propsControlEditing && agent) {
+        agent.submit();
+        return;
+      }
+      warnDev2(
+        "submit was ignored: provide `onSubmit`, or render inside a <NativeAgentProvider>."
+      );
+    },
+    [value, disabled, loading, workspace, onSubmit, propsControlEditing, agent]
+  );
+  const handleKeyDown = React4.useCallback(
+    (e) => {
+      if (e.key === "Enter" && !e.shiftKey) {
+        e.preventDefault();
+        handleSubmit();
+      }
+    },
+    [handleSubmit]
+  );
+  const attach = leftActions ?? (onAttach ? /* @__PURE__ */ jsxRuntime.jsx(
+    "button",
+    {
+      type: "button",
+      onClick: onAttach,
+      "aria-label": "Attach",
+      className: "flex size-9 shrink-0 items-center justify-center rounded-xl text-muted-foreground transition-colors hover:bg-secondary hover:text-foreground",
+      children: /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Paperclip, { className: "size-4" })
+    }
+  ) : null);
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "form",
+    {
+      onSubmit: handleSubmit,
+      className: cn(
+        "flex items-end gap-2 rounded-2xl border border-border bg-background p-2 shadow-sm transition-colors focus-within:border-foreground/30",
+        className
+      ),
+      children: [
+        attach,
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "textarea",
+          {
+            ref: textareaRef,
+            value,
+            onChange: (e) => handleChange(e.target.value),
+            onKeyDown: handleKeyDown,
+            placeholder,
+            disabled,
+            autoFocus,
+            rows: minRows,
+            className: cn(
+              "flex-1 resize-none border-0 bg-transparent px-1 py-2 text-sm leading-5 shadow-none outline-none",
+              "placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-0",
+              "disabled:cursor-not-allowed disabled:opacity-50",
+              inputClassName
+            )
+          }
+        ),
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "button",
+          {
+            type: "submit",
+            "aria-label": "Send",
+            disabled: !value.trim() || disabled || loading,
+            className: "flex size-9 shrink-0 items-center justify-center rounded-full bg-primary text-primary-foreground transition-opacity disabled:opacity-30",
+            children: loading ? /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Loader2, { className: "size-4 animate-spin" }) : /* @__PURE__ */ jsxRuntime.jsx(lucideReact.ArrowUp, { className: "size-4" })
+          }
+        )
+      ]
+    }
+  );
+}
+function AgentWorkspacePanelToggle({
+  side,
+  open: openProp,
+  onToggle,
+  className
+}) {
+  const workspace = useAgentWorkspaceOptional();
+  const propsControlled = openProp !== void 0 || onToggle !== void 0;
+  if (!propsControlled && workspace) {
+    const hasPanel = side === "left" ? workspace.hasLeftPanel : workspace.hasRightPanel;
+    if (!hasPanel) return null;
+  }
+  const open = propsControlled ? openProp ?? false : side === "left" ? workspace?.leftPanelOpen ?? false : workspace?.rightPanelOpen ?? false;
+  const handleToggle = propsControlled ? onToggle : side === "left" ? workspace?.toggleLeftPanel : workspace?.toggleRightPanel;
+  const Icon = side === "left" ? lucideReact.PanelLeft : lucideReact.PanelRight;
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "button",
+    {
+      type: "button",
+      onClick: handleToggle,
+      "aria-label": side === "left" ? "Toggle left panel" : "Toggle right panel",
+      "aria-pressed": open,
+      className: cn(
+        "flex size-8 items-center justify-center rounded-lg transition-colors",
+        open ? "bg-secondary text-foreground" : "text-muted-foreground hover:bg-secondary",
+        className
+      ),
+      children: /* @__PURE__ */ jsxRuntime.jsx(Icon, { className: "size-4" })
+    }
+  );
+}
+var inertProps = (inert) => inert ? { inert: "" } : {};
+function useOpenState(controlled, defaultOpen, onChange) {
+  const [internal, setInternal] = React4.useState(defaultOpen);
+  const isControlled = controlled !== void 0;
+  const open = isControlled ? controlled : internal;
+  const onChangeRef = React4.useRef(onChange);
+  React4.useEffect(() => {
+    onChangeRef.current = onChange;
+  }, [onChange]);
+  const setOpen = React4.useCallback(
+    (next) => {
+      if (!isControlled) setInternal(next);
+      onChangeRef.current?.(next);
+    },
+    [isControlled]
+  );
+  return [open, setOpen];
+}
+function AgentWorkspace({
+  children,
+  leftPanel,
+  rightPanel,
+  leftPanelWidth = 320,
+  rightPanelWidth = 460,
+  defaultLeftPanelOpen = true,
+  defaultRightPanelOpen = true,
+  leftPanelOpen: leftPanelOpenProp,
+  rightPanelOpen: rightPanelOpenProp,
+  onLeftPanelOpenChange,
+  onRightPanelOpenChange,
+  showPanelToggles = false,
+  showHeader,
+  showConversationHeader,
+  headerActions,
+  headerStatus,
+  conversation,
+  conversationOpen: conversationOpenProp,
+  onConversationOpenChange,
+  conversationTitle = "AI Assistant",
+  composer = true,
+  composerPlaceholder,
+  composerHint,
+  onComposerSubmit,
+  className,
+  contentClassName,
+  conversationClassName,
+  leftPanelClassName,
+  rightPanelClassName,
+  composerClassName
+}) {
+  const agent = useNativeAgentOptional();
+  const hasLeftPanel = leftPanel !== void 0 && leftPanel !== null;
+  const hasRightPanel = rightPanel !== void 0 && rightPanel !== null;
+  const [leftOpen, setLeftOpen] = useOpenState(
+    leftPanelOpenProp,
+    defaultLeftPanelOpen,
+    onLeftPanelOpenChange
+  );
+  const [rightOpen, setRightOpen] = useOpenState(
+    rightPanelOpenProp,
+    defaultRightPanelOpen,
+    onRightPanelOpenChange
+  );
+  const [conversationOpen, setConversationOpen] = useOpenState(
+    conversationOpenProp,
+    false,
+    onConversationOpenChange
+  );
+  const isActive = agent?.isActive ?? false;
+  const wasActiveRef = React4.useRef(false);
+  React4.useEffect(() => {
+    if (isActive !== wasActiveRef.current) {
+      wasActiveRef.current = isActive;
+      setConversationOpen(isActive);
+    }
+  }, [isActive, setConversationOpen]);
+  const value = React4.useMemo(
+    () => ({
+      hasLeftPanel,
+      hasRightPanel,
+      leftPanelOpen: leftOpen,
+      rightPanelOpen: rightOpen,
+      setLeftPanelOpen: setLeftOpen,
+      setRightPanelOpen: setRightOpen,
+      toggleLeftPanel: () => setLeftOpen(!leftOpen),
+      toggleRightPanel: () => setRightOpen(!rightOpen),
+      conversationOpen,
+      setConversationOpen,
+      openConversation: () => setConversationOpen(true),
+      closeConversation: () => setConversationOpen(false)
+    }),
+    [
+      hasLeftPanel,
+      hasRightPanel,
+      leftOpen,
+      rightOpen,
+      setLeftOpen,
+      setRightOpen,
+      conversationOpen,
+      setConversationOpen
+    ]
+  );
+  const showDock = composer !== false;
+  const dockNode = composer === true || composer === void 0 ? /* @__PURE__ */ jsxRuntime.jsx(
+    AgentWorkspaceComposer,
+    {
+      placeholder: composerPlaceholder,
+      onSubmit: onComposerSubmit
+    }
+  ) : composer;
+  const headerVisible = showHeader ?? showConversationHeader ?? true;
+  const statusLine = headerStatus ?? (agent ? agent.error ?? agent.statusLabel : null);
+  return /* @__PURE__ */ jsxRuntime.jsx(AgentWorkspaceContext.Provider, { value, children: /* @__PURE__ */ jsxRuntime.jsxs(
+    "div",
+    {
+      "data-conversation-open": conversationOpen || void 0,
+      className: cn(
+        "flex h-full w-full overflow-hidden bg-background text-foreground",
+        className
+      ),
+      children: [
+        hasLeftPanel && /* @__PURE__ */ jsxRuntime.jsx(
+          "aside",
+          {
+            "data-state": leftOpen ? "open" : "collapsed",
+            "aria-hidden": !leftOpen || void 0,
+            className: cn(
+              "relative hidden h-full shrink-0 overflow-hidden border-r border-border transition-[width] duration-300 ease-in-out lg:block",
+              !leftOpen && "border-r-0",
+              leftPanelClassName
+            ),
+            style: { width: leftOpen ? leftPanelWidth : 0 },
+            children: /* @__PURE__ */ jsxRuntime.jsx("div", { className: "h-full", style: { width: leftPanelWidth }, children: leftPanel })
+          }
+        ),
+        /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "relative flex h-full min-w-0 grow flex-col", children: [
+          showPanelToggles && hasLeftPanel && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "absolute left-3 top-3 z-30 hidden lg:block", children: /* @__PURE__ */ jsxRuntime.jsx(
+            AgentWorkspacePanelToggle,
+            {
+              side: "left",
+              className: "border border-border/60 bg-background/80 shadow-sm backdrop-blur"
+            }
+          ) }),
+          showPanelToggles && hasRightPanel && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "absolute right-3 top-3 z-30 hidden lg:block", children: /* @__PURE__ */ jsxRuntime.jsx(
+            AgentWorkspacePanelToggle,
+            {
+              side: "right",
+              className: "border border-border/60 bg-background/80 shadow-sm backdrop-blur"
+            }
+          ) }),
+          headerVisible && /* @__PURE__ */ jsxRuntime.jsxs(
+            "div",
+            {
+              "data-workspace-header": "",
+              className: "flex shrink-0 items-center justify-between gap-3 border-b border-border bg-background px-3 py-2.5",
+              children: [
+                /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex min-w-0 items-center gap-2.5", children: [
+                  hasLeftPanel && /* @__PURE__ */ jsxRuntime.jsx(
+                    AgentWorkspacePanelToggle,
+                    {
+                      side: "left",
+                      className: "hidden lg:flex"
+                    }
+                  ),
+                  /* @__PURE__ */ jsxRuntime.jsx("span", { className: "flex size-7 shrink-0 items-center justify-center rounded-md bg-primary text-primary-foreground", children: /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Sparkles, { className: "size-3.5" }) }),
+                  /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "min-w-0", children: [
+                    /* @__PURE__ */ jsxRuntime.jsx("div", { className: "truncate text-sm font-medium", children: conversationTitle }),
+                    statusLine && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "truncate text-xs text-muted-foreground", children: statusLine })
+                  ] })
+                ] }),
+                /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex shrink-0 items-center gap-1", children: [
+                  headerActions,
+                  agent && /* @__PURE__ */ jsxRuntime.jsx(
+                    "button",
+                    {
+                      type: "button",
+                      onClick: () => agent.reset(),
+                      "aria-label": "Start a new conversation",
+                      title: "New conversation",
+                      className: "flex size-8 items-center justify-center rounded-lg text-muted-foreground transition-colors hover:bg-secondary hover:text-foreground",
+                      children: /* @__PURE__ */ jsxRuntime.jsx(lucideReact.RotateCcw, { className: "size-4" })
+                    }
+                  ),
+                  /* @__PURE__ */ jsxRuntime.jsx(
+                    "button",
+                    {
+                      type: "button",
+                      onClick: () => setConversationOpen(!conversationOpen),
+                      "aria-label": conversationOpen ? "Hide conversation" : "Show conversation",
+                      title: conversationOpen ? "Hide conversation" : "Show conversation",
+                      className: "flex size-8 items-center justify-center rounded-lg text-muted-foreground transition-colors hover:bg-secondary hover:text-foreground",
+                      children: /* @__PURE__ */ jsxRuntime.jsx(
+                        lucideReact.ChevronDown,
+                        {
+                          className: cn(
+                            "size-4 transition-transform duration-200",
+                            !conversationOpen && "rotate-180"
+                          )
+                        }
+                      )
+                    }
+                  ),
+                  hasRightPanel && /* @__PURE__ */ jsxRuntime.jsx(
+                    AgentWorkspacePanelToggle,
+                    {
+                      side: "right",
+                      className: "hidden lg:flex"
+                    }
+                  )
+                ] })
+              ]
+            }
+          ),
+          /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "relative min-h-0 grow", children: [
+            /* @__PURE__ */ jsxRuntime.jsx(
+              "div",
+              {
+                "aria-hidden": conversationOpen || void 0,
+                ...inertProps(conversationOpen),
+                className: cn("h-full overflow-y-auto", contentClassName),
+                children
+              }
+            ),
+            /* @__PURE__ */ jsxRuntime.jsx(
+              "div",
+              {
+                "data-state": conversationOpen ? "open" : "closed",
+                "aria-hidden": !conversationOpen || void 0,
+                ...inertProps(!conversationOpen),
+                className: cn(
+                  "absolute inset-0 z-20 flex flex-col bg-background transition-[opacity,transform] duration-300 ease-out",
+                  conversationOpen ? "translate-y-0 opacity-100" : "pointer-events-none translate-y-8 opacity-0",
+                  conversationClassName
+                ),
+                children: /* @__PURE__ */ jsxRuntime.jsx("div", { className: "min-h-0 grow", children: conversation ?? /* @__PURE__ */ jsxRuntime.jsx(
+                  AgentConversation,
+                  {
+                    contentClassName: "mx-auto w-full max-w-3xl",
+                    showAvatars: true
+                  }
+                ) })
+              }
+            )
+          ] }),
+          showDock && /* @__PURE__ */ jsxRuntime.jsx(
+            "div",
+            {
+              className: cn(
+                "relative z-30 shrink-0 border-t border-border bg-background/80 px-4 py-3 backdrop-blur",
+                composerClassName
+              ),
+              children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "mx-auto w-full max-w-3xl", children: [
+                isActive && !conversationOpen && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "mb-2 flex justify-center", children: /* @__PURE__ */ jsxRuntime.jsxs(
+                  "button",
+                  {
+                    type: "button",
+                    onClick: () => setConversationOpen(true),
+                    className: "inline-flex items-center gap-1.5 rounded-full border border-border bg-background px-2.5 py-1 text-xs text-muted-foreground transition-colors hover:border-foreground/20 hover:text-foreground",
+                    children: [
+                      agent?.isResponding ? /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Loader2, { className: "size-3 animate-spin" }) : /* @__PURE__ */ jsxRuntime.jsx(lucideReact.MessageSquare, { className: "size-3" }),
+                      "View conversation"
+                    ]
+                  }
+                ) }),
+                dockNode,
+                composerHint && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "mt-2 text-center text-[11px] text-muted-foreground", children: composerHint })
+              ] })
+            }
+          )
+        ] }),
+        hasRightPanel && /* @__PURE__ */ jsxRuntime.jsx(
+          "aside",
+          {
+            "data-state": rightOpen ? "open" : "collapsed",
+            "aria-hidden": !rightOpen || void 0,
+            className: cn(
+              "relative hidden h-full shrink-0 overflow-hidden border-l border-border transition-[width] duration-300 ease-in-out lg:block",
+              !rightOpen && "border-l-0",
+              rightPanelClassName
+            ),
+            style: { width: rightOpen ? rightPanelWidth : 0 },
+            children: /* @__PURE__ */ jsxRuntime.jsx("div", { className: "h-full", style: { width: rightPanelWidth }, children: rightPanel })
+          }
+        )
+      ]
+    }
+  ) });
+}
 
 exports.AgentAvatar = AgentAvatar;
 exports.AgentComposer = AgentComposer;
@@ -8559,6 +9018,9 @@ exports.AgentConversation = AgentConversation;
 exports.AgentHandoff = AgentHandoff;
 exports.AgentProvider = AgentProvider;
 exports.AgentSurface = AgentSurface;
+exports.AgentWorkspace = AgentWorkspace;
+exports.AgentWorkspaceComposer = AgentWorkspaceComposer;
+exports.AgentWorkspacePanelToggle = AgentWorkspacePanelToggle;
 exports.AllocationBreakdown = AllocationBreakdown;
 exports.AnalyticsDashboard = AnalyticsDashboard;
 exports.Avatar = Avatar;
@@ -8672,6 +9134,8 @@ exports.useAgentBackend = useAgentBackend;
 exports.useAgentInput = useAgentInput;
 exports.useAgentLayout = useAgentLayout;
 exports.useAgentMessages = useAgentMessages;
+exports.useAgentWorkspace = useAgentWorkspace;
+exports.useAgentWorkspaceOptional = useAgentWorkspaceOptional;
 exports.useNativeAgent = useNativeAgent;
 exports.useNativeAgentOptional = useNativeAgentOptional;
 exports.useSemanticBuilder = useSemanticBuilder;