@widgetic/embed-sdk 0.0.0-stage → 2.0.7

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 (89) hide show
  1. package/README.md +567 -2
  2. package/dist/browser/chunks/ABTestManager.js +1 -0
  3. package/dist/browser/chunks/advanced.js +1 -0
  4. package/dist/browser/chunks/api.js +1 -0
  5. package/dist/browser/chunks/core.js +1 -0
  6. package/dist/browser/chunks/display.js +1 -0
  7. package/dist/browser/chunks/media.js +1 -0
  8. package/dist/browser/chunks/messaging.js +1 -0
  9. package/dist/browser/chunks/performance.js +1 -0
  10. package/dist/browser/chunks/renderers.js +1 -0
  11. package/dist/browser/chunks/scanner.js +1 -0
  12. package/dist/browser/chunks/security.js +1 -0
  13. package/dist/browser/chunks/vendor.js +1 -0
  14. package/dist/browser/embed-bootstrap.js +1 -0
  15. package/dist/browser/embed-sdk.js +1 -0
  16. package/dist/esm/chunks/ABTestManager.js +1 -0
  17. package/dist/esm/chunks/advanced.js +1 -0
  18. package/dist/esm/chunks/api.js +1 -0
  19. package/dist/esm/chunks/core.js +1 -0
  20. package/dist/esm/chunks/display.js +1 -0
  21. package/dist/esm/chunks/media.js +1 -0
  22. package/dist/esm/chunks/messaging.js +1 -0
  23. package/dist/esm/chunks/performance.js +1 -0
  24. package/dist/esm/chunks/renderers.js +1 -0
  25. package/dist/esm/chunks/scanner.js +1 -0
  26. package/dist/esm/chunks/security.js +1 -0
  27. package/dist/esm/chunks/vendor.js +1 -0
  28. package/dist/esm/embed-bootstrap.js +1 -0
  29. package/dist/esm/embed-sdk.js +1 -0
  30. package/dist/esm/types/abTesting/ABTestElement.d.ts +120 -0
  31. package/dist/esm/types/abTesting/ABTestManager.d.ts +177 -0
  32. package/dist/esm/types/api/batch-client.d.ts +163 -0
  33. package/dist/esm/types/api/layers.d.ts +119 -0
  34. package/dist/esm/types/core/advanced-security-manager.d.ts +330 -0
  35. package/dist/esm/types/core/analytics-tracker.d.ts +224 -0
  36. package/dist/esm/types/core/auth-detector.d.ts +65 -0
  37. package/dist/esm/types/core/auth-manager.d.ts +90 -0
  38. package/dist/esm/types/core/autoscale-manager.d.ts +91 -0
  39. package/dist/esm/types/core/breakpoints.d.ts +48 -0
  40. package/dist/esm/types/core/config.d.ts +152 -0
  41. package/dist/esm/types/core/constants.d.ts +75 -0
  42. package/dist/esm/types/core/content-position-manager.d.ts +228 -0
  43. package/dist/esm/types/core/custom-element.d.ts +152 -0
  44. package/dist/esm/types/core/display-manager.d.ts +109 -0
  45. package/dist/esm/types/core/editor-overlay.d.ts +113 -0
  46. package/dist/esm/types/core/embed-sdk.d.ts +310 -0
  47. package/dist/esm/types/core/exit-intent-trigger.d.ts +114 -0
  48. package/dist/esm/types/core/lazy-loader.d.ts +111 -0
  49. package/dist/esm/types/core/media-manager.d.ts +364 -0
  50. package/dist/esm/types/core/messaging.d.ts +251 -0
  51. package/dist/esm/types/core/overlay-manager.d.ts +119 -0
  52. package/dist/esm/types/core/performance-monitor.d.ts +152 -0
  53. package/dist/esm/types/core/privacy-compliance.d.ts +236 -0
  54. package/dist/esm/types/core/realtime-manager.d.ts +279 -0
  55. package/dist/esm/types/core/resize-handler.d.ts +81 -0
  56. package/dist/esm/types/core/resource-optimizer.d.ts +133 -0
  57. package/dist/esm/types/core/responsive-manager.d.ts +49 -0
  58. package/dist/esm/types/core/scroll-trigger.d.ts +105 -0
  59. package/dist/esm/types/core/security-manager.d.ts +150 -0
  60. package/dist/esm/types/core/text-field-manager.d.ts +204 -0
  61. package/dist/esm/types/core/token-provider.d.ts +75 -0
  62. package/dist/esm/types/core/trigger-defaults.d.ts +36 -0
  63. package/dist/esm/types/core/trigger-manager.d.ts +248 -0
  64. package/dist/esm/types/core/types.d.ts +473 -0
  65. package/dist/esm/types/core/ui-sdk-loader.d.ts +90 -0
  66. package/dist/esm/types/core/widget-manager.d.ts +285 -0
  67. package/dist/esm/types/core/widget-metadata.d.ts +107 -0
  68. package/dist/esm/types/embed-sdk.d.ts +31 -0
  69. package/dist/esm/types/loaders/module-loader.d.ts +147 -0
  70. package/dist/esm/types/renderers/custom-element-renderer.d.ts +78 -0
  71. package/dist/esm/types/renderers/iframe-renderer.d.ts +185 -0
  72. package/dist/esm/types/renderers/widget-renderer.d.ts +173 -0
  73. package/dist/esm/types/sdk/embed-bootstrap.d.ts +84 -0
  74. package/dist/esm/types/sdk/embed-sdk.d.ts +31 -0
  75. package/dist/esm/types/translations/TranslationElement.d.ts +93 -0
  76. package/dist/esm/types/utils/browser.d.ts +29 -0
  77. package/dist/esm/types/utils/caseConversion.d.ts +2 -0
  78. package/dist/esm/types/utils/css-debug.d.ts +105 -0
  79. package/dist/esm/types/utils/device-detector.d.ts +100 -0
  80. package/dist/esm/types/utils/event-emitter.d.ts +14 -0
  81. package/dist/esm/types/utils/hydrate-published-host.d.ts +17 -0
  82. package/dist/esm/types/utils/logger.d.ts +31 -0
  83. package/dist/esm/types/utils/parser.d.ts +39 -0
  84. package/dist/esm/types/utils/portal.d.ts +74 -0
  85. package/dist/esm/types/utils/public-embed-lookup.d.ts +68 -0
  86. package/dist/esm/types/utils/published-host-display.d.ts +61 -0
  87. package/dist/umd/embed-bootstrap.js +1 -0
  88. package/dist/umd/embed-sdk.js +1 -0
  89. package/package.json +154 -4
@@ -0,0 +1,105 @@
1
+ /**
2
+ * Phase 3: CSS Debugging and Conflict Detection Tools
3
+ * Helps developers debug widget styling issues and CSS conflicts
4
+ */
5
+ export interface CSSConflict {
6
+ property: string;
7
+ widgetValue: string;
8
+ externalValue: string;
9
+ specificity: number;
10
+ source: string;
11
+ }
12
+ export interface StyleIsolationReport {
13
+ widgetId: string;
14
+ conflicts: CSSConflict[];
15
+ isolationScore: number;
16
+ recommendations: string[];
17
+ }
18
+ /**
19
+ * CSS Debugging and Conflict Detection Utility
20
+ */
21
+ export declare class CSSDebugger {
22
+ private static instance;
23
+ private debugMode;
24
+ private trackedElements;
25
+ static getInstance(): CSSDebugger;
26
+ /**
27
+ * Enable CSS debugging mode
28
+ */
29
+ enableDebugMode(): void;
30
+ /**
31
+ * Disable CSS debugging mode
32
+ */
33
+ disableDebugMode(): void;
34
+ /**
35
+ * Analyze CSS conflicts for a widget element
36
+ */
37
+ analyzeWidget(element: Element): StyleIsolationReport;
38
+ /**
39
+ * Detect CSS conflicts between widget and external styles
40
+ */
41
+ private detectCSSConflicts;
42
+ /**
43
+ * Check style isolation effectiveness
44
+ */
45
+ private checkStyleIsolation;
46
+ /**
47
+ * Calculate isolation score (0-100)
48
+ */
49
+ private calculateIsolationScore;
50
+ /**
51
+ * Check if a style comes from external sources
52
+ */
53
+ private isExternalStyle;
54
+ /**
55
+ * Check if a style is widget-specific
56
+ */
57
+ private isWidgetStyle;
58
+ /**
59
+ * Get widget's intended style value
60
+ */
61
+ private getWidgetStyleValue;
62
+ /**
63
+ * Calculate CSS specificity for debugging
64
+ */
65
+ private calculateSpecificity;
66
+ /**
67
+ * Get style source information
68
+ */
69
+ private getStyleSource;
70
+ /**
71
+ * Get matching CSS rules for an element
72
+ */
73
+ private getMatchingCSSRules;
74
+ /**
75
+ * Check if element creates a stacking context
76
+ */
77
+ private hasStackingContext;
78
+ /**
79
+ * Add debug styles to highlight widget boundaries
80
+ */
81
+ private addDebugStyles;
82
+ /**
83
+ * Remove debug styles
84
+ */
85
+ private removeDebugStyles;
86
+ /**
87
+ * Display debug report in console
88
+ */
89
+ private displayDebugReport;
90
+ /**
91
+ * Monitor widget for style changes
92
+ */
93
+ monitorWidget(element: Element): void;
94
+ }
95
+ /**
96
+ * Global CSS debugger instance
97
+ */
98
+ export declare const cssDebugger: CSSDebugger;
99
+ /**
100
+ * Convenience functions for global access
101
+ */
102
+ export declare function enableCSSDebug(): void;
103
+ export declare function disableCSSDebug(): void;
104
+ export declare function analyzeWidgetCSS(element: Element): StyleIsolationReport;
105
+ export declare function monitorWidgetCSS(element: Element): void;
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Device Detection Utility
3
+ * Determines device type using user agent, touch capabilities, and hardware features
4
+ * Does not rely on screen width for more reliable detection
5
+ */
6
+ export type DeviceType = 'mobile' | 'tablet' | 'desktop';
7
+ export interface DeviceInfo {
8
+ type: DeviceType;
9
+ isMobile: boolean;
10
+ isTablet: boolean;
11
+ isDesktop: boolean;
12
+ hasTouch: boolean;
13
+ userAgent: string;
14
+ platform: string;
15
+ vendor: string;
16
+ maxTouchPoints: number;
17
+ hardwareConcurrency: number;
18
+ deviceMemory?: number;
19
+ }
20
+ /**
21
+ * Comprehensive device detection class
22
+ */
23
+ export declare class DeviceDetector {
24
+ private static instance;
25
+ private deviceInfo;
26
+ private constructor();
27
+ static getInstance(): DeviceDetector;
28
+ /**
29
+ * Get current device information
30
+ */
31
+ getDeviceInfo(): DeviceInfo;
32
+ /**
33
+ * Get device type (mobile, tablet, desktop)
34
+ */
35
+ getDeviceType(): DeviceType;
36
+ /**
37
+ * Check if device is mobile
38
+ */
39
+ isMobile(): boolean;
40
+ /**
41
+ * Check if device is tablet
42
+ */
43
+ isTablet(): boolean;
44
+ /**
45
+ * Check if device is desktop (includes tablets)
46
+ */
47
+ isDesktop(): boolean;
48
+ /**
49
+ * Check if device has touch capabilities
50
+ */
51
+ hasTouch(): boolean;
52
+ /**
53
+ * Perform comprehensive device detection
54
+ */
55
+ private detectDevice;
56
+ /**
57
+ * Detect touch capability using multiple methods
58
+ */
59
+ private detectTouchCapability;
60
+ /**
61
+ * Determine device type using multiple detection methods
62
+ */
63
+ private determineDeviceType;
64
+ /**
65
+ * Check device restrictions against current device
66
+ */
67
+ checkDeviceRestrictions(mobileEnabled?: boolean, desktopEnabled?: boolean): boolean;
68
+ /**
69
+ * Get detailed device capabilities for debugging
70
+ */
71
+ getDeviceCapabilities(): any;
72
+ /**
73
+ * Reset device detection (for testing)
74
+ */
75
+ reset(): void;
76
+ }
77
+ /**
78
+ * Get global device detector instance
79
+ */
80
+ export declare function getDeviceDetector(): DeviceDetector;
81
+ /**
82
+ * Quick device type check
83
+ */
84
+ export declare function getDeviceType(): DeviceType;
85
+ /**
86
+ * Quick mobile check
87
+ */
88
+ export declare function isMobile(): boolean;
89
+ /**
90
+ * Quick tablet check
91
+ */
92
+ export declare function isTablet(): boolean;
93
+ /**
94
+ * Quick desktop check (includes tablets)
95
+ */
96
+ export declare function isDesktop(): boolean;
97
+ /**
98
+ * Check if current device is allowed based on restrictions
99
+ */
100
+ export declare function isDeviceAllowed(mobileEnabled?: boolean, desktopEnabled?: boolean): boolean;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Lightweight, browser-compatible EventEmitter implementation
3
+ * Replaces Node.js 'events' module dependency for client bundles
4
+ */
5
+ export type EventListener = (...args: any[]) => void;
6
+ export declare class SimpleEventEmitter {
7
+ private listeners;
8
+ on(event: string, listener: EventListener): this;
9
+ off(event: string, listener: EventListener): this;
10
+ addListener(event: string, listener: EventListener): this;
11
+ removeListener(event: string, listener: EventListener): this;
12
+ emit(event: string, ...args: any[]): boolean;
13
+ removeAllListeners(event?: string): this;
14
+ }
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Hydrate customer `<widgetic composition-id>` in place.
3
+ * Customer tag is one word: `<widgetic>`. No `<widgetic-widget>`, no render-mode.
4
+ *
5
+ * Copy iframe = raw `<iframe src>` without SDK.
6
+ * Copy web component = SDK + `<widgetic composition-id>` — SDK looks up the
7
+ * published widget.html and mounts it inside the host.
8
+ */
9
+ /**
10
+ * Set on a host whose embed the gateway refused to show on this website (the
11
+ * owner limited it to the websites they listed). Its value is the refusal code.
12
+ * The page is scanned again whenever it changes, and a refused host must not be
13
+ * looked up again each time, so a host that carries it is left alone.
14
+ */
15
+ export declare const REFUSED_HOST_ATTRIBUTE = "data-widgetic-refused";
16
+ export declare function hydratePublishedHost(host: HTMLElement): boolean;
17
+ export declare function hydratePublishedHosts(root?: ParentNode): number;
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Simple Logger Utility
3
+ * Provides consistent logging with debug levels and sensitive data protection
4
+ */
5
+ export declare function setDebugEnabled(enabled: boolean): void;
6
+ type LogLevel = "debug" | "info" | "warn" | "error";
7
+ /**
8
+ * Simple logger class with level-based filtering and sensitive data protection
9
+ */
10
+ declare class Logger {
11
+ private logLevels;
12
+ private currentLevel;
13
+ constructor(level?: LogLevel);
14
+ private shouldLog;
15
+ private formatMessage;
16
+ debug(message: string, ...args: any[]): void;
17
+ info(message: string, ...args: any[]): void;
18
+ warn(message: string, ...args: any[]): void;
19
+ error(message: string, ...args: any[]): void;
20
+ setLevel(level: LogLevel): void;
21
+ setDebug(enabled: boolean): void;
22
+ }
23
+ export declare const logger: Logger;
24
+ export declare const log: {
25
+ debug: (message: string, ...args: any[]) => void;
26
+ info: (message: string, ...args: any[]) => void;
27
+ warn: (message: string, ...args: any[]) => void;
28
+ error: (message: string, ...args: any[]) => void;
29
+ setLevel: (level: LogLevel) => void;
30
+ };
31
+ export {};
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Attribute Parser Utilities
3
+ * Parse widget configuration from HTML elements
4
+ */
5
+ import type { WidgetConfig, TriggerConfig } from "../core/types";
6
+ /**
7
+ * Parse widget configuration from a <widgetic> element
8
+ */
9
+ export declare function parseWidgetConfig(element: HTMLElement): WidgetConfig;
10
+ /**
11
+ * Generate a unique instance ID for a widget element
12
+ */
13
+ export declare function generateInstanceId(compositionId: string): string;
14
+ /**
15
+ * Validate that an element is a valid widget element
16
+ */
17
+ export declare function isValidWidgetElement(element: Element): element is HTMLElement;
18
+ /**
19
+ * Parse the Embed Editor's Advanced Settings into the trigger configuration.
20
+ *
21
+ * Three attributes on their own — `embed-target`, `max-views`, `time-period` —
22
+ * were the editor's biggest silent no-ops, because the code that acts on all
23
+ * three (`TriggerManager`) is only ever constructed when `config.triggers` is
24
+ * set, and nothing set it.
25
+ *
26
+ * Filling this object in was only half of the wire. A `<widgetic composition-id>`
27
+ * tag is hydrated by `hydratePublishedHost`, which never went through
28
+ * `WidgetManager`, so the object had no reader for published embeds until
29
+ * `published-host-display` started building the `TriggerManager` from it.
30
+ *
31
+ * Returns `undefined` for a plain inline embed, and that is deliberate: a
32
+ * `TriggerManager` has nothing to do in site mode, so existing embeds keep the
33
+ * exact object shape they had before this existed.
34
+ *
35
+ * `restrictions` is not an attribute — it is the editor's master switch, and its
36
+ * effect is the *presence* of `max-views`/`time-period`. So the recurrence block
37
+ * is enabled by inference: a limit was configured, therefore it counts.
38
+ */
39
+ export declare function parseTriggerConfig(element: HTMLElement): TriggerConfig | undefined;
@@ -0,0 +1,74 @@
1
+ /**
2
+ * JavaScript Portal Utility
3
+ * Provides Portal functionality similar to design system's Portal.svelte
4
+ * for embedding elements outside their normal DOM hierarchy
5
+ */
6
+ export interface PortalOptions {
7
+ target?: string | HTMLElement;
8
+ className?: string;
9
+ style?: string;
10
+ clickThrough?: boolean;
11
+ zIndex?: number;
12
+ }
13
+ export interface PortalInstance {
14
+ mount(content: HTMLElement): void;
15
+ unmount(): void;
16
+ destroy(): void;
17
+ getContainer(): HTMLElement | null;
18
+ isDestroyed(): boolean;
19
+ }
20
+ /**
21
+ * Portal class for mounting elements outside normal DOM hierarchy
22
+ */
23
+ export declare class Portal implements PortalInstance {
24
+ private host;
25
+ private container;
26
+ private content;
27
+ private destroyed;
28
+ private options;
29
+ constructor(options?: PortalOptions);
30
+ /**
31
+ * Create the portal structure
32
+ */
33
+ private createPortal;
34
+ /**
35
+ * Find existing host or create new one
36
+ */
37
+ private findOrCreateHost;
38
+ /**
39
+ * Mount content into the portal
40
+ */
41
+ mount(content: HTMLElement): void;
42
+ /**
43
+ * Unmount content from portal
44
+ */
45
+ unmount(): void;
46
+ /**
47
+ * Destroy the portal completely
48
+ */
49
+ destroy(): void;
50
+ /**
51
+ * Get the portal container element
52
+ */
53
+ getContainer(): HTMLElement | null;
54
+ /**
55
+ * Check if portal is destroyed
56
+ */
57
+ isDestroyed(): boolean;
58
+ /**
59
+ * Update portal options
60
+ */
61
+ updateOptions(newOptions: Partial<PortalOptions>): void;
62
+ }
63
+ /**
64
+ * Create a new portal instance
65
+ */
66
+ export declare function createPortal(options?: PortalOptions): Portal;
67
+ /**
68
+ * Create a portal specifically for editor overlays
69
+ */
70
+ export declare function createEditorPortal(className?: string): Portal;
71
+ /**
72
+ * Global portal cleanup utility
73
+ */
74
+ export declare function cleanupAllPortals(): void;
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Public composition → published widget.html lookup.
3
+ * No API key.
4
+ *
5
+ * Order:
6
+ * 1. <script data-api-url> / window.WIDGETIC_EMBED_API (local / Render tests)
7
+ * 2. localhost:3000 when the host page is local
8
+ * 3. CDN lookup script (no CORS — works on CodePen)
9
+ * 4. Render gateway, then getApiUrl() / api.widgetic.com (new platform API)
10
+ *
11
+ * api.widgetic.com is the new API host. Legacy REST is widgetic.com/api/v2.
12
+ * Until DNS/proxy for api.widgetic.com points at the new gateway (today it can
13
+ * 301 via old Varnish to widgetic.com), keep CDN + Render as fallbacks.
14
+ *
15
+ * A gateway that answers 403 DOMAIN_NOT_ALLOWED has given its answer: the
16
+ * embed's owner limited it to the websites they listed, and this page is not
17
+ * one of them. The lookup stops there and nothing is mounted. The CDN copy
18
+ * (step 3) stands in for a gateway that cannot be reached, never for one that
19
+ * said no.
20
+ */
21
+ /** The code the gateway puts on the 403 it sends to a website the embed's owner did not list. */
22
+ export declare const EMBED_DOMAIN_REFUSAL_CODE = "DOMAIN_NOT_ALLOWED";
23
+ /**
24
+ * What a widgetic-widget element shows where the embed would have been. Fixed
25
+ * text: nothing the server sent is ever written into the page.
26
+ */
27
+ export declare const EMBED_REFUSED_MESSAGE = "This embed is not authorized to be shown on this website.";
28
+ export type PublicEmbedOverlay = {
29
+ design?: Record<string, string>;
30
+ content?: Record<string, unknown>;
31
+ contentItems?: unknown[];
32
+ };
33
+ export type PublicEmbedPayload = PublicEmbedOverlay & {
34
+ embedUrl: string;
35
+ compositionId?: string;
36
+ };
37
+ /** The gateway's refusal: the owner limited this embed to listed websites and this page is not listed. */
38
+ export type PublishedEmbedRefusal = {
39
+ code: typeof EMBED_DOMAIN_REFUSAL_CODE;
40
+ /** Why the gateway refused (for example that the page was not listed). For the console only. */
41
+ reason?: string;
42
+ };
43
+ /**
44
+ * The three ways a lookup can end. A caller has to say what it does with a
45
+ * refusal: it cannot be mistaken for "not found", which is the case where
46
+ * falling back to another copy is right.
47
+ */
48
+ export type PublishedEmbedLookup = {
49
+ status: "found";
50
+ payload: PublicEmbedPayload;
51
+ } | {
52
+ status: "refused";
53
+ refusal: PublishedEmbedRefusal;
54
+ } | {
55
+ status: "not-found";
56
+ };
57
+ export declare function publicCompositionLookupUrls(compositionId: string): string[];
58
+ export declare function resolvePublishedEmbed(compositionId: string): Promise<PublishedEmbedLookup>;
59
+ export declare function resolvePublishedEmbedUrl(compositionId: string): Promise<string | null>;
60
+ /**
61
+ * Tells the developer, once per composition, why an embed was not shown.
62
+ * It is a console.warn on purpose: the SDK logger prints nothing unless debug
63
+ * is on, and a website that is missing from the owner's list is a setup
64
+ * mistake the person integrating needs to see on the first try.
65
+ */
66
+ export declare function reportRefusedEmbed(compositionId: string, refusal: PublishedEmbedRefusal): void;
67
+ export declare function applyCompositionOverlay(iframe: HTMLIFrameElement, overlay?: PublicEmbedOverlay | null): void;
68
+ export declare function createPublishedIframe(src: string, width: string, height: string, compositionId?: string, overlay?: PublicEmbedOverlay | null): HTMLIFrameElement;
@@ -0,0 +1,61 @@
1
+ /**
2
+ * Display behaviour for hydrated `<widgetic composition-id>` hosts.
3
+ *
4
+ * `hydratePublishedHost` turns the tag into an iframe and, until this module
5
+ * existed, did nothing else. Every other attribute the Embed Editor writes
6
+ * (the device switches, `embed-target`, the event trigger, the view limit, the
7
+ * overlay position and backdrop) was parsed by `parseWidgetConfig` and then read
8
+ * by nothing on this path: the batch renderer that acts on them is only reached
9
+ * by tags that do not hydrate, and `TriggerManager` is only built by
10
+ * `WidgetManager`, which only the A/B testing code calls. So a published embed
11
+ * always rendered inline, whatever its settings said.
12
+ *
13
+ * This is the missing wire. It stays out of `hydrate-published-host.ts` so that
14
+ * file keeps doing one job, and it changes nothing for a plain inline embed.
15
+ */
16
+ import type { TriggerConfig } from "../core/types.js";
17
+ /**
18
+ * Marks a host whose overlay trigger has not been armed yet (`pending`) or has
19
+ * been (`armed`). `markMounted` reads it to leave `display` alone: the overlay
20
+ * decides when the widget appears, so mounting must not reveal it.
21
+ */
22
+ export declare const OVERLAY_HOST_ATTRIBUTE = "data-widgetic-overlay";
23
+ /** Set on a host that this device is switched off for. Nothing is fetched or mounted for it. */
24
+ export declare const DEVICE_RESTRICTED_ATTRIBUTE = "data-device-restricted";
25
+ export interface PublishedHostDisplayPlan {
26
+ /** True when this device is switched off: the host is hidden and must not be mounted */
27
+ suppressed: boolean;
28
+ /** Trigger configuration to arm once the iframe is mounted; absent for a plain inline embed */
29
+ triggers?: TriggerConfig;
30
+ }
31
+ /**
32
+ * Decide, before anything is fetched, what this host is allowed to become on
33
+ * this device.
34
+ *
35
+ * - A device the embed switched off is hidden at once and never fetched.
36
+ * - An overlay embed is hidden from the very first moment, so the inline copy
37
+ * never flashes on the page before the overlay takes over.
38
+ * - Anything else is left exactly as it was.
39
+ */
40
+ export declare function planPublishedHostDisplay(host: HTMLElement): PublishedHostDisplayPlan;
41
+ /**
42
+ * Hand a host to a `TriggerManager`.
43
+ *
44
+ * Called once the composition has been found, not before: an overlay whose
45
+ * composition could not be found must stay invisible instead of opening an
46
+ * empty modal, and a delay trigger should count from the moment the widget can
47
+ * be shown.
48
+ *
49
+ * `mountWhenShown` is for an overlay embed, and builds the widget when the
50
+ * overlay opens instead of before. Moving an iframe reloads it, so a widget
51
+ * mounted in its place on the page and moved into the overlay later would load
52
+ * twice, and a second time in front of the visitor. Built inside the overlay it
53
+ * loads once, and an overlay that never opens (its view limit is used up, or
54
+ * its trigger never fires) never loads at all.
55
+ *
56
+ * The trigger code is loaded on demand, so a page with only plain embeds never
57
+ * pays for it. If that load fails, the host stays hidden: an overlay that
58
+ * quietly turned into an inline block in the middle of the page would be worse
59
+ * than one that did not appear.
60
+ */
61
+ export declare function armPublishedHostTriggers(host: HTMLElement, triggers: TriggerConfig, mountWhenShown?: () => void): void;