@syntrologie/runtime-sdk 2.1.0-canary.9 → 2.2.0-canary.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (363) hide show
  1. package/CAPABILITIES.md +155 -99
  2. package/README.md +7 -7
  3. package/dist/RuntimeProvider.d.ts +1 -1
  4. package/dist/ShadowRootContext.d.ts +19 -0
  5. package/dist/SmartCanvasApp.d.ts +4 -6
  6. package/dist/SmartCanvasElement.d.ts +7 -4
  7. package/dist/SmartCanvasPortal.d.ts +1 -1
  8. package/dist/actions/executors/index.d.ts +3 -3
  9. package/dist/actions/executors/tour.d.ts +1 -1
  10. package/dist/actions/index.d.ts +4 -3
  11. package/dist/actions/schema.d.ts +1229 -0
  12. package/dist/actions/schema.js +67 -0
  13. package/dist/actions/schema.js.map +7 -0
  14. package/dist/adaptives/adaptive-chatbot/index.js +7 -5
  15. package/dist/adaptives/adaptive-chatbot/index.js.map +4 -4
  16. package/dist/adaptives/adaptive-content/index.js +22 -0
  17. package/dist/adaptives/adaptive-content/index.js.map +7 -0
  18. package/dist/adaptives/adaptive-faq/index.js +28 -0
  19. package/dist/adaptives/adaptive-faq/index.js.map +7 -0
  20. package/dist/adaptives/adaptive-gamification/index.js +2 -0
  21. package/dist/adaptives/adaptive-gamification/index.js.map +7 -0
  22. package/dist/adaptives/adaptive-nav/index.js +27 -0
  23. package/dist/adaptives/adaptive-nav/index.js.map +7 -0
  24. package/dist/adaptives/adaptive-overlays/index.js +94 -0
  25. package/dist/adaptives/adaptive-overlays/index.js.map +7 -0
  26. package/dist/api.d.ts +2 -10
  27. package/dist/apps/AppLoader.d.ts +5 -0
  28. package/dist/apps/examples/gamification-app.example.d.ts +4 -4
  29. package/dist/apps/index.d.ts +7 -7
  30. package/dist/apps/types.d.ts +26 -0
  31. package/dist/blocks/data/index.d.ts +1 -1
  32. package/dist/blocks/index.d.ts +10 -6
  33. package/dist/blocks/interactive/index.d.ts +1 -1
  34. package/dist/blocks/notification/NotificationBlock.d.ts +1 -1
  35. package/dist/blocks/notification/index.d.ts +1 -1
  36. package/dist/blocks/theme-tokens.d.ts +23 -0
  37. package/dist/bootstrap.d.ts +4 -4
  38. package/dist/chunk-AYTRRBR5.js +251 -0
  39. package/dist/chunk-AYTRRBR5.js.map +7 -0
  40. package/dist/chunk-HJKAXD5S.js +7921 -0
  41. package/dist/chunk-HJKAXD5S.js.map +7 -0
  42. package/dist/components/ShadowCanvasOverlay.d.ts +7 -4
  43. package/dist/components/TileCard.d.ts +2 -6
  44. package/dist/configFetcher.d.ts +5 -1
  45. package/dist/context/ContextManager.d.ts +1 -1
  46. package/dist/context/index.d.ts +3 -3
  47. package/dist/decisions/engine.d.ts +5 -1
  48. package/dist/decisions/index.d.ts +3 -3
  49. package/dist/decisions/schema.d.ts +265 -24
  50. package/dist/decisions/strategies/rules.d.ts +1 -1
  51. package/dist/decisions/strategies/score.d.ts +1 -1
  52. package/dist/decisions/types.d.ts +21 -1
  53. package/dist/editorLoader.d.ts +6 -6
  54. package/dist/events/EventAccumulator.d.ts +29 -0
  55. package/dist/events/EventBus.d.ts +1 -1
  56. package/dist/events/index.d.ts +7 -4
  57. package/dist/events/registerConfigPredicates.d.ts +19 -0
  58. package/dist/events/types.d.ts +4 -0
  59. package/dist/experiments/adapters/growthbook.d.ts +3 -2
  60. package/dist/experiments/index.d.ts +2 -2
  61. package/dist/experiments/registry.d.ts +1 -1
  62. package/dist/experiments/types.d.ts +5 -0
  63. package/dist/fetchers/experimentsFetcher.d.ts +23 -1
  64. package/dist/fetchers/index.d.ts +2 -2
  65. package/dist/fetchers/mergeConfigs.d.ts +29 -0
  66. package/dist/hooks/useShadowCanvasConfig.d.ts +1 -1
  67. package/dist/hostPatcher/index.d.ts +2 -2
  68. package/dist/index.d.ts +25 -21
  69. package/dist/index.js +818 -49
  70. package/dist/index.js.map +7 -1
  71. package/dist/metrics/index.d.ts +1 -1
  72. package/dist/notifications/NotificationToastStack.d.ts +8 -0
  73. package/dist/notifications/index.d.ts +9 -0
  74. package/dist/notifications/matcher.d.ts +25 -0
  75. package/dist/notifications/types.d.ts +64 -0
  76. package/dist/notifications/useNotifications.d.ts +19 -0
  77. package/dist/notifications/useNotifyWatcher.d.ts +15 -0
  78. package/dist/overlays/runtime/index.d.ts +3 -3
  79. package/dist/overlays/runtime/overlay/root.d.ts +17 -1
  80. package/dist/overlays/runtime/overlay/tooltip.d.ts +1 -1
  81. package/dist/react.js +90 -134
  82. package/dist/react.js.map +7 -1
  83. package/dist/render/RenderContext.d.ts +2 -2
  84. package/dist/render/index.d.ts +2 -2
  85. package/dist/render/types.d.ts +3 -4
  86. package/dist/runtime.d.ts +11 -8
  87. package/dist/smart-canvas.esm.js +137 -117
  88. package/dist/smart-canvas.esm.js.map +4 -4
  89. package/dist/smart-canvas.js +16725 -16759
  90. package/dist/smart-canvas.js.map +4 -4
  91. package/dist/smart-canvas.min.js +137 -117
  92. package/dist/smart-canvas.min.js.map +4 -4
  93. package/dist/state/StateStore.d.ts +1 -1
  94. package/dist/state/helpers/cooldowns.d.ts +1 -1
  95. package/dist/state/helpers/dismissals.d.ts +1 -1
  96. package/dist/state/helpers/frequency.d.ts +1 -1
  97. package/dist/state/index.d.ts +3 -3
  98. package/dist/surfaces/index.d.ts +3 -3
  99. package/dist/surfaces/positioning.d.ts +1 -1
  100. package/dist/telemetry/adapters/posthog.d.ts +2 -2
  101. package/dist/telemetry/index.d.ts +3 -3
  102. package/dist/telemetry/registry.d.ts +1 -1
  103. package/dist/theme/ThemeProvider.d.ts +1 -1
  104. package/dist/theme/defaultTheme.d.ts +5 -0
  105. package/dist/theme/extractHostTheme.d.ts +1 -1
  106. package/dist/theme/index.d.ts +4 -4
  107. package/dist/theme/types.d.ts +7 -0
  108. package/dist/types-only.d.ts +1 -1
  109. package/dist/types-only.js +1 -11
  110. package/dist/types-only.js.map +7 -1
  111. package/dist/types.d.ts +14 -101
  112. package/dist/version.d.ts +1 -1
  113. package/dist/widgets/WidgetRegistry.d.ts +6 -1
  114. package/dist/widgets/index.d.ts +1 -1
  115. package/package.json +25 -17
  116. package/schema/canvas-config.base.schema.json +351 -0
  117. package/schema/canvas-config.schema.json +3169 -442
  118. package/schema/event-catalog.schema.json +157 -0
  119. package/scripts/validate-config.mjs +58 -55
  120. package/dist/RuntimeProvider.js +0 -113
  121. package/dist/RuntimeProvider.js.map +0 -1
  122. package/dist/SmartCanvasApp.js +0 -137
  123. package/dist/SmartCanvasApp.js.map +0 -1
  124. package/dist/SmartCanvasElement.js +0 -143
  125. package/dist/SmartCanvasElement.js.map +0 -1
  126. package/dist/SmartCanvasPortal.js +0 -17
  127. package/dist/SmartCanvasPortal.js.map +0 -1
  128. package/dist/actions/ActionEngine.js +0 -272
  129. package/dist/actions/ActionEngine.js.map +0 -1
  130. package/dist/actions/executors/index.js +0 -237
  131. package/dist/actions/executors/index.js.map +0 -1
  132. package/dist/actions/executors/tour.js +0 -332
  133. package/dist/actions/executors/tour.js.map +0 -1
  134. package/dist/actions/index.js +0 -12
  135. package/dist/actions/index.js.map +0 -1
  136. package/dist/actions/types.js +0 -8
  137. package/dist/actions/types.js.map +0 -1
  138. package/dist/actions/validation.js +0 -602
  139. package/dist/actions/validation.js.map +0 -1
  140. package/dist/adaptives/faq/index.js +0 -11
  141. package/dist/adaptives/faq/index.js.map +0 -7
  142. package/dist/adaptives/gamification/index.js +0 -2
  143. package/dist/adaptives/gamification/index.js.map +0 -7
  144. package/dist/adaptives/nav/index.js +0 -11
  145. package/dist/adaptives/nav/index.js.map +0 -7
  146. package/dist/antiFlicker.js +0 -39
  147. package/dist/antiFlicker.js.map +0 -1
  148. package/dist/api.js +0 -205
  149. package/dist/api.js.map +0 -1
  150. package/dist/apps/AppContext.js +0 -91
  151. package/dist/apps/AppContext.js.map +0 -1
  152. package/dist/apps/AppLoader.js +0 -268
  153. package/dist/apps/AppLoader.js.map +0 -1
  154. package/dist/apps/AppRegistry.js +0 -317
  155. package/dist/apps/AppRegistry.js.map +0 -1
  156. package/dist/apps/examples/gamification-app.example.js +0 -329
  157. package/dist/apps/examples/gamification-app.example.js.map +0 -1
  158. package/dist/apps/index.js +0 -16
  159. package/dist/apps/index.js.map +0 -1
  160. package/dist/apps/types.js +0 -8
  161. package/dist/apps/types.js.map +0 -1
  162. package/dist/blocks/data/ComparisonBlock.js +0 -92
  163. package/dist/blocks/data/ComparisonBlock.js.map +0 -1
  164. package/dist/blocks/data/StatsBlock.js +0 -101
  165. package/dist/blocks/data/StatsBlock.js.map +0 -1
  166. package/dist/blocks/data/index.js +0 -3
  167. package/dist/blocks/data/index.js.map +0 -1
  168. package/dist/blocks/index.js +0 -93
  169. package/dist/blocks/index.js.map +0 -1
  170. package/dist/blocks/interactive/ChecklistBlock.js +0 -110
  171. package/dist/blocks/interactive/ChecklistBlock.js.map +0 -1
  172. package/dist/blocks/interactive/RatingBlock.js +0 -139
  173. package/dist/blocks/interactive/RatingBlock.js.map +0 -1
  174. package/dist/blocks/interactive/index.js +0 -3
  175. package/dist/blocks/interactive/index.js.map +0 -1
  176. package/dist/blocks/notification/NotificationBlock.js +0 -170
  177. package/dist/blocks/notification/NotificationBlock.js.map +0 -1
  178. package/dist/blocks/notification/index.js +0 -2
  179. package/dist/blocks/notification/index.js.map +0 -1
  180. package/dist/bootstrap.js +0 -443
  181. package/dist/bootstrap.js.map +0 -1
  182. package/dist/bundle-entry.js +0 -9
  183. package/dist/bundle-entry.js.map +0 -1
  184. package/dist/components/ShadowCanvasOverlay.js +0 -252
  185. package/dist/components/ShadowCanvasOverlay.js.map +0 -1
  186. package/dist/components/TileCard.js +0 -328
  187. package/dist/components/TileCard.js.map +0 -1
  188. package/dist/components/TileWheel.js +0 -52
  189. package/dist/components/TileWheel.js.map +0 -1
  190. package/dist/config-validator.js +0 -173
  191. package/dist/config-validator.js.map +0 -1
  192. package/dist/configFetcher.js +0 -100
  193. package/dist/configFetcher.js.map +0 -1
  194. package/dist/context/ContextManager.js +0 -268
  195. package/dist/context/ContextManager.js.map +0 -1
  196. package/dist/context/index.js +0 -7
  197. package/dist/context/index.js.map +0 -1
  198. package/dist/context/schema.js +0 -50
  199. package/dist/context/schema.js.map +0 -1
  200. package/dist/context/types.js +0 -8
  201. package/dist/context/types.js.map +0 -1
  202. package/dist/controller.js +0 -34
  203. package/dist/controller.js.map +0 -1
  204. package/dist/decisions/engine.js +0 -112
  205. package/dist/decisions/engine.js.map +0 -1
  206. package/dist/decisions/index.js +0 -10
  207. package/dist/decisions/index.js.map +0 -1
  208. package/dist/decisions/schema.js +0 -143
  209. package/dist/decisions/schema.js.map +0 -1
  210. package/dist/decisions/strategies/rules.js +0 -152
  211. package/dist/decisions/strategies/rules.js.map +0 -1
  212. package/dist/decisions/strategies/score.js +0 -29
  213. package/dist/decisions/strategies/score.js.map +0 -1
  214. package/dist/decisions/types.js +0 -2
  215. package/dist/decisions/types.js.map +0 -1
  216. package/dist/earlyPatcher.js +0 -20
  217. package/dist/earlyPatcher.js.map +0 -1
  218. package/dist/editorLoader.js +0 -233
  219. package/dist/editorLoader.js.map +0 -1
  220. package/dist/events/EventBus.js +0 -152
  221. package/dist/events/EventBus.js.map +0 -1
  222. package/dist/events/index.js +0 -10
  223. package/dist/events/index.js.map +0 -1
  224. package/dist/events/normalizers/canvas.js +0 -116
  225. package/dist/events/normalizers/canvas.js.map +0 -1
  226. package/dist/events/normalizers/posthog.js +0 -163
  227. package/dist/events/normalizers/posthog.js.map +0 -1
  228. package/dist/events/schema.js +0 -30
  229. package/dist/events/schema.js.map +0 -1
  230. package/dist/events/types.js +0 -49
  231. package/dist/events/types.js.map +0 -1
  232. package/dist/experiments/adapters/growthbook.js +0 -93
  233. package/dist/experiments/adapters/growthbook.js.map +0 -1
  234. package/dist/experiments/index.js +0 -4
  235. package/dist/experiments/index.js.map +0 -1
  236. package/dist/experiments/registry.js +0 -30
  237. package/dist/experiments/registry.js.map +0 -1
  238. package/dist/experiments/types.js +0 -2
  239. package/dist/experiments/types.js.map +0 -1
  240. package/dist/fetchers/cdnFetcher.js +0 -96
  241. package/dist/fetchers/cdnFetcher.js.map +0 -1
  242. package/dist/fetchers/experimentsFetcher.js +0 -62
  243. package/dist/fetchers/experimentsFetcher.js.map +0 -1
  244. package/dist/fetchers/index.js +0 -5
  245. package/dist/fetchers/index.js.map +0 -1
  246. package/dist/fetchers/registry.js +0 -58
  247. package/dist/fetchers/registry.js.map +0 -1
  248. package/dist/fetchers/types.js +0 -2
  249. package/dist/fetchers/types.js.map +0 -1
  250. package/dist/hooks/useCanvasOverlays.js +0 -128
  251. package/dist/hooks/useCanvasOverlays.js.map +0 -1
  252. package/dist/hooks/useHostPatches.js +0 -40
  253. package/dist/hooks/useHostPatches.js.map +0 -1
  254. package/dist/hooks/useShadowCanvasConfig.js +0 -63
  255. package/dist/hooks/useShadowCanvasConfig.js.map +0 -1
  256. package/dist/hostPatcher/core/patcher.js +0 -181
  257. package/dist/hostPatcher/core/patcher.js.map +0 -1
  258. package/dist/hostPatcher/core/sanitizer.js +0 -66
  259. package/dist/hostPatcher/core/sanitizer.js.map +0 -1
  260. package/dist/hostPatcher/core/types.js +0 -2
  261. package/dist/hostPatcher/core/types.js.map +0 -1
  262. package/dist/hostPatcher/index.js +0 -7
  263. package/dist/hostPatcher/index.js.map +0 -1
  264. package/dist/hostPatcher/policy/defaultPolicy.js +0 -23
  265. package/dist/hostPatcher/policy/defaultPolicy.js.map +0 -1
  266. package/dist/hostPatcher/utils/anchors.js +0 -105
  267. package/dist/hostPatcher/utils/anchors.js.map +0 -1
  268. package/dist/hostPatcher/utils/observer.js +0 -11
  269. package/dist/hostPatcher/utils/observer.js.map +0 -1
  270. package/dist/logger.js +0 -81
  271. package/dist/logger.js.map +0 -1
  272. package/dist/metrics/index.js +0 -5
  273. package/dist/metrics/index.js.map +0 -1
  274. package/dist/metrics/sessionMetrics.js +0 -178
  275. package/dist/metrics/sessionMetrics.js.map +0 -1
  276. package/dist/overlays/fetcher.js +0 -15
  277. package/dist/overlays/fetcher.js.map +0 -1
  278. package/dist/overlays/recipeRegistry.js +0 -32
  279. package/dist/overlays/recipeRegistry.js.map +0 -1
  280. package/dist/overlays/runtime/anchor/resolve.js +0 -87
  281. package/dist/overlays/runtime/anchor/resolve.js.map +0 -1
  282. package/dist/overlays/runtime/index.js +0 -8
  283. package/dist/overlays/runtime/index.js.map +0 -1
  284. package/dist/overlays/runtime/overlay/highlight.js +0 -160
  285. package/dist/overlays/runtime/overlay/highlight.js.map +0 -1
  286. package/dist/overlays/runtime/overlay/modal.js +0 -78
  287. package/dist/overlays/runtime/overlay/modal.js.map +0 -1
  288. package/dist/overlays/runtime/overlay/root.js +0 -297
  289. package/dist/overlays/runtime/overlay/root.js.map +0 -1
  290. package/dist/overlays/runtime/overlay/runner.js +0 -602
  291. package/dist/overlays/runtime/overlay/runner.js.map +0 -1
  292. package/dist/overlays/runtime/overlay/tooltip.js +0 -232
  293. package/dist/overlays/runtime/overlay/tooltip.js.map +0 -1
  294. package/dist/overlays/runtime/utils/dom.js +0 -12
  295. package/dist/overlays/runtime/utils/dom.js.map +0 -1
  296. package/dist/overlays/schema.js +0 -52
  297. package/dist/overlays/schema.js.map +0 -1
  298. package/dist/overlays/types.js +0 -2
  299. package/dist/overlays/types.js.map +0 -1
  300. package/dist/render/RenderContext.js +0 -67
  301. package/dist/render/RenderContext.js.map +0 -1
  302. package/dist/render/index.js +0 -3
  303. package/dist/render/index.js.map +0 -1
  304. package/dist/render/types.js +0 -2
  305. package/dist/render/types.js.map +0 -1
  306. package/dist/runtime.js +0 -221
  307. package/dist/runtime.js.map +0 -1
  308. package/dist/state/StateStore.js +0 -176
  309. package/dist/state/StateStore.js.map +0 -1
  310. package/dist/state/helpers/cooldowns.js +0 -31
  311. package/dist/state/helpers/cooldowns.js.map +0 -1
  312. package/dist/state/helpers/dismissals.js +0 -34
  313. package/dist/state/helpers/dismissals.js.map +0 -1
  314. package/dist/state/helpers/frequency.js +0 -43
  315. package/dist/state/helpers/frequency.js.map +0 -1
  316. package/dist/state/index.js +0 -7
  317. package/dist/state/index.js.map +0 -1
  318. package/dist/state/schema.js +0 -25
  319. package/dist/state/schema.js.map +0 -1
  320. package/dist/state/types.js +0 -9
  321. package/dist/state/types.js.map +0 -1
  322. package/dist/store/example.js +0 -43
  323. package/dist/store/example.js.map +0 -1
  324. package/dist/store/mini-effector.js +0 -88
  325. package/dist/store/mini-effector.js.map +0 -1
  326. package/dist/surfaces/Surfaces.js +0 -361
  327. package/dist/surfaces/Surfaces.js.map +0 -1
  328. package/dist/surfaces/index.js +0 -12
  329. package/dist/surfaces/index.js.map +0 -1
  330. package/dist/surfaces/positioning.js +0 -228
  331. package/dist/surfaces/positioning.js.map +0 -1
  332. package/dist/surfaces/types.js +0 -23
  333. package/dist/surfaces/types.js.map +0 -1
  334. package/dist/telemetry/adapters/noop.js +0 -42
  335. package/dist/telemetry/adapters/noop.js.map +0 -1
  336. package/dist/telemetry/adapters/posthog.js +0 -180
  337. package/dist/telemetry/adapters/posthog.js.map +0 -1
  338. package/dist/telemetry/index.js +0 -4
  339. package/dist/telemetry/index.js.map +0 -1
  340. package/dist/telemetry/registry.js +0 -29
  341. package/dist/telemetry/registry.js.map +0 -1
  342. package/dist/telemetry/types.js +0 -2
  343. package/dist/telemetry/types.js.map +0 -1
  344. package/dist/theme/ThemeProvider.js +0 -109
  345. package/dist/theme/ThemeProvider.js.map +0 -1
  346. package/dist/theme/defaultTheme.js +0 -172
  347. package/dist/theme/defaultTheme.js.map +0 -1
  348. package/dist/theme/extractHostTheme.js +0 -259
  349. package/dist/theme/extractHostTheme.js.map +0 -1
  350. package/dist/theme/index.js +0 -7
  351. package/dist/theme/index.js.map +0 -1
  352. package/dist/theme/types.js +0 -6
  353. package/dist/theme/types.js.map +0 -1
  354. package/dist/token.js +0 -44
  355. package/dist/token.js.map +0 -1
  356. package/dist/types.js +0 -17
  357. package/dist/types.js.map +0 -1
  358. package/dist/version.js +0 -14
  359. package/dist/version.js.map +0 -1
  360. package/dist/widgets/WidgetRegistry.js +0 -182
  361. package/dist/widgets/WidgetRegistry.js.map +0 -1
  362. package/dist/widgets/index.js +0 -7
  363. package/dist/widgets/index.js.map +0 -1
package/CAPABILITIES.md CHANGED
@@ -568,6 +568,40 @@ The `ordering` field controls how FAQ items are sorted:
568
568
  }
569
569
  ```
570
570
 
571
+ ### Contextual Hints (Companion Tooltips)
572
+
573
+ FAQ questions can be surfaced proactively on the page using companion overlay tooltips. When a tooltip CTA has an `actionId` matching `faq:open:<questionId>`, clicking it expands the corresponding question in the FAQ widget and scrolls it into view.
574
+
575
+ This is a convention-based integration — no special FAQ action is needed. Use a standard `overlays:tooltip` action with `ctaButtons`:
576
+
577
+ ```json
578
+ {
579
+ "kind": "overlays:tooltip",
580
+ "anchorId": "#complex-feature",
581
+ "content": {
582
+ "title": "Need help?",
583
+ "body": "Check our FAQ for details.",
584
+ "ctaButtons": [
585
+ { "label": "View Answer", "actionId": "faq:open:getting-started", "primary": true },
586
+ { "label": "Dismiss", "actionId": "dismiss" }
587
+ ]
588
+ },
589
+ "trigger": "immediate",
590
+ "placement": "bottom"
591
+ }
592
+ ```
593
+
594
+ **How it works:**
595
+
596
+ 1. The tooltip CTA click publishes an `action.tooltip_cta_clicked` event via the EventBus
597
+ 2. The FAQ widget subscribes to these events and filters for `faq:open:*` actionIds
598
+ 3. The matching question expands and scrolls into view
599
+ 4. The widget also publishes `canvas.requestOpen` to open the canvas panel if needed
600
+
601
+ **Late-mount support:** If the FAQ widget mounts after the CTA click (e.g., canvas was closed), it checks the EventBus history for recent `faq:open:*` events (within 10 seconds) and auto-expands the target question on mount.
602
+
603
+ **`dismiss` actionId:** Destroys the tooltip without publishing an event. Use this for a "close" or "not now" button.
604
+
571
605
  ### Dynamic Injection
572
606
 
573
607
  Injection rules add contextual FAQ items when conditions are met:
@@ -700,68 +734,85 @@ Mounts gamification UI elements.
700
734
 
701
735
  # @syntrologie/adapt-nav
702
736
 
703
- Navigation link list widget with conditional item visibility.
737
+ Navigation tips accordion widget with conditional item visibility and toast notifications.
704
738
 
705
- ## Actions
739
+ ## Widget: `adaptive-nav:tips`
706
740
 
707
- ### mount_nav
741
+ Accordion of contextual navigation tips. Each tip has a collapsible header and expanded body with optional CTA link.
708
742
 
709
- Mounts a navigation link list widget to a surface slot.
743
+ ### Tile Config
710
744
 
711
- | Property | Type | Required | Description |
712
- | -------------- | ------------- | -------- | ---------------------------------------------------------- |
713
- | `kind` | `"mount_nav"` | Yes | Action type |
714
- | `slot` | string | Yes | Target slot (e.g., `"drawer_left"`, `"inline:{anchorId}"`) |
715
- | `config.title` | string | No | Widget title |
716
- | `config.items` | array | Yes | Navigation items (see below) |
745
+ | Property | Type | Required | Default | Description |
746
+ | ---------------------- | --------------------------------- | -------- | ---------- | --------------------- |
747
+ | `widget` | `"adaptive-nav:tips"` | Yes | | Widget identifier |
748
+ | `props.expandBehavior` | `"single"` \| `"multiple"` | No | `"single"` | Accordion expand mode |
749
+ | `props.theme` | `"light"` \| `"dark"` \| `"auto"` | No | `"auto"` | Color theme |
750
+ | `props.actions` | `NavTipAction[]` | Yes | | Navigation tip items |
717
751
 
718
- ### Nav Item Schema
752
+ ### Nav Tip Action (`nav:tip`)
719
753
 
720
- Each item in the `items` array:
754
+ Compositional action — rendered as an accordion item by the parent widget.
755
+
756
+ | Property | Type | Required | Description |
757
+ | -------------------- | --------------------------- | -------- | ------------------------------------ |
758
+ | `kind` | `"nav:tip"` | Yes | Action type |
759
+ | `config.id` | string | Yes | Unique tip identifier |
760
+ | `config.title` | string | Yes | Accordion header text |
761
+ | `config.description` | string | Yes | Expanded body text |
762
+ | `config.href` | string | No | Optional CTA link URL |
763
+ | `config.icon` | string | No | Icon (emoji or icon key) |
764
+ | `config.external` | boolean | No | Open link in new tab |
765
+ | `config.category` | string | No | Category for grouping |
766
+ | `showWhen` | `DecisionStrategy<boolean>` | No | Conditional visibility |
767
+ | `notify` | `{ title?, body?, icon? }` | No | Toast config for showWhen transition |
768
+ | `rationale` | `{ why, confidence? }` | No | AI reasoning for recommendation |
769
+
770
+ ### Events Published
721
771
 
722
- | Property | Type | Required | Description |
723
- | ---------- | ---------------- | -------- | ------------------------------- |
724
- | `label` | string | Yes | Link text |
725
- | `href` | string | Yes | Link destination |
726
- | `icon` | string | No | Icon identifier |
727
- | `showWhen` | DecisionStrategy | No | Conditional visibility strategy |
772
+ | Event | When | Props |
773
+ | ------------------ | ----------------------------------- | --------------------------------- |
774
+ | `nav:toggled` | User expands/collapses a tip | `{ instanceId, tipId, expanded }` |
775
+ | `nav:tip_clicked` | User clicks a tip's CTA link | `{ instanceId, href, external }` |
776
+ | `nav:tip_revealed` | `showWhen` transitions false → true | `{ tipId, title, body, icon }` |
777
+
778
+ ### Notify Watchers
779
+
780
+ Tips with both `showWhen` and `notify` are registered as notify watchers. The runtime evaluates these continuously (even when drawer is closed). When `showWhen` transitions false → true, publishes `nav:tip_revealed` which can trigger toast notifications via tile-level `notifications` rules.
728
781
 
729
782
  ```json
730
783
  {
731
- "kind": "mount_nav",
732
- "slot": "drawer_left",
733
- "config": {
734
- "title": "Quick Links",
735
- "items": [
736
- {
737
- "label": "Dashboard",
738
- "href": "/dashboard",
739
- "icon": "home"
740
- },
741
- {
742
- "label": "Admin Settings",
743
- "href": "/admin",
744
- "icon": "settings",
745
- "showWhen": {
746
- "type": "rules",
747
- "rules": [
748
- {
749
- "conditions": [{ "type": "state_equals", "key": "user.role", "value": "admin" }],
750
- "value": true
751
- }
752
- ],
753
- "default": false
754
- }
755
- },
784
+ "id": "nav",
785
+ "widget": "adaptive-nav:tips",
786
+ "notifications": [
787
+ {
788
+ "on": "nav:tip_revealed",
789
+ "title": "{{props.title}}",
790
+ "body": "{{props.body}}",
791
+ "icon": "🧭"
792
+ }
793
+ ],
794
+ "props": {
795
+ "expandBehavior": "single",
796
+ "theme": "dark",
797
+ "actions": [
756
798
  {
757
- "label": "Upgrade",
758
- "href": "/pricing",
759
- "icon": "sparkles",
799
+ "kind": "nav:tip",
800
+ "config": {
801
+ "id": "tip-analytics",
802
+ "title": "Advanced Analytics",
803
+ "description": "Unlock deeper insights with our analytics suite.",
804
+ "href": "/analytics",
805
+ "icon": "📊",
806
+ "category": "Power User"
807
+ },
808
+ "notify": { "title": "New Tip", "body": "Advanced Analytics", "icon": "📊" },
760
809
  "showWhen": {
761
810
  "type": "rules",
762
811
  "rules": [
763
812
  {
764
- "conditions": [{ "type": "state_equals", "key": "user.plan", "value": "free" }],
813
+ "conditions": [
814
+ { "type": "event_count", "key": "link-clicks", "operator": "gte", "count": 3 }
815
+ ],
765
816
  "value": true
766
817
  }
767
818
  ],
@@ -773,57 +824,28 @@ Each item in the `items` array:
773
824
  }
774
825
  ```
775
826
 
776
- ## Compositional Pattern
777
-
778
- The nav widget supports **per-item conditional visibility** using `showWhen` strategies. This allows different navigation items to appear based on:
779
-
780
- - User role or permissions
781
- - Subscription tier
782
- - Feature flags
783
- - Any other DecisionStrategy condition
784
-
785
- Items without `showWhen` are always visible.
786
-
787
827
  ## Navigation Actions
788
828
 
789
- ### scroll_to
829
+ ### `navigation:scrollTo`
790
830
 
791
831
  Scrolls the viewport to bring an element into view.
792
832
 
793
- | Property | Type | Required | Default | Description |
794
- | ---------- | ------------- | -------- | ----------- | ------------------------------------------- |
795
- | `kind` | `"scroll_to"` | Yes | | Action type |
796
- | `anchorId` | string | Yes | | Element selector |
797
- | `behavior` | string | No | `"smooth"` | `"smooth"`, `"instant"`, `"auto"` |
798
- | `block` | string | No | `"center"` | `"start"`, `"center"`, `"end"`, `"nearest"` |
799
- | `inline` | string | No | `"nearest"` | `"start"`, `"center"`, `"end"`, `"nearest"` |
833
+ | Property | Type | Required | Default | Description |
834
+ | ---------- | ----------------------- | -------- | ---------- | ------------------------------------------- |
835
+ | `kind` | `"navigation:scrollTo"` | Yes | | Action type |
836
+ | `anchorId` | string | Yes | | Element selector |
837
+ | `behavior` | string | No | `"smooth"` | `"smooth"`, `"instant"`, `"auto"` |
838
+ | `block` | string | No | `"center"` | `"start"`, `"center"`, `"end"`, `"nearest"` |
800
839
 
801
- ```json
802
- {
803
- "kind": "scroll_to",
804
- "anchorId": "#pricing-section",
805
- "behavior": "smooth",
806
- "block": "start"
807
- }
808
- ```
809
-
810
- ### navigate
840
+ ### `navigation:navigate`
811
841
 
812
842
  Navigates to a URL.
813
843
 
814
- | Property | Type | Required | Default | Description |
815
- | -------- | ------------ | -------- | --------- | ----------------------- |
816
- | `kind` | `"navigate"` | Yes | | Action type |
817
- | `url` | string | Yes | | Destination URL |
818
- | `target` | string | No | `"_self"` | `"_self"` or `"_blank"` |
819
-
820
- ```json
821
- {
822
- "kind": "navigate",
823
- "url": "/signup?ref=banner",
824
- "target": "_self"
825
- }
826
- ```
844
+ | Property | Type | Required | Default | Description |
845
+ | -------- | ----------------------- | -------- | --------- | ----------------------- |
846
+ | `kind` | `"navigation:navigate"` | Yes | | Action type |
847
+ | `url` | string | Yes | | Destination URL |
848
+ | `target` | string | No | `"_self"` | `"_self"` or `"_blank"` |
827
849
 
828
850
  **Note:** `javascript:` URLs are blocked for security.
829
851
 
@@ -864,19 +886,22 @@ Creates a spotlight effect around an element with a scrim overlay.
864
886
 
865
887
  Shows a tooltip near an element with optional title, body, and CTA.
866
888
 
867
- | Property | Type | Required | Default | Description |
868
- | -------------------- | ----------- | -------- | ------------- | ----------------------------------- |
869
- | `kind` | `"tooltip"` | Yes | | Action type |
870
- | `anchorId` | string | Yes | | Element selector |
871
- | `content.title` | string | No | | Tooltip heading |
872
- | `content.body` | string | Yes | | Tooltip text |
873
- | `content.cta.label` | string | No | | CTA button text |
874
- | `content.cta.action` | Action | No | | Action to execute on CTA click |
875
- | `trigger` | string | No | `"immediate"` | `"immediate"`, `"hover"`, `"click"` |
876
- | `placement` | string | No | `"top"` | See placement options below |
889
+ | Property | Type | Required | Default | Description |
890
+ | -------------------- | ----------- | -------- | ------------- | -------------------------------------- |
891
+ | `kind` | `"tooltip"` | Yes | | Action type |
892
+ | `anchorId` | string | Yes | | Element selector |
893
+ | `content.title` | string | No | | Tooltip heading |
894
+ | `content.body` | string | Yes | | Tooltip text |
895
+ | `content.cta.label` | string | No | | CTA button text (single-CTA shorthand) |
896
+ | `content.cta.action` | Action | No | | Action to execute on CTA click |
897
+ | `content.ctaButtons` | array | No | | Multiple CTA buttons (see below) |
898
+ | `trigger` | string | No | `"immediate"` | `"immediate"`, `"hover"`, `"click"` |
899
+ | `placement` | string | No | `"top"` | See placement options below |
877
900
 
878
901
  **Placement options:** `top`, `top-start`, `top-end`, `bottom`, `bottom-start`, `bottom-end`, `left`, `left-start`, `left-end`, `right`, `right-start`, `right-end`
879
902
 
903
+ **Single CTA (shorthand):**
904
+
880
905
  ```json
881
906
  {
882
907
  "kind": "tooltip",
@@ -894,6 +919,37 @@ Shows a tooltip near an element with optional title, body, and CTA.
894
919
  }
895
920
  ```
896
921
 
922
+ **Multiple CTAs (`ctaButtons`):**
923
+
924
+ Use `ctaButtons` for tooltips with multiple actions. Each button has:
925
+
926
+ - `label`: Button text
927
+ - `actionId`: Identifier published with the `action.tooltip_cta_clicked` event
928
+ - `primary`: Whether this is a primary button (default: false)
929
+
930
+ ```json
931
+ {
932
+ "kind": "overlays:tooltip",
933
+ "anchorId": "[data-nav=\"features\"]",
934
+ "content": {
935
+ "title": "Learn About Features",
936
+ "body": "We have answers about our feature set.",
937
+ "ctaButtons": [
938
+ { "label": "View Answer", "actionId": "faq:open:q-features", "primary": true },
939
+ { "label": "Dismiss", "actionId": "dismiss" }
940
+ ]
941
+ },
942
+ "trigger": "immediate",
943
+ "placement": "bottom"
944
+ }
945
+ ```
946
+
947
+ **Special actionId values:**
948
+
949
+ - `"dismiss"` — Destroys the tooltip immediately without publishing an event
950
+ - `"faq:open:<questionId>"` — Convention for companion FAQ tooltips (see adaptive-faq CAPABILITIES for details). Publishes `action.tooltip_cta_clicked` which the FAQ widget listens for.
951
+ - Any other value — Publishes `action.tooltip_cta_clicked` with the `actionId` in event props for custom handling
952
+
897
953
  ### badge
898
954
 
899
955
  Adds a small badge indicator near an element.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
- # Syntrologie Smart Canvas SDK
1
+ # Smart Canvas Runtime SDK
2
2
 
3
- ## Smart Canvas SDK (React + Shadow DOM)
3
+ ## Smart Canvas Runtime SDK (React + Shadow DOM)
4
4
 
5
5
  The SDK ships a framework-agnostic `<smart-canvas>` custom element with an **open shadow root**. We render everything with React, but the canvas is encapsulated so host Tailwind configs, resets, or stacking contexts can't break the UI.
6
6
 
@@ -73,7 +73,7 @@ For quick setup without a build process:
73
73
  ### Local Development
74
74
 
75
75
  ```bash
76
- cd tech-core/sdks/runtime-sdk
76
+ cd packages/runtime-sdk
77
77
  npm run build
78
78
  ```
79
79
 
@@ -322,7 +322,7 @@ if (result.value) {
322
322
  - Validate a config file locally:
323
323
 
324
324
  ```bash
325
- cd tech-core/sdks/runtime-sdk
325
+ cd packages/runtime-sdk
326
326
  npm run validate-config -- path/to/config.json
327
327
  ```
328
328
 
@@ -336,7 +336,7 @@ The SDK uses [semantic-release](https://github.com/semantic-release/semantic-rel
336
336
 
337
337
  | Channel | Trigger | npm dist-tag | CDN path |
338
338
  | ---------- | ---------------------------------------------- | ------------ | ----------------------------- |
339
- | **Canary** | Push to `develop` touching `tech-core/sdks/**` | `develop` | `/v2/canary/` |
339
+ | **Canary** | Push to `develop` touching `packages/**` | `develop` | `/v2/canary/` |
340
340
  | **Stable** | Manual workflow dispatch from `main` | `latest` | `/v2/latest/` + `/{VERSION}/` |
341
341
 
342
342
  ### Commit Messages → Version Bumps
@@ -411,7 +411,7 @@ https://cdn.syntrologie.com/runtime-sdk/v2/latest/adaptives/{appId}/index.js
411
411
 
412
412
  - **"No new version is released"** — 0 relevant commits since last tag. Push a `fix:` or `feat:` commit touching SDK paths.
413
413
  - **npm 404 / auth error** — package missing trusted publisher config on npmjs.com.
414
- - **Format check fails** — run `npx prettier --write <file>` locally before pushing.
414
+ - **Format check fails** — run `npx biome check --fix <file>` locally before pushing.
415
415
 
416
416
  ---
417
417
 
@@ -426,7 +426,7 @@ https://cdn.syntrologie.com/runtime-sdk/v2/latest/adaptives/{appId}/index.js
426
426
  ## Directory Overview
427
427
 
428
428
  ```
429
- tech-core/sdks/runtime-sdk
429
+ packages/runtime-sdk
430
430
  ├─ src
431
431
  │ ├─ actions/ # ActionEngine (interventions)
432
432
  │ │ ├─ types.ts
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * Provides access to the SmartCanvasRuntime from any component in the tree.
5
5
  */
6
- import { ReactNode } from 'react';
6
+ import { type ReactNode } from 'react';
7
7
  import type { RuntimeContext } from './context/types';
8
8
  import type { SmartCanvasRuntime } from './runtime';
9
9
  export interface RuntimeProviderProps {
@@ -0,0 +1,19 @@
1
+ import { type ReactNode } from 'react';
2
+ interface ShadowRootContextValue {
3
+ shadowRoot: ShadowRoot;
4
+ portalRoot: HTMLElement;
5
+ overlayContainer: HTMLElement;
6
+ }
7
+ export interface ShadowRootProviderProps {
8
+ shadowRoot: ShadowRoot;
9
+ portalRoot: HTMLElement;
10
+ overlayContainer: HTMLElement;
11
+ children: ReactNode;
12
+ }
13
+ export declare function ShadowRootProvider({ shadowRoot, portalRoot, overlayContainer, children, }: ShadowRootProviderProps): import("react/jsx-runtime").JSX.Element;
14
+ /**
15
+ * Access the shadow root context. Always available — SmartCanvasElement
16
+ * wraps the React tree in ShadowRootProvider, and tests use the helper.
17
+ */
18
+ export declare function useShadowRoot(): ShadowRootContextValue;
19
+ export {};
@@ -1,7 +1,6 @@
1
- import { ReactNode } from 'react';
2
- import { MountableComponent } from './api';
3
- import { CanvasTheme } from './components/ShadowCanvasOverlay';
4
- import { SmartCanvasController } from './controller';
1
+ import { type ReactNode } from 'react';
2
+ import { type CanvasTheme } from './components/ShadowCanvasOverlay';
3
+ import type { SmartCanvasController } from './controller';
5
4
  import type { ExperimentClient } from './experiments/types';
6
5
  import type { SmartCanvasRuntime } from './runtime';
7
6
  import type { TelemetryClient } from './telemetry/types';
@@ -29,7 +28,6 @@ export interface SmartCanvasAppProps {
29
28
  footerSlot?: ReactNode;
30
29
  launcherLabel?: string;
31
30
  canvasHost?: HTMLElement | null;
32
- customRenderers?: Record<string, MountableComponent>;
33
31
  theme?: Partial<CanvasTheme>;
34
32
  }
35
- export declare function SmartCanvasApp({ controller, fetcher, configUri, configUriFeatureKey, configFeatureKey, fetchCredentials, pollIntervalMs, experiments, telemetry, runtime, overlayFetcher, overlayConfigUri, overlayConfigFeatureKey, overlayFetchCredentials, footerSlot, launcherLabel, canvasHost, customRenderers, theme, }: SmartCanvasAppProps): import("react/jsx-runtime").JSX.Element;
33
+ export declare function SmartCanvasApp({ controller, fetcher, configUri, configUriFeatureKey, configFeatureKey, fetchCredentials, pollIntervalMs, experiments, telemetry, runtime, overlayFetcher, overlayConfigUri, overlayConfigFeatureKey, overlayFetchCredentials, footerSlot, launcherLabel, canvasHost, theme, }: SmartCanvasAppProps): import("react/jsx-runtime").JSX.Element;
@@ -1,5 +1,4 @@
1
- import { MountableComponent } from './api';
2
- import { SmartCanvasController } from './controller';
1
+ import { type SmartCanvasController } from './controller';
3
2
  import { type SmartCanvasAppProps } from './SmartCanvasApp';
4
3
  export declare class SmartCanvasElement extends HTMLElement {
5
4
  #private;
@@ -8,11 +7,15 @@ export declare class SmartCanvasElement extends HTMLElement {
8
7
  disconnectedCallback(): void;
9
8
  getMountNode(): HTMLDivElement;
10
9
  getController(): SmartCanvasController;
11
- getOverlayRoot(): HTMLElement;
10
+ /** React portal target inside shadow root (launcher, drawer, toasts) */
11
+ getPortalRoot(): HTMLDivElement;
12
+ /** Vanilla JS overlay container inside shadow root (tooltips, modals, spotlights) */
13
+ getOverlayContainer(): HTMLDivElement;
14
+ /** Direct access to the shadow root (for style injection) */
15
+ getShadowRoot(): ShadowRoot;
12
16
  open(): void;
13
17
  close(): void;
14
18
  toggle(): void;
15
- registerComponent(key: string, component: MountableComponent): void;
16
19
  setOverrideFetcher(fetcher: any): void;
17
20
  /**
18
21
  * Used by standalone create() helper to bootstrap React into the shadow.
@@ -1,4 +1,4 @@
1
- import { ReactNode } from 'react';
1
+ import { type ReactNode } from 'react';
2
2
  import type { SmartCanvasElement } from './SmartCanvasElement';
3
3
  export interface SmartCanvasPortalProps {
4
4
  element: SmartCanvasElement | null;
@@ -7,7 +7,7 @@
7
7
  * Core app executors are imported from their respective app packages.
8
8
  */
9
9
  import type { ZodSchema } from 'zod';
10
- import type { ActionStep, ActionKind, ActionExecutor, ValidationResult } from '../types';
10
+ import type { ActionExecutor, ActionKind, ActionStep, ValidationResult } from '../types';
11
11
  /**
12
12
  * Registration entry for an executor.
13
13
  */
@@ -111,6 +111,6 @@ export declare function getExecutor(kind: ActionKind | string): ActionExecutor<A
111
111
  * @deprecated Use executorRegistry.has() instead
112
112
  */
113
113
  export declare function hasExecutor(kind: ActionKind | string): boolean;
114
- export { executeInsertHtml, executeSetText, executeSetAttr, executeAddClass, executeRemoveClass, executeSetStyle, } from '@syntrologie/adapt-content/runtime';
115
- export { executeHighlight, executePulse, executeBadge, executeTooltip, executeModal, } from '@syntrologie/adapt-overlays/runtime';
114
+ export { executeAddClass, executeInsertHtml, executeRemoveClass, executeSetAttr, executeSetStyle, executeSetText, } from '@syntrologie/adapt-content/runtime';
115
+ export { executeBadge, executeHighlight, executeModal, executePulse, executeTooltip, } from '@syntrologie/adapt-overlays/runtime';
116
116
  export { executeTour } from './tour';
@@ -7,7 +7,7 @@
7
7
  * Each step contains an inner action (modal, tooltip) that gets executed.
8
8
  * The tour listens for CTA click events to advance to the next step.
9
9
  */
10
- import type { TourAction, ActionExecutor } from '../types';
10
+ import type { ActionExecutor, TourAction } from '../types';
11
11
  /**
12
12
  * Execute a tour action
13
13
  *
@@ -4,7 +4,8 @@
4
4
  * Unified execution layer for interventions (highlight, tooltip, badge, DOM modifications).
5
5
  */
6
6
  export { createActionEngine } from './ActionEngine';
7
- export type { ActionEngine, ActionEngineOptions, ActionEngineExecutorRegistry, ActionHandle, BatchActionHandle, ActiveAction, ActionStep, ActionKind, HighlightAction, PulseAction, BadgeAction, TooltipAction, InsertHtmlAction, SetTextAction, SetAttrAction, AddClassAction, RemoveClassAction, SetStyleAction, MountWidgetAction, ScrollToAction, NavigateAction, HighlightStyle, BadgePosition, TooltipContent, TooltipTrigger, InsertPosition, WidgetConfig, ActionState, ValidationResult, ValidationError, ValidationWarning, ExecutorResult, ExecutorContext, ExecutorCleanup, ExecutorUpdate, ActionExecutor, } from './types';
8
- export { validateAction, validateActions } from './validation';
9
- export { ExecutorRegistry, executorRegistry, getExecutor, hasExecutor } from './executors';
10
7
  export type { ExecutorRegistration } from './executors';
8
+ export { ExecutorRegistry, executorRegistry, getExecutor, hasExecutor } from './executors';
9
+ export { AddClassZ, BadgePositionZ, BadgeZ, CtaButtonZ, coreActionStepSchemas, HighlightStyleZ, HighlightZ, InsertHtmlZ, InsertPositionZ, ModalContentZ, ModalZ, MountWidgetZ, NavigateZ, ParallelZ, PlacementZ, PulseZ, RemoveClassZ, ScrollBehaviorZ, ScrollLogicalPositionZ, ScrollToZ, SequenceZ, SetAttrZ, SetStyleZ, SetTextZ, TooltipContentZ, TooltipTriggerZ, TooltipZ, TourStepForSchemaZ, TourZ, WaitZ, WidgetConfigZ, } from './schema';
10
+ export type { ActionEngine, ActionEngineExecutorRegistry, ActionEngineOptions, ActionExecutor, ActionHandle, ActionKind, ActionState, ActionStep, ActiveAction, AddClassAction, BadgeAction, BadgePosition, BatchActionHandle, ExecutorCleanup, ExecutorContext, ExecutorResult, ExecutorUpdate, HighlightAction, HighlightStyle, InsertHtmlAction, InsertPosition, MountWidgetAction, NavigateAction, PulseAction, RemoveClassAction, ScrollToAction, SetAttrAction, SetStyleAction, SetTextAction, TooltipAction, TooltipContent, TooltipTrigger, ValidationError, ValidationResult, ValidationWarning, WidgetConfig, } from './types';
11
+ export { validateAction, validateActions } from './validation';