From 0d4d85e2429a5a0df4f5f3e59183fe3ba1c2277d Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Wed, 1 Jul 2026 12:38:23 -0700
Subject: [PATCH 1/6] HTML Widgets

---
 .../Handlers/HtmlWidgetCallToolHandler.cs     |  54 ++
 .../Handlers/InvokeHandler.Activity.cs        |  46 +-
 .../HtmlWidget/CallToolRequest.cs             |  28 +
 .../HtmlWidget/CallToolResult.cs              | 109 ++++
 .../HtmlWidget/HtmlWidgetHelpers.cs           | 488 ++++++++++++++++++
 .../HtmlWidget/HtmlWidgetPayload.cs           | 146 ++++++
 6 files changed, 870 insertions(+), 1 deletion(-)
 create mode 100644 core/src/Microsoft.Teams.Apps/Handlers/HtmlWidgetCallToolHandler.cs
 create mode 100644 core/src/Microsoft.Teams.Apps/HtmlWidget/CallToolRequest.cs
 create mode 100644 core/src/Microsoft.Teams.Apps/HtmlWidget/CallToolResult.cs
 create mode 100644 core/src/Microsoft.Teams.Apps/HtmlWidget/HtmlWidgetHelpers.cs
 create mode 100644 core/src/Microsoft.Teams.Apps/HtmlWidget/HtmlWidgetPayload.cs

diff --git a/core/src/Microsoft.Teams.Apps/Handlers/HtmlWidgetCallToolHandler.cs b/core/src/Microsoft.Teams.Apps/Handlers/HtmlWidgetCallToolHandler.cs
new file mode 100644
index 00000000..ed0c6dd7
--- /dev/null
+++ b/core/src/Microsoft.Teams.Apps/Handlers/HtmlWidgetCallToolHandler.cs
@@ -0,0 +1,54 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Diagnostics.CodeAnalysis;
+
+using Microsoft.Teams.Apps.Handlers;
+using Microsoft.Teams.Apps.HtmlWidget;
+using Microsoft.Teams.Apps.Routing;
+using Microsoft.Teams.Apps.Schema;
+
+namespace Microsoft.Teams.Apps.Handlers;
+
+/// <summary>
+/// Delegate for handling <c>htmlwidget/calltool</c> invoke activities.
+/// Sent when a widget calls a tool on the bot via the MCP Apps protocol.
+/// </summary>
+/// <param name="context">The context for the invoke activity with a strongly-typed <see cref="CallToolRequest"/> value.</param>
+/// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
+/// <returns>A task that represents the asynchronous operation. The task result contains the invoke response.</returns>
+[Experimental("ExperimentalTeamsHtmlWidget")]
+public delegate Task<InvokeResponse> HtmlWidgetCallToolHandler(Context<InvokeActivity<CallToolRequest>> context, CancellationToken cancellationToken = default);
+
+/// <summary>
+/// Extension methods for registering HTML widget call tool invoke handlers.
+/// </summary>
+[Experimental("ExperimentalTeamsHtmlWidget")]
+public static class HtmlWidgetCallToolExtensions
+{
+    /// <summary>
+    /// Registers a handler for <c>htmlwidget/calltool</c> invoke activities.
+    /// Triggered when a widget calls a tool on the bot.
+    /// Cannot be combined with <see cref="InvokeExtensions.OnInvoke"/>.
+    /// </summary>
+    /// <param name="app">The Teams bot application.</param>
+    /// <param name="handler">The handler to register.</param>
+    /// <returns>The updated Teams bot application.</returns>
+    public static TeamsBotApplication OnWidgetCallTool(this TeamsBotApplication app, HtmlWidgetCallToolHandler handler)
+    {
+        ArgumentNullException.ThrowIfNull(app, nameof(app));
+        app.Router.Register(new Route<InvokeActivity>
+        {
+            Name = string.Join("/", TeamsActivityTypes.Invoke, InvokeNames.HtmlWidgetCallTool),
+            Selector = activity => activity.Name == InvokeNames.HtmlWidgetCallTool,
+            HandlerWithReturn = async (ctx, cancellationToken) =>
+            {
+                InvokeActivity<CallToolRequest> typedActivity = new(ctx.Activity);
+                var typedContext = ctx.CreateDerivedContext(typedActivity);
+                return await handler(typedContext, cancellationToken).ConfigureAwait(false);
+            }
+        });
+
+        return app;
+    }
+}
diff --git a/core/src/Microsoft.Teams.Apps/Handlers/InvokeHandler.Activity.cs b/core/src/Microsoft.Teams.Apps/Handlers/InvokeHandler.Activity.cs
index 92f71f46..b4509d51 100644
--- a/core/src/Microsoft.Teams.Apps/Handlers/InvokeHandler.Activity.cs
+++ b/core/src/Microsoft.Teams.Apps/Handlers/InvokeHandler.Activity.cs
@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+using System.Diagnostics.CodeAnalysis;
 using System.Text.Json;
 using System.Text.Json.Nodes;
 using System.Text.Json.Serialization;
@@ -184,10 +185,53 @@ public static class InvokeNames
     /// </summary>
     public const string MessageSubmitAction = "message/submitAction";
 
+    /// <summary>
+    /// HTML widget call tool invoke name.
+    /// </summary>
+    [Experimental("ExperimentalTeamsHtmlWidget")]
+    public const string HtmlWidgetCallTool = "htmlwidget/calltool";
+
     /// <summary>
     /// Suggested action submit invoke name.
     /// Sent when the user clicks a suggested action of type <c>Action.Submit</c>.
     /// </summary>
-    [System.Diagnostics.CodeAnalysis.Experimental("ExperimentalTeamsSuggestedAction")]
+    [Experimental("ExperimentalTeamsSuggestedAction")]
     public const string SuggestedActionSubmit = "suggestedActions/submit";
+
+    //TODO : review
+    /*
+    /// <summary>
+    /// Execute action invoke name.
+    /// </summary>
+    public const string ExecuteAction = "actionableMessage/executeAction";
+
+    /// <summary>
+    /// Handoff invoke name.
+    /// </summary>
+    public const string Handoff = "handoff/action";
+
+    /// <summary>
+    /// Search invoke name.
+    /// </summary>
+    public const string Search = "search";
+    /// <summary>
+    /// Config fetch invoke name.
+    /// </summary>
+    public const string ConfigFetch = "config/fetch";
+
+    /// <summary>
+    /// Config submit invoke name.
+    /// </summary>
+    public const string ConfigSubmit = "config/submit";
+
+     /// <summary>
+     /// Message extension card button clicked invoke name.
+     /// </summary>
+     public const string MessageExtensionCardButtonClicked = "composeExtension/onCardButtonClicked";
+
+     /// <summary>
+     /// Message extension setting invoke name.
+     /// </summary>
+     public const string MessageExtensionSetting = "composeExtension/setting";
+     */
 }
diff --git a/core/src/Microsoft.Teams.Apps/HtmlWidget/CallToolRequest.cs b/core/src/Microsoft.Teams.Apps/HtmlWidget/CallToolRequest.cs
new file mode 100644
index 00000000..5a7a2393
--- /dev/null
+++ b/core/src/Microsoft.Teams.Apps/HtmlWidget/CallToolRequest.cs
@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+
+namespace Microsoft.Teams.Apps.HtmlWidget;
+
+/// <summary>
+/// A request from a widget to call a tool on the bot.
+/// Sent as the value of an <c>htmlwidget/calltool</c> invoke activity.
+/// </summary>
+[Experimental("ExperimentalTeamsHtmlWidget")]
+public class CallToolRequest
+{
+    /// <summary>
+    /// The name of the tool to call.
+    /// </summary>
+    [JsonPropertyName("name")]
+    public string Name { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The arguments to pass to the tool.
+    /// </summary>
+    [JsonPropertyName("arguments")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public object? Arguments { get; set; }
+}
diff --git a/core/src/Microsoft.Teams.Apps/HtmlWidget/CallToolResult.cs b/core/src/Microsoft.Teams.Apps/HtmlWidget/CallToolResult.cs
new file mode 100644
index 00000000..27a7bf9a
--- /dev/null
+++ b/core/src/Microsoft.Teams.Apps/HtmlWidget/CallToolResult.cs
@@ -0,0 +1,109 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+
+namespace Microsoft.Teams.Apps.HtmlWidget;
+
+/// <summary>
+/// A content item in an MCP UI call tool result.
+/// </summary>
+[Experimental("ExperimentalTeamsHtmlWidget")]
+public class McpUiCallToolResultContent
+{
+    /// <summary>
+    /// The type of content (e.g. "text").
+    /// </summary>
+    [JsonPropertyName("type")]
+    public string Type { get; set; } = "text";
+
+    /// <summary>
+    /// The text content.
+    /// </summary>
+    [JsonPropertyName("text")]
+    public string Text { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// The result of a widget's <c>tools/call</c> request, returned by the bot
+/// in response to an <c>htmlwidget/calltool</c> invoke activity.
+/// </summary>
+[Experimental("ExperimentalTeamsHtmlWidget")]
+public class McpUiCallToolResult
+{
+    /// <summary>
+    /// An array of content items to return to the widget.
+    /// </summary>
+    [JsonPropertyName("content")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public IList<McpUiCallToolResultContent>? Content { get; set; }
+
+    /// <summary>
+    /// Structured data that the widget can render from.
+    /// </summary>
+    [JsonPropertyName("structuredContent")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public object? StructuredContent { get; set; }
+
+    /// <summary>
+    /// Whether the tool call resulted in an error.
+    /// </summary>
+    [JsonPropertyName("isError")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
+    public bool IsError { get; set; }
+}
+
+/// <summary>
+/// The wire-format response body for an <c>htmlwidget/calltool</c> invoke.
+/// Teams expects this shape (with <c>responseType</c> discriminator) rather than
+/// a bare <see cref="McpUiCallToolResult"/>.
+/// </summary>
+[Experimental("ExperimentalTeamsHtmlWidget")]
+public class HtmlWidgetCallToolResponse
+{
+    /// <summary>
+    /// Discriminator that tells Teams how to interpret the response.
+    /// </summary>
+    [JsonPropertyName("responseType")]
+    public string ResponseType { get; set; } = "htmlwidget/calltoolresult";
+
+    /// <summary>
+    /// The tool call result payload.
+    /// </summary>
+    [JsonPropertyName("callToolResult")]
+    public McpUiCallToolResult CallToolResult { get; set; } = new();
+
+    /// <summary>
+    /// Creates a successful response with text content.
+    /// </summary>
+    /// <param name="text">The text to return to the widget.</param>
+    /// <returns>A new <see cref="HtmlWidgetCallToolResponse"/>.</returns>
+    public static HtmlWidgetCallToolResponse FromText(string text)
+    {
+        return new HtmlWidgetCallToolResponse
+        {
+            CallToolResult = new McpUiCallToolResult
+            {
+                Content = [new McpUiCallToolResultContent { Type = "text", Text = text }]
+            }
+        };
+    }
+
+    /// <summary>
+    /// Creates an error response with a message.
+    /// </summary>
+    /// <param name="message">The error message.</param>
+    /// <returns>A new <see cref="HtmlWidgetCallToolResponse"/> with IsError set.</returns>
+    public static HtmlWidgetCallToolResponse FromError(string message)
+    {
+        return new HtmlWidgetCallToolResponse
+        {
+            CallToolResult = new McpUiCallToolResult
+            {
+                Content = [new McpUiCallToolResultContent { Type = "text", Text = message }],
+                IsError = true
+            }
+        };
+    }
+}
diff --git a/core/src/Microsoft.Teams.Apps/HtmlWidget/HtmlWidgetHelpers.cs b/core/src/Microsoft.Teams.Apps/HtmlWidget/HtmlWidgetHelpers.cs
new file mode 100644
index 00000000..c69e75d0
--- /dev/null
+++ b/core/src/Microsoft.Teams.Apps/HtmlWidget/HtmlWidgetHelpers.cs
@@ -0,0 +1,488 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Globalization;
+using System.Text;
+using System.Text.Json;
+using System.Text.RegularExpressions;
+
+using Microsoft.Teams.Apps.Schema;
+
+namespace Microsoft.Teams.Apps.HtmlWidget;
+
+/// <summary>
+/// Options for injecting the MCP Apps protocol into widget HTML.
+/// </summary>
+[Experimental("ExperimentalTeamsHtmlWidget")]
+public class InjectWidgetProtocolOptions
+{
+    /// <summary>
+    /// The widget app name sent during ui/initialize.
+    /// </summary>
+    public string Name { get; set; } = "widget";
+
+    /// <summary>
+    /// The widget app version sent during ui/initialize.
+    /// </summary>
+    public string Version { get; set; } = "1.0.0";
+
+    /// <summary>
+    /// Display modes this widget supports.
+    /// </summary>
+    public IList<string>? AvailableDisplayModes { get; set; }
+
+    /// <summary>
+    /// Host notifications to listen for.
+    /// Known values: "tool-result", "tool-input", "tool-input-partial",
+    /// "tool-cancelled", "host-context-changed", "resource-teardown".
+    /// </summary>
+    public IList<string>? Notifications { get; set; }
+
+    /// <summary>
+    /// When true, injects a CSP violation listener for debugging.
+    /// </summary>
+    public bool DebugCspViolations { get; set; }
+}
+
+/// <summary>
+/// Options for building an HTML widget markdown string.
+/// </summary>
+[Experimental("ExperimentalTeamsHtmlWidget")]
+public class HtmlWidgetMarkdownOptions
+{
+    /// <summary>
+    /// Text to include before the widget code block.
+    /// </summary>
+    public string? Before { get; set; }
+
+    /// <summary>
+    /// Text to include after the widget code block.
+    /// </summary>
+    public string? After { get; set; }
+
+    /// <summary>
+    /// Options forwarded to <see cref="HtmlWidgetHelpers.InjectWidgetProtocol"/> when the protocol
+    /// is auto-injected. The Name field is always set from the payload's Name.
+    /// </summary>
+    public InjectWidgetProtocolOptions? ProtocolOptions { get; set; }
+}
+
+/// <summary>
+/// A warning produced by <see cref="HtmlWidgetHelpers.ValidateSecurityPolicy"/> when the widget HTML
+/// references an external origin not present in the declared security policy.
+/// </summary>
+[Experimental("ExperimentalTeamsHtmlWidget")]
+public class SecurityPolicyWarning
+{
+    /// <summary>
+    /// The URL or origin found in the HTML.
+    /// </summary>
+    [SuppressMessage("Design", "CA1056:URI-like properties should not be strings", Justification = "May contain relative URLs, fragments, or unparseable values")]
+    public string Url { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The HTML element or API where the reference was found.
+    /// </summary>
+    public string Source { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The securityPolicy field that should include this origin.
+    /// </summary>
+    public string PolicyField { get; set; } = string.Empty;
+
+    /// <summary>
+    /// A human-readable description of the issue.
+    /// </summary>
+    public string Message { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// Helper methods for building and validating HTML widget messages.
+/// </summary>
+[Experimental("ExperimentalTeamsHtmlWidget")]
+public static class HtmlWidgetHelpers
+{
+    private const string McpProtocolVersion = "2026-01-26";
+
+    private static readonly Dictionary<string, string> NotificationCallbacks = new()
+    {
+        ["tool-result"] = "onToolResult",
+        ["tool-input"] = "onToolInput",
+        ["tool-input-partial"] = "onToolInputPartial",
+        ["tool-cancelled"] = "onToolCancelled",
+        ["host-context-changed"] = "onHostContextChanged",
+        ["resource-teardown"] = "onResourceTeardown",
+    };
+
+    private static readonly HtmlWidgetSecurityPolicy DefaultSecurityPolicy = new()
+    {
+        ConnectDomains = [],
+        ResourceDomains = ["'self'", "data:"],
+        FrameDomains = [],
+        BaseUriDomains = [],
+    };
+
+    /// <summary>
+    /// Injects the MCP Apps protocol script into widget HTML.
+    /// If the HTML already contains the protocol (detected by "ui/initialize"), it is returned unchanged.
+    /// </summary>
+    /// <param name="html">The raw HTML content for the widget.</param>
+    /// <param name="options">Optional configuration for the protocol setup.</param>
+    /// <returns>The HTML with the protocol script injected.</returns>
+    public static string InjectWidgetProtocol(string html, InjectWidgetProtocolOptions? options = null)
+    {
+        ArgumentNullException.ThrowIfNull(html);
+
+        if (html.Contains("ui/initialize", StringComparison.Ordinal))
+        {
+            return html;
+        }
+
+        var name = EscapeForInlineScript(options?.Name ?? "widget");
+        var version = EscapeForInlineScript(options?.Version ?? "1.0.0");
+
+        var capsJson = options?.AvailableDisplayModes is { Count: > 0 } modes
+            ? $"{{availableDisplayModes:{JsonSerializer.Serialize(modes)}}}"
+            : "{}";
+
+        var hookLines = new StringBuilder();
+        if (options?.Notifications is { Count: > 0 } notifications)
+        {
+            foreach (var n in notifications)
+            {
+                if (NotificationCallbacks.TryGetValue(n, out var cb))
+                {
+                    hookLines.Append(CultureInfo.InvariantCulture, $"if(d.method==='ui/notifications/{n}'&&window.{cb}){{window.{cb}(d.params);}}");
+                }
+            }
+        }
+
+        var cspDebug = options?.DebugCspViolations == true
+            ? "document.addEventListener('securitypolicyviolation',function(e){"
+              + "console.warn('[widget CSP violation]',{"
+              + "blockedURI:e.blockedURI,"
+              + "violatedDirective:e.violatedDirective,"
+              + "originalPolicy:e.originalPolicy"
+              + "});});"
+            : "";
+
+        var 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;"
+            + "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:'{McpProtocolVersion}',appInfo:{{name:'{name}',version:'{version}'}},appCapabilities:{capsJson}}}}},'*');"
+            + "document.addEventListener('DOMContentLoaded',notifySize);"
+            + "})()</script>";
+
+        if (html.Contains("</body>", StringComparison.Ordinal))
+        {
+            return html.Replace("</body>", script + "</body>", StringComparison.Ordinal);
+        }
+
+        return html + script;
+    }
+
+    /// <summary>
+    /// Wraps an HTML widget payload in the ```html-widget markdown code fence
+    /// format required by Teams to render the widget in a message.
+    /// </summary>
+    /// <param name="payload">The widget payload to serialize.</param>
+    /// <param name="options">Optional text to include before/after the widget block.</param>
+    /// <returns>The markdown string containing the widget code block.</returns>
+    public static string BuildHtmlWidgetMarkdown(HtmlWidgetPayload payload, HtmlWidgetMarkdownOptions? options = null)
+    {
+        ArgumentNullException.ThrowIfNull(payload);
+        ValidatePayload(payload);
+
+        var protocolOpts = new InjectWidgetProtocolOptions
+        {
+            Name = payload.Name,
+            Version = options?.ProtocolOptions?.Version ?? "1.0.0",
+            AvailableDisplayModes = options?.ProtocolOptions?.AvailableDisplayModes,
+            Notifications = options?.ProtocolOptions?.Notifications,
+            DebugCspViolations = options?.ProtocolOptions?.DebugCspViolations ?? false,
+        };
+
+        var injectedPayload = new HtmlWidgetPayload
+        {
+            Type = payload.Type,
+            Name = payload.Name,
+            Description = payload.Description,
+            Html = InjectWidgetProtocol(payload.Html, protocolOpts),
+            Domain = payload.Domain,
+            SecurityPolicy = payload.SecurityPolicy ?? DefaultSecurityPolicy,
+            ToolInput = payload.ToolInput,
+            ToolOutput = payload.ToolOutput,
+            Permissions = payload.Permissions,
+        };
+
+        var json = JsonSerializer.Serialize(injectedPayload);
+        var parts = new List<string>();
+
+        if (!string.IsNullOrEmpty(options?.Before))
+        {
+            parts.Add(options.Before);
+            parts.Add("");
+        }
+
+        parts.Add("```html-widget");
+        parts.Add(json);
+        parts.Add("```");
+
+        if (!string.IsNullOrEmpty(options?.After))
+        {
+            parts.Add("");
+            parts.Add(options.After);
+        }
+
+        return string.Join("\n", parts);
+    }
+
+    /// <summary>
+    /// Builds a message activity containing an HTML widget, ready to be sent.
+    /// </summary>
+    /// <param name="payload">The widget payload to include in the message.</param>
+    /// <param name="options">Optional text to include before/after the widget block.</param>
+    /// <returns>A MessageActivity with TextFormat set to "extendedmarkdown".</returns>
+    public static MessageActivity BuildHtmlWidgetMessage(HtmlWidgetPayload payload, HtmlWidgetMarkdownOptions? options = null)
+    {
+        return new MessageActivity
+        {
+            Text = BuildHtmlWidgetMarkdown(payload, options),
+            TextFormat = TextFormats.ExtendedMarkdown,
+        };
+    }
+
+    /// <summary>
+    /// Validates that external references in widget HTML are covered by the
+    /// declared security policy. Returns a list of warnings for any
+    /// references to origins not present in the appropriate policy field.
+    /// </summary>
+    /// <param name="html">The raw HTML content of the widget.</param>
+    /// <param name="policy">The security policy to validate against.</param>
+    /// <returns>A list of warnings. Empty list means no issues found.</returns>
+    public static IList<SecurityPolicyWarning> ValidateSecurityPolicy(string html, HtmlWidgetSecurityPolicy policy)
+    {
+        ArgumentNullException.ThrowIfNull(html);
+        ArgumentNullException.ThrowIfNull(policy);
+
+        var warnings = new List<SecurityPolicyWarning>();
+
+        // resourceDomains: <script src>, <link href>, <img src>, <source src>, <audio src>, <video src>
+        CheckTagAttribute(html, "script", "src", "resourceDomains", "<script src>", policy.ResourceDomains, warnings);
+        CheckTagAttribute(html, "link", "href", "resourceDomains", "<link href>", policy.ResourceDomains, warnings);
+        CheckTagAttribute(html, "img", "src", "resourceDomains", "<img src>", policy.ResourceDomains, warnings);
+        CheckTagAttribute(html, "source", "src", "resourceDomains", "<source src>", policy.ResourceDomains, warnings);
+        CheckTagAttribute(html, "audio", "src", "resourceDomains", "<audio src>", policy.ResourceDomains, warnings);
+        CheckTagAttribute(html, "video", "src", "resourceDomains", "<video src>", policy.ResourceDomains, warnings);
+
+        // CSS url() and @import
+        CheckCssPatterns(html, policy.ResourceDomains, warnings);
+
+        // connectDomains: fetch(), XMLHttpRequest.open(), new WebSocket(), new EventSource()
+        CheckConnectPatterns(html, policy.ConnectDomains, warnings);
+
+        // frameDomains: <iframe src>
+        CheckTagAttribute(html, "iframe", "src", "frameDomains", "<iframe src>", policy.FrameDomains, warnings);
+
+        // connectDomains: <form action>
+        CheckTagAttribute(html, "form", "action", "connectDomains", "<form action>", policy.ConnectDomains, warnings);
+
+        return warnings;
+    }
+
+    private static void ValidatePayload(HtmlWidgetPayload payload)
+    {
+        if (string.IsNullOrWhiteSpace(payload.Name))
+        {
+            throw new ArgumentException("HTML widget payload requires a non-empty \"name\" field.");
+        }
+
+        if (string.IsNullOrWhiteSpace(payload.Html))
+        {
+            throw new ArgumentException("HTML widget payload requires a non-empty \"html\" field.");
+        }
+
+        if (string.IsNullOrWhiteSpace(payload.Domain) || !payload.Domain.StartsWith("https://", StringComparison.Ordinal))
+        {
+            throw new ArgumentException("HTML widget payload requires \"domain\" to be a valid URL starting with \"https://\".");
+        }
+    }
+
+    private static string EscapeForInlineScript(string value)
+    {
+        return value
+            .Replace("\\", "\\\\", StringComparison.Ordinal)
+            .Replace("'", "\\'", StringComparison.Ordinal)
+            .Replace("</", "<\\/", StringComparison.Ordinal)
+            .Replace("\n", "\\n", StringComparison.Ordinal)
+            .Replace("\r", "\\r", StringComparison.Ordinal);
+    }
+
+    private static string? ExtractOrigin(string url)
+    {
+        var trimmed = url.Trim();
+        if (string.IsNullOrEmpty(trimmed) || trimmed.StartsWith("data:", StringComparison.Ordinal) || trimmed.StartsWith('#') || trimmed.StartsWith("blob:", StringComparison.Ordinal))
+        {
+            return null;
+        }
+
+        if (!trimmed.Contains("://", StringComparison.Ordinal) && !trimmed.StartsWith("//", StringComparison.Ordinal))
+        {
+            return null;
+        }
+
+        try
+        {
+            var fullUrl = trimmed.StartsWith("//", StringComparison.Ordinal) ? $"https:{trimmed}" : trimmed;
+            var uri = new Uri(fullUrl);
+            return $"{uri.Scheme}://{uri.Host}{(uri.IsDefaultPort ? "" : $":{uri.Port}")}";
+        }
+        catch (UriFormatException)
+        {
+            return null;
+        }
+    }
+
+    private static bool IsOriginAllowed(string origin, IList<string>? allowedDomains)
+    {
+        if (allowedDomains is null || allowedDomains.Count == 0) return false;
+        if (allowedDomains.Contains("*")) return true;
+
+        foreach (var domain in allowedDomains)
+        {
+            var cleaned = domain.Trim('\'', '"');
+            if (cleaned == "*") return true;
+            if (origin == cleaned) return true;
+
+            var domainHost = Regex.Replace(cleaned, @"^https?://", "");
+            if (origin.EndsWith($".{domainHost}", StringComparison.OrdinalIgnoreCase)) return true;
+        }
+
+        return false;
+    }
+
+    private static void CheckTagAttribute(
+        string html,
+        string tagName,
+        string attrName,
+        string policyField,
+        string source,
+        IList<string>? allowedDomains,
+        List<SecurityPolicyWarning> warnings)
+    {
+        var upperHtml = html.ToUpperInvariant();
+        var needle = $"<{tagName}".ToUpperInvariant();
+        var pos = 0;
+
+        while (pos < upperHtml.Length)
+        {
+            var start = upperHtml.IndexOf(needle, pos, StringComparison.Ordinal);
+            if (start == -1) break;
+
+            var afterTag = start + needle.Length;
+            if (afterTag < upperHtml.Length && upperHtml[afterTag] != ' ' && upperHtml[afterTag] != '\t'
+                && upperHtml[afterTag] != '\n' && upperHtml[afterTag] != '\r' && upperHtml[afterTag] != '>'
+                && upperHtml[afterTag] != '/')
+            {
+                pos = afterTag;
+                continue;
+            }
+
+            var end = html.IndexOf('>', start);
+            if (end == -1) break;
+
+            var tagStr = html.Substring(start, end - start + 1);
+            var attrMatch = Regex.Match(tagStr, $@"{attrName}=[""']([^""']+)[""']", RegexOptions.IgnoreCase);
+            if (attrMatch.Success)
+            {
+                var url = attrMatch.Groups[1].Value;
+                var origin = ExtractOrigin(url);
+                if (origin != null && !IsOriginAllowed(origin, allowedDomains))
+                {
+                    warnings.Add(new SecurityPolicyWarning
+                    {
+                        Url = url,
+                        Source = source,
+                        PolicyField = policyField,
+                        Message = $"{source} references \"{url}\" but origin \"{origin}\" is not in {policyField}.",
+                    });
+                }
+            }
+
+            pos = end + 1;
+        }
+    }
+
+    private static void CheckCssPatterns(string html, IList<string>? allowedDomains, List<SecurityPolicyWarning> warnings)
+    {
+        var cssUrlRegex = new Regex(@"url\(\s*[""']([^""')]+)[""']\s*\)", RegexOptions.IgnoreCase);
+        foreach (Match match in cssUrlRegex.Matches(html))
+        {
+            var url = match.Groups[1].Value;
+            var origin = ExtractOrigin(url);
+            if (origin != null && !IsOriginAllowed(origin, allowedDomains))
+            {
+                warnings.Add(new SecurityPolicyWarning
+                {
+                    Url = url,
+                    Source = "CSS url()",
+                    PolicyField = "resourceDomains",
+                    Message = $"CSS url() references \"{url}\" but origin \"{origin}\" is not in resourceDomains.",
+                });
+            }
+        }
+
+        var importRegex = new Regex(@"@import\s+[""']([^""']+)[""']", RegexOptions.IgnoreCase);
+        foreach (Match match in importRegex.Matches(html))
+        {
+            var url = match.Groups[1].Value;
+            var origin = ExtractOrigin(url);
+            if (origin != null && !IsOriginAllowed(origin, allowedDomains))
+            {
+                warnings.Add(new SecurityPolicyWarning
+                {
+                    Url = url,
+                    Source = "CSS @import",
+                    PolicyField = "resourceDomains",
+                    Message = $"CSS @import references \"{url}\" but origin \"{origin}\" is not in resourceDomains.",
+                });
+            }
+        }
+    }
+
+    private static void CheckConnectPatterns(string html, IList<string>? allowedDomains, List<SecurityPolicyWarning> warnings)
+    {
+        var patterns = new (Regex Regex, string Source)[]
+        {
+            (new Regex(@"fetch\(\s*[""']([^""']+)[""']", RegexOptions.IgnoreCase), "fetch()"),
+            (new Regex(@"\.open\(\s*[""'][A-Za-z]+[""']\s*,\s*[""']([^""']+)[""']", RegexOptions.IgnoreCase), "XMLHttpRequest.open()"),
+            (new Regex(@"new\s+WebSocket\(\s*[""']([^""']+)[""']", RegexOptions.IgnoreCase), "new WebSocket()"),
+            (new Regex(@"new\s+EventSource\(\s*[""']([^""']+)[""']", RegexOptions.IgnoreCase), "new EventSource()"),
+        };
+
+        foreach (var (regex, source) in patterns)
+        {
+            foreach (Match match in regex.Matches(html))
+            {
+                var url = match.Groups[1].Value;
+                var origin = ExtractOrigin(url);
+                if (origin != null && !IsOriginAllowed(origin, allowedDomains))
+                {
+                    warnings.Add(new SecurityPolicyWarning
+                    {
+                        Url = url,
+                        Source = source,
+                        PolicyField = "connectDomains",
+                        Message = $"{source} references \"{url}\" but origin \"{origin}\" is not in connectDomains.",
+                    });
+                }
+            }
+        }
+    }
+}
diff --git a/core/src/Microsoft.Teams.Apps/HtmlWidget/HtmlWidgetPayload.cs b/core/src/Microsoft.Teams.Apps/HtmlWidget/HtmlWidgetPayload.cs
new file mode 100644
index 00000000..a2bec804
--- /dev/null
+++ b/core/src/Microsoft.Teams.Apps/HtmlWidget/HtmlWidgetPayload.cs
@@ -0,0 +1,146 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+
+namespace Microsoft.Teams.Apps.HtmlWidget;
+
+/// <summary>
+/// The security policy for an HTML widget, controlling allowed origins
+/// for network requests, static resources, nested iframes, and base URIs.
+/// </summary>
+[Experimental("ExperimentalTeamsHtmlWidget")]
+public class HtmlWidgetSecurityPolicy
+{
+    /// <summary>
+    /// Allowed origins for network requests.
+    /// </summary>
+    [JsonPropertyName("connectDomains")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public IList<string>? ConnectDomains { get; set; }
+
+    /// <summary>
+    /// Allowed origins for static resources.
+    /// </summary>
+    [JsonPropertyName("resourceDomains")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public IList<string>? ResourceDomains { get; set; }
+
+    /// <summary>
+    /// Allowed origins for nested iframes.
+    /// </summary>
+    [JsonPropertyName("frameDomains")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public IList<string>? FrameDomains { get; set; }
+
+    /// <summary>
+    /// Allowed base URIs for the document.
+    /// </summary>
+    [JsonPropertyName("baseUriDomains")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public IList<string>? BaseUriDomains { get; set; }
+}
+
+/// <summary>
+/// Permissions that the widget may request from the host.
+/// </summary>
+[Experimental("ExperimentalTeamsHtmlWidget")]
+public class HtmlWidgetPermissions
+{
+    /// <summary>
+    /// Request camera access.
+    /// </summary>
+    [JsonPropertyName("camera")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public object? Camera { get; set; }
+
+    /// <summary>
+    /// Request microphone access.
+    /// </summary>
+    [JsonPropertyName("microphone")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public object? Microphone { get; set; }
+
+    /// <summary>
+    /// Request geolocation access.
+    /// </summary>
+    [JsonPropertyName("geolocation")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public object? Geolocation { get; set; }
+
+    /// <summary>
+    /// Request clipboard write access.
+    /// </summary>
+    [JsonPropertyName("clipboardWrite")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public object? ClipboardWrite { get; set; }
+}
+
+/// <summary>
+/// The JSON payload for an HTML widget, sent inside a ```html-widget code block
+/// within a Markdown message.
+/// </summary>
+[Experimental("ExperimentalTeamsHtmlWidget")]
+public class HtmlWidgetPayload
+{
+    /// <summary>
+    /// The widget type identifier. Currently only "widget/mcp-ui" is supported.
+    /// </summary>
+    [JsonPropertyName("type")]
+    public string Type { get; set; } = "widget/mcp-ui";
+
+    /// <summary>
+    /// The display name of the MCP app.
+    /// </summary>
+    [JsonPropertyName("name")]
+    public string Name { get; set; } = string.Empty;
+
+    /// <summary>
+    /// A description of the MCP app.
+    /// </summary>
+    [JsonPropertyName("description")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? Description { get; set; }
+
+    /// <summary>
+    /// The HTML content that makes up the widget.
+    /// </summary>
+    [JsonPropertyName("html")]
+    public string Html { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The domain associated with the widget, applied to sandbox metadata.
+    /// Must be a valid domain URL (e.g. 'https://example.com').
+    /// </summary>
+    [JsonPropertyName("domain")]
+    public string Domain { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Optional security policy controlling allowed origins.
+    /// </summary>
+    [JsonPropertyName("securityPolicy")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public HtmlWidgetSecurityPolicy? SecurityPolicy { get; set; }
+
+    /// <summary>
+    /// Optional data that was passed as input to the tool that produced this widget.
+    /// </summary>
+    [JsonPropertyName("toolInput")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public object? ToolInput { get; set; }
+
+    /// <summary>
+    /// Optional data that the tool produced alongside this widget.
+    /// </summary>
+    [JsonPropertyName("toolOutput")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public object? ToolOutput { get; set; }
+
+    /// <summary>
+    /// Optional permissions the widget requests from the host.
+    /// </summary>
+    [JsonPropertyName("permissions")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public HtmlWidgetPermissions? Permissions { get; set; }
+}

From 67b54784e4fba8e14ef934ec6c0350e563ad5362 Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Wed, 1 Jul 2026 12:39:26 -0700
Subject: [PATCH 2/6] HTMLWidgetBot Sample

---
 core/core.slnx                                |   1 +
 .../HtmlWidgetBot/HtmlWidgetBot.csproj        |  14 +
 core/samples/HtmlWidgetBot/Program.cs         | 370 ++++++++++++++++++
 core/samples/HtmlWidgetBot/Widgets.cs         | 153 ++++++++
 core/samples/HtmlWidgetBot/appsettings.json   |   9 +
 5 files changed, 547 insertions(+)
 create mode 100644 core/samples/HtmlWidgetBot/HtmlWidgetBot.csproj
 create mode 100644 core/samples/HtmlWidgetBot/Program.cs
 create mode 100644 core/samples/HtmlWidgetBot/Widgets.cs
 create mode 100644 core/samples/HtmlWidgetBot/appsettings.json

diff --git a/core/core.slnx b/core/core.slnx
index 5bd7088e..1adeb2fb 100644
--- a/core/core.slnx
+++ b/core/core.slnx
@@ -19,6 +19,7 @@
     <Project Path="samples/CoreBot/CoreBot.csproj" Id="142a67bc-68e7-4020-83cf-51423e317b53" />
     <Project Path="samples/CustomHosting/CustomHosting.csproj" Id="de2e42de-3d8f-4a9d-920f-14c7e39fc3c0" />
     <Project Path="samples/ExtAIBot/ExtAIBot.csproj" />
+    <Project Path="samples/HtmlWidgetBot/HtmlWidgetBot.csproj" />
     <Project Path="samples/McpServer/McpServer.csproj" />
     <Project Path="samples/MeetingsBot/MeetingsBot.csproj" />
     <Project Path="samples/MessageExtensionBot/MessageExtensionBot.csproj" />
diff --git a/core/samples/HtmlWidgetBot/HtmlWidgetBot.csproj b/core/samples/HtmlWidgetBot/HtmlWidgetBot.csproj
new file mode 100644
index 00000000..a718b9f3
--- /dev/null
+++ b/core/samples/HtmlWidgetBot/HtmlWidgetBot.csproj
@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+	<PropertyGroup>
+		<TargetFramework>net10.0</TargetFramework>
+		<Nullable>enable</Nullable>
+		<ImplicitUsings>enable</ImplicitUsings>
+		<NoWarn>$(NoWarn);ExperimentalTeamsHtmlWidget</NoWarn>
+	</PropertyGroup>
+
+	<ItemGroup>
+		<ProjectReference Include="..\..\src\Microsoft.Teams.Apps\Microsoft.Teams.Apps.csproj" />
+	</ItemGroup>
+
+</Project>
diff --git a/core/samples/HtmlWidgetBot/Program.cs b/core/samples/HtmlWidgetBot/Program.cs
new file mode 100644
index 00000000..773f5cc2
--- /dev/null
+++ b/core/samples/HtmlWidgetBot/Program.cs
@@ -0,0 +1,370 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Text.Json;
+
+using Microsoft.Teams.Apps;
+using Microsoft.Teams.Apps.Handlers;
+using Microsoft.Teams.Apps.HtmlWidget;
+using Microsoft.Teams.Apps.Schema;
+
+using HtmlWidgetBot;
+
+WebApplicationBuilder webAppBuilder = WebApplication.CreateSlimBuilder(args);
+webAppBuilder.Services.AddTeamsBotApplication();
+WebApplication webApp = webAppBuilder.Build();
+
+TeamsBotApplication teamsApp = webApp.UseTeamsBotApplication();
+
+// ==================== MESSAGE COMMANDS ====================
+
+teamsApp.OnMessage(async (context, cancellationToken) =>
+{
+    var text = context.Activity.Text?.Trim().ToLowerInvariant() ?? "";
+
+    switch (text)
+    {
+        case "/simple":
+        {
+            var message = HtmlWidgetHelpers.BuildHtmlWidgetMessage(
+                new HtmlWidgetPayload
+                {
+                    Name = "Simple Widget",
+                    Description = "A static HTML widget with no callbacks.",
+                    Html = Widgets.SimpleHtml,
+                    Domain = "https://teams.microsoft.com",
+                    SecurityPolicy = new HtmlWidgetSecurityPolicy
+                    {
+                        ConnectDomains = [],
+                        ResourceDomains = ["'self'", "data:"],
+                        FrameDomains = [],
+                        BaseUriDomains = [],
+                    },
+                },
+                new HtmlWidgetMarkdownOptions
+                {
+                    Before = "Here is a simple static widget:",
+                    After = "No callbacks needed for static content.",
+                });
+            await context.SendActivityAsync(message, cancellationToken);
+            break;
+        }
+
+        case "/calltool":
+        {
+            var message = HtmlWidgetHelpers.BuildHtmlWidgetMessage(
+                new HtmlWidgetPayload
+                {
+                    Name = "CallTool Widget",
+                    Description = "Widget that calls tools on the bot.",
+                    Html = Widgets.CallToolHtml,
+                    Domain = "https://teams.microsoft.com",
+                    SecurityPolicy = new HtmlWidgetSecurityPolicy
+                    {
+                        ConnectDomains = ["https://teams.microsoft.com", "https://teams.cloud.microsoft.com"],
+                        ResourceDomains = ["'self'", "data:"],
+                        FrameDomains = [],
+                        BaseUriDomains = [],
+                    },
+                    ToolInput = new { demo = true },
+                    ToolOutput = new
+                    {
+                        content = new[] { new { type = "text", text = "Initial data loaded." } },
+                        structuredContent = new { counter = 0, lastAction = "init" },
+                        isError = false,
+                    },
+                },
+                new HtmlWidgetMarkdownOptions
+                {
+                    Before = "Here is a widget with callTool support (click Refresh):",
+                });
+            await context.SendActivityAsync(message, cancellationToken);
+            break;
+        }
+
+        case "/messageback":
+        {
+            var message = HtmlWidgetHelpers.BuildHtmlWidgetMessage(
+                new HtmlWidgetPayload
+                {
+                    Name = "MessageBack Widget",
+                    Description = "Widget that sends messageBack to the bot.",
+                    Html = Widgets.MessageBackHtml,
+                    Domain = "https://teams.microsoft.com",
+                    SecurityPolicy = new HtmlWidgetSecurityPolicy
+                    {
+                        ConnectDomains = [],
+                        ResourceDomains = ["'self'", "data:"],
+                        FrameDomains = [],
+                        BaseUriDomains = [],
+                    },
+                },
+                new HtmlWidgetMarkdownOptions
+                {
+                    Before = "This widget tests the onMessage (messageBack) callback:",
+                });
+            await context.SendActivityAsync(message, cancellationToken);
+            break;
+        }
+
+        case "/fullscreen":
+        {
+            var message = HtmlWidgetHelpers.BuildHtmlWidgetMessage(
+                new HtmlWidgetPayload
+                {
+                    Name = "Fullscreen Widget",
+                    Description = "Widget that requests fullscreen mode.",
+                    Html = Widgets.FullscreenHtml,
+                    Domain = "https://teams.microsoft.com",
+                    SecurityPolicy = new HtmlWidgetSecurityPolicy
+                    {
+                        ConnectDomains = [],
+                        ResourceDomains = ["'self'", "data:"],
+                        FrameDomains = [],
+                        BaseUriDomains = [],
+                    },
+                },
+                new HtmlWidgetMarkdownOptions
+                {
+                    Before = "This widget will request fullscreen mode:",
+                });
+            await context.SendActivityAsync(message, cancellationToken);
+            break;
+        }
+
+        case "/multi":
+        {
+            var message = HtmlWidgetHelpers.BuildHtmlWidgetMessage(
+                new HtmlWidgetPayload
+                {
+                    Name = "Multi-Tool Widget",
+                    Description = "Widget that calls multiple different tools.",
+                    Html = Widgets.MultiToolHtml,
+                    Domain = "https://teams.microsoft.com",
+                    SecurityPolicy = new HtmlWidgetSecurityPolicy
+                    {
+                        ConnectDomains = ["https://teams.microsoft.com"],
+                        ResourceDomains = ["'self'", "data:"],
+                        FrameDomains = [],
+                        BaseUriDomains = [],
+                    },
+                    ToolInput = new { },
+                    ToolOutput = new
+                    {
+                        content = new[] { new { type = "text", text = "Ready." } },
+                        structuredContent = new { tools = new[] { "getTime", "roll", "echo" } },
+                        isError = false,
+                    },
+                },
+                new HtmlWidgetMarkdownOptions
+                {
+                    Before = "This widget has multiple tools to test dispatch:",
+                });
+            await context.SendActivityAsync(message, cancellationToken);
+            break;
+        }
+
+        case "/openlink":
+        {
+            var message = HtmlWidgetHelpers.BuildHtmlWidgetMessage(
+                new HtmlWidgetPayload
+                {
+                    Name = "open-link-test",
+                    Html = Widgets.OpenLinkHtml,
+                    Domain = "https://teams.microsoft.com",
+                },
+                new HtmlWidgetMarkdownOptions
+                {
+                    Before = "Widget with ui/open-link support (click a button to open a URL):",
+                });
+            await context.SendActivityAsync(message, cancellationToken);
+            break;
+        }
+
+        case "/context":
+        {
+            var message = HtmlWidgetHelpers.BuildHtmlWidgetMessage(
+                new HtmlWidgetPayload
+                {
+                    Name = "update-context-test",
+                    Html = Widgets.UpdateContextHtml,
+                    Domain = "https://teams.microsoft.com",
+                },
+                new HtmlWidgetMarkdownOptions
+                {
+                    Before = "Widget with ui/update-model-context support:",
+                });
+            await context.SendActivityAsync(message, cancellationToken);
+            break;
+        }
+
+        case "/hostcontext":
+        {
+            var message = HtmlWidgetHelpers.BuildHtmlWidgetMessage(
+                new HtmlWidgetPayload
+                {
+                    Name = "host-context-inspector",
+                    Html = Widgets.HostContextHtml,
+                    Domain = "https://teams.microsoft.com",
+                },
+                new HtmlWidgetMarkdownOptions
+                {
+                    Before = "Widget that inspects hostContext from ui/initialize:",
+                });
+            await context.SendActivityAsync(message, cancellationToken);
+            break;
+        }
+
+        case "/validate":
+        {
+            var 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>
+                """;
+
+            var strictPolicy = new HtmlWidgetSecurityPolicy
+            {
+                ConnectDomains = [],
+                ResourceDomains = ["'self'", "data:"],
+                FrameDomains = [],
+                BaseUriDomains = [],
+            };
+            var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(htmlWithExternalRefs, strictPolicy);
+
+            var correctedPolicy = new HtmlWidgetSecurityPolicy
+            {
+                ConnectDomains = [],
+                ResourceDomains = ["'self'", "data:", "https://fonts.googleapis.com"],
+                FrameDomains = [],
+                BaseUriDomains = [],
+            };
+            var warningText = string.Join("\n", warnings.Select(w => $"- **{w.Source}**: `{w.Url}` not in `{w.PolicyField}`"));
+            var markdown = HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(
+                new HtmlWidgetPayload
+                {
+                    Name = "Validated Widget",
+                    Description = "Widget built after security policy validation.",
+                    Html = htmlWithExternalRefs,
+                    Domain = "https://teams.microsoft.com",
+                    SecurityPolicy = correctedPolicy,
+                },
+                new HtmlWidgetMarkdownOptions
+                {
+                    Before = $"**Validation found {warnings.Count} warning(s):**\n\n{warningText}\n\nPolicy was corrected before sending:",
+                });
+            await context.SendActivityAsync(
+                new MessageActivity(markdown) { TextFormat = TextFormats.ExtendedMarkdown },
+                cancellationToken);
+            break;
+        }
+
+        case "/help":
+        {
+            await context.SendActivityAsync(
+                new MessageActivity(
+                    "**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")
+                { TextFormat = TextFormats.Markdown },
+                cancellationToken);
+            break;
+        }
+
+        default:
+        {
+            await context.SendActivityAsync(
+                "Send `/help` for available widget test commands.",
+                cancellationToken);
+
+            break;
+        }
+    }
+});
+
+// ==================== WIDGET CALL TOOL HANDLER ====================
+
+teamsApp.OnWidgetCallTool(async (context, cancellationToken) =>
+{
+    var request = context.Activity.Value;
+    var toolName = request?.Name ?? "unknown";
+    var args = request?.Arguments;
+
+    Console.WriteLine($"[widget.callTool] tool={toolName} args={JsonSerializer.Serialize(args)}");
+
+    var response = toolName switch
+    {
+        "refresh" => new HtmlWidgetCallToolResponse
+        {
+            CallToolResult = new McpUiCallToolResult
+            {
+                Content = [new McpUiCallToolResultContent { Text = "Refreshed!" }],
+                StructuredContent = new
+                {
+                    counter = GetCounter(args) + 1,
+                    lastAction = "refresh",
+                    timestamp = DateTime.UtcNow.ToString("o"),
+                },
+            }
+        },
+        "getTime" => new HtmlWidgetCallToolResponse
+        {
+            CallToolResult = new McpUiCallToolResult
+            {
+                Content = [new McpUiCallToolResultContent { Text = DateTime.UtcNow.ToString("HH:mm:ss") }],
+                StructuredContent = new { time = DateTime.UtcNow.ToString("o") },
+            }
+        },
+        "roll" => CreateRollResponse(args),
+        "echo" => new HtmlWidgetCallToolResponse
+        {
+            CallToolResult = new McpUiCallToolResult
+            {
+                Content = [new McpUiCallToolResultContent { Text = JsonSerializer.Serialize(args) }],
+                StructuredContent = args,
+            }
+        },
+        _ => HtmlWidgetCallToolResponse.FromError($"Unknown tool: {toolName}"),
+    };
+
+    Console.WriteLine($"[widget.callTool] result={JsonSerializer.Serialize(response)}");
+
+    await Task.CompletedTask;
+    return InvokeResponse.Ok(response);
+});
+
+webApp.Run();
+
+static int GetCounter(object? args)
+{
+    if (args is JsonElement je && je.TryGetProperty("counter", out var c) && c.TryGetInt32(out var val))
+        return val;
+    return 0;
+}
+
+static HtmlWidgetCallToolResponse CreateRollResponse(object? args)
+{
+    int sides = 6;
+    if (args is JsonElement je && je.TryGetProperty("sides", out var s) && s.TryGetInt32(out var val))
+        sides = val;
+
+    int result = Random.Shared.Next(1, sides + 1);
+    return new HtmlWidgetCallToolResponse
+    {
+        CallToolResult = new McpUiCallToolResult
+        {
+            Content = [new McpUiCallToolResultContent { Text = $"Rolled a {result} (d{sides})" }],
+            StructuredContent = new { result, sides },
+        }
+    };
+}
diff --git a/core/samples/HtmlWidgetBot/Widgets.cs b/core/samples/HtmlWidgetBot/Widgets.cs
new file mode 100644
index 00000000..16e43a8b
--- /dev/null
+++ b/core/samples/HtmlWidgetBot/Widgets.cs
@@ -0,0 +1,153 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace HtmlWidgetBot;
+
+/// <summary>
+/// HTML widget strings matching the TS/PY examples exactly.
+/// These are browser-side JavaScript -- language-agnostic across all SDKs.
+/// </summary>
+public static class Widgets
+{
+    public const string SimpleHtml = """
+        <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; padding: 16px; border-radius: 8px; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white;">
+          <h2 style="margin: 0 0 8px 0;">Hello from HTML Widget!</h2>
+          <p style="margin: 0; opacity: 0.9;">This is a static widget with no callbacks. It demonstrates basic HTML rendering in Teams.</p>
+          <div style="margin-top: 12px; padding: 8px; background: rgba(255,255,255,0.2); border-radius: 4px; font-family: monospace; font-size: 12px;">
+            Rendered at: <span id="time"></span>
+          </div>
+          <script>document.getElementById('time').textContent=new Date().toLocaleTimeString();</script>
+        </div>
+        """;
+
+    public const string CallToolHtml = """
+        <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; padding: 16px;">
+          <h3 style="margin: 0 0 12px 0;">CallTool Widget</h3>
+          <div id="status" style="padding: 8px; background: #f0f0f0; border-radius: 4px; margin-bottom: 12px;">Ready</div>
+          <button onclick="callRefresh()" style="padding: 8px 16px; background: #6264a7; color: white; border: none; border-radius: 4px; cursor: pointer;">Refresh</button>
+          <pre id="result" style="margin-top: 12px; padding: 8px; background: #1e1e1e; color: #d4d4d4; border-radius: 4px; font-size: 11px; overflow: auto; max-height: 200px;"></pre>
+          <script>
+            var counter=0;
+            function callRefresh(){
+              counter++;
+              document.getElementById('status').textContent='Calling tool...';
+              var id='refresh-'+Date.now();
+              window.parent.postMessage({jsonrpc:'2.0',method:'tools/call',id:id,params:{name:'refresh',arguments:{counter:counter}}},'*');
+              window.addEventListener('message',function handler(ev){
+                var d=ev.data;if(!d||d.id!==id)return;
+                window.removeEventListener('message',handler);
+                document.getElementById('status').textContent='Done (counter='+counter+')';
+                document.getElementById('result').textContent=JSON.stringify(d.result||d.error,null,2);
+              });
+            }
+          </script>
+        </div>
+        """;
+
+    public const string MessageBackHtml = """
+        <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; padding: 16px;">
+          <h3 style="margin: 0 0 12px 0;">MessageBack Widget</h3>
+          <p style="margin: 0 0 12px 0; color: #666;">Click a button to send a messageBack to the bot:</p>
+          <button onclick="send('hello')" style="padding: 8px 16px; margin-right: 8px; background: #6264a7; color: white; border: none; border-radius: 4px; cursor: pointer;">Say Hello</button>
+          <button onclick="send('world')" style="padding: 8px 16px; background: #6264a7; color: white; border: none; border-radius: 4px; cursor: pointer;">Say World</button>
+          <script>
+            function send(text){
+              window.parent.postMessage({jsonrpc:'2.0',method:'ui/message',params:{type:'messageBack',text:text,value:{source:'widget',action:text}}},'*');
+            }
+          </script>
+        </div>
+        """;
+
+    public const string FullscreenHtml = """
+        <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; padding: 16px;">
+          <h3 style="margin: 0 0 12px 0;">Fullscreen Widget</h3>
+          <p id="mode" style="margin: 0 0 12px 0;">Current mode: inline</p>
+          <button onclick="requestFullscreen()" style="padding: 8px 16px; background: #6264a7; color: white; border: none; border-radius: 4px; cursor: pointer;">Go Fullscreen</button>
+          <button onclick="requestInline()" style="padding: 8px 16px; margin-left: 8px; background: #666; color: white; border: none; border-radius: 4px; cursor: pointer;">Go Inline</button>
+          <script>
+            function requestFullscreen(){
+              window.parent.postMessage({jsonrpc:'2.0',method:'ui/request-display-mode',id:'fs-'+Date.now(),params:{displayMode:'fullscreen'}},'*');
+              document.getElementById('mode').textContent='Current mode: fullscreen (requested)';
+            }
+            function requestInline(){
+              window.parent.postMessage({jsonrpc:'2.0',method:'ui/request-display-mode',id:'in-'+Date.now(),params:{displayMode:'inline'}},'*');
+              document.getElementById('mode').textContent='Current mode: inline (requested)';
+            }
+          </script>
+        </div>
+        """;
+
+    public const string MultiToolHtml = """
+        <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; padding: 16px;">
+          <h3 style="margin: 0 0 12px 0;">Multi-Tool Widget</h3>
+          <div style="display: flex; gap: 8px; margin-bottom: 12px;">
+            <button onclick="call('getTime',{})" style="padding: 8px 12px; background: #6264a7; color: white; border: none; border-radius: 4px; cursor: pointer;">Get Time</button>
+            <button onclick="call('roll',{sides:20})" style="padding: 8px 12px; background: #6264a7; color: white; border: none; border-radius: 4px; cursor: pointer;">Roll d20</button>
+            <button onclick="call('echo',{msg:'hello'})" style="padding: 8px 12px; background: #6264a7; color: white; border: none; border-radius: 4px; cursor: pointer;">Echo</button>
+          </div>
+          <pre id="log" style="padding: 8px; background: #1e1e1e; color: #d4d4d4; border-radius: 4px; font-size: 11px; max-height: 200px; overflow: auto;"></pre>
+          <script>
+            function call(name,args){
+              var id=name+'-'+Date.now();
+              window.parent.postMessage({jsonrpc:'2.0',method:'tools/call',id:id,params:{name:name,arguments:args}},'*');
+              window.addEventListener('message',function handler(ev){
+                var d=ev.data;if(!d||d.id!==id)return;
+                window.removeEventListener('message',handler);
+                var log=document.getElementById('log');
+                log.textContent+=name+': '+JSON.stringify(d.result||d.error)+'\n';
+              });
+            }
+          </script>
+        </div>
+        """;
+
+    public const string OpenLinkHtml = """
+        <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; padding: 16px;">
+          <h3 style="margin: 0 0 12px 0;">Open Link Widget</h3>
+          <button onclick="openUrl('https://learn.microsoft.com/microsoftteams/')" style="padding: 8px 16px; margin-right: 8px; background: #6264a7; color: white; border: none; border-radius: 4px; cursor: pointer;">Teams Docs</button>
+          <button onclick="openUrl('https://github.com/microsoft/teams.ts')" style="padding: 8px 16px; background: #6264a7; color: white; border: none; border-radius: 4px; cursor: pointer;">Teams SDK</button>
+          <script>
+            function openUrl(url){
+              window.parent.postMessage({jsonrpc:'2.0',method:'ui/open-link',id:'ol-'+Date.now(),params:{url:url}},'*');
+            }
+          </script>
+        </div>
+        """;
+
+    public const string UpdateContextHtml = """
+        <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; padding: 16px;">
+          <h3 style="margin: 0 0 12px 0;">Update Context Widget</h3>
+          <textarea id="ctx" rows="3" style="width: 100%; box-sizing: border-box; padding: 8px; border: 1px solid #ddd; border-radius: 4px;" placeholder="Type context to send to the model..."></textarea>
+          <button onclick="updateCtx()" style="margin-top: 8px; padding: 8px 16px; background: #6264a7; color: white; border: none; border-radius: 4px; cursor: pointer;">Send Context</button>
+          <div id="status" style="margin-top: 8px; color: #666; font-size: 12px;"></div>
+          <script>
+            function updateCtx(){
+              var text=document.getElementById('ctx').value;
+              var id='ctx-'+Date.now();
+              window.parent.postMessage({jsonrpc:'2.0',method:'ui/update-model-context',id:id,params:{modelContext:{content:text}}},'*');
+              window.addEventListener('message',function handler(ev){
+                var d=ev.data;if(!d||d.id!==id)return;
+                window.removeEventListener('message',handler);
+                document.getElementById('status').textContent=d.error?'Error: '+JSON.stringify(d.error):'Context updated!';
+              });
+            }
+          </script>
+        </div>
+        """;
+
+    public const string HostContextHtml = """
+        <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; padding: 16px;">
+          <h3 style="margin: 0 0 12px 0;">Host Context Inspector</h3>
+          <pre id="ctx" style="padding: 8px; background: #1e1e1e; color: #d4d4d4; border-radius: 4px; font-size: 11px; overflow: auto; max-height: 300px;">Waiting for ui/initialize...</pre>
+          <script>
+            window.addEventListener('message',function(ev){
+              var d=ev.data;
+              if(d&&d.method==='ui/initialize'){
+                document.getElementById('ctx').textContent=JSON.stringify(d.params,null,2);
+                window.parent.postMessage({jsonrpc:'2.0',method:'ui/notifications/initialized',params:{}},'*');
+              }
+            });
+          </script>
+        </div>
+        """;
+}
diff --git a/core/samples/HtmlWidgetBot/appsettings.json b/core/samples/HtmlWidgetBot/appsettings.json
new file mode 100644
index 00000000..5febf4fe
--- /dev/null
+++ b/core/samples/HtmlWidgetBot/appsettings.json
@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Warning",
+      "Microsoft.Teams": "Information"
+    }
+  },
+  "AllowedHosts": "*"
+}

From 7e7aa107705c385c4d1ee453c5b693beebef79aa Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Wed, 1 Jul 2026 12:39:48 -0700
Subject: [PATCH 3/6] Unit tests

---
 .../HtmlWidgetHelpersTests.cs                 | 738 ++++++++++++++++++
 .../Microsoft.Teams.Apps.UnitTests.csproj     |   2 +-
 2 files changed, 739 insertions(+), 1 deletion(-)
 create mode 100644 core/test/Microsoft.Teams.Apps.UnitTests/HtmlWidgetHelpersTests.cs

diff --git a/core/test/Microsoft.Teams.Apps.UnitTests/HtmlWidgetHelpersTests.cs b/core/test/Microsoft.Teams.Apps.UnitTests/HtmlWidgetHelpersTests.cs
new file mode 100644
index 00000000..5e174bb3
--- /dev/null
+++ b/core/test/Microsoft.Teams.Apps.UnitTests/HtmlWidgetHelpersTests.cs
@@ -0,0 +1,738 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Text.Json;
+
+using Microsoft.Teams.Apps.Handlers;
+using Microsoft.Teams.Apps.HtmlWidget;
+using Microsoft.Teams.Apps.Schema;
+
+namespace Microsoft.Teams.Apps.UnitTests;
+
+#pragma warning disable ExperimentalTeamsHtmlWidget
+
+public class HtmlWidgetHelpersTests
+{
+    // --- InjectWidgetProtocol ---
+
+    [Fact]
+    public void InjectWidgetProtocol_SkipsIfAlreadyPresent()
+    {
+        var html = "<body><script>ui/initialize</script></body>";
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol(html);
+        Assert.Equal(html, result);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_InjectsBeforeBodyClose()
+    {
+        var html = "<body><p>Hello</p></body>";
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol(html);
+        Assert.Contains("ui/initialize", result);
+        Assert.Contains("ui/notifications/size-changed", result);
+        Assert.EndsWith("</body>", result);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_AppendsIfNoBody()
+    {
+        var html = "<div>Hello</div>";
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol(html);
+        Assert.Contains("ui/initialize", result);
+        Assert.StartsWith("<div>Hello</div>", result);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_UsesCustomNameAndVersion()
+    {
+        var html = "<body></body>";
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol(html, new InjectWidgetProtocolOptions
+        {
+            Name = "myWidget",
+            Version = "2.0.0"
+        });
+        Assert.Contains("name:'myWidget'", result);
+        Assert.Contains("version:'2.0.0'", result);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_InjectsNotificationHooks()
+    {
+        var html = "<body></body>";
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol(html, new InjectWidgetProtocolOptions
+        {
+            Notifications = ["tool-result", "tool-input"]
+        });
+        Assert.Contains("ui/notifications/tool-result", result);
+        Assert.Contains("window.onToolResult", result);
+        Assert.Contains("ui/notifications/tool-input", result);
+        Assert.Contains("window.onToolInput", result);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_IgnoresUnknownNotifications()
+    {
+        var html = "<body></body>";
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol(html, new InjectWidgetProtocolOptions
+        {
+            Notifications = ["unknown-notification"]
+        });
+        Assert.DoesNotContain("unknown-notification", result);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_InjectsCspDebugListener()
+    {
+        var html = "<body></body>";
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol(html, new InjectWidgetProtocolOptions
+        {
+            DebugCspViolations = true
+        });
+        Assert.Contains("securitypolicyviolation", result);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_IncludesDisplayModes()
+    {
+        var html = "<body></body>";
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol(html, new InjectWidgetProtocolOptions
+        {
+            AvailableDisplayModes = ["inline", "fullscreen"]
+        });
+        Assert.Contains("availableDisplayModes", result);
+        Assert.Contains("inline", result);
+        Assert.Contains("fullscreen", result);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_EscapesSpecialChars()
+    {
+        var html = "<body></body>";
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol(html, new InjectWidgetProtocolOptions
+        {
+            Name = "it's a \"test\\"
+        });
+        Assert.Contains("it\\'s a \"test\\\\", result);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_EscapesScriptCloseTagInName()
+    {
+        var html = "<body></body>";
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol(html, new InjectWidgetProtocolOptions
+        {
+            Name = "</script><img src=x onerror=alert(1)>"
+        });
+        // Only one </script> should exist (the injected protocol's closing tag)
+        var scriptTagCount = System.Text.RegularExpressions.Regex.Matches(result, "</script>", System.Text.RegularExpressions.RegexOptions.IgnoreCase).Count;
+        Assert.Equal(1, scriptTagCount);
+        Assert.Contains("<\\/script>", result);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_EscapesScriptCloseTagInVersion()
+    {
+        var html = "<body></body>";
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol(html, new InjectWidgetProtocolOptions
+        {
+            Version = "</script><svg onload=fetch(\"/steal\")>"
+        });
+        var scriptTagCount = System.Text.RegularExpressions.Regex.Matches(result, "</script>", System.Text.RegularExpressions.RegexOptions.IgnoreCase).Count;
+        Assert.Equal(1, scriptTagCount);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_EscapesNewlinesInName()
+    {
+        var html = "<body></body>";
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol(html, new InjectWidgetProtocolOptions
+        {
+            Name = "line1\nline2\rline3"
+        });
+        var scriptMatch = System.Text.RegularExpressions.Regex.Match(result, @"<script>(.*?)</script>", System.Text.RegularExpressions.RegexOptions.Singleline);
+        Assert.True(scriptMatch.Success);
+        var scriptContent = scriptMatch.Groups[1].Value;
+        Assert.DoesNotContain("\n", scriptContent);
+        Assert.Contains("\\n", scriptContent);
+        Assert.Contains("\\r", scriptContent);
+    }
+
+    // --- BuildHtmlWidgetMarkdown ---
+
+    [Fact]
+    public void BuildHtmlWidgetMarkdown_WrapsInCodeFence()
+    {
+        var payload = new HtmlWidgetPayload
+        {
+            Name = "test",
+            Html = "<body><p>Hi</p></body>",
+            Domain = "https://example.com"
+        };
+        var result = HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(payload);
+        Assert.StartsWith("```html-widget\n", result);
+        Assert.EndsWith("\n```", result);
+    }
+
+    [Fact]
+    public void BuildHtmlWidgetMarkdown_InjectsProtocol()
+    {
+        var payload = new HtmlWidgetPayload
+        {
+            Name = "test",
+            Html = "<body><p>Hi</p></body>",
+            Domain = "https://example.com"
+        };
+        var result = HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(payload);
+        Assert.Contains("ui/initialize", result);
+    }
+
+    [Fact]
+    public void BuildHtmlWidgetMarkdown_AppliesDefaultSecurityPolicy()
+    {
+        var payload = new HtmlWidgetPayload
+        {
+            Name = "test",
+            Html = "<body><p>Hi</p></body>",
+            Domain = "https://example.com"
+        };
+        var result = HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(payload);
+        Assert.Contains("securityPolicy", result);
+        Assert.Contains("resourceDomains", result);
+    }
+
+    [Fact]
+    public void BuildHtmlWidgetMarkdown_IncludesBeforeAndAfter()
+    {
+        var payload = new HtmlWidgetPayload
+        {
+            Name = "test",
+            Html = "<body><p>Hi</p></body>",
+            Domain = "https://example.com"
+        };
+        var result = HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(payload, new HtmlWidgetMarkdownOptions
+        {
+            Before = "Hello before",
+            After = "Hello after"
+        });
+        Assert.StartsWith("Hello before\n", result);
+        Assert.EndsWith("\nHello after", result);
+    }
+
+    [Fact]
+    public void BuildHtmlWidgetMarkdown_ThrowsOnEmptyName()
+    {
+        var payload = new HtmlWidgetPayload
+        {
+            Name = "",
+            Html = "<body>Hi</body>",
+            Domain = "https://example.com"
+        };
+        var ex = Assert.Throws<ArgumentException>(() => HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(payload));
+        Assert.Contains("name", ex.Message);
+    }
+
+    [Fact]
+    public void BuildHtmlWidgetMarkdown_ThrowsOnEmptyHtml()
+    {
+        var payload = new HtmlWidgetPayload
+        {
+            Name = "test",
+            Html = "",
+            Domain = "https://example.com"
+        };
+        var ex = Assert.Throws<ArgumentException>(() => HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(payload));
+        Assert.Contains("html", ex.Message);
+    }
+
+    [Fact]
+    public void BuildHtmlWidgetMarkdown_ThrowsOnInvalidDomain()
+    {
+        var payload = new HtmlWidgetPayload
+        {
+            Name = "test",
+            Html = "<body>Hi</body>",
+            Domain = "http://example.com"
+        };
+        var ex = Assert.Throws<ArgumentException>(() => HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(payload));
+        Assert.Contains("domain", ex.Message);
+    }
+
+    // --- BuildHtmlWidgetMessage ---
+
+    [Fact]
+    public void BuildHtmlWidgetMessage_SetsExtendedMarkdownFormat()
+    {
+        var payload = new HtmlWidgetPayload
+        {
+            Name = "test",
+            Html = "<body><p>Hi</p></body>",
+            Domain = "https://example.com"
+        };
+        var message = HtmlWidgetHelpers.BuildHtmlWidgetMessage(payload);
+        Assert.Equal(TextFormats.ExtendedMarkdown, message.TextFormat);
+        Assert.Contains("```html-widget", message.Text);
+    }
+
+    // --- ValidateSecurityPolicy ---
+
+    [Fact]
+    public void ValidateSecurityPolicy_DetectsExternalScriptSrc()
+    {
+        var html = "<script src=\"https://cdn.example.com/lib.js\"></script>";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+        Assert.Equal("<script src>", warnings[0].Source);
+        Assert.Equal("resourceDomains", warnings[0].PolicyField);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_AllowsMatchingDomains()
+    {
+        var html = "<script src=\"https://cdn.example.com/lib.js\"></script>";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = ["https://cdn.example.com"] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Empty(warnings);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_DetectsFetch()
+    {
+        var html = "<script>fetch('https://api.example.com/data')</script>";
+        var policy = new HtmlWidgetSecurityPolicy { ConnectDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+        Assert.Equal("fetch()", warnings[0].Source);
+        Assert.Equal("connectDomains", warnings[0].PolicyField);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_DetectsIframeSrc()
+    {
+        var html = "<iframe src=\"https://embed.example.com/video\"></iframe>";
+        var policy = new HtmlWidgetSecurityPolicy { FrameDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+        Assert.Equal("<iframe src>", warnings[0].Source);
+        Assert.Equal("frameDomains", warnings[0].PolicyField);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_AllowsWildcard()
+    {
+        var html = "<script src=\"https://anything.com/lib.js\"></script>";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = ["*"] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Empty(warnings);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_IgnoresRelativeUrls()
+    {
+        var html = "<script src=\"./local.js\"></script><img src=\"/images/logo.png\">";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Empty(warnings);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_IgnoresDataUrls()
+    {
+        var html = "<img src=\"data:image/png;base64,abc\">";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Empty(warnings);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_DetectsCssUrl()
+    {
+        var html = "<style>body { background: url('https://cdn.example.com/bg.png'); }</style>";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+        Assert.Equal("CSS url()", warnings[0].Source);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_DetectsFormAction()
+    {
+        var html = "<form action=\"https://evil.com/steal\"></form>";
+        var policy = new HtmlWidgetSecurityPolicy { ConnectDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+        Assert.Equal("<form action>", warnings[0].Source);
+    }
+
+    // --- InvokeNames ---
+
+    [Fact]
+    public void InvokeNames_HasHtmlWidgetCallTool()
+    {
+        Assert.Equal("htmlwidget/calltool", InvokeNames.HtmlWidgetCallTool);
+    }
+
+    // --- TextFormats ---
+
+    [Fact]
+    public void TextFormats_HasExtendedMarkdown()
+    {
+        Assert.Equal("extendedmarkdown", TextFormats.ExtendedMarkdown);
+    }
+
+    // --- CallToolResponse helpers ---
+
+    [Fact]
+    public void HtmlWidgetCallToolResponse_FromText_CreatesCorrectShape()
+    {
+        var response = HtmlWidgetCallToolResponse.FromText("hello");
+        Assert.Equal("htmlwidget/calltoolresult", response.ResponseType);
+        Assert.NotNull(response.CallToolResult.Content);
+        Assert.Single(response.CallToolResult.Content);
+        Assert.Equal("text", response.CallToolResult.Content[0].Type);
+        Assert.Equal("hello", response.CallToolResult.Content[0].Text);
+        Assert.False(response.CallToolResult.IsError);
+    }
+
+    [Fact]
+    public void HtmlWidgetCallToolResponse_FromError_SetsIsError()
+    {
+        var response = HtmlWidgetCallToolResponse.FromError("something failed");
+        Assert.Equal("htmlwidget/calltoolresult", response.ResponseType);
+        Assert.True(response.CallToolResult.IsError);
+        Assert.Equal("something failed", response.CallToolResult.Content![0].Text);
+    }
+
+    [Fact]
+    public void HtmlWidgetCallToolResponse_SerializesCorrectly()
+    {
+        var response = HtmlWidgetCallToolResponse.FromText("test");
+        var json = JsonSerializer.Serialize(response);
+        Assert.Contains("\"responseType\":\"htmlwidget/calltoolresult\"", json);
+        Assert.Contains("\"callToolResult\"", json);
+    }
+
+    [Fact]
+    public void BuildHtmlWidgetMarkdown_DoesNotMutateProtocolOptions()
+    {
+        var protoOpts = new InjectWidgetProtocolOptions { Version = "2.0.0", Notifications = ["tool-result"] };
+        var options = new HtmlWidgetMarkdownOptions { ProtocolOptions = protoOpts };
+        var payload = new HtmlWidgetPayload
+        {
+            Name = "MutationTest",
+            Html = "<body>hi</body>",
+            Domain = "https://example.com",
+        };
+        HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(payload, options);
+        // The original protocolOptions.Name should remain "widget" (default), not mutated to "MutationTest"
+        Assert.Equal("widget", protoOpts.Name);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_EmbedsCorrectProtocolVersion()
+    {
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol("<body></body>");
+        Assert.Contains("protocolVersion:'2026-01-26'", result);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_AllowsSubdomainWhenParentInPolicy()
+    {
+        var html = "<script src=\"https://cdn.example.com/lib.js\"></script>";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = ["https://example.com"] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Empty(warnings);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_DoesNotAllowUnrelatedDomainSharingSuffix()
+    {
+        var html = "<script src=\"https://notexample.com/lib.js\"></script>";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = ["https://example.com"] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_PassesUnicodeThroughCorrectly()
+    {
+        var opts = new InjectWidgetProtocolOptions { Name = "Widget \u2764\uFE0F" };
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol("<body></body>", opts);
+        Assert.Contains("name:'Widget \u2764\uFE0F'", result);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_IsIdempotent()
+    {
+        var html = "<body><p>Hello</p></body>";
+        var first = HtmlWidgetHelpers.InjectWidgetProtocol(html);
+        var second = HtmlWidgetHelpers.InjectWidgetProtocol(first);
+        Assert.Equal(first, second);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_NotificationHooksOptIn()
+    {
+        var html = "<body></body>";
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol(html);
+        // Without notifications option, no notification handlers injected
+        Assert.DoesNotContain("tool-result", result);
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_InjectsAllKnownNotificationTypes()
+    {
+        var allNotifications = new List<string>
+        {
+            "tool-result", "tool-input", "tool-input-partial",
+            "tool-cancelled", "host-context-changed", "resource-teardown"
+        };
+        var opts = new InjectWidgetProtocolOptions { Notifications = allNotifications };
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol("<body></body>", opts);
+        foreach (var n in allNotifications)
+        {
+            Assert.Contains(n, result);
+        }
+    }
+
+    [Fact]
+    public void InjectWidgetProtocol_UsesPayloadNameOverOptionsName()
+    {
+        // BuildHtmlWidgetMarkdown should use the payload name for the protocol script
+        var payload = new HtmlWidgetPayload
+        {
+            Name = "PayloadName",
+            Html = "<body>hi</body>",
+            Domain = "https://example.com",
+        };
+        var options = new HtmlWidgetMarkdownOptions
+        {
+            ProtocolOptions = new InjectWidgetProtocolOptions { Name = "OptionsName" }
+        };
+        var result = HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(payload, options);
+        // Parse the JSON and check injected HTML uses payload name
+        var json = result.Replace("```html-widget\n", "").Replace("\n```", "");
+        using var doc = JsonDocument.Parse(json);
+        var html = doc.RootElement.GetProperty("html").GetString()!;
+        Assert.Contains("name:'PayloadName'", html);
+        Assert.DoesNotContain("OptionsName", html);
+    }
+
+    [Fact]
+    public void BuildHtmlWidgetMarkdown_DoesNotOverwriteUserSecurityPolicy()
+    {
+        var customPolicy = new HtmlWidgetSecurityPolicy
+        {
+            ConnectDomains = ["https://api.custom.com"],
+            ResourceDomains = ["https://cdn.custom.com"],
+            FrameDomains = ["https://embed.custom.com"],
+            BaseUriDomains = [],
+        };
+        var payload = new HtmlWidgetPayload
+        {
+            Name = "test",
+            Html = "<body>hi</body>",
+            Domain = "https://example.com",
+            SecurityPolicy = customPolicy,
+        };
+        var result = HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(payload);
+        Assert.Contains("api.custom.com", result);
+        Assert.Contains("cdn.custom.com", result);
+        Assert.Contains("embed.custom.com", result);
+    }
+
+    [Fact]
+    public void BuildHtmlWidgetMarkdown_SerializesFullPayload()
+    {
+        var payload = new HtmlWidgetPayload
+        {
+            Name = "Weather Widget",
+            Description = "Current weather",
+            Html = "<body><div>72F</div></body>",
+            Domain = "https://weather.example.com",
+            SecurityPolicy = new HtmlWidgetSecurityPolicy
+            {
+                ConnectDomains = ["https://api.example.com"],
+                ResourceDomains = ["'self'", "data:"],
+                FrameDomains = [],
+                BaseUriDomains = [],
+            },
+            ToolInput = JsonSerializer.SerializeToElement(new { location = "Seattle" }),
+            Permissions = new HtmlWidgetPermissions { ClipboardWrite = new() },
+        };
+        var result = HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(payload);
+        Assert.StartsWith("```html-widget\n", result);
+        Assert.EndsWith("\n```", result);
+        Assert.Contains("Weather Widget", result);
+        Assert.Contains("Current weather", result);
+        Assert.Contains("weather.example.com", result);
+        Assert.Contains("api.example.com", result);
+        Assert.Contains("Seattle", result);
+        Assert.Contains("clipboardWrite", result);
+    }
+
+    [Fact]
+    public void BuildHtmlWidgetMarkdown_ForwardsProtocolOptions()
+    {
+        var payload = new HtmlWidgetPayload
+        {
+            Name = "test",
+            Html = "<body>hi</body>",
+            Domain = "https://example.com",
+        };
+        var options = new HtmlWidgetMarkdownOptions
+        {
+            ProtocolOptions = new InjectWidgetProtocolOptions
+            {
+                Version = "3.0.0",
+                Notifications = ["tool-result"],
+                DebugCspViolations = true,
+            }
+        };
+        var result = HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(payload, options);
+        // Parse the JSON from inside the code fence to check the injected HTML
+        var json = result.Replace("```html-widget\n", "").Replace("\n```", "");
+        using var doc = JsonDocument.Parse(json);
+        var html = doc.RootElement.GetProperty("html").GetString()!;
+        Assert.Contains("version:'3.0.0'", html);
+        Assert.Contains("tool-result", html);
+        Assert.Contains("securitypolicyviolation", html);
+    }
+
+    // --- Additional security policy validators ---
+
+    [Fact]
+    public void ValidateSecurityPolicy_DetectsImgSrc()
+    {
+        var html = "<img src=\"https://cdn.example.com/logo.png\">";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+        Assert.Equal("<img src>", warnings[0].Source);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_DetectsAudioSrc()
+    {
+        var html = "<audio src=\"https://cdn.example.com/audio.mp3\"></audio>";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+        Assert.Equal("<audio src>", warnings[0].Source);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_DetectsVideoSrc()
+    {
+        var html = "<video src=\"https://cdn.example.com/video.mp4\"></video>";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+        Assert.Equal("<video src>", warnings[0].Source);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_DetectsLinkHref()
+    {
+        var html = "<link href=\"https://cdn.example.com/style.css\" rel=\"stylesheet\">";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+        Assert.Equal("<link href>", warnings[0].Source);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_DetectsWebSocket()
+    {
+        var html = "<script>new WebSocket('wss://ws.example.com/feed')</script>";
+        var policy = new HtmlWidgetSecurityPolicy { ConnectDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+        Assert.Equal("new WebSocket()", warnings[0].Source);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_DetectsXhr()
+    {
+        var html = "<script>xhr.open('GET', 'https://api.example.com/data')</script>";
+        var policy = new HtmlWidgetSecurityPolicy { ConnectDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+        Assert.Equal("XMLHttpRequest.open()", warnings[0].Source);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_DetectsEventSource()
+    {
+        var html = "<script>new EventSource('https://sse.example.com/stream')</script>";
+        var policy = new HtmlWidgetSecurityPolicy { ConnectDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+        Assert.Equal("new EventSource()", warnings[0].Source);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_DetectsMultipleViolations()
+    {
+        var html = "<script src=\"https://a.com/x.js\"></script><img src=\"https://b.com/y.png\"><script>fetch('https://c.com/api')</script>";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = [], ConnectDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Equal(3, warnings.Count);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_NoWarningsForNoExternalRefs()
+    {
+        var html = "<div><p>Just text</p></div>";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Empty(warnings);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_HandlesProtocolRelativeUrls()
+    {
+        var html = "<script src=\"//cdn.example.com/lib.js\"></script>";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_NoWarnWhenFetchInConnectDomains()
+    {
+        var html = "<script>fetch('https://api.example.com/data')</script>";
+        var policy = new HtmlWidgetSecurityPolicy { ConnectDomains = ["https://api.example.com"] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Empty(warnings);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_NoWarnWhenIframeInFrameDomains()
+    {
+        var html = "<iframe src=\"https://embed.example.com/video\"></iframe>";
+        var policy = new HtmlWidgetSecurityPolicy { FrameDomains = ["https://embed.example.com"] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Empty(warnings);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_DetectsCssImport()
+    {
+        var html = "<style>@import url('https://fonts.example.com/font.css');</style>";
+        var policy = new HtmlWidgetSecurityPolicy { ResourceDomains = [] };
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+    }
+
+    [Fact]
+    public void ValidateSecurityPolicy_HandlesUndefinedPolicyFields()
+    {
+        var html = "<script src=\"https://cdn.example.com/lib.js\"></script>";
+        var policy = new HtmlWidgetSecurityPolicy();
+        var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
+        Assert.Single(warnings);
+    }
+}
+
+#pragma warning restore ExperimentalTeamsHtmlWidget
diff --git a/core/test/Microsoft.Teams.Apps.UnitTests/Microsoft.Teams.Apps.UnitTests.csproj b/core/test/Microsoft.Teams.Apps.UnitTests/Microsoft.Teams.Apps.UnitTests.csproj
index bd61ffd3..8e3a491b 100644
--- a/core/test/Microsoft.Teams.Apps.UnitTests/Microsoft.Teams.Apps.UnitTests.csproj
+++ b/core/test/Microsoft.Teams.Apps.UnitTests/Microsoft.Teams.Apps.UnitTests.csproj
@@ -5,7 +5,7 @@
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
     <IsPackable>false</IsPackable>
-    <NoWarn>$(NoWarn);ExperimentalTeamsTargeted</NoWarn>
+    <NoWarn>$(NoWarn);ExperimentalTeamsTargeted;ExperimentalTeamsHtmlWidget</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

From b802ffecb252760a5d45b4d7cbc51f833b9f92fc Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Wed, 1 Jul 2026 12:40:23 -0700
Subject: [PATCH 4/6] Integration tests

---
 core/test/IntegrationTests/HtmlWidgetTests.cs | 165 ++++++++++++++++++
 .../IntegrationTests/IntegrationTests.csproj  |   2 +-
 2 files changed, 166 insertions(+), 1 deletion(-)
 create mode 100644 core/test/IntegrationTests/HtmlWidgetTests.cs

diff --git a/core/test/IntegrationTests/HtmlWidgetTests.cs b/core/test/IntegrationTests/HtmlWidgetTests.cs
new file mode 100644
index 00000000..71ef144a
--- /dev/null
+++ b/core/test/IntegrationTests/HtmlWidgetTests.cs
@@ -0,0 +1,165 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Teams.Apps.HtmlWidget;
+using Microsoft.Teams.Apps.Schema;
+using Microsoft.Teams.Core;
+using Microsoft.Teams.Core.Schema;
+using Xunit.Abstractions;
+
+namespace IntegrationTests;
+
+/// <summary>
+/// Integration tests for HTML widget messages — verifies Teams accepts widget payloads via the Bot API.
+/// These tests require a canary service URL to pass (widgets are canary-only).
+/// </summary>
+[SuppressMessage("Usage", "ExperimentalTeamsHtmlWidget:Type is for evaluation purposes only", Justification = "Integration tests for experimental feature")]
+public class HtmlWidgetTests : IClassFixture<IntegrationTestFixture>
+{
+    private readonly IntegrationTestFixture _f;
+    private readonly ITestOutputHelper _output;
+
+    public HtmlWidgetTests(IntegrationTestFixture fixture, ITestOutputHelper output)
+    {
+        _f = fixture;
+        _f.OutputHelper = output;
+        _output = output;
+    }
+
+    private bool IsCanary => _f.ServiceUrl.ToString().Contains("canary", StringComparison.OrdinalIgnoreCase);
+
+    private CoreActivity CreateWidgetActivity(string markdown) =>
+        CoreActivity.CreateBuilder()
+            .WithType(ActivityType.Message)
+            .WithFrom(IntegrationTestFixture.GetChannelAccountWithAgenticProperties())
+            .WithProperty("text", markdown)
+            .WithProperty("textFormat", TextFormats.ExtendedMarkdown)
+            .Build();
+
+    [SkippableFact(Timeout = 5000)]
+    public async Task SendWidgetMessage()
+    {
+        Skip.IfNot(IsCanary, "Widgets require canary service");
+
+        var markdown = HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(
+            new HtmlWidgetPayload
+            {
+                Name = "Integration Test Widget",
+                Description = "Verifies Teams accepts widget payload.",
+                Html = "<body><p>Integration test widget</p></body>",
+                Domain = "https://teams.microsoft.com",
+                SecurityPolicy = new HtmlWidgetSecurityPolicy
+                {
+                    ConnectDomains = [],
+                    ResourceDomains = ["'self'", "data:"],
+                    FrameDomains = [],
+                    BaseUriDomains = [],
+                },
+                Permissions = new HtmlWidgetPermissions(),
+            },
+            new HtmlWidgetMarkdownOptions { Before = "[.NET Integration] HTML widget send test" });
+
+        CoreActivity activity = CreateWidgetActivity(markdown);
+        SendActivityResponse? res = await _f.ScopedApiClient.Conversations.Activities.CreateAsync(_f.ConversationId, activity);
+
+        Assert.NotNull(res);
+        Assert.NotNull(res.Id);
+        _output.WriteLine($"Sent widget activity: {res.Id}");
+    }
+
+    [SkippableFact(Timeout = 5000)]
+    public async Task SendWidgetWithToolData()
+    {
+        Skip.IfNot(IsCanary, "Widgets require canary service");
+
+        var markdown = HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(
+            new HtmlWidgetPayload
+            {
+                Name = "ToolOutput Widget",
+                Description = "Widget with initial tool data.",
+                Html = "<body><p>Widget with tool data</p></body>",
+                Domain = "https://teams.microsoft.com",
+                SecurityPolicy = new HtmlWidgetSecurityPolicy
+                {
+                    ConnectDomains = [],
+                    ResourceDomains = ["'self'"],
+                    FrameDomains = [],
+                    BaseUriDomains = [],
+                },
+                ToolInput = System.Text.Json.JsonSerializer.SerializeToElement(new { query = "test" }),
+                ToolOutput = System.Text.Json.JsonSerializer.SerializeToElement(new
+                {
+                    content = new[] { new { type = "text", text = "Result data" } },
+                    structuredContent = new { key = "value" },
+                    isError = false,
+                }),
+                Permissions = new HtmlWidgetPermissions { ClipboardWrite = new() },
+            });
+
+        CoreActivity activity = CreateWidgetActivity(markdown);
+        SendActivityResponse? res = await _f.ScopedApiClient.Conversations.Activities.CreateAsync(_f.ConversationId, activity);
+
+        Assert.NotNull(res);
+        Assert.NotNull(res.Id);
+        _output.WriteLine($"Sent widget with tool data: {res.Id}");
+    }
+
+    [SkippableFact(Timeout = 5000)]
+    public async Task UpdateWidgetMessage()
+    {
+        Skip.IfNot(IsCanary, "Widgets require canary service");
+
+        var markdown = HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(
+            new HtmlWidgetPayload
+            {
+                Name = "Update Test Widget",
+                Html = "<body><p>Original content</p></body>",
+                Domain = "https://teams.microsoft.com",
+            },
+            new HtmlWidgetMarkdownOptions { Before = "[.NET Integration] Widget update test - original" });
+
+        CoreActivity activity = CreateWidgetActivity(markdown);
+        SendActivityResponse? sent = await _f.ScopedApiClient.Conversations.Activities.CreateAsync(_f.ConversationId, activity);
+        Assert.NotNull(sent?.Id);
+
+        var updatedMarkdown = HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(
+            new HtmlWidgetPayload
+            {
+                Name = "Update Test Widget",
+                Html = "<body><p>Updated content</p></body>",
+                Domain = "https://teams.microsoft.com",
+            },
+            new HtmlWidgetMarkdownOptions { Before = "[.NET Integration] Widget update test - updated" });
+
+        CoreActivity updatedActivity = CreateWidgetActivity(updatedMarkdown);
+        UpdateActivityResponse? res = await _f.ScopedApiClient.Conversations.Activities.UpdateAsync(
+            _f.ConversationId, sent.Id, updatedActivity);
+
+        Assert.NotNull(res?.Id);
+        _output.WriteLine($"Updated widget activity: {res.Id}");
+    }
+
+    [SkippableFact(Timeout = 10000)]
+    public async Task DeleteWidgetMessage()
+    {
+        Skip.IfNot(IsCanary, "Widgets require canary service");
+
+        var markdown = HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(
+            new HtmlWidgetPayload
+            {
+                Name = "Delete Test Widget",
+                Html = "<body><p>Will be deleted</p></body>",
+                Domain = "https://teams.microsoft.com",
+            });
+
+        CoreActivity activity = CreateWidgetActivity(markdown);
+        SendActivityResponse? sent = await _f.ScopedApiClient.Conversations.Activities.CreateAsync(_f.ConversationId, activity);
+        Assert.NotNull(sent?.Id);
+
+        await Task.Delay(2000);
+
+        await _f.ScopedApiClient.Conversations.Activities.DeleteAsync(_f.ConversationId, sent.Id, _f.AgenticIdentity);
+        _output.WriteLine($"Deleted widget activity: {sent.Id}");
+    }
+}
diff --git a/core/test/IntegrationTests/IntegrationTests.csproj b/core/test/IntegrationTests/IntegrationTests.csproj
index aeed14f9..2479fec0 100644
--- a/core/test/IntegrationTests/IntegrationTests.csproj
+++ b/core/test/IntegrationTests/IntegrationTests.csproj
@@ -5,7 +5,7 @@
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
     <IsPackable>false</IsPackable>
-	<NoWarn>$(NoWarn);ExperimentalTeamsTargeted;CS0618</NoWarn>
+	<NoWarn>$(NoWarn);ExperimentalTeamsTargeted;ExperimentalTeamsHtmlWidget;CS0618</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

From c77ee78e54995cc7579d45dc68e7cde6e0d4855e Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Wed, 1 Jul 2026 12:40:28 -0700
Subject: [PATCH 5/6] CI Fixes

---
 Samples/Deprecated.Controllers/Deprecated.Controllers.csproj   | 3 ++-
 Samples/Samples.Dialogs/Samples.Dialogs.csproj                 | 3 ++-
 Samples/Samples.Echo/Samples.Echo.csproj                       | 2 +-
 Samples/Samples.Quoting/Samples.Quoting.csproj                 | 2 +-
 Samples/Samples.SuggestedAction/Samples.SuggestedAction.csproj | 2 +-
 .../Samples.TargetedMessages/Samples.TargetedMessages.csproj   | 2 +-
 6 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/Samples/Deprecated.Controllers/Deprecated.Controllers.csproj b/Samples/Deprecated.Controllers/Deprecated.Controllers.csproj
index 9a269eea..d2c63d5a 100644
--- a/Samples/Deprecated.Controllers/Deprecated.Controllers.csproj
+++ b/Samples/Deprecated.Controllers/Deprecated.Controllers.csproj
@@ -9,7 +9,8 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.2" />
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.9" />
+    <PackageReference Include="Microsoft.OpenApi" Version="2.7.5" />
   </ItemGroup>
 
   <ItemGroup>
diff --git a/Samples/Samples.Dialogs/Samples.Dialogs.csproj b/Samples/Samples.Dialogs/Samples.Dialogs.csproj
index 90bea372..36e90424 100644
--- a/Samples/Samples.Dialogs/Samples.Dialogs.csproj
+++ b/Samples/Samples.Dialogs/Samples.Dialogs.csproj
@@ -21,7 +21,8 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.9" />
+    <PackageReference Include="Microsoft.OpenApi" Version="2.7.5" />
     <PackageReference Include="Microsoft.Extensions.FileProviders.Embedded" Version="10.0.0" />
   </ItemGroup>
 
diff --git a/Samples/Samples.Echo/Samples.Echo.csproj b/Samples/Samples.Echo/Samples.Echo.csproj
index 8c396d7b..3747a677 100644
--- a/Samples/Samples.Echo/Samples.Echo.csproj
+++ b/Samples/Samples.Echo/Samples.Echo.csproj
@@ -7,7 +7,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.2" />
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.9" />
   </ItemGroup>
 
   <ItemGroup>
diff --git a/Samples/Samples.Quoting/Samples.Quoting.csproj b/Samples/Samples.Quoting/Samples.Quoting.csproj
index 8c396d7b..3747a677 100644
--- a/Samples/Samples.Quoting/Samples.Quoting.csproj
+++ b/Samples/Samples.Quoting/Samples.Quoting.csproj
@@ -7,7 +7,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.2" />
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.9" />
   </ItemGroup>
 
   <ItemGroup>
diff --git a/Samples/Samples.SuggestedAction/Samples.SuggestedAction.csproj b/Samples/Samples.SuggestedAction/Samples.SuggestedAction.csproj
index 8c396d7b..3747a677 100644
--- a/Samples/Samples.SuggestedAction/Samples.SuggestedAction.csproj
+++ b/Samples/Samples.SuggestedAction/Samples.SuggestedAction.csproj
@@ -7,7 +7,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.2" />
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.9" />
   </ItemGroup>
 
   <ItemGroup>
diff --git a/Samples/Samples.TargetedMessages/Samples.TargetedMessages.csproj b/Samples/Samples.TargetedMessages/Samples.TargetedMessages.csproj
index d6390cbb..16a70e6e 100644
--- a/Samples/Samples.TargetedMessages/Samples.TargetedMessages.csproj
+++ b/Samples/Samples.TargetedMessages/Samples.TargetedMessages.csproj
@@ -8,7 +8,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.2" />
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.9" />
   </ItemGroup>
 
   <ItemGroup>

From 10c6faf38c444e7234e5a39e44bb583e11e405fa Mon Sep 17 00:00:00 2001
From: Corina Gum <14900841+corinagum@users.noreply.github.com>
Date: Tue, 7 Jul 2026 16:24:40 -0700
Subject: [PATCH 6/6] Address feedback

---
 .../HtmlWidget/CallToolResult.cs              |  3 ++-
 .../HtmlWidget/HtmlWidgetPayload.cs           | 19 ++++++++++--------
 ...etProtocol_FullScriptSnapshot.verified.txt |  1 +
 .../HtmlWidgetHelpersTests.cs                 | 20 ++++++++++++++++++-
 .../Microsoft.Teams.Apps.UnitTests.csproj     |  1 +
 5 files changed, 34 insertions(+), 10 deletions(-)
 create mode 100644 core/test/Microsoft.Teams.Apps.UnitTests/HtmlWidgetHelpersTests.InjectWidgetProtocol_FullScriptSnapshot.verified.txt

diff --git a/core/src/Microsoft.Teams.Apps/HtmlWidget/CallToolResult.cs b/core/src/Microsoft.Teams.Apps/HtmlWidget/CallToolResult.cs
index 27a7bf9a..4ae49311 100644
--- a/core/src/Microsoft.Teams.Apps/HtmlWidget/CallToolResult.cs
+++ b/core/src/Microsoft.Teams.Apps/HtmlWidget/CallToolResult.cs
@@ -13,7 +13,8 @@ namespace Microsoft.Teams.Apps.HtmlWidget;
 public class McpUiCallToolResultContent
 {
     /// <summary>
-    /// The type of content (e.g. "text").
+    /// The type of content. MCP defines: "text", "image", "audio", "resource".
+    /// Teams currently only renders "text" content.
     /// </summary>
     [JsonPropertyName("type")]
     public string Type { get; set; } = "text";
diff --git a/core/src/Microsoft.Teams.Apps/HtmlWidget/HtmlWidgetPayload.cs b/core/src/Microsoft.Teams.Apps/HtmlWidget/HtmlWidgetPayload.cs
index a2bec804..974fd0dd 100644
--- a/core/src/Microsoft.Teams.Apps/HtmlWidget/HtmlWidgetPayload.cs
+++ b/core/src/Microsoft.Teams.Apps/HtmlWidget/HtmlWidgetPayload.cs
@@ -44,37 +44,38 @@ public class HtmlWidgetSecurityPolicy
 
 /// <summary>
 /// Permissions that the widget may request from the host.
+/// Presence of a field means the permission is requested (value should be an empty object).
 /// </summary>
 [Experimental("ExperimentalTeamsHtmlWidget")]
 public class HtmlWidgetPermissions
 {
     /// <summary>
-    /// Request camera access.
+    /// Request camera access. Set to an empty dictionary to request.
     /// </summary>
     [JsonPropertyName("camera")]
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
-    public object? Camera { get; set; }
+    public IDictionary<string, object>? Camera { get; set; }
 
     /// <summary>
-    /// Request microphone access.
+    /// Request microphone access. Set to an empty dictionary to request.
     /// </summary>
     [JsonPropertyName("microphone")]
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
-    public object? Microphone { get; set; }
+    public IDictionary<string, object>? Microphone { get; set; }
 
     /// <summary>
-    /// Request geolocation access.
+    /// Request geolocation access. Set to an empty dictionary to request.
     /// </summary>
     [JsonPropertyName("geolocation")]
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
-    public object? Geolocation { get; set; }
+    public IDictionary<string, object>? Geolocation { get; set; }
 
     /// <summary>
-    /// Request clipboard write access.
+    /// Request clipboard write access. Set to an empty dictionary to request.
     /// </summary>
     [JsonPropertyName("clipboardWrite")]
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
-    public object? ClipboardWrite { get; set; }
+    public IDictionary<string, object>? ClipboardWrite { get; set; }
 }
 
 /// <summary>
@@ -112,6 +113,8 @@ public class HtmlWidgetPayload
     /// <summary>
     /// The domain associated with the widget, applied to sandbox metadata.
     /// Must be a valid domain URL (e.g. 'https://example.com').
+    /// This is informational metadata, not a verified identity claim.
+    /// The platform does not authenticate this value.
     /// </summary>
     [JsonPropertyName("domain")]
     public string Domain { get; set; } = string.Empty;
diff --git a/core/test/Microsoft.Teams.Apps.UnitTests/HtmlWidgetHelpersTests.InjectWidgetProtocol_FullScriptSnapshot.verified.txt b/core/test/Microsoft.Teams.Apps.UnitTests/HtmlWidgetHelpersTests.InjectWidgetProtocol_FullScriptSnapshot.verified.txt
new file mode 100644
index 00000000..47ea8ebc
--- /dev/null
+++ b/core/test/Microsoft.Teams.Apps.UnitTests/HtmlWidgetHelpersTests.InjectWidgetProtocol_FullScriptSnapshot.verified.txt
@@ -0,0 +1 @@
+(function(){document.addEventListener('securitypolicyviolation',function(e){console.warn('[widget CSP violation]',{blockedURI:e.blockedURI,violatedDirective:e.violatedDirective,originalPolicy:e.originalPolicy});});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);}if(d.method==='ui/notifications/tool-result'&&window.onToolResult){window.onToolResult(d.params);}if(d.method==='ui/notifications/tool-input'&&window.onToolInput){window.onToolInput(d.params);}});window.parent.postMessage({jsonrpc:'2.0',id:id,method:'ui/initialize',params:{protocolVersion:'2026-01-26',appInfo:{name:'My Widget',version:'2.0.0'},appCapabilities:{availableDisplayModes:["inline","fullscreen"]}}},'*');document.addEventListener('DOMContentLoaded',notifySize);})()
\ No newline at end of file
diff --git a/core/test/Microsoft.Teams.Apps.UnitTests/HtmlWidgetHelpersTests.cs b/core/test/Microsoft.Teams.Apps.UnitTests/HtmlWidgetHelpersTests.cs
index 5e174bb3..ebcf00e4 100644
--- a/core/test/Microsoft.Teams.Apps.UnitTests/HtmlWidgetHelpersTests.cs
+++ b/core/test/Microsoft.Teams.Apps.UnitTests/HtmlWidgetHelpersTests.cs
@@ -558,7 +558,7 @@ public void BuildHtmlWidgetMarkdown_SerializesFullPayload()
                 BaseUriDomains = [],
             },
             ToolInput = JsonSerializer.SerializeToElement(new { location = "Seattle" }),
-            Permissions = new HtmlWidgetPermissions { ClipboardWrite = new() },
+            Permissions = new HtmlWidgetPermissions { ClipboardWrite = new Dictionary<string, object>() },
         };
         var result = HtmlWidgetHelpers.BuildHtmlWidgetMarkdown(payload);
         Assert.StartsWith("```html-widget\n", result);
@@ -733,6 +733,24 @@ public void ValidateSecurityPolicy_HandlesUndefinedPolicyFields()
         var warnings = HtmlWidgetHelpers.ValidateSecurityPolicy(html, policy);
         Assert.Single(warnings);
     }
+
+    [Fact]
+    public async Task InjectWidgetProtocol_FullScriptSnapshot()
+    {
+        var opts = new InjectWidgetProtocolOptions
+        {
+            Name = "My Widget",
+            Version = "2.0.0",
+            AvailableDisplayModes = ["inline", "fullscreen"],
+            Notifications = ["tool-result", "tool-input"],
+            DebugCspViolations = true,
+        };
+        var result = HtmlWidgetHelpers.InjectWidgetProtocol("<body><h1>Hello</h1></body>", opts);
+
+        var match = System.Text.RegularExpressions.Regex.Match(result, @"<script>(.*?)</script>");
+        Assert.True(match.Success);
+        await VerifyXunit.Verifier.Verify(match.Groups[1].Value);
+    }
 }
 
 #pragma warning restore ExperimentalTeamsHtmlWidget
diff --git a/core/test/Microsoft.Teams.Apps.UnitTests/Microsoft.Teams.Apps.UnitTests.csproj b/core/test/Microsoft.Teams.Apps.UnitTests/Microsoft.Teams.Apps.UnitTests.csproj
index 8e3a491b..eabfcdbb 100644
--- a/core/test/Microsoft.Teams.Apps.UnitTests/Microsoft.Teams.Apps.UnitTests.csproj
+++ b/core/test/Microsoft.Teams.Apps.UnitTests/Microsoft.Teams.Apps.UnitTests.csproj
@@ -15,6 +15,7 @@
     </PackageReference>
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.4.0" />
     <PackageReference Include="Moq" Version="4.20.72" />
+    <PackageReference Include="Verify.Xunit" Version="31.12.5" />
     <PackageReference Include="xunit" Version="2.9.3" />
     <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5">
       <PrivateAssets>all</PrivateAssets>