@syntrologie/runtime-sdk 0.2.21 → 1.0.0-canary.1

package/CAPABILITIES.md

@@ -1,611 +1,872 @@
 # SmartCanvas SDK Capabilities
 
-This document describes all available operations and capabilities of the SmartCanvas SDK for DOM manipulation and enhancement.
+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)
-- [Policy Tiers](#policy-tiers)
-- [Anchor Selectors](#anchor-selectors)
-- [Operations](#operations)
-- [Overlays](#overlays)
-- [Runtime v2 Providers](#runtime-v2-providers)
+- [Quick Start Example](#quick-start-example)
+- [Adaptive Packages](#adaptive-packages)
+- [Surfaces](#surfaces)
+- [Anchor Resolution](#anchor-resolution)
+- [Decision Strategies](#decision-strategies)
 - [Best Practices](#best-practices)
 
+---
+
 ## Overview
 
-The SmartCanvas SDK allows you to safely modify web pages through a controlled patching system. All modifications are applied through "patches" that contain:
-- An anchor selector to find the target element
-- One or more operations to apply
-- A policy tier that controls what modifications are allowed
+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": "set_text",
+      "anchorId": "h1.hero-title",
+      "text": "Welcome to Our New Experience"
+    }
+  ]
+}
+```
+
+---
 
-## Policy Tiers
+## Adaptive Packages
 
-The SDK uses three policy tiers to control what operations are allowed:
+The SDK includes the following adaptive packages, each providing specific capabilities:
 
-### 1. **additive** (default)
-- **Purpose**: Safest tier - only add new elements and classes
-- **Allowed**: Adding HTML, adding prefixed classes, safe styles
-- **Not Allowed**: Modifying existing text or attributes
-- **Use When**: Adding badges, tooltips, or decorative elements
+- [@syntrologie/adapt-chatbot](#syntrologieadapt-chatbot)
+- [@syntrologie/adapt-content](#syntrologieadapt-content)
+- [@syntrologie/adapt-faq](#syntrologieadapt-faq)
+- [@syntrologie/adapt-gamification](#syntrologieadapt-gamification)
+- [@syntrologie/adapt-nav](#syntrologieadapt-nav)
+- [@syntrologie/adapt-navigation](#syntrologieadapt-navigation)
+- [@syntrologie/adapt-overlays](#syntrologieadapt-overlays)
 
-### 2. **moderate**
-- **Purpose**: Allows limited modifications to existing elements
-- **Allowed**: Everything from additive + title attribute
-- **Not Allowed**: Text changes, color changes
-- **Use When**: Adding accessibility improvements or metadata
+---
 
-### 3. **surgical**
-- **Purpose**: Full control over content modification
-- **Allowed**: Everything including setText, background/text colors
-- **Required For**: Changing headlines, CTAs, or any text content
-- **Use When**: A/B testing copy variations or personalizing content
+# @syntrologie/adapt-chatbot
 
-## Anchor Selectors
+AI chat assistant widget with action execution capabilities.
 
-Anchors define how to find elements in the DOM. The SDK supports four types:
+## Widgets
+
+### adaptive-chatbot:assistant
+
+Mounts an AI-powered chat assistant that connects to a backend LLM endpoint. The assistant can parse action instructions from the LLM response and execute them on the page via the runtime's ActionEngine.
+
+**Tile config example:**
 
-### 1. CSS Selector
 ```json
 {
-  "by": "css",
-  "value": "h1.hero-title"
+  "id": "chatbot-assistant",
+  "title": "Ask Assistant",
+  "content": {
+    "type": "custom",
+    "component": "adaptive-chatbot:assistant",
+    "props": {
+      "backendUrl": "/api/chat/message",
+      "mlflowRunId": "abc123",
+      "greeting": "Hi! How can I help?"
+    }
+  },
+  "size": "full",
+  "defaultExpanded": true
 }
 ```
-- **Use**: Standard CSS selectors
-- **Example**: `"h1"`, `".button-primary"`, `"#hero-section h2"`
 
-### 2. Data Attribute
+### Config Props
+
+| Property      | Type   | Required | Default               | Description                             |
+| ------------- | ------ | -------- | --------------------- | --------------------------------------- |
+| `backendUrl`  | string | Yes      | —                     | URL for the chat API endpoint           |
+| `mlflowRunId` | string | No       | —                     | MLflow run ID for experiment tracking   |
+| `greeting`    | string | No       | "Hi! How can I help?" | Initial greeting message                |
+| `maxHistory`  | number | No       | 20                    | Max messages sent as history to backend |
+
+## Action Execution
+
+The chatbot does **not** define its own action kinds. Instead, it parses JSON action blocks from the LLM response and executes them via `runtime.actions.applyBatch()`. This means the chatbot can trigger any action kind registered in the runtime (highlights, tooltips, text changes, navigation, tours, etc.).
+
+### LLM Response Format
+
+The backend returns a text reply that may contain embedded JSON action blocks in fenced code blocks:
+
+```
+Here's what I found. Let me highlight the pricing section for you.
+
+\`\`\`json
+{"kind": "overlays:highlight", "anchorId": "pricing-section"}
+\`\`\`
+
+Is there anything else you'd like to know?
+```
+
+- JSON blocks with a `kind` field are extracted as actions and removed from display text
+- JSON blocks without `kind` are left in the display text as-is
+- Multiple action blocks can appear in a single response
+- Actions with unknown kinds are silently ignored by the ActionEngine
+
+## Authentication
+
+The widget reads auth credentials from the browser:
+
+- **JWT**: `stytch_session_jwt` cookie
+- **Workspace ID**: `syntrologie_workspace_id` from localStorage
+- Headers: `Authorization: Bearer <jwt>` + `X-Workspace-Id: <id>`
+
+## Events
+
+| Event                     | Props                        | Description                       |
+| ------------------------- | ---------------------------- | --------------------------------- |
+| `chatbot.actions_applied` | `count`, `kinds[]`, `tileId` | Emitted when actions are executed |
+
+
+---
+
+# @syntrologie/adapt-content
+
+DOM content modification capabilities for text, attributes, styles, HTML, and classes.
+
+## Actions
+
+### set_text
+
+Replaces the text content of an element.
+
+| Property   | Type         | Required | Description      |
+| ---------- | ------------ | -------- | ---------------- |
+| `kind`     | `"set_text"` | Yes      | Action type      |
+| `anchorId` | string       | Yes      | Element selector |
+| `text`     | string       | Yes      | New text content |
+
 ```json
 {
-  "by": "data",
-  "key": "testid",
-  "value": "hero-banner"  // optional
+  "kind": "set_text",
+  "anchorId": "h1.hero-title",
+  "text": "Start Your Free Trial Today"
 }
 ```
-- **Use**: Target elements by data attributes
-- **Example**: Finds `<div data-testid="hero-banner">`
-- **Note**: If value is omitted, matches any element with that data attribute
 
-### 3. ARIA Selector
+### set_attr
+
+Sets an HTML attribute on an element.
+
+| Property   | Type         | Required | Description      |
+| ---------- | ------------ | -------- | ---------------- |
+| `kind`     | `"set_attr"` | Yes      | Action type      |
+| `anchorId` | string       | Yes      | Element selector |
+| `attr`     | string       | Yes      | Attribute name   |
+| `value`    | string       | Yes      | Attribute value  |
+
+**Blocked attributes:** Event handlers (`onclick`, `onerror`, etc.) are not allowed.
+
 ```json
 {
-  "by": "aria",
-  "role": "button",     // optional
-  "label": "Submit"     // optional
+  "kind": "set_attr",
+  "anchorId": "#signup-form",
+  "attr": "data-experiment",
+  "value": "signup-v2"
 }
 ```
-- **Use**: Target accessible elements
-- **Example**: Finds `<button role="button" aria-label="Submit">`
-- **Note**: Can use role, label, or both
 
-### 4. Element Reference
+### set_style
+
+Sets inline CSS styles on an element.
+
+| Property   | Type          | Required | Description              |
+| ---------- | ------------- | -------- | ------------------------ |
+| `kind`     | `"set_style"` | Yes      | Action type              |
+| `anchorId` | string        | Yes      | Element selector         |
+| `styles`   | object        | Yes      | CSS property/value pairs |
+
 ```json
 {
-  "by": "ref",
-  "el": elementReference
+  "kind": "set_style",
+  "anchorId": ".hero-section",
+  "styles": {
+    "background-color": "#1e40af",
+    "padding": "2rem"
+  }
 }
 ```
-- **Use**: Direct element reference (programmatic use only)
-- **Note**: Cannot be serialized in JSON configs
 
-## Operations
+### insert_html
+
+Inserts HTML content relative to an element.
+
+| Property   | Type            | Required | Description                                                 |
+| ---------- | --------------- | -------- | ----------------------------------------------------------- |
+| `kind`     | `"insert_html"` | Yes      | Action type                                                 |
+| `anchorId` | string          | Yes      | Element selector                                            |
+| `html`     | string          | Yes      | HTML content (sanitized)                                    |
+| `position` | string          | Yes      | `"before"`, `"after"`, `"prepend"`, `"append"`, `"replace"` |
+
+**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
 
-### 1. setText
-**Purpose**: Replace the text content of an element
 ```json
 {
-  "kind": "setText",
-  "text": "New headline text"
+  "kind": "insert_html",
+  "anchorId": ".cta-button",
+  "html": "<span class=\"badge\">NEW</span>",
+  "position": "append"
 }
 ```
-- **Requires**: `tier: "surgical"`
-- **Effect**: Replaces all text content in the element
-- **Common Use**: A/B testing headlines, CTAs, product descriptions
-- **Note**: Removes all child elements, use carefully
 
-### 2. setStyle
-**Purpose**: Modify CSS styles on an element
+### add_class
+
+Adds a CSS class to an element.
+
+| Property    | Type          | Required | Description       |
+| ----------- | ------------- | -------- | ----------------- |
+| `kind`      | `"add_class"` | Yes      | Action type       |
+| `anchorId`  | string        | Yes      | Element selector  |
+| `className` | string        | Yes      | Class name to add |
+
 ```json
 {
-  "kind": "setStyle",
-  "prop": "backgroundColor",
-  "value": "#ff0000",
-  "important": true  // optional, adds !important
+  "kind": "add_class",
+  "anchorId": ".pricing-card",
+  "className": "highlighted"
 }
 ```
-- **Allowed Properties (any tier)**:
-  - `outline`, `outlineColor`, `outlineWidth`, `outlineStyle`
-  - `boxShadow`, `filter`
-  - `scrollMargin` and related properties
-  - CSS variables (`--custom-var`)
-- **Additional Properties (surgical tier)**:
-  - `backgroundColor`, `color`
-- **Common Use**: Highlighting elements, adding visual emphasis
-- **Note**: Value can be `null` to remove a style
-
-### 3. addClass
-**Purpose**: Add a CSS class to an element
+
+### remove_class
+
+Removes a CSS class from an element.
+
+| Property    | Type             | Required | Description          |
+| ----------- | ---------------- | -------- | -------------------- |
+| `kind`      | `"remove_class"` | Yes      | Action type          |
+| `anchorId`  | string           | Yes      | Element selector     |
+| `className` | string           | Yes      | Class name to remove |
+
 ```json
 {
-  "kind": "addClass",
-  "className": "syntro-highlight"
+  "kind": "remove_class",
+  "anchorId": ".pricing-card",
+  "className": "hidden"
 }
 ```
-- **Requirement**: Class must start with `syntro-`, `sc-`, or `sx-`
-- **Common Use**: Apply pre-defined styles, mark elements
-- **Note**: Won't add duplicate classes
 
-### 4. removeClass
-**Purpose**: Remove a CSS class from an element
+
+---
+
+# @syntrologie/adapt-faq
+
+FAQ accordion widget with conditional item visibility.
+
+## Actions
+
+### mount_faq
+
+Mounts an FAQ accordion widget to a surface slot.
+
+| Property       | Type          | Required | Description                                              |
+| -------------- | ------------- | -------- | -------------------------------------------------------- |
+| `kind`         | `"mount_faq"` | Yes      | Action type                                              |
+| `slot`         | string        | Yes      | Target slot (e.g., `"drawer_right"`, `"overlay_center"`) |
+| `config.title` | string        | No       | Widget title                                             |
+| `config.items` | array         | Yes      | FAQ items (see below)                                    |
+
+### FAQ Item Schema
+
+Each item in the `items` array:
+
+| Property   | Type             | Required | Description                         |
+| ---------- | ---------------- | -------- | ----------------------------------- |
+| `question` | string           | Yes      | The question text                   |
+| `answer`   | string           | Yes      | The answer text (supports markdown) |
+| `showWhen` | DecisionStrategy | No       | Conditional visibility strategy     |
+
 ```json
 {
-  "kind": "removeClass",
-  "className": "syntro-hidden"
+  "kind": "mount_faq",
+  "slot": "drawer_right",
+  "config": {
+    "title": "Frequently Asked Questions",
+    "items": [
+      {
+        "question": "How do I get started?",
+        "answer": "Sign up for a free account and follow our quickstart guide."
+      },
+      {
+        "question": "What payment methods do you accept?",
+        "answer": "We accept all major credit cards and PayPal.",
+        "showWhen": {
+          "type": "rules",
+          "rules": [
+            {
+              "conditions": [{ "type": "page_url", "pattern": "/pricing*" }],
+              "value": true
+            }
+          ],
+          "default": false
+        }
+      }
+    ]
+  }
 }
 ```
-- **Requirement**: Can only remove prefixed classes
-- **Common Use**: Revealing hidden elements, removing states
-- **Note**: Safe if class doesn't exist
 
-### 5. setAttr
-**Purpose**: Set or remove HTML attributes
+## Compositional Pattern
+
+The FAQ widget supports **per-item conditional visibility** using `showWhen` strategies. This allows different FAQ items to appear based on:
+
+- Current page/route
+- User segment or state
+- Viewport conditions
+- Any other DecisionStrategy condition
+
+Items without `showWhen` are always visible.
+
+
+---
+
+# @syntrologie/adapt-gamification
+
+Gamification capabilities including badges, points, and leaderboards.
+
+## Actions
+
+### mount_gamification
+
+Mounts gamification UI elements.
+
+| Property | Type                   | Required | Description                |
+| -------- | ---------------------- | -------- | -------------------------- |
+| `kind`   | `"mount_gamification"` | Yes      | Action type                |
+| `slot`   | string                 | Yes      | Target slot                |
+| `config` | object                 | Yes      | Gamification configuration |
+
+### 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
 {
-  "kind": "setAttr",
-  "name": "data-tracked",
-  "value": "true"  // or null to remove
+  "kind": "mount_gamification",
+  "slot": "overlay_corner_br",
+  "config": {
+    "badges": [
+      {
+        "id": "first-purchase",
+        "name": "First Purchase",
+        "icon": "shopping-cart",
+        "description": "Made your first purchase!",
+        "trigger": {
+          "event": "purchase_completed"
+        }
+      },
+      {
+        "id": "explorer",
+        "name": "Explorer",
+        "icon": "compass",
+        "description": "Visited 10 different pages",
+        "trigger": {
+          "event": "page_view",
+          "conditions": [
+            { "type": "session_metric", "key": "unique_pages", "operator": ">=", "threshold": 10 }
+          ]
+        }
+      }
+    ],
+    "points": {
+      "enabled": true,
+      "multiplier": 2
+    },
+    "leaderboard": {
+      "enabled": true,
+      "refreshInterval": 30000
+    }
+  }
 }
 ```
-- **Allowed Attributes (any tier)**:
-  - `data-*` (any data attribute)
-  - `aria-*` (accessibility attributes)
-  - `role`
-- **Additional Attributes (moderate/surgical)**:
-  - `title`
-- **Common Use**: Tracking, accessibility improvements
-- **Note**: Setting to `null` removes the attribute
-
-### 6. append
-**Purpose**: Add HTML content at the end of an element
+
+## 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-nav
+
+Navigation link list widget with conditional item visibility.
+
+## Actions
+
+### mount_nav
+
+Mounts a navigation link list widget to a surface slot.
+
+| Property       | Type          | Required | Description                                                |
+| -------------- | ------------- | -------- | ---------------------------------------------------------- |
+| `kind`         | `"mount_nav"` | Yes      | Action type                                                |
+| `slot`         | string        | Yes      | Target slot (e.g., `"drawer_left"`, `"inline:{anchorId}"`) |
+| `config.title` | string        | No       | Widget title                                               |
+| `config.items` | array         | Yes      | Navigation items (see below)                               |
+
+### Nav Item Schema
+
+Each item in the `items` array:
+
+| Property   | Type             | Required | Description                     |
+| ---------- | ---------------- | -------- | ------------------------------- |
+| `label`    | string           | Yes      | Link text                       |
+| `href`     | string           | Yes      | Link destination                |
+| `icon`     | string           | No       | Icon identifier                 |
+| `showWhen` | DecisionStrategy | No       | Conditional visibility strategy |
+
 ```json
 {
-  "kind": "append",
-  "html": "<span class='syntro-badge'>NEW</span>"
+  "kind": "mount_nav",
+  "slot": "drawer_left",
+  "config": {
+    "title": "Quick Links",
+    "items": [
+      {
+        "label": "Dashboard",
+        "href": "/dashboard",
+        "icon": "home"
+      },
+      {
+        "label": "Admin Settings",
+        "href": "/admin",
+        "icon": "settings",
+        "showWhen": {
+          "type": "rules",
+          "rules": [
+            {
+              "conditions": [{ "type": "state_equals", "key": "user.role", "value": "admin" }],
+              "value": true
+            }
+          ],
+          "default": false
+        }
+      },
+      {
+        "label": "Upgrade",
+        "href": "/pricing",
+        "icon": "sparkles",
+        "showWhen": {
+          "type": "rules",
+          "rules": [
+            {
+              "conditions": [{ "type": "state_equals", "key": "user.plan", "value": "free" }],
+              "value": true
+            }
+          ],
+          "default": false
+        }
+      }
+    ]
+  }
 }
 ```
-- **Effect**: Inserts after existing children
-- **Common Use**: Adding badges, icons, supplementary content
-- **Note**: HTML is sanitized for safety
 
-### 7. prepend
-**Purpose**: Add HTML content at the beginning of an element
+## Compositional Pattern
+
+The nav widget supports **per-item conditional visibility** using `showWhen` strategies. This allows different navigation items to appear based on:
+
+- User role or permissions
+- Subscription tier
+- Feature flags
+- Any other DecisionStrategy condition
+
+Items without `showWhen` are always visible.
+
+
+---
+
+# @syntrologie/adapt-navigation
+
+Navigation capabilities for scrolling and URL navigation.
+
+## Actions
+
+### scroll_to
+
+Scrolls the viewport to bring an element into view.
+
+| Property   | Type          | Required | Default     | Description                                 |
+| ---------- | ------------- | -------- | ----------- | ------------------------------------------- |
+| `kind`     | `"scroll_to"` | Yes      |             | Action type                                 |
+| `anchorId` | string        | Yes      |             | Element selector                            |
+| `behavior` | string        | No       | `"smooth"`  | `"smooth"`, `"instant"`, `"auto"`           |
+| `block`    | string        | No       | `"center"`  | `"start"`, `"center"`, `"end"`, `"nearest"` |
+| `inline`   | string        | No       | `"nearest"` | `"start"`, `"center"`, `"end"`, `"nearest"` |
+
+```json
+{
+  "kind": "scroll_to",
+  "anchorId": "#pricing-section",
+  "behavior": "smooth",
+  "block": "start"
+}
+```
+
+### navigate
+
+Navigates to a URL.
+
+| Property | Type         | Required | Default   | Description             |
+| -------- | ------------ | -------- | --------- | ----------------------- |
+| `kind`   | `"navigate"` | Yes      |           | Action type             |
+| `url`    | string       | Yes      |           | Destination URL         |
+| `target` | string       | No       | `"_self"` | `"_self"` or `"_blank"` |
+
 ```json
 {
-  "kind": "prepend",
-  "html": "<span class='syntro-icon'>★</span>"
+  "kind": "navigate",
+  "url": "/signup?ref=banner",
+  "target": "_self"
 }
 ```
-- **Effect**: Inserts before existing children
-- **Common Use**: Adding icons, prefixes, notifications
-- **Note**: HTML is sanitized for safety
 
-### 8. insertAdjacent
-**Purpose**: Insert HTML at specific positions relative to element
+**Note:** `javascript:` URLs are blocked for security.
+
+
+---
+
+# @syntrologie/adapt-overlays
+
+Visual overlay capabilities including highlights, tooltips, badges, and pulse animations.
+
+## Actions
+
+### highlight
+
+Creates a spotlight effect around an element with a scrim overlay.
+
+| Property             | Type          | Required | Default     | Description                             |
+| -------------------- | ------------- | -------- | ----------- | --------------------------------------- |
+| `kind`               | `"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": "insertAdjacent",
-  "where": "afterbegin",
-  "html": "<div class='syntro-alert'>Important!</div>"
+  "kind": "highlight",
+  "anchorId": "#signup-button",
+  "style": {
+    "color": "#22c55e",
+    "scrimOpacity": 0.4
+  }
 }
 ```
-- **Positions**:
-  - `beforebegin`: Before the element itself
-  - `afterbegin`: Inside element, before first child
-  - `beforeend`: Inside element, after last child
-  - `afterend`: After the element itself
-- **Common Use**: Complex insertions, wrapping elements
-- **Note**: More flexible than append/prepend
 
-## Overlays
+### tooltip
+
+Shows a tooltip near an element with optional title, body, and CTA.
 
-The SDK supports overlay elements that don't modify the DOM. These are defined in `overlayRecipe.steps`:
+| Property             | Type        | Required | Default       | Description                         |
+| -------------------- | ----------- | -------- | ------------- | ----------------------------------- |
+| `kind`               | `"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                     |
+| `content.cta.action` | Action      | No       |               | Action to execute on CTA click      |
+| `trigger`            | string      | No       | `"immediate"` | `"immediate"`, `"hover"`, `"click"` |
+| `placement`          | string      | No       | `"top"`       | See placement options below         |
 
-### Tooltips
-Floating information bubbles that appear near target elements.
+**Placement options:** `top`, `top-start`, `top-end`, `bottom`, `bottom-start`, `bottom-end`, `left`, `left-start`, `left-end`, `right`, `right-start`, `right-end`
 
 ```json
 {
   "kind": "tooltip",
-  "id": "feature_tooltip_1",
-  "anchor": {
-    "by": "css",
-    "value": ".pricing-card"
-  },
+  "anchorId": "#pricing-toggle",
   "content": {
-    "title": "Best Value",
-    "body": "This plan includes all features at the lowest per-user cost"
-  },
-  "placement": "top",
-  "trigger": "hover",
-  "ctaButtons": [
-    {
-      "label": "Learn More",
-      "actionId": "learn_more_click"
+    "title": "Save 20%",
+    "body": "Switch to annual billing to save on your subscription.",
+    "cta": {
+      "label": "Switch Now",
+      "action": { "kind": "navigate", "url": "/billing?annual=true" }
     }
-  ],
-  "dismiss": {
-    "onEsc": true,
-    "closeButton": true
-  }
+  },
+  "placement": "bottom",
+  "trigger": "immediate"
 }
 ```
 
-**Properties:**
-- `kind`: Must be `"tooltip"`
-- `id`: Unique identifier for tracking
-- `anchor`: Element selector (same as patches)
-- `content.title`: Optional heading text
-- `content.body`: Required tooltip body text
-- `placement`: `"top"`, `"bottom"`, `"left"`, `"right"`, or `"auto"`
-- `trigger`: `"immediate"`, `"hover"`, or `"click"`
-- `offsetPx`: Distance from anchor element (optional)
-- `blocking`: If true, blocks page interaction (optional)
-- `ctaButtons`: Array of action buttons (optional)
-- `dismiss.onEsc`: Close on Escape key
-- `dismiss.closeButton`: Show X button
-- `dismiss.timeoutMs`: Auto-dismiss after milliseconds
-
-### Highlights
-Visual emphasis rings that draw attention to elements.
+### badge
+
+Adds a small badge indicator near an element.
+
+| Property   | Type      | Required | Default       | Description                                                    |
+| ---------- | --------- | -------- | ------------- | -------------------------------------------------------------- |
+| `kind`     | `"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": "highlight",
-  "id": "cta_highlight_1",
-  "anchor": {
-    "by": "css",
-    "value": ".hero-cta button"
-  },
-  "copy": "Click here to get started",
-  "ring": {
-    "paddingPx": 8,
-    "radiusPx": 4
-  },
-  "ringColor": "#3b82f6",
-  "scrim": {
-    "opacity": 0.5
-  },
-  "blocking": true,
-  "dismiss": {
-    "onClickOutside": true,
-    "onEsc": true
-  }
+  "kind": "badge",
+  "anchorId": "#inbox-icon",
+  "text": "5",
+  "position": "top-right"
 }
 ```
 
-**Properties:**
-- `kind`: Must be `"highlight"`
-- `id`: Unique identifier for tracking
-- `anchor`: Element selector (same as patches)
-- `copy`: Text to display near the highlight (optional)
-- `ring.paddingPx`: Space between element and ring
-- `ring.radiusPx`: Corner radius of ring
-- `ringColor`: Color of the highlight ring
-- `scrim.opacity`: Opacity of background dimming (0-1)
-- `blocking`: If true, blocks interaction outside highlight
-- `dismiss.onClickOutside`: Close when clicking outside
-- `dismiss.onEsc`: Close on Escape key
-- `dismiss.timeoutMs`: Auto-dismiss after milliseconds
+### pulse
 
-### Overlay Recipe Structure
+Adds a pulsing animation to draw attention.
 
-Overlays are defined in `overlayRecipe`:
+| Property   | Type      | Required | Default | Description              |
+| ---------- | --------- | -------- | ------- | ------------------------ |
+| `kind`     | `"pulse"` | Yes      |         | Action type              |
+| `anchorId` | string    | Yes      |         | Element selector         |
+| `duration` | number    | No       | `2000`  | Animation duration in ms |
 
 ```json
 {
-  "overlayRecipe": {
-    "id": "onboarding_flow",
-    "version": 1,
-    "routes": ["/dashboard", "/home"],
-    "steps": [
-      { "kind": "tooltip", ... },
-      { "kind": "highlight", ... }
-    ]
-  }
+  "kind": "pulse",
+  "anchorId": ".notification-bell",
+  "duration": 3000
 }
 ```
 
-- `id`: Recipe identifier
-- `version`: Version number for tracking changes
-- `routes`: URL paths where this recipe applies (optional)
-- `steps`: Array of tooltip and highlight steps
+### modal
 
-## Runtime v2 Providers
+Shows a centered modal dialog with optional CTA buttons.
 
-The v2 runtime provides adaptives with a unified interface for context, events, state, and decisions.
+| 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"` |
 
-### SmartCanvasRuntime
+**CTA Button properties:**
 
-Every adaptive receives a `runtime` object:
+- `label`: Button text
+- `actionId`: Identifier for the action
+- `primary`: Whether this is a primary button (default: false)
 
-```typescript
-type SmartCanvasRuntime = {
-  telemetry: TelemetryClient;   // Emit events to PostHog
-  context: ContextManager;       // Subscribe to page/session state
-  events: EventBus;              // Subscribe to normalized events
-  state: StateStore;             // Persist dismissals, cooldowns
-  version: string;
-  mode: "production" | "development";
-};
+```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"
+}
 ```
 
-### Usage
 
-```typescript
-const { canvas, runtime } = await Syntro.init({
-  token: "syn_..."
-});
+---
 
-// Access runtime providers
-runtime.telemetry?.trackAction(...);
-runtime.context.subscribe((ctx, prev) => { ... });
-runtime.events.subscribe({ names: ['ui.click'] }, (event) => { ... });
-runtime.state.dismissals.mark('my-tile');
-```
 
-### Context Manager
+---
 
-Subscribe to runtime context changes:
+## Surfaces
 
-```typescript
-const unsubscribe = runtime.context.subscribe((ctx, prev) => {
-  if (ctx.page.url !== prev.page.url) {
-    // Handle route change
-  }
-});
+Surfaces are named slots where widgets can be mounted. Use the `mount_widget` action to render content into a surface slot.
 
-const ctx = runtime.context.get();
-console.log(ctx.page.url, ctx.session.sessionId);
-```
+### Static Slots
 
-**Available Context:**
-| Field | Type | Description |
-|-------|------|-------------|
-| `page.url` | string | Current page URL |
-| `page.routeId` | string? | Matched route pattern |
-| `page.title` | string? | Document title |
-| `session.sessionId` | string | PostHog session ID |
-| `session.startTs` | number | Session start timestamp |
-| `viewport.width` | number | Viewport width in pixels |
-| `viewport.height` | number | Viewport height in pixels |
-| `anchors` | AnchorState[]? | Tracked anchor visibility |
-
-### Event Bus
-
-Subscribe to normalized events:
-
-```typescript
-const unsubscribe = runtime.events.subscribe(
-  { names: ["ui.click", "nav.page_view"] },
-  (event) => {
-    console.log(event.name, event.props);
-  }
-);
-```
+Fixed-position slots for common UI patterns:
 
-**Event Schema:**
-```typescript
-type NormalizedEvent = {
-  ts: number;           // Timestamp
-  name: string;         // e.g., "ui.click", "canvas.opened"
-  source: "posthog" | "canvas" | "derived";
-  props?: Record<string, any>;
-  schemaVersion: string;
-};
-```
+| 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 |
 
-**Standard Events:**
-| Event | Source | Description |
-|-------|--------|-------------|
-| `ui.click` | posthog | User clicked element |
-| `ui.scroll` | posthog | User scrolled |
-| `nav.page_view` | posthog | Page navigation |
-| `canvas.opened` | canvas | Smart Canvas opened |
-| `canvas.closed` | canvas | Smart Canvas closed |
-| `tile.viewed` | canvas | Tile became visible |
-| `tile.action` | canvas | User clicked tile action |
+### Dynamic Slots
 
-### State Store
+Slots that position content relative to anchors:
 
-Persist state across sessions:
+- **Inline Slots**: Render content inside an anchor element. Format: `inline:{anchorId}`
+- **Adjacent Slots**: Render content positioned near an anchor element. Format: `adjacent:{anchorId}`
 
-```typescript
-// Session storage (cleared on close)
-runtime.state.session.set("lastTileViewed", "tile-123");
-const last = runtime.state.session.get<string>("lastTileViewed");
+---
 
-// User storage (persists across sessions)
-runtime.state.user.set("onboardingComplete", true);
+## Anchor Resolution
 
-// Namespace by adaptive
-const ns = runtime.state.ns("my-adaptive");
-ns.session.set("step", 3);
-```
+The `anchorId` field identifies which DOM element to target. Multiple formats are supported:
 
-**Built-in Helpers:**
-```typescript
-// Track dismissals
-runtime.state.dismissals.mark("tooltip-1");
-if (runtime.state.dismissals.isDismissed("tooltip-1")) { ... }
+### CSS Selectors
 
-// Cooldowns (don't show again for X ms)
-runtime.state.cooldowns.set("promo-banner", 86400000); // 24h
-if (runtime.state.cooldowns.isActive("promo-banner")) { ... }
+| 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` |
 
-// Frequency caps
-runtime.state.frequency.increment("upsell-shown");
-if (runtime.state.frequency.count("upsell-shown") >= 3) { ... }
-```
+### Data Attributes (Recommended)
 
-### Decision Strategies
+For stability, add `data-syntro-anchor` attributes to target elements:
 
-Tile activation uses `DecisionStrategy` for conditional rendering:
+```html
+<h1 data-syntro-anchor="hero-title">Welcome</h1>
+```
+
+Then reference by the anchor name:
 
 ```json
-{
-  "id": "promo-tile",
-  "title": "Limited Offer",
-  "activation": {
-    "routes": { "include": ["/pricing", "/upgrade"] },
-    "strategy": {
-      "type": "rules",
-      "rules": [
-        {
-          "conditions": [
-            { "type": "viewport", "minWidth": 768 },
-            { "type": "dismissed", "key": "promo-tile", "inverted": true }
-          ],
-          "value": true
-        }
-      ],
-      "default": false
-    }
-  }
-}
+{ "anchorId": "hero-title" }
 ```
 
-**Strategy Types:**
-| Type | Description |
-|------|-------------|
-| `rules` | Condition-based matching (if/then) |
-| `score` | Threshold on augmented field |
-| `model` | ML model prediction (future) |
-| `external` | Remote decision endpoint (future) |
-
-**Condition Types:**
-| Condition | Parameters | Description |
-|-----------|------------|-------------|
-| `page_url` | `url` (pattern) | URL matches pattern |
-| `route` | `routeId` | Route ID matches |
-| `anchor_visible` | `anchorId`, `state` | Anchor visibility state |
-| `event_occurred` | `eventName`, `withinMs?` | Event happened recently |
-| `state_equals` | `key`, `value` | State value matches |
-| `viewport` | `minWidth?`, `maxWidth?` | Viewport size range |
-| `session_metric` | `key`, `operator`, `threshold` | Session metric comparison |
-| `dismissed` | `key`, `inverted?` | Item has been dismissed |
-| `cooldown_active` | `key`, `inverted?` | Cooldown is active |
-| `frequency_limit` | `key`, `limit`, `inverted?` | Frequency cap reached |
+---
 
-### Migration from v1
+## Decision Strategies
 
-The new `activation` field replaces the deprecated `experiment` field:
+Control when adaptives activate using `DecisionStrategy`:
 
-**Before (v1):**
-```json
-{
-  "experiment": {
-    "featureKey": "my-feature",
-    "variationId": 1
-  }
-}
-```
+### Rules Strategy
 
-**After (v2):**
 ```json
 {
-  "activation": {
-    "strategy": {
-      "type": "rules",
-      "rules": [
-        {
-          "conditions": [
-            { "type": "route", "routeId": "/dashboard" }
-          ],
-          "value": true
-        }
+  "type": "rules",
+  "rules": [
+    {
+      "conditions": [
+        { "type": "page_url", "pattern": "/pricing*" },
+        { "type": "viewport", "minWidth": 768 },
+        { "type": "dismissed", "key": "promo", "inverted": true }
       ],
-      "default": false
+      "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. Element Selection
-- Use the most specific selector that won't break
-- Prefer data attributes over classes for stability
-- Test selectors across different page states
+### 1. Choose the Right Action Type
 
-### 2. Tier Selection
-- Start with the lowest tier that works
-- Only use `surgical` when modifying text
-- Document why a specific tier is needed
+| Goal | Action |
+|------|--------|
+| Change text | `set_text` |
+| Add visual indicator | `badge`, `pulse` |
+| Show help text | `tooltip` |
+| Draw attention | `highlight` |
+| Add content | `insert_html` |
+| Navigate user | `scroll_to`, `navigate` |
+| Show UI panel | `mount_widget` + Surfaces |
 
-### 3. Operation Order
-- Operations are applied in array order
-- Plan sequences carefully (e.g., addClass before setStyle)
-- Test operation combinations
+### 2. Anchor Selection
 
-### 4. Performance
-- Batch related patches together
-- Avoid selecting too many elements
-- Use CSS classes instead of inline styles when possible
+- **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
 
-### 5. Compatibility
-- All HTML is sanitized to prevent XSS
-- Classes must be prefixed to avoid conflicts
-- Test across different browsers and devices
+### 3. Reversibility
 
-## Example: Complete A/B Test
+- Always store handles if you need to revert
+- Use `applyBatch` for related changes (atomic rollback)
+- Clean up on route changes
 
-```json
-{
-  "configVersion": "1.0",
-  "patches": [
-    {
-      "id": "hero_headline_test",
-      "anchor": {
-        "by": "css",
-        "value": "h1.hero-title"
-      },
-      "tier": "surgical",
-      "operations": [
-        {
-          "kind": "setText",
-          "text": "Start Your Free Trial Today"
-        },
-        {
-          "kind": "addClass",
-          "className": "syntro-tested"
-        }
-      ]
-    },
-    {
-      "id": "cta_enhancement",
-      "anchor": {
-        "by": "data",
-        "key": "testid",
-        "value": "primary-cta"
-      },
-      "tier": "additive",
-      "operations": [
-        {
-          "kind": "setStyle",
-          "prop": "boxShadow",
-          "value": "0 4px 6px rgba(0,0,0,0.1)"
-        },
-        {
-          "kind": "append",
-          "html": "<span class='syntro-arrow'>→</span>"
-        }
-      ]
-    }
-  ]
-}
-```
+### 4. Performance
+
+- Batch related actions together
+- Use `validate()` to check actions before applying
+- Avoid applying many actions simultaneously
+
+### 5. Events
 
-This example:
-1. Changes the hero headline text (requires surgical tier)
-2. Enhances the CTA button with shadow and an arrow icon (uses additive tier)
-3. Properly tracks both changes with IDs
+- Listen for `action.failed` to handle errors
+- Track `action.applied` for analytics
+- Use EventBus for cross-adaptive coordination