Add docs on troubleshooting web components CSP errors & update CSP terminal error message (#733)

Author: wwwillchen

docs/assets/csp-message.webp

@@ -0,0 +1,73 @@
+# Troubleshooting
+
+## Security policy
+
+One of the most common issues when using web components is that you will need to relax the stringent security policy Mesop uses by default.
+
+If you use the `mesop` command-line tool to run your app, you will see a detailed error message printed like this that will tell you how to fix the error:
+
+<img src="/assets/csp-message.webp">
+
+If you are using Colab or another tool to run your Mesop app, and you can't see the terminal messages, then you can use your browser developer tools to view the console error messages.
+
+### Content security policy error messages
+
+In your browser developer tools, you may see the following console error messages (the exact wording may differ):
+
+#### script-src Error
+
+???+ failure "script-src Console Error"
+    Refused to load the script 'https://cdn.jsdelivr.net/gh/lit/dist@3/core/lit-core.min.js' because it violates the following Content Security Policy directive: "script-src 'self' 'nonce-X-_ZR64fycojGBCDQbjpLA'". Note that 'script-src-elem' was not explicitly set, so 'script-src' is used as a fallback.
+
+If you see this error message, then you will need to update your page's [Security Policy](../api/page.md#mesop.security.security_policy.SecurityPolicy) `allowed_script_srcs` property. In this example, because the "script-src" directive was violated, you will need to add the script's URL to the Security Policy like this:
+
+```py
+@me.page(
+    security_policy=me.SecurityPolicy(
+        allowed_script_srcs=["https://cdn.jsdelivr.net"]
+    )
+)
+```
+
+???+ tip "Allow-listing sites"
+     You can allow-list the full URL including the path, but it's usually more convenient
+     to allow-list the entire site. This depends on how trustworthy the site is.
+
+#### connect-src Error
+
+???+ failure "connect-src Console Error"
+    zone.umd.js:2767 Refused to connect to 'https://identitytoolkit.googleapis.com/v1/projects' because it violates the following Content Security Policy directive: "default-src 'self'". Note that 'connect-src' was not explicitly set, so 'default-src' is used as a fallback.
+
+
+If you see this error message, then you will need to update your page's [Security Policy](../api/page.md#mesop.security.security_policy.SecurityPolicy) `allowed_connect_srcs` property. In this example, because the "connect-src" directive was violated, you will need to add the URL you are trying to connect to (e.g. XHR, fetch) to the Security Policy like this:
+
+```py
+@me.page(
+    security_policy=me.SecurityPolicy(
+        allowed_connect_srcs=["https://*.googleapis.com"]
+    )
+)
+```
+
+???+ tip "Allow-listing domains using wildcard"
+     You can wildcard all the subdomains for a site by using the wildcard character `*`.
+
+#### Trusted Types Error
+
+Trusted Types errors can come in various forms. If you see a console error message that contains TrustedHTML, TrustedScriptURL or some other variation, then you are likely hitting a trusted types error. Trusted Types is a powerful web security feature which prevents untrusted code from using sensitive browser APIs.
+
+Unfortunately, many third-party libraries are incompatible with trusted types which means you need to disable this web security defense protection for the Mesop page which uses these libraries via web components.
+
+???+ failure "TrustedHTML Console Error"
+
+    TypeError: Failed to set the 'innerHTML' property on 'Element': This document requires 'TrustedHTML' assignment.
+
+You can fix this Trusted Types error by disabling Trusted Types in the security policy like this:
+
+```py
+@me.page(
+    security_policy=me.SecurityPolicy(
+        dangerously_disable_trusted_types=True
+    )
+)
+```

docs/web-components/troubleshooting.md

@@ -135,7 +135,7 @@ def csp_report():
       keyword_arg = "allowed_connect_srcs"
     elif violated_directive == "frame-ancestors":
       keyword_arg = "allowed_iframe_parents"
-    elif violated_directive == "require-trusted-types-for":
+    elif violated_directive in ("require-trusted-types-for", "trusted-types"):
       keyword_arg = "dangerously_disable_trusted_types"
     else:
       raise Exception("Unexpected CSP violation:", violated_directive, report)
@@ -148,7 +148,6 @@ def csp_report():
       f"""
 {tc.RED}⚠️  Content Security Policy Error  ⚠️{tc.RESET}
 {tc.YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━{tc.RESET}
-
 {tc.CYAN}Directive:{tc.RESET}   {tc.GREEN}{violated_directive}{tc.RESET}
 {tc.CYAN}Blocked URL:{tc.RESET} {tc.GREEN}{blocked_uri}{tc.RESET}
 {tc.CYAN}App path:{tc.RESET}    {tc.GREEN}{path}{tc.RESET}
@@ -162,6 +161,8 @@ def csp_report():
   {tc.MAGENTA}){tc.RESET}
 {tc.MAGENTA}){tc.RESET}
 
+{tc.YELLOW}For more info:
+{tc.CYAN}https://google.github.io/mesop/web-components/troubleshooting/{tc.RESET}
 {tc.YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━{tc.RESET}
 """  # noqa: RUF001
     )

mesop/server/static_file_serving.py

@@ -32,6 +32,7 @@ nav:
               - Overview: web-components/index.md
               - Quickstart: web-components/quickstart.md
               - API: web-components/api.md
+              - Troubleshooting: web-components/troubleshooting.md
       - High-level:
           - Chat: components/chat.md
           - Text to Text: components/text-to-text.md