@stackable-labs/mcp-app-extension 1.5.0 → 1.7.0

package/dist/index.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { IDENTITY_EVENT, ACTIVITY_EVENT, SURFACE_TARGET, TEMPLATE_FLAVORS, PERMISSIONS, CAPABILITY_PERMISSION_MAP, EVENT_HOOK_PERMISSION_MAP, ALLOWED_ICONS, UI_TAGS, UI_TAG_ATTRIBUTES, tagToComponentName } from '@stackable-labs/sdk-extension-contracts';
+import { IDENTITY_EVENT, ACTIVITY_EVENT, SURFACE_TARGET, TEMPLATE_FLAVORS, PERMISSIONS, CAPABILITY_PERMISSION_MAP, EVENT_HOOK_PERMISSION_MAP, ALLOWED_ICONS, UI_TAGS, UI_TAG_CATEGORIES, UI_TAG_ATTRIBUTES, tagToComponentName } from '@stackable-labs/sdk-extension-contracts';
+import { validatePatternFormat } from '@stackable-labs/lib-contracts';
 import fs4, { readFile, mkdir, writeFile, constants } from 'fs/promises';
 import path, { join } from 'path';
 import os, { homedir } from 'os';
@@ -382,6 +383,22 @@ var frontmatter = (meta) => {
 var generateCoreReference = () => CORE_CONTENT;
 
 // ../../sdk/extension/ai-docs/src/generators/components.ts
+var CATEGORY_ORDER = [
+  "layout",
+  "text",
+  "input",
+  "navigation",
+  "feedback",
+  "composite"
+];
+var CATEGORY_LABELS = {
+  layout: "Layout",
+  text: "Text",
+  input: "Input",
+  navigation: "Navigation",
+  feedback: "Feedback",
+  composite: "Composite"
+};
 var generateComponents = () => {
   const fm = frontmatter({
     root: false,
@@ -389,13 +406,31 @@ var generateComponents = () => {
     description: "Available UI components with allowed attributes per tag",
     globs: ["packages/extension/src/**/*.tsx"]
   });
-  const componentLines = [];
+  const tagsByCategory = /* @__PURE__ */ new Map();
   for (const tag of UI_TAGS) {
-    const attrs = UI_TAG_ATTRIBUTES[tag];
-    const name = tagToComponentName(tag);
-    componentLines.push(`### \`<ui.${name}>\` (\`${tag}\`)`);
-    componentLines.push(`Allowed attributes: ${attrs.map((a2) => `\`${a2}\``).join(", ")}`);
+    const category = UI_TAG_CATEGORIES[tag];
+    const bucket = tagsByCategory.get(category) ?? [];
+    bucket.push(tag);
+    tagsByCategory.set(category, bucket);
+  }
+  for (const tags of tagsByCategory.values()) {
+    tags.sort();
+  }
+  const componentLines = [];
+  for (const category of CATEGORY_ORDER) {
+    const tags = tagsByCategory.get(category);
+    if (!tags || tags.length === 0) {
+      continue;
+    }
+    componentLines.push(`## ${CATEGORY_LABELS[category]}`);
     componentLines.push("");
+    for (const tag of tags) {
+      const attrs = UI_TAG_ATTRIBUTES[tag];
+      const name = tagToComponentName(tag);
+      componentLines.push(`### \`<ui.${name}>\` (\`${tag}\`)`);
+      componentLines.push(`Allowed attributes: ${attrs.map((a2) => `\`${a2}\``).join(", ")}`);
+      componentLines.push("");
+    }
   }
   const iconList = ALLOWED_ICONS.map((icon) => `\`${icon}\``).join(", ");
   return `${fm}
@@ -492,12 +527,12 @@ Access capabilities via the \`useCapabilities()\` hook:
 const capabilities = useCapabilities()
 \`\`\`
 
-## data.query \u2014 Host-Mediated Requests
-The host handles the API call. Extension sends an action name + params, host returns data.
+## data.query \u2014 Platform-Mediated Requests
+The Stackable platform handles the API call. Extension sends an action name + params, the platform returns data.
 - **Permission required:** \`data:query\`
 - **Usage:** \`capabilities.data.query<T>(payload: ApiRequest): Promise<T>\`
 - **ApiRequest shape:** \`{ action: string; [key: string]: unknown }\`
-- **When to use:** When the host application handles the API integration
+- **When to use:** When the platform handles the API integration
 
 \`\`\`tsx
 const result = await capabilities.data.query<Customer>({
@@ -543,8 +578,8 @@ const result = await capabilities.data.fetch('https://api.example.com/orders', {
 
 > See [Instance Settings](./instance-settings) for the full schema-declaration + storage-mode story, including which field types accept \`secret: true\`.
 
-## context.read \u2014 Read Host Context
-Read host-provided context (customer ID, email, extension settings, etc.).
+## context.read \u2014 Read Platform Context
+Read framework-provided context (customer ID, email, extension settings, etc.).
 - **Permission required:** \`context:read\`
 - **Usage:** \`capabilities.context.read(): Promise<ContextData>\`
 - **ContextData shape:** \`{ customerId?: string, customerEmail?: string, settings?: Record<string, unknown>, [key: string]: unknown }\`
@@ -572,7 +607,7 @@ Non-secret settings declared in \`settingsSchema\` are automatically available v
 - No new permission needed \u2014 \`context:read\` is the only gate
 
 ## actions.toast \u2014 Show Toast Notifications
-Display a toast notification in the host UI.
+Display a toast notification in the framework widget's UI.
 - **Permission required:** \`actions:toast\`
 - **Usage:** \`capabilities.actions.toast(payload: ToastPayload): Promise<void>\`
 - **ToastPayload:** \`{ message: string, type?: 'success'|'error'|'info'|'warning', duration?: number }\`
@@ -581,8 +616,8 @@ Display a toast notification in the host UI.
 capabilities.actions.toast({ message: 'Saved!', type: 'success' })
 \`\`\`
 
-## actions.invoke \u2014 Invoke Host Actions
-Trigger host-defined actions (e.g., open a new conversation, set conversation tags/fields).
+## actions.invoke \u2014 Invoke Platform Actions
+Trigger framework-defined actions (e.g., open a new conversation, set conversation tags/fields).
 - **Permission required:** \`actions:invoke\`
 - **Usage:** \`capabilities.actions.invoke<T>(action: string, payload?: Record<string, unknown>): Promise<T>\`
 - **Available actions:**
@@ -611,7 +646,7 @@ await capabilities.actions.invoke('setConversationFields', [
 **Zendesk constraints:** Tags max 20, auto-lowercased/sanitized. Fields require \`web_widget_conversation_ticket_metadata\` feature flag. Both \`conversationTags\` and \`conversationFields\` **replace** on each call (not additive).
 
 ## events:identity \u2014 Identity Event Subscription
-Subscribe to real-time identity events (login, logout, refresh, expired) pushed from the host.
+Subscribe to real-time identity events (login, logout, refresh, expired) pushed from the host via the framework.
 - **Permission required:** \`events:identity\`
 - **Manifest events array:** Declare specific events to listen for (e.g. \`["identity:login", "identity:logout"]\`)
 - **Hook:** \`useIdentityEvent(eventType, handler)\`
@@ -651,7 +686,7 @@ ${HOOK_SNIPPETS["events:messaging"]}
 \`\`\`
 
 ## events:activity \u2014 Activity Event Subscription
-Subscribe to host activity events (e.g. page views, clicks, purchases) pushed from the host application.
+Subscribe to activity events (e.g. page views, clicks, purchases) pushed from the host via the framework.
 - **Permission required:** \`events:activity\`
 - **Manifest events array:** Declare specific events to listen for (e.g. \`["activity:product_view", "activity:add_to_cart"]\`) \u2014 manifest uses fully-qualified strings
 - **Hook:** \`useActivityEvent(eventType, handler)\` \u2014 \`ActivityEventHandler\` type exported for use with \`useCallback\`
@@ -684,7 +719,7 @@ ${HOOK_SNIPPETS["events:activity"]}
 **Generic alternative:** \`useEvent('activity:product_view', handler)\` \u2014 a cross-domain hook that accepts fully-qualified event types. Domain wildcard (e.g., \`'activity'\`) receives all events in that domain.
 
 ## extend:identity \u2014 Identity Claim Enrichment
-Enrich identity JWT claims before signing. The host sends base claims to your extension, and you return additional claims to merge into the token.
+Enrich identity JWT claims before signing. The framework sends base claims to your extension, and you return additional claims to merge into the token.
 - **Permission required:** \`extend:identity\`
 - **Hook:** \`useExtendIdentity(handler)\` \u2014 \`ExtendIdentityHandler\` type exported for use with \`useCallback\`
 - **Handler signature:** \`(claims: IdentityBaseClaims) => Record<string, unknown> | Promise<Record<string, unknown>>\`
@@ -1089,7 +1124,7 @@ const appStore = createStore<AppState>({ viewState: { type: 'menu' } })
 - \`subscribe(listener: (state: T) => void): () => void\` \u2014 subscribe, returns unsubscribe fn
 
 ## useIdentityEvent(eventType, handler)
-Subscribe to identity events pushed from the host. Requires \`events:identity\` permission and matching entries in manifest \`events\` array.
+Subscribe to identity events pushed from the host via the framework. Requires \`events:identity\` permission and matching entries in manifest \`events\` array.
 - \`eventType: ${identityEventTypes}\`
 - \`handler: (event: IdentityEvent) => void\`
 - \`IdentityEvent: { eventName: IdentityEventType, data: { state: IdentityState, timestamp: string } }\`
@@ -1117,7 +1152,7 @@ ${HOOK_SNIPPETS_MEMOIZED["events:messaging"]}
 \`\`\`
 
 ## useActivityEvent(eventType, handler)
-Subscribe to host activity events. Requires \`events:activity\` permission and matching entries in manifest \`events\` array.
+Subscribe to activity events pushed from the host via the framework. Requires \`events:activity\` permission and matching entries in manifest \`events\` array.
 - \`eventType: ${activityEventTypes} | '*'\` (domain-stripped)
 - \`handler: ActivityEventHandler\` \u2014 \`(event: ActivityEvent) => void\`
 - \`ActivityEvent: { eventName: string, data: Record<string, unknown> }\`
@@ -1505,13 +1540,13 @@ These rules must always be followed when writing extension code.
 
 ## Components
 - Use the \`ui.*\` namespace for components (\`<ui.Card>\`, \`<ui.Button>\`) \u2014 don't import components directly
-- Only use the attributes listed in the component reference \u2014 the host rejects unknown attributes
+- Only use the attributes listed in the component reference \u2014 the framework rejects unknown attributes
 - Use \`<ui.ScrollArea>\` for content that may overflow
 
 ## Manifest
 - Always declare permissions in \`manifest.json\` before using capabilities
 - Don't use \`data.fetch\` without adding the domain to \`allowedDomains\` in manifest
-- \`allowedDomains\` must be exact hostnames \u2014 no wildcards, no paths
+- \`allowedDomains\`: prefer exact hostnames. Use \`*.<suffix>\` wildcards only if you need any subdomain; the apex is separate. No paths, no protocols, no mid-string wildcards. Wildcards must use a multi-label suffix (e.g., \`*.example.com\`, not \`*.com\`); TLD patterns such as \`*.co.uk\` may pass format checks but will be rejected at submission
 
 ## Entry Point
 - Don't modify \`index.html\` \u2014 the extension entry point is always \`src/index.tsx\` via \`createExtension\`
@@ -1673,7 +1708,7 @@ var generateSurfaces = () => {
 
 # Surfaces
 
-Surfaces are the UI slots where your extension renders content inside the host application.
+Surfaces are the UI slots where your extension renders content inside the embedding application.
 Each surface maps to a specific layout position and is declared as a React component using
 the \`<Surface>\` wrapper from \`@stackable-labs/sdk-extension-react\`.
 
@@ -1710,15 +1745,15 @@ ${EXAMPLE_SNIPPETS.bootstrap}
 \`\`\`
 
 \`createExtension\` bootstraps the extension runtime \u2014 it handles the sandboxed iframe
-communication, capability injection, and surface registration with the host.
+communication, capability injection, and surface registration with the framework.
 
 ## Surface Lifecycle
 
-1. **Mount** \u2014 Host creates an iframe for the extension and loads the entry point
+1. **Mount** \u2014 The framework creates an iframe for the extension and loads the entry point
 2. **Register** \u2014 \`createExtension\` scans the rendered tree for \`<Surface>\` components
-3. **Render** \u2014 Each \`<Surface>\` renders its children into the matching host slot
+3. **Render** \u2014 Each \`<Surface>\` renders its children into the matching slot in the embedding application
 4. **Update** \u2014 Surfaces re-render when props, state, or context data changes
-5. **Unmount** \u2014 Host removes the extension iframe when no longer needed
+5. **Unmount** \u2014 The framework removes the extension iframe when no longer needed
 
 ## Multi-Surface State
 
@@ -1748,31 +1783,32 @@ export const Header = () => {
 `;
 };
 var DLX = "pnpm --config.dlx-cache-max-age=0 dlx";
+var CLI_PKG = "@stackable-labs/cli-app-extension@latest";
 var CLI = {
   /** Scaffold a new extension project */
-  create: (name = "<extension-name>") => `${DLX} @stackable-labs/create-extension ${name}`,
+  create: (name = "<extension-name>") => `${DLX} ${CLI_PKG} create ${name}`,
   /** Start dev servers with hot reload */
-  dev: `${DLX} @stackable-labs/cli-app-extension@latest dev`,
+  dev: `${DLX} ${CLI_PKG} dev`,
   /** Deploy the extension (future) */
-  deploy: `${DLX} @stackable-labs/cli-app-extension@latest deploy`,
+  deploy: `${DLX} ${CLI_PKG} deploy`,
   /** Validate the extension for common errors (coming soon) */
-  validate: `${DLX} @stackable-labs/cli-app-extension@latest validate`,
+  validate: `${DLX} ${CLI_PKG} validate`,
   /** Scaffold from an existing extension */
-  scaffold: `${DLX} @stackable-labs/cli-app-extension@latest scaffold`,
+  scaffold: `${DLX} ${CLI_PKG} scaffold`,
   /** Update an existing extension */
-  update: `${DLX} @stackable-labs/cli-app-extension@latest update`,
+  update: `${DLX} ${CLI_PKG} update`,
   /** Manage CLI authentication (browser-based OAuth) */
   auth: {
-    login: `${DLX} @stackable-labs/cli-app-extension@latest auth login`,
-    logout: `${DLX} @stackable-labs/cli-app-extension@latest auth logout`,
-    status: `${DLX} @stackable-labs/cli-app-extension@latest auth status`
+    login: `${DLX} ${CLI_PKG} auth login`,
+    logout: `${DLX} ${CLI_PKG} auth logout`,
+    status: `${DLX} ${CLI_PKG} auth status`
   },
   /** AI editor configuration tools (Skills + MCP) */
   ai: {
     /** Download AI editor config files (Stackable Skills) into your project */
-    scaffold: `${DLX} @stackable-labs/cli-app-extension@latest ai scaffold`,
+    scaffold: `${DLX} ${CLI_PKG} ai scaffold`,
     /** Add Stackable MCP server config to your project */
-    mcp: `${DLX} @stackable-labs/cli-app-extension@latest ai mcp`
+    mcp: `${DLX} ${CLI_PKG} ai mcp`
   }
 };
 var TEMPLATE_FLAVOR_META = {
@@ -1811,7 +1847,7 @@ Stackable supports two authoring paths. Both produce the same kind of extension
 | **Version control** | Auto-saved to cloud | Git-based |
 | **Deployment** | Link to extension + deploy | CLI deploy command |
 
-Both produce the same output \u2014 a Stackable extension that runs in the host application via the same Remote DOM pipeline. **This guide covers the [CLI](/docs/reference/cli-reference) path.** For Studio, see [AI Extension Studio](/docs/reference/extension-studio).
+Both produce the same output \u2014 a Stackable extension that runs inside the embedding application via the same Remote DOM pipeline. **This guide covers the [CLI](/docs/reference/cli-reference) path.** For Studio, see [AI Extension Studio](/docs/reference/extension-studio).
 
 ## Prerequisites
 
@@ -1851,7 +1887,7 @@ The dev command:
 2. Creates a public Cloudflare tunnel to your local server
 3. Displays a **query parameter** you can use to preview your extension
 
-### Testing against your host app
+### Testing against your extension
 
 The CLI outputs a query param like:
 
@@ -1859,16 +1895,17 @@ The CLI outputs a query param like:
 ?_stackable_dev=ext-123%3Ahttps%3A%2F%2Fabc.trycloudflare.com
 \`\`\`
 
-Copy this and **append it to your host application URL** to load your local extension
-instead of the production bundle. For example:
+Copy this and **append it to the host site's URL** (the site or product where your
+extension is installed/authorized) to load your local extension instead of the
+production bundle. For example:
 
 \`\`\`
-https://your-app.com/dashboard?_stackable_dev=ext-123%3Ahttps%3A%2F%2Fabc.trycloudflare.com
+https://your-host-site.com/dashboard?_stackable_dev=ext-123%3Ahttps%3A%2F%2Fabc.trycloudflare.com
 \`\`\`
 
 This override is **browser-session only** \u2014 no database changes, no shared state.
 Each developer gets isolated overrides. Changes you make locally appear immediately
-in the host app via hot reload.
+in your extension via hot reload.
 
 Use \`--no-tunnel\` if you only want to run the local Vite dev server without a tunnel.
 
@@ -2040,9 +2077,9 @@ ${CLI.dev}
 1. Reads \`.env.stackable\` for cached App/Extension context (prompts if missing)
 2. Creates Cloudflare tunnels for the extension dev server
 3. Starts Vite dev servers with hot reload
-4. Displays a \`_stackable_dev\` query param to append to your host app URL
+4. Displays a \`_stackable_dev\` query param to append to a host site's URL
 
-### Host App Override
+### Host-Site Override
 
 The CLI outputs a query param like:
 
@@ -2050,9 +2087,10 @@ The CLI outputs a query param like:
 ?_stackable_dev=ext-123%3Ahttps%3A%2F%2Fabc.trycloudflare.com
 \`\`\`
 
-Append this to your deployed host app URL to load your local extension instead
-of the production bundle. The override is browser-session only \u2014 no DB changes,
-no shared state. Each developer gets isolated overrides.
+Append this to your deployed host site's URL (the site or product where your
+extension is installed/authorized) to load your local extension instead of the production
+bundle. The override is browser-session only \u2014 no DB changes, no shared state.
+Each developer gets isolated overrides.
 
 ## validate *(coming soon)*
 
@@ -2194,7 +2232,7 @@ var generateExternalApis = () => {
   const fm = frontmatter({
     root: false,
     targets: ["*"],
-    description: "Direct HTTP requests via data.fetch, allowedDomains configuration, and API wrapper patterns",
+    description: "Direct HTTP requests via data.fetch, allowedDomains configuration, wildcard domains, and API wrapper patterns",
     globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts", "packages/extension/public/manifest.json"]
   });
   return `${fm}
@@ -2202,7 +2240,7 @@ var generateExternalApis = () => {
 # External APIs
 
 Extensions can make direct HTTP requests to external services using the \`data.fetch\`
-capability. All requests are proxied through the host for security \u2014 the extension
+capability. All requests are proxied through the framework for security \u2014 the extension
 never makes raw network calls from the sandbox.
 
 ## Setup
@@ -2223,14 +2261,75 @@ Every domain your extension calls must be listed in \`allowedDomains\`:
 
 \`\`\`json
 {
-  "allowedDomains": ["api.example.com", "graphql.example.com"]
+  "allowedDomains": ["api.example.com", "graphql.example.com", "*.myshopify.com"]
 }
 \`\`\`
 
 **Rules:**
-- Exact hostnames only \u2014 no wildcards, no paths, no protocols
-- The host rejects requests to unlisted domains
-- Add each subdomain separately (e.g., \`api.example.com\` and \`cdn.example.com\`)
+- Exact hostnames or \`*.<suffix>\` wildcards (subdomain match) \u2014 no paths, no protocols
+- Wildcards take the form \`*.<suffix>\` and must use a multi-label suffix (e.g., \`*.example.com\`, not \`*.com\`)
+- The framework will reject requests to unlisted domains
+- Add each subdomain separately when listing exact hosts (e.g., \`api.example.com\` and \`cdn.example.com\`)
+
+### Wildcards
+
+**Prefer exact hostnames where possible.** Use \`*.example.com\` only when you
+need to match any subdomain \u2014 for example, tenant-per-subdomain platforms
+(Shopify shops, Salesforce subdomains, Zendesk subdomains, multi-region API hosts) where
+you don't know the full set of hostnames at authoring time or will differ by instance.
+
+\`\`\`json
+{
+  "allowedDomains": ["*.myshopify.com"]
+}
+\`\`\`
+
+With this entry, the framework allows requests to \`acme.myshopify.com\`,
+\`widgets.myshopify.com\`, and any subdomain at any depth (e.g.,
+\`shop.eu.myshopify.com\`). A request to \`evil.com\` is still rejected.
+
+**Apex is separate.** \`*.myshopify.com\` does **not** match \`myshopify.com\`
+itself \u2014 this matches CORS, TLS-certificate, and DNS-wildcard convention. To
+allow both the apex and any subdomain, list both:
+
+\`\`\`json
+{
+  "allowedDomains": ["myshopify.com", "*.myshopify.com"]
+}
+\`\`\`
+
+**Worked example:**
+
+\`\`\`json
+{
+  "allowedDomains": [
+    "*.myshopify.com",
+    "myshopify.com",
+    "api.example.com",
+    "*.staging.example.com"
+  ]
+}
+\`\`\`
+
+This allows any customer shop subdomain, the Shopify apex, an exact API host,
+and any subdomain (at any depth) under \`staging.example.com\`.
+
+**What's rejected and where.** Wildcards must use a multi-label suffix
+(e.g., \`*.example.com\`, not \`*.com\`). Two layers enforce this:
+
+- *Format-level* (instant feedback in the CLI, MCP, and Studio AI panel) \u2014
+  \`*\` alone, multiple wildcards, mid-string wildcards (\`api-*.example.com\`),
+  single-label suffixes (\`*.com\`, \`*.localhost\`, \`*.io\`), protocols
+  (\`https://...\`), paths, ports, and IP literals.
+- *Server-level* (at submission) \u2014 TLD patterns such as \`*.co.uk\`,
+  \`*.com.au\`, and \`*.github.io\` may pass the format check but will be
+  rejected at submission, since they would otherwise allow any registrant
+  under a shared registry.
+
+**Local development.** Exact \`localhost\` and IPv4 literals (\`127.0.0.1\`) are
+still valid for exact-host entries. Dev/staging extension modes bypass the
+domain check entirely, so wildcards aren't needed for local iteration \u2014 they
+matter at submission and in production.
 
 ### 3. Make Requests
 
@@ -2317,10 +2416,10 @@ const customer = await fetchCustomer(capabilities, customerId)
 
 | | data.fetch | data.query |
 |--|-----------|-----------|
-| **Who handles the request** | Extension (via proxy) | Host application |
+| **Who handles the request** | Extension (via proxy) | Platform |
 | **Permission** | \`data:fetch\` | \`data:query\` |
 | **Domain config** | Required (\`allowedDomains\`) | Not needed |
-| **Use when** | Calling external APIs directly | Host provides the API integration |
+| **Use when** | Calling external APIs directly | Platform provides the API integration |
 
 ## Error Handling
 
@@ -2379,7 +2478,7 @@ AI-powered smart insertion to place the component in the correct location.
 
 ### Surfaces
 
-Lists the surface targets available for your app (e.g., \`slot.header\`,
+Lists the surface targets available for your extension (e.g., \`slot.header\`,
 \`slot.content\`, \`slot.footer\`). Surfaces already present in your code are
 filtered out. Clicking a surface adds it to your manifest and inserts a
 \`<Surface>\` block via AI smart insertion.
@@ -2448,7 +2547,7 @@ Studio toolbar.
 
 Comparing approaches? See [Choosing your path](/docs/guides/quick-start#choosing-your-path) in the Quick Start guide for the full Studio vs CLI comparison.
 
-Both workflows produce the same output \u2014 a Stackable extension that runs in the host application via the same Remote DOM pipeline. Start in Studio to prototype, then scaffold to CLI when you need the full development workflow.
+Both workflows produce the same output \u2014 a Stackable extension that runs inside the embedding application via the same Remote DOM pipeline. Start in Studio to prototype, then scaffold to CLI when you need the full development workflow.
 `;
 };
 
@@ -2599,7 +2698,7 @@ my-extension/
 
 ### manifest.json
 
-The extension manifest declares what the extension needs from the host:
+The extension manifest declares what the extension needs from the framework:
 
 \`\`\`json
 {
@@ -2617,7 +2716,11 @@ The extension manifest declares what the extension needs from the host:
 | \`version\` | Semver version string |
 | \`targets\` | Surface slots the extension renders into |
 | \`permissions\` | Capabilities the extension uses |
-| \`allowedDomains\` | Hostnames for data.fetch requests (exact match, no wildcards) |
+| \`allowedDomains\` | Hostnames for data.fetch requests (exact hostnames or \`*.<suffix>\` wildcards) |
+
+See **External APIs > Wildcards** for the full \`allowedDomains\` rules,
+including the apex-vs-subdomain distinction and what's rejected at format
+vs. submission time.
 
 ### index.tsx \u2014 Entry Point
 
@@ -2628,9 +2731,9 @@ ${EXAMPLE_SNIPPETS.bootstrap}
 \`\`\`
 
 \`createExtension\` handles:
-- Sandboxed iframe communication with the host
+- Sandboxed iframe communication with the framework
 - Capability injection (makes \`useCapabilities()\` work)
-- Surface registration (maps \`<Surface id="...">\` to host layout slots)
+- Surface registration (maps \`<Surface id="...">\` to layout slots in the embedding application)
 
 **Do not modify \`index.html\`** \u2014 the extension always bootstraps through \`createExtension\`.
 
@@ -2690,17 +2793,17 @@ var generateStylingAndTheming = () => {
 
 # Styling & Theming
 
-Extensions inherit the host application's theme automatically. The SDK component library
-(\`ui.*\` namespace) renders inside the host's styling context, so colors, fonts, and
-spacing match the host UI without any configuration.
+Extensions inherit the embedding application's theme automatically. The SDK component
+library (\`ui.*\` namespace) renders inside the surrounding application's styling context,
+so colors, fonts, and spacing match without any configuration.
 
-## Host Theme Inheritance
+## Theme Inheritance
 
-The \`ui.*\` components automatically use the host's design tokens:
-- **Colors** \u2014 text, backgrounds, borders adapt to the host's color scheme
-- **Typography** \u2014 font family, sizes, and weights match the host
-- **Spacing** \u2014 padding and margins follow the host's spacing scale
-- **Dark mode** \u2014 components respond to the host's light/dark mode setting
+The \`ui.*\` components automatically use the embedding application's design tokens:
+- **Colors** \u2014 text, backgrounds, borders adapt to the application's color scheme
+- **Typography** \u2014 font family, sizes, and weights match the application
+- **Spacing** \u2014 padding and margins follow the application's spacing scale
+- **Dark mode** \u2014 components respond to the application's light/dark mode setting
 
 No CSS or theme configuration is needed in the extension.
 
@@ -2772,7 +2875,7 @@ Use component props (not CSS) to control visual style:
 
 Extensions run in a sandboxed iframe. These constraints apply:
 
-- **No global CSS** \u2014 styles don't leak between extensions or into the host
+- **No global CSS** \u2014 styles don't leak between extensions or into the embedding application
 - **No \`document\` access** \u2014 cannot inject stylesheets or modify the DOM directly
 - **No \`window.location\`** \u2014 cannot read or modify the URL
 - **Component-only styling** \u2014 use \`className\` on \`ui.*\` components, not raw HTML elements
@@ -2780,7 +2883,7 @@ Extensions run in a sandboxed iframe. These constraints apply:
 
 ## Responsive Design
 
-Extensions render in a constrained viewport (the host's sidebar or panel). Design for
+Extensions render in a constrained viewport (the embedding application's sidebar or panel). Design for
 narrow widths:
 
 \`\`\`tsx
@@ -2797,7 +2900,7 @@ narrow widths:
 - Assume a **narrow viewport** (~300-400px wide)
 - Use \`<ui.ScrollArea>\` for long lists or content
 - Avoid horizontal scrolling \u2014 stack elements vertically
-- Test at the minimum panel width the host supports
+- Test at the minimum panel width the embedding application supports
 `;
 };
 
@@ -2885,16 +2988,36 @@ var parseSafelist = (css) => {
   return classes;
 };
 var classifyFamily = (cls) => {
-  if (cls.startsWith("dark:hover:text-")) return "Dark \u2014 hover text";
-  if (cls.startsWith("dark:hover:bg-")) return "Dark \u2014 hover background";
-  if (cls.startsWith("dark:text-")) return "Dark \u2014 text color";
-  if (cls.startsWith("dark:bg-")) return "Dark \u2014 background color";
-  if (cls.startsWith("dark:border-")) return "Dark \u2014 border color";
-  if (cls.startsWith("hover:opacity-")) return "Hover \u2014 opacity";
-  if (cls.startsWith("hover:text-")) return "Hover \u2014 text color";
-  if (cls.startsWith("hover:bg-")) return "Hover \u2014 background color";
-  if (cls.startsWith("focus:")) return "Focus";
-  if (cls.startsWith("disabled:")) return "Disabled";
+  if (cls.startsWith("dark:hover:text-")) {
+    return "Dark \u2014 hover text";
+  }
+  if (cls.startsWith("dark:hover:bg-")) {
+    return "Dark \u2014 hover background";
+  }
+  if (cls.startsWith("dark:text-")) {
+    return "Dark \u2014 text color";
+  }
+  if (cls.startsWith("dark:bg-")) {
+    return "Dark \u2014 background color";
+  }
+  if (cls.startsWith("dark:border-")) {
+    return "Dark \u2014 border color";
+  }
+  if (cls.startsWith("hover:opacity-")) {
+    return "Hover \u2014 opacity";
+  }
+  if (cls.startsWith("hover:text-")) {
+    return "Hover \u2014 text color";
+  }
+  if (cls.startsWith("hover:bg-")) {
+    return "Hover \u2014 background color";
+  }
+  if (cls.startsWith("focus:")) {
+    return "Focus";
+  }
+  if (cls.startsWith("disabled:")) {
+    return "Disabled";
+  }
   if (/^(m|mx|my|mt|mb|ml|mr)-/.test(cls)) {
     return "Margin";
   }
@@ -3103,14 +3226,14 @@ Apply them via the \`className\` prop on \`ui.*\` components:
 Always prefer:
 - Component variants (\`<ui.Button variant="primary">\`) over color overrides
 - Layout components (\`<ui.Stack>\`, \`<ui.Inline>\`) over manual flexbox class chains
-- The semantic color tokens (\`text-foreground\`, \`bg-background\`) which adapt to the host theme
+- The semantic color tokens (\`text-foreground\`, \`bg-background\`) which adapt to the embedding application's theme
 
 ## Safelist limits
 
 The safelist is intentionally a fixed list, **NOT the full Tailwind catalog** to provide UI consistency and reduce bundle size. Anything beyond what is listed below will be missing from the platform stylesheet at runtime \u2014 the class will appear in your DOM but the corresponding CSS rule will not exist, and the style will silently no-op. In particular:
 
 - **Arbitrary values are NOT supported** in general (e.g. \`w-[123px]\`, \`bg-[#1a1a1a]\`, \`text-[15px]\`). The single exception is \`aspect-[9/16]\` (portrait video). For any other arbitrary value, use the named utility closest to your target.
-- **Off-list color shades** (e.g. \`bg-cyan-500\`, \`text-rose-500\`) are not pre-emitted. The supported color set below is curated for visual consistency with the host theme.
+- **Off-list color shades** (e.g. \`bg-cyan-500\`, \`text-rose-500\`) are not pre-emitted. The supported color set below is curated for visual consistency with the embedding application's theme.
 - **Off-list ladder values** (e.g. \`mt-32\`, \`text-4xl\`, \`w-128\`) are not pre-emitted. The ladders below cover sizes appropriate for the embedded widget's narrow viewport.
 
 If you need something that's not on this list, file an issue with your use case \u2014 the safelist is curated, not frozen.
@@ -3263,9 +3386,9 @@ Focused examples showing each SDK capability in a working Surface component.
 Each example is self-contained \u2014 copy it into a surface file and add the
 corresponding permission to your \`manifest.json\`.
 
-## context.read \u2014 Reading Host Context
+## context.read \u2014 Reading Platform Context
 
-Read customer and session data provided by the host. The \`useContextData\`
+Read customer and session data provided by the framework. The \`useContextData\`
 hook handles loading state automatically.
 
 **Permission:** \`context:read\`
@@ -3274,9 +3397,9 @@ hook handles loading state automatically.
 ${EXAMPLE_SNIPPETS["context.read"]}
 \`\`\`
 
-## data.query \u2014 Host-Mediated Requests
+## data.query \u2014 Platform-Mediated Requests
 
-Send structured requests to the host application. The host handles the API
+Send structured requests to the platform. The framework handles the API
 call and returns the result \u2014 no \`allowedDomains\` needed.
 
 **Permission:** \`data:query\`
@@ -3288,7 +3411,8 @@ ${EXAMPLE_SNIPPETS["data.query"]}
 ## data.fetch \u2014 Direct HTTP Requests
 
 Make HTTP requests directly from the extension sandbox. The domain must be
-listed in \`allowedDomains\` in your manifest.
+listed in \`allowedDomains\` in your manifest \u2014 exact hostnames or
+\`*.<suffix>\` wildcards. See **External APIs > Wildcards** for the full rules.
 
 **Permission:** \`data:fetch\`
 
@@ -3298,7 +3422,7 @@ ${EXAMPLE_SNIPPETS["data.fetch"]}
 
 ## actions.toast \u2014 Toast Notifications
 
-Display toast notifications in the host UI to provide feedback to users.
+Display toast notifications in the host widget's UI to provide feedback to users.
 
 **Permission:** \`actions:toast\`
 
@@ -3335,7 +3459,7 @@ surfaces, store-based navigation, and loading states.
 ## Bootstrap \u2014 Entry Point
 
 Set up your extension entry point in \`src/index.tsx\`. The \`createExtension\` factory
-bootstraps the sandboxed runtime and registers all surfaces with the host.
+bootstraps the sandboxed runtime and registers all surfaces with the framework.
 
 \`\`\`tsx
 ${EXAMPLE_SNIPPETS.bootstrap}
@@ -3343,7 +3467,7 @@ ${EXAMPLE_SNIPPETS.bootstrap}
 
 ## Surfaces \u2014 Declaring UI Slots
 
-Each surface renders into a specific layout slot in the host application.
+Each surface renders into a specific layout slot in the embedding application.
 The \`id\` prop must match a target declared in your \`manifest.json\`.
 
 ### Header
@@ -3412,7 +3536,7 @@ var generateCookbookEvents = () => {
 
 # Events & Extensions
 
-Subscribe to real-time events pushed from the host and extend identity claims.
+Subscribe to real-time events pushed from the host via the framework, and extend identity claims.
 Each event type has a dedicated hook \u2014 never use \`capabilities.events.*\` directly.
 
 ## Identity Events
@@ -3456,9 +3580,9 @@ ${EXAMPLE_SNIPPETS["events:messaging"]}
 
 ## Activity Events
 
-Subscribe to host activity events like page views, clicks, and purchases.
-Activity event names are domain-stripped \u2014 use \`useActivityEvent('product_view', ...)\`
-not \`'activity:product_view'\`.
+Subscribe to host site activity events like page views, clicks, and purchases pushed from
+the host via the framework. Activity event names are domain-stripped \u2014
+use \`useActivityEvent('product_view', ...)\` not \`'activity:product_view'\`.
 
 **Permission:** \`events:activity\`
 **Well-known events:** ${activityEventTypes2}
@@ -4769,12 +4893,6 @@ pair(EXAMPLE_SNIPPETS, EXAMPLE_SNIPPETS2);
 pair(CAPABILITY_SNIPPETS, CAPABILITY_SNIPPETS2);
 pair(EVENT_SNIPPETS, EVENT_SNIPPETS2);
 
-// ../../lib/contracts/src/custom.ts
-var CUSTOM_ROLE = {
-  SUPER_ADMIN: "super_admin"
-};
-new Set(Object.values(CUSTOM_ROLE));
-
 // ../../lib/utils-js/src/crypto.ts
 var getCrypto = () => {
   if (typeof globalThis !== "undefined" && globalThis.crypto) {
@@ -5005,13 +5123,21 @@ var createMcpServer = (options = {}) => {
     }
     if (!Array.isArray(manifest.allowedDomains)) {
       errors.push('Missing "allowedDomains" array. Use an empty array if no external API calls are needed.');
+    } else {
+      for (let i = 0; i < manifest.allowedDomains.length; i++) {
+        const entry = manifest.allowedDomains[i];
+        const reason = validatePatternFormat(entry);
+        if (reason) {
+          errors.push(`allowedDomains[${i}] "${String(entry)}": ${reason}`);
+        }
+      }
     }
     const permissions = manifest.permissions ?? [];
     if (permissions.includes("data:fetch") && Array.isArray(manifest.allowedDomains) && manifest.allowedDomains.length === 0) {
       errors.push('"data:fetch" permission declared but "allowedDomains" is empty. Add the domains your extension needs to fetch from.');
     }
     if (errors.length === 0) {
-      return textContent("Manifest is valid.");
+      return textContent("Manifest is valid. Note: server will additionally validate wildcard suffixes against the public suffix list at submission time.");
     }
     return errorContent(`Manifest validation failed:
 ${errors.map((e) => `- ${e}`).join("\n")}`);