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

package/schema/canvas-config.schema.json

@@ -4989,7 +4989,7 @@
             "additionalProperties": false
           },
           "default": [],
-          "description": "The FAQ items rendered by the accordion. Each item is a faq:question compositional action."
+          "description": "The FAQ items rendered by the accordion. Each item is a faq:question compositional action — these are configuration data rendered by the widget, not actions executed by the runtime. This compositional pattern enables per-item conditional visibility via triggerWhen, category grouping, and dynamic injection."
         },
         "feedback": {
           "anyOf": [
@@ -7429,5 +7429,356 @@
       "$el_text": "Visible text content of the element",
       "attr__*": "HTML attribute prefixed with attr__. Example: attr__data-id matches the data-id attribute, attr__class matches the class attribute, attr__href matches the href attribute."
     }
+  },
+  "_capabilitiesDocumentation": {
+    "adaptive-content": {
+      "packageId": "adaptive-content",
+      "description": "DOM content modification capabilities for text, attributes, styles, HTML, and classes.",
+      "whenToUse": [
+        {
+          "goal": "Replace an element's text",
+          "action": "content:setText"
+        },
+        {
+          "goal": "Change an HTML attribute (href, src, data-*)",
+          "action": "content:setAttr"
+        },
+        {
+          "goal": "Modify inline styles (color, size, spacing)",
+          "action": "content:setStyle"
+        },
+        {
+          "goal": "Inject new HTML before/after/inside an element",
+          "action": "content:insertHtml"
+        },
+        {
+          "goal": "Add a CSS class (show/hide, animate)",
+          "action": "content:addClass"
+        },
+        {
+          "goal": "Remove a CSS class",
+          "action": "content:removeClass"
+        }
+      ],
+      "conventions": [
+        {
+          "name": "Deep-linking inserted content to canvas tiles",
+          "description": "Use the deepLink property on content:insertHtml to make inserted elements open the canvas panel and navigate to a specific tile when clicked. NEVER use onclick handlers or window.SynOS in HTML strings — they are sanitized and stripped. deepLink is the only supported mechanism."
+        },
+        {
+          "name": "Blocked attributes",
+          "description": "Event handler attributes (onclick, onerror, onload, etc.) are blocked by content:setAttr. Use data-* attributes for experiment markers instead."
+        }
+      ],
+      "events": []
+    },
+    "adaptive-faq": {
+      "packageId": "adaptive-faq",
+      "description": "Collapsible Q&A accordion with actions, rich content, feedback, and personalization.",
+      "whenToUse": [
+        {
+          "goal": "Add an FAQ accordion widget",
+          "action": "Add a tile with widget: \"adaptive-faq:accordion\""
+        },
+        {
+          "goal": "Scroll to and expand a specific FAQ item",
+          "action": "faq:scroll_to"
+        },
+        {
+          "goal": "Open, close, or toggle a FAQ item",
+          "action": "faq:toggle_item"
+        },
+        {
+          "goal": "Add, remove, reorder, or replace FAQ items",
+          "action": "faq:update"
+        }
+      ],
+      "conventions": [
+        {
+          "name": "Compositional action pattern",
+          "description": "faq:question actions are configuration data rendered by the accordion widget, not actions executed by the runtime. This allows per-item conditional visibility via triggerWhen, category grouping under collapsible section headers, and dynamic injection of contextual items."
+        },
+        {
+          "name": "Rich answer content formats",
+          "description": "FAQ answers support three formats: plain string (simple text with basic markdown), rich HTML ({ \"type\": \"rich\", \"html\": \"<p>...</p>\" } for pre-rendered content), or enhanced markdown ({ \"type\": \"markdown\", \"content\": \"...\", \"assets\": [...] } with embedded media via asset:<id> URIs)."
+        },
+        {
+          "name": "Companion overlay tooltips",
+          "description": "FAQ questions can be surfaced proactively using overlays:tooltip with ctaButtons. Set the CTA actionId to \"faq:open:<questionId>\" — the FAQ widget listens for action.tooltip_cta_clicked events with this pattern and expands the matching question. Late-mount support: if the widget mounts after the click, it checks EventBus history (within 10 seconds) and auto-expands."
+        },
+        {
+          "name": "Feedback events",
+          "description": "When feedback is enabled, user feedback events are published via context.publishEvent for analytics integration."
+        }
+      ],
+      "events": [
+        {
+          "name": "faq:feedback_submitted",
+          "when": "User submits feedback on a FAQ answer",
+          "props": "{ questionId, style, value }"
+        }
+      ]
+    },
+    "adaptive-mcp": {
+      "packageId": "adaptive-mcp",
+      "description": "Loader adaptive for the MCP Apps protocol. Currently a pure loader — no actions, widgets, or surfaces yet.",
+      "whenToUse": [],
+      "conventions": [],
+      "events": []
+    },
+    "adaptive-nav": {
+      "packageId": "adaptive-nav",
+      "description": "Navigation tips accordion widget with conditional item visibility and toast notifications.",
+      "whenToUse": [
+        {
+          "goal": "Show contextual navigation tips widget",
+          "action": "Add a tile with widget: \"adaptive-nav:tips\""
+        },
+        {
+          "goal": "Scroll to an element on the page",
+          "action": "navigation:scrollTo"
+        },
+        {
+          "goal": "Navigate to a different URL",
+          "action": "navigation:navigate"
+        }
+      ],
+      "conventions": [
+        {
+          "name": "Notify watchers",
+          "description": "Tips with both triggerWhen and notify are registered as notify watchers. The runtime evaluates these continuously even when the drawer is closed. When triggerWhen transitions false → true, the widget publishes nav:tip_revealed which can trigger toast notifications via tile-level notifications rules."
+        }
+      ],
+      "events": [
+        {
+          "name": "nav:toggled",
+          "when": "User expands or collapses a tip",
+          "props": "{ instanceId, tipId, expanded }"
+        },
+        {
+          "name": "nav:tip_clicked",
+          "when": "User clicks a tip's CTA link",
+          "props": "{ instanceId, href, external }"
+        },
+        {
+          "name": "nav:tip_revealed",
+          "when": "triggerWhen transitions false → true",
+          "props": "{ tipId, title, body, icon }"
+        }
+      ]
+    },
+    "adaptive-overlays": {
+      "packageId": "adaptive-overlays",
+      "description": "Visual overlay capabilities including highlights, tooltips, badges, pulse animations, modals, tours, and celebrations.",
+      "whenToUse": [
+        {
+          "goal": "Draw attention to an element (spotlight)",
+          "action": "overlays:highlight"
+        },
+        {
+          "goal": "Show contextual help or guidance near an element",
+          "action": "overlays:tooltip"
+        },
+        {
+          "goal": "Add a notification indicator (count, \"NEW\")",
+          "action": "overlays:badge"
+        },
+        {
+          "goal": "Subtle attention-grab animation",
+          "action": "overlays:pulse"
+        },
+        {
+          "goal": "Show a blocking or non-blocking dialog",
+          "action": "overlays:modal"
+        },
+        {
+          "goal": "Celebrate a user achievement",
+          "action": "overlays:celebrate"
+        },
+        {
+          "goal": "Multi-step guided walkthrough",
+          "action": "overlays:tour"
+        }
+      ],
+      "conventions": [
+        {
+          "name": "Tooltip actionId: \"dismiss\"",
+          "description": "The special actionId \"dismiss\" closes the tooltip immediately without publishing an event. Use for \"close\" or \"not now\" buttons."
+        },
+        {
+          "name": "Companion FAQ tooltips (faq:open:<questionId>)",
+          "description": "A tooltip CTA with actionId \"faq:open:<questionId>\" publishes action.tooltip_cta_clicked, which the adaptive-faq:accordion widget listens for. The matching FAQ question expands and scrolls into view. If the FAQ widget mounts after the click (e.g. canvas was closed), it checks EventBus history for recent faq:open:* events (within 10 seconds) and auto-expands on mount. The widget also publishes canvas.requestOpen to open the canvas panel if needed."
+        },
+        {
+          "name": "Celebrate effect presets",
+          "description": "Available effects: \"confetti\" (falling rectangular/circular pieces with gravity and rotation), \"fireworks\" (burst centers with radiating particles and glow), \"sparkles\" (diamond shapes with sine-wave opacity and upward float), \"emoji-rain\" (emoji characters falling with horizontal wobble — set props.emoji to customize the character)."
+        }
+      ],
+      "events": [
+        {
+          "name": "action.tooltip_cta_clicked",
+          "when": "User clicks a tooltip CTA button",
+          "props": "{ actionId }"
+        },
+        {
+          "name": "action.modal_cta_clicked",
+          "when": "User clicks a modal CTA button",
+          "props": "{ actionId }"
+        }
+      ]
+    },
+    "adaptive-viz": {
+      "packageId": "adaptive-viz",
+      "description": "Charts and tables for visualizing data — bar, line, table, and pie layouts.",
+      "whenToUse": [
+        {
+          "goal": "Show a bar chart (categorical x, quantitative y)",
+          "action": "Add a tile with widget: \"adaptive-viz:chart\" and layout: \"bar\""
+        },
+        {
+          "goal": "Show a line chart (continuous x, quantitative y)",
+          "action": "Add a tile with widget: \"adaptive-viz:chart\" and layout: \"line\""
+        },
+        {
+          "goal": "Show tabular data with rich cell renderers",
+          "action": "Add a tile with widget: \"adaptive-viz:chart\" and layout: \"table\""
+        },
+        {
+          "goal": "Show a pie/donut chart (part-of-whole)",
+          "action": "Add a tile with widget: \"adaptive-viz:chart\" and layout: \"pie\""
+        }
+      ],
+      "conventions": [
+        {
+          "name": "Theme tokens",
+          "description": "Charts consume CSS custom properties from the canvas theme: --sc-color-primary, --sc-color-primary-hover, --sc-overlay-text-color, --sc-font-family, --sc-tile-background. These map to Vega-Lite config properties internally."
+        },
+        {
+          "name": "Inline data only",
+          "description": "All data must be provided inline in the data array. External URLs are not supported by design — data must be self-contained."
+        }
+      ],
+      "events": []
+    }
+  },
+  "_sdkDocumentation": {
+    "surfaces": {
+      "description": "Surfaces are named slots where widgets can be mounted.",
+      "staticSlots": [
+        {
+          "slot": "drawer_right",
+          "position": "Right edge, full height",
+          "useCase": "Settings panels, details"
+        },
+        {
+          "slot": "drawer_left",
+          "position": "Left edge, full height",
+          "useCase": "Navigation, filters"
+        },
+        {
+          "slot": "drawer_bottom",
+          "position": "Bottom edge, full width",
+          "useCase": "Action sheets, keyboards"
+        },
+        {
+          "slot": "overlay_center",
+          "position": "Centered modal",
+          "useCase": "Dialogs, confirmations"
+        },
+        {
+          "slot": "overlay_corner_br",
+          "position": "Bottom-right corner",
+          "useCase": "Chat widgets, help"
+        },
+        {
+          "slot": "overlay_corner_bl",
+          "position": "Bottom-left corner",
+          "useCase": "Notifications"
+        },
+        {
+          "slot": "toast_top",
+          "position": "Top center",
+          "useCase": "Success/error messages"
+        },
+        {
+          "slot": "toast_bottom",
+          "position": "Bottom center",
+          "useCase": "Snackbar notifications"
+        }
+      ]
+    },
+    "anchorResolution": {
+      "description": "The anchorId field identifies which DOM element to target. It is always an object with { selector, route } — never a plain string.",
+      "selectorFormats": [
+        {
+          "format": "Class",
+          "example": ".hero-title",
+          "matches": "<h1 class=\"hero-title\">"
+        },
+        {
+          "format": "ID",
+          "example": "#signup-button",
+          "matches": "<button id=\"signup-button\">"
+        },
+        {
+          "format": "Attribute",
+          "example": "[data-testid='cta']",
+          "matches": "<button data-testid=\"cta\">"
+        },
+        {
+          "format": "Tag + class",
+          "example": "h1.page-title",
+          "matches": "<h1 class=\"page-title\">"
+        },
+        {
+          "format": "Nested",
+          "example": ".card .title",
+          "matches": "<div class=\"title\"> inside .card"
+        }
+      ],
+      "bestPractices": [
+        "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"
+      ]
+    },
+    "routeScoping": {
+      "description": "Every tile and action must declare which pages it applies to via activation.routes.",
+      "patterns": [
+        {
+          "pattern": "/dashboard/income",
+          "matches": "Exact path only",
+          "useCase": "Page-specific"
+        },
+        {
+          "pattern": "/dashboard/**",
+          "matches": "/dashboard and all sub-paths",
+          "useCase": "Section-wide"
+        },
+        {
+          "pattern": "/**",
+          "matches": "All pages",
+          "useCase": "Global (always active)"
+        },
+        {
+          "pattern": "/dashboard/:id",
+          "matches": "Any single segment after /dashboard/",
+          "useCase": "Dynamic routes"
+        }
+      ],
+      "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"
+      ]
+    },
+    "bestPractices": [
+      "NEVER use onclick handlers or window.SynOS in HTML strings — use deepLink instead",
+      "Batch related actions together for atomic rollback",
+      "Use validate() to check actions before applying",
+      "Listen for action.failed to handle errors",
+      "Track action.applied for analytics"
+    ]
   }
 }