@noodleseed/assistant 1.6.0 → 1.8.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 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
@@ -32,6 +33,11 @@ The full, always-current integration guide (access modes, session response contr
 troubleshooting) lives at <https://docs.noodleseed.dev/guides/embedded-assistant>. Authoring and deploying
 the server itself is `@noodleseed/one` (`npm install -g @noodleseed/one`).
 
+If your page sends a `Content-Security-Policy`, allow the Noodle service origin in `connect-src` (turns and
+event streams) **and** `frame-src` (app widgets render inside a hosted sandbox document served from the
+service origin, `endpoints.sandbox`, so your `script-src` can stay strict). Details are in the guide's
+"Content-Security-Policy on your page" section.
+
 ## Quick start
 
 Install the package in the customer web application with that application's existing package manager. For
@@ -137,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
 
@@ -205,8 +211,44 @@ 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.
+
+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";
@@ -224,19 +266,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
@@ -276,8 +333,9 @@ 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:
+fetch the `ui://` URI, inject `part.data.html`, or assign it to `srcdoc`. The standard element alone mounts
+the service-supplied document through its double-iframe MCP Apps host, and it also forwards the same detail
+as a DOM event:
 
 ```ts
 element.addEventListener("assistant-view-available", (event) => {

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

package/dist/{chunk-NSBPE2FW.js → chunk-5FUTL2UF.js}

@@ -1,10 +1,14 @@
 var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
 }) : x)(function(x) {
   if (typeof require !== "undefined") return require.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -12,6 +16,7 @@ var __export = (target, all) => {
 
 export {
   __require,
+  __commonJS,
   __export
 };
-//# sourceMappingURL=chunk-NSBPE2FW.js.map
+//# sourceMappingURL=chunk-5FUTL2UF.js.map