@syntrologie/runtime-sdk 0.2.21 → 1.0.0

package/schema/canvas-config.schema.json

@@ -2,346 +2,580 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://syntropyforge.com/schemas/smart-canvas-config.json",
   "title": "Smart Canvas Configuration",
+  "description": "Action-based configuration for Smart Canvas. All interventions are unified as ActionStep.",
   "type": "object",
-  "required": ["fetchedAt", "rectangles"],
+  "required": ["fetchedAt", "tiles", "actions"],
   "properties": {
     "fetchedAt": {
       "type": "string",
-      "format": "date-time"
+      "format": "date-time",
+      "description": "When the config was fetched"
     },
     "configVersion": {
-      "type": "string"
+      "type": "string",
+      "description": "Version string for cache invalidation"
     },
     "canvasTitle": {
-      "type": "string"
-    },
-    "overlayRecipeUri": {
       "type": "string",
-      "description": "Optional URI pointing to tooltip/highlight recipe"
+      "description": "Display title for the canvas"
     },
-    "overlayRecipe": {
-      "type": "object",
-      "description": "Inline overlay recipe (for testing)",
-      "properties": {
-        "id": { "type": "string" },
-        "version": { "type": "number" },
-        "routes": { "type": "array", "items": { "type": "string" } },
-        "steps": {
-          "type": "array",
-          "items": { "oneOf": [
-            { "$ref": "#/$defs/tooltipStep" },
-            { "$ref": "#/$defs/highlightStep" }
-          ] }
-        }
-      },
-      "required": ["id", "version", "steps"],
-      "additionalProperties": false
-    },
-    "patches": {
+    "tiles": {
       "type": "array",
-      "description": "Optional host DOM patches to apply when the canvas renders",
-      "items": {
-        "$ref": "#/$defs/patch"
-      }
+      "description": "Tiles to display in the canvas drawer",
+      "items": { "$ref": "#/$defs/tile" }
     },
-    "rectangles": {
+    "actions": {
       "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["id", "title", "content"],
-        "properties": {
-          "id": { "type": "string" },
-          "title": { "type": "string" },
-          "subtitle": { "type": "string" },
-          "icon": { "type": "string" },
-          "size": { "type": "string", "enum": ["half", "quarter"] },
-          "order": { "type": "number" },
-          "style": {
-            "type": "object",
-            "properties": {
-              "background": { "type": "string" },
-              "borderColor": { "type": "string" },
-              "textColor": { "type": "string" },
-              "accentColor": { "type": "string" }
-            },
-            "additionalProperties": false
-          },
-          "content": {
-            "type": "object",
-            "required": ["type"],
-            "properties": {
-              "type": {
-                "type": "string",
-                "enum": ["text", "metric", "chatbot", "embed", "custom"]
-              },
-              "headline": { "type": "string" },
-              "body": { "type": "string" },
-              "metricValue": { "type": "string" },
-              "metricUnit": { "type": "string" },
-              "embedUrl": { "type": "string" },
-              "customRendererKey": { "type": "string" },
-              "actions": {
-                "type": "array",
-                "items": {
-                  "type": "object",
-                  "required": ["label"],
-                  "properties": {
-                    "label": { "type": "string" },
-                    "href": { "type": "string" },
-                    "onClickId": { "type": "string" }
-                  },
-                  "additionalProperties": false
-                }
-              }
-            },
-            "additionalProperties": false
-          },
-          "experiment": {
-            "type": "object",
-            "description": "DEPRECATED: Use activation.strategy instead",
-            "properties": {
-              "featureKey": { "type": "string" },
-              "variationId": { "type": "number" },
-              "variationValue": {},
-              "predicate": {}
-            },
-            "additionalProperties": true
-          },
-          "activation": {
-            "$ref": "#/$defs/activationConfig",
-            "description": "v2 activation config for conditional rendering"
-          },
-          "analyticsKey": { "type": "string" }
-        },
-        "additionalProperties": false
-      }
+      "description": "Actions to execute. This is the unified intervention format - every DOM change, tooltip, highlight, or modal is an ActionStep.",
+      "items": { "$ref": "#/$defs/actionStep" }
+    },
+    "theme": {
+      "$ref": "#/$defs/themeConfig",
+      "description": "Theme configuration"
+    },
+    "launcher": {
+      "$ref": "#/$defs/launcherConfig",
+      "description": "Launcher button configuration"
+    },
+    "routes": {
+      "$ref": "#/$defs/routesConfig",
+      "description": "Route filtering"
     }
   },
   "additionalProperties": false,
   "$defs": {
-    "anchorSelector": {
+    "tile": {
       "type": "object",
-      "oneOf": [
-        {
-          "required": ["type", "value"],
-          "properties": {
-            "type": { "const": "css" },
-            "value": { "type": "string" }
-          },
-          "additionalProperties": false
-        },
-        {
-          "required": ["type", "key"],
+      "required": ["id", "title", "content"],
+      "properties": {
+        "id": { "type": "string" },
+        "title": { "type": "string" },
+        "subtitle": { "type": "string" },
+        "icon": { "type": "string" },
+        "size": { "type": "string", "enum": ["full", "half", "quarter"] },
+        "order": { "type": "number" },
+        "expandable": { "type": "boolean" },
+        "defaultExpanded": { "type": "boolean" },
+        "style": {
+          "type": "object",
           "properties": {
-            "type": { "const": "data" },
-            "key": { "type": "string" },
-            "value": { "type": "string" }
+            "background": { "type": "string" },
+            "borderColor": { "type": "string" },
+            "textColor": { "type": "string" },
+            "accentColor": { "type": "string" }
           },
           "additionalProperties": false
         },
-        {
-          "required": ["type"],
-          "properties": {
-            "type": { "const": "aria" },
-            "role": { "type": "string" },
-            "label": { "type": "string" }
-          },
-          "additionalProperties": false
+        "content": { "$ref": "#/$defs/tileContent" },
+        "activation": {
+          "$ref": "#/$defs/activationConfig",
+          "description": "Activation config for conditional rendering"
         },
-        {
-          "required": ["type", "value"],
-          "properties": {
-            "type": { "const": "shadow-css" },
-            "value": { "type": "string" }
-          },
-          "additionalProperties": false
+        "analyticsKey": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "tileContent": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "text",
+            "metric",
+            "chatbot",
+            "embed",
+            "custom",
+            "alert",
+            "success",
+            "warning",
+            "info",
+            "error",
+            "video",
+            "gallery",
+            "code",
+            "form",
+            "rating",
+            "progress",
+            "survey",
+            "checklist",
+            "stats",
+            "comparison",
+            "chart",
+            "table"
+          ]
         },
-        {
-          "required": ["type"],
-          "properties": {
-            "type": { "const": "ref" },
-            "el": {}
-          },
-          "additionalProperties": false
+        "headline": { "type": "string" },
+        "body": { "type": "string" },
+        "metricValue": { "type": "string" },
+        "metricUnit": { "type": "string" },
+        "embedUrl": { "type": "string" },
+        "component": { "type": "string", "description": "Custom component name" },
+        "actions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["label"],
+            "properties": {
+              "label": { "type": "string" },
+              "href": { "type": "string" },
+              "onClickId": { "type": "string" }
+            },
+            "additionalProperties": false
+          }
         }
-      ]
+      },
+      "additionalProperties": true
     },
-    "operation": {
+    "actionStep": {
       "oneOf": [
-        {
+        { "$ref": "#/$defs/setText" },
+        { "$ref": "#/$defs/setAttr" },
+        { "$ref": "#/$defs/addClass" },
+        { "$ref": "#/$defs/removeClass" },
+        { "$ref": "#/$defs/setStyle" },
+        { "$ref": "#/$defs/insertHtml" },
+        { "$ref": "#/$defs/tooltip" },
+        { "$ref": "#/$defs/highlight" },
+        { "$ref": "#/$defs/pulse" },
+        { "$ref": "#/$defs/badge" },
+        { "$ref": "#/$defs/modal" },
+        { "$ref": "#/$defs/scrollTo" },
+        { "$ref": "#/$defs/navigate" },
+        { "$ref": "#/$defs/mountWidget" },
+        { "$ref": "#/$defs/wait" },
+        { "$ref": "#/$defs/sequence" },
+        { "$ref": "#/$defs/parallel" },
+        { "$ref": "#/$defs/tour" }
+      ]
+    },
+    "setText": {
+      "type": "object",
+      "required": ["kind", "anchorId", "text"],
+      "properties": {
+        "kind": { "const": "content:setText" },
+        "anchorId": { "type": "string", "description": "CSS selector for target element" },
+        "text": { "type": "string" },
+        "label": { "type": "string", "description": "Identifier for this action" }
+      },
+      "additionalProperties": false
+    },
+    "setAttr": {
+      "type": "object",
+      "required": ["kind", "anchorId", "attr", "value"],
+      "properties": {
+        "kind": { "const": "content:setAttr" },
+        "anchorId": { "type": "string" },
+        "attr": { "type": "string" },
+        "value": { "type": ["string", "null"] },
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "addClass": {
+      "type": "object",
+      "required": ["kind", "anchorId", "className"],
+      "properties": {
+        "kind": { "const": "content:addClass" },
+        "anchorId": { "type": "string" },
+        "className": { "type": "string" },
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "removeClass": {
+      "type": "object",
+      "required": ["kind", "anchorId", "className"],
+      "properties": {
+        "kind": { "const": "content:removeClass" },
+        "anchorId": { "type": "string" },
+        "className": { "type": "string" },
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "setStyle": {
+      "type": "object",
+      "required": ["kind", "anchorId", "styles"],
+      "properties": {
+        "kind": { "const": "content:setStyle" },
+        "anchorId": { "type": "string" },
+        "styles": {
           "type": "object",
-          "required": ["kind"],
-          "properties": {
-            "kind": { "const": "append" },
-            "html": { "type": "string" },
-            "position": { "type": "string" }
-          },
-          "additionalProperties": false
+          "additionalProperties": { "type": "string" }
         },
-        {
-          "type": "object",
-          "required": ["kind"],
-          "properties": {
-            "kind": { "const": "prepend" },
-            "html": { "type": "string" }
-          },
-          "additionalProperties": false
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "insertHtml": {
+      "type": "object",
+      "required": ["kind", "anchorId", "html"],
+      "properties": {
+        "kind": { "const": "content:insertHtml" },
+        "anchorId": { "type": "string" },
+        "html": { "type": "string" },
+        "position": {
+          "type": "string",
+          "enum": ["beforebegin", "afterbegin", "beforeend", "afterend", "replace"],
+          "default": "beforeend"
         },
-        {
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "ctaButton": {
+      "type": "object",
+      "required": ["label", "actionId"],
+      "properties": {
+        "label": { "type": "string", "description": "Button text" },
+        "actionId": { "type": "string", "description": "Identifier for the action" },
+        "primary": {
+          "type": "boolean",
+          "description": "Whether this is a primary button",
+          "default": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "tooltip": {
+      "type": "object",
+      "required": ["kind", "anchorId", "content"],
+      "properties": {
+        "kind": { "const": "overlays:tooltip" },
+        "anchorId": { "type": "string" },
+        "content": {
           "type": "object",
-          "required": ["kind", "where"],
+          "required": ["body"],
           "properties": {
-            "kind": { "const": "insertAdjacent" },
-            "where": {
-              "enum": ["beforebegin", "afterbegin", "beforeend", "afterend"]
-            },
-            "html": { "type": "string" }
+            "title": { "type": "string" },
+            "body": { "type": "string" },
+            "ctaButtons": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/ctaButton" },
+              "description": "Multiple CTA buttons for tours"
+            }
           },
           "additionalProperties": false
         },
-        {
+        "placement": {
+          "type": "string",
+          "enum": ["top", "bottom", "left", "right"],
+          "default": "top"
+        },
+        "trigger": {
+          "type": "string",
+          "enum": ["immediate", "hover", "click"],
+          "default": "immediate"
+        },
+        "waitFor": {
+          "type": "string",
+          "description": "When the action completes (for sequences). Options: 'dismissed', 'cta-click', 'timeout:N' (ms)"
+        },
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "highlight": {
+      "type": "object",
+      "required": ["kind", "anchorId"],
+      "properties": {
+        "kind": { "const": "overlays:highlight" },
+        "anchorId": { "type": "string" },
+        "style": {
           "type": "object",
-          "required": ["kind", "className"],
           "properties": {
-            "kind": { "enum": ["addClass", "removeClass"] },
-            "className": { "type": "string" }
+            "color": { "type": "string" },
+            "scrimOpacity": { "type": "number", "minimum": 0, "maximum": 1 },
+            "paddingPx": { "type": "number" },
+            "radiusPx": { "type": "number" }
           },
           "additionalProperties": false
         },
-        {
+        "duration": {
+          "type": "number",
+          "description": "Duration in ms before auto-cleanup (for sequences)"
+        },
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "pulse": {
+      "type": "object",
+      "required": ["kind", "anchorId"],
+      "properties": {
+        "kind": { "const": "overlays:pulse" },
+        "anchorId": { "type": "string" },
+        "color": { "type": "string" },
+        "durationMs": { "type": "number" },
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "badge": {
+      "type": "object",
+      "required": ["kind", "anchorId", "text"],
+      "properties": {
+        "kind": { "const": "overlays:badge" },
+        "anchorId": { "type": "string" },
+        "text": { "type": "string" },
+        "variant": {
+          "type": "string",
+          "enum": ["info", "success", "warning", "error"],
+          "default": "info"
+        },
+        "position": {
+          "type": "string",
+          "enum": ["top-right", "top-left", "bottom-right", "bottom-left"],
+          "default": "top-right"
+        },
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "modal": {
+      "type": "object",
+      "required": ["kind", "content"],
+      "properties": {
+        "kind": { "const": "overlays:modal" },
+        "content": {
           "type": "object",
-          "required": ["kind", "name"],
+          "required": ["body"],
           "properties": {
-            "kind": { "const": "setAttr" },
-            "name": { "type": "string" },
-            "value": { "type": ["string", "null"] }
+            "title": { "type": "string" },
+            "body": { "type": "string" }
           },
           "additionalProperties": false
         },
-        {
+        "size": {
+          "type": "string",
+          "enum": ["sm", "md", "lg"],
+          "default": "md",
+          "description": "Modal size"
+        },
+        "blocking": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether the modal blocks interaction with the page"
+        },
+        "scrim": {
           "type": "object",
-          "required": ["kind", "prop"],
           "properties": {
-            "kind": { "const": "setStyle" },
-            "prop": { "type": "string" },
-            "value": { "type": ["string", "null"] },
-            "important": { "type": "boolean" }
+            "opacity": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.6 }
           },
           "additionalProperties": false
         },
-        {
+        "dismiss": {
           "type": "object",
-          "required": ["kind", "text"],
           "properties": {
-            "kind": { "const": "setText" },
-            "text": { "type": "string" }
+            "onEsc": { "type": "boolean", "default": true },
+            "closeButton": { "type": "boolean", "default": true },
+            "timeoutMs": { "type": "number", "minimum": 0 }
           },
           "additionalProperties": false
-        }
-      ]
+        },
+        "ctaButtons": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ctaButton" }
+        },
+        "waitFor": {
+          "type": "string",
+          "description": "When the action completes (for sequences). Options: 'dismissed', 'cta-click', 'timeout:N' (ms)"
+        },
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
     },
-    "patch": {
+    "scrollTo": {
       "type": "object",
-      "required": ["id", "anchor", "operations"],
+      "required": ["kind", "anchorId"],
       "properties": {
-        "id": { "type": "string" },
-        "routes": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "URL path patterns where this patch should apply. Supports wildcards (e.g., '/', '/pricing', '/products/*'). If omitted, patch applies on all pages."
+        "kind": { "const": "navigation:scrollTo" },
+        "anchorId": { "type": "string" },
+        "behavior": {
+          "type": "string",
+          "enum": ["smooth", "instant"],
+          "default": "smooth"
         },
-        "anchor": { "$ref": "#/$defs/anchorSelector" },
-        "operations": {
-          "type": "array",
-          "items": { "$ref": "#/$defs/operation" }
-        }
+        "block": {
+          "type": "string",
+          "enum": ["start", "center", "end"],
+          "default": "center"
+        },
+        "label": { "type": "string" }
       },
       "additionalProperties": false
     },
-    "tooltipStep": {
+    "navigate": {
       "type": "object",
-      "required": ["kind", "id", "anchor", "content"],
+      "required": ["kind", "url"],
       "properties": {
-        "kind": { "const": "tooltip" },
-        "id": { "type": "string" },
-        "anchor": { "$ref": "#/$defs/anchorSelector" },
-        "content": {
+        "kind": { "const": "navigation:navigate" },
+        "url": { "type": "string" },
+        "target": {
+          "type": "string",
+          "enum": ["_self", "_blank"],
+          "default": "_self"
+        },
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "mountWidget": {
+      "type": "object",
+      "required": ["kind", "slot", "widget"],
+      "properties": {
+        "kind": { "const": "core:mountWidget" },
+        "slot": {
+          "type": "string",
+          "description": "Surface slot to mount to (e.g., overlay_center, sidebar_top)"
+        },
+        "widget": {
           "type": "object",
+          "required": ["widgetId"],
           "properties": {
-            "title": { "type": "string" },
-            "body": { "type": "string" }
+            "widgetId": { "type": "string" },
+            "props": { "type": "object", "additionalProperties": true }
           },
-          "required": ["body"],
           "additionalProperties": false
         },
-        "placement": { "enum": ["top","bottom","left","right","auto"] },
-        "offsetPx": { "type": "number" },
-        "blocking": { "type": "boolean" },
-        "trigger": { "enum": ["immediate","hover","click"] },
-        "ctaButtons": {
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "wait": {
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": { "const": "core:wait" },
+        "durationMs": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Wait for a duration in milliseconds"
+        },
+        "event": { "type": "string", "description": "Wait for an event on the EventBus" },
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "sequence": {
+      "type": "object",
+      "required": ["kind", "actions"],
+      "properties": {
+        "kind": { "const": "core:sequence" },
+        "actions": {
           "type": "array",
-          "items": {
-            "type": "object",
-            "properties": {
-              "label": { "type": "string" },
-              "actionId": { "type": "string" }
-            },
-            "required": ["label","actionId"],
-            "additionalProperties": false
-          }
+          "items": { "$ref": "#/$defs/actionStep" }
         },
-        "dismiss": {
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "parallel": {
+      "type": "object",
+      "required": ["kind", "actions"],
+      "properties": {
+        "kind": { "const": "core:parallel" },
+        "actions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/actionStep" }
+        },
+        "waitFor": {
+          "type": "string",
+          "enum": ["all", "any"],
+          "default": "all",
+          "description": "How to determine completion: 'all' waits for all, 'any' completes when first finishes"
+        },
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "tourStep": {
+      "type": "object",
+      "required": ["id", "action"],
+      "properties": {
+        "id": { "type": "string", "description": "Unique identifier for this step" },
+        "action": {
+          "$ref": "#/$defs/actionStep",
+          "description": "Action to execute for this step"
+        },
+        "route": { "type": "string", "description": "Route this step appears on" },
+        "onAction": {
           "type": "object",
-          "properties": {
-            "onEsc": { "type": "boolean" },
-            "closeButton": { "type": "boolean" },
-            "timeoutMs": { "type": "number" }
+          "additionalProperties": {
+            "type": "string",
+            "description": "Target step ID or 'end' to finish the tour"
           },
-          "additionalProperties": false
+          "description": "Map of actionId to next step ID"
         }
       },
       "additionalProperties": false
     },
-    "highlightStep": {
+    "tour": {
       "type": "object",
-      "required": ["kind", "id", "anchor"],
+      "required": ["kind", "tourId", "steps"],
       "properties": {
-        "kind": { "const": "highlight" },
-        "id": { "type": "string" },
-        "anchor": { "$ref": "#/$defs/anchorSelector" },
-        "copy": { "type": "string" },
-        "ring": {
-          "type": "object",
-          "properties": {
-            "paddingPx": { "type": "number" },
-            "radiusPx": { "type": "number" }
-          },
-          "additionalProperties": false
+        "kind": { "const": "core:tour" },
+        "tourId": { "type": "string", "description": "Unique identifier for this tour" },
+        "steps": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/tourStep" },
+          "minItems": 1,
+          "description": "Sequential tour steps"
         },
-        "scrim": {
-          "type": "object",
-          "properties": {
-            "opacity": { "type": "number" }
-          },
-          "additionalProperties": false
+        "startStep": {
+          "type": "string",
+          "description": "ID of the step to start at (defaults to first step)"
         },
-        "ringColor": { "type": "string" },
-        "blocking": { "type": "boolean" },
-        "dismiss": {
-          "type": "object",
-          "properties": {
-            "onClickOutside": { "type": "boolean" },
-            "onEsc": { "type": "boolean" },
-            "timeoutMs": { "type": "number" }
-          },
-          "additionalProperties": false
+        "autoStart": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether to start the tour automatically"
+        },
+        "label": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "themeConfig": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "mode": { "type": "string", "enum": ["dark", "light"] },
+        "position": { "type": "string", "enum": ["left", "right"] },
+        "colorPrimary": { "type": "string" },
+        "colorBackground": { "type": "string" },
+        "colorText": { "type": "string" },
+        "borderRadius": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "launcherConfig": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "label": { "type": "string" },
+        "position": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "routesConfig": {
+      "type": "object",
+      "properties": {
+        "exclude": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "include": {
+          "type": "array",
+          "items": { "type": "string" }
         }
       },
       "additionalProperties": false
     },
     "activationConfig": {
       "type": "object",
-      "description": "v2 activation configuration for conditional tile rendering",
+      "description": "Activation configuration for conditional tile rendering",
       "properties": {
         "routes": { "$ref": "#/$defs/routeFilter" },
         "strategy": { "$ref": "#/$defs/decisionStrategy" }