@noodleseed/assistant 1.7.0 → 1.9.0

package/README.md

@@ -2,12 +2,13 @@
 
 Customer-branded embedded assistant surfaces for Noodle Seed deployments.
 
-The package exports the canonical `<noodle-assistant>` Web Component, a React wrapper from
-`@noodleseed/assistant/react`, a DOM-free client from `@noodleseed/assistant/client`, and the backend-only
-`createAssistantSession` helper from `@noodleseed/assistant/server`. Light, dark, and automatic themes work
-without configuration; the component inherits the deployed MCP server's brand kit while slots, methods,
-events, and semantic CSS variables let a SaaS developer integrate it without depending on internal DOM
-selectors.
+The package exports the canonical `<noodle-assistant>` Web Component, a managed React wrapper and secure
+`NoodleAppView` MCP App renderer from `@noodleseed/assistant/react`, a renderer-free React hook from
+`@noodleseed/assistant/react/client`, a DOM-free client from `@noodleseed/assistant/client`, and the
+backend-only `createAssistantSession` helper from `@noodleseed/assistant/server`. Light, dark, and automatic
+themes work without configuration; the component inherits the deployed MCP server's brand kit while slots,
+methods, events, and semantic CSS variables let a SaaS developer integrate it without depending on internal
+DOM selectors.
 
 Never pass an embed client secret, model key, MCP token, or raw application session into the browser
 component. Exchange the already-authenticated user from the customer backend and return only the short-lived
@@ -142,10 +143,10 @@ markup-looking text stays text. `presentation.panel.radius` is a bounded panel-s
 not a second color or identity source. An HTTPS or packaged SVG referenced by `branding.logo`, `branding.mark`, or
 `branding.avatar` is a bounded asset, not inline renderer markup.
 
-If `presentation` is omitted, the quiet premium baseline remains: solid panel, soft elevation, subtle
-border/motion, medium brand-mark launcher without status or effect, undecorated header, pill composer with
-no leading icon and an arrow-up send icon, and bubble user/plain assistant messages at comfortable width.
-Partial objects merge with those defaults.
+If `presentation` is omitted, the rounded Halo-inspired baseline remains: a frosted glass panel with a 24px
+radius, soft elevation, subtle border/motion, medium brand-mark launcher without status or effect,
+undecorated header, pill composer and action controls, and rounded user bubbles with plain assistant messages
+at comfortable width. Partial objects merge with those defaults.
 
 ### Configure and deploy
 
@@ -210,8 +211,68 @@ import { NoodleAssistant } from "@noodleseed/assistant/react";
 <NoodleAssistant sessionEndpoint="/api/assistant/session" theme="auto" />;
 ```
 
-For a customer-owned renderer, subscribe to the same turn and interaction stream without registering a
-custom element or touching browser storage:
+Or keep the Noodle backend and own every rendered element in React:
+
+```tsx
+"use client";
+
+import { useNoodleAssistant } from "@noodleseed/assistant/react/client";
+import { YourChatUI } from "./your-chat-ui";
+
+export function CustomAssistant({ principalKey }: { principalKey: string }) {
+  const { client, messages, status, error } = useNoodleAssistant({
+    sessionEndpoint: "/api/assistant/session",
+    principalKey,
+  });
+
+  return (
+    <YourChatUI
+      messages={messages}
+      status={status}
+      error={error}
+      onSend={(text) => client.sendMessage(text)}
+      onStop={() => client.abort()}
+      onRespond={(id, response) => client.respond(id, response)}
+    />
+  );
+}
+```
+
+`useNoodleAssistant` owns client lifetime and React subscription only. It renders no Noodle markup,
+registers no custom element, and returns `{ client, messages, status, error }`. `client` remains the one
+command surface for messages, interactions, context, Apps requests, session resets, and aborts. A
+customer-owned renderer must present every interaction it supports, await or catch command promises, and
+preserve the typed part semantics; it must not invent user messages when an accepted, declined, or cancelled
+interaction streams a continuation. `principalKey` is browser-local and never sent to Noodle. Change it
+whenever the authenticated user or tenant changes so the hook aborts and clears the previous session and
+transcript.
+
+When the customer-owned transcript should render the linked MCP App itself, pass the typed `data-view`
+payload and the same client to the supported host component:
+
+```tsx
+import { NoodleAppView } from "@noodleseed/assistant/react";
+
+if (part.type === "data-view") {
+  return (
+    <NoodleAppView
+      key={`${part.data.id}:${part.data.resourceUri}`}
+      client={client}
+      view={part.data}
+      theme="dark"
+      onError={(failure) => reportAssistantError(failure)}
+    />
+  );
+}
+```
+
+`NoodleAppView` owns the double iframe and AppBridge. Its lifecycle identity is the supplied client plus
+`view.id` plus `view.resourceUri`: ordinary parent rerenders and fresh view/callback objects retain the
+iframe, while a semantic view replacement or unmount requests standard App teardown and closes the bridge.
+Do not also key an ancestor by the whole view object or a callback.
+
+Outside React, subscribe to the DOM-free AI SDK `UIMessage` state without registering a custom element or
+touching browser storage:
 
 ```ts
 import { createAssistantClient } from "@noodleseed/assistant/client";
@@ -229,19 +290,34 @@ assistant.updateModelContext({
   structuredContent: { widget: { name: "time-off", lifecycle: "mounted" } },
 });
 
-const unsubscribe = assistant.subscribe((event) => {
-  renderAssistantEvent(event);
-  if (event.event === "view_available") {
-    renderRegisteredView(event.data.resourceUri, event.data.result);
+const unsubscribe = assistant.subscribeChat((state) => {
+  renderUIMessageState(state);
+  for (const message of state.messages) {
+    for (const part of message.parts) {
+      if (part.type === "data-confirmation" && part.data.status === "pending") {
+        renderConfirmation(part.data, (response) =>
+          assistant.respond(part.data.id, response),
+        );
+      }
+      if (part.type === "data-view") {
+        renderRegisteredView(part.data.resourceUri, part.data.result);
+      }
+    }
   }
 });
 await assistant.sendMessage("Book next Thursday and Friday off");
-await assistant.respond("interaction_123", { action: "accept" });
-// Resolve one interaction once; alternatives are { action: 'decline' } or { action: 'cancel' }.
 
 unsubscribe();
 ```
 
+`subscribeChat` immediately emits a detached `{ messages, status, error? }` snapshot and then emits as the
+AI SDK `UIMessage.parts` change. Assistant text uses `text`; confirmations, structured input requests, tool
+results, and linked MCP Apps use `data-confirmation`, `data-input-request`, `data-tool-result`, and
+`data-view`. Interaction data moves through `pending`, `submitting`, `accepted`, `declined`, or `cancelled`.
+Use the lower-level `subscribe(...)` event stream only for transport and session lifecycle observations that
+do not belong in the transcript. The package uses the headless `ai` runtime only; React remains an optional
+peer isolated to the `/react` and `/react/client` entries.
+
 `clientContext` contains untrusted locale/timezone presentation hints and is evaluated for every turn.
 The client resolves a turn or interaction only after exactly one valid terminal `done` event followed by
 stream EOF. A truncated or malformed stream, duplicate `done`, or any frame after `done` is
@@ -279,10 +355,13 @@ leaves the same input interaction pending so the renderer can submit a corrected
 flow collects all elicited input before its first connector operation.
 
 A completed widget-linked tool emits typed `view_available` data with its call/interaction id, tool,
-`ui://` resource identity, optional title, and bounded/redacted public result. This is an availability
-signal, not proof of rendering. Map the identity to a component already trusted by your application; never
-fetch the `ui://` URI or inject its resource HTML into your page. The standard element does not render it,
-but forwards the same detail as a DOM event:
+`ui://` resource identity, optional title, bounded/redacted public result, and—on current services—the
+self-contained App document. This is an availability signal, not proof of rendering. A customer-owned React
+renderer either mounts the actual App with `NoodleAppView` or deliberately substitutes a component already
+trusted by the application and selected by `resourceUri`/tool. The JSON `result` is data for a native
+component; serializing it is not a rendering of the linked App. Never fetch the `ui://` URI, inject
+`part.data.html`, or assign it to `srcdoc` yourself. The standard element also forwards the same detail as a
+DOM event:
 
 ```ts
 element.addEventListener("assistant-view-available", (event) => {

package/dist/{appearance-DowzFJjh.d.cts → appearance-Cc-eqSbp.d.cts}

@@ -133,4 +133,4 @@ interface AssistantLabels {
     readonly sessionError: string;
 }
 
-export type { AssistantThemeMode as A, AssistantConfiguration as a };
+export type { AssistantConfiguration as A, AssistantThemeMode as a };

package/dist/{appearance-DowzFJjh.d.ts → appearance-Cc-eqSbp.d.ts}

@@ -133,4 +133,4 @@ interface AssistantLabels {
     readonly sessionError: string;
 }
 
-export type { AssistantThemeMode as A, AssistantConfiguration as a };
+export type { AssistantConfiguration as A, AssistantThemeMode as a };

package/dist/{chunk-UXPKSCID.js → chunk-3YYTUJPJ.js}

@@ -1,6 +1,6 @@
 import {
   __export
-} from "./chunk-NSBPE2FW.js";
+} from "./chunk-5FUTL2UF.js";
 
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 var external_exports = {};
@@ -14764,4 +14764,4 @@ export {
   external_exports,
   v4_default
 };
-//# sourceMappingURL=chunk-UXPKSCID.js.map
+//# sourceMappingURL=chunk-3YYTUJPJ.js.map