@syntrologie/runtime-sdk 2.8.0-canary.9 → 2.9.0

package/CAPABILITIES.md

@@ -233,6 +233,7 @@ Inserts HTML content relative to an element.
 | `anchorId` | string          | Yes      | Element selector                                            |
 | `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:**
 
@@ -251,6 +252,27 @@ Inserts HTML content relative to an element.
 }
 ```
 
+**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": "insert_html",
+  "anchorId": "[data-id='pricing-heading']",
+  "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.
+
 ### add_class
 
 Adds a CSS class to an element.
@@ -1285,24 +1307,24 @@ Control when adaptives activate using `DecisionStrategy`:
 - Track `action.applied` for analytics
 - Use EventBus for cross-adaptive coordination
 
-### 6. JavaScript API (window.SynOS)
-
-When generating `content:insertHtml` with interactive elements (buttons, links) that need to control the SDK canvas panel, use the `window.SynOS.handle` API:
-
-| Method | Description |
-|--------|-------------|
-| `window.SynOS.handle.open()` | Open the canvas panel |
-| `window.SynOS.handle.close()` | Close the canvas panel |
+### 6. Opening the Canvas from Inserted Content
 
-Example — button that opens the canvas:
+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": "insert_html",
-  "anchorId": ".pricing-heading",
-  "html": "<button onclick='window.SynOS?.handle?.open()'>Help Me Choose</button>",
-  "position": "after"
+  "anchorId": "[data-id='pricing-heading']",
+  "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" }
 }
 ```
 
-**WARNING:** There is NO `window.SynOS.canvas` property. Always use `window.SynOS.handle`.
+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 `insert_html` HTML strings.** The HTML is sanitized and event handlers are stripped. Use `deepLink` instead.