@runtypelabs/persona 3.24.0 → 3.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.24.0",
+  "version": "3.26.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",

package/src/client.test.ts

@@ -1633,6 +1633,55 @@ describe('AgentWidgetClient - partId Text/Tool Interleaving', () => {
     expect(seqTool).toBeLessThan(seq1);
   });
 
+  it('should not emit a whitespace-only assistant bubble before a leading tool call', async () => {
+    const events: AgentWidgetEvent[] = [];
+
+    const encoder = new TextEncoder();
+    global.fetch = vi.fn().mockImplementation(async () => {
+      const stream = new ReadableStream({
+        start(controller) {
+          const e = (eventType: string, data: Record<string, unknown>) =>
+            controller.enqueue(encoder.encode(`event: ${eventType}\ndata: ${JSON.stringify({ type: eventType, ...data })}\n\n`));
+
+          e('flow_start', { flowId: 'f1', flowName: 'Test', totalSteps: 1 });
+          e('step_start', { id: 's1', name: 'Prompt', stepType: 'prompt', index: 1, totalSteps: 1 });
+          // Tool UI is the first meaningful output. Some providers still emit
+          // newline-only text lifecycle events around the tool boundary; those
+          // must not become an empty assistant message bubble.
+          e('tool_start', { toolId: 'tc_1', name: 'add_to_cart', toolType: 'local', sequenceIndex: 4 });
+          e('text_start', { partId: 'text_0', messageId: 'msg_s1', seq: 1 });
+          e('step_delta', { id: 's1', text: '\n', partId: 'text_0', messageId: 'msg_s1', seq: 2 });
+          e('text_end', { partId: 'text_0', messageId: 'msg_s1', seq: 3 });
+          e('tool_complete', { toolId: 'tc_1', name: 'add_to_cart', success: true, completedAt: new Date().toISOString(), executionTime: 20, sequenceIndex: 5 });
+          e('flow_complete', { success: true });
+          controller.close();
+        }
+      });
+      return { ok: true, body: stream };
+    });
+
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+    await client.dispatch(
+      { messages: [{ id: 'usr_1', role: 'user', content: 'Add to cart', createdAt: new Date().toISOString() }] },
+      (event) => events.push(event)
+    );
+
+    const messageEvents = events.filter(e => e.type === 'message');
+    const messagesById = new Map<string, AgentWidgetMessage>();
+    for (const event of messageEvents) {
+      if (event.type === 'message') messagesById.set(event.message.id, event.message);
+    }
+
+    const allMessages = Array.from(messagesById.values());
+    const assistantTexts = allMessages.filter(m => m.role === 'assistant' && !m.variant);
+    const toolMsgs = allMessages.filter(m => m.variant === 'tool');
+
+    expect(assistantTexts).toHaveLength(0);
+    expect(toolMsgs).toHaveLength(1);
+    expect(toolMsgs[0].toolCall?.name).toBe('add_to_cart');
+    expect(toolMsgs[0].toolCall?.status).toBe('complete');
+  });
+
   it('should not split when partId is absent (backward compatible)', async () => {
     const events: AgentWidgetEvent[] = [];
 

package/src/client.ts

@@ -1297,7 +1297,25 @@ export class AgentWidgetClient {
       };
     };
 
+    const shouldEmitMessage = (msg: AgentWidgetMessage): boolean => {
+      if (msg.role !== "assistant" || msg.variant) return true;
+
+      const hasContentParts =
+        Array.isArray(msg.contentParts) && msg.contentParts.length > 0;
+      const hasRawContent =
+        typeof msg.rawContent === "string" && msg.rawContent.trim() !== "";
+      const hasVisibleText =
+        typeof msg.content === "string" && msg.content.trim() !== "";
+
+      // Do not surface assistant text bubbles that only contain whitespace.
+      // Some providers emit newline-only text parts around a leading tool call;
+      // rendering those as normal messages creates an empty bubble above the
+      // tool card. Keep media/component/stop-reason messages renderable.
+      return hasVisibleText || hasContentParts || hasRawContent || Boolean(msg.stopReason);
+    };
+
     const emitMessage = (msg: AgentWidgetMessage) => {
+      if (!shouldEmitMessage(msg)) return;
       onEvent({
         type: "message",
         message: cloneMessage(msg)

package/src/index-core.ts

@@ -0,0 +1,406 @@
+import {
+  initAgentWidget as initAgentWidgetFn,
+  type AgentWidgetInitHandle
+} from "./runtime/init";
+
+export type {
+  AgentWidgetConfig,
+  AgentWidgetFeatureFlags,
+  AgentWidgetArtifactsFeature,
+  AgentWidgetArtifactsLayoutConfig,
+  PersonaArtifactKind,
+  PersonaArtifactRecord,
+  PersonaArtifactManualUpsert,
+  ArtifactConfigPayload,
+  AgentWidgetInitOptions,
+  AgentWidgetMessage,
+  AgentWidgetLauncherConfig,
+  AgentWidgetDockConfig,
+  AgentWidgetEvent,
+  AgentWidgetStreamParser,
+  AgentWidgetStreamParserResult,
+  AgentWidgetRequestPayload,
+  // Context provider types (e.g. for config.contextProviders)
+  AgentWidgetContextProvider,
+  AgentWidgetContextProviderContext,
+  AgentWidgetCustomFetch,
+  AgentWidgetSSEEventParser,
+  AgentWidgetSSEEventResult,
+  AgentWidgetHeadersFunction,
+  // Multi-modal content types
+  TextContentPart,
+  ImageContentPart,
+  ContentPart,
+  MessageContent,
+  // Attachment config type
+  AgentWidgetAttachmentsConfig,
+  AgentWidgetComposerConfig,
+  // Layout types
+  AgentWidgetLayoutConfig,
+  AgentWidgetHeaderLayoutConfig,
+  AgentWidgetMessageLayoutConfig,
+  AgentWidgetAvatarConfig,
+  AgentWidgetTimestampConfig,
+  WidgetLayoutSlot,
+  SlotRenderer,
+  SlotRenderContext,
+  HeaderRenderContext,
+  MessageRenderContext,
+  // Markdown types
+  AgentWidgetMarkdownConfig,
+  AgentWidgetMarkdownOptions,
+  AgentWidgetMarkdownRendererOverrides,
+  // Message actions types
+  AgentWidgetMessageActionsConfig,
+  AgentWidgetMessageFeedback,
+  // Client token types
+  ClientSession,
+  ClientInitResponse,
+  ClientChatRequest,
+  ClientFeedbackRequest,
+  ClientFeedbackType,
+  // Message injection types
+  InjectMessageOptions,
+  InjectAssistantMessageOptions,
+  InjectUserMessageOptions,
+  InjectSystemMessageOptions,
+  InjectComponentDirectiveOptions,
+  // Loading indicator types
+  LoadingIndicatorRenderContext,
+  AgentWidgetLoadingIndicatorConfig,
+  // Idle indicator types
+  IdleIndicatorRenderContext,
+  // Agent execution types
+  AgentConfig,
+  AgentLoopConfig,
+  AgentToolsConfig,
+  AgentRequestOptions,
+  AgentExecutionState,
+  AgentMessageMetadata,
+  AgentWidgetAgentRequestPayload,
+  // Approval types
+  AgentWidgetApproval,
+  AgentWidgetApprovalConfig,
+  // WebMCP — page-discovered tool consumption
+  AgentWidgetWebMcpConfig,
+  ClientToolDefinition,
+  WebMcpConfirmHandler,
+  WebMcpConfirmInfo,
+  WebMcpToolResult,
+  // Event stream types
+  SSEEventRecord,
+  EventStreamConfig,
+  EventStreamBadgeColor,
+  EventStreamViewRenderContext,
+  EventStreamRowRenderContext,
+  EventStreamToolbarRenderContext,
+  EventStreamPayloadRenderContext,
+  // Controller event map
+  AgentWidgetControllerEventMap,
+  // Ask-user-question (built-in answer-pill sheet) types
+  AskUserQuestionPayload,
+  AskUserQuestionPrompt,
+  AskUserQuestionOption,
+  AgentWidgetAskUserQuestionFeature,
+  AgentWidgetAskUserQuestionStyles
+} from "./types";
+
+export {
+  ASK_USER_QUESTION_TOOL_NAME,
+  createAskUserQuestionBubble,
+  ensureAskUserQuestionSheet,
+  removeAskUserQuestionSheet,
+  isAskUserQuestionMessage,
+  parseAskUserQuestionPayload
+} from "./components/ask-user-question-bubble";
+
+export { initAgentWidgetFn as initAgentWidget };
+export {
+  createWidgetHostLayout,
+  type WidgetHostLayout,
+  type WidgetHostLayoutMode
+} from "./runtime/host-layout";
+export {
+  createAgentExperience,
+  type AgentWidgetController
+} from "./ui";
+export {
+  AgentWidgetSession,
+  type AgentWidgetSessionStatus
+} from "./session";
+export { AgentWidgetClient } from "./client";
+export type { SSEEventCallback } from "./client";
+export {
+  WebMcpBridge,
+  WEBMCP_TOOL_PREFIX,
+  isWebMcpToolName,
+  stripWebMcpPrefix
+} from "./webmcp-bridge";
+export { createLocalStorageAdapter } from "./utils/storage";
+export {
+  createActionManager,
+  defaultActionHandlers,
+  defaultJsonActionParser
+} from "./utils/actions";
+export {
+  markdownPostprocessor,
+  escapeHtml,
+  directivePostprocessor,
+  createMarkdownProcessor,
+  createMarkdownProcessorFromConfig,
+  createDirectivePostprocessor
+} from "./postprocessors";
+export type { MarkdownProcessorOptions } from "./postprocessors";
+export {
+  createDefaultSanitizer,
+  resolveSanitizer
+} from "./utils/sanitize";
+export type { SanitizeFunction } from "./utils/sanitize";
+export {
+  createPlainTextParser,
+  createJsonStreamParser,
+  createFlexibleJsonStreamParser,
+  createRegexJsonParser,
+  createXmlParser
+} from "./utils/formatting";
+export {
+  // Multi-modal content utilities
+  normalizeContent,
+  getDisplayText,
+  hasImages,
+  getImageParts,
+  createTextPart,
+  createImagePart,
+  fileToImagePart,
+  validateImageFile
+} from "./utils/content";
+export {
+  collectEnrichedPageContext,
+  formatEnrichedContext,
+  generateStableSelector,
+  defaultParseRules
+} from "./utils/dom-context";
+export type {
+  EnrichedPageElement,
+  DomContextOptions,
+  DomContextMode,
+  ParseOptionsConfig,
+  ParseRule,
+  RuleScoringContext,
+  FormatEnrichedContextOptions
+} from "./utils/dom-context";
+export {
+  AttachmentManager,
+  type PendingAttachment,
+  type AttachmentManagerConfig
+} from "./utils/attachment-manager";
+export {
+  generateMessageId,
+  generateUserMessageId,
+  generateAssistantMessageId
+} from "./utils/message-id";
+export { isDockedMountMode, resolveDockConfig } from "./utils/dock";
+// NOTE: `generateCodeSnippet` (dev/config-tool helper) is intentionally NOT
+// re-exported here so it stays out of the IIFE/CDN bundle (index-global.ts
+// re-exports from this module). It is re-added to the npm barrel in `index.ts`.
+export { VERSION } from "./version";
+export type { AgentWidgetInitHandle };
+
+// Plugin system exports
+export type { AgentWidgetPlugin } from "./plugins/types";
+export { pluginRegistry } from "./plugins/registry";
+
+// Stream animation plugin API — lets consumers register custom animations
+// that match the built-in surface (typewriter, pop-bubble) and subpath
+// modules (letter-rise, word-fade, wipe, glyph-cycle).
+export {
+  registerStreamAnimationPlugin,
+  unregisterStreamAnimationPlugin,
+  listRegisteredStreamAnimations,
+} from "./utils/stream-animation";
+export type {
+  StreamAnimationPlugin,
+  StreamAnimationContext,
+  AgentWidgetStreamAnimationBuffer,
+  AgentWidgetStreamAnimationBuiltinType,
+  AgentWidgetStreamAnimationType,
+  AgentWidgetStreamAnimationFeature,
+  AgentWidgetStreamAnimationPlaceholder,
+} from "./types";
+
+// Action system types — needed to type the `actionHandlers` / `actionParsers`
+// config options and to author custom handlers/parsers.
+export type {
+  AgentWidgetActionHandler,
+  AgentWidgetActionHandlerResult,
+  AgentWidgetActionParser,
+  AgentWidgetParsedAction,
+  AgentWidgetActionContext,
+  AgentWidgetActionEventPayload,
+} from "./types";
+
+// Dropdown utility exports
+export { createDropdownMenu } from "./utils/dropdown";
+export type { DropdownMenuItem, CreateDropdownOptions, DropdownMenuHandle } from "./utils/dropdown";
+
+// Icon utility exports
+export { renderLucideIcon } from "./utils/icons";
+export type { IconName } from "./utils/icons";
+
+// Button utility exports
+export { createIconButton, createLabelButton, createToggleGroup, createComboButton } from "./utils/buttons";
+export type {
+  CreateIconButtonOptions,
+  CreateLabelButtonOptions,
+  CreateToggleGroupOptions,
+  ToggleGroupItem,
+  ToggleGroupHandle,
+  CreateComboButtonOptions,
+  ComboButtonHandle
+} from "./utils/buttons";
+
+// NOTE: `createDemoCarousel` (demo-only component) is intentionally NOT
+// re-exported here so it stays out of the IIFE/CDN bundle. It is re-added to
+// the npm barrel in `index.ts`.
+
+// Theme system exports
+export {
+  createTheme,
+  resolveTokens,
+  themeToCssVariables,
+  applyThemeVariables,
+  getActiveTheme,
+  getColorScheme,
+  detectColorScheme,
+  createThemeObserver
+} from "./utils/theme";
+export {
+  DEFAULT_PALETTE,
+  DEFAULT_SEMANTIC,
+  DEFAULT_COMPONENTS,
+  validateTheme,
+  THEME_ZONES
+} from "./utils/tokens";
+export type { ThemeZone } from "./utils/tokens";
+export {
+  accessibilityPlugin,
+  animationsPlugin,
+  brandPlugin,
+  reducedMotionPlugin,
+  highContrastPlugin,
+  createPlugin
+} from "./utils/plugins";
+export type {
+  DeepPartial,
+  PersonaTheme,
+  PersonaThemePlugin,
+  CreateThemeOptions,
+  TokenReference,
+  ColorShade,
+  ColorPalette,
+  SpacingScale,
+  TypographyScale,
+  ShadowScale,
+  BorderScale,
+  RadiusScale,
+  SemanticColors,
+  SemanticSpacing,
+  SemanticTypography,
+  ComponentTokens,
+  ArtifactToolbarTokens,
+  ArtifactTabTokens,
+  ArtifactPaneTokens,
+  IconButtonTokens,
+  LabelButtonTokens,
+  ToggleGroupTokens,
+  ThemeValidationResult,
+  ThemeValidationError
+} from "./types/theme";
+
+// Component system exports
+export { componentRegistry } from "./components/registry";
+export type { ComponentRenderer, ComponentContext } from "./components/registry";
+export {
+  createComponentStreamParser,
+  isComponentDirectiveType
+} from "./utils/component-parser";
+export type { ComponentDirective } from "./utils/component-parser";
+export {
+  renderComponentDirective,
+  createComponentMiddleware,
+  hasComponentDirective,
+  extractComponentDirectiveFromMessage
+} from "./utils/component-middleware";
+
+// Default configuration exports
+export {
+  DEFAULT_WIDGET_CONFIG,
+  DEFAULT_FLOATING_LAUNCHER_MAX_WIDTH,
+  DEFAULT_FLOATING_LAUNCHER_WIDTH,
+  mergeWithDefaults
+} from "./defaults";
+export {
+  PRESETS,
+  getPreset,
+  PRESET_SHOP,
+  PRESET_MINIMAL,
+  PRESET_FULLSCREEN
+} from "./presets";
+export type { WidgetPreset } from "./presets";
+
+// Layout system exports
+export {
+  buildHeader,
+  buildComposer,
+  attachHeaderToContainer
+} from "./components/panel";
+export type {
+  HeaderElements,
+  HeaderBuildContext,
+  ComposerElements,
+  ComposerBuildContext
+} from "./components/panel";
+export {
+  headerLayouts,
+  getHeaderLayout,
+  buildHeaderWithLayout,
+  buildDefaultHeader,
+  buildMinimalHeader
+} from "./components/header-layouts";
+export type {
+  HeaderLayoutContext,
+  HeaderLayoutRenderer
+} from "./components/header-layouts";
+export {
+  createStandardBubble,
+  createBubbleWithLayout,
+  createTypingIndicator,
+  createMessageActions,
+  renderLoadingIndicatorWithFallback
+} from "./components/message-bubble";
+export type {
+  MessageTransform,
+  MessageActionCallbacks,
+  LoadingIndicatorRenderer,
+  CreateStandardBubbleOptions
+} from "./components/message-bubble";
+export {
+  createCSATFeedback,
+  createNPSFeedback
+} from "./components/feedback";
+export type { CSATFeedbackOptions, NPSFeedbackOptions } from "./components/feedback";
+
+// Voice module exports
+export {
+  createVoiceProvider,
+  createBestAvailableVoiceProvider,
+  isVoiceSupported
+} from "./voice";
+export type {
+  VoiceProvider,
+  VoiceResult,
+  VoiceStatus,
+  VoiceConfig
+} from "./types";
+
+export default initAgentWidgetFn;

package/src/index-global.ts

@@ -12,8 +12,10 @@
  * modules so bundlers can tree-shake them.
  */
 
-// Re-export the full public API.
-export * from "./index";
+// Re-export the full public API — from `index-core` (NOT `index`) so the
+// dev-only helpers (`generateCodeSnippet`, `createDemoCarousel`) stay out of the
+// CDN/IIFE bundle. npm consumers still get them via the `index.ts` barrel.
+export * from "./index-core";
 
 // Side-import the remaining subpath animations so they're available to
 // script-tag consumers without an explicit import. (`letter-rise` and