@noodleseed/assistant 1.2.0 → 1.4.0

package/README.md

@@ -15,10 +15,10 @@ assistant session.
 
 The model configuration and SaaS integration credentials have different owners:
 
-| Owner | Configuration | Destination |
-| --- | --- | --- |
-| Noodle deployment | `ASSISTANT_MODEL_BASE_URL`, `ASSISTANT_MODEL`, `ASSISTANT_MODEL_API_KEY` | Managed with `noodle variables set` / `noodle secrets set` |
-| Customer backend | `NOODLE_SERVICE_URL`, `NOODLE_ASSISTANT_CLIENT_ID`, `NOODLE_ASSISTANT_CLIENT_SECRET` | Backend environment or secret manager only |
+| Owner             | Configuration                                                                        | Destination                                                |
+| ----------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
+| Noodle deployment | `ASSISTANT_MODEL_BASE_URL`, `ASSISTANT_MODEL`, `ASSISTANT_MODEL_API_KEY`             | Managed with `noodle variables set` / `noodle secrets set` |
+| Customer backend  | `NOODLE_SERVICE_URL`, `NOODLE_ASSISTANT_CLIENT_ID`, `NOODLE_ASSISTANT_CLIENT_SECRET` | Backend environment or secret manager only                 |
 
 `allowedOrigins` accepts exact origins. Production origins must be HTTPS; plain HTTP is accepted only for
 loopback development origins such as `http://localhost:3000`. Local MCP authoring remains available without
@@ -41,6 +41,109 @@ example:
 npm install @noodleseed/assistant
 ```
 
+### Author `server.ts`
+
+Put customer identity and colors in the server's top-level `branding` option. Put only assistant-specific
+structure and treatment in `embeddedAssistant({ presentation })`:
+
+```ts
+import {
+  embeddedAssistant,
+  openAICompatible,
+  secret,
+  server,
+  tool,
+  variable,
+  z,
+} from "@noodleseed/one";
+
+export default server(
+  "acme_support",
+  {
+    title: "Acme Support",
+    version: "1.0.0",
+    branding: {
+      name: "Acme Assistant",
+      accent: "#5B4CF0",
+      surface: "#FFFFFF",
+      surfaceDark: "#15131A",
+      mark: { uri: "https://assets.acme.example/mark.svg", alt: "Acme" },
+      colorScheme: "auto",
+    },
+    assistant: embeddedAssistant({
+      model: openAICompatible({
+        baseUrl: variable("ASSISTANT_MODEL_BASE_URL"),
+        model: variable("ASSISTANT_MODEL"),
+        apiKey: secret("ASSISTANT_MODEL_API_KEY"),
+      }),
+      allowedOrigins: ["http://localhost:3000", "https://app.acme.example"],
+      layout: {
+        mode: "floating",
+        position: "bottom-right",
+        panelWidth: 520,
+        panelMinHeight: 540,
+        panelMaxHeight: 740,
+        edgeOffset: 24,
+      },
+      behavior: { showTimestamps: true },
+      labels: {
+        welcomeHeading: "How can Acme help?",
+        welcomeMessage: "Fast answers from the tools your team already uses.",
+        composerPlaceholder: "Message Acme Support…",
+        sessionReady: "Acme support is online",
+      },
+      presentation: {
+        panel: {
+          surface: "solid",
+          elevation: "dramatic",
+          border: "strong",
+          radius: 20,
+        },
+        launcher: {
+          icon: "chat",
+          size: "lg",
+          status: "session",
+          effect: "pulse",
+        },
+        header: {
+          mark: "status",
+          badge: { text: "Support online", tone: "success", indicator: true },
+        },
+        composer: {
+          leadingIcon: "brand-mark",
+          sendIcon: "paper-plane",
+          shape: "rounded",
+        },
+        messages: { userStyle: "accent", assistantStyle: "bubble" },
+      },
+    }),
+  },
+  [
+    tool("status", {
+      description: "Read the support service status.",
+      input: z.object({}),
+      output: z.object({ status: z.string() }),
+      fulfil: () => ({ status: "operational" }),
+    }),
+  ],
+);
+```
+
+`presentation` is a closed set of semantic primitives for the panel, launcher, header, composer, and
+messages. The Atlas-style product treatment above is the maximum supported customization level: it can
+change geometry, status decoration, controls, and message treatment without replacing the assistant's
+structure. It has no raw HTML, CSS, inline SVG, class-name, or callback field;
+markup-looking text stays text. `presentation.panel.radius` is a bounded panel-specific geometry override,
+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 complete Halo baseline remains: glass 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.
+
+### Configure and deploy
+
 Configure the model through Noodle managed config, validate, and deploy the assistant-enabled server before
 creating the embed client:
 
@@ -63,7 +166,7 @@ Move those values to the customer backend's secret manager without printing or c
 route can exchange the current signed-in user like this:
 
 ```ts
-import { createAssistantSession } from '@noodleseed/assistant/server';
+import { createAssistantSession } from "@noodleseed/assistant/server";
 
 export async function POST(request: Request) {
   const user = await requireCurrentUser(request);
@@ -84,17 +187,20 @@ export async function POST(request: Request) {
 Then add the framework-neutral element:
 
 ```ts
-import '@noodleseed/assistant';
+import "@noodleseed/assistant";
 ```
 
 ```html
-<noodle-assistant session-endpoint="/api/assistant/session" theme="auto"></noodle-assistant>
+<noodle-assistant
+  session-endpoint="/api/assistant/session"
+  theme="auto"
+></noodle-assistant>
 ```
 
 Or use React:
 
 ```tsx
-import { NoodleAssistant } from '@noodleseed/assistant/react';
+import { NoodleAssistant } from "@noodleseed/assistant/react";
 
 <NoodleAssistant sessionEndpoint="/api/assistant/session" theme="auto" />;
 ```
@@ -103,10 +209,10 @@ For a customer-owned renderer, subscribe to the same turn and interaction stream
 custom element or touching browser storage:
 
 ```ts
-import { createAssistantClient } from '@noodleseed/assistant/client';
+import { createAssistantClient } from "@noodleseed/assistant/client";
 
 const assistant = createAssistantClient({
-  sessionEndpoint: '/api/assistant/session',
+  sessionEndpoint: "/api/assistant/session",
   clientContext: () => ({
     locale: navigator.language,
     timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
@@ -114,18 +220,18 @@ const assistant = createAssistantClient({
 });
 
 assistant.updateModelContext({
-  content: [{ type: 'text', text: 'The time-off form is mounted.' }],
-  structuredContent: { widget: { name: 'time-off', lifecycle: 'mounted' } },
+  content: [{ type: "text", text: "The time-off form is mounted." }],
+  structuredContent: { widget: { name: "time-off", lifecycle: "mounted" } },
 });
 
 const unsubscribe = assistant.subscribe((event) => {
   renderAssistantEvent(event);
-  if (event.event === 'view_available') {
+  if (event.event === "view_available") {
     renderRegisteredView(event.data.resourceUri, event.data.result);
   }
 });
-await assistant.sendMessage('Book next Thursday and Friday off');
-await assistant.respond('interaction_123', { action: 'accept' });
+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();
@@ -173,7 +279,7 @@ fetch the `ui://` URI or inject its resource HTML into your page. The standard e
 but forwards the same detail as a DOM event:
 
 ```ts
-element.addEventListener('assistant-view-available', (event) => {
+element.addEventListener("assistant-view-available", (event) => {
   renderRegisteredView(event.detail.resourceUri, event.detail.result);
 });
 ```
@@ -186,15 +292,18 @@ replay across sessions. React applications may observe recovery and structured f
 <NoodleAssistant
   sessionEndpoint="/api/assistant/session"
   onSessionExpired={() => reportAssistantRecovery()}
-  onError={({ code, status, retryable }) => reportAssistantError({ code, status, retryable })}
-/>;
+  onError={({ code, status, retryable }) =>
+    reportAssistantError({ code, status, retryable })
+  }
+/>
 ```
 
 `createAssistantSession` returns the opaque token, expiry, resolved non-secret configuration, and explicit
 turn/interaction endpoint URLs. Forward that response unchanged to the component or headless client.
 
-The MCP server's top-level `branding` block provides the shared identity and theme for widgets and the
-assistant. Set semantic CSS variables only for application-level integration overrides:
+The MCP server's top-level `branding` block is the sole deployment source for identity and colors shared by
+widgets and the assistant. Set public semantic CSS variables only for application-level integration
+overrides:
 
 ```css
 noodle-assistant {
@@ -204,6 +313,13 @@ noodle-assistant {
 }
 ```
 
+For each matching region or token, precedence is host-provided slot content or a public CSS custom property,
+then compiled server `presentation`/`branding`, then Halo defaults. The public slots are `launcher-icon`,
+`header-leading`, `header-actions`, `empty-state`, `composer-leading`, `composer-trailing`, and
+`conversation-footer`; slotted host DOM replaces the renderer fallback for that region. Slots are a trusted
+embedding-page integration API, not a way to put HTML or callbacks in deployment configuration. Internal
+shadow-DOM selectors and classes are not public API.
+
 Server branding controls customer name, themed logo/mark/avatar assets, semantic light/dark colors, density,
 radius, typography, and automatic theme. `embeddedAssistant(...)` controls floating/inline/drawer layout,
 position and dimensions, mobile and launcher/header/avatar/timestamp behavior, visible labels, suggested

package/dist/{appearance-KDbtkt2G.d.cts → appearance-BLO7kFYB.d.cts}

@@ -1,6 +1,38 @@
 type AssistantThemeMode = 'auto' | 'light' | 'dark';
 type AssistantLayoutMode = 'floating' | 'inline' | 'drawer';
 type AssistantPosition = 'bottom-left' | 'bottom-right';
+type AssistantPresentationTone = 'neutral' | 'success' | 'warning' | 'danger';
+interface AssistantPresentationConfiguration {
+    readonly panel?: {
+        readonly surface?: 'solid' | 'glass';
+        readonly elevation?: 'soft' | 'dramatic';
+        readonly border?: 'subtle' | 'strong';
+        readonly radius?: number;
+    };
+    readonly launcher?: {
+        readonly icon?: 'brand-mark' | 'chat' | 'none';
+        readonly size?: 'md' | 'lg';
+        readonly status?: 'none' | 'session';
+        readonly effect?: 'none' | 'pulse';
+    };
+    readonly header?: {
+        readonly mark?: 'none' | 'brand-mark' | 'status';
+        readonly badge?: {
+            readonly text: string;
+            readonly tone?: AssistantPresentationTone;
+            readonly indicator?: boolean;
+        };
+    };
+    readonly composer?: {
+        readonly leadingIcon?: 'none' | 'brand-mark';
+        readonly sendIcon?: 'arrow-up' | 'paper-plane';
+        readonly shape?: 'rounded' | 'pill';
+    };
+    readonly messages?: {
+        readonly userStyle?: 'bubble' | 'accent';
+        readonly assistantStyle?: 'plain' | 'bubble';
+    };
+}
 interface AssistantConfiguration {
     readonly branding?: {
         readonly name?: string;
@@ -50,6 +82,7 @@ interface AssistantUiConfiguration {
         readonly panelWidth?: number;
         readonly panelMinHeight?: number;
         readonly panelMaxHeight?: number;
+        readonly edgeOffset?: number;
         readonly zIndex?: number;
         readonly density?: 'compact' | 'comfortable';
         readonly mobileFullscreen?: boolean;
@@ -64,6 +97,7 @@ interface AssistantUiConfiguration {
         readonly showTimestamps?: boolean;
     };
     readonly labels?: Partial<AssistantLabels>;
+    readonly presentation?: AssistantPresentationConfiguration;
     readonly suggestedPrompts?: readonly string[];
     readonly privacyUrl?: string;
     readonly termsUrl?: string;
@@ -74,6 +108,7 @@ interface AssistantLabels {
     readonly welcomeHeading: string;
     readonly welcomeMessage: string;
     readonly composerPlaceholder: string;
+    readonly thinking: string;
     readonly send: string;
     readonly stop: string;
     readonly close: string;
@@ -83,6 +118,10 @@ interface AssistantLabels {
     readonly retry: string;
     readonly unavailable: string;
     readonly sessionExpired: string;
+    readonly sessionIdle: string;
+    readonly sessionLoading: string;
+    readonly sessionReady: string;
+    readonly sessionError: string;
 }
 
 export type { AssistantThemeMode as A, AssistantConfiguration as a };

package/dist/{appearance-KDbtkt2G.d.ts → appearance-BLO7kFYB.d.ts}

@@ -1,6 +1,38 @@
 type AssistantThemeMode = 'auto' | 'light' | 'dark';
 type AssistantLayoutMode = 'floating' | 'inline' | 'drawer';
 type AssistantPosition = 'bottom-left' | 'bottom-right';
+type AssistantPresentationTone = 'neutral' | 'success' | 'warning' | 'danger';
+interface AssistantPresentationConfiguration {
+    readonly panel?: {
+        readonly surface?: 'solid' | 'glass';
+        readonly elevation?: 'soft' | 'dramatic';
+        readonly border?: 'subtle' | 'strong';
+        readonly radius?: number;
+    };
+    readonly launcher?: {
+        readonly icon?: 'brand-mark' | 'chat' | 'none';
+        readonly size?: 'md' | 'lg';
+        readonly status?: 'none' | 'session';
+        readonly effect?: 'none' | 'pulse';
+    };
+    readonly header?: {
+        readonly mark?: 'none' | 'brand-mark' | 'status';
+        readonly badge?: {
+            readonly text: string;
+            readonly tone?: AssistantPresentationTone;
+            readonly indicator?: boolean;
+        };
+    };
+    readonly composer?: {
+        readonly leadingIcon?: 'none' | 'brand-mark';
+        readonly sendIcon?: 'arrow-up' | 'paper-plane';
+        readonly shape?: 'rounded' | 'pill';
+    };
+    readonly messages?: {
+        readonly userStyle?: 'bubble' | 'accent';
+        readonly assistantStyle?: 'plain' | 'bubble';
+    };
+}
 interface AssistantConfiguration {
     readonly branding?: {
         readonly name?: string;
@@ -50,6 +82,7 @@ interface AssistantUiConfiguration {
         readonly panelWidth?: number;
         readonly panelMinHeight?: number;
         readonly panelMaxHeight?: number;
+        readonly edgeOffset?: number;
         readonly zIndex?: number;
         readonly density?: 'compact' | 'comfortable';
         readonly mobileFullscreen?: boolean;
@@ -64,6 +97,7 @@ interface AssistantUiConfiguration {
         readonly showTimestamps?: boolean;
     };
     readonly labels?: Partial<AssistantLabels>;
+    readonly presentation?: AssistantPresentationConfiguration;
     readonly suggestedPrompts?: readonly string[];
     readonly privacyUrl?: string;
     readonly termsUrl?: string;
@@ -74,6 +108,7 @@ interface AssistantLabels {
     readonly welcomeHeading: string;
     readonly welcomeMessage: string;
     readonly composerPlaceholder: string;
+    readonly thinking: string;
     readonly send: string;
     readonly stop: string;
     readonly close: string;
@@ -83,6 +118,10 @@ interface AssistantLabels {
     readonly retry: string;
     readonly unavailable: string;
     readonly sessionExpired: string;
+    readonly sessionIdle: string;
+    readonly sessionLoading: string;
+    readonly sessionReady: string;
+    readonly sessionError: string;
 }
 
 export type { AssistantThemeMode as A, AssistantConfiguration as a };