@syntrologie/runtime-sdk 2.1.0 → 2.2.0-canary.2

package/CAPABILITIES.md

@@ -742,38 +742,38 @@ Accordion of contextual navigation tips. Each tip has a collapsible header and e
 
 ### Tile Config
 
-| Property                 | Type                       | Required | Default    | Description                     |
-| ------------------------ | -------------------------- | -------- | ---------- | ------------------------------- |
-| `widget`                 | `"adaptive-nav:tips"`      | Yes      |            | Widget identifier               |
-| `props.expandBehavior`   | `"single"` \| `"multiple"` | No       | `"single"` | Accordion expand mode           |
-| `props.theme`            | `"light"` \| `"dark"` \| `"auto"` | No | `"auto"` | Color theme                     |
-| `props.actions`          | `NavTipAction[]`           | Yes      |            | Navigation tip items            |
+| Property               | Type                              | Required | Default    | Description           |
+| ---------------------- | --------------------------------- | -------- | ---------- | --------------------- |
+| `widget`               | `"adaptive-nav:tips"`             | Yes      |            | Widget identifier     |
+| `props.expandBehavior` | `"single"` \| `"multiple"`        | No       | `"single"` | Accordion expand mode |
+| `props.theme`          | `"light"` \| `"dark"` \| `"auto"` | No       | `"auto"`   | Color theme           |
+| `props.actions`        | `NavTipAction[]`                  | Yes      |            | Navigation tip items  |
 
 ### Nav Tip Action (`nav:tip`)
 
 Compositional action — rendered as an accordion item by the parent widget.
 
-| Property               | Type                         | Required | Description                          |
-| ---------------------- | ---------------------------- | -------- | ------------------------------------ |
-| `kind`                 | `"nav:tip"`                  | Yes      | Action type                          |
-| `config.id`            | string                       | Yes      | Unique tip identifier                |
-| `config.title`         | string                       | Yes      | Accordion header text                |
-| `config.description`   | string                       | Yes      | Expanded body text                   |
-| `config.href`          | string                       | No       | Optional CTA link URL                |
-| `config.icon`          | string                       | No       | Icon (emoji or icon key)             |
-| `config.external`      | boolean                      | No       | Open link in new tab                 |
-| `config.category`      | string                       | No       | Category for grouping                |
-| `showWhen`             | `DecisionStrategy<boolean>`  | No       | Conditional visibility               |
-| `notify`               | `{ title?, body?, icon? }`   | No       | Toast config for showWhen transition |
-| `rationale`            | `{ why, confidence? }`       | No       | AI reasoning for recommendation      |
+| Property             | Type                        | Required | Description                          |
+| -------------------- | --------------------------- | -------- | ------------------------------------ |
+| `kind`               | `"nav:tip"`                 | Yes      | Action type                          |
+| `config.id`          | string                      | Yes      | Unique tip identifier                |
+| `config.title`       | string                      | Yes      | Accordion header text                |
+| `config.description` | string                      | Yes      | Expanded body text                   |
+| `config.href`        | string                      | No       | Optional CTA link URL                |
+| `config.icon`        | string                      | No       | Icon (emoji or icon key)             |
+| `config.external`    | boolean                     | No       | Open link in new tab                 |
+| `config.category`    | string                      | No       | Category for grouping                |
+| `showWhen`           | `DecisionStrategy<boolean>` | No       | Conditional visibility               |
+| `notify`             | `{ title?, body?, icon? }`  | No       | Toast config for showWhen transition |
+| `rationale`          | `{ why, confidence? }`      | No       | AI reasoning for recommendation      |
 
 ### Events Published
 
-| Event              | When                                  | Props                                |
-| ------------------ | ------------------------------------- | ------------------------------------ |
-| `nav:toggled`      | User expands/collapses a tip          | `{ instanceId, tipId, expanded }`    |
-| `nav:tip_clicked`  | User clicks a tip's CTA link          | `{ instanceId, href, external }`     |
-| `nav:tip_revealed` | `showWhen` transitions false → true   | `{ tipId, title, body, icon }`       |
+| Event              | When                                | Props                             |
+| ------------------ | ----------------------------------- | --------------------------------- |
+| `nav:toggled`      | User expands/collapses a tip        | `{ instanceId, tipId, expanded }` |
+| `nav:tip_clicked`  | User clicks a tip's CTA link        | `{ instanceId, href, external }`  |
+| `nav:tip_revealed` | `showWhen` transitions false → true | `{ tipId, title, body, icon }`    |
 
 ### Notify Watchers
 
@@ -808,7 +808,14 @@ Tips with both `showWhen` and `notify` are registered as notify watchers. The ru
         "notify": { "title": "New Tip", "body": "Advanced Analytics", "icon": "📊" },
         "showWhen": {
           "type": "rules",
-          "rules": [{ "conditions": [{ "type": "event_count", "key": "link-clicks", "operator": "gte", "count": 3 }], "value": true }],
+          "rules": [
+            {
+              "conditions": [
+                { "type": "event_count", "key": "link-clicks", "operator": "gte", "count": 3 }
+              ],
+              "value": true
+            }
+          ],
           "default": false
         }
       }
@@ -823,12 +830,12 @@ Tips with both `showWhen` and `notify` are registered as notify watchers. The ru
 
 Scrolls the viewport to bring an element into view.
 
-| Property   | Type          | Required | Default     | Description                                 |
-| ---------- | ------------- | -------- | ----------- | ------------------------------------------- |
-| `kind`     | `"navigation:scrollTo"` | Yes |           | Action type                                 |
-| `anchorId` | string        | Yes      |             | Element selector                            |
-| `behavior` | string        | No       | `"smooth"`  | `"smooth"`, `"instant"`, `"auto"`           |
-| `block`    | string        | No       | `"center"`  | `"start"`, `"center"`, `"end"`, `"nearest"` |
+| Property   | Type                    | Required | Default    | Description                                 |
+| ---------- | ----------------------- | -------- | ---------- | ------------------------------------------- |
+| `kind`     | `"navigation:scrollTo"` | Yes      |            | Action type                                 |
+| `anchorId` | string                  | Yes      |            | Element selector                            |
+| `behavior` | string                  | No       | `"smooth"` | `"smooth"`, `"instant"`, `"auto"`           |
+| `block`    | string                  | No       | `"center"` | `"start"`, `"center"`, `"end"`, `"nearest"` |
 
 ### `navigation:navigate`
 
@@ -836,7 +843,7 @@ Navigates to a URL.
 
 | Property | Type                    | Required | Default   | Description             |
 | -------- | ----------------------- | -------- | --------- | ----------------------- |
-| `kind`   | `"navigation:navigate"` | Yes     |           | Action type             |
+| `kind`   | `"navigation:navigate"` | Yes      |           | Action type             |
 | `url`    | string                  | Yes      |           | Destination URL         |
 | `target` | string                  | No       | `"_self"` | `"_self"` or `"_blank"` |
 
@@ -879,17 +886,17 @@ Creates a spotlight effect around an element with a scrim overlay.
 
 Shows a tooltip near an element with optional title, body, and CTA.
 
-| Property             | Type        | Required | Default       | Description                         |
-| -------------------- | ----------- | -------- | ------------- | ----------------------------------- |
-| `kind`               | `"tooltip"` | Yes      |               | Action type                         |
-| `anchorId`           | string      | Yes      |               | Element selector                    |
-| `content.title`      | string      | No       |               | Tooltip heading                     |
-| `content.body`       | string      | Yes      |               | Tooltip text                        |
-| `content.cta.label`  | string      | No       |               | CTA button text (single-CTA shorthand)  |
-| `content.cta.action` | Action      | No       |               | Action to execute on CTA click           |
-| `content.ctaButtons` | array       | No       |               | Multiple CTA buttons (see below)         |
-| `trigger`            | string      | No       | `"immediate"` | `"immediate"`, `"hover"`, `"click"`      |
-| `placement`          | string      | No       | `"top"`       | See placement options below              |
+| Property             | Type        | Required | Default       | Description                            |
+| -------------------- | ----------- | -------- | ------------- | -------------------------------------- |
+| `kind`               | `"tooltip"` | Yes      |               | Action type                            |
+| `anchorId`           | string      | Yes      |               | Element selector                       |
+| `content.title`      | string      | No       |               | Tooltip heading                        |
+| `content.body`       | string      | Yes      |               | Tooltip text                           |
+| `content.cta.label`  | string      | No       |               | CTA button text (single-CTA shorthand) |
+| `content.cta.action` | Action      | No       |               | Action to execute on CTA click         |
+| `content.ctaButtons` | array       | No       |               | Multiple CTA buttons (see below)       |
+| `trigger`            | string      | No       | `"immediate"` | `"immediate"`, `"hover"`, `"click"`    |
+| `placement`          | string      | No       | `"top"`       | See placement options below            |
 
 **Placement options:** `top`, `top-start`, `top-end`, `bottom`, `bottom-start`, `bottom-end`, `left`, `left-start`, `left-end`, `right`, `right-start`, `right-end`
 

package/README.md

@@ -1,6 +1,6 @@
-# Syntrologie Smart Canvas SDK
+# Smart Canvas Runtime SDK
 
-## Smart Canvas SDK (React + Shadow DOM)
+## Smart Canvas Runtime SDK (React + Shadow DOM)
 
 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.
 
@@ -73,7 +73,7 @@ For quick setup without a build process:
 ### Local Development
 
 ```bash
-cd tech-core/sdks/runtime-sdk
+cd packages/runtime-sdk
 npm run build
 ```
 
@@ -322,7 +322,7 @@ if (result.value) {
 - Validate a config file locally:
 
 ```bash
-cd tech-core/sdks/runtime-sdk
+cd packages/runtime-sdk
 npm run validate-config -- path/to/config.json
 ```
 
@@ -336,7 +336,7 @@ The SDK uses [semantic-release](https://github.com/semantic-release/semantic-rel
 
 | Channel    | Trigger                                        | npm dist-tag | CDN path                      |
 | ---------- | ---------------------------------------------- | ------------ | ----------------------------- |
-| **Canary** | Push to `develop` touching `tech-core/sdks/**` | `develop`    | `/v2/canary/`                 |
+| **Canary** | Push to `develop` touching `packages/**` | `develop`    | `/v2/canary/`                 |
 | **Stable** | Manual workflow dispatch from `main`           | `latest`     | `/v2/latest/` + `/{VERSION}/` |
 
 ### Commit Messages → Version Bumps
@@ -411,7 +411,7 @@ https://cdn.syntrologie.com/runtime-sdk/v2/latest/adaptives/{appId}/index.js
 
 - **"No new version is released"** — 0 relevant commits since last tag. Push a `fix:` or `feat:` commit touching SDK paths.
 - **npm 404 / auth error** — package missing trusted publisher config on npmjs.com.
-- **Format check fails** — run `npx prettier --write <file>` locally before pushing.
+- **Format check fails** — run `npx biome check --fix <file>` locally before pushing.
 
 ---
 
@@ -426,7 +426,7 @@ https://cdn.syntrologie.com/runtime-sdk/v2/latest/adaptives/{appId}/index.js
 ## Directory Overview
 
 ```
-tech-core/sdks/runtime-sdk
+packages/runtime-sdk
 ├─ src
 │  ├─ actions/              # ActionEngine (interventions)
 │  │  ├─ types.ts

package/dist/RuntimeProvider.d.ts

@@ -3,7 +3,7 @@
  *
  * Provides access to the SmartCanvasRuntime from any component in the tree.
  */
-import { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 import type { RuntimeContext } from './context/types';
 import type { SmartCanvasRuntime } from './runtime';
 export interface RuntimeProviderProps {

package/dist/ShadowRootContext.d.ts

@@ -0,0 +1,19 @@
+import { type ReactNode } from 'react';
+interface ShadowRootContextValue {
+    shadowRoot: ShadowRoot;
+    portalRoot: HTMLElement;
+    overlayContainer: HTMLElement;
+}
+export interface ShadowRootProviderProps {
+    shadowRoot: ShadowRoot;
+    portalRoot: HTMLElement;
+    overlayContainer: HTMLElement;
+    children: ReactNode;
+}
+export declare function ShadowRootProvider({ shadowRoot, portalRoot, overlayContainer, children, }: ShadowRootProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Access the shadow root context. Always available — SmartCanvasElement
+ * wraps the React tree in ShadowRootProvider, and tests use the helper.
+ */
+export declare function useShadowRoot(): ShadowRootContextValue;
+export {};

package/dist/SmartCanvasApp.d.ts

@@ -1,6 +1,6 @@
-import { ReactNode } from 'react';
-import { CanvasTheme } from './components/ShadowCanvasOverlay';
-import { SmartCanvasController } from './controller';
+import { type ReactNode } from 'react';
+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';

package/dist/SmartCanvasElement.d.ts

@@ -1,4 +1,4 @@
-import { SmartCanvasController } from './controller';
+import { type SmartCanvasController } from './controller';
 import { type SmartCanvasAppProps } from './SmartCanvasApp';
 export declare class SmartCanvasElement extends HTMLElement {
     #private;
@@ -7,7 +7,12 @@ export declare class SmartCanvasElement extends HTMLElement {
     disconnectedCallback(): void;
     getMountNode(): HTMLDivElement;
     getController(): SmartCanvasController;
-    getOverlayRoot(): HTMLElement;
+    /** React portal target inside shadow root (launcher, drawer, toasts) */
+    getPortalRoot(): HTMLDivElement;
+    /** Vanilla JS overlay container inside shadow root (tooltips, modals, spotlights) */
+    getOverlayContainer(): HTMLDivElement;
+    /** Direct access to the shadow root (for style injection) */
+    getShadowRoot(): ShadowRoot;
     open(): void;
     close(): void;
     toggle(): void;

package/dist/SmartCanvasPortal.d.ts

@@ -1,4 +1,4 @@
-import { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 import type { SmartCanvasElement } from './SmartCanvasElement';
 export interface SmartCanvasPortalProps {
     element: SmartCanvasElement | null;

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

@@ -7,7 +7,7 @@
  * Core app executors are imported from their respective app packages.
  */
 import type { ZodSchema } from 'zod';
-import type { ActionStep, ActionKind, ActionExecutor, ValidationResult } from '../types';
+import type { ActionExecutor, ActionKind, ActionStep, ValidationResult } from '../types';
 /**
  * Registration entry for an executor.
  */
@@ -111,6 +111,6 @@ export declare function getExecutor(kind: ActionKind | string): ActionExecutor<A
  * @deprecated Use executorRegistry.has() instead
  */
 export declare function hasExecutor(kind: ActionKind | string): boolean;
-export { executeInsertHtml, executeSetText, executeSetAttr, executeAddClass, executeRemoveClass, executeSetStyle, } from '@syntrologie/adapt-content/runtime';
-export { executeHighlight, executePulse, executeBadge, executeTooltip, executeModal, } from '@syntrologie/adapt-overlays/runtime';
+export { executeAddClass, executeInsertHtml, executeRemoveClass, executeSetAttr, executeSetStyle, executeSetText, } from '@syntrologie/adapt-content/runtime';
+export { executeBadge, executeHighlight, executeModal, executePulse, executeTooltip, } from '@syntrologie/adapt-overlays/runtime';
 export { executeTour } from './tour';

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

@@ -7,7 +7,7 @@
  * Each step contains an inner action (modal, tooltip) that gets executed.
  * The tour listens for CTA click events to advance to the next step.
  */
-import type { TourAction, ActionExecutor } from '../types';
+import type { ActionExecutor, TourAction } from '../types';
 /**
  * Execute a tour action
  *

package/dist/actions/index.d.ts

@@ -4,7 +4,8 @@
  * Unified execution layer for interventions (highlight, tooltip, badge, DOM modifications).
  */
 export { createActionEngine } from './ActionEngine';
-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';
-export { validateAction, validateActions } from './validation';
-export { ExecutorRegistry, executorRegistry, getExecutor, hasExecutor } from './executors';
 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 { validateAction, validateActions } from './validation';