@syntrologie/adapt-nav 2.13.0 → 2.15.0

package/node_modules/@syntrologie/sdk-contracts/dist/schemas.js

@@ -15,76 +15,168 @@ export const AnchorIdZ = z
 })
     .strict();
 // =============================================================================
+// TRIGGER VOCABULARY — canonical lists of valid event names, metric keys, etc.
+// These flow through to the JSON schema as enums and are used by the LLM prompt.
+// =============================================================================
+/** Events that can be counted in event_count conditions. */
+export const 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',
+];
+export const CountableEventZ = z
+    .enum(COUNTABLE_EVENTS)
+    .describe('Event name to count. ui.* = user interactions and behavioral detectors, nav.* = page navigation, behavior.* = derived behavioral signals.');
+/** Valid session metric keys. */
+export const SESSION_METRIC_KEYS = ['time_on_page', 'page_views', 'scroll_depth'];
+export const 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.');
+/** Element chain match field prefixes for counter filters. */
+export const ELEMENT_MATCH_FIELDS = ['tag_name', '$el_text'];
+// Note: attr__* is a dynamic prefix (attr__data-id, attr__class, attr__href, etc.)
+// and cannot be enumerated. The match key is either one of ELEMENT_MATCH_FIELDS
+// or starts with "attr__".
+// =============================================================================
 // CONDITION SCHEMAS
 // =============================================================================
-export const PageUrlConditionZ = z.object({
+export const PageUrlConditionZ = z
+    .object({
     type: z.literal('page_url'),
-    url: z.string(),
-});
-export const RouteConditionZ = z.object({
+    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"}');
+export const RouteConditionZ = z
+    .object({
     type: z.literal('route'),
-    routeId: z.string(),
-});
-export const AnchorVisibleConditionZ = z.object({
+    routeId: z.string().describe('Named route ID from the route filter'),
+})
+    .describe('Fires when the current route matches a named route ID.');
+export const AnchorVisibleConditionZ = z
+    .object({
     type: z.literal('anchor_visible'),
-    anchorId: z.string(),
-    state: z.enum(['visible', 'present', 'absent']),
-});
-export const EventOccurredConditionZ = z.object({
+    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"}');
+export const EventOccurredConditionZ = z
+    .object({
     type: z.literal('event_occurred'),
-    eventName: z.string(),
-    withinMs: z.number().optional(),
-});
-export const StateEqualsConditionZ = z.object({
+    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}');
+export const StateEqualsConditionZ = z
+    .object({
     type: z.literal('state_equals'),
-    key: z.string(),
-    value: z.unknown(),
-});
-export const ViewportConditionZ = z.object({
+    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() — ' +
+    '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.');
+export const ViewportConditionZ = z
+    .object({
     type: z.literal('viewport'),
-    minWidth: z.number().optional(),
-    maxWidth: z.number().optional(),
-    minHeight: z.number().optional(),
-    maxHeight: z.number().optional(),
-});
-export const SessionMetricConditionZ = z.object({
+    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} — fires on tablet and larger.');
+export const SessionMetricConditionZ = z
+    .object({
     type: z.literal('session_metric'),
-    key: z.string(),
+    key: SessionMetricKeyZ,
     operator: z.enum(['gte', 'lte', 'eq', 'gt', 'lt']),
-    threshold: z.number(),
-});
-export const DismissedConditionZ = z.object({
+    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}');
+export const DismissedConditionZ = z
+    .object({
     type: z.literal('dismissed'),
-    key: z.string(),
-    inverted: z.boolean().optional(),
-});
-export const CooldownActiveConditionZ = z.object({
+    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.');
+export const CooldownActiveConditionZ = z
+    .object({
     type: z.literal('cooldown_active'),
-    key: z.string(),
-    inverted: z.boolean().optional(),
-});
-export const FrequencyLimitConditionZ = z.object({
+    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.');
+export const FrequencyLimitConditionZ = z
+    .object({
     type: z.literal('frequency_limit'),
-    key: z.string(),
-    limit: z.number(),
-    inverted: z.boolean().optional(),
-});
-export const MatchOpZ = z.object({
+    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.');
+export const MatchOpZ = z
+    .object({
     equals: z.union([z.string(), z.number(), z.boolean()]).optional(),
     contains: z.string().optional(),
-});
-export const CounterDefZ = z.object({
-    events: z.array(z.string()).min(1),
-    match: z.record(z.string(), MatchOpZ).optional(),
-});
-export const EventCountConditionZ = z.object({
+})
+    .describe('Match operator for counter filters. Exactly one of equals or contains must be specified.');
+export const 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.');
+export const EventCountConditionZ = z
+    .object({
     type: z.literal('event_count'),
-    key: z.string(),
+    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),
-    withinMs: z.number().positive().optional(),
-    counter: CounterDefZ.optional(),
-});
+    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"}}}}');
 export const ConditionZ = z.discriminatedUnion('type', [
     PageUrlConditionZ,
     RouteConditionZ,
@@ -101,36 +193,57 @@ export const ConditionZ = z.discriminatedUnion('type', [
 // =============================================================================
 // STRATEGY SCHEMAS
 // =============================================================================
-export const RuleZ = z.object({
-    conditions: z.array(ConditionZ),
-    value: z.unknown(),
-});
-export const RuleStrategyZ = z.object({
+export const RuleZ = z
+    .object({
+    conditions: z
+        .array(ConditionZ)
+        .describe('Array of conditions — 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 — first rule where all conditions match wins and returns its value.');
+export const RuleStrategyZ = z
+    .object({
     type: z.literal('rules'),
-    rules: z.array(RuleZ),
-    default: z.unknown(),
-});
-export const ScoreStrategyZ = z.object({
+    rules: z
+        .array(RuleZ)
+        .describe('Ordered list of rules. Evaluated top-to-bottom — 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.');
+export const ScoreStrategyZ = z
+    .object({
     type: z.literal('score'),
     field: z.string(),
     threshold: z.number(),
     above: z.unknown(),
     below: z.unknown(),
-});
-export const ModelStrategyZ = z.object({
+})
+    .describe('Score-based strategy. Compares a field value against a threshold.');
+export const 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(),
-});
-export const ExternalStrategyZ = z.object({
+})
+    .describe('ML model strategy. Sends inputs to a model and maps outputs.');
+export const 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.');
 export const DecisionStrategyZ = z.discriminatedUnion('type', [
     RuleStrategyZ,
     ScoreStrategyZ,
@@ -140,6 +253,92 @@ export const DecisionStrategyZ = z.discriminatedUnion('type', [
 /** Canonical Zod schema for the optional triggerWhen field on actions and adaptive items. */
 export const TriggerWhenZ = DecisionStrategyZ.nullable().optional();
 // =============================================================================
+// TRIGGER DOCUMENTATION — examples and match field docs
+// Exported as constants so the schema generator can inject them into the
+// JSON schema. The Python prompt builder reads them from the schema.
+// =============================================================================
+/** Complete triggerWhen examples showing the full rules wrapper structure. */
+export const TRIGGER_EXAMPLES = [
+    {
+        name: 'Click count on a specific element',
+        description: 'Fire when user clicks an element with data-id="hero-cta" 2+ times',
+        triggerWhen: {
+            type: 'rules',
+            rules: [
+                {
+                    conditions: [
+                        {
+                            type: 'event_count',
+                            key: 'cta-clicks',
+                            operator: 'gte',
+                            count: 2,
+                            counter: {
+                                events: ['ui.click'],
+                                match: { 'attr__data-id': { equals: 'hero-cta' } },
+                            },
+                        },
+                    ],
+                    value: true,
+                },
+            ],
+            default: false,
+        },
+    },
+    {
+        name: 'Time on page threshold',
+        description: 'Fire after user spends 30+ seconds on the page',
+        triggerWhen: {
+            type: 'rules',
+            rules: [
+                {
+                    conditions: [
+                        {
+                            type: 'session_metric',
+                            key: 'time_on_page',
+                            operator: 'gte',
+                            threshold: 30,
+                        },
+                    ],
+                    value: true,
+                },
+            ],
+            default: false,
+        },
+    },
+    {
+        name: 'Element visible in viewport',
+        description: 'Fire when a DOM element becomes visible',
+        triggerWhen: {
+            type: 'rules',
+            rules: [
+                {
+                    conditions: [
+                        {
+                            type: 'anchor_visible',
+                            anchorId: '#pricing-section',
+                            state: 'visible',
+                        },
+                    ],
+                    value: true,
+                },
+            ],
+            default: false,
+        },
+    },
+    {
+        name: 'No trigger (fire immediately)',
+        description: 'Action fires as soon as the segment matches — no in-session condition needed',
+        triggerWhen: null,
+    },
+];
+/** Documentation for counter.match field keys. */
+export const MATCH_FIELD_DOCS = {
+    tag_name: 'HTML tag name (e.g. "button", "a", "input")',
+    $el_text: 'Visible text content of the element',
+    'attr__*': 'HTML attribute prefixed with attr__. Example: attr__data-id matches the data-id attribute, ' +
+        'attr__class matches the class attribute, attr__href matches the href attribute.',
+};
+// =============================================================================
 // EVENT SCOPE SCHEMA
 // =============================================================================
 /** Scopes a widget to specific events/URLs. */

package/node_modules/@syntrologie/shared-editor-ui/dist/components/AnchorPicker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnchorPicker.d.ts","sourceRoot":"","sources":["../../src/components/AnchorPicker.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAWH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IACxC,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB;;8DAE0D;IAC1D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAKD,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,iBAAyB,EACzB,eAAuJ,GACxJ,EAAE,iBAAiB,sCAwMnB"}
+{"version":3,"file":"AnchorPicker.d.ts","sourceRoot":"","sources":["../../src/components/AnchorPicker.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAWH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IACxC,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB;;8DAE0D;IAC1D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAKD,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,iBAAyB,EACzB,eAAuJ,GACxJ,EAAE,iBAAiB,sCA2MnB"}

package/node_modules/@syntrologie/shared-editor-ui/dist/components/AnchorPicker.js

@@ -27,11 +27,14 @@ export function AnchorPicker({ isActive, onPick, onCancel, passthroughClicks = f
     const overlayRef = useRef(null);
     const handleMouseMove = useCallback((e) => {
         const overlay = overlayRef.current;
-        if (overlay) {
+        // In passthrough mode the overlay is already pointerEvents:'none',
+        // so elementFromPoint can see through it — no toggle needed.
+        // In non-passthrough mode, temporarily disable to detect elements underneath.
+        if (overlay && !passthroughClicks) {
             overlay.style.pointerEvents = 'none';
         }
         const elementAtPoint = document.elementFromPoint(e.clientX, e.clientY);
-        if (overlay) {
+        if (overlay && !passthroughClicks) {
             overlay.style.pointerEvents = 'auto';
         }
         if (!elementAtPoint) {
@@ -52,7 +55,7 @@ export function AnchorPicker({ isActive, onPick, onCancel, passthroughClicks = f
         setHoveredElement(elementAtPoint);
         const selector = generateSelector(elementAtPoint);
         setHoveredSelector(selector);
-    }, [excludeSelector]);
+    }, [excludeSelector, passthroughClicks]);
     const handleClick = useCallback((e) => {
         if (passthroughClicks)
             return; // Let click propagate to PostHog

package/node_modules/@syntrologie/shared-editor-ui/dist/components/AnchorPickerLit.d.ts

@@ -0,0 +1,84 @@
+/**
+ * AnchorPickerLit — Shared Element Picker Overlay (Lit web component).
+ *
+ * Full-page overlay that lets the user hover and click to select a DOM element.
+ * Returns the element, its CSS selector, and a human-readable description
+ * via custom events.
+ *
+ * The overlay is rendered into a portal div appended to document.body, NOT
+ * into the component's own render root. This is necessary because the editor
+ * panel applies `backdrop-filter: blur(...)` which, in Chrome, creates a new
+ * containing block for `position: fixed` descendants. Without the portal, the
+ * highlight box coordinates (from getBoundingClientRect, which are viewport-
+ * relative) would be interpreted relative to the panel, causing the highlight
+ * to appear far off from the actual hovered element.
+ *
+ * Lit port of AnchorPicker.tsx — preserves all behavior including:
+ * - Mouse tracking with elementFromPoint detection
+ * - Passthrough click mode for PostHog integration
+ * - Element highlight with info tooltip
+ * - Escape key cancellation
+ * - Exclude selector filtering
+ */
+import { LitElement } from 'lit';
+export interface PickedElement {
+    element: Element;
+    selector: string;
+    description: string;
+}
+export declare class AnchorPickerLit extends LitElement {
+    static properties: {
+        isActive: {
+            type: BooleanConstructor;
+            attribute: string;
+        };
+        passthroughClicks: {
+            type: BooleanConstructor;
+            attribute: string;
+        };
+        excludeSelector: {
+            type: StringConstructor;
+            attribute: string;
+        };
+        _hoveredElement: {
+            state: boolean;
+        };
+        _hoveredSelector: {
+            state: boolean;
+        };
+    };
+    isActive: boolean;
+    passthroughClicks: boolean;
+    excludeSelector: string;
+    private _hoveredElement;
+    private _hoveredSelector;
+    private _overlayEl;
+    private _portalDiv;
+    createRenderRoot(): this;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    updated(changed: Map<string, unknown>): void;
+    /**
+     * Create or update the body-level portal div.
+     * Rendering into document.body ensures position:fixed coordinates are
+     * relative to the viewport, not an ancestor with backdrop-filter.
+     */
+    private _syncPortal;
+    private _destroyPortal;
+    private _attachDocumentListeners;
+    private _detachDocumentListeners;
+    /**
+     * Resolve the shadow host this picker lives inside, if any. When the picker
+     * is mounted inside a shadow root (e.g. the editor SDK mounts inside
+     * `<smart-canvas>`'s shadow), `document.elementFromPoint` returns the shadow
+     * *host*, not the host page element beneath. Temporarily disabling pointer
+     * events on the host lets hit-testing fall through to the host page.
+     */
+    private _getShadowHost;
+    private _handleMouseMove;
+    private _handleClick;
+    private _handleKeyDown;
+    render(): symbol;
+    private _overlayTemplate;
+}
+//# sourceMappingURL=AnchorPickerLit.d.ts.map

package/node_modules/@syntrologie/shared-editor-ui/dist/components/AnchorPickerLit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnchorPickerLit.d.ts","sourceRoot":"","sources":["../../src/components/AnchorPickerLit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAQ,UAAU,EAAgC,MAAM,KAAK,CAAC;AAarE,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAiBD,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,OAAgB,UAAU;;;;;;;;;;;;;;;;;;;MAOxB;IAEF,QAAQ,UAAS;IACjB,iBAAiB,UAAS;IAC1B,eAAe,EAAE,MAAM,CAA4B;IAGnD,OAAO,CAAC,eAAe,CAAwB;IAC/C,OAAO,CAAC,gBAAgB,CAAM;IAG9B,OAAO,CAAC,UAAU,CAA+B;IAGjD,OAAO,CAAC,UAAU,CAA+B;IAIxC,gBAAgB;IAIhB,iBAAiB,IAAI,IAAI;IAOzB,oBAAoB,IAAI,IAAI;IAM5B,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAiBrD;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAgBnB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,wBAAwB;IAQhC,OAAO,CAAC,wBAAwB;IAQhC;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,gBAAgB,CA+CtB;IAEF,OAAO,CAAC,YAAY,CAwBlB;IAEF,OAAO,CAAC,cAAc,CAUpB;IAMO,MAAM;IAIf,OAAO,CAAC,gBAAgB;CA0GzB"}