From a8107a673306767fadba0ccc08b3039b5b2e5fdc Mon Sep 17 00:00:00 2001
From: Jonathan Hefner <jonathan@hefner.pro>
Date: Fri, 21 Nov 2025 16:41:37 -0600
Subject: [PATCH] Convert UiResourceMeta documentation to TypeDoc comments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move metadata field documentation from separate prose section into
TypeDoc comments on the UiResourceMeta interface properties. This
consolidates the documentation and eliminates duplication while making
it more maintainable and IDE-friendly.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 specification/draft/apps.mdx | 76 +++++++++++++++++++++---------------
 1 file changed, 45 insertions(+), 31 deletions(-)

diff --git a/specification/draft/apps.mdx b/specification/draft/apps.mdx
index 7701afa..57c67d7 100644
--- a/specification/draft/apps.mdx
+++ b/specification/draft/apps.mdx
@@ -61,11 +61,56 @@ interface UIResource {
 }
 
 interface UIResourceMeta {
+  /**
+   * Content Security Policy configuration
+   *
+   * Servers declare which external origins their UI needs to access.
+   * Hosts use this to enforce appropriate CSP headers.
+   */
   csp?: {
+    /**
+     * Origins for network requests
+     *
+     * - Empty or omitted = no external connections (secure default)
+     * - Maps to CSP `connect-src` directive
+     *
+     * @example
+     * ["https://api.weather.com", "wss://realtime.service.com"]
+     */
     connectDomains?: string[],
+    /**
+     * Origins for static resources (images, scripts, stylesheets, fonts)
+     *
+     * - Empty or omitted = no external resources (secure default)
+     * - Wildcard subdomains supported: `https://*.example.com`
+     * - Maps to CSP `img-src`, `script-src`, `style-src`, `font-src` directives
+     *
+     * @example
+     * ["https://cdn.jsdelivr.net", "https://*.cloudflare.com"]
+     */
     resourceDomains?: string[],
   },
+  /**
+   * Dedicated origin for widget
+   *
+   * Optional domain for the widget's sandbox origin. Useful when widgets need
+   * dedicated origins for API key allowlists or cross-origin isolation.
+   *
+   * If omitted, Host uses default sandbox origin.
+   *
+   * @example
+   * "https://weather-widget.example.com"
+   */
   domain?: string,
+  /**
+   * Visual boundary preference
+   *
+   * Boolean indicating the UI prefers a visible border. Useful for widgets
+   * that might blend with host background.
+   *
+   * - `true`: Request visible border (host decides styling)
+   * - `false` or omitted: No preference
+   */
   prefersBorder?: boolean,
 }
 ```
@@ -101,37 +146,6 @@ The resource content is returned via `resources/read`:
 - Content MUST be provided via either `text` (string) or `blob` (base64-encoded)
 - Content MUST be valid HTML5 document
 
-#### Metadata Fields:
-
-**`ui.csp` - Content Security Policy configuration**
-
-Servers declare which external origins their UI needs to access. Hosts use this to enforce appropriate CSP headers.
-
-- `connect_domains`: Origins for network requests
-  - Example: `["https://api.weather.com", "wss://realtime.service.com"]`
-  - Empty or omitted = no external connections (secure default)
-  - Maps to CSP `connect-src` directive
-
-- `resource_domains`: Origins for static resources (images, scripts, stylesheets, fonts)
-  - Example: `["https://cdn.jsdelivr.net", "https://*.cloudflare.com"]`
-  - Empty or omitted = no external resources (secure default)
-  - Wildcard subdomains supported: `https://*.example.com`
-  - Maps to CSP `img-src`, `script-src`, `style-src`, `font-src` directives
-
-**`ui.domain` - Dedicated origin for widget**
-
-Optional domain for the widget's sandbox origin. Useful when widgets need dedicated origins for API key allowlists or cross-origin isolation.
-
-- Example: `"https://weather-widget.example.com"`
-- If omitted, Host uses default sandbox origin
-
-**`ui.prefersBorder` - Visual boundary preference**
-
-Boolean indicating the UI prefers a visible border. Useful for widgets that might blend with host background.
-
-- `true`: Request visible border (host decides styling)
-- `false` or omitted: No preference
-
 #### Host Behavior:
 
 - **CSP Enforcement:** Host MUST construct CSP headers based on declared domains