From 47a709a63956e94f3c2b7fe5ee4a3bde9e4347fc Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Mon, 15 Jun 2026 16:48:29 -0700
Subject: [PATCH 01/12] feat(api): add HTML widget types and invoke activity

Add types for the HTML widget contract:
- IHtmlWidgetPayload, IHtmlWidgetSecurityPolicy, IHtmlWidgetPermissions
- ICallToolRequest, IMcpUiCallToolResult
- IHtmlWidgetCallToolInvokeActivity (htmlwidget/calltool invoke)
- Add 'extendedmarkdown' to TextFormat union
- Add htmlwidget/calltool to InvokeResponseBody map

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../invoke/html-widget/call-tool.ts           |  14 +++
 .../activities/invoke/html-widget/index.ts    |   1 +
 packages/api/src/activities/invoke/index.ts   |   5 +-
 .../models/html-widget/call-tool-request.ts   |  15 +++
 .../models/html-widget/call-tool-result.ts    |  35 ++++++
 .../models/html-widget/html-widget-payload.ts | 101 ++++++++++++++++++
 packages/api/src/models/html-widget/index.ts  |   3 +
 packages/api/src/models/index.ts              |   1 +
 packages/api/src/models/invoke-response.ts    |   2 +
 9 files changed, 176 insertions(+), 1 deletion(-)
 create mode 100644 packages/api/src/activities/invoke/html-widget/call-tool.ts
 create mode 100644 packages/api/src/activities/invoke/html-widget/index.ts
 create mode 100644 packages/api/src/models/html-widget/call-tool-request.ts
 create mode 100644 packages/api/src/models/html-widget/call-tool-result.ts
 create mode 100644 packages/api/src/models/html-widget/html-widget-payload.ts
 create mode 100644 packages/api/src/models/html-widget/index.ts

diff --git a/packages/api/src/activities/invoke/html-widget/call-tool.ts b/packages/api/src/activities/invoke/html-widget/call-tool.ts
new file mode 100644
index 000000000..275be4229
--- /dev/null
+++ b/packages/api/src/activities/invoke/html-widget/call-tool.ts
@@ -0,0 +1,14 @@
+import { ICallToolRequest } from '../../../models';
+import { IActivity } from '../../activity';
+
+export interface IHtmlWidgetCallToolInvokeActivity extends IActivity<'invoke'> {
+  /**
+   * The name of the operation associated with an invoke or event activity.
+   */
+  name: 'htmlwidget/calltool';
+
+  /**
+   * A value that is associated with the activity.
+   */
+  value: ICallToolRequest;
+}
diff --git a/packages/api/src/activities/invoke/html-widget/index.ts b/packages/api/src/activities/invoke/html-widget/index.ts
new file mode 100644
index 000000000..0271fdc65
--- /dev/null
+++ b/packages/api/src/activities/invoke/html-widget/index.ts
@@ -0,0 +1 @@
+export * from './call-tool';
diff --git a/packages/api/src/activities/invoke/index.ts b/packages/api/src/activities/invoke/index.ts
index 8411469c5..d1349163c 100644
--- a/packages/api/src/activities/invoke/index.ts
+++ b/packages/api/src/activities/invoke/index.ts
@@ -3,6 +3,7 @@ import { ConfigInvokeActivity } from './config';
 import { IExecuteActionInvokeActivity } from './execute-action';
 import { IFileConsentInvokeActivity } from './file-consent';
 import { IHandoffActionInvokeActivity } from './handoff-action';
+import { IHtmlWidgetCallToolInvokeActivity } from './html-widget';
 import { MessageInvokeActivity } from './message';
 import { MessageExtensionInvokeActivity } from './message-extension';
 import { SignInInvokeActivity } from './sign-in';
@@ -21,7 +22,8 @@ export type InvokeActivity =
   | IHandoffActionInvokeActivity
   | SignInInvokeActivity
   | AdaptiveCardInvokeActivity
-  | ISuggestedActionSubmitInvokeActivity;
+  | ISuggestedActionSubmitInvokeActivity
+  | IHtmlWidgetCallToolInvokeActivity;
 
 export * from './file-consent';
 export * from './execute-action';
@@ -34,3 +36,4 @@ export * from './handoff-action';
 export * from './sign-in';
 export * from './suggested-action-submit';
 export * from './adaptive-card';
+export * from './html-widget';
diff --git a/packages/api/src/models/html-widget/call-tool-request.ts b/packages/api/src/models/html-widget/call-tool-request.ts
new file mode 100644
index 000000000..54a79a73b
--- /dev/null
+++ b/packages/api/src/models/html-widget/call-tool-request.ts
@@ -0,0 +1,15 @@
+/**
+ * A request from a widget to call a tool on the bot.
+ * Sent as the value of an `htmlwidget/calltool` invoke activity.
+ */
+export interface ICallToolRequest {
+  /**
+   * The name of the tool to call.
+   */
+  name: string;
+
+  /**
+   * The arguments to pass to the tool.
+   */
+  arguments?: unknown;
+}
diff --git a/packages/api/src/models/html-widget/call-tool-result.ts b/packages/api/src/models/html-widget/call-tool-result.ts
new file mode 100644
index 000000000..c87a802fa
--- /dev/null
+++ b/packages/api/src/models/html-widget/call-tool-result.ts
@@ -0,0 +1,35 @@
+/**
+ * A content item in an MCP UI call tool result.
+ */
+export interface IMcpUiCallToolResultContent {
+  /**
+   * The type of content (e.g. "text").
+   */
+  type: string;
+
+  /**
+   * The text content.
+   */
+  text: string;
+}
+
+/**
+ * The result of a widget's `tools/call` request, returned by the bot
+ * in response to an `htmlwidget/calltool` invoke activity.
+ */
+export interface IMcpUiCallToolResult {
+  /**
+   * An array of content items to return to the widget.
+   */
+  content?: IMcpUiCallToolResultContent[];
+
+  /**
+   * Structured data that the widget can render from.
+   */
+  structuredContent?: unknown;
+
+  /**
+   * Whether the tool call resulted in an error.
+   */
+  isError?: boolean;
+}
diff --git a/packages/api/src/models/html-widget/html-widget-payload.ts b/packages/api/src/models/html-widget/html-widget-payload.ts
new file mode 100644
index 000000000..956281b8c
--- /dev/null
+++ b/packages/api/src/models/html-widget/html-widget-payload.ts
@@ -0,0 +1,101 @@
+/**
+ * The security policy for an HTML widget, controlling allowed origins
+ * for network requests, static resources, nested iframes, and base URIs.
+ */
+export interface IHtmlWidgetSecurityPolicy {
+  /**
+   * Allowed origins for network requests.
+   */
+  connectDomains?: string[];
+
+  /**
+   * Allowed origins for static resources.
+   */
+  resourceDomains?: string[];
+
+  /**
+   * Allowed origins for nested iframes.
+   */
+  frameDomains?: string[];
+
+  /**
+   * Allowed base URIs for the document.
+   */
+  baseUriDomains?: string[];
+}
+
+/**
+ * Permissions that the widget may request from the host.
+ */
+export interface IHtmlWidgetPermissions {
+  /**
+   * Request camera access.
+   */
+  camera?: unknown;
+
+  /**
+   * Request microphone access.
+   */
+  microphone?: unknown;
+
+  /**
+   * Request geolocation access.
+   */
+  geolocation?: unknown;
+
+  /**
+   * Request clipboard write access.
+   */
+  clipboardWrite?: unknown;
+}
+
+/**
+ * The JSON payload for an HTML widget, sent inside a ```html-widget code block
+ * within a Markdown message.
+ */
+export interface IHtmlWidgetPayload {
+  /**
+   * The widget type identifier. Currently only "widget/mcp-ui" is supported.
+   */
+  type: 'widget/mcp-ui';
+
+  /**
+   * The display name of the MCP app.
+   */
+  name: string;
+
+  /**
+   * A description of the MCP app.
+   */
+  description?: string;
+
+  /**
+   * The HTML content that makes up the widget.
+   */
+  html: string;
+
+  /**
+   * The domain associated with the widget.
+   */
+  domain: string;
+
+  /**
+   * Optional security policy controlling allowed origins.
+   */
+  securityPolicy?: IHtmlWidgetSecurityPolicy;
+
+  /**
+   * Optional data that was passed as input to the tool that produced this widget.
+   */
+  toolInput?: unknown;
+
+  /**
+   * Optional data that the tool produced alongside this widget.
+   */
+  toolOutput?: unknown;
+
+  /**
+   * Optional permissions the widget requests from the host.
+   */
+  permissions?: IHtmlWidgetPermissions;
+}
diff --git a/packages/api/src/models/html-widget/index.ts b/packages/api/src/models/html-widget/index.ts
new file mode 100644
index 000000000..ca1e46e3e
--- /dev/null
+++ b/packages/api/src/models/html-widget/index.ts
@@ -0,0 +1,3 @@
+export * from './html-widget-payload';
+export * from './call-tool-request';
+export * from './call-tool-result';
diff --git a/packages/api/src/models/index.ts b/packages/api/src/models/index.ts
index 83dbdface..11346644f 100644
--- a/packages/api/src/models/index.ts
+++ b/packages/api/src/models/index.ts
@@ -35,4 +35,5 @@ export * from './team-details';
 export * from './meeting';
 export * from './channel-id';
 export * from './activity-like';
+export * from './html-widget';
 
diff --git a/packages/api/src/models/invoke-response.ts b/packages/api/src/models/invoke-response.ts
index 14cbda234..a9cd28178 100644
--- a/packages/api/src/models/invoke-response.ts
+++ b/packages/api/src/models/invoke-response.ts
@@ -1,6 +1,7 @@
 import {
   AdaptiveCardActionResponse,
   ConfigResponse,
+  IMcpUiCallToolResult,
   MessagingExtensionActionResponse,
   MessagingExtensionResponse,
   TabResponse,
@@ -63,4 +64,5 @@ type InvokeResponseBody = {
   'signin/verifyState': void;
   'signin/failure': void;
   'adaptiveCard/action': AdaptiveCardActionResponse;
+  'htmlwidget/calltool': IMcpUiCallToolResult;
 };

From a83930965f6ef4eb226e8e66c041273360d2243d Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Mon, 15 Jun 2026 16:57:08 -0700
Subject: [PATCH 02/12] feat(apps): add widget.callTool invoke route and helper
 methods

- Add 'htmlwidget/calltool' -> 'widget.callTool' invoke alias
- Add WidgetCallToolRoutes type for typed handler registration
- Add buildHtmlWidgetMarkdown() and buildHtmlWidgetMessage() helpers
- Add unit tests (14 cases including edge cases)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 packages/apps/src/index.ts                    |   4 +
 packages/apps/src/routes/invoke/index.ts      |   7 +-
 .../apps/src/routes/invoke/widget-calltool.ts |  11 ++
 packages/apps/src/utils/html-widget.spec.ts   | 156 ++++++++++++++++++
 packages/apps/src/utils/html-widget.ts        |  61 +++++++
 5 files changed, 238 insertions(+), 1 deletion(-)
 create mode 100644 packages/apps/src/routes/invoke/widget-calltool.ts
 create mode 100644 packages/apps/src/utils/html-widget.spec.ts
 create mode 100644 packages/apps/src/utils/html-widget.ts

diff --git a/packages/apps/src/index.ts b/packages/apps/src/index.ts
index 98918b252..9debe384b 100644
--- a/packages/apps/src/index.ts
+++ b/packages/apps/src/index.ts
@@ -10,3 +10,7 @@ export * from './http';
 
 // Threading utilities
 export { toThreadedConversationId } from './utils/thread';
+
+// HTML Widget utilities
+export { buildHtmlWidgetMarkdown, buildHtmlWidgetMessage } from './utils/html-widget';
+export type { IHtmlWidgetMarkdownOptions } from './utils/html-widget';
diff --git a/packages/apps/src/routes/invoke/index.ts b/packages/apps/src/routes/invoke/index.ts
index 0a1db3d50..eb43f2df5 100644
--- a/packages/apps/src/routes/invoke/index.ts
+++ b/packages/apps/src/routes/invoke/index.ts
@@ -9,6 +9,7 @@ import { DialogSubmitSubRoutes } from './dialog-submit';
 import { FileConsentActivityRoutes } from './file-consent';
 import { MessageExtensionSubmitActivityRoutes } from './message-extension-submit';
 import { MessageSubmitActivityRoutes } from './message-submit';
+import { WidgetCallToolRoutes } from './widget-calltool';
 
 export type InvokeActivityRoutes<TExtraCtx extends Record<string, any> = Record<string, any>> = {
   [K in InvokeActivity['name']as InvokeAliases[K]]?: RouteHandler<
@@ -20,7 +21,8 @@ export type InvokeActivityRoutes<TExtraCtx extends Record<string, any> = Record<
   MessageSubmitActivityRoutes &
   DialogOpenSubRoutes<TExtraCtx> &
   DialogSubmitSubRoutes<TExtraCtx> &
-  CardActionSubRoutes<TExtraCtx>;
+  CardActionSubRoutes<TExtraCtx> &
+  WidgetCallToolRoutes<TExtraCtx>;
 
 type InvokeAliases = {
   'config/fetch': 'config.open';
@@ -48,6 +50,7 @@ type InvokeAliases = {
   'signin/verifyState': 'signin.verify-state';
   'signin/failure': 'signin.failure';
   'adaptiveCard/action': 'card.action';
+  'htmlwidget/calltool': 'widget.callTool';
 };
 
 export const INVOKE_ALIASES: InvokeAliases = {
@@ -76,6 +79,7 @@ export const INVOKE_ALIASES: InvokeAliases = {
   'signin/verifyState': 'signin.verify-state',
   'signin/failure': 'signin.failure',
   'adaptiveCard/action': 'card.action',
+  'htmlwidget/calltool': 'widget.callTool',
 };
 
 export * from './card-action';
@@ -84,4 +88,5 @@ export * from './dialog-submit';
 export * from './file-consent';
 export * from './message-extension-submit';
 export * from './message-submit';
+export * from './widget-calltool';
 
diff --git a/packages/apps/src/routes/invoke/widget-calltool.ts b/packages/apps/src/routes/invoke/widget-calltool.ts
new file mode 100644
index 000000000..7991735ac
--- /dev/null
+++ b/packages/apps/src/routes/invoke/widget-calltool.ts
@@ -0,0 +1,11 @@
+import { IHtmlWidgetCallToolInvokeActivity, InvokeResponse } from '@microsoft/teams.api';
+
+import { IActivityContext } from '../../contexts';
+import { RouteHandler } from '../../types';
+
+export type WidgetCallToolRoutes<TExtraCtx extends Record<string, any> = Record<string, any>> = {
+  'widget.callTool'?: RouteHandler<
+    IActivityContext<IHtmlWidgetCallToolInvokeActivity, TExtraCtx>,
+    InvokeResponse<'htmlwidget/calltool'> | InvokeResponse<'htmlwidget/calltool'>['body']
+  >;
+};
diff --git a/packages/apps/src/utils/html-widget.spec.ts b/packages/apps/src/utils/html-widget.spec.ts
new file mode 100644
index 000000000..cbaebba37
--- /dev/null
+++ b/packages/apps/src/utils/html-widget.spec.ts
@@ -0,0 +1,156 @@
+import { buildHtmlWidgetMarkdown, buildHtmlWidgetMessage } from './html-widget';
+import { IHtmlWidgetPayload } from '@microsoft/teams.api';
+
+const MINIMAL_PAYLOAD: IHtmlWidgetPayload = {
+  type: 'widget/mcp-ui',
+  name: 'Test Widget',
+  html: '<div>Hello</div>',
+  domain: 'https://example.com',
+};
+
+const FULL_PAYLOAD: IHtmlWidgetPayload = {
+  type: 'widget/mcp-ui',
+  name: 'Weather Widget',
+  description: 'Current weather conditions',
+  html: '<div class="weather">72F</div>',
+  domain: 'https://weather.example.com',
+  securityPolicy: {
+    connectDomains: ['https://api.example.com'],
+    resourceDomains: ["'self'", 'data:'],
+    frameDomains: [],
+    baseUriDomains: [],
+  },
+  toolInput: { location: 'Seattle, WA' },
+  toolOutput: { content: [{ type: 'text', text: 'Seattle: 72F' }], structuredContent: { tempF: 72 }, isError: false },
+  permissions: { clipboardWrite: {} },
+};
+
+describe('buildHtmlWidgetMarkdown', () => {
+  it('should wrap payload in html-widget code fence', () => {
+    const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD);
+    expect(result).toBe(
+      '```html-widget\n' + JSON.stringify(MINIMAL_PAYLOAD) + '\n```'
+    );
+  });
+
+  it('should include text before the widget', () => {
+    const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD, { before: 'Check this out:' });
+    expect(result).toBe(
+      'Check this out:\n\n```html-widget\n' + JSON.stringify(MINIMAL_PAYLOAD) + '\n```'
+    );
+  });
+
+  it('should include text after the widget', () => {
+    const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD, { after: 'Pretty cool, right?' });
+    expect(result).toBe(
+      '```html-widget\n' + JSON.stringify(MINIMAL_PAYLOAD) + '\n```\n\nPretty cool, right?'
+    );
+  });
+
+  it('should include text before and after the widget', () => {
+    const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD, {
+      before: 'Before',
+      after: 'After',
+    });
+    expect(result).toBe(
+      'Before\n\n```html-widget\n' + JSON.stringify(MINIMAL_PAYLOAD) + '\n```\n\nAfter'
+    );
+  });
+
+  it('should serialize a full payload with all fields', () => {
+    const result = buildHtmlWidgetMarkdown(FULL_PAYLOAD);
+    const parsed = JSON.parse(result.replace('```html-widget\n', '').replace('\n```', ''));
+    expect(parsed.type).toBe('widget/mcp-ui');
+    expect(parsed.name).toBe('Weather Widget');
+    expect(parsed.description).toBe('Current weather conditions');
+    expect(parsed.html).toBe('<div class="weather">72F</div>');
+    expect(parsed.domain).toBe('https://weather.example.com');
+    expect(parsed.securityPolicy.connectDomains).toEqual(['https://api.example.com']);
+    expect(parsed.toolInput).toEqual({ location: 'Seattle, WA' });
+    expect(parsed.permissions).toEqual({ clipboardWrite: {} });
+  });
+
+  it('should produce valid markdown with no options', () => {
+    const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD);
+    expect(result.startsWith('```html-widget\n')).toBe(true);
+    expect(result.endsWith('\n```')).toBe(true);
+  });
+
+  it('should handle HTML containing backticks without breaking the fence', () => {
+    const payload: IHtmlWidgetPayload = {
+      ...MINIMAL_PAYLOAD,
+      html: '<code>```some code```</code>',
+    };
+    const result = buildHtmlWidgetMarkdown(payload);
+    // JSON.stringify escapes nothing about backticks, but they appear inside
+    // a JSON string value (quoted), so the code fence boundary is unambiguous
+    // because the fence opener/closer are on their own lines.
+    expect(result.startsWith('```html-widget\n')).toBe(true);
+    expect(result.endsWith('\n```')).toBe(true);
+    const jsonLine = result.split('\n').slice(1, -1).join('\n');
+    const parsed = JSON.parse(jsonLine);
+    expect(parsed.html).toBe('<code>```some code```</code>');
+  });
+
+  it('should handle HTML with newlines and special characters', () => {
+    const payload: IHtmlWidgetPayload = {
+      ...MINIMAL_PAYLOAD,
+      html: '<div>\n  <p>"Hello" & \'world\'</p>\n</div>',
+    };
+    const result = buildHtmlWidgetMarkdown(payload);
+    // JSON.stringify will escape the newlines and quotes inside the string
+    const jsonLine = result.split('\n')[1];
+    const parsed = JSON.parse(jsonLine);
+    expect(parsed.html).toBe('<div>\n  <p>"Hello" & \'world\'</p>\n</div>');
+  });
+
+  it('should handle empty string options without adding extra lines', () => {
+    const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD, { before: '', after: '' });
+    expect(result).toBe(
+      '```html-widget\n' + JSON.stringify(MINIMAL_PAYLOAD) + '\n```'
+    );
+  });
+
+  it('should handle payload with undefined optional fields', () => {
+    const payload: IHtmlWidgetPayload = {
+      type: 'widget/mcp-ui',
+      name: 'Bare',
+      html: '',
+      domain: '',
+    };
+    const result = buildHtmlWidgetMarkdown(payload);
+    const jsonLine = result.split('\n')[1];
+    const parsed = JSON.parse(jsonLine);
+    expect(parsed.type).toBe('widget/mcp-ui');
+    expect(parsed.description).toBeUndefined();
+    expect(parsed.securityPolicy).toBeUndefined();
+    expect(parsed.toolInput).toBeUndefined();
+    expect(parsed.permissions).toBeUndefined();
+  });
+});
+
+describe('buildHtmlWidgetMessage', () => {
+  it('should return a message activity with extendedmarkdown format', () => {
+    const result = buildHtmlWidgetMessage(MINIMAL_PAYLOAD);
+    expect(result.type).toBe('message');
+    expect(result.textFormat).toBe('extendedmarkdown');
+  });
+
+  it('should contain the widget markdown in the text field', () => {
+    const result = buildHtmlWidgetMessage(MINIMAL_PAYLOAD);
+    expect(result.text).toBe(buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD));
+  });
+
+  it('should pass options through to markdown builder', () => {
+    const result = buildHtmlWidgetMessage(FULL_PAYLOAD, { before: 'Weather today:' });
+    expect(result.text).toBe(buildHtmlWidgetMarkdown(FULL_PAYLOAD, { before: 'Weather today:' }));
+  });
+
+  it('should produce a message sendable as ActivityLike', () => {
+    const result = buildHtmlWidgetMessage(MINIMAL_PAYLOAD);
+    // ActivityLike requires at minimum a `type` field
+    expect(result).toHaveProperty('type');
+    expect(result).toHaveProperty('text');
+    expect(result).toHaveProperty('textFormat');
+  });
+});
diff --git a/packages/apps/src/utils/html-widget.ts b/packages/apps/src/utils/html-widget.ts
new file mode 100644
index 000000000..09407ecc5
--- /dev/null
+++ b/packages/apps/src/utils/html-widget.ts
@@ -0,0 +1,61 @@
+import { IHtmlWidgetPayload } from '@microsoft/teams.api';
+
+/**
+ * Options for building an HTML widget markdown string.
+ */
+export interface IHtmlWidgetMarkdownOptions {
+  /**
+   * Text to include before the widget code block.
+   */
+  before?: string;
+
+  /**
+   * Text to include after the widget code block.
+   */
+  after?: string;
+}
+
+/**
+ * Wraps an HTML widget payload in the ```html-widget markdown code fence format.
+ *
+ * @param payload - The widget payload to serialize.
+ * @param options - Optional text to include before/after the widget block.
+ * @returns The markdown string containing the widget code block.
+ */
+export function buildHtmlWidgetMarkdown(
+  payload: IHtmlWidgetPayload,
+  options?: IHtmlWidgetMarkdownOptions
+): string {
+  const json = JSON.stringify(payload);
+  const parts: string[] = [];
+
+  if (options?.before) {
+    parts.push(options.before, '');
+  }
+
+  parts.push('```html-widget', json, '```');
+
+  if (options?.after) {
+    parts.push('', options.after);
+  }
+
+  return parts.join('\n');
+}
+
+/**
+ * Builds a message activity containing an HTML widget, ready to be sent.
+ *
+ * @param payload - The widget payload to include in the message.
+ * @param options - Optional text to include before/after the widget block.
+ * @returns An activity object with textFormat set to 'extendedmarkdown'.
+ */
+export function buildHtmlWidgetMessage(
+  payload: IHtmlWidgetPayload,
+  options?: IHtmlWidgetMarkdownOptions
+): { type: 'message'; text: string; textFormat: 'extendedmarkdown' } {
+  return {
+    type: 'message',
+    text: buildHtmlWidgetMarkdown(payload, options),
+    textFormat: 'extendedmarkdown',
+  };
+}

From fe7d67a5f4309df8e5201e2549a4bbd5170f8a68 Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Thu, 25 Jun 2026 09:59:45 -0700
Subject: [PATCH 03/12] Fix IHTMLWidgetCallToolResponse wrapper type and update
 domain docs

---
 .../src/models/html-widget/call-tool-result.ts  | 17 +++++++++++++++++
 .../models/html-widget/html-widget-payload.ts   |  5 ++++-
 packages/api/src/models/invoke-response.ts      |  4 ++--
 3 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/packages/api/src/models/html-widget/call-tool-result.ts b/packages/api/src/models/html-widget/call-tool-result.ts
index c87a802fa..398fecee7 100644
--- a/packages/api/src/models/html-widget/call-tool-result.ts
+++ b/packages/api/src/models/html-widget/call-tool-result.ts
@@ -33,3 +33,20 @@ export interface IMcpUiCallToolResult {
    */
   isError?: boolean;
 }
+
+/**
+ * The wire-format response body for an `htmlwidget/calltool` invoke.
+ * Teams expects this shape (with `responseType` discriminator) rather than
+ * a bare {@link IMcpUiCallToolResult}.
+ */
+export interface IHtmlWidgetCallToolResponse {
+  /**
+   * Discriminator that tells Teams how to interpret the response.
+   */
+  responseType: 'htmlwidget/calltoolresult';
+
+  /**
+   * The tool call result payload.
+   */
+  callToolResult: IMcpUiCallToolResult;
+}
diff --git a/packages/api/src/models/html-widget/html-widget-payload.ts b/packages/api/src/models/html-widget/html-widget-payload.ts
index 956281b8c..4c74e9579 100644
--- a/packages/api/src/models/html-widget/html-widget-payload.ts
+++ b/packages/api/src/models/html-widget/html-widget-payload.ts
@@ -75,7 +75,10 @@ export interface IHtmlWidgetPayload {
   html: string;
 
   /**
-   * The domain associated with the widget.
+   * The domain associated with the widget, applied to sandbox metadata.
+   * Must be a valid domain URL (e.g. 'https://example.com'). The domain
+   * does not need to resolve or serve content, but must be non-empty.
+   * This value is available to the rendering MCP App as informational context.
    */
   domain: string;
 
diff --git a/packages/api/src/models/invoke-response.ts b/packages/api/src/models/invoke-response.ts
index a9cd28178..8c992465a 100644
--- a/packages/api/src/models/invoke-response.ts
+++ b/packages/api/src/models/invoke-response.ts
@@ -1,7 +1,7 @@
 import {
   AdaptiveCardActionResponse,
   ConfigResponse,
-  IMcpUiCallToolResult,
+  IHtmlWidgetCallToolResponse,
   MessagingExtensionActionResponse,
   MessagingExtensionResponse,
   TabResponse,
@@ -64,5 +64,5 @@ type InvokeResponseBody = {
   'signin/verifyState': void;
   'signin/failure': void;
   'adaptiveCard/action': AdaptiveCardActionResponse;
-  'htmlwidget/calltool': IMcpUiCallToolResult;
+  'htmlwidget/calltool': IHtmlWidgetCallToolResponse;
 };

From e7eda66229891f5e2b18518094598f316ea6d5d3 Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Thu, 25 Jun 2026 10:44:03 -0700
Subject: [PATCH 04/12] Add injectWidgetProtocol helper and payload validation

---
 packages/apps/src/index.ts                  |   4 +-
 packages/apps/src/utils/html-widget.spec.ts | 362 ++++++++++++++++++--
 packages/apps/src/utils/html-widget.ts      | 206 ++++++++++-
 3 files changed, 537 insertions(+), 35 deletions(-)

diff --git a/packages/apps/src/index.ts b/packages/apps/src/index.ts
index 9debe384b..61e441a18 100644
--- a/packages/apps/src/index.ts
+++ b/packages/apps/src/index.ts
@@ -12,5 +12,5 @@ export * from './http';
 export { toThreadedConversationId } from './utils/thread';
 
 // HTML Widget utilities
-export { buildHtmlWidgetMarkdown, buildHtmlWidgetMessage } from './utils/html-widget';
-export type { IHtmlWidgetMarkdownOptions } from './utils/html-widget';
+export { buildHtmlWidgetMarkdown, buildHtmlWidgetMessage, injectWidgetProtocol } from './utils/html-widget';
+export type { IHtmlWidgetMarkdownOptions, IInjectWidgetProtocolOptions } from './utils/html-widget';
diff --git a/packages/apps/src/utils/html-widget.spec.ts b/packages/apps/src/utils/html-widget.spec.ts
index cbaebba37..9bbd61906 100644
--- a/packages/apps/src/utils/html-widget.spec.ts
+++ b/packages/apps/src/utils/html-widget.spec.ts
@@ -1,6 +1,7 @@
-import { buildHtmlWidgetMarkdown, buildHtmlWidgetMessage } from './html-widget';
 import { IHtmlWidgetPayload } from '@microsoft/teams.api';
 
+import { buildHtmlWidgetMarkdown, buildHtmlWidgetMessage, injectWidgetProtocol } from './html-widget';
+
 const MINIMAL_PAYLOAD: IHtmlWidgetPayload = {
   type: 'widget/mcp-ui',
   name: 'Test Widget',
@@ -16,7 +17,7 @@ const FULL_PAYLOAD: IHtmlWidgetPayload = {
   domain: 'https://weather.example.com',
   securityPolicy: {
     connectDomains: ['https://api.example.com'],
-    resourceDomains: ["'self'", 'data:'],
+    resourceDomains: ['\'self\'', 'data:'],
     frameDomains: [],
     baseUriDomains: [],
   },
@@ -28,23 +29,42 @@ const FULL_PAYLOAD: IHtmlWidgetPayload = {
 describe('buildHtmlWidgetMarkdown', () => {
   it('should wrap payload in html-widget code fence', () => {
     const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD);
-    expect(result).toBe(
-      '```html-widget\n' + JSON.stringify(MINIMAL_PAYLOAD) + '\n```'
-    );
+    expect(result.startsWith('```html-widget\n')).toBe(true);
+    expect(result.endsWith('\n```')).toBe(true);
+  });
+
+  it('should auto-inject the widget protocol into the HTML', () => {
+    const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD);
+    const jsonLine = result.split('\n').slice(1, -1).join('\n');
+    const parsed = JSON.parse(jsonLine);
+    expect(parsed.html).toContain('ui/initialize');
+    expect(parsed.html).toContain('<div>Hello</div>');
+  });
+
+  it('should not double-inject if HTML already has the protocol', () => {
+    const htmlWithInit = '<div>Hello</div><script>ui/initialize</script>';
+    const payload = { ...MINIMAL_PAYLOAD, html: htmlWithInit };
+    const result = buildHtmlWidgetMarkdown(payload);
+    const jsonLine = result.split('\n').slice(1, -1).join('\n');
+    const parsed = JSON.parse(jsonLine);
+    expect(parsed.html).toBe(htmlWithInit);
+  });
+
+  it('should use the payload name as the protocol app name', () => {
+    const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD);
+    const jsonLine = result.split('\n').slice(1, -1).join('\n');
+    const parsed = JSON.parse(jsonLine);
+    expect(parsed.html).toContain('name:\'Test Widget\'');
   });
 
   it('should include text before the widget', () => {
     const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD, { before: 'Check this out:' });
-    expect(result).toBe(
-      'Check this out:\n\n```html-widget\n' + JSON.stringify(MINIMAL_PAYLOAD) + '\n```'
-    );
+    expect(result.startsWith('Check this out:\n\n```html-widget\n')).toBe(true);
   });
 
   it('should include text after the widget', () => {
     const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD, { after: 'Pretty cool, right?' });
-    expect(result).toBe(
-      '```html-widget\n' + JSON.stringify(MINIMAL_PAYLOAD) + '\n```\n\nPretty cool, right?'
-    );
+    expect(result.endsWith('\n```\n\nPretty cool, right?')).toBe(true);
   });
 
   it('should include text before and after the widget', () => {
@@ -52,9 +72,8 @@ describe('buildHtmlWidgetMarkdown', () => {
       before: 'Before',
       after: 'After',
     });
-    expect(result).toBe(
-      'Before\n\n```html-widget\n' + JSON.stringify(MINIMAL_PAYLOAD) + '\n```\n\nAfter'
-    );
+    expect(result.startsWith('Before\n\n```html-widget\n')).toBe(true);
+    expect(result.endsWith('\n```\n\nAfter')).toBe(true);
   });
 
   it('should serialize a full payload with all fields', () => {
@@ -63,17 +82,28 @@ describe('buildHtmlWidgetMarkdown', () => {
     expect(parsed.type).toBe('widget/mcp-ui');
     expect(parsed.name).toBe('Weather Widget');
     expect(parsed.description).toBe('Current weather conditions');
-    expect(parsed.html).toBe('<div class="weather">72F</div>');
+    expect(parsed.html).toContain('<div class="weather">72F</div>');
+    expect(parsed.html).toContain('ui/initialize');
     expect(parsed.domain).toBe('https://weather.example.com');
     expect(parsed.securityPolicy.connectDomains).toEqual(['https://api.example.com']);
     expect(parsed.toolInput).toEqual({ location: 'Seattle, WA' });
     expect(parsed.permissions).toEqual({ clipboardWrite: {} });
   });
 
-  it('should produce valid markdown with no options', () => {
-    const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD);
-    expect(result.startsWith('```html-widget\n')).toBe(true);
-    expect(result.endsWith('\n```')).toBe(true);
+  it('should not overwrite a user-provided securityPolicy with defaults', () => {
+    const customPolicy = {
+      connectDomains: ['https://api.custom.com'],
+      resourceDomains: ['https://cdn.custom.com'],
+      frameDomains: ['https://embed.custom.com'],
+      baseUriDomains: [],
+    };
+    const payload: IHtmlWidgetPayload = {
+      ...MINIMAL_PAYLOAD,
+      securityPolicy: customPolicy,
+    };
+    const result = buildHtmlWidgetMarkdown(payload);
+    const parsed = JSON.parse(result.split('\n')[1]);
+    expect(parsed.securityPolicy).toEqual(customPolicy);
   });
 
   it('should handle HTML containing backticks without breaking the fence', () => {
@@ -82,14 +112,11 @@ describe('buildHtmlWidgetMarkdown', () => {
       html: '<code>```some code```</code>',
     };
     const result = buildHtmlWidgetMarkdown(payload);
-    // JSON.stringify escapes nothing about backticks, but they appear inside
-    // a JSON string value (quoted), so the code fence boundary is unambiguous
-    // because the fence opener/closer are on their own lines.
     expect(result.startsWith('```html-widget\n')).toBe(true);
     expect(result.endsWith('\n```')).toBe(true);
     const jsonLine = result.split('\n').slice(1, -1).join('\n');
     const parsed = JSON.parse(jsonLine);
-    expect(parsed.html).toBe('<code>```some code```</code>');
+    expect(parsed.html).toContain('<code>```some code```</code>');
   });
 
   it('should handle HTML with newlines and special characters', () => {
@@ -98,32 +125,37 @@ describe('buildHtmlWidgetMarkdown', () => {
       html: '<div>\n  <p>"Hello" & \'world\'</p>\n</div>',
     };
     const result = buildHtmlWidgetMarkdown(payload);
-    // JSON.stringify will escape the newlines and quotes inside the string
     const jsonLine = result.split('\n')[1];
     const parsed = JSON.parse(jsonLine);
-    expect(parsed.html).toBe('<div>\n  <p>"Hello" & \'world\'</p>\n</div>');
+    expect(parsed.html).toContain('<div>\n  <p>"Hello" & \'world\'</p>\n</div>');
   });
 
   it('should handle empty string options without adding extra lines', () => {
     const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD, { before: '', after: '' });
-    expect(result).toBe(
-      '```html-widget\n' + JSON.stringify(MINIMAL_PAYLOAD) + '\n```'
-    );
+    expect(result.startsWith('```html-widget\n')).toBe(true);
+    expect(result.endsWith('\n```')).toBe(true);
+    // No extra blank lines from empty before/after
+    expect(result).not.toMatch(/^\n/);
   });
 
   it('should handle payload with undefined optional fields', () => {
     const payload: IHtmlWidgetPayload = {
       type: 'widget/mcp-ui',
       name: 'Bare',
-      html: '',
-      domain: '',
+      html: '<p>minimal</p>',
+      domain: 'https://example.com',
     };
     const result = buildHtmlWidgetMarkdown(payload);
     const jsonLine = result.split('\n')[1];
     const parsed = JSON.parse(jsonLine);
     expect(parsed.type).toBe('widget/mcp-ui');
     expect(parsed.description).toBeUndefined();
-    expect(parsed.securityPolicy).toBeUndefined();
+    expect(parsed.securityPolicy).toEqual({
+      connectDomains: [],
+      resourceDomains: ['\'self\'', 'data:'],
+      frameDomains: [],
+      baseUriDomains: [],
+    });
     expect(parsed.toolInput).toBeUndefined();
     expect(parsed.permissions).toBeUndefined();
   });
@@ -154,3 +186,271 @@ describe('buildHtmlWidgetMessage', () => {
     expect(result).toHaveProperty('textFormat');
   });
 });
+
+describe('injectWidgetProtocol', () => {
+  const BARE_HTML = '<body><h1>Hello</h1></body>';
+  const BARE_HTML_NO_BODY = '<h1>Hello</h1>';
+
+  it('should inject the protocol script before </body>', () => {
+    const result = injectWidgetProtocol(BARE_HTML);
+    expect(result).toContain('ui/initialize');
+    expect(result).toContain('ui/notifications/size-changed');
+    expect(result).toContain('ui/notifications/initialized');
+    expect(result).toContain('</body>');
+    // Script should come before </body>
+    const scriptIdx = result.indexOf('ui/initialize');
+    const bodyIdx = result.indexOf('</body>');
+    expect(scriptIdx).toBeLessThan(bodyIdx);
+  });
+
+  it('should append script if no </body> tag exists', () => {
+    const result = injectWidgetProtocol(BARE_HTML_NO_BODY);
+    expect(result).toContain('ui/initialize');
+    expect(result).toContain('<h1>Hello</h1>');
+  });
+
+  it('should use custom app name and version', () => {
+    const result = injectWidgetProtocol(BARE_HTML, { name: 'my-widget', version: '2.0.0' });
+    expect(result).toContain('name:\'my-widget\'');
+    expect(result).toContain('version:\'2.0.0\'');
+  });
+
+  it('should use default name and version when not provided', () => {
+    const result = injectWidgetProtocol(BARE_HTML);
+    expect(result).toContain('name:\'widget\'');
+    expect(result).toContain('version:\'1.0.0\'');
+  });
+
+  it('should not modify HTML that already contains ui/initialize', () => {
+    const htmlWithInit = '<body><script>ui/initialize</script></body>';
+    const result = injectWidgetProtocol(htmlWithInit);
+    expect(result).toBe(htmlWithInit);
+  });
+
+  it('should be idempotent -- calling twice produces the same output', () => {
+    const first = injectWidgetProtocol(BARE_HTML);
+    const second = injectWidgetProtocol(first);
+    expect(second).toBe(first);
+  });
+
+  it('should handle empty string HTML', () => {
+    const result = injectWidgetProtocol('');
+    expect(result).toContain('ui/initialize');
+    expect(result).toContain('<script>');
+  });
+
+  it('should inject before </body> in a full HTML document', () => {
+    const fullDoc = '<!DOCTYPE html><html><head><meta charset="utf-8"></head><body><div>Content</div></body></html>';
+    const result = injectWidgetProtocol(fullDoc);
+    expect(result).toContain('ui/initialize');
+    // Script should be between content and </body>
+    const contentIdx = result.indexOf('Content</div>');
+    const scriptIdx = result.indexOf('<script>');
+    const bodyIdx = result.indexOf('</body>');
+    expect(contentIdx).toBeLessThan(scriptIdx);
+    expect(scriptIdx).toBeLessThan(bodyIdx);
+  });
+
+  it('should match </body> naively even inside comments or strings', () => {
+    // Documents this known limitation: we do naive string matching
+    const htmlWithBodyInComment = '<body><!-- </body> --><p>Real content</p></body>';
+    const result = injectWidgetProtocol(htmlWithBodyInComment);
+    // Injects at first </body> occurrence (the one in the comment)
+    expect(result).toContain('ui/initialize');
+    const scriptIdx = result.indexOf('<script>');
+    const commentBodyIdx = result.indexOf('<!-- ');
+    // Script is injected before the first </body> (inside comment)
+    expect(scriptIdx).toBeGreaterThan(commentBodyIdx);
+  });
+
+  it('should include notification hooks only when opted in via notifications option', () => {
+    const withHooks = injectWidgetProtocol(BARE_HTML, {
+      notifications: ['tool-result', 'tool-input', 'host-context-changed'],
+    });
+    expect(withHooks).toContain('ui/notifications/tool-result');
+    expect(withHooks).toContain('window.onToolResult');
+    expect(withHooks).toContain('ui/notifications/tool-input');
+    expect(withHooks).toContain('window.onToolInput');
+    expect(withHooks).toContain('ui/notifications/host-context-changed');
+    expect(withHooks).toContain('window.onHostContextChanged');
+
+    const withoutHooks = injectWidgetProtocol(BARE_HTML);
+    expect(withoutHooks).not.toContain('onToolResult');
+    expect(withoutHooks).not.toContain('onToolInput');
+    expect(withoutHooks).not.toContain('onHostContextChanged');
+  });
+
+  it('should ignore unknown notification names', () => {
+    const result = injectWidgetProtocol(BARE_HTML, {
+      notifications: ['some-future-event'],
+    });
+    expect(result).not.toContain('ui/notifications/some-future-event');
+    expect(result).not.toContain('onSomeFutureEvent');
+  });
+
+  it('should inject hooks for all known notification types', () => {
+    const result = injectWidgetProtocol(BARE_HTML, {
+      notifications: ['tool-result', 'tool-input', 'tool-input-partial', 'tool-cancelled', 'host-context-changed', 'resource-teardown'],
+    });
+    expect(result).toContain('ui/notifications/tool-result');
+    expect(result).toContain('window.onToolResult');
+    expect(result).toContain('ui/notifications/tool-input-partial');
+    expect(result).toContain('window.onToolInputPartial');
+    expect(result).toContain('ui/notifications/tool-cancelled');
+    expect(result).toContain('window.onToolCancelled');
+    expect(result).toContain('ui/notifications/resource-teardown');
+    expect(result).toContain('window.onResourceTeardown');
+  });
+
+  it('should include availableDisplayModes in appCapabilities when provided', () => {
+    const result = injectWidgetProtocol(BARE_HTML, {
+      appCapabilities: { availableDisplayModes: ['inline', 'fullscreen'] },
+    });
+    expect(result).toContain('availableDisplayModes');
+    expect(result).toContain(JSON.stringify(['inline', 'fullscreen']));
+  });
+
+  it('should omit availableDisplayModes when not provided', () => {
+    const result = injectWidgetProtocol(BARE_HTML);
+    expect(result).not.toContain('availableDisplayModes');
+    expect(result).toContain('appCapabilities:{}');
+  });
+});
+
+describe('buildHtmlWidgetMarkdown integration', () => {
+  it('should inject protocol using payload name as appInfo name', () => {
+    const payload: IHtmlWidgetPayload = {
+      type: 'widget/mcp-ui',
+      name: 'My Custom Widget',
+      html: '<body><p>Hello</p></body>',
+      domain: 'https://example.com',
+    };
+    const result = buildHtmlWidgetMarkdown(payload);
+    const jsonLine = result.split('\n').slice(1, -1).join('\n');
+    const parsed = JSON.parse(jsonLine);
+    expect(parsed.html).toContain('name:\'My Custom Widget\'');
+  });
+
+  it('should not double-inject when HTML already has protocol', () => {
+    const htmlWithProtocol = '<body><script>ui/initialize already here</script></body>';
+    const payload: IHtmlWidgetPayload = {
+      type: 'widget/mcp-ui',
+      name: 'Test',
+      html: htmlWithProtocol,
+      domain: 'https://example.com',
+    };
+    const result = buildHtmlWidgetMarkdown(payload);
+    const jsonLine = result.split('\n').slice(1, -1).join('\n');
+    const parsed = JSON.parse(jsonLine);
+    expect(parsed.html).toBe(htmlWithProtocol);
+  });
+
+  it('should produce valid output with minimal payload fields', () => {
+    const payload: IHtmlWidgetPayload = {
+      type: 'widget/mcp-ui',
+      name: 'Bare',
+      html: '<p>minimal</p>',
+      domain: 'https://example.com',
+    };
+    const result = buildHtmlWidgetMarkdown(payload);
+    expect(result.startsWith('```html-widget\n')).toBe(true);
+    expect(result.endsWith('\n```')).toBe(true);
+    const jsonLine = result.split('\n').slice(1, -1).join('\n');
+    const parsed = JSON.parse(jsonLine);
+    expect(parsed.html).toContain('ui/initialize');
+    expect(parsed.html).toContain('<p>minimal</p>');
+  });
+
+  it('should produce message with protocol injected end-to-end', () => {
+    const payload: IHtmlWidgetPayload = {
+      type: 'widget/mcp-ui',
+      name: 'E2E Widget',
+      html: '<body><div>test</div></body>',
+      domain: 'https://teams.microsoft.com',
+    };
+    const msg = buildHtmlWidgetMessage(payload);
+    expect(msg.type).toBe('message');
+    expect(msg.textFormat).toBe('extendedmarkdown');
+    // Parse the JSON from the markdown
+    const jsonLine = msg.text.split('\n').slice(1, -1).join('\n');
+    const parsed = JSON.parse(jsonLine);
+    expect(parsed.html).toContain('ui/initialize');
+    expect(parsed.html).toContain('name:\'E2E Widget\'');
+  });
+});
+
+describe('payload validation', () => {
+  it('should throw if name is empty', () => {
+    const payload: IHtmlWidgetPayload = {
+      type: 'widget/mcp-ui',
+      name: '',
+      html: '<div>Hello</div>',
+      domain: 'https://example.com',
+    };
+    expect(() => buildHtmlWidgetMarkdown(payload)).toThrow('non-empty "name"');
+  });
+
+  it('should throw if name is only whitespace', () => {
+    const payload: IHtmlWidgetPayload = {
+      type: 'widget/mcp-ui',
+      name: '   ',
+      html: '<div>Hello</div>',
+      domain: 'https://example.com',
+    };
+    expect(() => buildHtmlWidgetMarkdown(payload)).toThrow('non-empty "name"');
+  });
+
+  it('should throw if html is empty', () => {
+    const payload: IHtmlWidgetPayload = {
+      type: 'widget/mcp-ui',
+      name: 'Widget',
+      html: '',
+      domain: 'https://example.com',
+    };
+    expect(() => buildHtmlWidgetMarkdown(payload)).toThrow('non-empty "html"');
+  });
+
+  it('should throw if html is only whitespace', () => {
+    const payload: IHtmlWidgetPayload = {
+      type: 'widget/mcp-ui',
+      name: 'Widget',
+      html: '   ',
+      domain: 'https://example.com',
+    };
+    expect(() => buildHtmlWidgetMarkdown(payload)).toThrow('non-empty "html"');
+  });
+
+  it('should not throw for valid payload', () => {
+    expect(() => buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD)).not.toThrow();
+  });
+
+  it('should validate through buildHtmlWidgetMessage', () => {
+    const payload: IHtmlWidgetPayload = {
+      type: 'widget/mcp-ui',
+      name: '',
+      html: '<div>Hello</div>',
+      domain: 'https://example.com',
+    };
+    expect(() => buildHtmlWidgetMessage(payload)).toThrow('non-empty "name"');
+  });
+
+  it('should throw if domain is empty', () => {
+    const payload: IHtmlWidgetPayload = {
+      type: 'widget/mcp-ui',
+      name: 'Widget',
+      html: '<div>Hello</div>',
+      domain: '',
+    };
+    expect(() => buildHtmlWidgetMarkdown(payload)).toThrow('https://');
+  });
+
+  it('should throw if domain does not start with https://', () => {
+    const payload: IHtmlWidgetPayload = {
+      type: 'widget/mcp-ui',
+      name: 'Widget',
+      html: '<div>Hello</div>',
+      domain: 'example.com',
+    };
+    expect(() => buildHtmlWidgetMarkdown(payload)).toThrow('https://');
+  });
+});
diff --git a/packages/apps/src/utils/html-widget.ts b/packages/apps/src/utils/html-widget.ts
index 09407ecc5..a4993ce48 100644
--- a/packages/apps/src/utils/html-widget.ts
+++ b/packages/apps/src/utils/html-widget.ts
@@ -1,5 +1,45 @@
 import { IHtmlWidgetPayload } from '@microsoft/teams.api';
 
+/**
+ * The MCP Apps protocol version used for the widget init handshake.
+ */
+const MCP_PROTOCOL_VERSION = '2026-01-26';
+
+/**
+ * Validates an HTML widget payload, throwing if required fields are
+ * missing or empty. This catches issues that would otherwise result
+ * in a silent client-side render failure ("Couldn't load widget").
+ */
+function validateHtmlWidgetPayload(payload: IHtmlWidgetPayload): void {
+  if (!payload.name?.trim()) {
+    throw new Error('HTML widget payload requires a non-empty "name" field.');
+  }
+
+  if (!payload.html?.trim()) {
+    throw new Error('HTML widget payload requires a non-empty "html" field.');
+  }
+
+  if (!payload.domain?.trim() || !payload.domain.startsWith('https://')) {
+    throw new Error('HTML widget payload requires "domain" to be a valid URL starting with "https://".');
+  }
+}
+
+/**
+ * Known host notification types from the MCP Apps spec (`ui/notifications/*`).
+ * These are the suffix portion of the full method name, e.g. 'tool-result'
+ * maps to the JSON-RPC method `ui/notifications/tool-result`.
+ *
+ * @see MCP Apps Protocol (SEP-1865) - Notifications section
+ */
+type WidgetNotification =
+  | 'tool-result'
+  | 'tool-input'
+  | 'tool-input-partial'
+  | 'tool-cancelled'
+  | 'host-context-changed'
+  | 'resource-teardown'
+  | (string & {});
+
 /**
  * Options for building an HTML widget markdown string.
  */
@@ -16,7 +56,162 @@ export interface IHtmlWidgetMarkdownOptions {
 }
 
 /**
- * Wraps an HTML widget payload in the ```html-widget markdown code fence format.
+ * Options for injecting the MCP Apps protocol into widget HTML.
+ */
+export interface IInjectWidgetProtocolOptions {
+  /**
+   * The widget app name sent during ui/initialize.
+   * @default 'widget'
+   */
+  name?: string;
+
+  /**
+   * The widget app version sent during ui/initialize.
+   * @default '1.0.0'
+   */
+  version?: string;
+
+  /**
+   * Capabilities declared to the host during the `ui/initialize` handshake.
+   * Sent as `appCapabilities` in the init request per the MCP Apps spec.
+   */
+  appCapabilities?: {
+    /**
+     * Display modes this widget supports. An array because a widget can
+     * declare support for multiple modes (e.g. both inline and fullscreen).
+     * The host uses this to determine which mode transitions to offer the user.
+     *
+     * Note: 'pip' is defined in the MCP Apps spec but not yet supported by Teams.
+     *
+     * @example ['inline', 'fullscreen']
+     */
+    availableDisplayModes?: Array<'inline' | 'fullscreen' | 'pip'>;
+  };
+
+  /**
+   * Host notifications to listen for. These correspond to JSON-RPC methods
+   * defined in the MCP Apps spec under `ui/notifications/*`. For each
+   * notification included, define the matching `window.onX` callback in
+   * your widget HTML to handle it.
+   *
+   * Known notifications (from the MCP Apps spec):
+   * - `'tool-result'` (`ui/notifications/tool-result`) - define `window.onToolResult`
+   * - `'tool-input'` (`ui/notifications/tool-input`) - define `window.onToolInput`
+   * - `'tool-input-partial'` (`ui/notifications/tool-input-partial`) - define `window.onToolInputPartial`
+   * - `'tool-cancelled'` (`ui/notifications/tool-cancelled`) - define `window.onToolCancelled`
+   * - `'host-context-changed'` (`ui/notifications/host-context-changed`) - define `window.onHostContextChanged`
+   * - `'resource-teardown'` (`ui/notifications/resource-teardown`) - define `window.onResourceTeardown`
+   *
+   * Unknown notification names are ignored (only the above are injected).
+   *
+   * @default [] (no notification hooks injected)
+   */
+  notifications?: WidgetNotification[];
+}
+
+/**
+ * Explicit mapping of notification names to their window callback names.
+ * Only notifications in this map will have hooks injected.
+ *
+ * Confirmed in Teams spec: tool-result, tool-input
+ * Not yet available in Teams: tool-input-partial, tool-cancelled,
+ * host-context-changed, resource-teardown
+ */
+const NOTIFICATION_CALLBACKS: Record<string, string> = {
+  // Confirmed in Teams
+  'tool-result': 'onToolResult',
+  'tool-input': 'onToolInput',
+  // MCP Apps spec (SEP-1865) - not yet available in Teams
+  'tool-input-partial': 'onToolInputPartial',
+  'tool-cancelled': 'onToolCancelled',
+  'host-context-changed': 'onHostContextChanged',
+  'resource-teardown': 'onResourceTeardown',
+};
+
+/**
+ * Injects the MCP Apps protocol script into widget HTML.
+ *
+ * This is a convenience helper - widgets that implement the protocol themselves do not need to use it.
+ * {@link buildHtmlWidgetMarkdown} calls this internally, so most developers won't call it directly.
+ *
+ * This sets up:
+ * - The ui/initialize handshake (required for rendering)
+ * - Size reporting via ui/notifications/size-changed
+ * - Optional notification hooks (opt-in via `notifications` option)
+ *
+ * If the HTML already contains the protocol (detected by the presence of `ui/initialize`), it is returned unchanged.
+ *
+ * @param html - The raw HTML content for the widget.
+ * @param options - Optional configuration for the protocol setup.
+ * @returns The HTML with the protocol script injected.
+ */
+export function injectWidgetProtocol(
+  html: string,
+  options?: IInjectWidgetProtocolOptions
+): string {
+  if (html.includes('ui/initialize')) {
+    return html;
+  }
+
+  const name = options?.name ?? 'widget';
+  const version = options?.version ?? '1.0.0';
+  const caps = options?.appCapabilities;
+  const capsJson = caps?.availableDisplayModes
+    ? `{availableDisplayModes:${JSON.stringify(caps.availableDisplayModes)}}`
+    : '{}';
+
+  // Build inline JS that dispatches incoming JSON-RPC notifications to
+  // the corresponding window.onX callback defined by the developer.
+  const notifications = options?.notifications ?? [];
+  const hookLines = notifications
+    .filter((n) => n in NOTIFICATION_CALLBACKS)
+    .map((n) => {
+      const method = `ui/notifications/${n}`;
+      const cb = NOTIFICATION_CALLBACKS[n];
+      return `if(d.method==='${method}'&&window.${cb}){window.${cb}(d.params);}`;
+    }).join('');
+
+  // Assemble the protocol script (minified for payload size):
+  // - Generate a unique request ID for the init handshake
+  // - Define notifySize to report body height to the host
+  // - Listen for messages: on init response, send initialized + size;
+  //   on known notifications, dispatch to window.onX callbacks
+  // - Send ui/initialize request with app info and capabilities
+  // - Report size on DOMContentLoaded
+  const script = '<script>(function(){'
+    + 'var id=\'init-\'+Math.random().toString(36).slice(2);'
+    + 'function notifySize(){window.parent.postMessage({jsonrpc:\'2.0\',method:\'ui/notifications/size-changed\',params:{height:document.body.scrollHeight}},\'*\');}'
+    + 'window.addEventListener(\'message\',function(e){var d=e.data;if(!d||d.jsonrpc!==\'2.0\')return;'
+    + 'if(d.id===id&&d.result){window.parent.postMessage({jsonrpc:\'2.0\',method:\'ui/notifications/initialized\'},\'*\');setTimeout(notifySize,100);}'
+    + hookLines
+    + '});'
+    + `window.parent.postMessage({jsonrpc:'2.0',id:id,method:'ui/initialize',params:{protocolVersion:'${MCP_PROTOCOL_VERSION}',appInfo:{name:'${name}',version:'${version}'},appCapabilities:${capsJson}}},'*');`
+    + 'document.addEventListener(\'DOMContentLoaded\',notifySize);'
+    + '})()</script>';
+
+  // Inject before </body> if present, otherwise append
+  if (html.includes('</body>')) {
+    return html.replace('</body>', script + '</body>');
+  }
+
+  return html + script;
+}
+
+/**
+ * Default security policy applied when none is specified.
+ * Follows the MCP Apps spec recommendation of restrictive defaults:
+ * no external network access, self + data URIs for resources only.
+ */
+const DEFAULT_SECURITY_POLICY: Required<IHtmlWidgetPayload>['securityPolicy'] = {
+  connectDomains: [],
+  resourceDomains: ['\'self\'', 'data:'],
+  frameDomains: [],
+  baseUriDomains: [],
+};
+
+/**
+ * Wraps an HTML widget payload in the ` ```html-widget ` markdown code fence
+ * format required by Teams to render the widget in a message.
  *
  * @param payload - The widget payload to serialize.
  * @param options - Optional text to include before/after the widget block.
@@ -26,7 +221,14 @@ export function buildHtmlWidgetMarkdown(
   payload: IHtmlWidgetPayload,
   options?: IHtmlWidgetMarkdownOptions
 ): string {
-  const json = JSON.stringify(payload);
+  validateHtmlWidgetPayload(payload);
+
+  const injectedPayload = {
+    ...payload,
+    html: injectWidgetProtocol(payload.html, { name: payload.name }),
+    securityPolicy: payload.securityPolicy ?? DEFAULT_SECURITY_POLICY,
+  };
+  const json = JSON.stringify(injectedPayload);
   const parts: string[] = [];
 
   if (options?.before) {

From a1edda5625e8851bade0e6c833d2f02ca03f8f7a Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Thu, 25 Jun 2026 10:52:23 -0700
Subject: [PATCH 05/12] Add html-widgets example bot

---
 examples/html-widgets/README.md               |  62 +++
 examples/html-widgets/package.json            |  31 ++
 examples/html-widgets/src/index.ts            | 359 ++++++++++++++++++
 examples/html-widgets/src/widgets/calltool.ts |   8 +
 .../html-widgets/src/widgets/fullscreen.ts    |   7 +
 .../html-widgets/src/widgets/host-context.ts  |  92 +++++
 .../html-widgets/src/widgets/messageback.ts   |   8 +
 .../html-widgets/src/widgets/multi-tool.ts    |   8 +
 .../html-widgets/src/widgets/open-link.ts     |  58 +++
 examples/html-widgets/src/widgets/simple.ts   |   8 +
 .../src/widgets/update-context.ts             |  91 +++++
 examples/html-widgets/tsconfig.json           |   8 +
 12 files changed, 740 insertions(+)
 create mode 100644 examples/html-widgets/README.md
 create mode 100644 examples/html-widgets/package.json
 create mode 100644 examples/html-widgets/src/index.ts
 create mode 100644 examples/html-widgets/src/widgets/calltool.ts
 create mode 100644 examples/html-widgets/src/widgets/fullscreen.ts
 create mode 100644 examples/html-widgets/src/widgets/host-context.ts
 create mode 100644 examples/html-widgets/src/widgets/messageback.ts
 create mode 100644 examples/html-widgets/src/widgets/multi-tool.ts
 create mode 100644 examples/html-widgets/src/widgets/open-link.ts
 create mode 100644 examples/html-widgets/src/widgets/simple.ts
 create mode 100644 examples/html-widgets/src/widgets/update-context.ts
 create mode 100644 examples/html-widgets/tsconfig.json

diff --git a/examples/html-widgets/README.md b/examples/html-widgets/README.md
new file mode 100644
index 000000000..5b42ad77a
--- /dev/null
+++ b/examples/html-widgets/README.md
@@ -0,0 +1,62 @@
+# HTML Widgets Example
+
+This example bot demonstrates the HTML widget contract for Teams bots using the Teams SDK.
+
+## What it tests
+
+| Command | Purpose | Widget callbacks |
+|---------|---------|-----------------|
+| `/simple` | Static widget rendering | None |
+| `/calltool` | Widget calling bot tools | `htmlwidget/calltool` invoke |
+| `/messageback` | Widget sending messageBack | `onMessage` |
+| `/fullscreen` | Widget requesting display mode change | `onRequestDisplayMode` (client-side) |
+| `/multi` | Multiple tool dispatch | `htmlwidget/calltool` with different tool names |
+| `/raw` | Direct markdown helper usage | None |
+| `/permissions` | Widget requesting permissions | None (host-enforced) |
+
+## Architecture
+
+```
+Bot sends message:
+  textFormat: 'extendedmarkdown'
+  text: "...\n```html-widget\n{JSON payload}\n```"
+
+Teams client:
+  McpWidgetRenderer loads widget HTML in sandboxed iframe
+  @modelcontextprotocol/ext-apps SDK provides callServerTool API
+
+Widget calls tool:
+  ext-apps SDK -> postMessage -> McpWidgetRenderer -> htmlwidget/calltool invoke -> Bot
+
+Bot returns:
+  { status: 200, body: { content: [...], structuredContent: {...}, isError: false } }
+```
+
+## Running
+
+1. Copy credentials:
+   ```
+   cp ../../../bots/.env .env
+   ```
+
+2. Start a devtunnel and update the Azure Bot endpoint
+
+3. Run the bot:
+   ```
+   npm run dev
+   ```
+
+4. In Teams, message the bot with `/help` to see available commands
+
+## Note on widget HTML
+
+The widget HTML in `src/widgets/` is static HTML for rendering verification.
+Interactive behavior (callTool, messageBack, displayMode) requires the
+`@modelcontextprotocol/ext-apps` SDK which is provided by the Teams widget host
+page (`mcpwidget.html` on `widget-renderer.usercontent.microsoft`).
+
+The bot-side code (`widget.callTool` handler in `src/index.ts`) is the primary
+test target. It verifies that:
+- The SDK's invoke route alias correctly matches `htmlwidget/calltool`
+- The typed handler receives `{ name, arguments }` in `activity.value`
+- The response body format (`McpUiCallToolResult`) is accepted by the client
diff --git a/examples/html-widgets/package.json b/examples/html-widgets/package.json
new file mode 100644
index 000000000..30685e433
--- /dev/null
+++ b/examples/html-widgets/package.json
@@ -0,0 +1,31 @@
+{
+  "name": "@examples/html-widgets",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "main": "dist/index",
+  "types": "dist/index",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "npx rimraf ./dist",
+    "lint": "npx eslint",
+    "lint:fix": "npx eslint --fix",
+    "build": "npx tsc",
+    "start": "node .",
+    "dev": "tsx watch -r dotenv/config src/index.ts"
+  },
+  "dependencies": {
+    "@microsoft/teams.apps": "*"
+  },
+  "devDependencies": {
+    "@microsoft/teams.config": "*",
+    "@types/node": "^22.5.4",
+    "dotenv": "^16.4.5",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.4.5"
+  }
+}
diff --git a/examples/html-widgets/src/index.ts b/examples/html-widgets/src/index.ts
new file mode 100644
index 000000000..728897f48
--- /dev/null
+++ b/examples/html-widgets/src/index.ts
@@ -0,0 +1,359 @@
+/**
+ * HTML Widgets Example Bot
+ *
+ * This example demonstrates the full HTML widget contract for Teams bots.
+ * Commands are annotated to distinguish between:
+ *   - [CONTRACT TEST] Tests that verify the contract works end-to-end
+ *   - [EXAMPLE] Code patterns useful for customers building widget bots
+ */
+
+import { App, buildHtmlWidgetMarkdown, buildHtmlWidgetMessage } from '@microsoft/teams.apps';
+import { IMcpUiCallToolResult } from '@microsoft/teams.api';
+import { ConsoleLogger } from '@microsoft/teams.common';
+
+import { SIMPLE_WIDGET_HTML } from './widgets/simple';
+import { CALLTOOL_WIDGET_HTML } from './widgets/calltool';
+import { MESSAGEBACK_WIDGET_HTML } from './widgets/messageback';
+import { FULLSCREEN_WIDGET_HTML } from './widgets/fullscreen';
+import { MULTI_WIDGET_HTML } from './widgets/multi-tool';
+import { OPEN_LINK_WIDGET_HTML } from './widgets/open-link';
+import { UPDATE_CONTEXT_WIDGET_HTML } from './widgets/update-context';
+import { HOST_CONTEXT_WIDGET_HTML } from './widgets/host-context';
+
+const app = new App({
+  logger: new ConsoleLogger('@examples/html-widgets', { level: 'debug' }),
+});
+
+// ---------------------------------------------------------------------------
+// [EXAMPLE] Simple static widget - no callbacks
+// Shows the minimal code to send an HTML widget.
+// ---------------------------------------------------------------------------
+app.on('message', async ({ send, activity }) => {
+  if (!activity.text) return;
+  const text = activity.text.trim().toLowerCase();
+
+  if (text === '/simple') {
+    const message = buildHtmlWidgetMessage(
+      {
+        type: 'widget/mcp-ui',
+        name: 'Simple Widget',
+        description: 'A static HTML widget with no callbacks.',
+        html: SIMPLE_WIDGET_HTML,
+        domain: 'https://teams.microsoft.com',
+        securityPolicy: {
+          connectDomains: [],
+          resourceDomains: ["'self'", 'data:'],
+          frameDomains: [],
+          baseUriDomains: [],
+        },
+        permissions: {},
+      },
+      { before: 'Here is a simple static widget:' }
+    );
+    await send(message);
+    return;
+  }
+
+  // ---------------------------------------------------------------------------
+  // [EXAMPLE] Widget with onCallTool callback
+  // The widget calls tools on the bot and re-renders with the result.
+  // ---------------------------------------------------------------------------
+  if (text === '/calltool') {
+    const message = buildHtmlWidgetMessage(
+      {
+        type: 'widget/mcp-ui',
+        name: 'CallTool Widget',
+        description: 'Widget that calls tools on the bot.',
+        html: CALLTOOL_WIDGET_HTML,
+        domain: 'https://teams.microsoft.com',
+        securityPolicy: {
+          connectDomains: ['https://teams.microsoft.com', 'https://teams.cloud.microsoft.com'],
+          resourceDomains: ["'self'", 'data:'],
+          frameDomains: [],
+          baseUriDomains: [],
+        },
+        toolInput: { demo: true },
+        toolOutput: {
+          content: [{ type: 'text', text: 'Initial data loaded.' }],
+          structuredContent: { counter: 0, lastAction: 'init' },
+          isError: false,
+        },
+        permissions: {},
+      },
+      { before: 'Here is a widget with callTool support (click Refresh):' }
+    );
+    await send(message);
+    return;
+  }
+
+  // ---------------------------------------------------------------------------
+  // [CONTRACT TEST] Widget with onMessage (messageBack) callback
+  // Tests that the widget can send messageBack to the bot.
+  // ---------------------------------------------------------------------------
+  if (text === '/messageback') {
+    const message = buildHtmlWidgetMessage(
+      {
+        type: 'widget/mcp-ui',
+        name: 'MessageBack Widget',
+        description: 'Widget that sends messageBack to the bot.',
+        html: MESSAGEBACK_WIDGET_HTML,
+        domain: 'https://teams.microsoft.com',
+        securityPolicy: {
+          connectDomains: [],
+          resourceDomains: ["'self'", 'data:'],
+          frameDomains: [],
+          baseUriDomains: [],
+        },
+        permissions: {},
+      },
+      { before: 'This widget tests the onMessage (messageBack) callback:' }
+    );
+    await send(message);
+    return;
+  }
+
+  // ---------------------------------------------------------------------------
+  // [CONTRACT TEST] Widget requesting fullscreen display mode
+  // Tests onRequestDisplayMode with "fullscreen" value.
+  // ---------------------------------------------------------------------------
+  if (text === '/fullscreen') {
+    const message = buildHtmlWidgetMessage(
+      {
+        type: 'widget/mcp-ui',
+        name: 'Fullscreen Widget',
+        description: 'Widget that requests fullscreen mode.',
+        html: FULLSCREEN_WIDGET_HTML,
+        domain: 'https://teams.microsoft.com',
+        securityPolicy: {
+          connectDomains: [],
+          resourceDomains: ["'self'", 'data:'],
+          frameDomains: [],
+          baseUriDomains: [],
+        },
+        permissions: {},
+      },
+      { before: 'This widget will request fullscreen mode:' }
+    );
+    await send(message);
+    return;
+  }
+
+  // ---------------------------------------------------------------------------
+  // [CONTRACT TEST] Widget with multiple tools
+  // Tests that calltool dispatches correctly by tool name.
+  // ---------------------------------------------------------------------------
+  if (text === '/multi') {
+    const message = buildHtmlWidgetMessage(
+      {
+        type: 'widget/mcp-ui',
+        name: 'Multi-Tool Widget',
+        description: 'Widget that calls multiple different tools.',
+        html: MULTI_WIDGET_HTML,
+        domain: 'https://teams.microsoft.com',
+        securityPolicy: {
+          connectDomains: ['https://teams.microsoft.com'],
+          resourceDomains: ["'self'", 'data:'],
+          frameDomains: [],
+          baseUriDomains: [],
+        },
+        toolInput: {},
+        toolOutput: {
+          content: [{ type: 'text', text: 'Ready.' }],
+          structuredContent: { tools: ['getTime', 'roll', 'echo'] },
+          isError: false,
+        },
+        permissions: {},
+      },
+      { before: 'This widget has multiple tools to test dispatch:' }
+    );
+    await send(message);
+    return;
+  }
+
+  // ---------------------------------------------------------------------------
+  // [CONTRACT TEST] Raw markdown test - verifies extendedmarkdown format works
+  // Uses buildHtmlWidgetMarkdown directly for more control.
+  // ---------------------------------------------------------------------------
+  if (text === '/raw') {
+    const markdown = buildHtmlWidgetMarkdown(
+      {
+        type: 'widget/mcp-ui',
+        name: 'Raw Test',
+        description: 'Testing raw markdown assembly.',
+        html: SIMPLE_WIDGET_HTML,
+        domain: 'https://teams.microsoft.com',
+      },
+      { before: 'Text before widget.', after: 'Text after widget.' }
+    );
+    await send({ type: 'message', text: markdown, textFormat: 'extendedmarkdown' });
+    return;
+  }
+
+  // ---------------------------------------------------------------------------
+  // [CONTRACT TEST] Widget with permissions requested
+  // Tests that the permissions field is accepted by the host.
+  // ---------------------------------------------------------------------------
+  if (text === '/permissions') {
+    const message = buildHtmlWidgetMessage(
+      {
+        type: 'widget/mcp-ui',
+        name: 'Permissions Widget',
+        description: 'Widget requesting clipboard and geolocation.',
+        html: SIMPLE_WIDGET_HTML,
+        domain: 'https://teams.microsoft.com',
+        securityPolicy: {
+          connectDomains: [],
+          resourceDomains: ["'self'"],
+          frameDomains: [],
+          baseUriDomains: [],
+        },
+        permissions: {
+          clipboardWrite: {},
+          geolocation: {},
+        },
+      },
+      { before: 'This widget requests permissions (clipboard + geolocation):' }
+    );
+    await send(message);
+    return;
+  }
+
+  // [CONTRACT TEST] ui/open-link method
+  if (text === '/openlink') {
+    const message = buildHtmlWidgetMessage(
+      {
+        type: 'widget/mcp-ui',
+        name: 'open-link-test',
+        html: OPEN_LINK_WIDGET_HTML,
+        domain: 'https://teams.microsoft.com',
+      },
+      { before: 'Widget with ui/open-link support (click a button to open a URL):' }
+    );
+    await send(message);
+    return;
+  }
+
+  // [CONTRACT TEST] ui/update-model-context method
+  if (text === '/context') {
+    const message = buildHtmlWidgetMessage(
+      {
+        type: 'widget/mcp-ui',
+        name: 'update-context-test',
+        html: UPDATE_CONTEXT_WIDGET_HTML,
+        domain: 'https://teams.microsoft.com',
+      },
+      { before: 'Widget with ui/update-model-context support:' }
+    );
+    await send(message);
+    return;
+  }
+
+  // [CONTRACT TEST] Host context inspector - shows what hostContext is returned
+  if (text === '/hostcontext') {
+    const message = buildHtmlWidgetMessage(
+      {
+        type: 'widget/mcp-ui',
+        name: 'host-context-inspector',
+        html: HOST_CONTEXT_WIDGET_HTML,
+        domain: 'https://teams.microsoft.com',
+      },
+      { before: 'Widget that inspects hostContext from ui/initialize:' }
+    );
+    await send(message);
+    return;
+  }
+
+  // Default: show help
+  if (text === '/help' || text === 'help') {
+    await send(
+      '**HTML Widget Test Commands:**\n\n' +
+      '- `/simple` - Static widget (no callbacks)\n' +
+      '- `/calltool` - Widget with onCallTool\n' +
+      '- `/messageback` - Widget with onMessage\n' +
+      '- `/fullscreen` - Widget requesting fullscreen\n' +
+      '- `/multi` - Widget with multiple tools\n' +
+      '- `/raw` - Raw markdown with before/after text\n' +
+      '- `/permissions` - Widget requesting permissions\n' +
+      '- `/openlink` - Widget with ui/open-link\n' +
+      '- `/context` - Widget with ui/update-model-context\n' +
+      '- `/hostcontext` - Inspect hostContext from initialize\n' +
+      '- `/help` - This message'
+    );
+    return;
+  }
+
+  // Handle messageBack values from the messageback widget
+  if (activity.value) {
+    await send(`Received messageBack value: ${JSON.stringify(activity.value)}`);
+    return;
+  }
+
+  await send('Send `/help` for available widget test commands.');
+});
+
+// ---------------------------------------------------------------------------
+// [EXAMPLE] Handle htmlwidget/calltool invoke
+// This is the typed handler for when a widget calls a tool on the bot.
+// ---------------------------------------------------------------------------
+app.on('widget.callTool', async ({ activity }) => {
+  const { name, arguments: args } = activity.value;
+  console.log(`[widget.callTool] tool="${name}" args=${JSON.stringify(args)}`);
+
+  let callToolResult: IMcpUiCallToolResult;
+  switch (name) {
+    case 'refresh':
+      callToolResult = {
+        content: [{ type: 'text', text: 'Refreshed!' }],
+        structuredContent: {
+          counter: ((args as any)?.counter ?? 0) + 1,
+          lastAction: 'refresh',
+          timestamp: new Date().toISOString(),
+        },
+        isError: false,
+      };
+      break;
+
+    case 'getTime':
+      callToolResult = {
+        content: [{ type: 'text', text: new Date().toLocaleTimeString() }],
+        structuredContent: { time: new Date().toISOString() },
+        isError: false,
+      };
+      break;
+
+    case 'roll': {
+      const sides = (args as any)?.sides ?? 6;
+      const result = Math.floor(Math.random() * sides) + 1;
+      callToolResult = {
+        content: [{ type: 'text', text: `Rolled a ${result} (d${sides})` }],
+        structuredContent: { result, sides },
+        isError: false,
+      };
+      break;
+    }
+
+    case 'echo':
+      callToolResult = {
+        content: [{ type: 'text', text: JSON.stringify(args) }],
+        structuredContent: args,
+        isError: false,
+      };
+      break;
+
+    default:
+      callToolResult = {
+        content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+        isError: true,
+      };
+      break;
+  }
+
+  console.log(`[widget.callTool] result=`, JSON.stringify(callToolResult));
+
+  return {
+    responseType: 'htmlwidget/calltoolresult',
+    callToolResult,
+  };
+});
+
+app.start(process.env.PORT || 3978).catch(console.error);
diff --git a/examples/html-widgets/src/widgets/calltool.ts b/examples/html-widgets/src/widgets/calltool.ts
new file mode 100644
index 000000000..97e9e9ab7
--- /dev/null
+++ b/examples/html-widgets/src/widgets/calltool.ts
@@ -0,0 +1,8 @@
+/**
+ * CallTool widget - calls a "refresh" tool on the bot and displays the result.
+ *
+ * This HTML includes the interactive calltool behavior (tools/call) since
+ * that is widget-specific logic, not boilerplate. The example bot uses
+ * injectWidgetProtocol() automatically via the builders.
+ */
+export const CALLTOOL_WIDGET_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;overflow:auto}body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}h3{margin:0 0 8px 0}p{margin:0 0 12px 0;color:#666}button{padding:8px 16px;background:#5b5fc7;color:#fff;border:none;border-radius:4px;cursor:pointer}button:hover{background:#4b4fb7}#result{margin-top:12px;padding:8px;background:#f5f5f5;border-radius:4px}</style></head><body><h3>CallTool Widget</h3><p>Click Refresh to call the bot's "refresh" tool.</p><button id="refreshBtn">Refresh</button><div id="result">Waiting for action...</div><script>(function(){var callId=0;document.getElementById('refreshBtn').addEventListener('click',function(){var id='call-'+(++callId);document.getElementById('result').textContent='Calling refresh...';window.parent.postMessage({jsonrpc:'2.0',id:id,method:'tools/call',params:{name:'refresh',arguments:{}}},'*');});window.addEventListener('message',function(e){var d=e.data;if(d&&d.jsonrpc==='2.0'&&d.id&&typeof d.id==='string'&&d.id.startsWith('call-')){if(d.result)document.getElementById('result').textContent=JSON.stringify(d.result);if(d.error)document.getElementById('result').textContent='Error: '+JSON.stringify(d.error);}});})()</script></body></html>`;
diff --git a/examples/html-widgets/src/widgets/fullscreen.ts b/examples/html-widgets/src/widgets/fullscreen.ts
new file mode 100644
index 000000000..f693b2cd3
--- /dev/null
+++ b/examples/html-widgets/src/widgets/fullscreen.ts
@@ -0,0 +1,7 @@
+/**
+ * Fullscreen widget - requests fullscreen display mode from the host.
+ *
+ * Uses requestDisplayMode to ask the Teams host for fullscreen mode.
+ * The example bot uses injectWidgetProtocol() automatically via the builders.
+ */
+export const FULLSCREEN_WIDGET_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;overflow:auto}body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}h3{margin:0 0 8px 0}p{margin:0 0 12px 0;color:#666}button{padding:8px 16px;background:#107c10;color:#fff;border:none;border-radius:4px;cursor:pointer}button:hover{background:#0e6b0e}#content{margin-top:12px;padding:16px;background:#f0fff0;border-radius:4px}#modeLabel{font-weight:600}</style></head><body><h3>Fullscreen Widget</h3><p>Click the button to request fullscreen mode from Teams.</p><button id="fsBtn">Go Fullscreen</button><div id="content"><p>In fullscreen mode, this widget will expand to fill the available space.</p><p>Current mode: <span id="modeLabel">inline</span></p></div><script>(function(){document.getElementById('fsBtn').addEventListener('click',function(){var id='fs-'+Math.random().toString(36).slice(2);window.parent.postMessage({jsonrpc:'2.0',id:id,method:'ui/request-display-mode',params:{mode:'fullscreen'}},'*');});window.addEventListener('message',function(e){var d=e.data;if(d&&d.jsonrpc==='2.0'){if(d.result&&d.result.mode)document.getElementById('modeLabel').textContent=d.result.mode;if(d.error)document.getElementById('modeLabel').textContent='Error: '+JSON.stringify(d.error);}});})()</script></body></html>`;
diff --git a/examples/html-widgets/src/widgets/host-context.ts b/examples/html-widgets/src/widgets/host-context.ts
new file mode 100644
index 000000000..35bfa9e99
--- /dev/null
+++ b/examples/html-widgets/src/widgets/host-context.ts
@@ -0,0 +1,92 @@
+/**
+ * Host Context widget - displays the hostContext received during ui/initialize.
+ * Shows theme, display mode, container dimensions, locale, etc.
+ * Also listens for ui/notifications/host-context-changed.
+ */
+export const HOST_CONTEXT_WIDGET_HTML = `<!DOCTYPE html>
+<html><head><meta charset="utf-8">
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+html,body{height:100%;overflow:auto}
+body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}
+h3{margin:0 0 8px}
+.section{margin-top:12px;padding:8px;background:#f0f9ff;border-radius:4px}
+.section h4{margin:0 0 4px;font-size:12px;color:#333}
+pre{white-space:pre-wrap;word-break:break-all;font-family:monospace;font-size:11px;color:#555}
+.update{margin-top:8px;padding:6px;background:#fff3cd;border-radius:4px;font-size:11px}
+</style></head><body>
+<h3>Host Context Inspector</h3>
+<p>Displays the <code>hostContext</code> from <code>ui/initialize</code> response and listens for changes.</p>
+<div class="section">
+  <h4>Initialize Result</h4>
+  <pre id="initResult">Waiting for initialize...</pre>
+</div>
+<div class="section">
+  <h4>Host Context</h4>
+  <pre id="hostContext">-</pre>
+</div>
+<div class="section">
+  <h4>Host Capabilities</h4>
+  <pre id="hostCaps">-</pre>
+</div>
+<div id="updates"></div>
+<script>
+let nextId = 100;
+const pending = {};
+
+window.addEventListener('message', (event) => {
+  const data = event.data;
+  if (!data || typeof data !== 'object') return;
+
+  // Handle responses to our requests
+  if (data.id && pending[data.id]) {
+    pending[data.id](data);
+    return;
+  }
+
+  // Handle notifications from host
+  if (data.method === 'ui/notifications/host-context-changed') {
+    const el = document.getElementById('updates');
+    const div = document.createElement('div');
+    div.className = 'update';
+    div.textContent = '[' + new Date().toLocaleTimeString() + '] host-context-changed: ' + JSON.stringify(data.params);
+    el.appendChild(div);
+
+    // Update main display
+    if (data.params) {
+      document.getElementById('hostContext').textContent = JSON.stringify(data.params, null, 2);
+    }
+  }
+});
+
+function sendRequest(method, params) {
+  const id = nextId++;
+  return new Promise((resolve) => {
+    pending[id] = resolve;
+    window.parent.postMessage({ jsonrpc: '2.0', id, method, params }, '*');
+  });
+}
+
+async function init() {
+  const response = await sendRequest('ui/initialize', {
+    protocolVersion: '2026-01-26',
+    appInfo: { name: 'host-context-inspector', version: '1.0.0' },
+    appCapabilities: {}
+  });
+
+  document.getElementById('initResult').textContent = JSON.stringify(response.result || response.error, null, 2);
+
+  if (response.result) {
+    const ctx = response.result.hostContext;
+    const caps = response.result.hostCapabilities;
+    document.getElementById('hostContext').textContent = ctx ? JSON.stringify(ctx, null, 2) : '(none provided)';
+    document.getElementById('hostCaps').textContent = caps ? JSON.stringify(caps, null, 2) : '(none provided)';
+  }
+
+  // Send initialized notification
+  window.parent.postMessage({ jsonrpc: '2.0', method: 'ui/notifications/initialized', params: {} }, '*');
+}
+
+init();
+</script>
+</body></html>`;
diff --git a/examples/html-widgets/src/widgets/messageback.ts b/examples/html-widgets/src/widgets/messageback.ts
new file mode 100644
index 000000000..b67fe7135
--- /dev/null
+++ b/examples/html-widgets/src/widgets/messageback.ts
@@ -0,0 +1,8 @@
+/**
+ * MessageBack widget - sends a messageBack action to the bot.
+ *
+ * Uses the ui/message method to send a message to the conversation,
+ * similar to messageBack in Adaptive Cards. The example bot uses
+ * injectWidgetProtocol() automatically via the builders.
+ */
+export const MESSAGEBACK_WIDGET_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;overflow:auto}body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}h3{margin:0 0 8px 0}p{margin:0 0 12px 0;color:#666}button{padding:8px 16px;background:#0078d4;color:#fff;border:none;border-radius:4px;cursor:pointer}button:hover{background:#006cbd}#status{margin-top:12px;color:#666}</style></head><body><h3>MessageBack Widget</h3><p>Click the button to send a messageBack to the bot.</p><button id="msgBtn">Send MessageBack</button><div id="status"></div><script>(function(){document.getElementById('msgBtn').addEventListener('click',function(){var msgId='msg-'+Math.random().toString(36).slice(2);document.getElementById('status').textContent='Sending messageBack...';window.parent.postMessage({jsonrpc:'2.0',id:msgId,method:'ui/message',params:{role:'user',content:[{type:'text',text:'Hello from the widget!'}]}},'*');document.getElementById('status').textContent='MessageBack sent!';});})()</script></body></html>`;
diff --git a/examples/html-widgets/src/widgets/multi-tool.ts b/examples/html-widgets/src/widgets/multi-tool.ts
new file mode 100644
index 000000000..0083565c9
--- /dev/null
+++ b/examples/html-widgets/src/widgets/multi-tool.ts
@@ -0,0 +1,8 @@
+/**
+ * Multi-tool widget - calls multiple different tools on the bot.
+ *
+ * Each button calls tools/call with a different tool name. Teams routes
+ * each as an `htmlwidget/calltool` invoke activity to the bot. The example
+ * bot uses injectWidgetProtocol() automatically via the builders.
+ */
+export const MULTI_WIDGET_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;overflow:auto}body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}h3{margin:0 0 8px 0}p{margin:0 0 12px 0;color:#666}.tools{display:flex;gap:8px;flex-wrap:wrap}.tools button{padding:8px 12px;color:#fff;border:none;border-radius:4px;cursor:pointer}#log{margin-top:12px;padding:8px;background:#1e1e1e;color:#d4d4d4;border-radius:4px;font-family:monospace;font-size:12px;max-height:200px;overflow-y:auto}</style></head><body><h3>Multi-Tool Widget</h3><p>Each button calls a different tool on the bot.</p><div class="tools"><button data-tool="getTime" style="background:#5b5fc7">Get Time</button><button data-tool="roll" data-args='{"sides":20}' style="background:#c75b5b">Roll d20</button><button data-tool="echo" data-args='{"hello":"world"}' style="background:#5bc75b">Echo</button><button data-tool="unknownTool" style="background:#999">Unknown (error)</button></div><div id="log">Available tools: getTime, roll, echo, unknownTool</div><script>(function(){var callId=0;var log=document.getElementById('log');document.querySelectorAll('[data-tool]').forEach(function(btn){btn.addEventListener('click',function(){var tool=btn.getAttribute('data-tool');var args=btn.getAttribute('data-args');var id='call-'+(++callId);log.textContent+='\\nCalling '+tool+'...';window.parent.postMessage({jsonrpc:'2.0',id:id,method:'tools/call',params:{name:tool,arguments:args?JSON.parse(args):{}}},'*');});});window.addEventListener('message',function(e){var d=e.data;if(d&&d.jsonrpc==='2.0'&&d.id&&typeof d.id==='string'&&d.id.startsWith('call-')){if(d.result)log.textContent+='\\nResult: '+JSON.stringify(d.result);if(d.error)log.textContent+='\\nError: '+JSON.stringify(d.error);}});})()</script></body></html>`;
diff --git a/examples/html-widgets/src/widgets/open-link.ts b/examples/html-widgets/src/widgets/open-link.ts
new file mode 100644
index 000000000..0057ac89b
--- /dev/null
+++ b/examples/html-widgets/src/widgets/open-link.ts
@@ -0,0 +1,58 @@
+/**
+ * Open Link widget - tests ui/open-link method.
+ * Clicking a button asks the host to open a URL in the user's browser.
+ */
+export const OPEN_LINK_WIDGET_HTML = `<!DOCTYPE html>
+<html><head><meta charset="utf-8">
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+html,body{height:100%;overflow:auto}
+body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}
+h3{margin:0 0 8px}
+button{margin:4px 4px 4px 0;padding:6px 12px;border:1px solid #ccc;border-radius:4px;background:#f5f5f5;cursor:pointer;font-size:12px}
+button:hover{background:#e0e0e0}
+#status{margin-top:12px;padding:8px;background:#f0f9ff;border-radius:4px;white-space:pre-wrap;font-family:monospace;font-size:11px}
+</style></head><body>
+<h3>Open Link Widget</h3>
+<p>Tests the <code>ui/open-link</code> method (host opens a URL).</p>
+<div style="margin-top:12px">
+  <button onclick="openLink('https://github.com/modelcontextprotocol/ext-apps')">Open MCP Apps Repo</button>
+  <button onclick="openLink('https://learn.microsoft.com/en-us/microsoftteams/')">Open Teams Docs</button>
+  <button onclick="openLink('not-a-valid-url')">Open Invalid URL (error test)</button>
+</div>
+<div id="status">Waiting...</div>
+<script>
+let nextId = 100;
+const pending = {};
+
+window.addEventListener('message', (event) => {
+  const data = event.data;
+  if (data?.id && pending[data.id]) {
+    pending[data.id](data);
+  }
+});
+
+function sendRequest(method, params) {
+  const id = nextId++;
+  return new Promise((resolve) => {
+    pending[id] = resolve;
+    window.parent.postMessage({ jsonrpc: '2.0', id, method, params }, '*');
+  });
+}
+
+async function openLink(url) {
+  const el = document.getElementById('status');
+  el.textContent = 'Opening: ' + url + '...';
+  try {
+    const response = await sendRequest('ui/open-link', { url });
+    if (response.error) {
+      el.textContent = 'Error: ' + JSON.stringify(response.error);
+    } else {
+      el.textContent = 'Success! Host opened: ' + url;
+    }
+  } catch (e) {
+    el.textContent = 'Exception: ' + e.message;
+  }
+}
+</script>
+</body></html>`;
diff --git a/examples/html-widgets/src/widgets/simple.ts b/examples/html-widgets/src/widgets/simple.ts
new file mode 100644
index 000000000..ff713a11c
--- /dev/null
+++ b/examples/html-widgets/src/widgets/simple.ts
@@ -0,0 +1,8 @@
+/**
+ * Simple static widget - no callbacks, no interactivity.
+ * Verifies that the host renders the HTML correctly.
+ *
+ * This is raw HTML without the MCP Apps protocol. The example bot uses
+ * injectWidgetProtocol() automatically via the builders.
+ */
+export const SIMPLE_WIDGET_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;overflow:auto}body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}h3{margin:0 0 8px 0;color:#333}p{margin:0;color:#666}.status{margin-top:12px;padding:8px;background:#f0f9ff;border-radius:4px}</style></head><body><h3>Simple HTML Widget</h3><p>This is a static HTML widget rendered inside a Teams message. No callbacks are needed.</p><div class="status"><strong>Status:</strong> Rendered successfully</div></body></html>`;
diff --git a/examples/html-widgets/src/widgets/update-context.ts b/examples/html-widgets/src/widgets/update-context.ts
new file mode 100644
index 000000000..331ab0389
--- /dev/null
+++ b/examples/html-widgets/src/widgets/update-context.ts
@@ -0,0 +1,91 @@
+/**
+ * Update Model Context widget - tests ui/update-model-context method.
+ * Sends structured context to the host that can be used by AI in future turns.
+ */
+export const UPDATE_CONTEXT_WIDGET_HTML = `<!DOCTYPE html>
+<html><head><meta charset="utf-8">
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+html,body{height:100%;overflow:auto}
+body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}
+h3{margin:0 0 8px}
+button{margin:4px 4px 4px 0;padding:6px 12px;border:1px solid #ccc;border-radius:4px;background:#f5f5f5;cursor:pointer;font-size:12px}
+button:hover{background:#e0e0e0}
+textarea{width:100%;height:60px;margin:8px 0;padding:8px;border:1px solid #ccc;border-radius:4px;font-family:monospace;font-size:11px;resize:vertical}
+#status{margin-top:12px;padding:8px;background:#f0f9ff;border-radius:4px;white-space:pre-wrap;font-family:monospace;font-size:11px}
+</style></head><body>
+<h3>Update Model Context Widget</h3>
+<p>Tests <code>ui/update-model-context</code> - sends context for AI to use in future turns.</p>
+<textarea id="contextInput">{"userPreference": "dark mode", "currentPage": "settings"}</textarea>
+<div>
+  <button onclick="sendStructuredContext()">Send Structured Context</button>
+  <button onclick="sendTextContext()">Send Text Context</button>
+  <button onclick="sendBoth()">Send Both</button>
+</div>
+<div id="status">Waiting...</div>
+<script>
+let nextId = 100;
+const pending = {};
+
+window.addEventListener('message', (event) => {
+  const data = event.data;
+  if (data?.id && pending[data.id]) {
+    pending[data.id](data);
+  }
+});
+
+function sendRequest(method, params) {
+  const id = nextId++;
+  return new Promise((resolve) => {
+    pending[id] = resolve;
+    window.parent.postMessage({ jsonrpc: '2.0', id, method, params }, '*');
+  });
+}
+
+async function sendStructuredContext() {
+  const el = document.getElementById('status');
+  const input = document.getElementById('contextInput').value;
+  let parsed;
+  try { parsed = JSON.parse(input); } catch (e) {
+    el.textContent = 'Invalid JSON in textarea';
+    return;
+  }
+  el.textContent = 'Sending structured context...';
+  const response = await sendRequest('ui/update-model-context', {
+    structuredContent: parsed
+  });
+  el.textContent = response.error
+    ? 'Error: ' + JSON.stringify(response.error)
+    : 'Success! Context updated with structured data.';
+}
+
+async function sendTextContext() {
+  const el = document.getElementById('status');
+  el.textContent = 'Sending text context...';
+  const response = await sendRequest('ui/update-model-context', {
+    content: [{ type: 'text', text: 'User is viewing the settings page and prefers dark mode.' }]
+  });
+  el.textContent = response.error
+    ? 'Error: ' + JSON.stringify(response.error)
+    : 'Success! Context updated with text content.';
+}
+
+async function sendBoth() {
+  const el = document.getElementById('status');
+  const input = document.getElementById('contextInput').value;
+  let parsed;
+  try { parsed = JSON.parse(input); } catch (e) {
+    el.textContent = 'Invalid JSON in textarea';
+    return;
+  }
+  el.textContent = 'Sending both text + structured context...';
+  const response = await sendRequest('ui/update-model-context', {
+    content: [{ type: 'text', text: 'User updated their preferences.' }],
+    structuredContent: parsed
+  });
+  el.textContent = response.error
+    ? 'Error: ' + JSON.stringify(response.error)
+    : 'Success! Context updated with both text and structured data.';
+}
+</script>
+</body></html>`;
diff --git a/examples/html-widgets/tsconfig.json b/examples/html-widgets/tsconfig.json
new file mode 100644
index 000000000..9a42fe553
--- /dev/null
+++ b/examples/html-widgets/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "@microsoft/teams.config/tsconfig.node.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"]
+}

From e28698a75f77c80ab9b1df2bb8cc5900386a4a5c Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Thu, 25 Jun 2026 10:52:43 -0700
Subject: [PATCH 06/12] Add html widgets integration tests

---
 test/integration/jest.config.ts           |   2 +-
 test/integration/src/fixture.ts           |   4 +-
 test/integration/src/html-widgets.test.ts | 146 ++++++++++++++++++++++
 3 files changed, 149 insertions(+), 3 deletions(-)
 create mode 100644 test/integration/src/html-widgets.test.ts

diff --git a/test/integration/jest.config.ts b/test/integration/jest.config.ts
index 313da5593..a30f7421e 100644
--- a/test/integration/jest.config.ts
+++ b/test/integration/jest.config.ts
@@ -6,7 +6,7 @@ const config: Config = {
     '^.+\\.ts$': 'ts-jest',
   },
   testEnvironment: 'node',
-  testTimeout: 15000,
+  testTimeout: 30000,
   // Run sequentially — tests share a conversation and can conflict if parallel
   maxWorkers: 1,
   verbose: true,
diff --git a/test/integration/src/fixture.ts b/test/integration/src/fixture.ts
index adf7985a5..db4457043 100644
--- a/test/integration/src/fixture.ts
+++ b/test/integration/src/fixture.ts
@@ -11,7 +11,7 @@ export interface TestConfig {
   userId: string;
   teamId: string;
   channelId: string;
-  meetingId: string;
+  meetingId?: string;
   userId2?: string;
   agenticAppId?: string;
   agenticUserId?: string;
@@ -46,7 +46,7 @@ function loadConfig(): TestConfig {
     userId: env('TEST_USER_ID'),
     teamId: env('TEST_TEAM_ID'),
     channelId: env('TEST_CHANNEL_ID'),
-    meetingId: env('TEST_MEETING_ID'),
+    meetingId: process.env['TEST_MEETING_ID'],
     userId2: process.env['TEST_USER_ID_2'],
     agenticAppId: process.env['TEST_AGENTIC_APP_ID'],
     agenticUserId: process.env['TEST_AGENTIC_USER_ID'],
diff --git a/test/integration/src/html-widgets.test.ts b/test/integration/src/html-widgets.test.ts
new file mode 100644
index 000000000..408ad7a10
--- /dev/null
+++ b/test/integration/src/html-widgets.test.ts
@@ -0,0 +1,146 @@
+import { getFixture, TestFixture } from './fixture';
+import { buildHtmlWidgetMarkdown } from '@microsoft/teams.apps';
+
+describe('HTML Widgets', () => {
+  let f: TestFixture;
+
+  beforeAll(async () => {
+    f = await getFixture();
+  });
+
+  it('should accept a widget message with extendedmarkdown textFormat', async () => {
+    if (!f.isCanary) return; // Widgets require canary service
+
+    const markdown = buildHtmlWidgetMarkdown(
+      {
+        type: 'widget/mcp-ui',
+        name: 'Integration Test Widget',
+        description: 'Verifies Teams accepts widget payload.',
+        html: '<body><p>Integration test widget</p></body>',
+        domain: 'https://teams.microsoft.com',
+        securityPolicy: {
+          connectDomains: [],
+          resourceDomains: ["'self'", 'data:'],
+          frameDomains: [],
+          baseUriDomains: [],
+        },
+        permissions: {},
+      },
+      { before: '[TS Integration] HTML widget send test' }
+    );
+
+    const response = await f.api.conversations
+      .activities(f.config.conversationId)
+      .create({
+        type: 'message',
+        text: markdown,
+        textFormat: 'extendedmarkdown',
+      });
+
+    expect(response).toBeDefined();
+    expect(response.id).toBeDefined();
+  });
+
+  it('should accept a widget payload with toolInput and toolOutput fields', async () => {
+    if (!f.isCanary) return; // Widgets require canary service
+
+    const markdown = buildHtmlWidgetMarkdown({
+      type: 'widget/mcp-ui',
+      name: 'ToolOutput Widget',
+      description: 'Widget with initial tool data.',
+      html: '<body><p>Widget with tool data</p></body>',
+      domain: 'https://teams.microsoft.com',
+      securityPolicy: {
+        connectDomains: [],
+        resourceDomains: ["'self'"],
+        frameDomains: [],
+        baseUriDomains: [],
+      },
+      toolInput: { query: 'test' },
+      toolOutput: {
+        content: [{ type: 'text', text: 'Result data' }],
+        structuredContent: { key: 'value' },
+        isError: false,
+      },
+      permissions: { clipboardWrite: {} },
+    });
+
+    const response = await f.api.conversations
+      .activities(f.config.conversationId)
+      .create({
+        type: 'message',
+        text: markdown,
+        textFormat: 'extendedmarkdown',
+      });
+
+    expect(response).toBeDefined();
+    expect(response.id).toBeDefined();
+  });
+
+  it('should update a widget message without error', async () => {
+    if (!f.isCanary) return; // Widgets require canary service
+
+    const markdown = buildHtmlWidgetMarkdown(
+      {
+        type: 'widget/mcp-ui',
+        name: 'Update Test Widget',
+        html: '<body><p>Original content</p></body>',
+        domain: 'https://teams.microsoft.com',
+      },
+      { before: '[TS Integration] Widget update test - original' }
+    );
+
+    const sent = await f.api.conversations
+      .activities(f.config.conversationId)
+      .create({
+        type: 'message',
+        text: markdown,
+        textFormat: 'extendedmarkdown',
+      });
+
+    expect(sent?.id).toBeDefined();
+
+    const updatedMarkdown = buildHtmlWidgetMarkdown(
+      {
+        type: 'widget/mcp-ui',
+        name: 'Update Test Widget',
+        html: '<body><p>Updated content</p></body>',
+        domain: 'https://teams.microsoft.com',
+      },
+      { before: '[TS Integration] Widget update test - updated' }
+    );
+
+    await f.api.conversations
+      .activities(f.config.conversationId)
+      .update(sent.id!, {
+        type: 'message',
+        text: updatedMarkdown,
+        textFormat: 'extendedmarkdown',
+      });
+  });
+
+  it('should delete a widget message without error', async () => {
+    if (!f.isCanary) return; // Widgets require canary service
+
+    const markdown = buildHtmlWidgetMarkdown({
+      type: 'widget/mcp-ui',
+      name: 'Delete Test Widget',
+      html: '<body><p>Will be deleted</p></body>',
+      domain: 'https://teams.microsoft.com',
+    });
+
+    const sent = await f.api.conversations
+      .activities(f.config.conversationId)
+      .create({
+        type: 'message',
+        text: markdown,
+        textFormat: 'extendedmarkdown',
+      });
+
+    expect(sent?.id).toBeDefined();
+
+    await f.api.conversations
+      .activities(f.config.conversationId)
+      .delete(sent.id!);
+  });
+});

From 341c5c05cbc2dedf722bb59f9070af08652ad9ab Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Thu, 25 Jun 2026 10:53:15 -0700
Subject: [PATCH 07/12] chore: update package-lock.json

---
 package-lock.json | 71 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 68 insertions(+), 3 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 0036bab51..7c167fe2c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -215,6 +215,22 @@
         "typescript": "^5.4.5"
       }
     },
+    "examples/html-widgets": {
+      "name": "@examples/html-widgets",
+      "version": "0.0.1",
+      "license": "MIT",
+      "dependencies": {
+        "@microsoft/teams.apps": "*"
+      },
+      "devDependencies": {
+        "@microsoft/teams.config": "*",
+        "@types/node": "^22.5.4",
+        "dotenv": "^16.4.5",
+        "rimraf": "^6.0.1",
+        "tsx": "^4.20.6",
+        "typescript": "^5.4.5"
+      }
+    },
     "examples/http-adapters": {
       "name": "@examples/http-adapters",
       "version": "0.0.1",
@@ -2213,6 +2229,10 @@
       "resolved": "examples/formatted-messaging",
       "link": true
     },
+    "node_modules/@examples/html-widgets": {
+      "resolved": "examples/html-widgets",
+      "link": true
+    },
     "node_modules/@examples/http-adapters": {
       "resolved": "examples/http-adapters",
       "link": true
@@ -5912,6 +5932,9 @@
         "arm"
       ],
       "dev": true,
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -5926,6 +5949,9 @@
         "arm"
       ],
       "dev": true,
+      "libc": [
+        "musl"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -5940,6 +5966,9 @@
         "arm64"
       ],
       "dev": true,
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -5954,6 +5983,9 @@
         "arm64"
       ],
       "dev": true,
+      "libc": [
+        "musl"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -5968,6 +6000,9 @@
         "loong64"
       ],
       "dev": true,
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -5982,6 +6017,9 @@
         "loong64"
       ],
       "dev": true,
+      "libc": [
+        "musl"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -5996,6 +6034,9 @@
         "ppc64"
       ],
       "dev": true,
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -6010,6 +6051,9 @@
         "ppc64"
       ],
       "dev": true,
+      "libc": [
+        "musl"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -6024,6 +6068,9 @@
         "riscv64"
       ],
       "dev": true,
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -6038,6 +6085,9 @@
         "riscv64"
       ],
       "dev": true,
+      "libc": [
+        "musl"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -6052,6 +6102,9 @@
         "s390x"
       ],
       "dev": true,
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -6065,6 +6118,9 @@
       "cpu": [
         "x64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -6079,6 +6135,9 @@
         "x64"
       ],
       "dev": true,
+      "libc": [
+        "musl"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -11770,9 +11829,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.25",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.25.tgz",
-      "integrity": "sha512-2NFaIyNVgJmBs/ecmtGzlmluTFs5cHEWGTdu0t1HBwYzoGXOL5nUQBRMXsXWla5i4KkG//QMzVP88m1+I3fdAQ==",
+      "version": "4.12.26",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.26.tgz",
+      "integrity": "sha512-uyZtpnYxM9CmQ7QsQknM4zN8EftNqhON1qYeIKM0Se67CCEe2c44xyGURwB0axX2fBDu1dqHrHAc1hmNT8ITkw==",
       "license": "MIT",
       "engines": {
         "node": ">=16.9.0"
@@ -16553,6 +16612,9 @@
         "x64"
       ],
       "dev": true,
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -17661,6 +17723,9 @@
       "cpu": [
         "x64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [

From 44ac17950baad6a2b20e982a27951508059553f4 Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Thu, 25 Jun 2026 11:23:58 -0700
Subject: [PATCH 08/12] Add preview markers for Html Widget

---
 .../src/models/html-widget/call-tool-result.ts |  6 ++++++
 .../models/html-widget/html-widget-payload.ts  |  9 +++++++++
 .../apps/src/routes/invoke/widget-calltool.ts  |  4 ++++
 packages/apps/src/utils/html-widget.ts         | 18 ++++++++++++++++++
 4 files changed, 37 insertions(+)

diff --git a/packages/api/src/models/html-widget/call-tool-result.ts b/packages/api/src/models/html-widget/call-tool-result.ts
index 398fecee7..e0c8ce326 100644
--- a/packages/api/src/models/html-widget/call-tool-result.ts
+++ b/packages/api/src/models/html-widget/call-tool-result.ts
@@ -16,6 +16,9 @@ export interface IMcpUiCallToolResultContent {
 /**
  * The result of a widget's `tools/call` request, returned by the bot
  * in response to an `htmlwidget/calltool` invoke activity.
+ *
+ * @experimental This API is in preview and may change in the future.
+ * Diagnostic: ExperimentalTeamsHtmlWidget
  */
 export interface IMcpUiCallToolResult {
   /**
@@ -38,6 +41,9 @@ export interface IMcpUiCallToolResult {
  * The wire-format response body for an `htmlwidget/calltool` invoke.
  * Teams expects this shape (with `responseType` discriminator) rather than
  * a bare {@link IMcpUiCallToolResult}.
+ *
+ * @experimental This API is in preview and may change in the future.
+ * Diagnostic: ExperimentalTeamsHtmlWidget
  */
 export interface IHtmlWidgetCallToolResponse {
   /**
diff --git a/packages/api/src/models/html-widget/html-widget-payload.ts b/packages/api/src/models/html-widget/html-widget-payload.ts
index 4c74e9579..047316d48 100644
--- a/packages/api/src/models/html-widget/html-widget-payload.ts
+++ b/packages/api/src/models/html-widget/html-widget-payload.ts
@@ -1,6 +1,9 @@
 /**
  * The security policy for an HTML widget, controlling allowed origins
  * for network requests, static resources, nested iframes, and base URIs.
+ *
+ * @experimental This API is in preview and may change in the future.
+ * Diagnostic: ExperimentalTeamsHtmlWidget
  */
 export interface IHtmlWidgetSecurityPolicy {
   /**
@@ -26,6 +29,9 @@ export interface IHtmlWidgetSecurityPolicy {
 
 /**
  * Permissions that the widget may request from the host.
+ *
+ * @experimental This API is in preview and may change in the future.
+ * Diagnostic: ExperimentalTeamsHtmlWidget
  */
 export interface IHtmlWidgetPermissions {
   /**
@@ -52,6 +58,9 @@ export interface IHtmlWidgetPermissions {
 /**
  * The JSON payload for an HTML widget, sent inside a ```html-widget code block
  * within a Markdown message.
+ *
+ * @experimental This API is in preview and may change in the future.
+ * Diagnostic: ExperimentalTeamsHtmlWidget
  */
 export interface IHtmlWidgetPayload {
   /**
diff --git a/packages/apps/src/routes/invoke/widget-calltool.ts b/packages/apps/src/routes/invoke/widget-calltool.ts
index 7991735ac..e59411c87 100644
--- a/packages/apps/src/routes/invoke/widget-calltool.ts
+++ b/packages/apps/src/routes/invoke/widget-calltool.ts
@@ -3,6 +3,10 @@ import { IHtmlWidgetCallToolInvokeActivity, InvokeResponse } from '@microsoft/te
 import { IActivityContext } from '../../contexts';
 import { RouteHandler } from '../../types';
 
+/**
+ * @experimental This API is in preview and may change in the future.
+ * Diagnostic: ExperimentalTeamsHtmlWidget
+ */
 export type WidgetCallToolRoutes<TExtraCtx extends Record<string, any> = Record<string, any>> = {
   'widget.callTool'?: RouteHandler<
     IActivityContext<IHtmlWidgetCallToolInvokeActivity, TExtraCtx>,
diff --git a/packages/apps/src/utils/html-widget.ts b/packages/apps/src/utils/html-widget.ts
index a4993ce48..a12a224d9 100644
--- a/packages/apps/src/utils/html-widget.ts
+++ b/packages/apps/src/utils/html-widget.ts
@@ -9,6 +9,9 @@ const MCP_PROTOCOL_VERSION = '2026-01-26';
  * Validates an HTML widget payload, throwing if required fields are
  * missing or empty. This catches issues that would otherwise result
  * in a silent client-side render failure ("Couldn't load widget").
+ *
+ * @experimental This API is in preview and may change in the future.
+ * Diagnostic: ExperimentalTeamsHtmlWidget
  */
 function validateHtmlWidgetPayload(payload: IHtmlWidgetPayload): void {
   if (!payload.name?.trim()) {
@@ -42,6 +45,9 @@ type WidgetNotification =
 
 /**
  * Options for building an HTML widget markdown string.
+ *
+ * @experimental This API is in preview and may change in the future.
+ * Diagnostic: ExperimentalTeamsHtmlWidget
  */
 export interface IHtmlWidgetMarkdownOptions {
   /**
@@ -57,6 +63,9 @@ export interface IHtmlWidgetMarkdownOptions {
 
 /**
  * Options for injecting the MCP Apps protocol into widget HTML.
+ *
+ * @experimental This API is in preview and may change in the future.
+ * Diagnostic: ExperimentalTeamsHtmlWidget
  */
 export interface IInjectWidgetProtocolOptions {
   /**
@@ -144,6 +153,9 @@ const NOTIFICATION_CALLBACKS: Record<string, string> = {
  * @param html - The raw HTML content for the widget.
  * @param options - Optional configuration for the protocol setup.
  * @returns The HTML with the protocol script injected.
+ *
+ * @experimental This API is in preview and may change in the future.
+ * Diagnostic: ExperimentalTeamsHtmlWidget
  */
 export function injectWidgetProtocol(
   html: string,
@@ -216,6 +228,9 @@ const DEFAULT_SECURITY_POLICY: Required<IHtmlWidgetPayload>['securityPolicy'] =
  * @param payload - The widget payload to serialize.
  * @param options - Optional text to include before/after the widget block.
  * @returns The markdown string containing the widget code block.
+ *
+ * @experimental This API is in preview and may change in the future.
+ * Diagnostic: ExperimentalTeamsHtmlWidget
  */
 export function buildHtmlWidgetMarkdown(
   payload: IHtmlWidgetPayload,
@@ -250,6 +265,9 @@ export function buildHtmlWidgetMarkdown(
  * @param payload - The widget payload to include in the message.
  * @param options - Optional text to include before/after the widget block.
  * @returns An activity object with textFormat set to 'extendedmarkdown'.
+ *
+ * @experimental This API is in preview and may change in the future.
+ * Diagnostic: ExperimentalTeamsHtmlWidget
  */
 export function buildHtmlWidgetMessage(
   payload: IHtmlWidgetPayload,

From 9915eb33c82775d35226459d9ca0856c797a9f1b Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Thu, 25 Jun 2026 11:32:18 -0700
Subject: [PATCH 09/12] html-widgets example eslint

---
 examples/html-widgets/eslint.config.js        |  1 +
 examples/html-widgets/src/index.ts            | 22 +++++++++----------
 examples/html-widgets/src/widgets/calltool.ts |  2 +-
 .../html-widgets/src/widgets/fullscreen.ts    |  2 +-
 .../html-widgets/src/widgets/messageback.ts   |  2 +-
 .../html-widgets/src/widgets/multi-tool.ts    |  2 +-
 examples/html-widgets/src/widgets/simple.ts   |  2 +-
 7 files changed, 17 insertions(+), 16 deletions(-)
 create mode 100644 examples/html-widgets/eslint.config.js

diff --git a/examples/html-widgets/eslint.config.js b/examples/html-widgets/eslint.config.js
new file mode 100644
index 000000000..5ccf8112f
--- /dev/null
+++ b/examples/html-widgets/eslint.config.js
@@ -0,0 +1 @@
+module.exports = require('@microsoft/teams.config/eslint.config').default;
diff --git a/examples/html-widgets/src/index.ts b/examples/html-widgets/src/index.ts
index 728897f48..461b9aa79 100644
--- a/examples/html-widgets/src/index.ts
+++ b/examples/html-widgets/src/index.ts
@@ -7,18 +7,18 @@
  *   - [EXAMPLE] Code patterns useful for customers building widget bots
  */
 
-import { App, buildHtmlWidgetMarkdown, buildHtmlWidgetMessage } from '@microsoft/teams.apps';
 import { IMcpUiCallToolResult } from '@microsoft/teams.api';
+import { App, buildHtmlWidgetMarkdown, buildHtmlWidgetMessage } from '@microsoft/teams.apps';
 import { ConsoleLogger } from '@microsoft/teams.common';
 
-import { SIMPLE_WIDGET_HTML } from './widgets/simple';
 import { CALLTOOL_WIDGET_HTML } from './widgets/calltool';
-import { MESSAGEBACK_WIDGET_HTML } from './widgets/messageback';
 import { FULLSCREEN_WIDGET_HTML } from './widgets/fullscreen';
+import { HOST_CONTEXT_WIDGET_HTML } from './widgets/host-context';
+import { MESSAGEBACK_WIDGET_HTML } from './widgets/messageback';
 import { MULTI_WIDGET_HTML } from './widgets/multi-tool';
 import { OPEN_LINK_WIDGET_HTML } from './widgets/open-link';
+import { SIMPLE_WIDGET_HTML } from './widgets/simple';
 import { UPDATE_CONTEXT_WIDGET_HTML } from './widgets/update-context';
-import { HOST_CONTEXT_WIDGET_HTML } from './widgets/host-context';
 
 const app = new App({
   logger: new ConsoleLogger('@examples/html-widgets', { level: 'debug' }),
@@ -42,7 +42,7 @@ app.on('message', async ({ send, activity }) => {
         domain: 'https://teams.microsoft.com',
         securityPolicy: {
           connectDomains: [],
-          resourceDomains: ["'self'", 'data:'],
+          resourceDomains: ['\'self\'', 'data:'],
           frameDomains: [],
           baseUriDomains: [],
         },
@@ -68,7 +68,7 @@ app.on('message', async ({ send, activity }) => {
         domain: 'https://teams.microsoft.com',
         securityPolicy: {
           connectDomains: ['https://teams.microsoft.com', 'https://teams.cloud.microsoft.com'],
-          resourceDomains: ["'self'", 'data:'],
+          resourceDomains: ['\'self\'', 'data:'],
           frameDomains: [],
           baseUriDomains: [],
         },
@@ -100,7 +100,7 @@ app.on('message', async ({ send, activity }) => {
         domain: 'https://teams.microsoft.com',
         securityPolicy: {
           connectDomains: [],
-          resourceDomains: ["'self'", 'data:'],
+          resourceDomains: ['\'self\'', 'data:'],
           frameDomains: [],
           baseUriDomains: [],
         },
@@ -126,7 +126,7 @@ app.on('message', async ({ send, activity }) => {
         domain: 'https://teams.microsoft.com',
         securityPolicy: {
           connectDomains: [],
-          resourceDomains: ["'self'", 'data:'],
+          resourceDomains: ['\'self\'', 'data:'],
           frameDomains: [],
           baseUriDomains: [],
         },
@@ -152,7 +152,7 @@ app.on('message', async ({ send, activity }) => {
         domain: 'https://teams.microsoft.com',
         securityPolicy: {
           connectDomains: ['https://teams.microsoft.com'],
-          resourceDomains: ["'self'", 'data:'],
+          resourceDomains: ['\'self\'', 'data:'],
           frameDomains: [],
           baseUriDomains: [],
         },
@@ -203,7 +203,7 @@ app.on('message', async ({ send, activity }) => {
         domain: 'https://teams.microsoft.com',
         securityPolicy: {
           connectDomains: [],
-          resourceDomains: ["'self'"],
+          resourceDomains: ['\'self\''],
           frameDomains: [],
           baseUriDomains: [],
         },
@@ -348,7 +348,7 @@ app.on('widget.callTool', async ({ activity }) => {
       break;
   }
 
-  console.log(`[widget.callTool] result=`, JSON.stringify(callToolResult));
+  console.log('[widget.callTool] result=', JSON.stringify(callToolResult));
 
   return {
     responseType: 'htmlwidget/calltoolresult',
diff --git a/examples/html-widgets/src/widgets/calltool.ts b/examples/html-widgets/src/widgets/calltool.ts
index 97e9e9ab7..d423f904f 100644
--- a/examples/html-widgets/src/widgets/calltool.ts
+++ b/examples/html-widgets/src/widgets/calltool.ts
@@ -5,4 +5,4 @@
  * that is widget-specific logic, not boilerplate. The example bot uses
  * injectWidgetProtocol() automatically via the builders.
  */
-export const CALLTOOL_WIDGET_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;overflow:auto}body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}h3{margin:0 0 8px 0}p{margin:0 0 12px 0;color:#666}button{padding:8px 16px;background:#5b5fc7;color:#fff;border:none;border-radius:4px;cursor:pointer}button:hover{background:#4b4fb7}#result{margin-top:12px;padding:8px;background:#f5f5f5;border-radius:4px}</style></head><body><h3>CallTool Widget</h3><p>Click Refresh to call the bot's "refresh" tool.</p><button id="refreshBtn">Refresh</button><div id="result">Waiting for action...</div><script>(function(){var callId=0;document.getElementById('refreshBtn').addEventListener('click',function(){var id='call-'+(++callId);document.getElementById('result').textContent='Calling refresh...';window.parent.postMessage({jsonrpc:'2.0',id:id,method:'tools/call',params:{name:'refresh',arguments:{}}},'*');});window.addEventListener('message',function(e){var d=e.data;if(d&&d.jsonrpc==='2.0'&&d.id&&typeof d.id==='string'&&d.id.startsWith('call-')){if(d.result)document.getElementById('result').textContent=JSON.stringify(d.result);if(d.error)document.getElementById('result').textContent='Error: '+JSON.stringify(d.error);}});})()</script></body></html>`;
+export const CALLTOOL_WIDGET_HTML = '<!DOCTYPE html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;overflow:auto}body{font-family:-apple-system,BlinkMacSystemFont,\'Segoe UI\',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}h3{margin:0 0 8px 0}p{margin:0 0 12px 0;color:#666}button{padding:8px 16px;background:#5b5fc7;color:#fff;border:none;border-radius:4px;cursor:pointer}button:hover{background:#4b4fb7}#result{margin-top:12px;padding:8px;background:#f5f5f5;border-radius:4px}</style></head><body><h3>CallTool Widget</h3><p>Click Refresh to call the bot\'s "refresh" tool.</p><button id="refreshBtn">Refresh</button><div id="result">Waiting for action...</div><script>(function(){var callId=0;document.getElementById(\'refreshBtn\').addEventListener(\'click\',function(){var id=\'call-\'+(++callId);document.getElementById(\'result\').textContent=\'Calling refresh...\';window.parent.postMessage({jsonrpc:\'2.0\',id:id,method:\'tools/call\',params:{name:\'refresh\',arguments:{}}},\'*\');});window.addEventListener(\'message\',function(e){var d=e.data;if(d&&d.jsonrpc===\'2.0\'&&d.id&&typeof d.id===\'string\'&&d.id.startsWith(\'call-\')){if(d.result)document.getElementById(\'result\').textContent=JSON.stringify(d.result);if(d.error)document.getElementById(\'result\').textContent=\'Error: \'+JSON.stringify(d.error);}});})()</script></body></html>';
diff --git a/examples/html-widgets/src/widgets/fullscreen.ts b/examples/html-widgets/src/widgets/fullscreen.ts
index f693b2cd3..8d6627d87 100644
--- a/examples/html-widgets/src/widgets/fullscreen.ts
+++ b/examples/html-widgets/src/widgets/fullscreen.ts
@@ -4,4 +4,4 @@
  * Uses requestDisplayMode to ask the Teams host for fullscreen mode.
  * The example bot uses injectWidgetProtocol() automatically via the builders.
  */
-export const FULLSCREEN_WIDGET_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;overflow:auto}body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}h3{margin:0 0 8px 0}p{margin:0 0 12px 0;color:#666}button{padding:8px 16px;background:#107c10;color:#fff;border:none;border-radius:4px;cursor:pointer}button:hover{background:#0e6b0e}#content{margin-top:12px;padding:16px;background:#f0fff0;border-radius:4px}#modeLabel{font-weight:600}</style></head><body><h3>Fullscreen Widget</h3><p>Click the button to request fullscreen mode from Teams.</p><button id="fsBtn">Go Fullscreen</button><div id="content"><p>In fullscreen mode, this widget will expand to fill the available space.</p><p>Current mode: <span id="modeLabel">inline</span></p></div><script>(function(){document.getElementById('fsBtn').addEventListener('click',function(){var id='fs-'+Math.random().toString(36).slice(2);window.parent.postMessage({jsonrpc:'2.0',id:id,method:'ui/request-display-mode',params:{mode:'fullscreen'}},'*');});window.addEventListener('message',function(e){var d=e.data;if(d&&d.jsonrpc==='2.0'){if(d.result&&d.result.mode)document.getElementById('modeLabel').textContent=d.result.mode;if(d.error)document.getElementById('modeLabel').textContent='Error: '+JSON.stringify(d.error);}});})()</script></body></html>`;
+export const FULLSCREEN_WIDGET_HTML = '<!DOCTYPE html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;overflow:auto}body{font-family:-apple-system,BlinkMacSystemFont,\'Segoe UI\',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}h3{margin:0 0 8px 0}p{margin:0 0 12px 0;color:#666}button{padding:8px 16px;background:#107c10;color:#fff;border:none;border-radius:4px;cursor:pointer}button:hover{background:#0e6b0e}#content{margin-top:12px;padding:16px;background:#f0fff0;border-radius:4px}#modeLabel{font-weight:600}</style></head><body><h3>Fullscreen Widget</h3><p>Click the button to request fullscreen mode from Teams.</p><button id="fsBtn">Go Fullscreen</button><div id="content"><p>In fullscreen mode, this widget will expand to fill the available space.</p><p>Current mode: <span id="modeLabel">inline</span></p></div><script>(function(){document.getElementById(\'fsBtn\').addEventListener(\'click\',function(){var id=\'fs-\'+Math.random().toString(36).slice(2);window.parent.postMessage({jsonrpc:\'2.0\',id:id,method:\'ui/request-display-mode\',params:{mode:\'fullscreen\'}},\'*\');});window.addEventListener(\'message\',function(e){var d=e.data;if(d&&d.jsonrpc===\'2.0\'){if(d.result&&d.result.mode)document.getElementById(\'modeLabel\').textContent=d.result.mode;if(d.error)document.getElementById(\'modeLabel\').textContent=\'Error: \'+JSON.stringify(d.error);}});})()</script></body></html>';
diff --git a/examples/html-widgets/src/widgets/messageback.ts b/examples/html-widgets/src/widgets/messageback.ts
index b67fe7135..ac56f6063 100644
--- a/examples/html-widgets/src/widgets/messageback.ts
+++ b/examples/html-widgets/src/widgets/messageback.ts
@@ -5,4 +5,4 @@
  * similar to messageBack in Adaptive Cards. The example bot uses
  * injectWidgetProtocol() automatically via the builders.
  */
-export const MESSAGEBACK_WIDGET_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;overflow:auto}body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}h3{margin:0 0 8px 0}p{margin:0 0 12px 0;color:#666}button{padding:8px 16px;background:#0078d4;color:#fff;border:none;border-radius:4px;cursor:pointer}button:hover{background:#006cbd}#status{margin-top:12px;color:#666}</style></head><body><h3>MessageBack Widget</h3><p>Click the button to send a messageBack to the bot.</p><button id="msgBtn">Send MessageBack</button><div id="status"></div><script>(function(){document.getElementById('msgBtn').addEventListener('click',function(){var msgId='msg-'+Math.random().toString(36).slice(2);document.getElementById('status').textContent='Sending messageBack...';window.parent.postMessage({jsonrpc:'2.0',id:msgId,method:'ui/message',params:{role:'user',content:[{type:'text',text:'Hello from the widget!'}]}},'*');document.getElementById('status').textContent='MessageBack sent!';});})()</script></body></html>`;
+export const MESSAGEBACK_WIDGET_HTML = '<!DOCTYPE html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;overflow:auto}body{font-family:-apple-system,BlinkMacSystemFont,\'Segoe UI\',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}h3{margin:0 0 8px 0}p{margin:0 0 12px 0;color:#666}button{padding:8px 16px;background:#0078d4;color:#fff;border:none;border-radius:4px;cursor:pointer}button:hover{background:#006cbd}#status{margin-top:12px;color:#666}</style></head><body><h3>MessageBack Widget</h3><p>Click the button to send a messageBack to the bot.</p><button id="msgBtn">Send MessageBack</button><div id="status"></div><script>(function(){document.getElementById(\'msgBtn\').addEventListener(\'click\',function(){var msgId=\'msg-\'+Math.random().toString(36).slice(2);document.getElementById(\'status\').textContent=\'Sending messageBack...\';window.parent.postMessage({jsonrpc:\'2.0\',id:msgId,method:\'ui/message\',params:{role:\'user\',content:[{type:\'text\',text:\'Hello from the widget!\'}]}},\'*\');document.getElementById(\'status\').textContent=\'MessageBack sent!\';});})()</script></body></html>';
diff --git a/examples/html-widgets/src/widgets/multi-tool.ts b/examples/html-widgets/src/widgets/multi-tool.ts
index 0083565c9..0a954429c 100644
--- a/examples/html-widgets/src/widgets/multi-tool.ts
+++ b/examples/html-widgets/src/widgets/multi-tool.ts
@@ -5,4 +5,4 @@
  * each as an `htmlwidget/calltool` invoke activity to the bot. The example
  * bot uses injectWidgetProtocol() automatically via the builders.
  */
-export const MULTI_WIDGET_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;overflow:auto}body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}h3{margin:0 0 8px 0}p{margin:0 0 12px 0;color:#666}.tools{display:flex;gap:8px;flex-wrap:wrap}.tools button{padding:8px 12px;color:#fff;border:none;border-radius:4px;cursor:pointer}#log{margin-top:12px;padding:8px;background:#1e1e1e;color:#d4d4d4;border-radius:4px;font-family:monospace;font-size:12px;max-height:200px;overflow-y:auto}</style></head><body><h3>Multi-Tool Widget</h3><p>Each button calls a different tool on the bot.</p><div class="tools"><button data-tool="getTime" style="background:#5b5fc7">Get Time</button><button data-tool="roll" data-args='{"sides":20}' style="background:#c75b5b">Roll d20</button><button data-tool="echo" data-args='{"hello":"world"}' style="background:#5bc75b">Echo</button><button data-tool="unknownTool" style="background:#999">Unknown (error)</button></div><div id="log">Available tools: getTime, roll, echo, unknownTool</div><script>(function(){var callId=0;var log=document.getElementById('log');document.querySelectorAll('[data-tool]').forEach(function(btn){btn.addEventListener('click',function(){var tool=btn.getAttribute('data-tool');var args=btn.getAttribute('data-args');var id='call-'+(++callId);log.textContent+='\\nCalling '+tool+'...';window.parent.postMessage({jsonrpc:'2.0',id:id,method:'tools/call',params:{name:tool,arguments:args?JSON.parse(args):{}}},'*');});});window.addEventListener('message',function(e){var d=e.data;if(d&&d.jsonrpc==='2.0'&&d.id&&typeof d.id==='string'&&d.id.startsWith('call-')){if(d.result)log.textContent+='\\nResult: '+JSON.stringify(d.result);if(d.error)log.textContent+='\\nError: '+JSON.stringify(d.error);}});})()</script></body></html>`;
+export const MULTI_WIDGET_HTML = '<!DOCTYPE html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;overflow:auto}body{font-family:-apple-system,BlinkMacSystemFont,\'Segoe UI\',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}h3{margin:0 0 8px 0}p{margin:0 0 12px 0;color:#666}.tools{display:flex;gap:8px;flex-wrap:wrap}.tools button{padding:8px 12px;color:#fff;border:none;border-radius:4px;cursor:pointer}#log{margin-top:12px;padding:8px;background:#1e1e1e;color:#d4d4d4;border-radius:4px;font-family:monospace;font-size:12px;max-height:200px;overflow-y:auto}</style></head><body><h3>Multi-Tool Widget</h3><p>Each button calls a different tool on the bot.</p><div class="tools"><button data-tool="getTime" style="background:#5b5fc7">Get Time</button><button data-tool="roll" data-args=\'{"sides":20}\' style="background:#c75b5b">Roll d20</button><button data-tool="echo" data-args=\'{"hello":"world"}\' style="background:#5bc75b">Echo</button><button data-tool="unknownTool" style="background:#999">Unknown (error)</button></div><div id="log">Available tools: getTime, roll, echo, unknownTool</div><script>(function(){var callId=0;var log=document.getElementById(\'log\');document.querySelectorAll(\'[data-tool]\').forEach(function(btn){btn.addEventListener(\'click\',function(){var tool=btn.getAttribute(\'data-tool\');var args=btn.getAttribute(\'data-args\');var id=\'call-\'+(++callId);log.textContent+=\'\\nCalling \'+tool+\'...\';window.parent.postMessage({jsonrpc:\'2.0\',id:id,method:\'tools/call\',params:{name:tool,arguments:args?JSON.parse(args):{}}},\'*\');});});window.addEventListener(\'message\',function(e){var d=e.data;if(d&&d.jsonrpc===\'2.0\'&&d.id&&typeof d.id===\'string\'&&d.id.startsWith(\'call-\')){if(d.result)log.textContent+=\'\\nResult: \'+JSON.stringify(d.result);if(d.error)log.textContent+=\'\\nError: \'+JSON.stringify(d.error);}});})()</script></body></html>';
diff --git a/examples/html-widgets/src/widgets/simple.ts b/examples/html-widgets/src/widgets/simple.ts
index ff713a11c..8510d9b66 100644
--- a/examples/html-widgets/src/widgets/simple.ts
+++ b/examples/html-widgets/src/widgets/simple.ts
@@ -5,4 +5,4 @@
  * This is raw HTML without the MCP Apps protocol. The example bot uses
  * injectWidgetProtocol() automatically via the builders.
  */
-export const SIMPLE_WIDGET_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;overflow:auto}body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}h3{margin:0 0 8px 0;color:#333}p{margin:0;color:#666}.status{margin-top:12px;padding:8px;background:#f0f9ff;border-radius:4px}</style></head><body><h3>Simple HTML Widget</h3><p>This is a static HTML widget rendered inside a Teams message. No callbacks are needed.</p><div class="status"><strong>Status:</strong> Rendered successfully</div></body></html>`;
+export const SIMPLE_WIDGET_HTML = '<!DOCTYPE html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{height:100%;overflow:auto}body{font-family:-apple-system,BlinkMacSystemFont,\'Segoe UI\',Roboto,sans-serif;padding:16px;background:#fff;color:#242424;font-size:13px}h3{margin:0 0 8px 0;color:#333}p{margin:0;color:#666}.status{margin-top:12px;padding:8px;background:#f0f9ff;border-radius:4px}</style></head><body><h3>Simple HTML Widget</h3><p>This is a static HTML widget rendered inside a Teams message. No callbacks are needed.</p><div class="status"><strong>Status:</strong> Rendered successfully</div></body></html>';

From 2f229c2ddfe0ba1758dfbdb2905316ea8b47d2bd Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Mon, 29 Jun 2026 12:06:12 -0700
Subject: [PATCH 10/12] Add validateSecurityPolicy

---
 examples/html-widgets/src/index.ts          | 169 ++++++------
 packages/apps/src/index.ts                  |   4 +-
 packages/apps/src/utils/html-widget.spec.ts | 271 +++++++++++++++++++-
 packages/apps/src/utils/html-widget.ts      | 251 ++++++++++++++++--
 4 files changed, 583 insertions(+), 112 deletions(-)

diff --git a/examples/html-widgets/src/index.ts b/examples/html-widgets/src/index.ts
index 461b9aa79..08e9edae9 100644
--- a/examples/html-widgets/src/index.ts
+++ b/examples/html-widgets/src/index.ts
@@ -1,14 +1,13 @@
 /**
  * HTML Widgets Example Bot
  *
- * This example demonstrates the full HTML widget contract for Teams bots.
- * Commands are annotated to distinguish between:
- *   - [CONTRACT TEST] Tests that verify the contract works end-to-end
- *   - [EXAMPLE] Code patterns useful for customers building widget bots
+ * This example demonstrates the full HTML widget capabilities for Teams bots.
+ * Each command shows a different widget feature that developers can use as
+ * a reference for building their own widget-enabled bots.
  */
 
 import { IMcpUiCallToolResult } from '@microsoft/teams.api';
-import { App, buildHtmlWidgetMarkdown, buildHtmlWidgetMessage } from '@microsoft/teams.apps';
+import { App, buildHtmlWidgetMarkdown, buildHtmlWidgetMessage, validateSecurityPolicy } from '@microsoft/teams.apps';
 import { ConsoleLogger } from '@microsoft/teams.common';
 
 import { CALLTOOL_WIDGET_HTML } from './widgets/calltool';
@@ -17,6 +16,7 @@ import { HOST_CONTEXT_WIDGET_HTML } from './widgets/host-context';
 import { MESSAGEBACK_WIDGET_HTML } from './widgets/messageback';
 import { MULTI_WIDGET_HTML } from './widgets/multi-tool';
 import { OPEN_LINK_WIDGET_HTML } from './widgets/open-link';
+
 import { SIMPLE_WIDGET_HTML } from './widgets/simple';
 import { UPDATE_CONTEXT_WIDGET_HTML } from './widgets/update-context';
 
@@ -25,7 +25,7 @@ const app = new App({
 });
 
 // ---------------------------------------------------------------------------
-// [EXAMPLE] Simple static widget - no callbacks
+// Simple static widget - no callbacks
 // Shows the minimal code to send an HTML widget.
 // ---------------------------------------------------------------------------
 app.on('message', async ({ send, activity }) => {
@@ -48,16 +48,18 @@ app.on('message', async ({ send, activity }) => {
         },
         permissions: {},
       },
-      { before: 'Here is a simple static widget:' }
+      { before: 'Here is a simple static widget:', after: 'No callbacks needed for static content.' }
     );
     await send(message);
+
+    // Alternative: use buildHtmlWidgetMarkdown for more control over the activity
+    // const markdown = buildHtmlWidgetMarkdown(payload, { before: '...' });
+    // await send({ type: 'message', text: markdown, textFormat: 'extendedmarkdown' });
     return;
   }
 
-  // ---------------------------------------------------------------------------
-  // [EXAMPLE] Widget with onCallTool callback
+  // Widget with onCallTool callback
   // The widget calls tools on the bot and re-renders with the result.
-  // ---------------------------------------------------------------------------
   if (text === '/calltool') {
     const message = buildHtmlWidgetMessage(
       {
@@ -86,10 +88,8 @@ app.on('message', async ({ send, activity }) => {
     return;
   }
 
-  // ---------------------------------------------------------------------------
-  // [CONTRACT TEST] Widget with onMessage (messageBack) callback
+  // Widget with onMessage (messageBack) callback
   // Tests that the widget can send messageBack to the bot.
-  // ---------------------------------------------------------------------------
   if (text === '/messageback') {
     const message = buildHtmlWidgetMessage(
       {
@@ -112,10 +112,8 @@ app.on('message', async ({ send, activity }) => {
     return;
   }
 
-  // ---------------------------------------------------------------------------
-  // [CONTRACT TEST] Widget requesting fullscreen display mode
+  // Widget requesting fullscreen display mode
   // Tests onRequestDisplayMode with "fullscreen" value.
-  // ---------------------------------------------------------------------------
   if (text === '/fullscreen') {
     const message = buildHtmlWidgetMessage(
       {
@@ -138,10 +136,8 @@ app.on('message', async ({ send, activity }) => {
     return;
   }
 
-  // ---------------------------------------------------------------------------
-  // [CONTRACT TEST] Widget with multiple tools
+  // Widget with multiple tools
   // Tests that calltool dispatches correctly by tool name.
-  // ---------------------------------------------------------------------------
   if (text === '/multi') {
     const message = buildHtmlWidgetMessage(
       {
@@ -170,55 +166,7 @@ app.on('message', async ({ send, activity }) => {
     return;
   }
 
-  // ---------------------------------------------------------------------------
-  // [CONTRACT TEST] Raw markdown test - verifies extendedmarkdown format works
-  // Uses buildHtmlWidgetMarkdown directly for more control.
-  // ---------------------------------------------------------------------------
-  if (text === '/raw') {
-    const markdown = buildHtmlWidgetMarkdown(
-      {
-        type: 'widget/mcp-ui',
-        name: 'Raw Test',
-        description: 'Testing raw markdown assembly.',
-        html: SIMPLE_WIDGET_HTML,
-        domain: 'https://teams.microsoft.com',
-      },
-      { before: 'Text before widget.', after: 'Text after widget.' }
-    );
-    await send({ type: 'message', text: markdown, textFormat: 'extendedmarkdown' });
-    return;
-  }
-
-  // ---------------------------------------------------------------------------
-  // [CONTRACT TEST] Widget with permissions requested
-  // Tests that the permissions field is accepted by the host.
-  // ---------------------------------------------------------------------------
-  if (text === '/permissions') {
-    const message = buildHtmlWidgetMessage(
-      {
-        type: 'widget/mcp-ui',
-        name: 'Permissions Widget',
-        description: 'Widget requesting clipboard and geolocation.',
-        html: SIMPLE_WIDGET_HTML,
-        domain: 'https://teams.microsoft.com',
-        securityPolicy: {
-          connectDomains: [],
-          resourceDomains: ['\'self\''],
-          frameDomains: [],
-          baseUriDomains: [],
-        },
-        permissions: {
-          clipboardWrite: {},
-          geolocation: {},
-        },
-      },
-      { before: 'This widget requests permissions (clipboard + geolocation):' }
-    );
-    await send(message);
-    return;
-  }
-
-  // [CONTRACT TEST] ui/open-link method
+  // Widget using ui/open-link
   if (text === '/openlink') {
     const message = buildHtmlWidgetMessage(
       {
@@ -233,7 +181,7 @@ app.on('message', async ({ send, activity }) => {
     return;
   }
 
-  // [CONTRACT TEST] ui/update-model-context method
+  // Widget using ui/update-model-context
   if (text === '/context') {
     const message = buildHtmlWidgetMessage(
       {
@@ -248,7 +196,7 @@ app.on('message', async ({ send, activity }) => {
     return;
   }
 
-  // [CONTRACT TEST] Host context inspector - shows what hostContext is returned
+  // Host context inspector - shows hostContext from ui/initialize
   if (text === '/hostcontext') {
     const message = buildHtmlWidgetMessage(
       {
@@ -263,22 +211,73 @@ app.on('message', async ({ send, activity }) => {
     return;
   }
 
+  // Security policy validation
+  // Demonstrates validateSecurityPolicy catching mismatched references.
+  // This is a dev-time audit tool, not a security boundary - the browser's
+  // CSP enforcement is the real protection. Use debugCspViolations for runtime.
+  if (text === '/validate') {
+    const htmlWithExternalRefs = `
+      <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto">
+      <div style="font-family: Roboto, sans-serif; padding: 16px;">
+        <h2>Validation Demo</h2>
+        <p>This widget was validated before sending.</p>
+      </div>`;
+
+    // Step 1: validate against a restrictive policy to catch issues
+    const strictPolicy = {
+      connectDomains: [],
+      resourceDomains: ['\'self\'', 'data:'],
+      frameDomains: [],
+      baseUriDomains: [],
+    };
+    const warnings = validateSecurityPolicy(htmlWithExternalRefs, strictPolicy);
+
+    // Step 2: fix the policy based on warnings, then build the widget
+    const correctedPolicy = {
+      ...strictPolicy,
+      resourceDomains: [...strictPolicy.resourceDomains, 'https://fonts.googleapis.com'],
+    };
+    const warningText = warnings
+      .map((w) => `- **${w.source}**: \`${w.url}\` not in \`${w.policyField}\``)
+      .join('\n');
+    const markdown = buildHtmlWidgetMarkdown(
+      {
+        type: 'widget/mcp-ui',
+        name: 'Validated Widget',
+        description: 'Widget built after security policy validation.',
+        html: htmlWithExternalRefs,
+        domain: 'https://teams.microsoft.com',
+        securityPolicy: correctedPolicy,
+      },
+      {
+        before:
+          `**Validation found ${warnings.length} warning(s):**\n\n` +
+          warningText + '\n\n' +
+          'Policy was corrected before sending:',
+      }
+    );
+    await send({ type: 'message', text: markdown, textFormat: 'extendedmarkdown' });
+    return;
+  }
+
   // Default: show help
   if (text === '/help' || text === 'help') {
-    await send(
-      '**HTML Widget Test Commands:**\n\n' +
-      '- `/simple` - Static widget (no callbacks)\n' +
-      '- `/calltool` - Widget with onCallTool\n' +
-      '- `/messageback` - Widget with onMessage\n' +
-      '- `/fullscreen` - Widget requesting fullscreen\n' +
-      '- `/multi` - Widget with multiple tools\n' +
-      '- `/raw` - Raw markdown with before/after text\n' +
-      '- `/permissions` - Widget requesting permissions\n' +
-      '- `/openlink` - Widget with ui/open-link\n' +
-      '- `/context` - Widget with ui/update-model-context\n' +
-      '- `/hostcontext` - Inspect hostContext from initialize\n' +
-      '- `/help` - This message'
-    );
+    await send({
+      type: 'message',
+      textFormat: 'markdown',
+      text:
+        '**HTML Widget Test Commands:**\n\n' +
+        '- `/simple` - Static widget (no callbacks)\n' +
+        '- `/calltool` - Widget with onCallTool\n' +
+        '- `/messageback` - Widget with onMessage\n' +
+        '- `/fullscreen` - Widget requesting fullscreen\n' +
+        '- `/multi` - Widget with multiple tools\n' +
+        '- `/openlink` - Widget with ui/open-link\n' +
+        '- `/context` - Widget with ui/update-model-context\n' +
+        '- `/hostcontext` - Inspect hostContext from initialize\n' +
+        '- `/validate` - Security policy validation demo\n' +
+        '- `/help` - This message',
+    });
     return;
   }
 
@@ -292,7 +291,7 @@ app.on('message', async ({ send, activity }) => {
 });
 
 // ---------------------------------------------------------------------------
-// [EXAMPLE] Handle htmlwidget/calltool invoke
+// Handle htmlwidget/calltool invoke
 // This is the typed handler for when a widget calls a tool on the bot.
 // ---------------------------------------------------------------------------
 app.on('widget.callTool', async ({ activity }) => {
diff --git a/packages/apps/src/index.ts b/packages/apps/src/index.ts
index 61e441a18..b629ba63b 100644
--- a/packages/apps/src/index.ts
+++ b/packages/apps/src/index.ts
@@ -12,5 +12,5 @@ export * from './http';
 export { toThreadedConversationId } from './utils/thread';
 
 // HTML Widget utilities
-export { buildHtmlWidgetMarkdown, buildHtmlWidgetMessage, injectWidgetProtocol } from './utils/html-widget';
-export type { IHtmlWidgetMarkdownOptions, IInjectWidgetProtocolOptions } from './utils/html-widget';
+export { buildHtmlWidgetMarkdown, buildHtmlWidgetMessage, injectWidgetProtocol, validateSecurityPolicy } from './utils/html-widget';
+export type { IHtmlWidgetMarkdownOptions, IInjectWidgetProtocolOptions, ISecurityPolicyWarning } from './utils/html-widget';
diff --git a/packages/apps/src/utils/html-widget.spec.ts b/packages/apps/src/utils/html-widget.spec.ts
index 9bbd61906..1b4f607ba 100644
--- a/packages/apps/src/utils/html-widget.spec.ts
+++ b/packages/apps/src/utils/html-widget.spec.ts
@@ -1,6 +1,6 @@
-import { IHtmlWidgetPayload } from '@microsoft/teams.api';
+import { IHtmlWidgetPayload, IHtmlWidgetSecurityPolicy } from '@microsoft/teams.api';
 
-import { buildHtmlWidgetMarkdown, buildHtmlWidgetMessage, injectWidgetProtocol } from './html-widget';
+import { buildHtmlWidgetMarkdown, buildHtmlWidgetMessage, injectWidgetProtocol, validateSecurityPolicy } from './html-widget';
 
 const MINIMAL_PAYLOAD: IHtmlWidgetPayload = {
   type: 'widget/mcp-ui',
@@ -76,6 +76,41 @@ describe('buildHtmlWidgetMarkdown', () => {
     expect(result.endsWith('\n```\n\nAfter')).toBe(true);
   });
 
+  it('should forward protocolOptions to injectWidgetProtocol', () => {
+    const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD, {
+      protocolOptions: {
+        notifications: ['tool-result'],
+      },
+    });
+    const jsonLine = result.split('\n').slice(1, -1).join('\n');
+    const parsed = JSON.parse(jsonLine);
+    expect(parsed.html).toContain('ui/notifications/tool-result');
+    expect(parsed.html).toContain('window.onToolResult');
+  });
+
+  it('should forward debugCspViolations through protocolOptions', () => {
+    const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD, {
+      protocolOptions: {
+        debugCspViolations: true,
+      },
+    });
+    const jsonLine = result.split('\n').slice(1, -1).join('\n');
+    const parsed = JSON.parse(jsonLine);
+    expect(parsed.html).toContain('securitypolicyviolation');
+  });
+
+  it('should use payload name even when protocolOptions is provided', () => {
+    const result = buildHtmlWidgetMarkdown(MINIMAL_PAYLOAD, {
+      protocolOptions: {
+        version: '2.0.0',
+      },
+    });
+    const jsonLine = result.split('\n').slice(1, -1).join('\n');
+    const parsed = JSON.parse(jsonLine);
+    expect(parsed.html).toContain('name:\'Test Widget\'');
+    expect(parsed.html).toContain('version:\'2.0.0\'');
+  });
+
   it('should serialize a full payload with all fields', () => {
     const result = buildHtmlWidgetMarkdown(FULL_PAYLOAD);
     const parsed = JSON.parse(result.replace('```html-widget\n', '').replace('\n```', ''));
@@ -454,3 +489,235 @@ describe('payload validation', () => {
     expect(() => buildHtmlWidgetMarkdown(payload)).toThrow('https://');
   });
 });
+
+describe('validateSecurityPolicy', () => {
+  const EMPTY_POLICY: IHtmlWidgetSecurityPolicy = {
+    connectDomains: [],
+    resourceDomains: [],
+    frameDomains: [],
+    baseUriDomains: [],
+  };
+
+  it('should return no warnings for HTML with no external references', () => {
+    const html = '<div><p>Hello world</p></div>';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toEqual([]);
+  });
+
+  it('should warn about <script src> not in resourceDomains', () => {
+    const html = '<script src="https://cdn.example.com/lib.js"></script>';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].policyField).toBe('resourceDomains');
+    expect(warnings[0].source).toBe('<script src>');
+    expect(warnings[0].url).toBe('https://cdn.example.com/lib.js');
+  });
+
+  it('should not warn when origin is in resourceDomains', () => {
+    const html = '<script src="https://cdn.example.com/lib.js"></script>';
+    const policy: IHtmlWidgetSecurityPolicy = {
+      ...EMPTY_POLICY,
+      resourceDomains: ['https://cdn.example.com'],
+    };
+    const warnings = validateSecurityPolicy(html, policy);
+    expect(warnings).toEqual([]);
+  });
+
+  it('should warn about <link href> not in resourceDomains', () => {
+    const html = '<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto">';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].policyField).toBe('resourceDomains');
+    expect(warnings[0].source).toBe('<link href>');
+  });
+
+  it('should warn about <img src> not in resourceDomains', () => {
+    const html = '<img src="https://images.example.com/photo.png">';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].policyField).toBe('resourceDomains');
+    expect(warnings[0].source).toBe('<img src>');
+  });
+
+  it('should warn about fetch() not in connectDomains', () => {
+    const html = '<script>fetch("https://api.example.com/data")</script>';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].policyField).toBe('connectDomains');
+    expect(warnings[0].source).toBe('fetch()');
+  });
+
+  it('should not warn when fetch origin is in connectDomains', () => {
+    const html = '<script>fetch("https://api.example.com/data")</script>';
+    const policy: IHtmlWidgetSecurityPolicy = {
+      ...EMPTY_POLICY,
+      connectDomains: ['https://api.example.com'],
+    };
+    const warnings = validateSecurityPolicy(html, policy);
+    expect(warnings).toEqual([]);
+  });
+
+  it('should warn about XMLHttpRequest.open() not in connectDomains', () => {
+    const html = '<script>xhr.open("GET", "https://api.example.com/data")</script>';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].policyField).toBe('connectDomains');
+    expect(warnings[0].source).toBe('XMLHttpRequest.open()');
+  });
+
+  it('should warn about new WebSocket() not in connectDomains', () => {
+    const html = '<script>new WebSocket("wss://ws.example.com/stream")</script>';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].policyField).toBe('connectDomains');
+  });
+
+  it('should warn about <iframe src> not in frameDomains', () => {
+    const html = '<iframe src="https://embed.youtube.com/video123"></iframe>';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].policyField).toBe('frameDomains');
+    expect(warnings[0].source).toBe('<iframe src>');
+  });
+
+  it('should not warn when iframe origin is in frameDomains', () => {
+    const html = '<iframe src="https://embed.youtube.com/video123"></iframe>';
+    const policy: IHtmlWidgetSecurityPolicy = {
+      ...EMPTY_POLICY,
+      frameDomains: ['https://embed.youtube.com'],
+    };
+    const warnings = validateSecurityPolicy(html, policy);
+    expect(warnings).toEqual([]);
+  });
+
+  it('should warn about CSS url() not in resourceDomains', () => {
+    const html = '<style>body { background-image: url("https://images.example.com/bg.png"); }</style>';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].policyField).toBe('resourceDomains');
+    expect(warnings[0].source).toBe('CSS url()');
+  });
+
+  it('should warn about CSS @import not in resourceDomains', () => {
+    const html = '<style>@import "https://fonts.googleapis.com/css2?family=Roboto";</style>';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].policyField).toBe('resourceDomains');
+    expect(warnings[0].source).toBe('CSS @import');
+  });
+
+  it('should warn about <form action> not in connectDomains', () => {
+    const html = '<form action="https://api.example.com/submit"><input type="text"></form>';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].policyField).toBe('connectDomains');
+    expect(warnings[0].source).toBe('<form action>');
+  });
+
+  it('should not warn when form action origin is in connectDomains', () => {
+    const html = '<form action="https://api.example.com/submit"><input type="text"></form>';
+    const policy: IHtmlWidgetSecurityPolicy = {
+      ...EMPTY_POLICY,
+      connectDomains: ['https://api.example.com'],
+    };
+    const warnings = validateSecurityPolicy(html, policy);
+    expect(warnings).toEqual([]);
+  });
+
+  it('should warn about new EventSource() not in connectDomains', () => {
+    const html = '<script>new EventSource("https://sse.example.com/events")</script>';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].policyField).toBe('connectDomains');
+    expect(warnings[0].source).toBe('new EventSource()');
+  });
+
+  it('should warn about <audio src> not in resourceDomains', () => {
+    const html = '<audio src="https://media.example.com/song.mp3"></audio>';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].policyField).toBe('resourceDomains');
+    expect(warnings[0].source).toBe('<audio src>');
+  });
+
+  it('should warn about <video src> not in resourceDomains', () => {
+    const html = '<video src="https://media.example.com/clip.mp4"></video>';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].policyField).toBe('resourceDomains');
+    expect(warnings[0].source).toBe('<video src>');
+  });
+
+  it('should ignore relative URLs', () => {
+    const html = '<img src="./logo.png"><script src="/app.js"></script>';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toEqual([]);
+  });
+
+  it('should ignore data: URIs', () => {
+    const html = '<img src="data:image/png;base64,abc123">';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toEqual([]);
+  });
+
+  it('should detect multiple violations across different policy fields', () => {
+    const html = [
+      '<script src="https://cdn.example.com/lib.js"></script>',
+      '<script>fetch("https://api.example.com/data")</script>',
+      '<iframe src="https://embed.example.com/widget"></iframe>',
+    ].join('');
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toHaveLength(3);
+    expect(warnings.map((w) => w.policyField).sort()).toEqual([
+      'connectDomains',
+      'frameDomains',
+      'resourceDomains',
+    ]);
+  });
+
+  it('should handle wildcard * in policy', () => {
+    const html = '<script src="https://any-cdn.com/lib.js"></script>';
+    const policy: IHtmlWidgetSecurityPolicy = {
+      ...EMPTY_POLICY,
+      resourceDomains: ['*'],
+    };
+    const warnings = validateSecurityPolicy(html, policy);
+    expect(warnings).toEqual([]);
+  });
+
+  it('should handle protocol-relative URLs', () => {
+    const html = '<script src="//cdn.example.com/lib.js"></script>';
+    const warnings = validateSecurityPolicy(html, EMPTY_POLICY);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].policyField).toBe('resourceDomains');
+  });
+
+  it('should handle undefined policy fields gracefully', () => {
+    const html = '<script src="https://cdn.example.com/lib.js"></script>';
+    const warnings = validateSecurityPolicy(html, {});
+    expect(warnings).toHaveLength(1);
+  });
+});
+
+describe('debugCspViolations', () => {
+  it('should inject CSP violation listener when enabled', () => {
+    const result = injectWidgetProtocol('<body><p>Hello</p></body>', {
+      debugCspViolations: true,
+    });
+    expect(result).toContain('securitypolicyviolation');
+    expect(result).toContain('blockedURI');
+    expect(result).toContain('violatedDirective');
+  });
+
+  it('should not inject CSP violation listener by default', () => {
+    const result = injectWidgetProtocol('<body><p>Hello</p></body>');
+    expect(result).not.toContain('securitypolicyviolation');
+  });
+
+  it('should not inject CSP violation listener when explicitly false', () => {
+    const result = injectWidgetProtocol('<body><p>Hello</p></body>', {
+      debugCspViolations: false,
+    });
+    expect(result).not.toContain('securitypolicyviolation');
+  });
+});
diff --git a/packages/apps/src/utils/html-widget.ts b/packages/apps/src/utils/html-widget.ts
index a12a224d9..795baa36d 100644
--- a/packages/apps/src/utils/html-widget.ts
+++ b/packages/apps/src/utils/html-widget.ts
@@ -1,4 +1,4 @@
-import { IHtmlWidgetPayload } from '@microsoft/teams.api';
+import { IHtmlWidgetPayload, IHtmlWidgetSecurityPolicy } from '@microsoft/teams.api';
 
 /**
  * The MCP Apps protocol version used for the widget init handshake.
@@ -27,22 +27,6 @@ function validateHtmlWidgetPayload(payload: IHtmlWidgetPayload): void {
   }
 }
 
-/**
- * Known host notification types from the MCP Apps spec (`ui/notifications/*`).
- * These are the suffix portion of the full method name, e.g. 'tool-result'
- * maps to the JSON-RPC method `ui/notifications/tool-result`.
- *
- * @see MCP Apps Protocol (SEP-1865) - Notifications section
- */
-type WidgetNotification =
-  | 'tool-result'
-  | 'tool-input'
-  | 'tool-input-partial'
-  | 'tool-cancelled'
-  | 'host-context-changed'
-  | 'resource-teardown'
-  | (string & {});
-
 /**
  * Options for building an HTML widget markdown string.
  *
@@ -59,8 +43,35 @@ export interface IHtmlWidgetMarkdownOptions {
    * Text to include after the widget code block.
    */
   after?: string;
+
+  /**
+   * Options forwarded to {@link injectWidgetProtocol} when the protocol
+   * is auto-injected into the widget HTML. Use this to configure
+   * notifications, display modes, or enable CSP violation debugging
+   * without calling `injectWidgetProtocol` manually.
+   *
+   * The `name` field is always set from the payload's `name` and cannot
+   * be overridden here.
+   */
+  protocolOptions?: Omit<IInjectWidgetProtocolOptions, 'name'>;
 }
 
+/**
+ * Known host notification types from the MCP Apps spec (`ui/notifications/*`).
+ * These are the suffix portion of the full method name, e.g. 'tool-result'
+ * maps to the JSON-RPC method `ui/notifications/tool-result`.
+ *
+ * @see MCP Apps Protocol (SEP-1865) - Notifications section
+ */
+type WidgetNotification =
+  | 'tool-result'
+  | 'tool-input'
+  | 'tool-input-partial'
+  | 'tool-cancelled'
+  | 'host-context-changed'
+  | 'resource-teardown'
+  | (string & {});
+
 /**
  * Options for injecting the MCP Apps protocol into widget HTML.
  *
@@ -116,23 +127,38 @@ export interface IInjectWidgetProtocolOptions {
    * @default [] (no notification hooks injected)
    */
   notifications?: WidgetNotification[];
+
+  /**
+   * When true, injects a `securitypolicyviolation` event listener that logs CSP violations to the console. 
+   * This catches dynamically constructed URLs that static analysis ({@link validateSecurityPolicy}) cannot detect.
+   *
+   * Should only be enabled during development.
+   *
+   * @default false
+   */
+  debugCspViolations?: boolean;
 }
 
+// ---------------------------------------------------------------------------
+// Protocol injection
+// ---------------------------------------------------------------------------
+
 /**
  * Explicit mapping of notification names to their window callback names.
  * Only notifications in this map will have hooks injected.
  *
- * Confirmed in Teams spec: tool-result, tool-input
- * Not yet available in Teams: tool-input-partial, tool-cancelled,
- * host-context-changed, resource-teardown
+ * Supported in the Teams app bridge: tool-result, tool-input
+ * Not supported in the Teams app bridge: tool-input-partial, tool-cancelled
+ * Not yet available in Teams: host-context-changed, resource-teardown
  */
 const NOTIFICATION_CALLBACKS: Record<string, string> = {
-  // Confirmed in Teams
+  // Supported in the Teams app bridge
   'tool-result': 'onToolResult',
   'tool-input': 'onToolInput',
-  // MCP Apps spec (SEP-1865) - not yet available in Teams
+  // MCP Apps spec (SEP-1865) - not supported in the Teams app bridge
   'tool-input-partial': 'onToolInputPartial',
   'tool-cancelled': 'onToolCancelled',
+  // MCP Apps spec (SEP-1865) - not yet available in Teams
   'host-context-changed': 'onHostContextChanged',
   'resource-teardown': 'onResourceTeardown',
 };
@@ -183,7 +209,18 @@ export function injectWidgetProtocol(
       return `if(d.method==='${method}'&&window.${cb}){window.${cb}(d.params);}`;
     }).join('');
 
+  // CSP violation listener (dev-only, opt-in)
+  const cspDebug = options?.debugCspViolations
+    ? 'document.addEventListener(\'securitypolicyviolation\',function(e){'
+      + 'console.warn(\'[widget CSP violation]\',{'
+      + 'blockedURI:e.blockedURI,'
+      + 'violatedDirective:e.violatedDirective,'
+      + 'originalPolicy:e.originalPolicy'
+      + '});});'
+    : '';
+
   // Assemble the protocol script (minified for payload size):
+  // - (opt-in) Listen for CSP violations and log them
   // - Generate a unique request ID for the init handshake
   // - Define notifySize to report body height to the host
   // - Listen for messages: on init response, send initialized + size;
@@ -191,6 +228,7 @@ export function injectWidgetProtocol(
   // - Send ui/initialize request with app info and capabilities
   // - Report size on DOMContentLoaded
   const script = '<script>(function(){'
+    + cspDebug
     + 'var id=\'init-\'+Math.random().toString(36).slice(2);'
     + 'function notifySize(){window.parent.postMessage({jsonrpc:\'2.0\',method:\'ui/notifications/size-changed\',params:{height:document.body.scrollHeight}},\'*\');}'
     + 'window.addEventListener(\'message\',function(e){var d=e.data;if(!d||d.jsonrpc!==\'2.0\')return;'
@@ -240,7 +278,7 @@ export function buildHtmlWidgetMarkdown(
 
   const injectedPayload = {
     ...payload,
-    html: injectWidgetProtocol(payload.html, { name: payload.name }),
+    html: injectWidgetProtocol(payload.html, { name: payload.name, ...options?.protocolOptions }),
     securityPolicy: payload.securityPolicy ?? DEFAULT_SECURITY_POLICY,
   };
   const json = JSON.stringify(injectedPayload);
@@ -279,3 +317,170 @@ export function buildHtmlWidgetMessage(
     textFormat: 'extendedmarkdown',
   };
 }
+
+/**
+ * A warning produced by {@link validateSecurityPolicy} when the widget HTML
+ * references an external origin that is not present in the declared security
+ * policy.
+ *
+ * @experimental This API is in preview and may change in the future.
+ * Diagnostic: ExperimentalTeamsHtmlWidget
+ */
+export interface ISecurityPolicyWarning {
+  /** The URL or origin found in the HTML. */
+  url: string;
+
+  /** The HTML element or API where the reference was found (e.g. `<script>`, `fetch`). */
+  source: string;
+
+  /** The securityPolicy field that should include this origin. */
+  policyField: keyof IHtmlWidgetSecurityPolicy;
+
+  /** A human-readable description of the issue. */
+  message: string;
+}
+
+/**
+ * Extracts the origin (scheme + host) from a URL string.
+ * Returns null if the URL is relative, a data URI, or unparseable.
+ */
+function extractOrigin(url: string): string | null {
+  const trimmed = url.trim();
+  if (!trimmed || trimmed.startsWith('data:') || trimmed.startsWith('#') || trimmed.startsWith('blob:')) {
+    return null;
+  }
+
+  // Relative URLs are fine (they resolve to the iframe origin)
+  if (!trimmed.includes('://') && !trimmed.startsWith('//')) {
+    return null;
+  }
+
+  try {
+    const parsed = new URL(trimmed.startsWith('//') ? `https:${trimmed}` : trimmed);
+    return `${parsed.protocol}//${parsed.host}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Checks whether an origin is covered by a list of allowed domains/origins.
+ * Handles special CSP values like `'self'` and `*`.
+ */
+function isOriginAllowed(origin: string, allowedDomains: string[]): boolean {
+  if (allowedDomains.includes('*')) return true;
+  return allowedDomains.some((domain) => {
+    const cleaned = domain.replace(/^['"]|['"]$/g, '');
+    if (cleaned === '*') return true;
+    return origin === cleaned || origin.endsWith(`.${cleaned.replace(/^https?:\/\//, '')}`);
+  });
+}
+
+/**
+ * Validates that external references in widget HTML are covered by the
+ * declared security policy. Returns an array of warnings for any
+ * references to origins not present in the appropriate policy field.
+ *
+ * This is a static analysis tool - it cannot catch dynamically constructed
+ * URLs (e.g. `fetch('https://' + domain)`). Use the `debugCspViolations`
+ * option on {@link injectWidgetProtocol} for runtime detection.
+ *
+ * Note: The CSP keyword `'self'` cannot be validated statically because it
+ * resolves to the iframe's parent origin at runtime. References that would
+ * be allowed by `'self'` may still produce warnings.
+ *
+ * @param html - The raw HTML content of the widget.
+ * @param policy - The security policy to validate against.
+ * @returns An array of warnings. Empty array means no issues found.
+ *
+ * @experimental This API is in preview and may change in the future.
+ * Diagnostic: ExperimentalTeamsHtmlWidget
+ */
+export function validateSecurityPolicy(
+  html: string,
+  policy: IHtmlWidgetSecurityPolicy
+): ISecurityPolicyWarning[] {
+  const warnings: ISecurityPolicyWarning[] = [];
+
+  // resourceDomains: <script src>, <link href>, <img src>, <source src>,
+  // <audio src>, <video src>, CSS url(), @import
+  const resourcePatterns: Array<{ regex: RegExp; source: string }> = [
+    { regex: /<script[^>]+src=["']([^"']+)["']/gi, source: '<script src>' },
+    { regex: /<link[^>]+href=["']([^"']+)["']/gi, source: '<link href>' },
+    { regex: /<img[^>]+src=["']([^"']+)["']/gi, source: '<img src>' },
+    { regex: /<source[^>]+src=["']([^"']+)["']/gi, source: '<source src>' },
+    { regex: /<audio[^>]+src=["']([^"']+)["']/gi, source: '<audio src>' },
+    { regex: /<video[^>]+src=["']([^"']+)["']/gi, source: '<video src>' },
+    { regex: /url\(\s*["']([^"')]+)["']\s*\)/gi, source: 'CSS url()' },
+    { regex: /@import\s+["']([^"']+)["']/gi, source: 'CSS @import' },
+  ];
+
+  for (const { regex, source } of resourcePatterns) {
+    let match;
+    while ((match = regex.exec(html)) !== null) {
+      const origin = extractOrigin(match[1]);
+      if (origin && !isOriginAllowed(origin, policy.resourceDomains ?? [])) {
+        warnings.push({
+          url: match[1],
+          source,
+          policyField: 'resourceDomains',
+          message: `${source} references "${match[1]}" but origin "${origin}" is not in resourceDomains.`,
+        });
+      }
+    }
+  }
+
+  // connectDomains: fetch(), XMLHttpRequest.open(), new WebSocket(), new EventSource()
+  const connectPatterns: Array<{ regex: RegExp; source: string }> = [
+    { regex: /fetch\(\s*["']([^"']+)["']/gi, source: 'fetch()' },
+    { regex: /\.open\(\s*["'][A-Z]+["']\s*,\s*["']([^"']+)["']/gi, source: 'XMLHttpRequest.open()' },
+    { regex: /new\s+WebSocket\(\s*["']([^"']+)["']/gi, source: 'new WebSocket()' },
+    { regex: /new\s+EventSource\(\s*["']([^"']+)["']/gi, source: 'new EventSource()' },
+  ];
+
+  for (const { regex, source } of connectPatterns) {
+    let match;
+    while ((match = regex.exec(html)) !== null) {
+      const origin = extractOrigin(match[1]);
+      if (origin && !isOriginAllowed(origin, policy.connectDomains ?? [])) {
+        warnings.push({
+          url: match[1],
+          source,
+          policyField: 'connectDomains',
+          message: `${source} references "${match[1]}" but origin "${origin}" is not in connectDomains.`,
+        });
+      }
+    }
+  }
+
+  // frameDomains: <iframe src>
+  const iframeRegex = /<iframe[^>]+src=["']([^"']+)["']/gi;
+  let match;
+  while ((match = iframeRegex.exec(html)) !== null) {
+    const origin = extractOrigin(match[1]);
+    if (origin && !isOriginAllowed(origin, policy.frameDomains ?? [])) {
+      warnings.push({
+        url: match[1],
+        source: '<iframe src>',
+        policyField: 'frameDomains',
+        message: `<iframe src> references "${match[1]}" but origin "${origin}" is not in frameDomains.`,
+      });
+    }
+  }
+
+  // connectDomains: <form action> (form submissions can exfiltrate data)
+  const formRegex = /<form[^>]+action=["']([^"']+)["']/gi;
+  while ((match = formRegex.exec(html)) !== null) {
+    const origin = extractOrigin(match[1]);
+    if (origin && !isOriginAllowed(origin, policy.connectDomains ?? [])) {
+      warnings.push({
+        url: match[1],
+        source: '<form action>',
+        policyField: 'connectDomains',
+        message: `<form action> references "${match[1]}" but origin "${origin}" is not in connectDomains.`,
+      });
+    }
+  }
+
+  return warnings;
+}

From 26d8e70932aec87a33b0f02c0ff153ca7bbc8c74 Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Mon, 29 Jun 2026 13:02:25 -0700
Subject: [PATCH 11/12] Fix regex

---
 packages/apps/src/utils/html-widget.ts | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/packages/apps/src/utils/html-widget.ts b/packages/apps/src/utils/html-widget.ts
index 795baa36d..f324bab5c 100644
--- a/packages/apps/src/utils/html-widget.ts
+++ b/packages/apps/src/utils/html-widget.ts
@@ -405,12 +405,12 @@ export function validateSecurityPolicy(
   // resourceDomains: <script src>, <link href>, <img src>, <source src>,
   // <audio src>, <video src>, CSS url(), @import
   const resourcePatterns: Array<{ regex: RegExp; source: string }> = [
-    { regex: /<script[^>]+src=["']([^"']+)["']/gi, source: '<script src>' },
-    { regex: /<link[^>]+href=["']([^"']+)["']/gi, source: '<link href>' },
-    { regex: /<img[^>]+src=["']([^"']+)["']/gi, source: '<img src>' },
-    { regex: /<source[^>]+src=["']([^"']+)["']/gi, source: '<source src>' },
-    { regex: /<audio[^>]+src=["']([^"']+)["']/gi, source: '<audio src>' },
-    { regex: /<video[^>]+src=["']([^"']+)["']/gi, source: '<video src>' },
+    { regex: /<script[^>]*?src=["']([^"']+)["']/gi, source: '<script src>' },
+    { regex: /<link[^>]*?href=["']([^"']+)["']/gi, source: '<link href>' },
+    { regex: /<img[^>]*?src=["']([^"']+)["']/gi, source: '<img src>' },
+    { regex: /<source[^>]*?src=["']([^"']+)["']/gi, source: '<source src>' },
+    { regex: /<audio[^>]*?src=["']([^"']+)["']/gi, source: '<audio src>' },
+    { regex: /<video[^>]*?src=["']([^"']+)["']/gi, source: '<video src>' },
     { regex: /url\(\s*["']([^"')]+)["']\s*\)/gi, source: 'CSS url()' },
     { regex: /@import\s+["']([^"']+)["']/gi, source: 'CSS @import' },
   ];
@@ -454,7 +454,7 @@ export function validateSecurityPolicy(
   }
 
   // frameDomains: <iframe src>
-  const iframeRegex = /<iframe[^>]+src=["']([^"']+)["']/gi;
+  const iframeRegex = /<iframe[^>]*?src=["']([^"']+)["']/gi;
   let match;
   while ((match = iframeRegex.exec(html)) !== null) {
     const origin = extractOrigin(match[1]);
@@ -469,7 +469,7 @@ export function validateSecurityPolicy(
   }
 
   // connectDomains: <form action> (form submissions can exfiltrate data)
-  const formRegex = /<form[^>]+action=["']([^"']+)["']/gi;
+  const formRegex = /<form[^>]*?action=["']([^"']+)["']/gi;
   while ((match = formRegex.exec(html)) !== null) {
     const origin = extractOrigin(match[1]);
     if (origin && !isOriginAllowed(origin, policy.connectDomains ?? [])) {

From d42d68f0425dd5126a15ca8a92029ab064fde730 Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Mon, 29 Jun 2026 13:08:32 -0700
Subject: [PATCH 12/12] Fix for regex

---
 packages/apps/src/utils/html-widget.ts | 90 +++++++++++++++++---------
 1 file changed, 61 insertions(+), 29 deletions(-)

diff --git a/packages/apps/src/utils/html-widget.ts b/packages/apps/src/utils/html-widget.ts
index f324bab5c..5ce5055a0 100644
--- a/packages/apps/src/utils/html-widget.ts
+++ b/packages/apps/src/utils/html-widget.ts
@@ -404,18 +404,42 @@ export function validateSecurityPolicy(
 
   // resourceDomains: <script src>, <link href>, <img src>, <source src>,
   // <audio src>, <video src>, CSS url(), @import
-  const resourcePatterns: Array<{ regex: RegExp; source: string }> = [
-    { regex: /<script[^>]*?src=["']([^"']+)["']/gi, source: '<script src>' },
-    { regex: /<link[^>]*?href=["']([^"']+)["']/gi, source: '<link href>' },
-    { regex: /<img[^>]*?src=["']([^"']+)["']/gi, source: '<img src>' },
-    { regex: /<source[^>]*?src=["']([^"']+)["']/gi, source: '<source src>' },
-    { regex: /<audio[^>]*?src=["']([^"']+)["']/gi, source: '<audio src>' },
-    { regex: /<video[^>]*?src=["']([^"']+)["']/gi, source: '<video src>' },
+  // Two-step extraction avoids polynomial backtracking (CodeQL ReDoS):
+  // Step 1: find opening tags; Step 2: extract attribute from tag content.
+  const tagAttrPatterns: Array<{ tagRegex: RegExp; attrRegex: RegExp; source: string }> = [
+    { tagRegex: /<script\s[^>]*>/gi, attrRegex: /src=["']([^"']+)["']/i, source: '<script src>' },
+    { tagRegex: /<link\s[^>]*>/gi, attrRegex: /href=["']([^"']+)["']/i, source: '<link href>' },
+    { tagRegex: /<img\s[^>]*>/gi, attrRegex: /src=["']([^"']+)["']/i, source: '<img src>' },
+    { tagRegex: /<source\s[^>]*>/gi, attrRegex: /src=["']([^"']+)["']/i, source: '<source src>' },
+    { tagRegex: /<audio\s[^>]*>/gi, attrRegex: /src=["']([^"']+)["']/i, source: '<audio src>' },
+    { tagRegex: /<video\s[^>]*>/gi, attrRegex: /src=["']([^"']+)["']/i, source: '<video src>' },
+  ];
+
+  for (const { tagRegex, attrRegex, source } of tagAttrPatterns) {
+    let tagMatch;
+    while ((tagMatch = tagRegex.exec(html)) !== null) {
+      const attrMatch = tagMatch[0].match(attrRegex);
+      if (attrMatch) {
+        const origin = extractOrigin(attrMatch[1]);
+        if (origin && !isOriginAllowed(origin, policy.resourceDomains ?? [])) {
+          warnings.push({
+            url: attrMatch[1],
+            source,
+            policyField: 'resourceDomains',
+            message: `${source} references "${attrMatch[1]}" but origin "${origin}" is not in resourceDomains.`,
+          });
+        }
+      }
+    }
+  }
+
+  // CSS url() and @import (no tag-level backtracking risk)
+  const cssPatterns: Array<{ regex: RegExp; source: string }> = [
     { regex: /url\(\s*["']([^"')]+)["']\s*\)/gi, source: 'CSS url()' },
     { regex: /@import\s+["']([^"']+)["']/gi, source: 'CSS @import' },
   ];
 
-  for (const { regex, source } of resourcePatterns) {
+  for (const { regex, source } of cssPatterns) {
     let match;
     while ((match = regex.exec(html)) !== null) {
       const origin = extractOrigin(match[1]);
@@ -454,31 +478,39 @@ export function validateSecurityPolicy(
   }
 
   // frameDomains: <iframe src>
-  const iframeRegex = /<iframe[^>]*?src=["']([^"']+)["']/gi;
-  let match;
-  while ((match = iframeRegex.exec(html)) !== null) {
-    const origin = extractOrigin(match[1]);
-    if (origin && !isOriginAllowed(origin, policy.frameDomains ?? [])) {
-      warnings.push({
-        url: match[1],
-        source: '<iframe src>',
-        policyField: 'frameDomains',
-        message: `<iframe src> references "${match[1]}" but origin "${origin}" is not in frameDomains.`,
-      });
+  const iframeTagRegex = /<iframe\s[^>]*>/gi;
+  const iframeSrcRegex = /src=["']([^"']+)["']/i;
+  let tagMatch;
+  while ((tagMatch = iframeTagRegex.exec(html)) !== null) {
+    const attrMatch = tagMatch[0].match(iframeSrcRegex);
+    if (attrMatch) {
+      const origin = extractOrigin(attrMatch[1]);
+      if (origin && !isOriginAllowed(origin, policy.frameDomains ?? [])) {
+        warnings.push({
+          url: attrMatch[1],
+          source: '<iframe src>',
+          policyField: 'frameDomains',
+          message: `<iframe src> references "${attrMatch[1]}" but origin "${origin}" is not in frameDomains.`,
+        });
+      }
     }
   }
 
   // connectDomains: <form action> (form submissions can exfiltrate data)
-  const formRegex = /<form[^>]*?action=["']([^"']+)["']/gi;
-  while ((match = formRegex.exec(html)) !== null) {
-    const origin = extractOrigin(match[1]);
-    if (origin && !isOriginAllowed(origin, policy.connectDomains ?? [])) {
-      warnings.push({
-        url: match[1],
-        source: '<form action>',
-        policyField: 'connectDomains',
-        message: `<form action> references "${match[1]}" but origin "${origin}" is not in connectDomains.`,
-      });
+  const formTagRegex = /<form\s[^>]*>/gi;
+  const formActionRegex = /action=["']([^"']+)["']/i;
+  while ((tagMatch = formTagRegex.exec(html)) !== null) {
+    const attrMatch = tagMatch[0].match(formActionRegex);
+    if (attrMatch) {
+      const origin = extractOrigin(attrMatch[1]);
+      if (origin && !isOriginAllowed(origin, policy.connectDomains ?? [])) {
+        warnings.push({
+          url: attrMatch[1],
+          source: '<form action>',
+          policyField: 'connectDomains',
+          message: `<form action> references "${attrMatch[1]}" but origin "${origin}" is not in connectDomains.`,
+        });
+      }
     }
   }