fix(theme): fix theme leaks, race conditions, and expose public theme API

Author: Parvin Mehrabani

docs/theme-usage.md

@@ -12,6 +12,7 @@ The IntroJS theme system allows you to easily customize the look and feel of you
 - ✅ **Custom Themes** - Load any CSS file as a theme
 - ✅ **Theme Registration** - Register custom themes for easy reuse
 - ✅ **Tour Options Integration** - Set theme directly in tour options
+- ✅ **Live Theme Switching** - Change the theme of a running tour with `tour.setTheme()`
 
 ## Quick Start
 
@@ -23,22 +24,22 @@ The simplest way to use themes is by setting the `theme` option when creating a
 import introJs from 'intro.js';
 
 // Use dark theme
-introJs().setOptions({
+introJs.tour().setOptions({
   theme: 'dark'
 }).start();
 
 // Use light theme
-introJs().setOptions({
+introJs.tour().setOptions({
   theme: 'light'
 }).start();
 
 // Use system preference (default)
-introJs().setOptions({
+introJs.tour().setOptions({
   theme: 'auto'
 }).start();
 
 // Use any pre-registered theme
-introJs().setOptions({
+introJs.tour().setOptions({
   theme: 'modern'
 }).start();
 ```
@@ -51,13 +52,13 @@ You can load a custom CSS file by providing both `theme` and `themePath` options
 import introJs from 'intro.js';
 
 // Load a custom theme from a CSS file
-introJs().setOptions({
+introJs.tour().setOptions({
   theme: 'ocean',
   themePath: 'path/to/themes/introjs-ocean.css'
 }).start();
 
 // Load from CDN
-introJs().setOptions({
+introJs.tour().setOptions({
   theme: 'custom',
   themePath: 'https://cdn.example.com/intro-custom-theme.css'
 }).start();
@@ -69,79 +70,79 @@ The following themes are available out of the box:
 
 | Theme Name | Description | CSS Path |
 |------------|-------------|----------|
-| `light` | Light theme (default style) | `themes/introjs-light.css` |
-| `dark` | Dark theme | `themes/introjs-dark.css` |
-| `auto` | System preference (switches automatically) | N/A (uses classes only) |
+| `light` | Light theme (default style) | N/A - uses CSS custom properties, no file to load |
+| `dark` | Dark theme | N/A - uses CSS custom properties, no file to load |
+| `auto` | Follows the system preference, switches automatically | N/A - uses CSS custom properties, no file to load |
 | `modern` | Modern theme | `themes/introjs-modern.css` |
 | `flattener` | Flat design theme | `themes/introjs-flattener.css` |
 | `nassim` | Nassim theme | `themes/introjs-nassim.css` |
 | `nazanin` | Nazanin theme (RTL support) | `themes/introjs-nazanin.css` |
 | `royal` | Royal theme | `themes/introjs-royal.css` |
 
+> Note: `light`, `dark` and `auto` are implemented purely with CSS classes/custom properties on the tour's root element, so no extra network request happens when you use them. The other themes are loaded on demand from the CSS file shown above.
+
 ## Advanced Usage
 
 ### 1. Registering Custom Themes
 
 You can register custom themes globally so they can be used by name:
 
 ```javascript
-import { registerTheme, registerThemes } from 'intro.js/theme';
 import introJs from 'intro.js';
 
 // Register a single theme
-registerTheme('ocean', 'themes/introjs-ocean.css');
+introJs.registerTheme('ocean', 'themes/introjs-ocean.css');
 
 // Now you can use it by name
-introJs().setOptions({
+introJs.tour().setOptions({
   theme: 'ocean'
 }).start();
 
 // Register multiple themes at once
-registerThemes([
+introJs.registerThemes([
   { name: 'sunset', cssPath: 'themes/introjs-sunset.css' },
   { name: 'forest', cssPath: 'themes/introjs-forest.css' },
   { name: 'corporate', cssPath: 'themes/introjs-corporate.css' }
 ]);
 ```
 
-### 2. Using Theme API Directly
+### 2. Changing the Theme of a Running Tour
 
-For more control, you can use the theme API directly:
+Every `Tour` instance exposes `setTheme()`/`getTheme()` so you can react to in-app theme toggles without restarting the tour:
 
 ```javascript
-import { applyTheme, getTheme } from 'intro.js/theme';
+import introJs from 'intro.js';
 
-// Apply a theme to a specific root element
-const root = document.getElementById('my-tour-container');
-applyTheme({ 
-  root: root, 
-  theme: 'dark' 
-});
+const tour = introJs.tour().setOptions({ theme: 'light' });
+await tour.start();
 
-// Get current theme instance
-const theme = getTheme();
-console.log(theme.currentTheme); // 'dark'
-console.log(theme.value); // 'dark' or 'light'
+console.log(tour.getTheme()); // 'light'
 
-// Change theme dynamically
-await theme.setTheme('light');
+// Switch the running tour to dark mode
+await tour.setTheme('dark');
+console.log(tour.getTheme()); // 'dark'
 
-// Clean up when done
-theme.destroy();
+// Switch to a custom CSS theme
+await tour.setTheme('ocean', 'themes/introjs-ocean.css');
 ```
 
+Calling `setTheme()` before the tour has started simply stores the choice; it's applied the next time `start()` runs.
+
 ### 3. Getting Theme Information
 
 ```javascript
-import { getThemePath, getRegisteredThemes } from 'intro.js/theme';
+import introJs from 'intro.js';
 
-// Get CSS path for a specific theme
-const darkPath = getThemePath('dark');
-console.log(darkPath); // 'themes/introjs-dark.css'
+// Get CSS path for a registered theme
+const modernPath = introJs.getThemePath('modern');
+console.log(modernPath); // 'themes/introjs-modern.css'
+
+// Built-in themes (light/dark/auto) are not file-based, so this is undefined
+console.log(introJs.getThemePath('dark')); // undefined
 
 // Get all registered theme names
-const allThemes = getRegisteredThemes();
-console.log(allThemes); // ['dark', 'light', 'modern', ...]
+const allThemes = introJs.getRegisteredThemes();
+console.log(allThemes); // ['modern', 'flattener', 'nassim', 'nazanin', 'royal', ...]
 ```
 
 ## Complete Examples
@@ -151,7 +152,7 @@ console.log(allThemes); // ['dark', 'light', 'modern', ...]
 ```javascript
 import introJs from 'intro.js';
 
-introJs().setOptions({
+introJs.tour().setOptions({
   steps: [
     {
       element: '#step1',
@@ -170,13 +171,12 @@ introJs().setOptions({
 
 ```javascript
 import introJs from 'intro.js';
-import { registerTheme } from 'intro.js/theme';
 
 // Register your custom theme
-registerTheme('mycompany', 'assets/css/intro-mycompany-theme.css');
+introJs.registerTheme('mycompany', 'assets/css/intro-mycompany-theme.css');
 
 // Use it in your tour
-introJs().setOptions({
+introJs.tour().setOptions({
   steps: [
     {
       element: '#welcome',
@@ -193,8 +193,9 @@ introJs().setOptions({
 import introJs from 'intro.js';
 
 // This tour will automatically use dark theme in dark mode
-// and light theme in light mode
-introJs().setOptions({
+// and light theme in light mode, and keeps reacting if the
+// user's OS theme changes while the tour is open
+introJs.tour().setOptions({
   steps: [
     {
       intro: 'This tour adapts to your system theme!'
@@ -209,7 +210,7 @@ introJs().setOptions({
 ```javascript
 import introJs from 'intro.js';
 
-const tour = introJs().setOptions({
+const tour = introJs.tour().setOptions({
   steps: [
     {
       intro: 'Starting with light theme'
@@ -221,15 +222,10 @@ const tour = introJs().setOptions({
   theme: 'light'
 });
 
-tour.onBeforeChange(function(targetElement) {
+tour.onBeforeChange(async function (targetElement) {
   if (this.getCurrentStep() === 1) {
-    // Switch to dark theme on step 2
-    this.setOption('theme', 'dark');
-    // Re-initialize theme
-    this.exit().then(() => {
-      this.setCurrentStep(1);
-      this.start();
-    });
+    // Switch the already-running tour to dark theme on step 2
+    await this.setTheme('dark');
   }
 });
 
@@ -285,7 +281,7 @@ Then use it:
 ```javascript
 import introJs from 'intro.js';
 
-introJs().setOptions({
+introJs.tour().setOptions({
   theme: 'ocean',
   themePath: 'themes/introjs-ocean.css'
 }).start();
@@ -296,17 +292,16 @@ introJs().setOptions({
 The theme system is fully typed:
 
 ```typescript
-import introJs from 'intro.js';
-import { ThemeType, registerTheme, applyTheme } from 'intro.js/theme';
+import introJs, { type ThemeType } from 'intro.js';
 
 // Theme types
 const theme: ThemeType = 'dark'; // 'light' | 'dark' | 'auto' | string
 
 // Register theme with types
-registerTheme('custom', 'path/to/custom.css');
+introJs.registerTheme('custom', 'path/to/custom.css');
 
 // Use in tour with types
-introJs().setOptions({
+introJs.tour().setOptions({
   theme: 'dark',
   themePath: 'path/to/theme.css' // optional
 }).start();
@@ -316,15 +311,15 @@ introJs().setOptions({
 
 1. **Use `auto` for Better UX**: Let users' system preferences determine the theme
    ```javascript
-   introJs().setOptions({ theme: 'auto' }).start();
+   introJs.tour().setOptions({ theme: 'auto' }).start();
    ```
 
 2. **Register Themes Early**: Register all custom themes at app initialization
    ```javascript
    // app-init.js
-   import { registerThemes } from 'intro.js/theme';
-   
-   registerThemes([
+   import introJs from 'intro.js';
+
+   introJs.registerThemes([
      { name: 'brand', cssPath: 'themes/brand.css' },
      { name: 'seasonal', cssPath: 'themes/seasonal.css' }
    ]);
@@ -353,7 +348,7 @@ introJs().setOptions({
 **Problem**: Theme is registered but not applying
 
 **Solutions**:
-- Make sure you call `registerTheme()` before starting the tour
+- Make sure you call `introJs.registerTheme()` before starting the tour
 - Verify the theme name matches exactly
 - Check that the CSS selectors in your theme file are correct
 - Ensure no other CSS is overriding your theme styles
@@ -363,9 +358,9 @@ introJs().setOptions({
 **Problem**: Multiple theme CSS files are being loaded
 
 **Solutions**:
-- The system automatically prevents duplicate loading
+- The system automatically prevents duplicate loading of the same CSS file
+- When you call `tour.setTheme()` with a different custom theme, the previous theme's `<link>` is removed automatically
 - Use the same theme name consistently
-- Call `theme.destroy()` when switching themes programmatically
 
 ## API Reference
 
@@ -376,11 +371,18 @@ introJs().setOptions({
 | `theme` | `ThemeType` | `'auto'` | Theme name ('light', 'dark', 'auto', or custom) |
 | `themePath` | `string` | `undefined` | Path to custom CSS file |
 
-### Theme Functions
+### Tour Instance Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `tour.setTheme(theme, themePath?)` | `theme: ThemeType, themePath?: string` | `Promise<Tour>` | Change the theme; applies immediately if the tour is running |
+| `tour.getTheme()` | - | `'light' \| 'dark' \| undefined` | The currently resolved theme, or `undefined` before the tour starts |
+
+### `introJs` Theme Functions
 
 | Function | Parameters | Returns | Description |
 |----------|------------|---------|-------------|
-| `registerTheme(name, cssPath)` | `name: string, cssPath: string` | `void` | Register a custom theme |
-| `registerThemes(themes)` | `themes: ThemeRegistration[]` | `void` | Register multiple themes |
-| `getThemePath(name)` | `name: string` | `string \| undefined` | Get CSS path for a theme |
-| `getRegisteredThemes()` | -
+| `introJs.registerTheme(name, cssPath)` | `name: string, cssPath: string` | `void` | Register a custom theme |
+| `introJs.registerThemes(themes)` | `themes: ThemeRegistration[]` | `void` | Register multiple themes |
+| `introJs.getThemePath(name)` | `name: string` | `string \| undefined` | Get the CSS path for a theme (built-in themes return `undefined`) |
+| `introJs.getRegisteredThemes()` | - | `string[]` | List the names of all registered themes |

src/index.test.ts

@@ -26,4 +26,15 @@ describe("index", () => {
     // Assert
     expect(hintInstance).toBeInstanceOf(Hint);
   });
+
+  it("should expose theme registration and lookup helpers", () => {
+    introJs.registerTheme("sunset", "/themes/sunset.css");
+    introJs.registerThemes([{ name: "forest", cssPath: "/themes/forest.css" }]);
+
+    expect(introJs.getThemePath("sunset")).toBe("/themes/sunset.css");
+    expect(introJs.getThemePath("forest")).toBe("/themes/forest.css");
+    expect(introJs.getRegisteredThemes()).toEqual(
+      expect.arrayContaining(["sunset", "forest"])
+    );
+  });
 });

src/index.ts

@@ -1,6 +1,13 @@
 import { version } from "../package.json";
 import { Hint } from "./packages/hint";
 import { Tour } from "./packages/tour";
+import {
+  registerTheme,
+  registerThemes,
+  getThemePath,
+  getRegisteredThemes,
+} from "./packages/tour/theme";
+export type { ThemeType, ThemeRegistration } from "./packages/tour/theme";
 
 class LegacyIntroJs extends Tour {
   /**
@@ -63,4 +70,24 @@ introJs.hint = (elementOrSelector?: string | HTMLElement) =>
  */
 introJs.version = version;
 
+/**
+ * Register a custom theme so it can be referenced by name in the `theme` tour option
+ */
+introJs.registerTheme = registerTheme;
+
+/**
+ * Register multiple custom themes at once
+ */
+introJs.registerThemes = registerThemes;
+
+/**
+ * Get the CSS path registered for a given theme name, if any
+ */
+introJs.getThemePath = getThemePath;
+
+/**
+ * List the names of all currently registered themes
+ */
+introJs.getRegisteredThemes = getRegisteredThemes;
+
 export default introJs;