@syntrologie/adapt-faq 2.15.0 → 2.17.0

package/dist/schema.js

@@ -1,215 +1,451 @@
-/**
- * Adaptive FAQ - Config Schema
- *
- * Zod schema for validating FAQ accordion configuration.
- * Demonstrates compositional action pattern with per-item triggerWhen.
- */
-import { AnchorIdZ, DecisionStrategyZ, NotifyZ, TriggerWhenZ } from '@syntrologie/sdk-contracts';
-import { z } from 'zod';
-// ============================================================================
-// Rich Answer Content Schemas
-// ============================================================================
-/** Schema for media assets embedded in enhanced markdown answers. */
-const AssetZ = z.object({
-    id: z.string(),
-    type: z.enum(['image', 'video']),
-    src: z.string(),
-    alt: z.string().optional(),
-    width: z.number().optional(),
-    height: z.number().optional(),
-});
-/** Schema for rich HTML answer content. */
-const RichHTMLAnswerZ = z.object({
-    type: z.literal('rich'),
-    html: z.string(),
-});
-/** Schema for enhanced markdown answer content with optional assets. */
-const EnhancedMarkdownAnswerZ = z.object({
-    type: z.literal('markdown'),
-    content: z.string(),
-    assets: z.array(AssetZ).optional(),
-});
-/** Union of all FAQ answer types: plain string, rich HTML, or enhanced markdown. */
-const FAQAnswerZ = z.union([z.string(), RichHTMLAnswerZ, EnhancedMarkdownAnswerZ]);
-// ============================================================================
-// Feedback Schemas
-// ============================================================================
-/** Schema for feedback widget configuration. */
-const FeedbackConfigZ = z.object({
-    style: z.enum(['thumbs', 'rating']),
-    prompt: z.string().optional(),
-});
-/** Feedback can be a boolean (enable/disable) or a detailed config object. */
-const FeedbackZ = z.union([z.boolean(), FeedbackConfigZ]);
-// ============================================================================
-// Ordering Schemas
-// ============================================================================
-/** Schema for segment-based ordering strategy. */
-const SegmentOrderingZ = z.object({
-    type: z.literal('segment'),
-    segmentWeights: z.record(z.array(z.string())),
-});
-/** Ordering strategy: static order, priority-based, or segment-based. */
-const OrderingStrategyZ = z.union([z.enum(['static', 'priority']), SegmentOrderingZ]);
-// ============================================================================
-// AI Answer Strategy Schema
-// ============================================================================
-/** Schema for AI-generated answer configuration. */
-const AnswerStrategyZ = z.object({
-    endpoint: z.string().min(1),
-    context: z.array(z.string()).optional(),
-    cache: z.enum(['session', 'none']).optional(),
-    fallback: z.string().optional(),
-});
-// ============================================================================
-// Injection Rule Schema
-// ============================================================================
-/** Schema for dynamic FAQ injection rules. */
-const InjectionRuleZ = z.object({
-    trigger: DecisionStrategyZ,
-    items: z.array(z.lazy(() => FAQQuestionSchema)),
-    position: z.enum(['prepend', 'append']).optional(),
-    once: z.boolean().optional(),
-});
-// ============================================================================
-// FAQ Question Schema
-// ============================================================================
-/**
- * Schema for a single FAQ question (compositional action).
- */
-export const FAQQuestionSchema = z
-    .object({
-    kind: z.literal('faq:question'),
-    config: z.object({
-        /** Unique identifier for this question */
-        id: z.string().min(1, 'ID is required'),
-        /** The question text */
-        question: z.string().min(1, 'Question is required'),
-        /** The answer content (plain string, rich HTML, or enhanced markdown) */
-        answer: FAQAnswerZ,
-        /** Optional category for grouping */
-        category: z.string().optional(),
-        /** Optional priority for ordering */
-        priority: z.number().optional(),
-        /** Optional AI answer generation strategy */
-        answerStrategy: AnswerStrategyZ.optional(),
-    }),
-    /** Per-item activation strategy (null = always show) */
-    triggerWhen: TriggerWhenZ,
-    /** Toast config when triggerWhen transitions false → true. Required when triggerWhen is set (use null to opt out). */
-    notify: NotifyZ,
-})
-    .refine((data) => !data.triggerWhen || data.notify !== undefined, {
-    message: 'notify is required when triggerWhen is present (use null to opt out of notifications)',
+// ../../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()
 });
-// ============================================================================
-// FAQ Config Schema
-// ============================================================================
-/**
- * Full configuration schema for adaptive-faq.
- */
-export const configSchema = z.object({
-    /** Display title for the FAQ widget */
-    title: z.string().optional(),
-    /** Whether only one or multiple questions can be expanded at once */
-    expandBehavior: z.enum(['single', 'multiple']).default('single'),
-    /** Whether to show a search/filter input */
-    searchable: z.boolean().default(false),
-    /** Color theme */
-    theme: z.enum(['light', 'dark', 'auto']).default('auto'),
-    /** FAQ questions (compositional actions) */
-    actions: z.array(FAQQuestionSchema).default([]),
-    /** Feedback widget configuration */
-    feedback: FeedbackZ.optional(),
-    /** Question ordering strategy */
-    ordering: OrderingStrategyZ.optional(),
-    /** Dynamic FAQ injection rules */
-    injections: z.array(InjectionRuleZ).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 AssetZ = z2.object({
+  id: z2.string().describe("Unique asset ID referenced inside the markdown content via `asset:<id>`."),
+  type: z2.enum(["image", "video"]).describe('"image" for static images, "video" for embeddable video clips.'),
+  src: z2.string().describe("Absolute URL of the media asset."),
+  alt: z2.string().optional().describe("Optional alt text for images (accessibility)."),
+  width: z2.number().optional().describe("Optional display width in pixels."),
+  height: z2.number().optional().describe("Optional display height in pixels.")
+}).describe(
+  "A single embedded media asset (image or video) referenced by ID in the markdown content."
+);
+var RichHTMLAnswerZ = z2.object({
+  type: z2.literal("rich").describe("Use this variant when the answer is pre-rendered HTML."),
+  html: z2.string().describe("Sanitized HTML string rendered directly as the answer body.")
+}).describe("Rich HTML answer: use when the answer content is pre-rendered HTML markup.");
+var EnhancedMarkdownAnswerZ = z2.object({
+  type: z2.literal("markdown").describe(
+    "Use this variant for markdown with embedded images or video via the assets array."
+  ),
+  content: z2.string().describe(
+    "Markdown string. Reference assets using the `asset:<id>` URI scheme, e.g. `![alt](asset:my-img)`."
+  ),
+  assets: z2.array(AssetZ).optional().describe("Optional media assets referenced in the markdown via `asset:<id>` URIs.")
+}).describe(
+  "Enhanced markdown answer: use when the answer mixes formatted text with images or video assets."
+);
+var FAQAnswerZ = z2.union([z2.string(), RichHTMLAnswerZ, EnhancedMarkdownAnswerZ]).describe(
+  'Answer content. Use a plain string for simple text, "rich" for pre-rendered HTML, or "markdown" for formatted text with embedded assets.'
+);
+var FeedbackConfigZ = z2.object({
+  style: z2.enum(["thumbs", "rating"]).describe('"thumbs" shows a thumbs-up/down pair; "rating" shows a numeric scale.'),
+  prompt: z2.string().optional().describe(
+    'Optional prompt text shown above the feedback controls (e.g. "Was this helpful?").'
+  )
+}).describe("Detailed feedback widget configuration specifying style and optional prompt text.");
+var FeedbackZ = z2.union([z2.boolean(), FeedbackConfigZ]).describe(
+  "Per-item feedback widget. Pass true for default thumbs feedback, false to disable, or a FeedbackConfig object for custom style and prompt."
+);
+var SegmentOrderingZ = z2.object({
+  type: z2.literal("segment").describe("Segment-based ordering: item order varies per user segment."),
+  segmentWeights: z2.record(z2.array(z2.string())).describe(
+    "Map of segment ID \u2192 ordered list of question IDs. Each segment gets its own item order."
+  )
+}).describe(
+  "Segment-based ordering strategy. Each key is a segment ID and the value is the ordered list of item IDs shown to users in that segment."
+);
+var OrderingStrategyZ = z2.union([z2.enum(["static", "priority"]), SegmentOrderingZ]).describe(
+  '"static" = config order, "priority" = sort by item priority field descending, or a segment object for per-segment ordering.'
+);
+var AnswerStrategyZ = z2.object({
+  endpoint: z2.string().min(1).describe("Backend endpoint URL that generates the AI answer for this question."),
+  context: z2.array(z2.string()).optional().describe("Optional list of context keys passed to the endpoint to ground the answer."),
+  cache: z2.enum(["session", "none"]).optional().describe(
+    `"session" caches the generated answer for the user's session; "none" regenerates on each expand.`
+  ),
+  fallback: z2.string().optional().describe("Static fallback answer text shown if the AI endpoint fails or times out.")
+}).describe(
+  "AI answer generation strategy. When present, the answer is generated dynamically by calling the specified endpoint."
+);
+var InjectionRuleZ = z2.object({
+  trigger: DecisionStrategyZ.describe(
+    "Decision strategy that evaluates to true when the items should be injected (e.g. page URL matches checkout)."
+  ),
+  items: z2.array(z2.lazy(() => FAQQuestionSchema)).describe("FAQ question items to inject when the trigger fires."),
+  position: z2.enum(["prepend", "append"]).optional().describe('"prepend" inserts injected items at the top; "append" adds them at the bottom.'),
+  once: z2.boolean().optional().describe("When true, items are injected only on the first trigger match and not again.")
+}).describe(
+  "Dynamic injection rule: adds contextual FAQ items when a trigger condition is met (e.g. user is on the checkout page)."
+);
+var FAQQuestionSchema = z2.object({
+  ...AuthoringFieldsZ,
+  kind: z2.literal("faq:question").describe(
+    "Compositional action type for a single FAQ accordion item. Rendered by the adaptive-faq:accordion widget."
+  ),
+  config: z2.object({
+    /** Unique identifier for this question */
+    id: z2.string().min(1, "ID is required"),
+    /** The question text */
+    question: z2.string().min(1, "Question is required").describe("The question text shown in the accordion header."),
+    /** The answer content (plain string, rich HTML, or enhanced markdown) */
+    answer: FAQAnswerZ,
+    /** Optional category for grouping */
+    category: z2.string().optional().describe(
+      "Optional grouping label. Questions with the same category are collapsible under a shared section header."
+    ),
+    /** Optional priority for ordering */
+    priority: z2.number().optional().describe(
+      'Numeric priority used when ordering="priority". Higher values appear first. Omit for equal priority.'
+    ),
+    /** Optional AI answer generation strategy */
+    answerStrategy: AnswerStrategyZ.optional().describe(
+      "Optional AI answer generation config. When set, the answer field is used as a fallback only."
+    )
+  }).describe(
+    "Per-question configuration including the question text, answer content, and optional metadata."
+  ),
+  /** Per-item activation strategy (null = always show) */
+  triggerWhen: TriggerWhenZ.describe(
+    "Conditional visibility strategy. When null or omitted, the question is always shown. Use a rules strategy to show/hide based on page URL, event counts, or session metrics."
+  ),
+  /** Toast config when triggerWhen transitions false → true. Required when triggerWhen is set (use null to opt out). */
+  notify: NotifyZ.describe(
+    "Toast notification shown when triggerWhen transitions false \u2192 true. Required when triggerWhen is set \u2014 pass null to opt out of the toast."
+  )
+}).refine((data) => !data.triggerWhen || data.notify !== void 0, {
+  message: "notify is required when triggerWhen is present (use null to opt out of notifications)"
 });
-// ============================================================================
-// Executor Action Schemas
-// ============================================================================
-/**
- * Schema for scrolling to a specific FAQ item.
- * Requires either itemId or itemQuestion to identify the target.
- */
-export const ScrollToFaqSchema = z
-    .object({
-    kind: z.literal('faq:scroll_to'),
-    itemId: z.string().optional(),
-    itemQuestion: z.string().optional(),
-    expand: z.boolean().optional(),
-    behavior: z.enum(['smooth', 'instant', 'auto']).optional(),
-})
-    .refine((data) => data.itemId || data.itemQuestion, {
-    message: 'Either itemId or itemQuestion is required',
+var configSchema = z2.object({
+  /** Display title for the FAQ widget */
+  title: z2.string().optional().describe("Optional header text shown above the accordion list."),
+  /** Whether only one or multiple questions can be expanded at once */
+  expandBehavior: z2.enum(["single", "multiple"]).default("single").describe(
+    '"single" collapses any open item before expanding another; "multiple" allows any number open at once.'
+  ),
+  /** Whether to show a search/filter input */
+  searchable: z2.boolean().default(false).describe("When true, renders a text input that filters questions by keyword."),
+  /** Color theme */
+  theme: z2.enum(["light", "dark", "auto"]).default("auto").describe(
+    `"auto" follows the user's OS preference; use "light" or "dark" to pin the theme.`
+  ),
+  /** FAQ questions (compositional actions) */
+  actions: z2.array(FAQQuestionSchema).default([]).describe(
+    "The FAQ items rendered by the accordion. Each item is a faq:question compositional action \u2014 these are configuration data rendered by the widget, not actions executed by the runtime. This compositional pattern enables per-item conditional visibility via triggerWhen, category grouping, and dynamic injection."
+  ),
+  /** Feedback widget configuration */
+  feedback: FeedbackZ.optional().describe(
+    "Optional per-item feedback widget. Enable with true (default thumbs style) or a FeedbackConfig for custom style."
+  ),
+  /** Question ordering strategy */
+  ordering: OrderingStrategyZ.optional().describe(
+    'Controls the display order of items. Omit for static (config) order, "priority" to sort by priority field, or a segment object for per-segment ordering.'
+  ),
+  /** Dynamic FAQ injection rules */
+  injections: z2.array(InjectionRuleZ).optional().describe(
+    "Optional injection rules that dynamically add FAQ items when trigger conditions are met (e.g. inject checkout FAQs on the checkout page)."
+  )
+}).describe(
+  "Props for the adaptive-faq:accordion tile widget. Configures the FAQ accordion including items, expand behavior, search, feedback, and ordering."
+);
+var ScrollToFaqSchema = z2.object({
+  ...AuthoringFieldsZ,
+  kind: z2.literal("faq:scroll_to").describe("Scrolls the viewport to a specific FAQ item and optionally expands it."),
+  itemId: z2.string().optional().describe("Target question ID. Use this or itemQuestion (at least one required)."),
+  itemQuestion: z2.string().optional().describe(
+    "Target question text for fuzzy matching. Use this or itemId (at least one required)."
+  ),
+  expand: z2.boolean().optional().describe("When true (default), expands the item after scrolling into view."),
+  behavior: z2.enum(["smooth", "instant", "auto"]).optional().describe('"smooth" animates the scroll; "instant" jumps; "auto" defers to browser default.')
+}).refine((data) => data.itemId || data.itemQuestion, {
+  message: "Either itemId or itemQuestion is required"
 });
-/**
- * Schema for toggling a FAQ item open/closed.
- * Requires either itemId or itemQuestion to identify the target.
- */
-export const ToggleFaqItemSchema = z
-    .object({
-    kind: z.literal('faq:toggle_item'),
-    itemId: z.string().optional(),
-    itemQuestion: z.string().optional(),
-    state: z.enum(['open', 'closed', 'toggle']).default('toggle'),
-})
-    .refine((data) => data.itemId || data.itemQuestion, {
-    message: 'Either itemId or itemQuestion is required',
+var ToggleFaqItemSchema = z2.object({
+  ...AuthoringFieldsZ,
+  kind: z2.literal("faq:toggle_item").describe("Opens, closes, or toggles the expanded state of a specific FAQ item."),
+  itemId: z2.string().optional().describe("Target question ID. Use this or itemQuestion (at least one required)."),
+  itemQuestion: z2.string().optional().describe(
+    "Target question text for fuzzy matching. Use this or itemId (at least one required)."
+  ),
+  state: z2.enum(["open", "closed", "toggle"]).default("toggle").describe('"open" expands, "closed" collapses, "toggle" flips the current state.')
+}).refine((data) => data.itemId || data.itemQuestion, {
+  message: "Either itemId or itemQuestion is required"
 });
-/**
- * Schema for updating FAQ items (add, remove, reorder, replace).
- */
-export const UpdateFaqSchema = z.object({
-    kind: z.literal('faq:update'),
-    operation: z.enum(['add', 'remove', 'reorder', 'replace']),
-    items: z.array(FAQQuestionSchema).optional(),
-    itemId: z.string().optional(),
-    order: z.array(z.string()).optional(),
-    position: z.enum(['prepend', 'append', 'before', 'after']).optional(),
-    anchorId: AnchorIdZ.optional(),
+var UpdateFaqSchema = z2.object({
+  ...AuthoringFieldsZ,
+  kind: z2.literal("faq:update").describe("Dynamically adds, removes, reorders, or replaces FAQ items at runtime."),
+  operation: z2.enum(["add", "remove", "reorder", "replace"]).describe(
+    '"add" inserts items, "remove" deletes one by ID, "reorder" applies a new ID order, "replace" swaps all items.'
+  ),
+  items: z2.array(FAQQuestionSchema).optional().describe(
+    'Items to act on. Required for "add" (the items to insert) and "replace" (the full replacement set; pass [] to intentionally clear all items).'
+  ),
+  itemId: z2.string().optional().describe('ID of the item to remove. Required for "remove".'),
+  order: z2.array(z2.string()).optional().describe(
+    'New display order as an ordered list of item IDs. Required for "reorder". To intentionally clear the list, use operation "replace" with items: [].'
+  ),
+  position: z2.enum(["prepend", "append", "before", "after"]).optional().describe("Where to insert new items relative to existing ones or relative to anchorId."),
+  anchorId: AnchorIdZ.optional().describe(
+    'Reference item for "before" or "after" positioning. Identifies an existing FAQ item as the insertion anchor.'
+  )
+}).describe(
+  "Runtime mutation action for the FAQ item list. Use to add contextual questions, remove outdated ones, or reorder by priority."
+).superRefine((data, ctx) => {
+  switch (data.operation) {
+    case "add":
+      if (data.items === void 0) {
+        ctx.addIssue({
+          code: z2.ZodIssueCode.custom,
+          path: ["items"],
+          message: 'items is required when operation is "add"'
+        });
+      }
+      break;
+    case "remove":
+      if (data.itemId === void 0) {
+        ctx.addIssue({
+          code: z2.ZodIssueCode.custom,
+          path: ["itemId"],
+          message: 'itemId is required when operation is "remove"'
+        });
+      }
+      break;
+    case "reorder":
+      if (data.order === void 0) {
+        ctx.addIssue({
+          code: z2.ZodIssueCode.custom,
+          path: ["order"],
+          message: 'order is required when operation is "reorder" (use operation "replace" with items: [] to intentionally clear the list)'
+        });
+      }
+      break;
+    case "replace":
+      if (data.items === void 0) {
+        ctx.addIssue({
+          code: z2.ZodIssueCode.custom,
+          path: ["items"],
+          message: 'items is required when operation is "replace" (pass [] to clear the list)'
+        });
+      }
+      break;
+  }
 });
-// ============================================================================
-// Validation Helpers
-// ============================================================================
-/**
- * Validate a FAQ question action.
- */
-export function validateFAQQuestion(data) {
-    return FAQQuestionSchema.safeParse(data);
+function validateFAQQuestion(data) {
+  return FAQQuestionSchema.safeParse(data);
 }
-/**
- * Validate the full FAQ config.
- */
-export function validateFAQConfig(data) {
-    return configSchema.safeParse(data);
+function validateFAQConfig(data) {
+  return configSchema.safeParse(data);
 }
-// ============================================================================
-// Unified Schema Export
-// ============================================================================
-/**
- * Action step schemas for unified JSON Schema generation.
- * The build script reads this array to merge adaptive actions into the
- * unified canvas-config.schema.json.
- *
- * Note: `.innerType()` strips the `.refine()` wrapper since JSON Schema
- * cannot express cross-field refinements; runtime Zod handles that.
- */
-export const actionStepSchemas = [
-    { defName: 'faqQuestion', schema: FAQQuestionSchema.innerType() },
-    { defName: 'faqScrollTo', schema: ScrollToFaqSchema.innerType() },
-    { defName: 'faqToggleItem', schema: ToggleFaqItemSchema.innerType() },
-    { defName: 'faqUpdate', schema: UpdateFaqSchema },
+var actionStepSchemas = [
+  { defName: "faqQuestion", schema: FAQQuestionSchema.innerType() },
+  { defName: "faqScrollTo", schema: ScrollToFaqSchema.innerType() },
+  { defName: "faqToggleItem", schema: ToggleFaqItemSchema.innerType() },
+  { defName: "faqUpdate", schema: UpdateFaqSchema.innerType() }
 ];
-// ============================================================================
-// Tile Widget Props Export
-// ============================================================================
-/**
- * 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.
- */
-export const tileWidgets = [
-    { widget: 'adaptive-faq:accordion', defName: 'faqAccordionProps', propsSchema: configSchema },
+var tileWidgets = [
+  { widget: "adaptive-faq:accordion", defName: "faqAccordionProps", propsSchema: configSchema }
 ];
+var CAPABILITIES_DOCUMENTATION = {
+  packageId: "adaptive-faq",
+  description: "Collapsible Q&A accordion with actions, rich content, feedback, and personalization.",
+  whenToUse: [
+    {
+      goal: "Add an FAQ accordion widget",
+      action: 'Add a tile with widget: "adaptive-faq:accordion"'
+    },
+    { goal: "Scroll to and expand a specific FAQ item", action: "faq:scroll_to" },
+    { goal: "Open, close, or toggle a FAQ item", action: "faq:toggle_item" },
+    { goal: "Add, remove, reorder, or replace FAQ items", action: "faq:update" }
+  ],
+  conventions: [
+    {
+      name: "Compositional action pattern",
+      description: "faq:question actions are configuration data rendered by the accordion widget, not actions executed by the runtime. This allows per-item conditional visibility via triggerWhen, category grouping under collapsible section headers, and dynamic injection of contextual items."
+    },
+    {
+      name: "Rich answer content formats",
+      description: 'FAQ answers support three formats: plain string (simple text with basic markdown), rich HTML ({ "type": "rich", "html": "<p>...</p>" } for pre-rendered content), or enhanced markdown ({ "type": "markdown", "content": "...", "assets": [...] } with embedded media via asset:<id> URIs).'
+    },
+    {
+      name: "Companion overlay tooltips",
+      description: 'FAQ questions can be surfaced proactively using overlays:tooltip with ctaButtons. Set the CTA actionId to "faq:open:<questionId>" \u2014 the FAQ widget listens for action.tooltip_cta_clicked events with this pattern and expands the matching question. Late-mount support: if the widget mounts after the click, it checks EventBus history (within 10 seconds) and auto-expands.'
+    },
+    {
+      name: "Feedback events",
+      description: "When feedback is enabled, user feedback events are published via context.publishEvent for analytics integration."
+    }
+  ],
+  events: [
+    {
+      name: "faq:feedback_submitted",
+      when: "User submits feedback on a FAQ answer",
+      props: "{ questionId, style, value }"
+    }
+  ]
+};
+export {
+  CAPABILITIES_DOCUMENTATION,
+  FAQQuestionSchema,
+  ScrollToFaqSchema,
+  ToggleFaqItemSchema,
+  UpdateFaqSchema,
+  actionStepSchemas,
+  configSchema,
+  tileWidgets,
+  validateFAQConfig,
+  validateFAQQuestion
+};
+//# sourceMappingURL=schema.js.map