@syntrologie/runtime-sdk 2.8.0-canary.1 → 2.8.0-canary.11

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.
@@ -292,7 +314,7 @@ Removes a CSS class from an element.
 
 # @syntrologie/adapt-faq
 
-Collapsible Q&A accordion with actions, rich content, feedback, and personalization. Supports mounting a full FAQ widget, scrolling to specific items, toggling item state, and dynamically updating the item list at runtime.
+Collapsible Q&A accordion with actions, rich content, feedback, and personalization.
 
 ## Actions
 
@@ -1284,3 +1306,25 @@ Control when adaptives activate using `DecisionStrategy`:
 - 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": "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 `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.