SDK Overview

The Spotlight SDK is a lightweight JavaScript library that renders in-app guidance -- tours, spotlights, tooltips, hotspots, modals, banners, and checklists -- directly on your website or application. It is designed to be invisible to your users until it has something to show, and invisible to your codebase at all times.

Key Capabilities

Shadow DOM Isolation

All Spotlight UI renders inside a single Shadow DOM host element attached to document.body. This provides complete bidirectional CSS isolation:

• Outward isolation -- Spotlight's styles never leak into your page. Adding a tooltip will not change your button colours, font sizes, or layout.
• Inward isolation -- Your page's styles never break Spotlight's UI. A global * { box-sizing: content-box; } or div { margin: 20px; } reset will not distort a Spotlight component.

The Shadow DOM host uses :host { all: initial; } to reset all inherited CSS properties, then re-declares only the properties Spotlight needs. Theming is handled via --spot-* CSS custom properties, which are the one CSS mechanism that intentionally pierces the Shadow DOM boundary.

<!-- What Spotlight adds to your page -->
<div id="spotlight-host"
     style="position:fixed;top:0;left:0;width:0;height:0;
            overflow:visible;z-index:999999;pointer-events:none;">
  <!-- #shadow-root (open) -->
  <!--   <style> ... all SDK styles ... </style> -->
  <!--   <div class="spot-container"> -->
  <!--     ... tooltips, modals, banners, etc. ... -->
  <!--   </div> -->
</div>

The host element takes up zero layout space, does not intercept clicks on your page, and renders its children above everything via z-index. Your page never knows it is there.

TIP

The Shadow DOM root is open mode, which means document.getElementById('spotlight-host').shadowRoot is technically accessible to your JavaScript. However, the SDK's internal DOM structure is not a public API and may change without notice between versions.

Bundle Size

The SDK targets under 20KB gzipped for the core bundle (JavaScript + CSS + HTML sanitiser + positioning library). This is a hard constraint enforced by a CI gate -- every build that exceeds the budget fails.

Component	Approximate Size
Core SDK (init, events, theming, targeting)	~10KB gzip
Positioning engine (@floating-ui/dom)	~3KB gzip
HTML sanitiser	~1KB gzip
Base styles (inlined in Shadow DOM)	~3KB gzip
Total core	~17KB gzip

Content type modules (tours, checklists, etc.) are loaded separately via dynamic import() based on which modules your tenant has enabled. A tenant with 4 modules enabled typically loads 40-78KB total.

WARNING

Admin overlay code (visual tour builder, element selector, theme editor, analytics panel, preview mode) is loaded via dynamic import() only when the current user has admin permissions. Non-admin users never download admin code, saving approximately 15KB gzipped.

Installation

Add a single script tag to your page. No build step, no framework coupling, no package manager required.

Script Tag

<script
  src="https://cdn.spotlight.example.com/sdk/v1/spotlight.js"
  data-api-key="spot_live_your_api_key_here"
  async
></script>

Script Tag + Manual Init

<script src="https://cdn.spotlight.example.com/sdk/v1/spotlight.js" async></script>
<script>
  window.Spotlight.init({
    apiKey: 'spot_live_your_api_key_here',
    userId: getCurrentUserId(),
  });
</script>

ES Module

import { Spotlight } from '@spotlight/sdk';

Spotlight.init({
  apiKey: 'spot_live_your_api_key_here',
  userId: getCurrentUserId(),
});

SPA Support

The SDK is designed for single-page applications from the ground up:

• MutationObserver on document.body detects DOM changes and URL changes caused by SPA navigation (pushState, replaceState, popstate).
• On navigation, the SDK re-evaluates which content should display on the new page.
• All event listeners, IntersectionObserver instances, and setTimeout handles from the previous page are cleaned up via TriggerEngine.destroy() to prevent memory leaks and ghost triggers.
• Element targeting uses a combination of MutationObserver and polling to wait for elements that render asynchronously after route changes (common in React, Vue, and Angular applications).

// No extra setup needed for SPAs.
// The SDK detects navigation automatically.
Spotlight.init({
  apiKey: 'spot_live_your_api_key_here',
  userId: getCurrentUserId(),
});

// If you need to manually notify the SDK of a navigation:
Spotlight.refresh();

Content Types

The SDK supports seven content types, each loaded as an independent module:

Content Type	Description	Element-Targeted
Tours	Multi-step walkthroughs with progress tracking	Yes
Spotlights	Single-element highlight with callout	Yes
Tooltips	Contextual help attached to an element	Yes
Hotspots	Pulsing beacon or help icon on an element	Yes
Modals	Centred overlay dialog	No
Banners	Top or bottom bar notification	No
Checklists	Onboarding task list with progress	No

Browser Support

The SDK targets modern evergreen browsers:

Browser	Minimum Version
Chrome	63+
Firefox	63+
Safari	13.1+
Edge	79+

Shadow DOM v1, CSS Custom Properties, MutationObserver, IntersectionObserver, and dynamic import() are required. No polyfills are included.

Architecture Summary

Your Application
├── Your DOM ...
│
└── <div id="spotlight-host">
      └── #shadow-root (open)
            ├── <style> SDK styles + theme variables </style>
            └── <div class="spot-container">
                  ├── TriggerEngine     -- evaluates when to show content
                  ├── ThemeEngine       -- applies --spot-* CSS custom properties
                  ├── TargetingEngine   -- finds and attaches to DOM elements
                  ├── EventPipeline     -- tracks analytics and fires callbacks
                  └── ModuleLoader      -- dynamically loads enabled content types

Next Steps

• Initialisation Options -- Full init() configuration reference
• Public API Methods -- start(), stop(), destroy(), on(), track()
• Events -- Event hooks for reacting to SDK lifecycle
• Theming -- CSS custom properties, dark mode, theme API