@syntrologie/adapt-overlays 2.15.0 → 2.17.0

package/dist/schema.js

@@ -1,156 +1,445 @@
-/**
- * Adaptive Overlays - Config Schema
- *
- * Zod schema for validating overlays app configuration.
- */
-import { AnchorIdZ, TriggerWhenZ } from '@syntrologie/sdk-contracts';
-import { z } from 'zod';
-/**
- * Overlays app config schema.
- * Defines the structure for overlay configurations in a canvas config.
- */
-export const configSchema = z.object({
-    /** Highlight configurations */
-    highlights: z
-        .array(z.object({
-        anchorId: AnchorIdZ,
-        summary: z.string(),
-        style: z
-            .object({
-            color: z.string().optional(),
-            paddingPx: z.number().optional(),
-            radiusPx: z.number().optional(),
-            scrimOpacity: z.number().optional(),
+import "./chunk-VHAA22YE.js";
+
+// ../../sdk-contracts/dist/schemas.js
+import { z } from "zod";
+var AnchorIdZ = z.object({
+  selector: z.string(),
+  route: z.union([z.string(), z.array(z.string())])
+}).strict();
+var AuthoringFieldsZ = {
+  title: z.string().max(200).optional().describe("Authoring-only: short label shown on the action plan dashboard. Stripped before serving to the runtime SDK."),
+  description: z.string().max(1e3).optional().describe("Authoring-only: one-sentence explanation of what this action does and why. Stripped before serving to the runtime SDK."),
+  validation: z.array(z.string().max(500)).max(10).optional().describe("Authoring-only: ordered steps a reviewer can follow to trigger this action and visually confirm it works. Each entry is one step. Stripped before serving to the runtime SDK.")
+};
+var COUNTABLE_EVENTS = [
+  // User interactions (from PostHog autocapture normalization)
+  "ui.click",
+  "ui.scroll",
+  "ui.input",
+  "ui.change",
+  "ui.submit",
+  // Behavioral detectors (from event-processor)
+  "ui.hover",
+  "ui.idle",
+  "ui.scroll_thrash",
+  "ui.focus_bounce",
+  // Navigation
+  "nav.page_view",
+  "nav.page_leave",
+  // Derived behavioral signals
+  "behavior.rage_click",
+  "behavior.hesitation",
+  "behavior.confusion"
+];
+var CountableEventZ = z.enum(COUNTABLE_EVENTS).describe("Event name to count. ui.* = user interactions and behavioral detectors, nav.* = page navigation, behavior.* = derived behavioral signals.");
+var SESSION_METRIC_KEYS = ["time_on_page", "page_views", "scroll_depth"];
+var SessionMetricKeyZ = z.enum(SESSION_METRIC_KEYS).describe("Session metric key. time_on_page = seconds on current page, page_views = pages visited this session, scroll_depth = 0-100 percentage.");
+var PageUrlConditionZ = z.object({
+  type: z.literal("page_url"),
+  url: z.string().describe('URL path to match (e.g. "/pricing", "/dashboard")')
+}).describe('Fires when the current page URL matches. Use for page-specific actions. Example: {"type": "page_url", "url": "/pricing"}');
+var RouteConditionZ = z.object({
+  type: z.literal("route"),
+  routeId: z.string().describe("Named route ID from the route filter")
+}).describe("Fires when the current route matches a named route ID.");
+var AnchorVisibleConditionZ = z.object({
+  type: z.literal("anchor_visible"),
+  anchorId: z.string().describe("CSS selector of the anchor element"),
+  state: z.enum(["visible", "present", "absent"]).describe('"visible" = in viewport, "present" = in DOM, "absent" = not in DOM')
+}).describe(`Fires based on a DOM element's visibility state. Example: {"type": "anchor_visible", "anchorId": "#cta-button", "state": "visible"}`);
+var EventOccurredConditionZ = z.object({
+  type: z.literal("event_occurred"),
+  eventName: z.string().describe('Event name (e.g. "ui.click", "$pageview")'),
+  withinMs: z.number().optional().describe("Time window in ms. Omit = any time this session.")
+}).describe('Fires when a specific event has occurred during this session. Example: {"type": "event_occurred", "eventName": "ui.click", "withinMs": 5000}');
+var StateEqualsConditionZ = z.object({
+  type: z.literal("state_equals"),
+  key: z.string().describe("Key in the SDK persistent state store (localStorage). Only valid for keys the host app explicitly sets via syntro.state.set()."),
+  value: z.unknown().describe("Expected value to match against")
+}).describe("Checks the SDK persistent state store (localStorage). ONLY for host-app state set via syntro.state.set() \u2014 NOT for user attributes like region, device, or UTM params (those are handled by segment targeting). Do NOT use this for targeting. If you do not know the valid state keys, do not use this condition type.");
+var ViewportConditionZ = z.object({
+  type: z.literal("viewport"),
+  minWidth: z.number().optional().describe("Minimum viewport width in pixels"),
+  maxWidth: z.number().optional().describe("Maximum viewport width in pixels"),
+  minHeight: z.number().optional().describe("Minimum viewport height in pixels"),
+  maxHeight: z.number().optional().describe("Maximum viewport height in pixels")
+}).describe('Fires based on viewport (screen) size. Use for responsive behavior. Example: {"type": "viewport", "minWidth": 768} \u2014 fires on tablet and larger.');
+var SessionMetricConditionZ = z.object({
+  type: z.literal("session_metric"),
+  key: SessionMetricKeyZ,
+  operator: z.enum(["gte", "lte", "eq", "gt", "lt"]),
+  threshold: z.number().describe("Numeric threshold to compare against")
+}).describe('Fires when a session metric crosses a threshold. Valid keys: "time_on_page" (seconds), "page_views" (count), "scroll_depth" (0-100). Example: {"type": "session_metric", "key": "time_on_page", "operator": "gte", "threshold": 30}');
+var DismissedConditionZ = z.object({
+  type: z.literal("dismissed"),
+  key: z.string().describe("Dismissal key (usually a tile or action ID)"),
+  inverted: z.boolean().optional().describe("When true, fires if NOT dismissed (default behavior)")
+}).describe("Checks if an item has been dismissed by the user. Use with inverted: true to show only if not dismissed.");
+var CooldownActiveConditionZ = z.object({
+  type: z.literal("cooldown_active"),
+  key: z.string().describe("Cooldown key"),
+  inverted: z.boolean().optional().describe("When true, fires if cooldown is NOT active")
+}).describe("Checks if a cooldown timer is currently active. Use to prevent showing the same intervention too frequently.");
+var FrequencyLimitConditionZ = z.object({
+  type: z.literal("frequency_limit"),
+  key: z.string().describe("Frequency counter key"),
+  limit: z.number().describe("Maximum allowed count"),
+  inverted: z.boolean().optional().describe("When true, fires if limit NOT reached")
+}).describe("Checks if a frequency limit has been reached. Use to cap how many times an action fires per session.");
+var MatchOpZ = z.object({
+  equals: z.union([z.string(), z.number(), z.boolean()]).optional(),
+  contains: z.string().optional()
+}).describe("Match operator for counter filters. Exactly one of equals or contains must be specified.");
+var CounterDefZ = z.object({
+  events: z.array(CountableEventZ).min(1).describe("Event names to count. Use values from the countable events enum."),
+  match: z.record(z.string(), MatchOpZ).optional().describe("Property filters. Keys are event prop names or element-chain fields (tag_name, $el_text, attr__*). All entries AND together.")
+}).describe("Defines what events to count. Registered as an accumulator predicate at config-load time.");
+var EventCountConditionZ = z.object({
+  type: z.literal("event_count"),
+  key: z.string().describe("Unique key for this counter (used for accumulator registration)"),
+  operator: z.enum(["gte", "lte", "eq", "gt", "lt"]),
+  count: z.number().int().min(0).describe("Target count threshold"),
+  withinMs: z.number().positive().optional().describe("Time window in ms. Omit = count across entire session."),
+  counter: CounterDefZ.optional().describe("Inline counter definition. Defines what events to count.")
+}).describe('Fires when accumulated event count crosses a threshold. Most powerful trigger type. Example: {"type": "event_count", "key": "pricing-clicks", "operator": "gte", "count": 3, "counter": {"events": ["ui.click"], "match": {"attr__data-cta": {"contains": "pricing"}}}}');
+var ConditionZ = z.discriminatedUnion("type", [
+  PageUrlConditionZ,
+  RouteConditionZ,
+  AnchorVisibleConditionZ,
+  EventOccurredConditionZ,
+  StateEqualsConditionZ,
+  ViewportConditionZ,
+  SessionMetricConditionZ,
+  DismissedConditionZ,
+  CooldownActiveConditionZ,
+  FrequencyLimitConditionZ,
+  EventCountConditionZ
+]);
+var RuleZ = z.object({
+  conditions: z.array(ConditionZ).describe("Array of conditions \u2014 ALL must match (AND logic) for this rule to fire."),
+  value: z.unknown().describe("Value returned when all conditions match. For triggerWhen: true = fire the action.")
+}).describe("A single rule. ALL conditions must match (AND logic). Rules in a strategy are evaluated top-to-bottom \u2014 first rule where all conditions match wins and returns its value.");
+var RuleStrategyZ = z.object({
+  type: z.literal("rules"),
+  rules: z.array(RuleZ).describe("Ordered list of rules. Evaluated top-to-bottom \u2014 first match wins."),
+  default: z.unknown().describe("Fallback value when no rule matches. For triggerWhen: false = do not fire by default.")
+}).describe("Rule-based strategy. Evaluates rules top-to-bottom. First rule where ALL conditions match returns its value. If no rule matches, returns default. For triggerWhen: set value=true on matching rules, default=false.");
+var ScoreStrategyZ = z.object({
+  type: z.literal("score"),
+  field: z.string(),
+  threshold: z.number(),
+  above: z.unknown(),
+  below: z.unknown()
+}).describe("Score-based strategy. Compares a field value against a threshold.");
+var ModelStrategyZ = z.object({
+  type: z.literal("model"),
+  modelId: z.string(),
+  inputs: z.array(z.string()),
+  outputMapping: z.record(z.string(), z.unknown()),
+  default: z.unknown()
+}).describe("ML model strategy. Sends inputs to a model and maps outputs.");
+var ExternalStrategyZ = z.object({
+  type: z.literal("external"),
+  endpoint: z.string(),
+  method: z.enum(["GET", "POST"]).optional(),
+  default: z.unknown(),
+  timeoutMs: z.number().optional()
+}).describe("External API strategy. Calls an endpoint to determine the value.");
+var DecisionStrategyZ = z.discriminatedUnion("type", [
+  RuleStrategyZ,
+  ScoreStrategyZ,
+  ModelStrategyZ,
+  ExternalStrategyZ
+]);
+var TriggerWhenZ = DecisionStrategyZ.nullable().optional();
+var EventScopeZ = z.object({
+  events: z.array(z.string()),
+  urlContains: z.string().optional(),
+  props: z.record(z.union([z.string(), z.number(), z.boolean()])).optional()
+});
+var NotifyZ = z.object({
+  title: z.string().optional(),
+  body: z.string().optional(),
+  icon: z.string().optional()
+}).nullable().optional();
+
+// src/schema.ts
+import { z as z2 } from "zod";
+var configSchema = z2.object({
+  /** Highlight configurations */
+  highlights: z2.array(
+    z2.object({
+      anchorId: AnchorIdZ.describe("Route and CSS selector of the element to spotlight."),
+      summary: z2.string().describe(
+        "Human-readable description of this highlight, used for logging and debugging."
+      ),
+      style: z2.object({
+        color: z2.string().optional().describe(
+          'Ring color as a CSS color string (e.g. "#5b8cff"). Defaults to brand blue.'
+        ),
+        paddingPx: z2.number().optional().describe(
+          "Space in pixels between the element edge and the spotlight ring. Defaults to 12."
+        ),
+        radiusPx: z2.number().optional().describe("Corner radius of the spotlight ring in pixels. Defaults to 12."),
+        scrimOpacity: z2.number().optional().describe(
+          "Opacity of the dark backdrop behind the spotlight (0\u20131). Set to 0 to show the ring without dimming the page. Defaults to 0.55."
+        )
+      }).optional().describe("Optional visual style overrides for the spotlight ring and backdrop.")
+    }).describe(
+      "A spotlight highlight that dims the page and draws a ring around a target element."
+    )
+  ).optional().describe(
+    "Spotlight highlights: draw attention to specific elements by ringing them with a colored border and dimming the rest of the page."
+  ),
+  /** Tooltip configurations */
+  tooltips: z2.array(
+    z2.object({
+      anchorId: AnchorIdZ.describe(
+        "Route and CSS selector of the element the tooltip is anchored to."
+      ),
+      summary: z2.string().describe(
+        "Human-readable description of this tooltip, used for logging and debugging."
+      ),
+      content: z2.object({
+        title: z2.string().optional().describe("Optional heading shown at the top of the tooltip."),
+        body: z2.string().describe(
+          "Main tooltip text (required). Explains the feature or provides guidance."
+        ),
+        cta: z2.object({
+          label: z2.string().describe("Button label text for the single CTA."),
+          action: z2.unknown().describe("Action step to execute when the CTA is clicked.")
+        }).optional().describe(
+          "Optional single CTA button shorthand. Use ctaButtons for multiple actions."
+        ),
+        ctaButtons: z2.array(
+          z2.object({
+            label: z2.string().describe("Button label text."),
+            actionId: z2.string().describe(
+              'Action identifier published with the action.tooltip_cta_clicked event. Special values: "dismiss" closes the tooltip without publishing an event; "faq:open:<questionId>" opens the corresponding FAQ question in an adaptive-faq:accordion widget (companion tooltip pattern). Any other value publishes action.tooltip_cta_clicked with the actionId in event props for custom handling.'
+            ),
+            primary: z2.boolean().optional().describe(
+              "When true, renders as the primary (filled) button style. Defaults to false."
+            )
+          })
+        ).optional().describe(
+          "Optional multi-button CTA row. Preferred over the single cta shorthand when more than one action is needed. Each button publishes action.tooltip_cta_clicked with its actionId."
+        )
+      }).describe("Tooltip content including body text and optional title and CTA."),
+      trigger: z2.enum(["immediate", "hover", "click"]).optional().describe(
+        '"immediate" shows on mount; "hover" shows when the user hovers the anchor; "click" shows on click. Defaults to "immediate".'
+      ),
+      placement: z2.enum([
+        "top",
+        "top-start",
+        "top-end",
+        "bottom",
+        "bottom-start",
+        "bottom-end",
+        "left",
+        "left-start",
+        "left-end",
+        "right",
+        "right-start",
+        "right-end"
+      ]).optional().describe(
+        'Preferred placement of the tooltip relative to the anchor element. The SDK flips to the opposite side if there is not enough space. Defaults to "top".'
+      )
+    }).describe(
+      "A tooltip anchored to a DOM element. Use for contextual help, feature discovery, or CTA prompts near specific UI elements."
+    )
+  ).optional().describe(
+    "Tooltips anchored to DOM elements. Use for contextual help, upsell prompts, or feature discovery near specific UI elements."
+  ),
+  /** Badge configurations */
+  badges: z2.array(
+    z2.object({
+      anchorId: AnchorIdZ.describe(
+        "Route and CSS selector of the element to attach the badge to."
+      ),
+      summary: z2.string().describe(
+        "Human-readable description of this badge, used for logging and debugging."
+      ),
+      content: z2.string().describe(
+        'Badge text (e.g. "NEW", "3", "!"). Keep short \u2014 typically 1\u20134 characters.'
+      ),
+      position: z2.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional().describe(
+        'Corner of the anchor element where the badge is positioned. Defaults to "top-right".'
+      )
+    }).describe("A small badge indicator positioned at a corner of a target element.")
+  ).optional().describe(
+    'Badge indicators overlaid on DOM elements. Use for notification counts ("3"), status labels ("NEW"), or attention markers ("!").'
+  ),
+  /** Pulse configurations */
+  pulses: z2.array(
+    z2.object({
+      anchorId: AnchorIdZ.describe("Route and CSS selector of the element to animate."),
+      summary: z2.string().describe(
+        "Human-readable description of this pulse, used for logging and debugging."
+      ),
+      duration: z2.number().optional().describe("Animation duration in milliseconds. Defaults to 2000ms.")
+    }).describe(
+      "A pulsing animation applied to a DOM element to draw subtle attention without blocking interaction."
+    )
+  ).optional().describe(
+    "Pulse animations on DOM elements. Use for subtle attention-grabbing when highlights would be too intrusive."
+  ),
+  /** Modal configurations */
+  modals: z2.array(
+    z2.object({
+      summary: z2.string().describe(
+        "Human-readable description of this modal, used for logging and debugging."
+      ),
+      content: z2.object({
+        title: z2.string().optional().describe("Optional modal heading shown at the top of the dialog."),
+        body: z2.string().describe("Main modal body text (required).")
+      }).describe("Modal content including body text and optional heading."),
+      size: z2.enum(["sm", "md", "lg"]).optional().describe(
+        'Dialog width: "sm" is narrow, "md" is standard, "lg" is wide. Defaults to "md".'
+      ),
+      blocking: z2.boolean().optional().describe(
+        "When true, the modal blocks all page interaction until dismissed. Use sparingly \u2014 only for critical confirmations."
+      ),
+      scrim: z2.object({
+        opacity: z2.number().optional().describe("Backdrop opacity behind the modal (0\u20131). Defaults to 0.6.")
+      }).optional().describe("Scrim (backdrop) configuration for the modal overlay."),
+      dismiss: z2.object({
+        onEsc: z2.boolean().optional().describe("When true (default), pressing Escape closes the modal."),
+        closeButton: z2.boolean().optional().describe("When true (default), an X close button is shown in the modal header."),
+        timeoutMs: z2.number().optional().describe(
+          "Optional auto-close timeout in milliseconds. Omit to require explicit dismissal."
+        )
+      }).optional().describe("Controls how the modal can be dismissed by the user."),
+      ctaButtons: z2.array(
+        z2.object({
+          label: z2.string().describe("Button label text."),
+          actionId: z2.string().describe(
+            'Action identifier published with the action.modal_cta_clicked event. Use "dismiss" to close the modal without publishing an event.'
+          ),
+          primary: z2.boolean().optional().describe(
+            "When true, renders as the primary (filled) button style. Defaults to false."
+          )
         })
-            .optional(),
-    }))
-        .optional(),
-    /** Tooltip configurations */
-    tooltips: z
-        .array(z.object({
-        anchorId: AnchorIdZ,
-        summary: z.string(),
-        content: z.object({
-            title: z.string().optional(),
-            body: z.string(),
-            cta: z
-                .object({
-                label: z.string(),
-                action: z.unknown(), // ActionStep - validated separately
-            })
-                .optional(),
-        }),
-        trigger: z.enum(['immediate', 'hover', 'click']).optional(),
-        placement: z
-            .enum([
-            'top',
-            'top-start',
-            'top-end',
-            'bottom',
-            'bottom-start',
-            'bottom-end',
-            'left',
-            'left-start',
-            'left-end',
-            'right',
-            'right-start',
-            'right-end',
-        ])
-            .optional(),
-    }))
-        .optional(),
-    /** Badge configurations */
-    badges: z
-        .array(z.object({
-        anchorId: AnchorIdZ,
-        summary: z.string(),
-        content: z.string(),
-        position: z.enum(['top-left', 'top-right', 'bottom-left', 'bottom-right']).optional(),
-    }))
-        .optional(),
-    /** Pulse configurations */
-    pulses: z
-        .array(z.object({
-        anchorId: AnchorIdZ,
-        summary: z.string(),
-        duration: z.number().optional(),
-    }))
-        .optional(),
-    /** Modal configurations */
-    modals: z
-        .array(z.object({
-        summary: z.string(),
-        content: z.object({
-            title: z.string().optional(),
-            body: z.string(),
-        }),
-        size: z.enum(['sm', 'md', 'lg']).optional(),
-        blocking: z.boolean().optional(),
-        scrim: z.object({ opacity: z.number().optional() }).optional(),
-        dismiss: z
-            .object({
-            onEsc: z.boolean().optional(),
-            closeButton: z.boolean().optional(),
-            timeoutMs: z.number().optional(),
+      ).optional().describe("Optional CTA buttons shown at the bottom of the modal.")
+    }).describe(
+      "A centered dialog modal. Use for announcements, onboarding prompts, or required confirmations."
+    )
+  ).optional().describe(
+    "Modal dialogs overlaid on the page. Use for announcements, onboarding prompts, or confirmations that require explicit user acknowledgement."
+  ),
+  /** Tour configurations */
+  tours: z2.array(
+    z2.object({
+      tourId: z2.string().describe(
+        "Unique identifier for this tour, used to start/resume it via action or deeplink."
+      ),
+      summary: z2.string().describe("Human-readable description of this tour, used for logging and debugging."),
+      steps: z2.array(
+        z2.object({
+          id: z2.string().describe("Unique step identifier within this tour."),
+          action: z2.record(z2.unknown()).describe(
+            "Action step config to execute for this tour step (e.g. a tooltip or highlight)."
+          ),
+          route: z2.string().optional().describe("Optional route the user must be on before this step executes."),
+          onAction: z2.record(z2.string()).optional().describe(
+            "Map of action event \u2192 next step ID. Defines transitions between steps based on user interaction."
+          )
         })
-            .optional(),
-        ctaButtons: z
-            .array(z.object({
-            label: z.string(),
-            actionId: z.string(),
-            primary: z.boolean().optional(),
-        }))
-            .optional(),
-    }))
-        .optional(),
-    /** Tour configurations */
-    tours: z
-        .array(z.object({
-        tourId: z.string(),
-        summary: z.string(),
-        steps: z.array(z.object({
-            id: z.string(),
-            action: z.record(z.unknown()),
-            route: z.string().optional(),
-            onAction: z.record(z.string()).optional(),
-        })),
-        startStep: z.string().optional(),
-        autoStart: z.boolean().optional(),
-    }))
-        .optional(),
-});
-// ============================================================================
-// Celebrate Action Schema
-// ============================================================================
-const CelebrateActionZ = z
-    .object({
-    kind: z.literal('overlays:celebrate'),
-    effect: z.string(),
-    duration: z.number().optional(),
-    intensity: z.enum(['light', 'medium', 'heavy']).optional(),
-    colors: z.array(z.string()).optional(),
-    props: z.record(z.unknown()).optional(),
-    label: z.string().optional(),
-    triggerWhen: TriggerWhenZ,
-})
-    .strict();
-// ============================================================================
-// Unified Schema Export
-// ============================================================================
-export const actionStepSchemas = [{ defName: 'celebrate', schema: CelebrateActionZ }];
-// ============================================================================
-// Tile Widget Definitions
-// ============================================================================
-/**
- * Tile widget definitions for unified JSON Schema generation.
- * Maps widget IDs to their props validation schema so the build script
- * can inject if/then constraints on tile.props.
- */
-const WorkflowTrackerPropsZ = z.object({}).passthrough();
-export const tileWidgets = [
+      ).min(
+        1,
+        `Tour must have at least one step \u2014 the executor throws Error('Tour "..." has no steps') when steps is empty.`
+      ).describe(
+        "Ordered list of tour steps. Each step executes one action and optionally transitions to the next."
+      ),
+      startStep: z2.string().optional().describe(
+        "ID of the step to begin the tour on. Defaults to the first step in the array."
+      ),
+      autoStart: z2.boolean().optional().describe(
+        "When true, the tour starts automatically when the config loads. Omit to require explicit triggering."
+      )
+    }).describe(
+      "A multi-step product tour. Steps execute sequentially (or via onAction transitions) to guide the user through a feature."
+    )
+  ).optional().describe(
+    "Multi-step product tours. Each tour chains overlay actions (tooltips, highlights) into a guided walkthrough of a feature or workflow."
+  )
+}).describe(
+  "Props for adaptive-overlays visual overlay operations. Each field targets a list of overlay instances by type: highlights (spotlight), tooltips, badges, pulses, modals, and tours."
+);
+var CelebrateActionZ = z2.object({
+  ...AuthoringFieldsZ,
+  kind: z2.literal("overlays:celebrate").describe(
+    "Renders a fullscreen Canvas 2D celebration effect. Use to reward a user achievement (e.g. completing onboarding, first purchase)."
+  ),
+  effect: z2.enum(["confetti", "fireworks", "sparkles", "emoji-rain"]).describe(
+    'Effect preset name: "confetti" (falling pieces), "fireworks" (burst particles), "sparkles" (twinkling diamonds), "emoji-rain" (falling emoji).'
+  ),
+  duration: z2.number().optional().describe("Animation duration in milliseconds. Defaults to 3000ms."),
+  intensity: z2.enum(["light", "medium", "heavy"]).optional().describe('Particle density: "light" is subtle, "heavy" is exuberant. Defaults to "medium".'),
+  colors: z2.array(z2.string()).optional().describe(
+    'Optional color palette as CSS color strings (e.g. ["#ff0000", "#00ff00"]). Defaults to a rainbow palette.'
+  ),
+  props: z2.record(z2.unknown()).optional().describe(
+    'Effect-specific properties. For "emoji-rain", use {"emoji": "\u{1F525}"} to set the falling character.'
+  ),
+  label: z2.string().optional().describe("Optional accessible label for the celebration (used for screen readers)."),
+  triggerWhen: TriggerWhenZ.describe(
+    "Conditional trigger strategy. When null, the celebration fires immediately. Use a rules strategy to fire on a specific behavioral event."
+  )
+}).strict().describe(
+  "Fullscreen celebration effect action. Use to celebrate a user milestone. Pick an effect preset and optionally customize duration, intensity, and colors."
+);
+var actionStepSchemas = [{ defName: "celebrate", schema: CelebrateActionZ }];
+var CAPABILITIES_DOCUMENTATION = {
+  packageId: "adaptive-overlays",
+  description: "Visual overlay capabilities including highlights, tooltips, badges, pulse animations, modals, tours, and celebrations.",
+  whenToUse: [
+    { goal: "Draw attention to an element (spotlight)", action: "overlays:highlight" },
+    { goal: "Show contextual help or guidance near an element", action: "overlays:tooltip" },
+    { goal: 'Add a notification indicator (count, "NEW")', action: "overlays:badge" },
+    { goal: "Subtle attention-grab animation", action: "overlays:pulse" },
+    { goal: "Show a blocking or non-blocking dialog", action: "overlays:modal" },
+    { goal: "Celebrate a user achievement", action: "overlays:celebrate" },
+    { goal: "Multi-step guided walkthrough", action: "overlays:tour" }
+  ],
+  conventions: [
+    {
+      name: 'Tooltip actionId: "dismiss"',
+      description: 'The special actionId "dismiss" closes the tooltip immediately without publishing an event. Use for "close" or "not now" buttons.'
+    },
     {
-        widget: 'adaptive-overlays:workflow-tracker',
-        defName: 'workflowTrackerProps',
-        propsSchema: WorkflowTrackerPropsZ,
+      name: "Companion FAQ tooltips (faq:open:<questionId>)",
+      description: 'A tooltip CTA with actionId "faq:open:<questionId>" publishes action.tooltip_cta_clicked, which the adaptive-faq:accordion widget listens for. The matching FAQ question expands and scrolls into view. If the FAQ widget mounts after the click (e.g. canvas was closed), it checks EventBus history for recent faq:open:* events (within 10 seconds) and auto-expands on mount. The widget also publishes canvas.requestOpen to open the canvas panel if needed.'
     },
+    {
+      name: "Celebrate effect presets",
+      description: 'Available effects: "confetti" (falling rectangular/circular pieces with gravity and rotation), "fireworks" (burst centers with radiating particles and glow), "sparkles" (diamond shapes with sine-wave opacity and upward float), "emoji-rain" (emoji characters falling with horizontal wobble \u2014 set props.emoji to customize the character).'
+    }
+  ],
+  events: [
+    {
+      name: "action.tooltip_cta_clicked",
+      when: "User clicks a tooltip CTA button",
+      props: "{ actionId }"
+    },
+    {
+      name: "action.modal_cta_clicked",
+      when: "User clicks a modal CTA button",
+      props: "{ actionId }"
+    }
+  ]
+};
+var WorkflowTrackerPropsZ = z2.object({}).passthrough();
+var tileWidgets = [
+  {
+    widget: "adaptive-overlays:workflow-tracker",
+    defName: "workflowTrackerProps",
+    propsSchema: WorkflowTrackerPropsZ
+  }
 ];
+export {
+  CAPABILITIES_DOCUMENTATION,
+  actionStepSchemas,
+  configSchema,
+  tileWidgets
+};
+//# sourceMappingURL=schema.js.map