@syntrologie/runtime-sdk 2.4.0-canary.2 → 2.4.0-canary.21

package/CAPABILITIES.md

@@ -10,6 +10,7 @@ This document describes all available operations and capabilities of the SmartCa
 - [Adaptive Packages](#adaptive-packages)
 - [Surfaces](#surfaces)
 - [Anchor Resolution](#anchor-resolution)
+- [Route Scoping](#route-scoping)
 - [Decision Strategies](#decision-strategies)
 - [Best Practices](#best-practices)
 
@@ -854,7 +855,7 @@ Navigates to a URL.
 
 # @syntrologie/adapt-overlays
 
-Visual overlay capabilities including highlights, tooltips, badges, and pulse animations.
+Visual overlay capabilities including highlights, tooltips, badges, pulse animations, and celebrations.
 
 ## Actions
 
@@ -1028,6 +1029,71 @@ Shows a centered modal dialog with optional CTA buttons.
 }
 ```
 
+### celebrate
+
+Renders a fullscreen Canvas 2D celebration effect. One action kind with a pluggable `effect` parameter supporting multiple visual presets.
+
+| Property    | Type                               | Required | Default                    | Description                                   |
+| ----------- | ---------------------------------- | -------- | -------------------------- | --------------------------------------------- |
+| `kind`      | `"overlays:celebrate"`             | Yes      |                            | Action type                                   |
+| `effect`    | string                             | Yes      |                            | Effect name (see presets below)                |
+| `duration`  | number                             | No       | `3000`                     | Animation duration in ms                      |
+| `intensity` | `"light"` \| `"medium"` \| `"heavy"` | No       | `"medium"`                 | Particle density                              |
+| `colors`    | string[]                           | No       | Rainbow palette            | Color palette for particles                   |
+| `props`     | object                             | No       |                            | Effect-specific properties (see presets below) |
+
+**Available effect presets:**
+
+- **`confetti`** — Falling rectangular/circular confetti pieces with gravity, air resistance, and rotation
+- **`fireworks`** — Multiple burst centers with radiating particles, deceleration, and glow effect
+- **`sparkles`** — Diamond shapes that twinkle via sine-wave opacity oscillation and float gently upward
+- **`emoji-rain`** — Emoji characters falling from the top with horizontal sine-wave wobble. Use `props.emoji` to set the character (default: `"🎉"`)
+
+**Confetti:**
+
+```json
+{
+  "kind": "overlays:celebrate",
+  "effect": "confetti",
+  "duration": 4000,
+  "intensity": "heavy",
+  "colors": ["#ff0000", "#00ff00", "#0000ff", "#ffff00"]
+}
+```
+
+**Fireworks:**
+
+```json
+{
+  "kind": "overlays:celebrate",
+  "effect": "fireworks",
+  "duration": 3000,
+  "intensity": "medium"
+}
+```
+
+**Sparkles:**
+
+```json
+{
+  "kind": "overlays:celebrate",
+  "effect": "sparkles",
+  "duration": 5000,
+  "colors": ["#ffd700", "#ffffff", "#fffacd"]
+}
+```
+
+**Emoji rain:**
+
+```json
+{
+  "kind": "overlays:celebrate",
+  "effect": "emoji-rain",
+  "duration": 3000,
+  "props": { "emoji": "🔥" }
+}
+```
+
 
 ---
 
@@ -1092,6 +1158,55 @@ Then reference by the anchor name:
 
 ---
 
+## Route Scoping
+
+Every tile and action **must** declare which pages it applies to via `activation.routes`. The config itself is always active — individual tiles and actions decide independently whether to render.
+
+### Per-Tile Activation
+
+```json
+{
+  "id": "faq-w2-boxes",
+  "widget": "adaptive-faq:accordion",
+  "activation": {
+    "routes": { "include": ["/dashboard/income"] }
+  },
+  "props": { ... }
+}
+```
+
+### Per-Action Activation
+
+```json
+{
+  "kind": "content:insertHtml",
+  "anchorId": "[data-section='refund-estimate']",
+  "activation": {
+    "routes": { "include": ["/dashboard"] }
+  },
+  "html": "...",
+  "position": "after"
+}
+```
+
+### Route Patterns
+
+| Pattern | Matches | Use Case |
+|---------|---------|----------|
+| `"/dashboard/income"` | Exact path only | Page-specific |
+| `"/dashboard/**"` | `/dashboard` and all sub-paths | Section-wide |
+| `"/**"` | All pages | Global (always active) |
+| `"/dashboard/:id"` | Any single segment after `/dashboard/` | Dynamic routes |
+
+### Pattern Matching 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`
+
+---
+
 ## Decision Strategies
 
 Control when adaptives activate using `DecisionStrategy`:

package/dist/SmartCanvasApp.d.ts

@@ -1,10 +1,10 @@
 import { type ReactNode } from 'react';
 import type { BatchActionHandle } from './actions/types';
-import { type CanvasTheme } from './components/ShadowCanvasOverlay';
 import type { SmartCanvasController } from './controller';
 import type { ExperimentClient } from './experiments/types';
 import type { SmartCanvasRuntime } from './runtime';
 import type { TelemetryClient } from './telemetry/types';
+import type { CanvasThemeConfig } from './theme';
 import type { CanvasConfigFetcher } from './types';
 export interface SmartCanvasAppProps {
     controller: SmartCanvasController;
@@ -13,6 +13,7 @@ export interface SmartCanvasAppProps {
     configUriFeatureKey?: string;
     configFeatureKey?: string;
     fetchCredentials?: RequestCredentials;
+    /** @deprecated No longer used — config updates are event-driven via ExperimentClient.onFeaturesChanged */
     pollIntervalMs?: number;
     experiments?: ExperimentClient;
     telemetry?: TelemetryClient;
@@ -29,8 +30,9 @@ export interface SmartCanvasAppProps {
     footerSlot?: ReactNode;
     launcherLabel?: string;
     canvasHost?: HTMLElement | null;
-    theme?: Partial<CanvasTheme>;
     /** Batch handle from eager action application in createSmartCanvas(). Prevents double-apply. */
     initialBatchHandle?: BatchActionHandle | null;
+    /** Workspace-level theme for 3-layer inheritance (defaults → workspace → config) */
+    workspaceTheme?: CanvasThemeConfig;
 }
-export declare function SmartCanvasApp({ controller, fetcher, configUri, configUriFeatureKey, configFeatureKey, fetchCredentials, pollIntervalMs, experiments, telemetry, runtime, overlayFetcher, overlayConfigUri, overlayConfigFeatureKey, overlayFetchCredentials, footerSlot, launcherLabel, canvasHost, theme, initialBatchHandle, }: SmartCanvasAppProps): import("react/jsx-runtime").JSX.Element;
+export declare function SmartCanvasApp({ controller, fetcher, configUri, configUriFeatureKey, configFeatureKey, fetchCredentials, pollIntervalMs, experiments, telemetry, runtime, overlayFetcher, overlayConfigUri, overlayConfigFeatureKey, overlayFetchCredentials, footerSlot, launcherLabel, canvasHost, initialBatchHandle, workspaceTheme, }: SmartCanvasAppProps): import("react/jsx-runtime").JSX.Element;

package/dist/actions/executors/index.d.ts

@@ -112,6 +112,5 @@ export declare function getExecutor(kind: ActionKind | string): ActionExecutor<A
  */
 export declare function hasExecutor(kind: ActionKind | string): boolean;
 export { executeAddClass, executeInsertHtml, executeRemoveClass, executeSetAttr, executeSetStyle, executeSetText, } from '@syntrologie/adapt-content/runtime';
-export { executeBadge, executeHighlight, executeModal, executePulse, executeTooltip, } from '@syntrologie/adapt-overlays/runtime';
+export { executeBadge, executeHighlight, executeModal, executePulse, executeTooltip, executeTour, } from '@syntrologie/adapt-overlays/runtime';
 export { executeParallel, executeSequence, executeWait } from './core-flow';
-export { executeTour } from './tour';

package/dist/actions/index.d.ts

@@ -6,6 +6,6 @@
 export { createActionEngine } from './ActionEngine';
 export type { ExecutorRegistration } from './executors';
 export { ExecutorRegistry, executorRegistry, getExecutor, hasExecutor } from './executors';
-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';
-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';
+export { AddClassZ, AnchorIdZ, 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';
+export type { ActionEngine, ActionEngineExecutorRegistry, ActionEngineOptions, ActionExecutor, ActionHandle, ActionKind, ActionState, ActionStep, ActiveAction, AddClassAction, AnchorId, BadgeAction, BadgePosition, BatchActionHandle, ExecutorCleanup, ExecutorContext, ExecutorResult, ExecutorUpdate, HighlightAction, HighlightStyle, InsertHtmlAction, InsertPosition, MountWidgetAction, NavigateAction, PulseAction, RemoveClassAction, ScrollToAction, SetAttrAction, SetStyleAction, SetTextAction, TooltipAction, TooltipContent, TooltipTrigger, TourAction, TourStep, ValidationError, ValidationResult, ValidationWarning, WidgetConfig, } from './types';
 export { validateAction, validateActions } from './validation';