npm - @cognior/iap-sdk - Versions diffs - 0.0.2 - Mend

@cognior/iap-sdk 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,1117 @@
+# Digital Adoption Platform (DAP) SDK
+A framework-agnostic JavaScript/TypeScript SDK for creating interactive user flows, onboarding experiences, tooltips, surveys, and walkthroughs in web applications.
+## Overview
+The DAP SDK enables developers to create guided user experiences driven by backend-defined Flow JSON configurations. It provides a comprehensive suite of UI components and interaction patterns that help users navigate and learn your application.
+**Architecture**: Backend Flow Engine → DAP SDK → Interactive UI Components
+### Typical Use Cases
+- **User Onboarding**: Step-by-step guided tours for new users
+- **Feature Discovery**: Interactive tooltips and hotspots highlighting new features
+- **Contextual Help**: Smart assistance based on user location and behavior
+- **Surveys & Feedback**: In-app surveys and micro-surveys for user insights
+- **Task Guidance**: Walkthrough workflows and complex processes
+- **Knowledge Base**: Embedded help content and documentation
+## Features
+### Core Capabilities
+- ✅ **Step-based Flow System**: Linear and AnyOrder execution models
+- ✅ **Mandatory vs Optional Steps**: Flexible flow completion requirements
+- ✅ **Advanced Trigger System**: DOM, Input, Lifecycle, and Time-based triggers
+- ✅ **Rule-based Branching**: Dynamic flow paths based on user input
+- ✅ **Multi-page Support**: Seamless flows across SPAs and traditional pages
+- ✅ **Real-time Analytics**: Comprehensive telemetry and user behavior tracking
+- ✅ **One-time vs Recurring**: Configurable flow frequency and targeting
+### UI Components
+- **Modals**: Rich content modals with dragging, resizing, and accessibility
+- **Tooltips**: Contextual help tooltips with smart positioning
+- **Popovers**: Interactive popovers with custom content
+- **Banners**: Page-level announcements and notifications
+- **Hotspots**: Visual indicators for interactive elements
+- **Surveys**: Inline and modal survey components
+- **Walkthroughs**: Multi-step guided tours
+- **Task Lists**: Interactive checklists and progress tracking
+## Browser & Platform Support
+- **Modern Browsers**: Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
+- **SPA Compatibility**: React, Angular, Vue, Svelte, and vanilla JavaScript
+- **MPA Support**: Traditional multi-page applications
+- **Mobile**: Responsive design with touch support
+- **Accessibility**: WCAG 2.1 AA compliant components
+## Installation
+### Option A: NPM Package (Recommended for Modern Development)
+```bash
+# Install via npm
+npm install @cognior/dap-sdk
+# Or install via yarn
+yarn add @cognior/dap-sdk
+```
+**ES Modules (Webpack, Vite, Rollup)**
+```javascript
+import { init, setUser } from '@cognior/dap-sdk';
+await init({
+  configUrl: 'https://api.yourcompany.com/config'
+});
+setUser({
+  id: 'user_123',
+  role: 'admin',
+  email: 'admin@company.com'
+});
+```
+**CommonJS (Node.js, Legacy Bundlers)**
+```javascript
+const { init, setUser } = require('@cognior/dap-sdk');
+init({
+  configUrl: 'https://api.yourcompany.com/config'
+}).then(() => {
+  setUser({
+    id: 'user_123',
+    role: 'admin'
+  });
+});
+```
+### Option B: Script Tag (Quick Setup/Testing)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <!-- Load DAP SDK -->
+  <script src="https://cdn.your-domain.com/dap-sdk/latest/dap.min.js"></script>
+</head>
+<body>
+  <script>
+    // Initialize after page load
+    window.addEventListener('DOMContentLoaded', async () => {
+      await window.DAP.init({
+        configUrl: 'https://api.your-domain.com/config',
+        debug: false
+      });
+      // Set user context for personalized experiences
+      window.DAP.setUser({
+        id: 'user_123',
+        role: 'user',
+        email: 'user@company.com'
+      });
+    });
+  </script>
+</body>
+</html>
+```
+### Option C: Direct Download
+Download the latest build files from the [releases page](https://github.com/CogniorAI/WebUserModule/releases) and include in your project:
+- `index.umd.js` - For script tag usage (global `DAP` variable)
+- `index.esm.js` - For ES module imports
+- `index.cjs.js` - For CommonJS require()
+- `index.d.ts` - TypeScript definitions
+## SDK Initialization
+### Required Configuration
+| Option | Description | Example |
+|--------|-------------|---------|
+| `configUrl` | URL to fetch DAP configuration | `"https://api.dap.com/config"` |
+### Optional Configuration
+| Option | Description | Default |
+|--------|-------------|---------|
+| `debug` | Enable verbose console logging | `false` |
+| `screenId` | Custom screen identifier | Current pathname |
+| `user` | Initial user context for personalized flows | `undefined` |
+### Example Initialization
+```javascript
+// Basic initialization
+await DAP.init({
+  configUrl: 'https://api.yourcompany.com/config',
+  debug: false
+});
+// With user context and debug mode
+await DAP.init({
+  configUrl: 'https://api.yourcompany.com/config',
+  debug: true,
+  screenId: 'dashboard',
+  user: {
+    id: 'user_123',
+    role: 'admin',
+    email: 'admin@company.com',
+    attributes: {
+      department: 'engineering',
+      subscription: 'enterprise'
+    }
+  }
+});
+```
+### Configuration File Format
+The `configUrl` should return a JSON configuration with the following structure:
+```json
+{
+  "organizationid": "your-org-id",
+  "siteid": "your-site-id",
+  "apikey": "your-api-key",
+  "apiurl": "https://api.yourcompany.com",
+  "enableDraggableModals": true
+}
+## User Context Management
+### Setting User Information
+The SDK supports comprehensive user context management for personalized experiences and analytics. User information should be provided after initialization or when user state changes.
+#### User Data Structure
+```typescript
+interface DapUser {
+  id: string;                          // Required: Unique user identifier
+  role?: string;                       // Optional: User role (admin, user, guest)
+  email?: string;                      // Optional: User email address
+  attributes?: Record<string, string>; // Optional: Custom user attributes
+}
+```
+#### Setting User Context
+```javascript
+// Set complete user context
+DAP.setUser({
+  id: 'user_12345',
+  role: 'premium',
+  email: 'user@company.com',
+  attributes: {
+    department: 'engineering',
+    experience_level: 'advanced',
+    subscription: 'pro',
+    signup_date: '2024-01-15'
+  }
+});
+// Update existing user context (merges with existing data)
+DAP.updateUser({
+  role: 'admin',
+  attributes: {
+    last_login: '2024-01-22'
+  }
+});
+// Get current user context
+const user = DAP.getUser();
+console.log('Current user:', user);
+// Clear user context (for logout)
+DAP.clearUser();
+```
+#### Integration Examples
+**React Integration**
+```javascript
+// In your authentication component
+useEffect(() => {
+  if (authUser) {
+    DAP.setUser({
+      id: authUser.id,
+      role: authUser.role,
+      email: authUser.email,
+      attributes: {
+        subscription_tier: authUser.subscription,
+        signup_date: authUser.createdAt,
+        last_active: new Date().toISOString()
+      }
+    });
+  } else {
+    DAP.clearUser();
+  }
+}, [authUser]);
+```
+**Angular Integration**
+```typescript
+// In your auth service
+@Injectable()
+export class AuthService {
+  private updateDapUser(user: User) {
+    DAP.setUser({
+      id: user.id,
+      role: user.role,
+      email: user.email,
+      attributes: {
+        department: user.department,
+        experience_level: user.experience,
+        feature_flags: user.featureFlags?.join(',') || ''
+      }
+    });
+  }
+}
+```
+**Login/Logout Workflow**
+```javascript
+// On successful login
+async function handleLogin(credentials) {
+  const user = await authenticate(credentials);
+  // Set user context for DAP
+  DAP.setUser({
+    id: user.id,
+    role: user.role,
+    email: user.email,
+    attributes: {
+      login_method: 'email',
+      user_segment: user.segment,
+      onboarding_completed: user.onboardingCompleted.toString()
+    }
+  });
+  // Flows will now be evaluated with user context
+}
+// On logout
+function handleLogout() {
+  DAP.clearUser();
+  // User-specific flows will stop, anonymous flows may continue
+}
+```
+### User Context Benefits
+#### Personalized Experiences
+```javascript
+// Flows can target specific user roles
+{
+  "targeting": {
+    "userAttributes": {
+      "role": "admin",
+      "experience_level": "beginner"
+    }
+  }
+}
+// Dynamic content based on user data
+{
+  "modalContent": {
+    "title": "Welcome {{user.attributes.department}} Team!"
+  }
+}
+```
+#### Analytics & Insights
+- **User Journey Tracking**: Complete user flow analytics
+- **Segmentation**: Analyze behavior by role, department, subscription tier
+- **Personalization**: Adapt experiences based on user attributes
+- **A/B Testing**: Target specific user segments for experiments
+#### Privacy & Security
+- **Data Minimization**: Only required data is stored
+- **Session Storage**: User context persists only during browser session
+- **Anonymous Fallback**: SDK works without user context using anonymous IDs
+- **Secure Handling**: No sensitive data logged or exposed
+### Best Practices
+#### Required vs Optional Data
+```javascript
+// ✅ Minimal required data
+DAP.setUser({
+  id: 'user_123'  // Only ID is required
+});
+// ✅ Rich context for better targeting
+DAP.setUser({
+  id: 'user_123',
+  role: 'admin',
+  attributes: {
+    subscription: 'enterprise',
+    onboarding_step: '3'
+  }
+});
+```
+#### Attribute Naming Conventions
+```javascript
+// ✅ Use consistent, descriptive attribute names
+attributes: {
+  'subscription_tier': 'pro',
+  'signup_date': '2024-01-15',
+  'feature_access': 'advanced',
+  'user_segment': 'power_user'
+}
+// ❌ Avoid unclear or inconsistent naming
+attributes: {
+  'sub': 'pro',           // Too abbreviated
+  'dt': '2024-01-15',     // Unclear meaning
+  'hasAccess': 'true'     // Inconsistent format
+}
+```
+#### Timing Considerations
+```javascript
+// ✅ Set user context early in app lifecycle
+async function initializeApp() {
+  // Initialize DAP with user context
+  await DAP.init({
+    configUrl: 'https://api.yourcompany.com/config',
+    user: currentUser,
+    debug: process.env.NODE_ENV === 'development'
+  });
+  // Flows will evaluate with proper context immediately
+}
+// ✅ Update context on relevant changes
+function handleSubscriptionUpgrade(newTier) {
+  DAP.updateUser({
+    attributes: {
+      subscription_tier: newTier,
+      upgrade_date: new Date().toISOString()
+    }
+  });
+}
+```
+#### Error Handling
+```javascript
+try {
+  DAP.setUser({
+    id: user.id,
+    role: user.role,
+    email: user.email,
+    attributes: userAttributes
+  });
+} catch (error) {
+  console.warn('Failed to set DAP user context:', error);
+  // Application continues to work, flows may use anonymous context
+}
+```
+## Embedding the SDK
+### Single Page Applications (SPA)
+For SPAs, initialize the SDK once and it will automatically track page changes:
+```javascript
+// Initialize once on app startup
+await DAP.init({
+  configUrl: 'https://api.yourcompany.com/config',
+  debug: false,
+  user: currentUser // Optional: set initial user context
+});
+// The SDK automatically detects route changes via:
+// - History API changes (pushState/replaceState)
+// - PopState events (back/forward buttons)
+// - Hash changes
+// No manual refresh needed for most frameworks
+```
+### Multi-Page Applications (MPA)
+Initialize on each page load:
+```javascript
+// Add to your main JavaScript file
+window.addEventListener('DOMContentLoaded', async () => {
+  await DAP.init({
+    configUrl: 'https://api.yourcompany.com/config'
+  });
+  // Flows automatically start based on page context
+});
+```
+### Page Change Detection
+The SDK automatically detects:
+- Browser navigation (back/forward buttons)
+- History API changes (`pushState`/`replaceState`)
+- Hash changes
+- Manual page transitions
+### Selector Best Practices
+Use stable, semantic selectors for reliable step targeting:
+```html
+<!-- ✅ Good: Stable, semantic selectors -->
+<button data-dap="onboarding-next" id="next-step">Next</button>
+<div class="user-profile" data-testid="profile-section">...</div>
+<!-- ❌ Avoid: Generated classes, fragile selectors -->
+<button class="btn-x7j2k9">Next</button>
+<div class="css-1234567">...</div>
+```
+## Flow Execution Model
+### Execution Types
+**Linear Flows**: Steps execute in sequential order
+```json
+{
+  "execution": {
+    "mode": "Linear"
+  },
+  "steps": [
+    { "stepOrder": 1, "stepType": "Mandatory", "stepId": "step1" },
+    { "stepOrder": 2, "stepType": "Optional", "stepId": "step2" },
+    { "stepOrder": 3, "stepType": "Mandatory", "stepId": "step3" }
+  ]
+}
+```
+**AnyOrder Flows**: Steps can be completed in any sequence
+```json
+{
+  "execution": {
+    "mode": "AnyOrder"
+  },
+  "steps": [
+    { "stepType": "Mandatory", "stepId": "intro" },
+    { "stepType": "Optional", "stepId": "tooltip1" },
+    { "stepType": "Mandatory", "stepId": "survey" }
+  ]
+}
+```
+### Step Types
+- **Mandatory**: Required for flow completion
+- **Optional**: Can be skipped without blocking flow completion
+### Trigger Precedence
+1. `step.trigger` - Direct step trigger override
+2. `step.uxExperience.elementTrigger` - Component-specific trigger
+3. Default component trigger (e.g., "click" for buttons)
+### Rule-based Branching
+Steps can include conditional rules that determine next flow transitions:
+```json
+{
+  "stepType": "Rule",
+  "userInputSelector": "#user-role-select",
+  "conditionRuleBlocks": [
+    {
+      "ruleBlockId": "admin-path",
+      "rules": [{"condition": "equals", "value": "admin"}],
+      "nextFlowId": "admin-onboarding"
+    },
+    {
+      "ruleBlockId": "user-path",
+      "rules": [{"condition": "equals", "value": "user"}],
+      "nextFlowId": "user-onboarding"
+    }
+  ]
+}
+```
+## Trigger System
+### Trigger Types
+| Type | Description | Example |
+|------|-------------|---------|
+| **Dom** | Element interaction triggers | `click`, `hover`, `focus`, `blur` |
+| **Input** | Form input events | `change`, `input`, `keydown`, `keyup` |
+| **Lifecycle** | Page/application events | `page load`, `on page load`, `pageload` |
+### Trigger Normalization
+The SDK automatically normalizes trigger strings from the backend:
+```javascript
+// These all normalize to the same trigger:
+"click" → "click"
+"on click" → "click"
+"Click" → "click"
+// Hover triggers:
+"hover" → "mouseenter"
+"on hover" → "mouseenter"
+"mouseover" → "mouseenter"
+// Page load triggers:
+"page load" → "pageload" (synthetic)
+"on page load" → "pageload" (synthetic)
+"pageload" → "pageload" (synthetic)
+// Input triggers:
+"input" → "input"
+"typing" → "input"
+"on input" → "input"
+```
+### Single vs Composite Triggers
+**Single Triggers**: Direct element events
+```json
+{
+  "elementSelector": "#get-started-btn",
+  "elementTrigger": "click"
+}
+```
+**Normalized Triggers**: Backend trigger strings are automatically normalized
+```json
+{
+  "elementSelector": "#form-input",
+  "elementTrigger": "on input"  // Becomes "input" event
+}
+```
+### Debounce and Once Behavior
+- **Debounce**: Prevents rapid-fire trigger execution
+- **Once**: Ensures triggers fire only once per session
+- **Automatic**: Intelligent trigger management for optimal UX
+## Analytics & Telemetry
+### Captured Events
+- **Flow Events**: Start, complete, abandon, skip
+- **Step Events**: View, interact, complete, error
+- **User Behavior**: Click patterns, time on step, navigation paths
+- **Performance**: Load times, render performance, error rates
+### Event Timing
+- **Real-time**: Critical events sent immediately
+- **Batched**: Non-critical events batched for efficiency
+- **Offline**: Events queued when offline, sent when reconnected
+### Privacy Considerations
+- **User Consent**: Respects user privacy preferences
+- **Data Minimization**: Only necessary data collected
+- **Anonymization**: Personal data anonymized by default
+- **GDPR Compliant**: Supports data protection regulations
+### Debug vs Production Logging
+```javascript
+// Enable debug mode for development
+await DAP.init({
+  configUrl: 'https://api.yourcompany.com/config',
+  debug: true  // Verbose console logging
+});
+// Production mode (default)
+await DAP.init({
+  configUrl: 'https://api.yourcompany.com/config'
+}); // Minimal logging
+```
+## Error Handling & Debugging
+### Common Issues
+**Selector Not Found**
+```javascript
+// Check selector specificity
+console.log(document.querySelector('#my-button'));
+// Ensure element exists before step triggers
+await DAP.waitForElement('#my-button', { timeout: 5000 });
+```
+**Step Not Triggering**
+```javascript
+// Verify trigger configuration
+console.log(step.elementTrigger); // Check trigger type
+console.log(step.elementSelector); // Verify selector
+// Check page context
+console.log(DAP.getCurrentPageContext());
+```
+**Flow Not Starting**
+```javascript
+// Verify flow targeting
+console.log(await DAP.getVisibleFlows()); // Check available flows
+console.log(DAP.isFlowRelevant(flowId)); // Check relevance
+```
+### Debug Mode
+Enable detailed logging for troubleshooting:
+```javascript
+// Set debug flag globally
+window.__DAP_DEBUG__ = true;
+// Or via initialization
+await DAP.initialize({ ...config, debug: true });
+// Console output will include:
+// [DAP] Flow evaluation started
+// [DAP] Step triggered: tooltip-1
+// [DAP] Selector resolved: #help-button
+// [DAP] Analytics event sent: step_view
+```
+### Console Log Levels
+| Level | Purpose | Example |
+|-------|---------|---------|
+| `debug` | Detailed execution flow | Step transitions, selector resolution |
+| `info` | General information | Flow starts, completions |
+| `warn` | Potential issues | Missing selectors, deprecated features |
+| `error` | Critical problems | API failures, configuration errors |
+## SDK Development Setup
+### Prerequisites
+- **Node.js**: Version 18+ required
+- **Package Manager**: npm 8+ or yarn 1.22+
+- **TypeScript**: 5.0+ for type safety
+### Local Development Setup
+```bash
+# Clone the repository
+git clone https://github.com/your-org/dap-sdk.git
+cd dap-sdk
+# Install dependencies
+npm install
+# Start development server with hot reload
+npm run dev
+# Build for production
+npm run build
+# Serve built files locally (serves on http://localhost:5173)
+npm run serve
+```
+### Project Structure
+```
+src/
+├── core/              # Core engine and flow management
+│   ├── flowEngine.ts  # Main flow execution engine
+│   └── triggerManager.ts # Trigger system management
+├── experiences/       # UI component renderers
+│   ├── modal.ts      # Modal experience
+│   ├── tooltip.ts    # Tooltip experience
+│   ├── survey.ts     # Survey components
+│   └── ...           # Other UI experiences
+├── services/         # Core services
+│   ├── flowManager.ts        # Flow lifecycle management
+│   ├── userContextService.ts # User context tracking
+│   └── pageContextService.ts # Page navigation tracking
+├── utils/            # Utility functions
+│   ├── selectors.ts  # DOM selector helpers
+│   ├── analytics.ts  # Analytics and tracking
+│   └── validation.ts # Input validation
+└── styles/           # Component styles
+    ├── modal.css.ts  # Modal styling
+    └── ...           # Other component styles
+```
+### Key Components
+- **FlowEngine**: Orchestrates flow execution and step management
+- **TriggerManager**: Handles DOM event binding and trigger evaluation
+- **PageContextService**: Tracks page navigation and context changes
+- **UserContextService**: Manages user state and preferences
+- **ValidationInterceptor**: Handles form validation integration
+## Running & Testing
+### Local Testing Strategy
+1. **Development Server**: Use `npm run dev` for hot reloading
+2. **Test Pages**: Create HTML pages in `public/` for manual testing
+3. **Flow JSON**: Place test flow configurations in `public/test-flows/`
+4. **Browser DevTools**: Use debug mode for real-time inspection
+### Sample Flow JSON for Testing
+```json
+{
+  "flowId": "test-onboarding",
+  "flowName": "Test Onboarding Flow",
+  "execution": {
+    "mode": "Linear",
+    "frequency": {
+      "type": "OneTime",
+      "maxRuns": 1
+    }
+  },
+  "steps": [
+    {
+      "stepId": "welcome-modal",
+      "stepOrder": 1,
+      "stepType": "Mandatory",
+      "uxExperience": {
+        "uxExperienceType": "modal",
+        "elementSelector": "body",
+        "elementTrigger": "immediate",
+        "modalContent": {
+          "title": "Welcome!",
+          "body": [
+            { "kind": "text", "html": "<p>Welcome to our application!</p>" },
+            { "kind": "text", "html": "<p>Let's get you started!</p>" }
+          ]
+        }
+      }
+    },
+    {
+      "stepId": "feature-tooltip",
+      "stepOrder": 2,
+      "stepType": "Optional",
+      "uxExperience": {
+        "uxExperienceType": "tooltip",
+        "elementSelector": "#main-feature",
+        "elementTrigger": "hover",
+        "content": {
+          "text": "This is our main feature!"
+        }
+      }
+    }
+  ]
+}
+```
+### Debug Tips
+```javascript
+// Inspect current SDK state
+console.log(DAP.getFlowState());
+// Check user context
+console.log(DAP.getUserState());
+// Execute custom flow
+await DAP.executeFlow(customFlowData);
+// Register flow for later execution
+DAP.registerFlow(flowData);
+// Start registered flow by ID
+await DAP.startFlow('my-flow-id');
+// Validate selectors
+const element = DAP.resolveSelector('#my-button'); // Returns element or null
+// Debug utilities (only available when debug=true)
+if (window.__DAP_DEBUG__) {
+  await DAP.testFlow('flow-id'); // Test specific flow
+  DAP.renderModal(modalConfig); // Test modal rendering
+}
+```
+## Advanced API
+### Flow Management
+#### Register Custom Flows
+```javascript
+// Register a flow for later execution
+DAP.registerFlow({
+  flowId: 'custom-onboarding',
+  flowName: 'Custom Onboarding Flow',
+  execution: {
+    mode: 'Linear',
+    frequency: { type: 'OneTime', maxRuns: 1 }
+  },
+  steps: [
+    {
+      stepId: 'welcome',
+      stepOrder: 1,
+      stepType: 'Mandatory',
+      uxExperience: {
+        uxExperienceType: 'modal',
+        elementTrigger: 'immediate',
+        modalContent: {
+          title: 'Welcome!',
+          body: [{ kind: 'text', html: '<p>Welcome to our app!</p>' }]
+        }
+      }
+    }
+  ]
+});
+// Execute registered flow
+await DAP.startFlow('custom-onboarding');
+```
+#### Execute Dynamic Flows
+```javascript
+// Execute a flow without registering
+await DAP.executeFlow({
+  flowId: 'dynamic-help',
+  flowName: 'Dynamic Help Flow',
+  steps: [
+    {
+      stepId: 'help-tooltip',
+      uxExperience: {
+        uxExperienceType: 'tooltip',
+        elementSelector: '#help-button',
+        elementTrigger: 'hover',
+        content: { text: 'Click here for help!' }
+      }
+    }
+  ]
+});
+```
+### Debug and Development
+#### State Inspection
+```javascript
+// Get current flow engine state
+const flowState = DAP.getFlowState();
+console.log('Active flow:', flowState.activeFlowId);
+console.log('Flow in progress:', flowState.flowInProgress);
+// Get user context debug state
+const userState = DAP.getUserState();
+console.log('Has user:', userState.hasUser);
+console.log('User ID:', userState.userId);
+console.log('Is anonymous:', userState.isAnonymous);
+```
+#### Element Resolution
+```javascript
+// Test selector resolution (useful for debugging)
+const element = DAP.resolveSelector('#my-button');
+if (element) {
+  console.log('Element found:', element);
+} else {
+  console.warn('Element not found');
+}
+```
+#### Debug Mode Features
+```javascript
+// Available only when debug=true during initialization
+if (window.__DAP_DEBUG__) {
+  // Test any flow by ID
+  await DAP.testFlow('flow-id-from-backend');
+  // Test modal rendering directly
+  DAP.renderModal({
+    title: 'Test Modal',
+    body: [{ kind: 'text', html: '<p>Testing modal</p>' }]
+  });
+}
+```
+### Core Services Access
+For advanced use cases, you can access core services directly:
+```javascript
+// Location context service
+const locationService = DAP.locationContext;
+console.log('Current context:', locationService.getContext());
+// User context service
+const userService = DAP.userContext;
+console.log('Analytics context:', userService.getAnalyticsContext());
+// Flow engine (use with caution)
+const engine = DAP.flowEngine;
+console.log('Engine state:', engine.getState());
+```
+## Configuration Reference
+### Execution Configuration
+```typescript
+interface ExecutionConfig {
+  mode: 'Linear' | 'AnyOrder';
+  multiPage?: boolean;          // Enable multi-page flows
+  frequency?: {
+    type: 'OneTime' | 'Daily' | 'Weekly' | 'Monthly';
+    maxRuns: number;            // Maximum execution count
+  };
+  targeting?: {
+    pages?: string[];           // URL patterns
+    userSegments?: string[];    // User segments
+    devices?: string[];         // Device types
+  };
+}
+```
+### Trigger Configuration
+```typescript
+interface TriggerConfig {
+  elementSelector: string;    // CSS selector
+  elementTrigger: string;     // Event type
+  debounce?: number;          // Debounce delay (ms)
+  once?: boolean;             // Fire only once
+  conditions?: string[];      // Additional conditions
+}
+```
+### Step Configuration
+```typescript
+interface StepConfig {
+  stepId: string;
+  stepOrder?: number;         // For Linear flows
+  stepType: 'Mandatory' | 'Optional' | 'Rule';
+  uxExperience: UXExperience;
+  targeting?: PageTargeting;  // Step-specific targeting
+}
+```
+### Rule Configuration
+```typescript
+interface RuleConfig {
+  userInputSelector: string;  // Input element selector
+  conditionRuleBlocks: {
+    ruleBlockId: string;
+    rules: {
+      condition: 'equals' | 'contains' | 'matches';
+      value: string;
+    }[];
+    nextFlowId: string;       // Target flow for this rule
+  }[];
+}
+```
+## FAQ
+### Why isn't my step triggering?
+1. **Check selector**: Verify the element exists: `document.querySelector(selector)`
+2. **Check page context**: Ensure you're on the correct page
+3. **Check timing**: Element might not be ready; add delays or use `waitForElement`
+4. **Check trigger type**: Verify the trigger event is appropriate for the element
+### How does multi-page support work?
+The SDK automatically:
+- Detects page navigation events
+- Preserves flow state across pages
+- Re-evaluates step relevance on each page
+- Handles both SPA and traditional page navigation
+### Why are rules evaluated late in the flow?
+Rule steps are evaluated when:
+- The user interacts with the specified input element
+- Input value changes trigger rule evaluation
+- This allows for dynamic flow branching based on user choices
+### How do I avoid selector issues?
+1. **Use stable selectors**: Prefer `data-*` attributes over CSS classes
+2. **Test selectors**: Verify selectors work in browser DevTools
+3. **Add fallbacks**: Provide alternative selectors when possible
+4. **Use semantic HTML**: Leverage semantic elements with stable attributes
+### Can I customize component styles?
+Yes! Components support:
+- **CSS custom properties**: Override default styles
+- **Theme configuration**: Pass custom themes via flow JSON
+- **Style injection**: Inject custom CSS for specific experiences
+### How do I handle dynamic content?
+- **Observer patterns**: SDK automatically observes DOM changes
+- **Refresh triggers**: Call `DAP.refreshFlows()` after content updates
+- **Dynamic selectors**: Use flexible selectors that work with dynamic IDs
+## Versioning & Compatibility
+### SDK Versioning
+The SDK follows [Semantic Versioning](https://semver.org/):
+- **Major** (X.0.0): Breaking changes, requires code updates
+- **Minor** (0.X.0): New features, backward compatible
+- **Patch** (0.0.X): Bug fixes, backward compatible
+### Flow JSON Compatibility
+- **Backward Compatible**: New SDK versions support older Flow JSON schemas
+- **Deprecation Notices**: Old features marked deprecated with migration guidance
+- **Schema Evolution**: New flow features added incrementally
+### Upgrade Notes
+```javascript
+// Version 2.x → 3.x Migration Example
+// OLD (deprecated)
+await DAP.init(config);
+// NEW (recommended)
+await DAP.initialize(config);
+// Check for deprecation warnings in console during development
+```
+### Browser Support Policy
+- **Current**: Support for current and previous major browser versions
+- **Legacy**: Best-effort support for IE 11 (with polyfills)
+- **Testing**: Automated testing across major browser combinations
+## License & Support
+### License
+This SDK is proprietary software licensed under the [Your Company License Agreement]. See `LICENSE.md` for complete terms.
+### Support & Contact
+- **Documentation**: [https://docs.your-company.com/dap-sdk](https://docs.your-company.com/dap-sdk)
+- **Support Portal**: [https://support.your-company.com](https://support.your-company.com)
+- **Community Forum**: [https://community.your-company.com](https://community.your-company.com)
+- **Email Support**: [dap-support@your-company.com](mailto:dap-support@your-company.com)
+### Contributing
+We welcome contributions from the community! Please see `CONTRIBUTING.md` for guidelines on:
+- Code standards and style guide
+- Testing requirements
+- Pull request process
+- Issue reporting templates
+---
+**Built with ❤️ by the DAP Team**