pika-shared 1.4.1 → 1.4.2

package/dist/types/chatbot/webcomp-types.d.mts

@@ -1,14 +1,19 @@
 import { UploadStatus } from '../upload-types.mjs';
-import { ShowToastFn, ChatUser, RecordOrUndef, UserAwsCredentials, ShareSessionState, UserPrefs, ChatAppMode, CustomDataUiRepresentation, ChatAppOverridableFeatures, TagDefinition, TagDefinitionWidget, ChatSession, UserDataOverrideSettings, ChatMessageForRendering, ChatApp } from './chatbot-types.mjs';
+import { ShowToastFn, ChatUser, RecordOrUndef, UserAwsCredentials, WidgetRenderingContextType, ShareSessionState, UserPrefs, ChatAppMode, IUserWidgetDataStoreState, CustomDataUiRepresentation, ChatAppOverridableFeatures, TagDefinition, TagDefinitionWidget, ChatSession, UserDataOverrideSettings, ChatMessageForRendering, ChatApp, InvokeAgentAsComponentOptions, WidgetMetadata, WidgetAction } from './chatbot-types.mjs';
 import '@aws-sdk/client-bedrock-agent-runtime';
 import '@aws-sdk/client-bedrock-agentcore';
 
+/**
+ * Note!!! The interfaces in this file are meant to expose public functionality to the web component authors.
+ * They are not meant to be exhaustive or complete.
+ */
+
 type SidebarState = any;
 type Snippet = any;
 /** Declare global event map for pika context request */
 declare global {
     interface HTMLElementEventMap {
-        'pika-context-request': PikaWCContextRequestEvent;
+        'pika-wc-context-request': PikaWCContextRequestEvent;
     }
 }
 interface IIdentityState {
@@ -25,12 +30,126 @@ interface IAppState {
     readonly identity: IIdentityState;
     readonly isMobile: boolean;
 }
+/**
+ * Widget Metadata API - scoped to a specific widget instance.
+ * Returned by getWidgetMetadataAPI() and bound to the widget's instanceId.
+ *
+ * This API allows widgets to register and update their display metadata (title and actions)
+ * which the parent app uses to render context-appropriate chrome.
+ *
+ * @example
+ * ```js
+ * const ctx = await getPikaContext($host());
+ * const metadata = ctx.chatAppState.getWidgetMetadataAPI('weather', 'favorite-cities', ctx.instanceId, ctx.renderingContext);
+ *
+ * metadata.setMetadata({
+ *   title: 'Favorite Cities',
+ *   actions: [
+ *     { id: 'refresh', title: 'Refresh', iconSvg: '<svg>...</svg>', callback: () => refresh() }
+ *   ]
+ * });
+ * ```
+ */
+interface IWidgetMetadataAPI {
+    /**
+     * Register or update complete metadata (title and actions).
+     * Replaces any previously registered metadata for this widget instance.
+     *
+     * @param metadata - The metadata to register
+     *
+     * @example
+     * ```js
+     * metadata.setMetadata({
+     *   title: 'Weather Comparison',
+     *   actions: [
+     *     { id: 'refresh', title: 'Refresh', iconSvg: '<svg>...</svg>', callback: () => refresh() },
+     *     { id: 'settings', title: 'Settings', iconSvg: '<svg>...</svg>', callback: () => showSettings() }
+     *   ]
+     * });
+     * ```
+     */
+    setMetadata(metadata: WidgetMetadata): void;
+    /**
+     * Update just the widget title without affecting actions.
+     *
+     * @param title - The new title
+     *
+     * @example
+     * ```js
+     * metadata.updateTitle(`Temperature Trend - ${newCity}`);
+     * ```
+     */
+    updateTitle(title: string): void;
+    /**
+     * Update a specific action's properties (e.g., disable/enable).
+     * Only updates the properties provided in `updates`.
+     *
+     * @param actionId - The ID of the action to update
+     * @param updates - Partial properties to update (cannot change id or callback)
+     *
+     * @example
+     * ```js
+     * // Disable the refresh button during loading
+     * metadata.updateAction('refresh', { disabled: true });
+     *
+     * // Re-enable it after loading
+     * metadata.updateAction('refresh', { disabled: false });
+     * ```
+     */
+    updateAction(actionId: string, updates: Partial<Omit<WidgetAction, 'id' | 'callback'>>): void;
+    /**
+     * Add a new action button dynamically.
+     *
+     * @param action - The action to add
+     *
+     * @example
+     * ```js
+     * if (userHasPremium) {
+     *   metadata.addAction({
+     *     id: 'export',
+     *     title: 'Export data',
+     *     iconSvg: '<svg>...</svg>',
+     *     callback: () => exportData()
+     *   });
+     * }
+     * ```
+     */
+    addAction(action: WidgetAction): void;
+    /**
+     * Remove an action button.
+     *
+     * @param actionId - The ID of the action to remove
+     *
+     * @example
+     * ```js
+     * metadata.removeAction('export');
+     * ```
+     */
+    removeAction(actionId: string): void;
+    /**
+     * Set the loading status for the widget.
+     *
+     * @param loading - Whether the widget is loading
+     * @param loadingMsg - The message to display while loading
+     *
+     * @example
+     * ```js
+     * metadata.setLoadingStatus(true, 'Loading...');
+     * ```
+     */
+    setLoadingStatus(loading: boolean, loadingMsg?: string): void;
+}
 interface IChatAppState {
     readonly entityFeatureEnabled: boolean;
     readonly shareCurrentSessionState: ShareSessionState;
     readonly showToast: ShowToastFn;
     readonly userPrefs: IUserPrefsState;
     readonly mode: ChatAppMode;
+    /**
+     * Get component-specific storage scoped to this component (scope.tag) and current user.
+     * Max 400KB per component.
+     */
+    getUserWidgetDataStoreState(scope: string, tag: string): IUserWidgetDataStoreState;
     readonly customDataUiRepresentation: CustomDataUiRepresentation | undefined;
     readonly features: ChatAppOverridableFeatures;
     readonly tagDefs: TagDefinition<TagDefinitionWidget>[];
@@ -65,6 +184,98 @@ interface IChatAppState {
     getMessageByMessageId(messageId: string): ChatMessageForRendering | undefined;
     uploadFiles(files: File[]): Promise<void>;
     initializeData(): Promise<void>;
+    renderTag(tagId: string, context: 'spotlight' | 'inline' | 'dialog' | 'canvas', data?: Record<string, any>): Promise<void>;
+    closeCanvas(): void;
+    closeDialog(): void;
+    /**
+     * Invoke the agent directly from a web component using the 'chat-app-component' invocation mode.
+     * This allows components to make out-of-band requests to the LLM without creating user sessions.
+     *
+     * The component must have a tag definition with `componentAgentInstructionsMd` that
+     * includes instructions for the specified `instructionName`.
+     *
+     * @param scope - The scope of the tag definition (e.g., 'weather')
+     * @param tag - The tag name (e.g., 'favorite-cities')
+     * @param instructionName - The key in the tag definition's componentAgentInstructionsMd
+     * @param userMessage - The message/query to send to the agent
+     * @param options - Optional streaming callbacks and configuration
+     * @returns Promise that resolves to the parsed JSON response from the agent
+     * @throws Error if the request fails or response cannot be parsed
+     *
+     * @example
+     * Simple usage:
+     * ```typescript
+     * const weatherData = await chatAppState.invokeAgentAsComponent<{ temperature: number, condition: string }>(
+     *   'weather',
+     *   'favorite-cities',
+     *   'get-weather',
+     *   'Get current weather for San Francisco'
+     * );
+     * ```
+     *
+     * With streaming callbacks:
+     * ```typescript
+     * const data = await chatAppState.invokeAgentAsComponent<WeatherData>(
+     *   'weather',
+     *   'favorite-cities',
+     *   'get-weather',
+     *   'Get weather for NYC',
+     *   {
+     *     onThinking: (text) => console.log('Thinking:', text),
+     *     onToolCall: (call) => console.log('Calling tool:', call.name)
+     *   }
+     * );
+     * ```
+     */
+    invokeAgentAsComponent<T = any>(scope: string, tag: string, instructionName: string, userMessage: string, options?: InvokeAgentAsComponentOptions): Promise<T>;
+    /**
+     * Get a scoped metadata API for registering widget title and actions.
+     * Call this once during widget initialization to get an API bound to this widget instance.
+     *
+     * The metadata you register will be used by the parent app to render context-appropriate chrome:
+     * - **Spotlight**: Small title bar overlay with icon + title + action menu
+     * - **Canvas**: Full title bar with all action buttons + close
+     * - **Dialog**: Title in header, actions as buttons in footer
+     * - **Inline**: No chrome rendered (widget manages own UI)
+     *
+     * **IMPORTANT**: You MUST pass instanceId and renderingContext from the PikaWCContext.
+     * These values are automatically set during component injection.
+     *
+     * @param scope - Widget scope (e.g., 'weather', 'pika')
+     * @param tag - Widget tag (e.g., 'favorite-cities')
+     * @param instanceId - Unique instance ID from context.instanceId (set during injection)
+     * @param renderingContext - Rendering context from context.renderingContext (set during injection)
+     * @returns Scoped API for this widget instance
+     *
+     * @example
+     * Correct usage (always pass context values):
+     * ```js
+     * const ctx = await getPikaContext($host());
+     * const metadata = ctx.chatAppState.getWidgetMetadataAPI(
+     *   'weather',
+     *   'favorite-cities',
+     *   ctx.instanceId,  // REQUIRED - set during injection
+     *   ctx.renderingContext       // REQUIRED - set during injection
+     * );
+     *
+     * metadata.setMetadata({
+     *   title: 'Favorite Cities',
+     *   actions: [
+     *     {
+     *       id: 'refresh',
+     *       title: 'Refresh weather data',
+     *       lucideIconName: 'refresh-cw',  // MUST be lowercase kebab-case
+     *       callback: async () => {
+     *         loading = true;
+     *         await fetchWeatherData();
+     *         loading = false;
+     *       }
+     *     }
+     *   ]
+     * });
+     * ```
+     */
+    getWidgetMetadataAPI(scope: string, tag: string, instanceId: string, renderingContext: WidgetRenderingContextType): IWidgetMetadataAPI;
 }
 interface IUserPrefsState {
     readonly initialized: boolean;
@@ -92,10 +303,18 @@ interface IUploadInstance {
  */
 interface PikaWCContext {
     appState: IAppState;
-    context: 'spotlight' | 'inline' | 'dialog' | 'canvas';
+    renderingContext: WidgetRenderingContextType;
     chatAppState: IChatAppState;
     chatAppId: string;
+    /**
+     * Unique instance ID for this component instance.
+     * Set by injectChatAppWebComponent() and used by getWidgetMetadataAPI().
+     */
+    instanceId: string;
+    /** Arbitrary data to be passed to the widget. */
+    dataForWidget: Record<string, any>;
 }
+type PikaWCContextWithoutInstanceId = Omit<PikaWCContext, 'instanceId'>;
 type PikaWCContextRequestCallbackFn = (contextRequest: PikaWCContext) => void;
 interface PikaWCContextRequestDetail {
     callback: PikaWCContextRequestCallbackFn;
@@ -104,4 +323,4 @@ interface PikaWCContextRequestEvent extends CustomEvent<PikaWCContextRequestDeta
     detail: PikaWCContextRequestDetail;
 }
 
-export type { IAppState, IChatAppState, IIdentityState, IUploadInstance, IUserPrefsState, PikaWCContext, PikaWCContextRequestCallbackFn, PikaWCContextRequestDetail, PikaWCContextRequestEvent, SidebarState, Snippet };
+export type { IAppState, IChatAppState, IIdentityState, IUploadInstance, IUserPrefsState, IWidgetMetadataAPI, PikaWCContext, PikaWCContextRequestCallbackFn, PikaWCContextRequestDetail, PikaWCContextRequestEvent, PikaWCContextWithoutInstanceId, SidebarState, Snippet };

package/dist/types/chatbot/webcomp-types.d.ts

@@ -1,14 +1,19 @@
 import { UploadStatus } from '../upload-types.js';
-import { ShowToastFn, ChatUser, RecordOrUndef, UserAwsCredentials, ShareSessionState, UserPrefs, ChatAppMode, CustomDataUiRepresentation, ChatAppOverridableFeatures, TagDefinition, TagDefinitionWidget, ChatSession, UserDataOverrideSettings, ChatMessageForRendering, ChatApp } from './chatbot-types.js';
+import { ShowToastFn, ChatUser, RecordOrUndef, UserAwsCredentials, WidgetRenderingContextType, ShareSessionState, UserPrefs, ChatAppMode, IUserWidgetDataStoreState, CustomDataUiRepresentation, ChatAppOverridableFeatures, TagDefinition, TagDefinitionWidget, ChatSession, UserDataOverrideSettings, ChatMessageForRendering, ChatApp, InvokeAgentAsComponentOptions, WidgetMetadata, WidgetAction } from './chatbot-types.js';
 import '@aws-sdk/client-bedrock-agent-runtime';
 import '@aws-sdk/client-bedrock-agentcore';
 
+/**
+ * Note!!! The interfaces in this file are meant to expose public functionality to the web component authors.
+ * They are not meant to be exhaustive or complete.
+ */
+
 type SidebarState = any;
 type Snippet = any;
 /** Declare global event map for pika context request */
 declare global {
     interface HTMLElementEventMap {
-        'pika-context-request': PikaWCContextRequestEvent;
+        'pika-wc-context-request': PikaWCContextRequestEvent;
     }
 }
 interface IIdentityState {
@@ -25,12 +30,126 @@ interface IAppState {
     readonly identity: IIdentityState;
     readonly isMobile: boolean;
 }
+/**
+ * Widget Metadata API - scoped to a specific widget instance.
+ * Returned by getWidgetMetadataAPI() and bound to the widget's instanceId.
+ *
+ * This API allows widgets to register and update their display metadata (title and actions)
+ * which the parent app uses to render context-appropriate chrome.
+ *
+ * @example
+ * ```js
+ * const ctx = await getPikaContext($host());
+ * const metadata = ctx.chatAppState.getWidgetMetadataAPI('weather', 'favorite-cities', ctx.instanceId, ctx.renderingContext);
+ *
+ * metadata.setMetadata({
+ *   title: 'Favorite Cities',
+ *   actions: [
+ *     { id: 'refresh', title: 'Refresh', iconSvg: '<svg>...</svg>', callback: () => refresh() }
+ *   ]
+ * });
+ * ```
+ */
+interface IWidgetMetadataAPI {
+    /**
+     * Register or update complete metadata (title and actions).
+     * Replaces any previously registered metadata for this widget instance.
+     *
+     * @param metadata - The metadata to register
+     *
+     * @example
+     * ```js
+     * metadata.setMetadata({
+     *   title: 'Weather Comparison',
+     *   actions: [
+     *     { id: 'refresh', title: 'Refresh', iconSvg: '<svg>...</svg>', callback: () => refresh() },
+     *     { id: 'settings', title: 'Settings', iconSvg: '<svg>...</svg>', callback: () => showSettings() }
+     *   ]
+     * });
+     * ```
+     */
+    setMetadata(metadata: WidgetMetadata): void;
+    /**
+     * Update just the widget title without affecting actions.
+     *
+     * @param title - The new title
+     *
+     * @example
+     * ```js
+     * metadata.updateTitle(`Temperature Trend - ${newCity}`);
+     * ```
+     */
+    updateTitle(title: string): void;
+    /**
+     * Update a specific action's properties (e.g., disable/enable).
+     * Only updates the properties provided in `updates`.
+     *
+     * @param actionId - The ID of the action to update
+     * @param updates - Partial properties to update (cannot change id or callback)
+     *
+     * @example
+     * ```js
+     * // Disable the refresh button during loading
+     * metadata.updateAction('refresh', { disabled: true });
+     *
+     * // Re-enable it after loading
+     * metadata.updateAction('refresh', { disabled: false });
+     * ```
+     */
+    updateAction(actionId: string, updates: Partial<Omit<WidgetAction, 'id' | 'callback'>>): void;
+    /**
+     * Add a new action button dynamically.
+     *
+     * @param action - The action to add
+     *
+     * @example
+     * ```js
+     * if (userHasPremium) {
+     *   metadata.addAction({
+     *     id: 'export',
+     *     title: 'Export data',
+     *     iconSvg: '<svg>...</svg>',
+     *     callback: () => exportData()
+     *   });
+     * }
+     * ```
+     */
+    addAction(action: WidgetAction): void;
+    /**
+     * Remove an action button.
+     *
+     * @param actionId - The ID of the action to remove
+     *
+     * @example
+     * ```js
+     * metadata.removeAction('export');
+     * ```
+     */
+    removeAction(actionId: string): void;
+    /**
+     * Set the loading status for the widget.
+     *
+     * @param loading - Whether the widget is loading
+     * @param loadingMsg - The message to display while loading
+     *
+     * @example
+     * ```js
+     * metadata.setLoadingStatus(true, 'Loading...');
+     * ```
+     */
+    setLoadingStatus(loading: boolean, loadingMsg?: string): void;
+}
 interface IChatAppState {
     readonly entityFeatureEnabled: boolean;
     readonly shareCurrentSessionState: ShareSessionState;
     readonly showToast: ShowToastFn;
     readonly userPrefs: IUserPrefsState;
     readonly mode: ChatAppMode;
+    /**
+     * Get component-specific storage scoped to this component (scope.tag) and current user.
+     * Max 400KB per component.
+     */
+    getUserWidgetDataStoreState(scope: string, tag: string): IUserWidgetDataStoreState;
     readonly customDataUiRepresentation: CustomDataUiRepresentation | undefined;
     readonly features: ChatAppOverridableFeatures;
     readonly tagDefs: TagDefinition<TagDefinitionWidget>[];
@@ -65,6 +184,98 @@ interface IChatAppState {
     getMessageByMessageId(messageId: string): ChatMessageForRendering | undefined;
     uploadFiles(files: File[]): Promise<void>;
     initializeData(): Promise<void>;
+    renderTag(tagId: string, context: 'spotlight' | 'inline' | 'dialog' | 'canvas', data?: Record<string, any>): Promise<void>;
+    closeCanvas(): void;
+    closeDialog(): void;
+    /**
+     * Invoke the agent directly from a web component using the 'chat-app-component' invocation mode.
+     * This allows components to make out-of-band requests to the LLM without creating user sessions.
+     *
+     * The component must have a tag definition with `componentAgentInstructionsMd` that
+     * includes instructions for the specified `instructionName`.
+     *
+     * @param scope - The scope of the tag definition (e.g., 'weather')
+     * @param tag - The tag name (e.g., 'favorite-cities')
+     * @param instructionName - The key in the tag definition's componentAgentInstructionsMd
+     * @param userMessage - The message/query to send to the agent
+     * @param options - Optional streaming callbacks and configuration
+     * @returns Promise that resolves to the parsed JSON response from the agent
+     * @throws Error if the request fails or response cannot be parsed
+     *
+     * @example
+     * Simple usage:
+     * ```typescript
+     * const weatherData = await chatAppState.invokeAgentAsComponent<{ temperature: number, condition: string }>(
+     *   'weather',
+     *   'favorite-cities',
+     *   'get-weather',
+     *   'Get current weather for San Francisco'
+     * );
+     * ```
+     *
+     * With streaming callbacks:
+     * ```typescript
+     * const data = await chatAppState.invokeAgentAsComponent<WeatherData>(
+     *   'weather',
+     *   'favorite-cities',
+     *   'get-weather',
+     *   'Get weather for NYC',
+     *   {
+     *     onThinking: (text) => console.log('Thinking:', text),
+     *     onToolCall: (call) => console.log('Calling tool:', call.name)
+     *   }
+     * );
+     * ```
+     */
+    invokeAgentAsComponent<T = any>(scope: string, tag: string, instructionName: string, userMessage: string, options?: InvokeAgentAsComponentOptions): Promise<T>;
+    /**
+     * Get a scoped metadata API for registering widget title and actions.
+     * Call this once during widget initialization to get an API bound to this widget instance.
+     *
+     * The metadata you register will be used by the parent app to render context-appropriate chrome:
+     * - **Spotlight**: Small title bar overlay with icon + title + action menu
+     * - **Canvas**: Full title bar with all action buttons + close
+     * - **Dialog**: Title in header, actions as buttons in footer
+     * - **Inline**: No chrome rendered (widget manages own UI)
+     *
+     * **IMPORTANT**: You MUST pass instanceId and renderingContext from the PikaWCContext.
+     * These values are automatically set during component injection.
+     *
+     * @param scope - Widget scope (e.g., 'weather', 'pika')
+     * @param tag - Widget tag (e.g., 'favorite-cities')
+     * @param instanceId - Unique instance ID from context.instanceId (set during injection)
+     * @param renderingContext - Rendering context from context.renderingContext (set during injection)
+     * @returns Scoped API for this widget instance
+     *
+     * @example
+     * Correct usage (always pass context values):
+     * ```js
+     * const ctx = await getPikaContext($host());
+     * const metadata = ctx.chatAppState.getWidgetMetadataAPI(
+     *   'weather',
+     *   'favorite-cities',
+     *   ctx.instanceId,  // REQUIRED - set during injection
+     *   ctx.renderingContext       // REQUIRED - set during injection
+     * );
+     *
+     * metadata.setMetadata({
+     *   title: 'Favorite Cities',
+     *   actions: [
+     *     {
+     *       id: 'refresh',
+     *       title: 'Refresh weather data',
+     *       lucideIconName: 'refresh-cw',  // MUST be lowercase kebab-case
+     *       callback: async () => {
+     *         loading = true;
+     *         await fetchWeatherData();
+     *         loading = false;
+     *       }
+     *     }
+     *   ]
+     * });
+     * ```
+     */
+    getWidgetMetadataAPI(scope: string, tag: string, instanceId: string, renderingContext: WidgetRenderingContextType): IWidgetMetadataAPI;
 }
 interface IUserPrefsState {
     readonly initialized: boolean;
@@ -92,10 +303,18 @@ interface IUploadInstance {
  */
 interface PikaWCContext {
     appState: IAppState;
-    context: 'spotlight' | 'inline' | 'dialog' | 'canvas';
+    renderingContext: WidgetRenderingContextType;
     chatAppState: IChatAppState;
     chatAppId: string;
+    /**
+     * Unique instance ID for this component instance.
+     * Set by injectChatAppWebComponent() and used by getWidgetMetadataAPI().
+     */
+    instanceId: string;
+    /** Arbitrary data to be passed to the widget. */
+    dataForWidget: Record<string, any>;
 }
+type PikaWCContextWithoutInstanceId = Omit<PikaWCContext, 'instanceId'>;
 type PikaWCContextRequestCallbackFn = (contextRequest: PikaWCContext) => void;
 interface PikaWCContextRequestDetail {
     callback: PikaWCContextRequestCallbackFn;
@@ -104,4 +323,4 @@ interface PikaWCContextRequestEvent extends CustomEvent<PikaWCContextRequestDeta
     detail: PikaWCContextRequestDetail;
 }
 
-export type { IAppState, IChatAppState, IIdentityState, IUploadInstance, IUserPrefsState, PikaWCContext, PikaWCContextRequestCallbackFn, PikaWCContextRequestDetail, PikaWCContextRequestEvent, SidebarState, Snippet };
+export type { IAppState, IChatAppState, IIdentityState, IUploadInstance, IUserPrefsState, IWidgetMetadataAPI, PikaWCContext, PikaWCContextRequestCallbackFn, PikaWCContextRequestDetail, PikaWCContextRequestEvent, PikaWCContextWithoutInstanceId, SidebarState, Snippet };

package/dist/util/icon-utils.d.mts

@@ -0,0 +1,12 @@
+/**
+ * This is useful when you need to dynamically retrieve the SVG for an icon.
+ * It will cache the icon SVG so that it doesn't need to be fetched multiple times.
+ * It will also return the same SVG for the same icon name and collection.
+ *
+ * @param iconName - The name of the icon to retrieve.
+ * @param collection - The collection of the icon to retrieve. Today we only support lucide.
+ * @returns The SVG for the icon.
+ */
+declare function getIconSvg(iconName: string, collection?: string): Promise<string>;
+
+export { getIconSvg };

package/dist/util/icon-utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * This is useful when you need to dynamically retrieve the SVG for an icon.
+ * It will cache the icon SVG so that it doesn't need to be fetched multiple times.
+ * It will also return the same SVG for the same icon name and collection.
+ *
+ * @param iconName - The name of the icon to retrieve.
+ * @param collection - The collection of the icon to retrieve. Today we only support lucide.
+ * @returns The SVG for the icon.
+ */
+declare function getIconSvg(iconName: string, collection?: string): Promise<string>;
+
+export { getIconSvg };

package/dist/util/icon-utils.js

@@ -0,0 +1,26 @@
+'use strict';
+
+// src/util/icon-utils.ts
+var iconCache = {};
+async function getIconSvg(iconName, collection = "lucide") {
+  if (collection !== "lucide") {
+    throw new Error(`Unsupported collection: ${collection}`);
+  }
+  if (iconName !== iconName.toLowerCase()) {
+    throw new Error(`Icon name must be all lower case and hyphen based: ${iconName}`);
+  }
+  const iconKey = `${collection}:${iconName}`;
+  if (iconCache[iconKey]) {
+    return iconCache[iconKey];
+  }
+  const lucideIconUrl = `https://cdn.jsdelivr.net/npm/lucide-static@0/icons/${iconName}.svg`;
+  const response = await fetch(lucideIconUrl);
+  let iconSvg = await response.text();
+  iconSvg = iconSvg.replace(/width="\d+" height="\d+"/, 'width="24" height="24"');
+  iconCache[iconKey] = iconSvg;
+  return iconSvg;
+}
+
+exports.getIconSvg = getIconSvg;
+//# sourceMappingURL=icon-utils.js.map
+//# sourceMappingURL=icon-utils.js.map

package/dist/util/icon-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/util/icon-utils.ts"],"names":[],"mappings":";;;AAAA,IAAM,YAAoC,EAAC;AAW3C,eAAsB,UAAA,CAAW,QAAA,EAAkB,UAAA,GAAa,QAAA,EAA2B;AAEvF,EAAA,IAAI,eAAe,QAAA,EAAU;AACzB,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,wBAAA,EAA2B,UAAU,CAAA,CAAE,CAAA;AAAA,EAC3D;AAIA,EAAA,IAAI,QAAA,KAAa,QAAA,CAAS,WAAA,EAAY,EAAG;AACrC,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,mDAAA,EAAsD,QAAQ,CAAA,CAAE,CAAA;AAAA,EACpF;AAEA,EAAA,MAAM,OAAA,GAAU,CAAA,EAAG,UAAU,CAAA,CAAA,EAAI,QAAQ,CAAA,CAAA;AACzC,EAAA,IAAI,SAAA,CAAU,OAAO,CAAA,EAAG;AACpB,IAAA,OAAO,UAAU,OAAO,CAAA;AAAA,EAC5B;AAEA,EAAA,MAAM,aAAA,GAAgB,sDAAsD,QAAQ,CAAA,IAAA,CAAA;AAGpF,EAAA,MAAM,QAAA,GAAW,MAAM,KAAA,CAAM,aAAa,CAAA;AAC1C,EAAA,IAAI,OAAA,GAAU,MAAM,QAAA,CAAS,IAAA,EAAK;AAGlC,EAAA,OAAA,GAAU,OAAA,CAAQ,OAAA,CAAQ,0BAAA,EAA4B,wBAAwB,CAAA;AAE9E,EAAA,SAAA,CAAU,OAAO,CAAA,GAAI,OAAA;AACrB,EAAA,OAAO,OAAA;AACX","file":"icon-utils.js","sourcesContent":["const iconCache: Record<string, string> = {};\n\n/**\n * This is useful when you need to dynamically retrieve the SVG for an icon.\n * It will cache the icon SVG so that it doesn't need to be fetched multiple times.\n * It will also return the same SVG for the same icon name and collection.\n *\n * @param iconName - The name of the icon to retrieve.\n * @param collection - The collection of the icon to retrieve. Today we only support lucide.\n * @returns The SVG for the icon.\n */\nexport async function getIconSvg(iconName: string, collection = 'lucide'): Promise<string> {\n    // Today we only support lucide\n    if (collection !== 'lucide') {\n        throw new Error(`Unsupported collection: ${collection}`);\n    }\n\n    // Lucide icon names must be lower case and they are all hyphen based, not camel case\n    // If the icon name isn't all lower case then throw an error so the developer knows to use the correct icon name\n    if (iconName !== iconName.toLowerCase()) {\n        throw new Error(`Icon name must be all lower case and hyphen based: ${iconName}`);\n    }\n\n    const iconKey = `${collection}:${iconName}`;\n    if (iconCache[iconKey]) {\n        return iconCache[iconKey];\n    }\n\n    const lucideIconUrl = `https://cdn.jsdelivr.net/npm/lucide-static@0/icons/${iconName}.svg`;\n\n    // Use fetch to get the icon SVG\n    const response = await fetch(lucideIconUrl);\n    let iconSvg = await response.text();\n\n    // Replace the width and height attributes with width=\"24\" and height=\"24\"\n    iconSvg = iconSvg.replace(/width=\"\\d+\" height=\"\\d+\"/, 'width=\"24\" height=\"24\"');\n\n    iconCache[iconKey] = iconSvg;\n    return iconSvg;\n}\n"]}

package/dist/util/icon-utils.mjs

@@ -0,0 +1,24 @@
+// src/util/icon-utils.ts
+var iconCache = {};
+async function getIconSvg(iconName, collection = "lucide") {
+  if (collection !== "lucide") {
+    throw new Error(`Unsupported collection: ${collection}`);
+  }
+  if (iconName !== iconName.toLowerCase()) {
+    throw new Error(`Icon name must be all lower case and hyphen based: ${iconName}`);
+  }
+  const iconKey = `${collection}:${iconName}`;
+  if (iconCache[iconKey]) {
+    return iconCache[iconKey];
+  }
+  const lucideIconUrl = `https://cdn.jsdelivr.net/npm/lucide-static@0/icons/${iconName}.svg`;
+  const response = await fetch(lucideIconUrl);
+  let iconSvg = await response.text();
+  iconSvg = iconSvg.replace(/width="\d+" height="\d+"/, 'width="24" height="24"');
+  iconCache[iconKey] = iconSvg;
+  return iconSvg;
+}
+
+export { getIconSvg };
+//# sourceMappingURL=icon-utils.mjs.map
+//# sourceMappingURL=icon-utils.mjs.map

package/dist/util/icon-utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/util/icon-utils.ts"],"names":[],"mappings":";AAAA,IAAM,YAAoC,EAAC;AAW3C,eAAsB,UAAA,CAAW,QAAA,EAAkB,UAAA,GAAa,QAAA,EAA2B;AAEvF,EAAA,IAAI,eAAe,QAAA,EAAU;AACzB,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,wBAAA,EAA2B,UAAU,CAAA,CAAE,CAAA;AAAA,EAC3D;AAIA,EAAA,IAAI,QAAA,KAAa,QAAA,CAAS,WAAA,EAAY,EAAG;AACrC,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,mDAAA,EAAsD,QAAQ,CAAA,CAAE,CAAA;AAAA,EACpF;AAEA,EAAA,MAAM,OAAA,GAAU,CAAA,EAAG,UAAU,CAAA,CAAA,EAAI,QAAQ,CAAA,CAAA;AACzC,EAAA,IAAI,SAAA,CAAU,OAAO,CAAA,EAAG;AACpB,IAAA,OAAO,UAAU,OAAO,CAAA;AAAA,EAC5B;AAEA,EAAA,MAAM,aAAA,GAAgB,sDAAsD,QAAQ,CAAA,IAAA,CAAA;AAGpF,EAAA,MAAM,QAAA,GAAW,MAAM,KAAA,CAAM,aAAa,CAAA;AAC1C,EAAA,IAAI,OAAA,GAAU,MAAM,QAAA,CAAS,IAAA,EAAK;AAGlC,EAAA,OAAA,GAAU,OAAA,CAAQ,OAAA,CAAQ,0BAAA,EAA4B,wBAAwB,CAAA;AAE9E,EAAA,SAAA,CAAU,OAAO,CAAA,GAAI,OAAA;AACrB,EAAA,OAAO,OAAA;AACX","file":"icon-utils.mjs","sourcesContent":["const iconCache: Record<string, string> = {};\n\n/**\n * This is useful when you need to dynamically retrieve the SVG for an icon.\n * It will cache the icon SVG so that it doesn't need to be fetched multiple times.\n * It will also return the same SVG for the same icon name and collection.\n *\n * @param iconName - The name of the icon to retrieve.\n * @param collection - The collection of the icon to retrieve. Today we only support lucide.\n * @returns The SVG for the icon.\n */\nexport async function getIconSvg(iconName: string, collection = 'lucide'): Promise<string> {\n    // Today we only support lucide\n    if (collection !== 'lucide') {\n        throw new Error(`Unsupported collection: ${collection}`);\n    }\n\n    // Lucide icon names must be lower case and they are all hyphen based, not camel case\n    // If the icon name isn't all lower case then throw an error so the developer knows to use the correct icon name\n    if (iconName !== iconName.toLowerCase()) {\n        throw new Error(`Icon name must be all lower case and hyphen based: ${iconName}`);\n    }\n\n    const iconKey = `${collection}:${iconName}`;\n    if (iconCache[iconKey]) {\n        return iconCache[iconKey];\n    }\n\n    const lucideIconUrl = `https://cdn.jsdelivr.net/npm/lucide-static@0/icons/${iconName}.svg`;\n\n    // Use fetch to get the icon SVG\n    const response = await fetch(lucideIconUrl);\n    let iconSvg = await response.text();\n\n    // Replace the width and height attributes with width=\"24\" and height=\"24\"\n    iconSvg = iconSvg.replace(/width=\"\\d+\" height=\"\\d+\"/, 'width=\"24\" height=\"24\"');\n\n    iconCache[iconKey] = iconSvg;\n    return iconSvg;\n}\n"]}

package/dist/util/instruction-assistance-utils.d.mts

@@ -35,6 +35,33 @@ declare function generateInstructionAssistanceContent(instructionAssistanceConfi
  * Apply instruction assistance to the base prompt using placeholder replacement
  */
 declare function applyInstructionAssistance(basePrompt: string, instructionContent: InstructionAssistanceConfig): string;
+/**
+ * IMPORTANT!!!!!!!!!!!!!!!!!!!!!!
+ *
+ * See header at top of file for important notes.
+ *
+ * Generate component-specific instruction content for direct component invocations
+ *
+ * @param tagDefinition - The tag definition with component invocation instructions
+ * @param componentAgentInstructionName - The name of the instruction set to use
+ * @param instructionAssistanceConfig - Optional instruction assistance config for placeholder replacement
+ * @param agentInstructionFeature - Optional agent instruction feature to control which placeholders are replaced
+ * @returns The component instruction content or undefined if not found
+ */
+declare function generateComponentInstructionContent(tagDefinition: TagDefinition<TagDefinitionWidget>, componentAgentInstructionName: string, instructionAssistanceConfig?: InstructionAssistanceConfig, agentInstructionFeature?: AgentInstructionChatAppOverridableFeature): string | undefined;
+/**
+ * IMPORTANT!!!!!!!!!!!!!!!!!!!!!!
+ *
+ * See header at top of file for important notes.
+ *
+ * Apply instruction assistance placeholder replacement to component instructions
+ *
+ * @param componentInstructions - The raw component instructions with placeholders
+ * @param instructionConfig - The instruction assistance configuration
+ * @param agentInstructionFeature - The agent instruction feature configuration
+ * @returns The component instructions with placeholders replaced
+ */
+declare function applyComponentInstructionAssistance(componentInstructions: string, instructionConfig: InstructionAssistanceConfig, agentInstructionFeature: AgentInstructionChatAppOverridableFeature): string;
 /**
  * IMPORTANT!!!!!!!!!!!!!!!!!!!!!!
  *
@@ -47,4 +74,4 @@ declare function applyInstructionAssistance(basePrompt: string, instructionConte
  */
 declare function getInstructionsAssistanceConfigFromRawSsmParams(params: Record<string, string>): InstructionAssistanceConfig;
 
-export { applyInstructionAssistance, generateInstructionAssistanceContent, getInstructionsAssistanceConfigFromRawSsmParams };
+export { applyComponentInstructionAssistance, applyInstructionAssistance, generateComponentInstructionContent, generateInstructionAssistanceContent, getInstructionsAssistanceConfigFromRawSsmParams };