@syntrologie/runtime-sdk 1.0.1-canary.3 → 2.0.0-canary.1

package/CAPABILITIES.md

@@ -1,611 +1,778 @@
 # 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"
+    }
+  ]
+}
+```
+
+---
+
+## Adaptive Packages
 
-## Policy Tiers
+The SDK includes the following adaptive packages, each providing specific capabilities:
 
-The SDK uses three policy tiers to control what operations are allowed:
+- [@syntrologie/app-content](#syntrologieapp-content)
+- [@syntrologie/app-faq](#syntrologieapp-faq)
+- [@syntrologie/app-gamification](#syntrologieapp-gamification)
+- [@syntrologie/app-nav](#syntrologieapp-nav)
+- [@syntrologie/app-navigation](#syntrologieapp-navigation)
+- [@syntrologie/app-overlays](#syntrologieapp-overlays)
 
-### 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
+---
 
-### 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
+# @syntrologie/app-content
 
-### 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
+DOM content modification capabilities for text, attributes, styles, HTML, and classes.
 
-## Anchor Selectors
+## Actions
 
-Anchors define how to find elements in the DOM. The SDK supports four types:
+### 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 |
 
-### 1. CSS Selector
 ```json
 {
-  "by": "css",
-  "value": "h1.hero-title"
+  "kind": "set_text",
+  "anchorId": "h1.hero-title",
+  "text": "Start Your Free Trial Today"
 }
 ```
-- **Use**: Standard CSS selectors
-- **Example**: `"h1"`, `".button-primary"`, `"#hero-section h2"`
 
-### 2. Data Attribute
+### 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": "data",
-  "key": "testid",
-  "value": "hero-banner"  // optional
+  "kind": "set_attr",
+  "anchorId": "#signup-form",
+  "attr": "data-experiment",
+  "value": "signup-v2"
 }
 ```
-- **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_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": "aria",
-  "role": "button",     // optional
-  "label": "Submit"     // optional
+  "kind": "set_style",
+  "anchorId": ".hero-section",
+  "styles": {
+    "background-color": "#1e40af",
+    "padding": "2rem"
+  }
 }
 ```
-- **Use**: Target accessible elements
-- **Example**: Finds `<button role="button" aria-label="Submit">`
-- **Note**: Can use role, label, or both
 
-### 4. Element Reference
+### 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
+
 ```json
 {
-  "by": "ref",
-  "el": elementReference
+  "kind": "insert_html",
+  "anchorId": ".cta-button",
+  "html": "<span class=\"badge\">NEW</span>",
+  "position": "append"
 }
 ```
-- **Use**: Direct element reference (programmatic use only)
-- **Note**: Cannot be serialized in JSON configs
 
-## Operations
+### 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 |
 
-### 1. setText
-**Purpose**: Replace the text content of an element
 ```json
 {
-  "kind": "setText",
-  "text": "New headline text"
+  "kind": "add_class",
+  "anchorId": ".pricing-card",
+  "className": "highlighted"
 }
 ```
-- **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
+### 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": "setStyle",
-  "prop": "backgroundColor",
-  "value": "#ff0000",
-  "important": true  // optional, adds !important
+  "kind": "remove_class",
+  "anchorId": ".pricing-card",
+  "className": "hidden"
 }
 ```
-- **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
+
+
+---
+
+# @syntrologie/app-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": "addClass",
-  "className": "syntro-highlight"
+  "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**: 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
+## 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/app-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": "removeClass",
-  "className": "syntro-hidden"
+  "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
+    }
+  }
 }
 ```
-- **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
+## 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/app-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": "setAttr",
-  "name": "data-tracked",
-  "value": "true"  // or null to remove
+  "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
+        }
+      }
+    ]
+  }
 }
 ```
-- **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
+
+## 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/app-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": "append",
-  "html": "<span class='syntro-badge'>NEW</span>"
+  "kind": "scroll_to",
+  "anchorId": "#pricing-section",
+  "behavior": "smooth",
+  "block": "start"
 }
 ```
-- **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
+### 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/app-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
+Adds a pulsing animation to draw attention.
 
-### Overlay Recipe Structure
-
-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
+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)
 
-## Runtime v2 Providers
+```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"
+}
+```
 
-The v2 runtime provides adaptives with a unified interface for context, events, state, and decisions.
 
-### SmartCanvasRuntime
+---
 
-Every adaptive receives a `runtime` object:
 
-```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";
-};
-```
+---
 
-### Usage
+## Surfaces
 
-```typescript
-const { canvas, runtime } = await Syntro.init({
-  token: "syn_..."
-});
+Surfaces are named slots where widgets can be mounted. Use the `mount_widget` action to render content into a surface slot.
 
-// Access runtime providers
-runtime.telemetry?.trackAction(...);
-runtime.context.subscribe((ctx, prev) => { ... });
-runtime.events.subscribe({ names: ['ui.click'] }, (event) => { ... });
-runtime.state.dismissals.mark('my-tile');
-```
+### Static Slots
 
-### Context Manager
+Fixed-position slots for common UI patterns:
 
-Subscribe to runtime context changes:
+| 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 |
 
-```typescript
-const unsubscribe = runtime.context.subscribe((ctx, prev) => {
-  if (ctx.page.url !== prev.page.url) {
-    // Handle route change
-  }
-});
+### Dynamic Slots
 
-const ctx = runtime.context.get();
-console.log(ctx.page.url, ctx.session.sessionId);
-```
+Slots that position content relative to anchors:
 
-**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);
-  }
-);
-```
+- **Inline Slots**: Render content inside an anchor element. Format: `inline:{anchorId}`
+- **Adjacent Slots**: Render content positioned near an anchor element. Format: `adjacent:{anchorId}`
 
-**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;
-};
-```
+---
 
-**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 |
+## Anchor Resolution
 
-### State Store
+The `anchorId` field identifies which DOM element to target. Multiple formats are supported:
 
-Persist state across sessions:
+### CSS Selectors
 
-```typescript
-// Session storage (cleared on close)
-runtime.state.session.set("lastTileViewed", "tile-123");
-const last = runtime.state.session.get<string>("lastTileViewed");
+| 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` |
 
-// User storage (persists across sessions)
-runtime.state.user.set("onboardingComplete", true);
+### Data Attributes (Recommended)
 
-// Namespace by adaptive
-const ns = runtime.state.ns("my-adaptive");
-ns.session.set("step", 3);
-```
+For stability, add `data-syntro-anchor` attributes to target elements:
 
-**Built-in Helpers:**
-```typescript
-// Track dismissals
-runtime.state.dismissals.mark("tooltip-1");
-if (runtime.state.dismissals.isDismissed("tooltip-1")) { ... }
+```html
+<h1 data-syntro-anchor="hero-title">Welcome</h1>
+```
 
-// Cooldowns (don't show again for X ms)
-runtime.state.cooldowns.set("promo-banner", 86400000); // 24h
-if (runtime.state.cooldowns.isActive("promo-banner")) { ... }
+Then reference by the anchor name:
 
-// Frequency caps
-runtime.state.frequency.increment("upsell-shown");
-if (runtime.state.frequency.count("upsell-shown") >= 3) { ... }
+```json
+{ "anchorId": "hero-title" }
 ```
 
-### Decision Strategies
+---
+
+## Decision Strategies
 
-Tile activation uses `DecisionStrategy` for conditional rendering:
+Control when adaptives activate using `DecisionStrategy`:
+
+### Rules Strategy
 
 ```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
-        }
+  "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
 }
 ```
 
-**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 |
+### Condition Types
+
+| Type | Parameters | Description |
+|------|------------|-------------|
+| `page_url` | `pattern` | URL matches glob 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 |
+| `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 |
 
-### Migration from v1
+---
 
-The new `activation` field replaces the deprecated `experiment` field:
+## Best Practices
 
-**Before (v1):**
-```json
-{
-  "experiment": {
-    "featureKey": "my-feature",
-    "variationId": 1
-  }
-}
-```
+### 1. Choose the Right Action Type
 
-**After (v2):**
-```json
-{
-  "activation": {
-    "strategy": {
-      "type": "rules",
-      "rules": [
-        {
-          "conditions": [
-            { "type": "route", "routeId": "/dashboard" }
-          ],
-          "value": true
-        }
-      ],
-      "default": false
-    }
-  }
-}
-```
+| 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 |
 
-## Best Practices
+### 2. Anchor Selection
 
-### 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
+- **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
 
-### 2. Tier Selection
-- Start with the lowest tier that works
-- Only use `surgical` when modifying text
-- Document why a specific tier is needed
+### 3. Reversibility
 
-### 3. Operation Order
-- Operations are applied in array order
-- Plan sequences carefully (e.g., addClass before setStyle)
-- Test operation combinations
+- Always store handles if you need to revert
+- Use `applyBatch` for related changes (atomic rollback)
+- Clean up on route changes
 
 ### 4. Performance
-- Batch related patches together
-- Avoid selecting too many elements
-- Use CSS classes instead of inline styles when possible
 
-### 5. Compatibility
-- All HTML is sanitized to prevent XSS
-- Classes must be prefixed to avoid conflicts
-- Test across different browsers and devices
+- Batch related actions together
+- Use `validate()` to check actions before applying
+- Avoid applying many actions simultaneously
 
-## Example: Complete A/B Test
-
-```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>"
-        }
-      ]
-    }
-  ]
-}
-```
+### 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