@page-speed/agent-everywhere 0.4.0 → 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,75 @@ 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
@@ -166,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
 

package/dist/index.cjs

@@ -7222,6 +7222,7 @@ function useSemanticBuilder({
   onGeneratedBlocks,
   onUndoRequest,
   buildWelcomeMessage,
+  seedWelcomeMessage = true,
   webSocketImpl
 }) {
   const [messages, setMessages] = React4.useState([]);
@@ -7255,6 +7256,7 @@ function useSemanticBuilder({
     resolveSocketUrlRef.current = resolveSocketUrl;
   }, [resolveSocketUrl]);
   React4.useEffect(() => {
+    if (!seedWelcomeMessage) return;
     const hasContentBrief = !!contentBrief;
     const content = buildWelcomeMessage?.({ pageName, hasContentBrief }) ?? (hasContentBrief ? `Connected to ${pageName}. The page brief is loaded and ready. Describe the page you want and I'll stream back layout guidance and design reasoning.` : `Connected to ${pageName}. There is no saved content brief yet, so I'll work from the current page structure and brand context.`);
     setMessages([
@@ -7265,7 +7267,7 @@ function useSemanticBuilder({
         createdAt: Date.now()
       }
     ]);
-  }, [contentBrief, pageName, pageSlug]);
+  }, [contentBrief, pageName, pageSlug, seedWelcomeMessage]);
   const handleEnvelope = React4.useCallback((envelope) => {
     switch (envelope.type) {
       case "connection_ready":
@@ -7477,6 +7479,14 @@ function useSemanticBuilder({
   const retry = React4.useCallback(() => {
     clientRef.current?.retry();
   }, []);
+  const reset = React4.useCallback(() => {
+    pendingHiddenRequestsRef.current = 0;
+    hiddenAssistantMessageIdsRef.current.clear();
+    clientRef.current?.close();
+    setConnectionState("idle");
+    setConnectionError(null);
+    setMessages([]);
+  }, []);
   const isConnected = connectionState === "ready" || connectionState === "streaming";
   const isStreaming = connectionState === "streaming";
   const statusLabel = React4.useMemo(() => {
@@ -7503,7 +7513,8 @@ function useSemanticBuilder({
     isConnected,
     isStreaming,
     sendMessage,
-    retry
+    retry,
+    reset
   };
 }
 var ScrollArea = React4__namespace.forwardRef(({ className, children, ...props }, ref) => /* @__PURE__ */ jsxRuntime.jsxs(
@@ -8007,6 +8018,54 @@ function FullBleedSurface({
     }
   );
 }
+function NativeSurface({
+  children,
+  input,
+  title,
+  subtitle,
+  icon,
+  headerActions,
+  suggestions,
+  footer,
+  isLoading = false,
+  autoScroll = true,
+  className,
+  contentClassName
+}) {
+  const scrollRef = React4.useRef(null);
+  React4.useEffect(() => {
+    if (autoScroll && scrollRef.current) {
+      scrollRef.current.scrollTop = scrollRef.current.scrollHeight;
+    }
+  }, [children, isLoading, autoScroll]);
+  const showHeader = !!title || !!headerActions || !!icon;
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: cn("flex h-full min-h-0 flex-col", className), children: [
+    showHeader && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center justify-between border-b px-4 py-3", children: [
+      /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center gap-2", children: [
+        icon,
+        (title || subtitle) && /* @__PURE__ */ jsxRuntime.jsxs("div", { children: [
+          title && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "font-medium text-sm", children: title }),
+          subtitle && /* @__PURE__ */ jsxRuntime.jsx("p", { className: "text-muted-foreground text-xs", children: subtitle })
+        ] })
+      ] }),
+      headerActions && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex items-center gap-2", children: headerActions })
+    ] }),
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        ref: scrollRef,
+        className: cn("min-h-0 flex-1 overflow-y-auto", contentClassName),
+        children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex flex-col gap-4 p-4", children: [
+          children,
+          isLoading && /* @__PURE__ */ jsxRuntime.jsx(TypingIndicator, {})
+        ] })
+      }
+    ),
+    suggestions && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "border-t px-4 py-2", children: suggestions }),
+    input,
+    footer && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "border-t px-4 py-1.5", children: footer })
+  ] });
+}
 function AgentSurface({
   mode,
   messages,
@@ -8130,6 +8189,21 @@ function AgentSurface({
           children: conversation
         }
       );
+    case "native":
+      return /* @__PURE__ */ jsxRuntime.jsx(
+        NativeSurface,
+        {
+          title,
+          subtitle,
+          icon,
+          headerActions,
+          input: resolvedInput,
+          suggestions,
+          isLoading,
+          className,
+          children: conversation
+        }
+      );
     case "panel":
     default:
       return /* @__PURE__ */ jsxRuntime.jsx(
@@ -8148,8 +8222,340 @@ function AgentSurface({
       );
   }
 }
+var NativeAgentContext = React4.createContext(
+  null
+);
+function useNativeAgent() {
+  const ctx = React4.useContext(NativeAgentContext);
+  if (!ctx) {
+    throw new Error(
+      "useNativeAgent must be used within a <NativeAgentProvider>."
+    );
+  }
+  return ctx;
+}
+function useNativeAgentOptional() {
+  return React4.useContext(NativeAgentContext);
+}
+var EMPTY_BLOCKS = [];
+var REASONING_STATUS = {
+  active: "active",
+  complete: "complete"
+};
+function toAgentMessage(message) {
+  const reasoning = message.thinking ? [
+    {
+      id: `${message.id}__thinking`,
+      label: "Thinking",
+      content: message.thinking,
+      status: message.streaming ? REASONING_STATUS.active : REASONING_STATUS.complete
+    }
+  ] : void 0;
+  return {
+    id: message.id,
+    role: message.role,
+    content: message.content,
+    timestamp: new Date(message.createdAt),
+    reasoning
+  };
+}
+function deriveStatus(connectionState) {
+  switch (connectionState) {
+    case "streaming":
+      return "busy";
+    case "ready":
+      return "online";
+    case "connecting":
+      return "away";
+    default:
+      return "offline";
+  }
+}
+function NativeAgentProvider({
+  children,
+  socketUrl,
+  resolveSocketUrl,
+  websiteId,
+  pageCategoryId,
+  pageName = "",
+  pageSlug,
+  blocks,
+  contentBrief,
+  onGeneratedBlocks,
+  webSocketImpl,
+  connectionStrategy = "lazy",
+  seedWelcomeMessage = false,
+  onError,
+  onActivate
+}) {
+  const [enabled, setEnabled] = React4.useState(connectionStrategy === "eager");
+  const [isActive, setIsActive] = React4.useState(false);
+  const [input, setInput] = React4.useState("");
+  const [pendingCount, setPendingCount] = React4.useState(0);
+  const [optimistic, setOptimistic] = React4.useState([]);
+  const blocksValue = blocks ?? EMPTY_BLOCKS;
+  const {
+    messages: builderMessages,
+    connectionState,
+    connectionError,
+    statusLabel,
+    isConnected,
+    isStreaming,
+    sendMessage,
+    retry,
+    reset: resetSession
+  } = useSemanticBuilder({
+    socketUrl,
+    resolveSocketUrl,
+    websiteId,
+    pageCategoryId,
+    pageName,
+    pageSlug,
+    blocks: blocksValue,
+    contentBrief,
+    enabled,
+    onGeneratedBlocks,
+    webSocketImpl,
+    seedWelcomeMessage
+  });
+  const pendingPromptsRef = React4.useRef([]);
+  const optimisticSeqRef = React4.useRef(0);
+  const onActivateRef = React4.useRef(onActivate);
+  const onErrorRef = React4.useRef(onError);
+  React4.useEffect(() => {
+    onActivateRef.current = onActivate;
+  }, [onActivate]);
+  React4.useEffect(() => {
+    onErrorRef.current = onError;
+  }, [onError]);
+  React4.useEffect(() => {
+    if (connectionError) onErrorRef.current?.(connectionError);
+  }, [connectionError]);
+  const markActive = React4.useCallback(() => {
+    setIsActive((prev) => {
+      if (!prev) onActivateRef.current?.();
+      return true;
+    });
+  }, []);
+  React4.useEffect(() => {
+    if (connectionState !== "ready" || pendingPromptsRef.current.length === 0) {
+      return;
+    }
+    const next = pendingPromptsRef.current.shift();
+    if (next === void 0) return;
+    setPendingCount(pendingPromptsRef.current.length);
+    setOptimistic((prev) => prev.slice(1));
+    void sendMessage(next).then((ok) => {
+      if (!ok) {
+        pendingPromptsRef.current.unshift(next);
+        setPendingCount(pendingPromptsRef.current.length);
+      }
+    });
+  }, [connectionState, pendingCount, sendMessage]);
+  const submit = React4.useCallback(
+    (content) => {
+      const text = (content ?? input).trim();
+      if (!text) return;
+      markActive();
+      setEnabled(true);
+      setInput("");
+      pendingPromptsRef.current.push(text);
+      setPendingCount(pendingPromptsRef.current.length);
+      const id = `native-pending-${optimisticSeqRef.current}`;
+      optimisticSeqRef.current += 1;
+      setOptimistic((prev) => [
+        ...prev,
+        { id, role: "user", content: text, timestamp: /* @__PURE__ */ new Date() }
+      ]);
+    },
+    [input, markActive]
+  );
+  const activate = React4.useCallback(() => {
+    markActive();
+    setEnabled(true);
+  }, [markActive]);
+  const reset = React4.useCallback(() => {
+    pendingPromptsRef.current = [];
+    setPendingCount(0);
+    setOptimistic([]);
+    setIsActive(false);
+    setInput("");
+    setEnabled(false);
+    resetSession();
+  }, [resetSession]);
+  const messages = React4.useMemo(
+    () => [...builderMessages.map(toAgentMessage), ...optimistic],
+    [builderMessages, optimistic]
+  );
+  const isResponding = isStreaming || pendingCount > 0 && !connectionError && connectionState !== "error" && connectionState !== "requires_shared_domain";
+  const status = deriveStatus(connectionState);
+  const value = React4.useMemo(
+    () => ({
+      messages,
+      isActive,
+      isConnected,
+      isResponding,
+      isStreaming,
+      connectionState,
+      statusLabel,
+      status,
+      error: connectionError,
+      input,
+      setInput,
+      submit,
+      activate,
+      reset,
+      retry
+    }),
+    [
+      messages,
+      isActive,
+      isConnected,
+      isResponding,
+      isStreaming,
+      connectionState,
+      statusLabel,
+      status,
+      connectionError,
+      input,
+      submit,
+      activate,
+      reset,
+      retry
+    ]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(NativeAgentContext.Provider, { value, children });
+}
+var noop = () => {
+};
+function warnDev(message) {
+  const env = globalThis.process?.env;
+  if (env && env.NODE_ENV !== "production") {
+    console.warn(`[AgentComposer] ${message}`);
+  }
+}
+function AgentComposer({
+  value: valueProp,
+  onChange,
+  onSubmit,
+  loading: loadingProp,
+  disabled: disabledProp,
+  placeholder = "Ask anything\u2026",
+  variant = "default",
+  bare = false,
+  suggestions,
+  footer,
+  leftActions,
+  rightActions,
+  autoFocus = false,
+  className,
+  inputClassName
+}) {
+  const ctx = useNativeAgentOptional();
+  const [draft, setDraft] = React4.useState("");
+  const propsControlEditing = valueProp !== void 0 || onChange !== void 0;
+  const value = propsControlEditing ? valueProp ?? "" : ctx ? ctx.input : draft;
+  const handleChange = propsControlEditing ? onChange ?? noop : ctx ? ctx.setInput : setDraft;
+  const loading = loadingProp ?? ctx?.isResponding ?? false;
+  const disabled = disabledProp ?? false;
+  const handleSubmit = React4.useCallback(() => {
+    if (onSubmit) {
+      onSubmit(value);
+      return;
+    }
+    if (!propsControlEditing && ctx) {
+      ctx.submit();
+      return;
+    }
+    warnDev(
+      "submit was ignored: provide `onSubmit`, or render inside a <NativeAgentProvider>."
+    );
+  }, [onSubmit, propsControlEditing, ctx, value]);
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "div",
+    {
+      className: cn(
+        !bare && "rounded-2xl border bg-background shadow-sm",
+        className
+      ),
+      children: [
+        suggestions && /* @__PURE__ */ jsxRuntime.jsx("div", { className: cn("px-3", bare ? "pb-2" : "pt-3"), children: suggestions }),
+        /* @__PURE__ */ jsxRuntime.jsx(
+          PromptInput,
+          {
+            value,
+            onChange: handleChange,
+            onSubmit: handleSubmit,
+            placeholder,
+            loading,
+            disabled,
+            variant,
+            autoFocus,
+            leftActions,
+            rightActions,
+            inputClassName
+          }
+        ),
+        footer && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "px-4 pb-2 text-muted-foreground text-xs", children: footer })
+      ]
+    }
+  );
+}
+var EMPTY_MESSAGES = [];
+function AgentConversation({
+  messages: messagesProp,
+  isLoading: isLoadingProp,
+  header,
+  emptyState,
+  showAvatars = true,
+  renderMessage,
+  onFeedback,
+  onConfirmAction,
+  autoScroll = true,
+  className,
+  contentClassName
+}) {
+  const ctx = useNativeAgentOptional();
+  const messages = React4.useMemo(
+    () => messagesProp ?? ctx?.messages ?? EMPTY_MESSAGES,
+    [messagesProp, ctx?.messages]
+  );
+  const isLoading = isLoadingProp ?? ctx?.isResponding ?? false;
+  const scrollRef = React4.useRef(null);
+  React4.useEffect(() => {
+    if (autoScroll && scrollRef.current) {
+      scrollRef.current.scrollTop = scrollRef.current.scrollHeight;
+    }
+  }, [messages, isLoading, autoScroll]);
+  const showEmptyState = messages.length === 0 && !isLoading && !!emptyState;
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: cn("flex h-full min-h-0 flex-col", className), children: [
+    header,
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        ref: scrollRef,
+        className: cn("min-h-0 flex-1 overflow-y-auto", contentClassName),
+        children: showEmptyState ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex h-full items-center justify-center p-6", children: emptyState }) : /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex flex-col gap-4 p-4", children: [
+          /* @__PURE__ */ jsxRuntime.jsx(
+            MessageList,
+            {
+              messages,
+              showAvatars,
+              renderMessage,
+              onFeedback,
+              onConfirmAction
+            }
+          ),
+          isLoading && /* @__PURE__ */ jsxRuntime.jsx(TypingIndicator, {})
+        ] })
+      }
+    )
+  ] });
+}
 
 exports.AgentAvatar = AgentAvatar;
+exports.AgentComposer = AgentComposer;
+exports.AgentConversation = AgentConversation;
 exports.AgentHandoff = AgentHandoff;
 exports.AgentProvider = AgentProvider;
 exports.AgentSurface = AgentSurface;
@@ -8196,6 +8602,8 @@ exports.MessageWithSteps = MessageWithSteps;
 exports.MetricsGrid = MetricsGrid;
 exports.MobileShell = MobileShell;
 exports.MultimodalInput = MultimodalInput;
+exports.NativeAgentProvider = NativeAgentProvider;
+exports.NativeSurface = NativeSurface;
 exports.OnboardingWizard = OnboardingWizard;
 exports.OptionCards = OptionCards;
 exports.OverlayModal = OverlayModal;
@@ -8264,6 +8672,8 @@ exports.useAgentBackend = useAgentBackend;
 exports.useAgentInput = useAgentInput;
 exports.useAgentLayout = useAgentLayout;
 exports.useAgentMessages = useAgentMessages;
+exports.useNativeAgent = useNativeAgent;
+exports.useNativeAgentOptional = useNativeAgentOptional;
 exports.useSemanticBuilder = useSemanticBuilder;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map