@syntrologie/runtime-sdk 2.8.0-canary.183 → 2.8.0-canary.185

package/CAPABILITIES.md

@@ -1,1450 +0,0 @@
-# SmartCanvas SDK Capabilities
-
-This document describes all available operations and capabilities of the SmartCanvas SDK for DOM manipulation, interventions, and UI rendering.
-
-> **Auto-generated**: This file is assembled from individual adaptive package capabilities during build.
-
-## Table of Contents
-- [Overview](#overview)
-- [Quick Start Example](#quick-start-example)
-- [Adaptive Packages](#adaptive-packages)
-- [Surfaces](#surfaces)
-- [Anchor Resolution](#anchor-resolution)
-- [Route Scoping](#route-scoping)
-- [Decision Strategies](#decision-strategies)
-- [Best Practices](#best-practices)
-
----
-
-## Overview
-
-The SmartCanvas SDK provides three main systems for modifying web pages:
-
-1. **ActionEngine** - Unified execution layer for interventions (highlight, tooltip, badge, DOM modifications)
-2. **Surfaces** - Managed surface system for rendering UI into named slots
-3. **Runtime** - Context, events, state, and decision management
-
-All modifications are reversible and publish events to the EventBus for tracking.
-
----
-
-## Quick Start Example
-
-### Simple Header Text Change
-
-Change a page header when the element is visible:
-
-```json
-{
-  "id": "welcome-header-change",
-  "activation": {
-    "routes": { "include": ["/", "/home"] },
-    "strategy": {
-      "type": "rules",
-      "rules": [
-        {
-          "conditions": [
-            { "type": "anchor_visible", "anchorId": "h1.hero-title", "state": "visible" }
-          ],
-          "value": true
-        }
-      ],
-      "default": false
-    }
-  },
-  "actions": [
-    {
-      "kind": "content:setText",
-      "anchorId": { "selector": "h1.hero-title", "route": "/" },
-      "text": "Welcome to Our New Experience"
-    }
-  ]
-}
-```
-
----
-
-## Adaptive Packages
-
-The SDK includes the following adaptive packages, each providing specific capabilities:
-
-- [@syntrologie/adapt-content](#syntrologieadapt-content)
-- [@syntrologie/adapt-faq](#syntrologieadapt-faq)
-- [@syntrologie/adapt-gamification](#syntrologieadapt-gamification)
-- [@syntrologie/adapt-mcp](#syntrologieadapt-mcp)
-- [@syntrologie/adapt-nav](#syntrologieadapt-nav)
-- [@syntrologie/adapt-overlays](#syntrologieadapt-overlays)
-- [@syntrologie/adapt-viz](#syntrologieadapt-viz)
-
----
-
-# @syntrologie/adapt-content
-
-DOM content modification capabilities for text, attributes, styles, HTML, and classes.
-
-## When to use
-
-| Goal | Action |
-|------|--------|
-| Replace an element's text | `content:setText` |
-| Change an HTML attribute (href, src, data-*) | `content:setAttr` |
-| Modify inline styles (color, size, spacing) | `content:setStyle` |
-| Inject new HTML before/after/inside an element | `content:insertHtml` |
-| Add a CSS class (show/hide, animate) | `content:addClass` |
-| Remove a CSS class | `content:removeClass` |
-
-## Actions
-
-### content:setText
-
-Replaces the text content of an element.
-
-| Property   | Type                | Required | Description      |
-| ---------- | ------------------- | -------- | ---------------- |
-| `kind`     | `"content:setText"` | Yes      | Action type      |
-| `anchorId` | object              | Yes      | `{ selector, route }` |
-| `text`     | string              | Yes      | New text content |
-
-```json
-{
-  "kind": "content:setText",
-  "anchorId": { "selector": "h1.hero-title", "route": "/" },
-  "text": "Start Your Free Trial Today"
-}
-```
-
-### content:setAttr
-
-Sets an HTML attribute on an element.
-
-| Property   | Type                | Required | Description      |
-| ---------- | ------------------- | -------- | ---------------- |
-| `kind`     | `"content:setAttr"` | Yes      | Action type      |
-| `anchorId` | object              | Yes      | `{ selector, route }` |
-| `attr`     | string              | Yes      | Attribute name   |
-| `value`    | string              | Yes      | Attribute value  |
-
-**Blocked attributes:** Event handlers (`onclick`, `onerror`, etc.) are not allowed.
-
-```json
-{
-  "kind": "content:setAttr",
-  "anchorId": { "selector": "#signup-form", "route": "/" },
-  "attr": "data-experiment",
-  "value": "signup-v2"
-}
-```
-
-### content:setStyle
-
-Sets inline CSS styles on an element.
-
-| Property   | Type                 | Required | Description              |
-| ---------- | -------------------- | -------- | ------------------------ |
-| `kind`     | `"content:setStyle"` | Yes      | Action type              |
-| `anchorId` | object               | Yes      | `{ selector, route }` |
-| `styles`   | object               | Yes      | CSS property/value pairs |
-
-```json
-{
-  "kind": "content:setStyle",
-  "anchorId": { "selector": ".hero-section", "route": "/" },
-  "styles": {
-    "background-color": "#1e40af",
-    "padding": "2rem"
-  }
-}
-```
-
-### content:insertHtml
-
-Inserts HTML content relative to an element.
-
-| Property   | Type                  | Required | Description                                                 |
-| ---------- | --------------------- | -------- | ----------------------------------------------------------- |
-| `kind`     | `"content:insertHtml"` | Yes      | Action type                                                 |
-| `anchorId` | object                | Yes      | `{ selector, route }` |
-| `html`     | string                | Yes      | HTML content (sanitized)                                    |
-| `position` | string                | Yes      | `"before"`, `"after"`, `"prepend"`, `"append"`, `"replace"` |
-| `deepLink` | object                | No       | Makes the entire inserted element clickable to open the canvas panel and navigate to a specific tile |
-
-**Positions:**
-
-- `before` - Insert before the element
-- `after` - Insert after the element
-- `prepend` - Insert inside, before first child
-- `append` - Insert inside, after last child
-- `replace` - Replace the entire element
-
-```json
-{
-  "kind": "content:insertHtml",
-  "anchorId": { "selector": ".cta-button", "route": "/" },
-  "html": "<span class=\"badge\">NEW</span>",
-  "position": "append"
-}
-```
-
-**Deep-linking to canvas tiles:**
-
-Use `deepLink` to make inserted content open the canvas panel and navigate to a specific tile when clicked. This is the correct way to connect inserted buttons/links to canvas tiles — do NOT use `onclick` handlers with `window.SynOS`.
-
-| Property         | Type   | Required | Description                        |
-| ---------------- | ------ | -------- | ---------------------------------- |
-| `deepLink.tileId` | string | Yes      | ID of the tile to open             |
-| `deepLink.itemId` | string | No       | Specific item within the tile      |
-
-```json
-{
-  "kind": "content:insertHtml",
-  "anchorId": { "selector": "[data-id='pricing-heading']", "route": "/" },
-  "html": "<button style='background: #4a90e2; color: white; border: none; padding: 8px 16px; border-radius: 20px; cursor: pointer;'>Help Me Choose</button>",
-  "position": "after",
-  "deepLink": { "tileId": "plan_selector_faq" }
-}
-```
-
-The SDK automatically handles opening the canvas, setting the cursor to pointer, and publishing a `notification.deep_link` event. The click handler is wired up and cleaned up by the SDK — no JavaScript in the HTML is needed.
-
-### content:addClass
-
-Adds a CSS class to an element.
-
-| Property    | Type                 | Required | Description       |
-| ----------- | -------------------- | -------- | ----------------- |
-| `kind`      | `"content:addClass"` | Yes      | Action type       |
-| `anchorId`  | object               | Yes      | `{ selector, route }` |
-| `className` | string               | Yes      | Class name to add |
-
-```json
-{
-  "kind": "content:addClass",
-  "anchorId": { "selector": ".pricing-card", "route": "/pricing" },
-  "className": "highlighted"
-}
-```
-
-### content:removeClass
-
-Removes a CSS class from an element.
-
-| Property    | Type                    | Required | Description          |
-| ----------- | ----------------------- | -------- | -------------------- |
-| `kind`      | `"content:removeClass"` | Yes      | Action type          |
-| `anchorId`  | object                  | Yes      | `{ selector, route }` |
-| `className` | string                  | Yes      | Class name to remove |
-
-```json
-{
-  "kind": "content:removeClass",
-  "anchorId": { "selector": ".pricing-card", "route": "/pricing" },
-  "className": "hidden"
-}
-```
-
-
----
-
-# @syntrologie/adapt-faq
-
-Collapsible Q&A accordion with actions, rich content, feedback, and personalization.
-
-## When to use
-
-| Goal | Action |
-|------|--------|
-| Add an FAQ accordion widget | Add a **tile** in `tiles[]` with `widget: "adaptive-faq:accordion"` |
-| Scroll to and expand a specific FAQ item | `faq:scroll_to` |
-| Open, close, or toggle a FAQ item | `faq:toggle_item` |
-| Add, remove, reorder, or replace FAQ items | `faq:update` |
-
-## Mounting an FAQ Widget
-
-FAQ widgets are mounted via **tiles** (not actions). Add an entry to the `tiles[]` array in the config:
-
-```json
-{
-  "tiles": [
-    {
-      "id": "my-faq",
-      "title": "Frequently Asked Questions",
-      "content": {
-        "type": "custom",
-        "component": "adaptive-faq:accordion",
-        "props": {
-          "expandBehavior": "single",
-          "searchable": true,
-          "items": [ ... ]
-        }
-      }
-    }
-  ]
-}
-```
-
-### Tile Props
-
-| Property                | Type                              | Required | Description                                                         |
-| ----------------------- | --------------------------------- | -------- | ------------------------------------------------------------------- |
-| `expandBehavior`        | `"single"` \| `"multiple"`        | No       | Whether one or many items can be open at once (default: `"single"`) |
-| `searchable`            | boolean                           | No       | Show a search/filter input (default: `false`)                       |
-| `theme`                 | `"light"` \| `"dark"` \| `"auto"` | No       | Color theme (default: `"auto"`)                                     |
-| `items`                 | array                             | Yes      | FAQ items (see below)                                               |
-| `feedback`              | boolean \| FeedbackConfig         | No       | Enable per-item feedback widget                                     |
-| `ordering`              | OrderingStrategy                  | No       | Item ordering strategy (default: `"static"`)                        |
-| `injections`            | InjectionRule[]                   | No       | Dynamic item injection rules                                        |
-
-### FAQ Item Schema
-
-Each item in the `items` array:
-
-| Property                | Type                     | Required | Description                                     |
-| ----------------------- | ------------------------ | -------- | ----------------------------------------------- |
-| `kind`                  | `"faq:question"`         | Yes      | Compositional action type                       |
-| `config.id`             | string                   | Yes      | Unique identifier for this question             |
-| `config.question`       | string                   | Yes      | The question text                               |
-| `config.answer`         | FAQAnswer                | Yes      | Answer content (string, rich HTML, or markdown) |
-| `config.category`       | string                   | No       | Category for grouping items                     |
-| `config.priority`       | number                   | No       | Priority weight for ordering                    |
-| `config.answerStrategy` | AnswerStrategy           | No       | AI-generated answer configuration               |
-| `triggerWhen`              | DecisionStrategy \| null | No       | Conditional visibility strategy                 |
-
-**Full tile example with FAQ items:**
-
-```json
-{
-  "tiles": [
-    {
-      "id": "help-faq",
-      "title": "Frequently Asked Questions",
-      "content": {
-        "type": "custom",
-        "component": "adaptive-faq:accordion",
-        "props": {
-          "expandBehavior": "single",
-          "searchable": true,
-          "feedback": {
-            "style": "thumbs",
-            "prompt": "Was this helpful?"
-          },
-          "ordering": "priority",
-          "items": [
-            {
-              "kind": "faq:question",
-              "config": {
-                "id": "getting-started",
-                "question": "How do I get started?",
-                "answer": "Sign up for a free account and follow our quickstart guide.",
-                "category": "General",
-                "priority": 10
-              }
-            },
-            {
-              "kind": "faq:question",
-              "config": {
-                "id": "payment-methods",
-                "question": "What payment methods do you accept?",
-                "answer": "We accept all major credit cards and PayPal.",
-                "category": "Billing",
-                "priority": 5
-              }
-            }
-          ]
-        }
-      }
-    }
-  ]
-}
-```
-
-### faq:scroll_to
-
-Scrolls the viewport to a specific FAQ item and optionally expands it.
-
-| Property       | Type              | Required | Default    | Description                                |
-| -------------- | ----------------- | -------- | ---------- | ------------------------------------------ |
-| `kind`         | `"faq:scroll_to"` | Yes      |            | Action type                                |
-| `itemId`       | string            | No\*     |            | Target item ID                             |
-| `itemQuestion` | string            | No\*     |            | Target item question text (fuzzy match)    |
-| `expand`       | boolean           | No       | `true`     | Whether to expand the item after scrolling |
-| `behavior`     | string            | No       | `"smooth"` | `"smooth"`, `"instant"`, `"auto"`          |
-
-\* Either `itemId` or `itemQuestion` is required.
-
-```json
-{
-  "kind": "faq:scroll_to",
-  "itemId": "payment-methods",
-  "expand": true,
-  "behavior": "smooth"
-}
-```
-
-### faq:toggle_item
-
-Opens, closes, or toggles a FAQ item's expanded state.
-
-| Property       | Type                | Required | Default    | Description                             |
-| -------------- | ------------------- | -------- | ---------- | --------------------------------------- |
-| `kind`         | `"faq:toggle_item"` | Yes      |            | Action type                             |
-| `itemId`       | string              | No\*     |            | Target item ID                          |
-| `itemQuestion` | string              | No\*     |            | Target item question text (fuzzy match) |
-| `state`        | string              | No       | `"toggle"` | `"open"`, `"closed"`, `"toggle"`        |
-
-\* Either `itemId` or `itemQuestion` is required.
-
-```json
-{
-  "kind": "faq:toggle_item",
-  "itemId": "getting-started",
-  "state": "open"
-}
-```
-
-### faq:update
-
-Dynamically adds, removes, reorders, or replaces FAQ items at runtime.
-
-| Property    | Type                | Required | Description                                             |
-| ----------- | ------------------- | -------- | ------------------------------------------------------- |
-| `kind`      | `"faq:update"`      | Yes      | Action type                                             |
-| `operation` | string              | Yes      | `"add"`, `"remove"`, `"reorder"`, `"replace"`           |
-| `items`     | FAQQuestionAction[] | No       | Items to add or replace with (required for add/replace) |
-| `itemId`    | string              | No       | Item to remove (required for remove)                    |
-| `order`     | string[]            | No       | Ordered list of item IDs (required for reorder)         |
-| `position`  | string              | No       | `"prepend"`, `"append"`, `"before"`, `"after"`          |
-| `anchorId`  | string              | No       | Reference item for before/after positioning             |
-
-**Add items:**
-
-```json
-{
-  "kind": "faq:update",
-  "operation": "add",
-  "position": "append",
-  "items": [
-    {
-      "kind": "faq:question",
-      "config": {
-        "id": "new-feature",
-        "question": "What is the new feature?",
-        "answer": "Our latest release includes AI-powered recommendations."
-      }
-    }
-  ]
-}
-```
-
-**Remove an item:**
-
-```json
-{
-  "kind": "faq:update",
-  "operation": "remove",
-  "itemId": "outdated-question"
-}
-```
-
-**Reorder items:**
-
-```json
-{
-  "kind": "faq:update",
-  "operation": "reorder",
-  "order": ["getting-started", "new-feature", "payment-methods"]
-}
-```
-
-**Replace all items:**
-
-```json
-{
-  "kind": "faq:update",
-  "operation": "replace",
-  "items": [
-    {
-      "kind": "faq:question",
-      "config": {
-        "id": "only-question",
-        "question": "Is this the only question?",
-        "answer": "Yes, after replacing all items."
-      }
-    }
-  ]
-}
-```
-
-## Compositional Pattern
-
-The FAQ widget uses a **compositional action pattern** where `faq:question` actions serve as configuration data rendered by the widget, rather than being executed by the runtime. This allows:
-
-- **Per-item conditional visibility** via `triggerWhen` strategies -- items can appear or hide based on page URL, user segment, viewport, or any DecisionStrategy condition
-- **Category grouping** -- items with a `category` field are grouped under collapsible section headers
-- **Dynamic injection** -- `injections` rules can add items when trigger conditions are met, supporting contextual FAQ content
-- **Ordering control** -- the `ordering` strategy determines how items are sorted within categories
-
-Items without `triggerWhen` are always visible. Items without `category` appear in an ungrouped section.
-
-## Rich Answer Content
-
-FAQ answers support three content formats via the `FAQAnswer` union type:
-
-- **Plain string** -- simple text, supports basic markdown
-- **Rich HTML** (`{ "type": "rich", "html": "<p>...</p>" }`) -- pre-rendered HTML content
-- **Enhanced markdown** (`{ "type": "markdown", "content": "...", "assets": [...] }`) -- markdown with embedded media assets (images, videos)
-
-```json
-{
-  "config": {
-    "id": "rich-example",
-    "question": "How does the visual editor work?",
-    "answer": {
-      "type": "markdown",
-      "content": "The visual editor lets you create experiments with a point-and-click interface.\n\n![Editor screenshot](asset:editor-screenshot)",
-      "assets": [
-        {
-          "id": "editor-screenshot",
-          "type": "image",
-          "src": "https://cdn.example.com/editor.png",
-          "alt": "Visual editor interface",
-          "width": 800,
-          "height": 450
-        }
-      ]
-    }
-  }
-}
-```
-
-## Feedback
-
-Per-item feedback allows users to rate answer helpfulness. Enable with a boolean or detailed config:
-
-- `"feedback": true` -- enables thumbs up/down with default prompt
-- `"feedback": { "style": "thumbs", "prompt": "Was this helpful?" }` -- thumbs with custom prompt
-- `"feedback": { "style": "rating" }` -- numeric rating scale
-
-Feedback events are published via `context.publishEvent` for analytics integration.
-
-## Personalization
-
-### Ordering Strategies
-
-The `ordering` field controls how FAQ items are sorted:
-
-- **`"static"`** (default) -- items appear in the order defined in the config
-- **`"priority"`** -- items are sorted by their `priority` field (higher values first)
-- **Segment-based** -- items are ordered differently per user segment:
-
-```json
-{
-  "ordering": {
-    "type": "segment",
-    "segmentWeights": {
-      "new_user": ["getting-started", "pricing", "support"],
-      "power_user": ["api-docs", "advanced-config", "integrations"]
-    }
-  }
-}
-```
-
-### Contextual Hints (Companion Tooltips)
-
-FAQ questions can be surfaced proactively on the page using companion overlay tooltips. When a tooltip CTA has an `actionId` matching `faq:open:<questionId>`, clicking it expands the corresponding question in the FAQ widget and scrolls it into view.
-
-This is a convention-based integration — no special FAQ action is needed. Use a standard `overlays:tooltip` action with `ctaButtons`:
-
-```json
-{
-  "kind": "overlays:tooltip",
-  "anchorId": "#complex-feature",
-  "content": {
-    "title": "Need help?",
-    "body": "Check our FAQ for details.",
-    "ctaButtons": [
-      { "label": "View Answer", "actionId": "faq:open:getting-started", "primary": true },
-      { "label": "Dismiss", "actionId": "dismiss" }
-    ]
-  },
-  "trigger": "immediate",
-  "placement": "bottom"
-}
-```
-
-**How it works:**
-
-1. The tooltip CTA click publishes an `action.tooltip_cta_clicked` event via the EventBus
-2. The FAQ widget subscribes to these events and filters for `faq:open:*` actionIds
-3. The matching question expands and scrolls into view
-4. The widget also publishes `canvas.requestOpen` to open the canvas panel if needed
-
-**Late-mount support:** If the FAQ widget mounts after the CTA click (e.g., canvas was closed), it checks the EventBus history for recent `faq:open:*` events (within 10 seconds) and auto-expands the target question on mount.
-
-**`dismiss` actionId:** Destroys the tooltip without publishing an event. Use this for a "close" or "not now" button.
-
-### Dynamic Injection
-
-Injection rules add contextual FAQ items when conditions are met:
-
-```json
-{
-  "injections": [
-    {
-      "trigger": {
-        "type": "rules",
-        "rules": [
-          {
-            "conditions": [{ "type": "page_url", "pattern": "/checkout*" }],
-            "value": true
-          }
-        ],
-        "default": false
-      },
-      "items": [
-        {
-          "kind": "faq:question",
-          "config": {
-            "id": "checkout-help",
-            "question": "Having trouble with checkout?",
-            "answer": "Contact support at help@example.com for immediate assistance."
-          }
-        }
-      ],
-      "position": "prepend",
-      "once": true
-    }
-  ]
-}
-```
-
-- `trigger` -- a DecisionStrategy that evaluates to `true` when injection should occur
-- `items` -- FAQ items to inject
-- `position` -- `"prepend"` or `"append"` relative to existing items
-- `once` -- if `true`, items are injected only on the first trigger match
-
-
----
-
-# @syntrologie/adapt-gamification
-
-Gamification capabilities including badges, points, and leaderboards.
-
-## When to use
-
-| Goal | Action |
-|------|--------|
-| Award a badge to a user | `gamification:awardBadge` |
-| Add points to a user's score | `gamification:addPoints` |
-| Mount a gamification widget (leaderboard, progress) | Add a **tile** with `component: "adaptive-gamification:leaderboard"` |
-
-## Actions
-
-### gamification:awardBadge
-
-Awards a badge to the current user.
-
-| Property | Type                       | Required | Description      |
-| -------- | -------------------------- | -------- | ---------------- |
-| `kind`   | `"gamification:awardBadge"` | Yes      | Action type      |
-| `badgeId` | string                    | Yes      | Badge identifier |
-
-```json
-{
-  "kind": "gamification:awardBadge",
-  "badgeId": "first-purchase"
-}
-```
-
-### gamification:addPoints
-
-Adds points to the current user's score.
-
-| Property | Type                       | Required | Description      |
-| -------- | -------------------------- | -------- | ---------------- |
-| `kind`   | `"gamification:addPoints"` | Yes      | Action type      |
-| `points` | number                     | Yes      | Points to add    |
-
-```json
-{
-  "kind": "gamification:addPoints",
-  "points": 50
-}
-```
-
-### Gamification Widget (via Tile)
-
-Mount gamification UI elements (leaderboard, badge display, progress tracker) via a **tile**:
-
-```json
-{
-  "tiles": [
-    {
-      "id": "gamification",
-      "title": "Your Progress",
-      "content": {
-        "type": "custom",
-        "component": "adaptive-gamification:leaderboard",
-        "props": { ... }
-      }
-    }
-  ]
-}
-```
-
-### Configuration Schema
-
-| Property                      | Type    | Required | Default | Description            |
-| ----------------------------- | ------- | -------- | ------- | ---------------------- |
-| `badges`                      | array   | No       | `[]`    | Badge definitions      |
-| `points.enabled`              | boolean | No       | `false` | Enable points system   |
-| `points.multiplier`           | number  | No       | `1`     | Points multiplier      |
-| `leaderboard.enabled`         | boolean | No       | `false` | Show leaderboard       |
-| `leaderboard.refreshInterval` | number  | No       | `60000` | Refresh interval in ms |
-
-### Badge Schema
-
-| Property             | Type   | Required | Description                   |
-| -------------------- | ------ | -------- | ----------------------------- |
-| `id`                 | string | Yes      | Unique badge identifier       |
-| `name`               | string | Yes      | Display name                  |
-| `icon`               | string | Yes      | Icon identifier               |
-| `description`        | string | No       | Badge description             |
-| `trigger.event`      | string | Yes      | Event that triggers the badge |
-| `trigger.conditions` | array  | No       | Additional conditions         |
-
-```json
-{
-  "tiles": [{
-    "id": "gamification-widget",
-    "title": "Achievements",
-    "content": {
-      "type": "custom",
-      "component": "adaptive-gamification:leaderboard",
-      "props": {
-    "badges": [
-      {
-        "id": "first-purchase",
-        "name": "First Purchase",
-        "icon": "shopping-cart",
-        "description": "Made your first purchase!",
-        "trigger": {
-          "event": "purchase_completed"
-        }
-      }
-    ],
-    "points": {
-      "enabled": true,
-      "multiplier": 2
-    },
-    "leaderboard": {
-      "enabled": true,
-      "refreshInterval": 30000
-    }
-  }
-}
-```
-
-## Use Cases
-
-- **Engagement rewards**: Award badges for completing onboarding steps
-- **Loyalty programs**: Track points for purchases or interactions
-- **Social proof**: Display leaderboards to encourage participation
-- **Progress tracking**: Show achievement progress to motivate users
-
-
----
-
-# @syntrologie/adapt-mcp
-
-Loader adaptive for the MCP Apps protocol.
-
-## What it does today
-
-Nothing observable from tile config. This adaptive is currently a pure loader:
-it pulls [`@modelcontextprotocol/ext-apps`](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps) into the page and exposes its `App`, `AppBridge`,
-and `PostMessageTransport` classes on `window.MCPApp`. No actions, no widgets,
-no surfaces.
-
-## Why it exists separately from `runtime-sdk`
-
-The MCP Apps bridge adds a non-trivial amount of code and a new dep
-(`@modelcontextprotocol/ext-apps`) to any page that includes it. Most Syntro
-deployments don't need it — only pages that want to render interactive MCP-app
-cards do. Splitting it into its own adaptive means the runtime stays lean and
-the bridge code only loads when a tile references it.
-
-This package is deliberately **not** listed in `BUNDLED_APP_IDS` in
-`packages/runtime-sdk/src/apps/AppLoader.ts`, so the AppLoader treats it as a
-CDN-hosted adaptive and fetches it on demand.
-
-## Loading
-
-The `./cdn` entrypoint is the CDN bundle. When it runs in a browser:
-
-1. Imports `App`, `AppBridge`, `PostMessageTransport` from
-   `@modelcontextprotocol/ext-apps/app-bridge`.
-2. Assigns them to `window.MCPApp`.
-3. Calls `window.SynOS.appRegistry.register(manifest)` if the host registry is
-   present.
-
-After this runs, any subsequent page code can use `window.MCPApp.App` to
-construct an MCP App instance without reloading the library.
-
-## Capabilities (none yet)
-
-| Kind | Available? | Notes |
-|------|------------|-------|
-| Actions | — | TBD once bridge requirements are defined. |
-| Widgets | — | TBD. |
-| Surfaces | — | TBD. |
-
-This file gets aggregated into `runtime-sdk/CAPABILITIES.md` during build. When
-actions land here, document them in the normal adaptive format (kind, description,
-params schema, example config).
-
-## Next steps (not in this package yet)
-
-- Canvas/host wiring: instantiate `AppBridge` per rendered MCP-app iframe.
-- Action registry: map `data-action` clicks to `app.callTool(...)` invocations.
-- Per-channel MCP client proxy on the canvas server.
-
-Those live in other PRs once we lock in the full interactivity design.
-
-
----
-
-# @syntrologie/adapt-nav
-
-Navigation tips accordion widget with conditional item visibility and toast notifications.
-
-## When to use
-
-| Goal | Action |
-|------|--------|
-| Scroll to an element on the page | `navigation:scrollTo` |
-| Navigate to a different URL | `navigation:navigate` |
-| Show contextual navigation tips widget | Add a **tile** with `component: "adaptive-nav:tips"` |
-
-## Widget: `adaptive-nav:tips`
-
-Accordion of contextual navigation tips. Each tip has a collapsible header and expanded body with optional CTA link.
-
-### Tile Config
-
-| Property               | Type                              | Required | Default    | Description           |
-| ---------------------- | --------------------------------- | -------- | ---------- | --------------------- |
-| `widget`               | `"adaptive-nav:tips"`             | Yes      |            | Widget identifier     |
-| `props.expandBehavior` | `"single"` \| `"multiple"`        | No       | `"single"` | Accordion expand mode |
-| `props.theme`          | `"light"` \| `"dark"` \| `"auto"` | No       | `"auto"`   | Color theme           |
-| `props.actions`        | `NavTipAction[]`                  | Yes      |            | Navigation tip items  |
-
-### Nav Tip Action (`nav:tip`)
-
-Compositional action — rendered as an accordion item by the parent widget.
-
-| Property             | Type                        | Required | Description                          |
-| -------------------- | --------------------------- | -------- | ------------------------------------ |
-| `kind`               | `"nav:tip"`                 | Yes      | Action type                          |
-| `config.id`          | string                      | Yes      | Unique tip identifier                |
-| `config.title`       | string                      | Yes      | Accordion header text                |
-| `config.description` | string                      | Yes      | Expanded body text                   |
-| `config.href`        | string                      | No       | Optional CTA link URL                |
-| `config.icon`        | string                      | No       | Icon (emoji or icon key)             |
-| `config.external`    | boolean                     | No       | Open link in new tab                 |
-| `config.category`    | string                      | No       | Category for grouping                |
-| `showWhen`           | `DecisionStrategy<boolean>` | No       | Conditional visibility               |
-| `notify`             | `{ title?, body?, icon? }`  | No       | Toast config for showWhen transition |
-| `rationale`          | `{ why, confidence? }`      | No       | AI reasoning for recommendation      |
-
-### Events Published
-
-| Event              | When                                | Props                             |
-| ------------------ | ----------------------------------- | --------------------------------- |
-| `nav:toggled`      | User expands/collapses a tip        | `{ instanceId, tipId, expanded }` |
-| `nav:tip_clicked`  | User clicks a tip's CTA link        | `{ instanceId, href, external }`  |
-| `nav:tip_revealed` | `showWhen` transitions false → true | `{ tipId, title, body, icon }`    |
-
-### Notify Watchers
-
-Tips with both `showWhen` and `notify` are registered as notify watchers. The runtime evaluates these continuously (even when drawer is closed). When `showWhen` transitions false → true, publishes `nav:tip_revealed` which can trigger toast notifications via tile-level `notifications` rules.
-
-```json
-{
-  "id": "nav",
-  "widget": "adaptive-nav:tips",
-  "notifications": [
-    {
-      "on": "nav:tip_revealed",
-      "title": "{{props.title}}",
-      "body": "{{props.body}}",
-      "icon": "🧭"
-    }
-  ],
-  "props": {
-    "expandBehavior": "single",
-    "theme": "dark",
-    "actions": [
-      {
-        "kind": "nav:tip",
-        "config": {
-          "id": "tip-analytics",
-          "title": "Advanced Analytics",
-          "description": "Unlock deeper insights with our analytics suite.",
-          "href": "/analytics",
-          "icon": "📊",
-          "category": "Power User"
-        },
-        "notify": { "title": "New Tip", "body": "Advanced Analytics", "icon": "📊" },
-        "showWhen": {
-          "type": "rules",
-          "rules": [
-            {
-              "conditions": [
-                { "type": "event_count", "key": "link-clicks", "operator": "gte", "count": 3 }
-              ],
-              "value": true
-            }
-          ],
-          "default": false
-        }
-      }
-    ]
-  }
-}
-```
-
-## Navigation Actions
-
-### `navigation:scrollTo`
-
-Scrolls the viewport to bring an element into view.
-
-| Property   | Type                    | Required | Default    | Description                                 |
-| ---------- | ----------------------- | -------- | ---------- | ------------------------------------------- |
-| `kind`     | `"navigation:scrollTo"` | Yes      |            | Action type                                 |
-| `anchorId` | string                  | Yes      |            | Element selector                            |
-| `behavior` | string                  | No       | `"smooth"` | `"smooth"`, `"instant"`, `"auto"`           |
-| `block`    | string                  | No       | `"center"` | `"start"`, `"center"`, `"end"`, `"nearest"` |
-
-### `navigation:navigate`
-
-Navigates to a URL.
-
-| Property | Type                    | Required | Default   | Description             |
-| -------- | ----------------------- | -------- | --------- | ----------------------- |
-| `kind`   | `"navigation:navigate"` | Yes      |           | Action type             |
-| `url`    | string                  | Yes      |           | Destination URL         |
-| `target` | string                  | No       | `"_self"` | `"_self"` or `"_blank"` |
-
-**Note:** `javascript:` URLs are blocked for security.
-
-
----
-
-# @syntrologie/adapt-overlays
-
-Visual overlay capabilities including highlights, tooltips, badges, pulse animations, and celebrations.
-
-## When to use
-
-| Goal | Action |
-|------|--------|
-| Draw attention to an element (spotlight) | `overlays:highlight` |
-| Show contextual help or guidance near an element | `overlays:tooltip` |
-| Add a notification indicator (count, "NEW") | `overlays:badge` |
-| Subtle attention-grab animation | `overlays:pulse` |
-| Show a blocking or non-blocking dialog | `overlays:modal` |
-| Celebrate a user achievement | `overlays:celebrate` |
-
-## Actions
-
-### overlays:highlight
-
-Creates a spotlight effect around an element with a scrim overlay.
-
-| Property             | Type          | Required | Default     | Description                             |
-| -------------------- | ------------- | -------- | ----------- | --------------------------------------- |
-| `kind`               | `"overlays:highlight"` | Yes      |             | Action type                             |
-| `anchorId`           | string        | Yes      |             | Element selector                        |
-| `style.color`        | string        | No       | `"#5b8cff"` | Ring color                              |
-| `style.scrimOpacity` | number        | No       | `0.55`      | Backdrop opacity 0-1 (set to 0 to hide) |
-| `style.paddingPx`    | number        | No       | `12`        | Space around element                    |
-| `style.radiusPx`     | number        | No       | `12`        | Ring corner radius                      |
-
-```json
-{
-  "kind": "overlays:highlight",
-  "anchorId": "#signup-button",
-  "style": {
-    "color": "#22c55e",
-    "scrimOpacity": 0.4
-  }
-}
-```
-
-### overlays:tooltip
-
-Shows a tooltip near an element with optional title, body, and CTA.
-
-| Property             | Type        | Required | Default       | Description                            |
-| -------------------- | ----------- | -------- | ------------- | -------------------------------------- |
-| `kind`               | `"overlays:tooltip"` | Yes      |               | Action type                            |
-| `anchorId`           | string      | Yes      |               | Element selector                       |
-| `content.title`      | string      | No       |               | Tooltip heading                        |
-| `content.body`       | string      | Yes      |               | Tooltip text                           |
-| `content.cta.label`  | string      | No       |               | CTA button text (single-CTA shorthand) |
-| `content.cta.action` | Action      | No       |               | Action to execute on CTA click         |
-| `content.ctaButtons` | array       | No       |               | Multiple CTA buttons (see below)       |
-| `trigger`            | string      | No       | `"immediate"` | `"immediate"`, `"hover"`, `"click"`    |
-| `placement`          | string      | No       | `"top"`       | See placement options below            |
-
-**Placement options:** `top`, `top-start`, `top-end`, `bottom`, `bottom-start`, `bottom-end`, `left`, `left-start`, `left-end`, `right`, `right-start`, `right-end`
-
-**Single CTA (shorthand):**
-
-```json
-{
-  "kind": "overlays:tooltip",
-  "anchorId": "#pricing-toggle",
-  "content": {
-    "title": "Save 20%",
-    "body": "Switch to annual billing to save on your subscription.",
-    "cta": {
-      "label": "Switch Now",
-      "action": { "kind": "navigation:navigate", "url": "/billing?annual=true" }
-    }
-  },
-  "placement": "bottom",
-  "trigger": "immediate"
-}
-```
-
-**Multiple CTAs (`ctaButtons`):**
-
-Use `ctaButtons` for tooltips with multiple actions. Each button has:
-
-- `label`: Button text
-- `actionId`: Identifier published with the `action.tooltip_cta_clicked` event
-- `primary`: Whether this is a primary button (default: false)
-
-```json
-{
-  "kind": "overlays:tooltip",
-  "anchorId": "[data-nav=\"features\"]",
-  "content": {
-    "title": "Learn About Features",
-    "body": "We have answers about our feature set.",
-    "ctaButtons": [
-      { "label": "View Answer", "actionId": "faq:open:q-features", "primary": true },
-      { "label": "Dismiss", "actionId": "dismiss" }
-    ]
-  },
-  "trigger": "immediate",
-  "placement": "bottom"
-}
-```
-
-**Special actionId values:**
-
-- `"dismiss"` — Destroys the tooltip immediately without publishing an event
-- `"faq:open:<questionId>"` — Convention for companion FAQ tooltips (see adaptive-faq CAPABILITIES for details). Publishes `action.tooltip_cta_clicked` which the FAQ widget listens for.
-- Any other value — Publishes `action.tooltip_cta_clicked` with the `actionId` in event props for custom handling
-
-### overlays:badge
-
-Adds a small badge indicator near an element.
-
-| Property   | Type      | Required | Default       | Description                                                    |
-| ---------- | --------- | -------- | ------------- | -------------------------------------------------------------- |
-| `kind`     | `"overlays:badge"` | Yes      |               | Action type                                                    |
-| `anchorId` | string    | Yes      |               | Element selector                                               |
-| `text`     | string    | Yes      |               | Badge text (e.g., "NEW", "3")                                  |
-| `position` | string    | No       | `"top-right"` | `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-right"` |
-
-```json
-{
-  "kind": "overlays:badge",
-  "anchorId": "#inbox-icon",
-  "text": "5",
-  "position": "top-right"
-}
-```
-
-### overlays:pulse
-
-Adds a pulsing animation to draw attention.
-
-| Property   | Type      | Required | Default | Description              |
-| ---------- | --------- | -------- | ------- | ------------------------ |
-| `kind`     | `"overlays:pulse"` | Yes      |         | Action type              |
-| `anchorId` | string    | Yes      |         | Element selector         |
-| `duration` | number    | No       | `2000`  | Animation duration in ms |
-
-```json
-{
-  "kind": "overlays:pulse",
-  "anchorId": ".notification-bell",
-  "duration": 3000
-}
-```
-
-### overlays:modal
-
-Shows a centered modal dialog with optional CTA buttons.
-
-| Property              | Type               | Required | Default | Description                                                   |
-| --------------------- | ------------------ | -------- | ------- | ------------------------------------------------------------- |
-| `kind`                | `"overlays:modal"` | Yes      |         | Action type                                                   |
-| `content.title`       | string             | No       |         | Modal heading                                                 |
-| `content.body`        | string             | Yes      |         | Modal text                                                    |
-| `size`                | string             | No       | `"md"`  | `"sm"`, `"md"`, `"lg"`                                        |
-| `blocking`            | boolean            | No       | `false` | Block page interaction                                        |
-| `scrim.opacity`       | number             | No       | `0.6`   | Backdrop opacity 0-1                                          |
-| `dismiss.onEsc`       | boolean            | No       | `true`  | Close on Escape key                                           |
-| `dismiss.closeButton` | boolean            | No       | `true`  | Show close button                                             |
-| `dismiss.timeoutMs`   | number             | No       |         | Auto-close after timeout                                      |
-| `ctaButtons`          | array              | No       |         | Array of CTA buttons                                          |
-| `waitFor`             | string             | No       |         | When to complete: `"dismissed"`, `"cta-click"`, `"timeout:N"` |
-
-**CTA Button properties:**
-
-- `label`: Button text
-- `actionId`: Identifier for the action
-- `primary`: Whether this is a primary button (default: false)
-
-```json
-{
-  "kind": "overlays:modal",
-  "content": {
-    "title": "Welcome!",
-    "body": "Thanks for signing up. Let us show you around."
-  },
-  "size": "md",
-  "ctaButtons": [
-    { "label": "Skip", "actionId": "skip" },
-    { "label": "Start Tour", "actionId": "start", "primary": true }
-  ],
-  "waitFor": "cta-click"
-}
-```
-
-### overlays:celebrate
-
-Renders a fullscreen Canvas 2D celebration effect. One action kind with a pluggable `effect` parameter supporting multiple visual presets.
-
-| Property    | Type                               | Required | Default                    | Description                                   |
-| ----------- | ---------------------------------- | -------- | -------------------------- | --------------------------------------------- |
-| `kind`      | `"overlays:celebrate"`             | Yes      |                            | Action type                                   |
-| `effect`    | string                             | Yes      |                            | Effect name (see presets below)                |
-| `duration`  | number                             | No       | `3000`                     | Animation duration in ms                      |
-| `intensity` | `"light"` \| `"medium"` \| `"heavy"` | No       | `"medium"`                 | Particle density                              |
-| `colors`    | string[]                           | No       | Rainbow palette            | Color palette for particles                   |
-| `props`     | object                             | No       |                            | Effect-specific properties (see presets below) |
-
-**Available effect presets:**
-
-- **`confetti`** — Falling rectangular/circular confetti pieces with gravity, air resistance, and rotation
-- **`fireworks`** — Multiple burst centers with radiating particles, deceleration, and glow effect
-- **`sparkles`** — Diamond shapes that twinkle via sine-wave opacity oscillation and float gently upward
-- **`emoji-rain`** — Emoji characters falling from the top with horizontal sine-wave wobble. Use `props.emoji` to set the character (default: `"🎉"`)
-
-**Confetti:**
-
-```json
-{
-  "kind": "overlays:celebrate",
-  "effect": "confetti",
-  "duration": 4000,
-  "intensity": "heavy",
-  "colors": ["#ff0000", "#00ff00", "#0000ff", "#ffff00"]
-}
-```
-
-**Fireworks:**
-
-```json
-{
-  "kind": "overlays:celebrate",
-  "effect": "fireworks",
-  "duration": 3000,
-  "intensity": "medium"
-}
-```
-
-**Sparkles:**
-
-```json
-{
-  "kind": "overlays:celebrate",
-  "effect": "sparkles",
-  "duration": 5000,
-  "colors": ["#ffd700", "#ffffff", "#fffacd"]
-}
-```
-
-**Emoji rain:**
-
-```json
-{
-  "kind": "overlays:celebrate",
-  "effect": "emoji-rain",
-  "duration": 3000,
-  "props": { "emoji": "🔥" }
-}
-```
-
-
----
-
-# @syntrologie/adapt-viz
-
-Charts and tables for visualizing data — bar, line, and tabular layouts.
-
-## Identity
-
-- **App ID:** `adaptive-viz`
-- **Bundling:** CDN-only (lazy-loaded; not in the core SDK bundle)
-- **Loader:** `cdn.ts` registers `<syntro-viz-chart>` and exports the widget mountable
-
-## Tile Widgets
-
-| Widget ID | Purpose |
-|-----------|---------|
-| `adaptive-viz:chart` | Renders a chart given typed props (bar / line / table) |
-
-## Configuration Shape (per tile)
-
-```jsonc
-{
-  "id": "tile-id",
-  "widget": "adaptive-viz:chart",
-  "props": {
-    "layout": "bar",  // or "line", "table"
-    // ...layout-specific fields (see schema.ts)
-  }
-}
-```
-
-## Layouts
-
-### `bar`
-Single bar chart. Inputs: `data: { [key: string]: unknown }[]`, `xField`, `yField`, optional `colorField`.
-
-### `line`
-Continuous line chart. Inputs: `data`, `xField`, `yField`, optional `seriesField`.
-
-### `table`
-Tabular data display (rendered as Vega-Lite text marks in a grid). Inputs: `data`, `columns: { field, header }[]`.
-
-## Actions
-
-None. This widget renders only; it does not emit DOM-mutation actions.
-
-## Theme Tokens Consumed
-
-`--sc-color-primary`, `--sc-color-primary-hover`, `--sc-overlay-text-color`, `--sc-font-family`, `--sc-tile-background`. See `theme.ts` for the full mapping to Vega-Lite `config` properties.
-
-
----
-
-
----
-
-## Surfaces
-
-Surfaces are named slots where widgets can be mounted. Use the `mount_widget` action to render content into a surface slot.
-
-### Static Slots
-
-Fixed-position slots for common UI patterns:
-
-| Slot | Position | Use Case |
-|------|----------|----------|
-| `drawer_right` | Right edge, full height | Settings panels, details |
-| `drawer_left` | Left edge, full height | Navigation, filters |
-| `drawer_bottom` | Bottom edge, full width | Action sheets, keyboards |
-| `overlay_center` | Centered modal | Dialogs, confirmations |
-| `overlay_corner_br` | Bottom-right corner | Chat widgets, help |
-| `overlay_corner_bl` | Bottom-left corner | Notifications |
-| `toast_top` | Top center | Success/error messages |
-| `toast_bottom` | Bottom center | Snackbar notifications |
-
-### Dynamic Slots
-
-Slots that position content relative to anchors:
-
-- **Inline Slots**: Render content inside an anchor element. Format: `inline:{anchorId}`
-- **Adjacent Slots**: Render content positioned near an anchor element. Format: `adjacent:{anchorId}`
-
----
-
-## Anchor Resolution
-
-The `anchorId` field identifies which DOM element to target. Multiple formats are supported:
-
-### CSS Selectors
-
-| Format | Example | Matches |
-|--------|---------|---------|
-| Class | `".hero-title"` | `<h1 class="hero-title">` |
-| ID | `"#signup-button"` | `<button id="signup-button">` |
-| Attribute | `"[data-testid='cta']"` | `<button data-testid="cta">` |
-| Tag + class | `"h1.page-title"` | `<h1 class="page-title">` |
-| Nested | `".card .title"` | `<div class="title">` inside `.card` |
-
-### Data Attributes (Recommended)
-
-For stability, add `data-syntro-anchor` attributes to target elements:
-
-```html
-<h1 data-syntro-anchor="hero-title">Welcome</h1>
-```
-
-Then reference by the anchor name:
-
-```json
-{ "anchorId": "hero-title" }
-```
-
----
-
-## Route Scoping
-
-Every tile and action **must** declare which pages it applies to via `activation.routes`. The config itself is always active — individual tiles and actions decide independently whether to render.
-
-### Per-Tile Activation
-
-```json
-{
-  "id": "faq-w2-boxes",
-  "widget": "adaptive-faq:accordion",
-  "activation": {
-    "routes": { "include": ["/dashboard/income"] }
-  },
-  "props": { ... }
-}
-```
-
-### Per-Action Activation
-
-```json
-{
-  "kind": "content:insertHtml",
-  "anchorId": "[data-section='refund-estimate']",
-  "activation": {
-    "routes": { "include": ["/dashboard"] }
-  },
-  "html": "...",
-  "position": "after"
-}
-```
-
-### Route Patterns
-
-| Pattern | Matches | Use Case |
-|---------|---------|----------|
-| `"/dashboard/income"` | Exact path only | Page-specific |
-| `"/dashboard/**"` | `/dashboard` and all sub-paths | Section-wide |
-| `"/**"` | All pages | Global (always active) |
-| `"/dashboard/:id"` | Any single segment after `/dashboard/` | Dynamic routes |
-
-### Pattern Matching Rules
-
-- Patterns match against **pathname only** (no domain, no query string)
-- `**` matches anything (including `/`)
-- `*` matches within a single path segment (not `/`)
-- `exclude` takes priority over `include`
-
----
-
-## Decision Strategies
-
-Control when adaptives activate using `DecisionStrategy`:
-
-### Rules Strategy
-
-```json
-{
-  "type": "rules",
-  "rules": [
-    {
-      "conditions": [
-        { "type": "page_url", "pattern": "/pricing*" },
-        { "type": "viewport", "minWidth": 768 },
-        { "type": "dismissed", "key": "promo", "inverted": true }
-      ],
-      "value": true
-    }
-  ],
-  "default": false
-}
-```
-
-### Condition Types
-
-| Type | Parameters | Description |
-|------|------------|-------------|
-| `page_url` | `pattern` | URL matches glob pattern |
-| `route` | `routeId` | Route ID matches |
-| `anchor_visible` | `anchorId`, `state` | Anchor visibility |
-| `event_occurred` | `eventName`, `withinMs?` | Recent event |
-| `state_equals` | `key`, `value` | State matches |
-| `viewport` | `minWidth?`, `maxWidth?`, `minHeight?`, `maxHeight?` | Viewport size |
-| `session_metric` | `key`, `operator`, `threshold` | Metric comparison |
-| `dismissed` | `key`, `inverted?` | Dismissal check |
-| `cooldown_active` | `key`, `inverted?` | Cooldown check |
-| `frequency_limit` | `key`, `limit`, `inverted?` | Frequency cap |
-
----
-
-## Best Practices
-
-### 1. Choose the Right Action Type
-
-Each adaptive package has a "When to use" guide at the top of its capabilities section above. Refer to those for action selection guidance.
-
-### 2. Anchor Selection
-
-- **Prefer stable selectors:** `[data-testid]`, IDs over classes
-- **Test across states:** Element may not exist on all pages
-- **Be specific:** Avoid selectors matching multiple elements
-
-### 3. Reversibility
-
-- Always store handles if you need to revert
-- Use `applyBatch` for related changes (atomic rollback)
-- Clean up on route changes
-
-### 4. Performance
-
-- Batch related actions together
-- Use `validate()` to check actions before applying
-- Avoid applying many actions simultaneously
-
-### 5. Events
-
-- Listen for `action.failed` to handle errors
-- Track `action.applied` for analytics
-- Use EventBus for cross-adaptive coordination
-
-### 6. Opening the Canvas from Inserted Content
-
-When `content:insertHtml` needs to open the canvas panel (e.g., a "Help Me Choose" button that opens an FAQ tile), use the `deepLink` property — **never write `onclick` handlers or reference `window.SynOS` in HTML**.
-
-```json
-{
-  "kind": "content:insertHtml",
-  "anchorId": { "selector": "[data-id='pricing-heading']", "route": "/" },
-  "html": "<button style='background: #4a90e2; color: white; border: none; padding: 8px 16px; border-radius: 20px; cursor: pointer;'>Help Me Choose</button>",
-  "position": "after",
-  "deepLink": { "tileId": "plan_selector_faq" }
-}
-```
-
-The `deepLink` object:
-- `tileId` (required) — ID of the canvas tile to navigate to
-- `itemId` (optional) — specific item within the tile (e.g., a FAQ question ID)
-
-The SDK automatically opens the canvas, navigates to the tile, sets cursor to pointer, and wires up click/cleanup handlers.
-
-**NEVER use `onclick`, `window.SynOS`, or any JavaScript in `content:insertHtml` HTML strings.** The HTML is sanitized and event handlers are stripped. Use `deepLink` instead.