fix: inline plugin stability and scroll depth trigger filtering

- Prevent duplicate inline experiences from being shown
- Fix scroll depth threshold evaluation to match specific percentages
- Remove trigger:inline emission that caused infinite event loops
- Add scrollDepth.reset() method to clear triggered thresholds
- Expand HTML sanitizer to allow div, ul, li tags for rich content
- Add smooth fade-in animations to inline experiences
- Add display conditions evaluation for trigger-based experiences
- Add inline to Experience type union
- Add tests for new functionality (432 tests passing)

Author: prosdev

.changeset/phase-2-presentation-layer.md

@@ -0,0 +1,107 @@
+---
+"@prosdevlab/experience-sdk": minor
+"@prosdevlab/experience-sdk-plugins": minor
+---
+
+**Phase 2: Presentation Layer - Modal & Inline Plugins**
+
+This release introduces two powerful new rendering plugins with built-in form support, completing the presentation layer for the Experience SDK.
+
+## 🎉 New Features
+
+### Modal Plugin
+- **Rich Content Modals**: Display announcements, promotions, and interactive content
+- **Built-in Forms**: Email capture, surveys, and feedback forms with validation
+- **Size Variants**: Small, medium, large, and extra-large sizes
+- **Hero Images**: Full-width images for visual impact
+- **Responsive Design**: Mobile fullscreen mode for optimal UX
+- **Keyboard Navigation**: Focus trap, Escape key, Tab navigation
+- **Animations**: Smooth fade-in/fade-out transitions
+- **Form States**: Success, error, and loading states
+- **API Methods**: `show()`, `remove()`, `isShowing()`, `showFormState()`, `resetForm()`, `getFormData()`
+
+### Inline Plugin
+- **DOM Insertion**: Embed content anywhere in your page
+- **5 Insertion Methods**: `replace`, `append`, `prepend`, `before`, `after`
+- **CSS Selector Targeting**: Use any valid selector to target elements
+- **Dismissal with Persistence**: Users can dismiss and it persists in localStorage
+- **No Layout Disruption**: Seamlessly integrates with existing page structure
+- **API Methods**: `show()`, `remove()`, `isShowing()`
+
+### Forms (Built into Modal)
+- **Field Types**: text, email, url, tel, number, textarea, select, checkbox, radio
+- **Validation**: Required, email, URL, pattern, custom validation, min/max length
+- **Real-time Feedback**: Validates on blur, shows errors inline
+- **Submission Handling**: Emits `experiences:modal:form:submit` event
+- **Success/Error States**: Built-in UI for post-submission states
+- **Pure Functions**: Validation and rendering logic easily extractable
+
+## 🎨 Theming & Customization
+
+### CSS Variables
+All plugins now support CSS variable theming:
+- **Modal**: `--xp-modal-*` variables for backdrop, dialog, title, content, buttons
+- **Forms**: `--xp-form-*` variables for inputs, labels, errors, submit button
+- **Banner**: `--xp-banner-*` variables (refactored from inline styles)
+- **Inline**: `--xp-inline-*` variables for custom styling
+
+See the [Theming Guide](https://prosdevlab.github.io/experience-sdk/guides/theming) for full reference.
+
+## 🔧 API Improvements
+
+### Runtime
+- **Auto-registration**: Modal and inline plugins are automatically registered
+- **Plugin API Access**: Expose plugin APIs via singleton (`experiences.modal.show()`)
+- **Trigger Event Handling**: Explicit listeners for each trigger type (exit intent, scroll depth, time delay)
+
+### Display Conditions
+Seamless integration with existing display condition plugins:
+- **Exit Intent + Modal**: Capture emails before users leave
+- **Scroll Depth + Inline**: Progressive feature discovery
+- **Time Delay + Modal**: Time-sensitive promotions
+- **Page Visits + Banner**: Returning user messages
+
+## 📦 Bundle Size
+- **Core SDK**: 13.4 KB gzipped (under 15 KB target ✅)
+- **All Plugins**: ~26 KB gzipped total (smaller than competitors like Pathfora at ~47 KB)
+- **Excellent Compression**: CSS-in-JS with CSS variables maintains small footprint
+
+## 🧪 Testing
+- **427 tests passing** (unit, integration, browser tests)
+- **Modal Plugin**: 50+ tests for core functionality, forms, keyboard nav, accessibility
+- **Inline Plugin**: 24+ tests for DOM insertion, dismissal, persistence
+- **Form Validation**: 35+ tests for all field types and edge cases
+- **Integration Tests**: 10+ tests for plugin interactions
+- **Browser Tests**: 5+ tests with Playwright for real browser behavior
+
+## 📚 Documentation
+- **Modal Plugin Reference**: Complete API docs with examples
+- **Inline Plugin Reference**: Full insertion method documentation
+- **Theming Guide**: CSS variable reference with examples
+- **Use Case Examples**: 4 complete implementation guides in playground
+
+## 🚀 Playground Enhancements
+- **Layout Gallery Hub**: Visual directory for banner, modal, and inline layouts
+- **Navigation System**: Breadcrumbs and sub-navigation tabs
+- **Use Case Examples**:
+  - Exit Intent Email Capture (exit intent + modal forms)
+  - Feature Discovery Journey (scroll depth + inline + modal)
+  - Time-Delayed Promotions (time delay + hero image modal)
+  - Promotions & Announcements (banner examples)
+- **Interactive Demos**: Live examples with SDK integration
+
+## ⚠️ Breaking Changes
+None. This is a **minor** release with backward compatibility.
+
+## 🔜 Next Steps (Phase 3+)
+- Browser tests for form focus management
+- Composable form plugin (separate from modal)
+- Additional layout plugins (tooltip, slideout, sticky bar)
+- Multi-instance support with `instanceId` tracking
+
+---
+
+**Migration Guide**: No migration needed. Simply upgrade and start using the new plugins!
+
+**Full Changelog**: See [Phase 2 Spec](https://github.com/prosdevlab/experience-sdk/blob/main/specs/phase-2-presentation-layer/spec.md)
+

biome.json

@@ -31,6 +31,7 @@
       "includes": [
         "packages/core/src/types.ts",
         "packages/core/src/runtime.ts",
+        "packages/core/src/singleton.ts",
         "packages/plugins/src/types.ts",
         "packages/plugins/src/exit-intent/exit-intent.ts",
         "packages/plugins/src/scroll-depth/scroll-depth.ts",

packages/core/src/runtime.test.ts

@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { ExperienceRuntime, evaluateUrlRule } from './runtime';
+import { ExperienceRuntime, evaluateExperience, evaluateUrlRule } from './runtime';
 
 describe('ExperienceRuntime', () => {
   let runtime: ExperienceRuntime;
@@ -447,6 +447,114 @@ describe('ExperienceRuntime', () => {
     });
   });
 
+  describe('display trigger evaluation', () => {
+    it('should match experience when scrollDepth threshold is reached', () => {
+      const experience = {
+        id: 'scroll-test',
+        type: 'inline' as const,
+        content: {},
+        targeting: {},
+        display: {
+          trigger: 'scrollDepth',
+          triggerData: { threshold: 50 },
+        },
+      };
+
+      const context = {
+        url: 'https://example.com',
+        timestamp: Date.now(),
+        triggers: {
+          scrollDepth: {
+            triggered: true,
+            threshold: 50,
+            percent: 50.5,
+          },
+        },
+      };
+
+      const result = evaluateExperience(experience, context);
+      expect(result.matched).toBe(true);
+      expect(result.reasons).toContain('Scroll depth threshold (50%) reached');
+    });
+
+    it('should not match experience when scrollDepth threshold does not match', () => {
+      const experience = {
+        id: 'scroll-test',
+        type: 'inline' as const,
+        content: {},
+        targeting: {},
+        display: {
+          trigger: 'scrollDepth',
+          triggerData: { threshold: 50 },
+        },
+      };
+
+      const context = {
+        url: 'https://example.com',
+        timestamp: Date.now(),
+        triggers: {
+          scrollDepth: {
+            triggered: true,
+            threshold: 25, // Different threshold
+            percent: 25.5,
+          },
+        },
+      };
+
+      const result = evaluateExperience(experience, context);
+      expect(result.matched).toBe(false);
+      expect(result.reasons).toContain('Scroll depth threshold mismatch (expected 50%, got 25%)');
+    });
+
+    it('should not match experience when trigger has not fired', () => {
+      const experience = {
+        id: 'scroll-test',
+        type: 'inline' as const,
+        content: {},
+        targeting: {},
+        display: {
+          trigger: 'exitIntent',
+        },
+      };
+
+      const context = {
+        url: 'https://example.com',
+        timestamp: Date.now(),
+        triggers: {},
+      };
+
+      const result = evaluateExperience(experience, context);
+      expect(result.matched).toBe(false);
+      expect(result.reasons).toContain('Waiting for exitIntent trigger');
+    });
+
+    it('should match non-scrollDepth triggers when triggered', () => {
+      const experience = {
+        id: 'exit-test',
+        type: 'modal' as const,
+        content: {},
+        targeting: {},
+        display: {
+          trigger: 'exitIntent',
+        },
+      };
+
+      const context = {
+        url: 'https://example.com',
+        timestamp: Date.now(),
+        triggers: {
+          exitIntent: {
+            triggered: true,
+          },
+        },
+      };
+
+      const result = evaluateExperience(experience, context);
+      expect(result.matched).toBe(true);
+      expect(result.reasons).toContain('exitIntent trigger fired');
+    });
+  });
+
   describe('frequency targeting', () => {
     it('should track frequency rule in trace', async () => {
       await runtime.init();
@@ -622,7 +730,7 @@ describe('ExperienceRuntime', () => {
       expect(decisions2.find((d) => d.experienceId === 'capped')?.show).toBe(false);
     });
 
-    it('should emit experiences:evaluated event with array', () => {
+    it('should emit experiences:evaluated event for each matched experience', () => {
       const handler = vi.fn();
       runtime.on('experiences:evaluated', handler);
 
@@ -640,18 +748,20 @@ describe('ExperienceRuntime', () => {
 
       runtime.evaluateAll();
 
-      expect(handler).toHaveBeenCalledOnce();
-      expect(handler).toHaveBeenCalledWith(
-        expect.arrayContaining([
-          expect.objectContaining({
-            decision: expect.objectContaining({ experienceId: 'banner1' }),
-            experience: expect.objectContaining({ id: 'banner1' }),
-          }),
-          expect.objectContaining({
-            decision: expect.objectContaining({ experienceId: 'banner2' }),
-            experience: expect.objectContaining({ id: 'banner2' }),
-          }),
-        ])
+      expect(handler).toHaveBeenCalledTimes(2);
+      expect(handler).toHaveBeenNthCalledWith(
+        1,
+        expect.objectContaining({
+          decision: expect.objectContaining({ experienceId: 'banner1' }),
+          experience: expect.objectContaining({ id: 'banner1' }),
+        })
+      );
+      expect(handler).toHaveBeenNthCalledWith(
+        2,
+        expect.objectContaining({
+          decision: expect.objectContaining({ experienceId: 'banner2' }),
+          experience: expect.objectContaining({ id: 'banner2' }),
+        })
       );
     });
 
@@ -674,9 +784,9 @@ describe('ExperienceRuntime', () => {
       runtime.evaluateAll({ url: 'https://example.com/' });
 
       expect(handler).toHaveBeenCalledOnce();
-      const emittedDecisions = handler.mock.calls[0][0];
-      expect(emittedDecisions).toHaveLength(1);
-      expect(emittedDecisions[0].decision.experienceId).toBe('match');
+      const emittedData = handler.mock.calls[0][0];
+      expect(emittedData.decision.experienceId).toBe('match');
+      expect(emittedData.experience.id).toBe('match');
     });
 
     it('should return empty array when no experiences registered', () => {

packages/core/src/runtime.ts

@@ -99,8 +99,10 @@ export class ExperienceRuntime {
           ...data, // Merge trigger-specific data
         };
 
-        // Re-evaluate all experiences with updated context
-        this.evaluate(this.triggerContext);
+        // Re-evaluate ALL experiences with updated trigger context
+        // Using evaluateAll() to show multiple matching experiences
+        // buildContext() will automatically add the current URL
+        this.evaluateAll(this.triggerContext);
       });
     }
   }
@@ -336,20 +338,20 @@ export class ExperienceRuntime {
       this.decisions.push(decision);
     }
 
-    // Emit single event with all decisions (array)
-    // Plugins can filter to their relevant experiences
+    // Emit one event per matched experience
+    // This allows plugins to react individually to each experience
     const matchedDecisions = decisions.filter((d) => d.show);
-    const matchedExperiences = matchedDecisions
-      .map((d) => d.experienceId && this.experiences.get(d.experienceId))
-      .filter((exp): exp is Experience => exp !== undefined);
-
-    this.sdk.emit(
-      'experiences:evaluated',
-      matchedDecisions.map((decision, index) => ({
-        decision,
-        experience: matchedExperiences[index],
-      }))
-    );
+    for (const decision of matchedDecisions) {
+      const experience = decision.experienceId
+        ? this.experiences.get(decision.experienceId)
+        : undefined;
+      if (experience) {
+        this.sdk.emit('experiences:evaluated', {
+          decision,
+          experience,
+        });
+      }
+    }
 
     return decisions;
   }
@@ -442,7 +444,7 @@ export function evaluateExperience(
   let matched = true;
 
   // Evaluate URL rule
-  if (experience.targeting.url) {
+  if (experience.targeting?.url) {
     const urlStart = Date.now();
     const urlMatch = evaluateUrlRule(experience.targeting.url, context.url);
 
@@ -463,6 +465,36 @@ export function evaluateExperience(
     }
   }
 
+  // Evaluate display trigger conditions
+  if (experience.display?.trigger && context.triggers) {
+    const triggerType = experience.display.trigger;
+    const triggerData = context.triggers[triggerType];
+
+    // Check if this trigger has fired
+    if (!triggerData?.triggered) {
+      reasons.push(`Waiting for ${triggerType} trigger`);
+      matched = false;
+    } else {
+      // For scrollDepth, check if threshold matches
+      if (triggerType === 'scrollDepth' && experience.display.triggerData?.threshold) {
+        const expectedThreshold = experience.display.triggerData.threshold;
+        const actualThreshold = triggerData.threshold;
+
+        if (actualThreshold === expectedThreshold) {
+          reasons.push(`Scroll depth threshold (${expectedThreshold}%) reached`);
+        } else {
+          reasons.push(
+            `Scroll depth threshold mismatch (expected ${expectedThreshold}%, got ${actualThreshold}%)`
+          );
+          matched = false;
+        }
+      } else {
+        // Other triggers just need to be triggered
+        reasons.push(`${triggerType} trigger fired`);
+      }
+    }
+  }
+
   return { matched, reasons, trace };
 }