torchlit 0.1.0

package/dist/tour-service-BKz7eeWb.js

@@ -0,0 +1,204 @@
+function deepQuery(selector, root = document.body) {
+  const found = root.querySelector(selector);
+  if (found) return found;
+  const children = root.querySelectorAll("*");
+  for (const el of children) {
+    if (el.shadowRoot) {
+      const shadowResult = deepQuery(selector, el.shadowRoot);
+      if (shadowResult) return shadowResult;
+    }
+  }
+  return null;
+}
+const DEFAULT_STORAGE_KEY = "torchlit-state";
+const DEFAULT_TARGET_ATTR = "data-tour-id";
+const DEFAULT_SPOTLIGHT_PADDING = 10;
+const noopStorage = {
+  getItem: () => null,
+  setItem: () => {
+  }
+};
+function defaultStorage() {
+  try {
+    const test = "__torchlit_test__";
+    localStorage.setItem(test, test);
+    localStorage.removeItem(test);
+    return localStorage;
+  } catch {
+    return noopStorage;
+  }
+}
+class TourService {
+  constructor(config = {}) {
+    this.tours = /* @__PURE__ */ new Map();
+    this.activeTourId = null;
+    this.currentStepIndex = 0;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.storageKey = config.storageKey ?? DEFAULT_STORAGE_KEY;
+    this.storage = config.storage ?? defaultStorage();
+    this.targetAttribute = config.targetAttribute ?? DEFAULT_TARGET_ATTR;
+    this.spotlightPadding = config.spotlightPadding ?? DEFAULT_SPOTLIGHT_PADDING;
+    this.persistedState = this.loadState();
+  }
+  /* ── Persistence ──────────────────────────────── */
+  loadState() {
+    try {
+      const stored = this.storage.getItem(this.storageKey);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        return {
+          completed: Array.isArray(parsed.completed) ? parsed.completed : [],
+          dismissed: Array.isArray(parsed.dismissed) ? parsed.dismissed : []
+        };
+      }
+    } catch (error) {
+      console.error("[torchlit] Failed to load state:", error);
+    }
+    return { completed: [], dismissed: [] };
+  }
+  saveState() {
+    try {
+      this.storage.setItem(this.storageKey, JSON.stringify(this.persistedState));
+    } catch (error) {
+      console.error("[torchlit] Failed to save state:", error);
+    }
+  }
+  register(input) {
+    if (Array.isArray(input)) {
+      input.forEach((t) => this.tours.set(t.id, t));
+    } else {
+      this.tours.set(input.id, input);
+    }
+  }
+  /* ── Queries ──────────────────────────────────── */
+  /** Return a registered tour by ID. */
+  getTour(id) {
+    return this.tours.get(id);
+  }
+  /** Return all registered tours. */
+  getAvailableTours() {
+    return Array.from(this.tours.values());
+  }
+  /**
+   * Whether a `first-visit` tour should auto-start.
+   * Returns `false` if the tour is manual, already completed, or dismissed.
+   */
+  shouldAutoStart(tourId) {
+    const tour = this.tours.get(tourId);
+    if (!tour || tour.trigger !== "first-visit") return false;
+    return !this.persistedState.completed.includes(tourId) && !this.persistedState.dismissed.includes(tourId);
+  }
+  /** Whether any tour is currently active. */
+  isActive() {
+    return this.activeTourId !== null;
+  }
+  /* ── Tour control ─────────────────────────────── */
+  /** Start a tour by ID. No-op if the tour doesn't exist or has no steps. */
+  start(tourId) {
+    const tour = this.tours.get(tourId);
+    if (!tour || tour.steps.length === 0) return;
+    this.activeTourId = tourId;
+    this.currentStepIndex = 0;
+    this.notify();
+  }
+  /** Advance to the next step, or complete the tour if on the last step. */
+  nextStep() {
+    if (!this.activeTourId) return;
+    const tour = this.tours.get(this.activeTourId);
+    if (this.currentStepIndex < tour.steps.length - 1) {
+      this.currentStepIndex++;
+      this.notify();
+    } else {
+      this.completeTour();
+    }
+  }
+  /** Go back to the previous step. No-op if already on step 0. */
+  prevStep() {
+    if (!this.activeTourId) return;
+    if (this.currentStepIndex > 0) {
+      this.currentStepIndex--;
+      this.notify();
+    }
+  }
+  /** Skip / dismiss the current tour. Persists "dismissed" state. */
+  skipTour() {
+    if (!this.activeTourId) return;
+    const id = this.activeTourId;
+    const tour = this.tours.get(id);
+    if (!this.persistedState.dismissed.includes(id)) {
+      this.persistedState.dismissed.push(id);
+      this.saveState();
+    }
+    this.activeTourId = null;
+    this.currentStepIndex = 0;
+    this.notify();
+    tour?.onSkip?.();
+  }
+  completeTour() {
+    if (!this.activeTourId) return;
+    const id = this.activeTourId;
+    const tour = this.tours.get(id);
+    if (!this.persistedState.completed.includes(id)) {
+      this.persistedState.completed.push(id);
+      this.saveState();
+    }
+    this.activeTourId = null;
+    this.currentStepIndex = 0;
+    this.notify();
+    tour?.onComplete?.();
+  }
+  /* ── Snapshot (current state for overlay) ─────── */
+  /** Return a snapshot of the current tour state, or `null` if inactive. */
+  getSnapshot() {
+    if (!this.activeTourId) return null;
+    const tour = this.tours.get(this.activeTourId);
+    if (!tour) return null;
+    const step = tour.steps[this.currentStepIndex];
+    if (!step) return null;
+    const targetElement = this.findTarget(step.target);
+    const targetRect = targetElement?.getBoundingClientRect() ?? null;
+    return {
+      tourId: this.activeTourId,
+      tourName: tour.name,
+      step,
+      stepIndex: this.currentStepIndex,
+      totalSteps: tour.steps.length,
+      targetRect,
+      targetElement
+    };
+  }
+  /* ── Shadow DOM target resolution ─────────────── */
+  /** Find a DOM element by its `data-tour-id` (or custom attribute). */
+  findTarget(targetId) {
+    return deepQuery(`[${this.targetAttribute}="${targetId}"]`, document.body);
+  }
+  /* ── Observer pattern ─────────────────────────── */
+  /** Subscribe to snapshot changes. Returns an unsubscribe function. */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  notify() {
+    const snapshot = this.getSnapshot();
+    this.listeners.forEach((listener) => listener(snapshot));
+  }
+  /* ── Reset (for testing & demos) ──────────────── */
+  /** Clear all persisted state and stop any active tour. */
+  resetAll() {
+    this.persistedState = { completed: [], dismissed: [] };
+    this.activeTourId = null;
+    this.currentStepIndex = 0;
+    this.tours.clear();
+    this.saveState();
+    this.notify();
+  }
+}
+function createTourService(config) {
+  return new TourService(config);
+}
+export {
+  TourService as T,
+  createTourService as c,
+  deepQuery as d
+};
+//# sourceMappingURL=tour-service-BKz7eeWb.js.map

package/dist/tour-service-BKz7eeWb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-service-BKz7eeWb.js","sources":["../src/utils/deep-query.ts","../src/tour-service.ts"],"sourcesContent":["/**\n * Recursively search the DOM — including shadow roots — for an element\n * matching the given CSS selector.\n *\n * This is the key differentiator vs. libraries like Shepherd.js or Intro.js\n * which cannot pierce shadow DOM boundaries.\n *\n * @param selector  A valid CSS selector string.\n * @param root      The root element (or Document) to start searching from.\n *                  Defaults to `document.body`.\n * @returns         The first matching `Element`, or `null`.\n *\n * @example\n * ```ts\n * import { deepQuery } from 'torchlit';\n *\n * const el = deepQuery('[data-tour-id=\"sidebar-nav\"]');\n * ```\n */\nexport function deepQuery(\n  selector: string,\n  root: Element | Document = document.body,\n): Element | null {\n  // Try light DOM first (fast path)\n  const found = root.querySelector(selector);\n  if (found) return found;\n\n  // Walk children that expose a shadowRoot\n  const children = root.querySelectorAll('*');\n  for (const el of children) {\n    if (el.shadowRoot) {\n      const shadowResult = deepQuery(selector, el.shadowRoot as unknown as Document);\n      if (shadowResult) return shadowResult;\n    }\n  }\n\n  return null;\n}\n","import { deepQuery } from './utils/deep-query.js';\nimport type {\n  TourConfig,\n  TourDefinition,\n  TourListener,\n  TourSnapshot,\n  TourState,\n  StorageAdapter,\n} from './types.js';\n\n// ── Defaults ─────────────────────────────────────────────────────────────────\n\nconst DEFAULT_STORAGE_KEY = 'torchlit-state';\nconst DEFAULT_TARGET_ATTR = 'data-tour-id';\nconst DEFAULT_SPOTLIGHT_PADDING = 10;\n\n/** A no-op storage adapter for SSR / environments without localStorage. */\nconst noopStorage: StorageAdapter = {\n  getItem: () => null,\n  setItem: () => {},\n};\n\n/** Safely wrap localStorage — falls back to noop if unavailable. */\nfunction defaultStorage(): StorageAdapter {\n  try {\n    // Guard against SSR or restricted environments\n    const test = '__torchlit_test__';\n    localStorage.setItem(test, test);\n    localStorage.removeItem(test);\n    return localStorage;\n  } catch {\n    return noopStorage;\n  }\n}\n\n// ── TourService ──────────────────────────────────────────────────────────────\n\nexport class TourService {\n  private tours: Map<string, TourDefinition> = new Map();\n  private persistedState: TourState;\n  private activeTourId: string | null = null;\n  private currentStepIndex = 0;\n  private listeners: Set<TourListener> = new Set();\n\n  // Resolved config\n  private readonly storageKey: string;\n  private readonly storage: StorageAdapter;\n  private readonly targetAttribute: string;\n  readonly spotlightPadding: number;\n\n  constructor(config: TourConfig = {}) {\n    this.storageKey = config.storageKey ?? DEFAULT_STORAGE_KEY;\n    this.storage = config.storage ?? defaultStorage();\n    this.targetAttribute = config.targetAttribute ?? DEFAULT_TARGET_ATTR;\n    this.spotlightPadding = config.spotlightPadding ?? DEFAULT_SPOTLIGHT_PADDING;\n    this.persistedState = this.loadState();\n  }\n\n  /* ── Persistence ──────────────────────────────── */\n\n  private loadState(): TourState {\n    try {\n      const stored = this.storage.getItem(this.storageKey);\n      if (stored) {\n        const parsed = JSON.parse(stored);\n        return {\n          completed: Array.isArray(parsed.completed) ? parsed.completed : [],\n          dismissed: Array.isArray(parsed.dismissed) ? parsed.dismissed : [],\n        };\n      }\n    } catch (error) {\n      console.error('[torchlit] Failed to load state:', error);\n    }\n    return { completed: [], dismissed: [] };\n  }\n\n  private saveState(): void {\n    try {\n      this.storage.setItem(this.storageKey, JSON.stringify(this.persistedState));\n    } catch (error) {\n      console.error('[torchlit] Failed to save state:', error);\n    }\n  }\n\n  /* ── Registration ─────────────────────────────── */\n\n  /** Register a single tour definition. */\n  register(tours: TourDefinition[]): void;\n  register(tour: TourDefinition): void;\n  register(input: TourDefinition | TourDefinition[]): void {\n    if (Array.isArray(input)) {\n      input.forEach(t => this.tours.set(t.id, t));\n    } else {\n      this.tours.set(input.id, input);\n    }\n  }\n\n  /* ── Queries ──────────────────────────────────── */\n\n  /** Return a registered tour by ID. */\n  getTour(id: string): TourDefinition | undefined {\n    return this.tours.get(id);\n  }\n\n  /** Return all registered tours. */\n  getAvailableTours(): TourDefinition[] {\n    return Array.from(this.tours.values());\n  }\n\n  /**\n   * Whether a `first-visit` tour should auto-start.\n   * Returns `false` if the tour is manual, already completed, or dismissed.\n   */\n  shouldAutoStart(tourId: string): boolean {\n    const tour = this.tours.get(tourId);\n    if (!tour || tour.trigger !== 'first-visit') return false;\n    return (\n      !this.persistedState.completed.includes(tourId) &&\n      !this.persistedState.dismissed.includes(tourId)\n    );\n  }\n\n  /** Whether any tour is currently active. */\n  isActive(): boolean {\n    return this.activeTourId !== null;\n  }\n\n  /* ── Tour control ─────────────────────────────── */\n\n  /** Start a tour by ID. No-op if the tour doesn't exist or has no steps. */\n  start(tourId: string): void {\n    const tour = this.tours.get(tourId);\n    if (!tour || tour.steps.length === 0) return;\n\n    this.activeTourId = tourId;\n    this.currentStepIndex = 0;\n    this.notify();\n  }\n\n  /** Advance to the next step, or complete the tour if on the last step. */\n  nextStep(): void {\n    if (!this.activeTourId) return;\n    const tour = this.tours.get(this.activeTourId)!;\n\n    if (this.currentStepIndex < tour.steps.length - 1) {\n      this.currentStepIndex++;\n      this.notify();\n    } else {\n      this.completeTour();\n    }\n  }\n\n  /** Go back to the previous step. No-op if already on step 0. */\n  prevStep(): void {\n    if (!this.activeTourId) return;\n    if (this.currentStepIndex > 0) {\n      this.currentStepIndex--;\n      this.notify();\n    }\n  }\n\n  /** Skip / dismiss the current tour. Persists \"dismissed\" state. */\n  skipTour(): void {\n    if (!this.activeTourId) return;\n    const id = this.activeTourId;\n    const tour = this.tours.get(id);\n\n    if (!this.persistedState.dismissed.includes(id)) {\n      this.persistedState.dismissed.push(id);\n      this.saveState();\n    }\n\n    this.activeTourId = null;\n    this.currentStepIndex = 0;\n    this.notify();\n\n    tour?.onSkip?.();\n  }\n\n  private completeTour(): void {\n    if (!this.activeTourId) return;\n    const id = this.activeTourId;\n    const tour = this.tours.get(id);\n\n    if (!this.persistedState.completed.includes(id)) {\n      this.persistedState.completed.push(id);\n      this.saveState();\n    }\n\n    this.activeTourId = null;\n    this.currentStepIndex = 0;\n    this.notify();\n\n    tour?.onComplete?.();\n  }\n\n  /* ── Snapshot (current state for overlay) ─────── */\n\n  /** Return a snapshot of the current tour state, or `null` if inactive. */\n  getSnapshot(): TourSnapshot | null {\n    if (!this.activeTourId) return null;\n    const tour = this.tours.get(this.activeTourId);\n    if (!tour) return null;\n\n    const step = tour.steps[this.currentStepIndex];\n    if (!step) return null;\n\n    const targetElement = this.findTarget(step.target);\n    const targetRect = targetElement?.getBoundingClientRect() ?? null;\n\n    return {\n      tourId: this.activeTourId,\n      tourName: tour.name,\n      step,\n      stepIndex: this.currentStepIndex,\n      totalSteps: tour.steps.length,\n      targetRect,\n      targetElement,\n    };\n  }\n\n  /* ── Shadow DOM target resolution ─────────────── */\n\n  /** Find a DOM element by its `data-tour-id` (or custom attribute). */\n  findTarget(targetId: string): Element | null {\n    return deepQuery(`[${this.targetAttribute}=\"${targetId}\"]`, document.body);\n  }\n\n  /* ── Observer pattern ─────────────────────────── */\n\n  /** Subscribe to snapshot changes. Returns an unsubscribe function. */\n  subscribe(listener: TourListener): () => void {\n    this.listeners.add(listener);\n    return () => this.listeners.delete(listener);\n  }\n\n  private notify(): void {\n    const snapshot = this.getSnapshot();\n    this.listeners.forEach(listener => listener(snapshot));\n  }\n\n  /* ── Reset (for testing & demos) ──────────────── */\n\n  /** Clear all persisted state and stop any active tour. */\n  resetAll(): void {\n    this.persistedState = { completed: [], dismissed: [] };\n    this.activeTourId = null;\n    this.currentStepIndex = 0;\n    this.tours.clear();\n    this.saveState();\n    this.notify();\n  }\n}\n\n// ── Factory ──────────────────────────────────────────────────────────────────\n\n/**\n * Create a new `TourService` instance.\n *\n * @example\n * ```ts\n * import { createTourService } from 'torchlit';\n *\n * const tours = createTourService({ storageKey: 'my-app-tours' });\n * tours.register([...]);\n * tours.start('onboarding');\n * ```\n */\nexport function createTourService(config?: TourConfig): TourService {\n  return new TourService(config);\n}\n"],"names":[],"mappings":"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"}

package/dist/tour-service.d.ts

@@ -0,0 +1,61 @@
+import type { TourConfig, TourDefinition, TourListener, TourSnapshot } from './types.js';
+export declare class TourService {
+    private tours;
+    private persistedState;
+    private activeTourId;
+    private currentStepIndex;
+    private listeners;
+    private readonly storageKey;
+    private readonly storage;
+    private readonly targetAttribute;
+    readonly spotlightPadding: number;
+    constructor(config?: TourConfig);
+    private loadState;
+    private saveState;
+    /** Register a single tour definition. */
+    register(tours: TourDefinition[]): void;
+    register(tour: TourDefinition): void;
+    /** Return a registered tour by ID. */
+    getTour(id: string): TourDefinition | undefined;
+    /** Return all registered tours. */
+    getAvailableTours(): TourDefinition[];
+    /**
+     * Whether a `first-visit` tour should auto-start.
+     * Returns `false` if the tour is manual, already completed, or dismissed.
+     */
+    shouldAutoStart(tourId: string): boolean;
+    /** Whether any tour is currently active. */
+    isActive(): boolean;
+    /** Start a tour by ID. No-op if the tour doesn't exist or has no steps. */
+    start(tourId: string): void;
+    /** Advance to the next step, or complete the tour if on the last step. */
+    nextStep(): void;
+    /** Go back to the previous step. No-op if already on step 0. */
+    prevStep(): void;
+    /** Skip / dismiss the current tour. Persists "dismissed" state. */
+    skipTour(): void;
+    private completeTour;
+    /** Return a snapshot of the current tour state, or `null` if inactive. */
+    getSnapshot(): TourSnapshot | null;
+    /** Find a DOM element by its `data-tour-id` (or custom attribute). */
+    findTarget(targetId: string): Element | null;
+    /** Subscribe to snapshot changes. Returns an unsubscribe function. */
+    subscribe(listener: TourListener): () => void;
+    private notify;
+    /** Clear all persisted state and stop any active tour. */
+    resetAll(): void;
+}
+/**
+ * Create a new `TourService` instance.
+ *
+ * @example
+ * ```ts
+ * import { createTourService } from 'torchlit';
+ *
+ * const tours = createTourService({ storageKey: 'my-app-tours' });
+ * tours.register([...]);
+ * tours.start('onboarding');
+ * ```
+ */
+export declare function createTourService(config?: TourConfig): TourService;
+//# sourceMappingURL=tour-service.d.ts.map

package/dist/tour-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-service.d.ts","sourceRoot":"","sources":["../src/tour-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,YAAY,EACZ,YAAY,EAGb,MAAM,YAAY,CAAC;AA6BpB,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAA0C;IACvD,OAAO,CAAC,cAAc,CAAY;IAClC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,SAAS,CAAgC;IAGjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;gBAEtB,MAAM,GAAE,UAAe;IAUnC,OAAO,CAAC,SAAS;IAgBjB,OAAO,CAAC,SAAS;IAUjB,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI;IACvC,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAWpC,sCAAsC;IACtC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI/C,mCAAmC;IACnC,iBAAiB,IAAI,cAAc,EAAE;IAIrC;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IASxC,4CAA4C;IAC5C,QAAQ,IAAI,OAAO;IAMnB,2EAA2E;IAC3E,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAS3B,0EAA0E;IAC1E,QAAQ,IAAI,IAAI;IAYhB,gEAAgE;IAChE,QAAQ,IAAI,IAAI;IAQhB,mEAAmE;IACnE,QAAQ,IAAI,IAAI;IAiBhB,OAAO,CAAC,YAAY;IAmBpB,0EAA0E;IAC1E,WAAW,IAAI,YAAY,GAAG,IAAI;IAwBlC,sEAAsE;IACtE,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI;IAM5C,sEAAsE;IACtE,SAAS,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,IAAI;IAK7C,OAAO,CAAC,MAAM;IAOd,0DAA0D;IAC1D,QAAQ,IAAI,IAAI;CAQjB;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,WAAW,CAElE"}

package/dist/tour-service.js

@@ -0,0 +1,6 @@
+import { T, c } from "./tour-service-BKz7eeWb.js";
+export {
+  T as TourService,
+  c as createTourService
+};
+//# sourceMappingURL=tour-service.js.map

package/dist/tour-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-service.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/types.d.ts

@@ -0,0 +1,92 @@
+/** Where to position the tooltip relative to the spotlight target. */
+export type TourPlacement = 'top' | 'bottom' | 'left' | 'right';
+export interface TourStep {
+    /**
+     * Matches `[data-tour-id="..."]` on the target element.
+     * Deep shadow DOM traversal is used automatically.
+     * Use `'_none_'` for a centered "welcome" card with no spotlight.
+     */
+    target: string;
+    /** Bold title shown in the tooltip. */
+    title: string;
+    /** Descriptive message shown below the title. */
+    message: string;
+    /** Where to position the tooltip relative to the target. */
+    placement: TourPlacement;
+    /**
+     * Arbitrary route / view hint.
+     * When set, a `tour-route-change` event is dispatched with `{ route }` detail
+     * so the host application can switch views before the step renders.
+     */
+    route?: string;
+    /**
+     * Optional async hook that runs **before** the step is shown.
+     * Use this for route navigation, data loading, or any async prep work.
+     */
+    beforeShow?: () => void | Promise<void>;
+}
+export interface TourDefinition {
+    /** Unique tour identifier. */
+    id: string;
+    /** Human-readable tour name. */
+    name: string;
+    /**
+     * `'first-visit'` — auto-triggers on first page load (unless completed/dismissed).
+     * `'manual'` — only starts when explicitly called via `service.start(id)`.
+     */
+    trigger: 'first-visit' | 'manual';
+    /** Ordered list of tour steps. */
+    steps: TourStep[];
+    /** Called when the user completes every step in the tour. */
+    onComplete?: () => void;
+    /** Called when the user skips / dismisses the tour. */
+    onSkip?: () => void;
+}
+export interface TourState {
+    /** Tour IDs that have been completed (user went through all steps). */
+    completed: string[];
+    /** Tour IDs that have been dismissed (user skipped). */
+    dismissed: string[];
+}
+export interface TourSnapshot {
+    tourId: string;
+    tourName: string;
+    step: TourStep;
+    stepIndex: number;
+    totalSteps: number;
+    targetRect: DOMRect | null;
+    targetElement: Element | null;
+}
+/**
+ * Minimal storage interface.
+ * Defaults to `localStorage` when not provided.
+ */
+export interface StorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+export interface TourConfig {
+    /**
+     * Key used for persisting tour state.
+     * @default `'torchlit-state'`
+     */
+    storageKey?: string;
+    /**
+     * Custom storage adapter. Useful for SSR, sessionStorage,
+     * or API-backed persistence.
+     * @default localStorage
+     */
+    storage?: StorageAdapter;
+    /**
+     * The `data-*` attribute used to locate tour targets.
+     * @default `'data-tour-id'`
+     */
+    targetAttribute?: string;
+    /**
+     * Padding (in px) around the spotlight cutout.
+     * @default 10
+     */
+    spotlightPadding?: number;
+}
+export type TourListener = (snapshot: TourSnapshot | null) => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAIhE,MAAM,WAAW,QAAQ;IACvB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IAEd,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAEhB,4DAA4D;IAC5D,SAAS,EAAE,aAAa,CAAC;IAEzB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAID,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IAEX,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,OAAO,EAAE,aAAa,GAAG,QAAQ,CAAC;IAElC,kCAAkC;IAClC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAElB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IAExB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAID,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,SAAS,EAAE,MAAM,EAAE,CAAC;IAEpB,wDAAwD;IACxD,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAID,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B;AAID;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAID,MAAM,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,KAAK,IAAI,CAAC"}

package/dist/utils/deep-query.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Recursively search the DOM — including shadow roots — for an element
+ * matching the given CSS selector.
+ *
+ * This is the key differentiator vs. libraries like Shepherd.js or Intro.js
+ * which cannot pierce shadow DOM boundaries.
+ *
+ * @param selector  A valid CSS selector string.
+ * @param root      The root element (or Document) to start searching from.
+ *                  Defaults to `document.body`.
+ * @returns         The first matching `Element`, or `null`.
+ *
+ * @example
+ * ```ts
+ * import { deepQuery } from 'torchlit';
+ *
+ * const el = deepQuery('[data-tour-id="sidebar-nav"]');
+ * ```
+ */
+export declare function deepQuery(selector: string, root?: Element | Document): Element | null;
+//# sourceMappingURL=deep-query.d.ts.map

package/dist/utils/deep-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-query.d.ts","sourceRoot":"","sources":["../../src/utils/deep-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,OAAO,GAAG,QAAwB,GACvC,OAAO,GAAG,IAAI,CAehB"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "torchlit",
+  "version": "0.1.0",
+  "description": "Lightweight guided-tour & onboarding library built on Lit web components. Shadow DOM aware, framework-agnostic, tiny footprint.",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./service": {
+      "import": "./dist/tour-service.js",
+      "types": "./dist/tour-service.d.ts"
+    },
+    "./overlay": {
+      "import": "./dist/tour-overlay.js",
+      "types": "./dist/tour-overlay.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "./dist/tour-overlay.js"
+  ],
+  "scripts": {
+    "dev": "vite serve examples",
+    "build": "vite build && tsc --emitDeclarationOnly --outDir dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "preview": "vite preview",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "keywords": [
+    "tour",
+    "onboarding",
+    "torchlit",
+    "spotlight",
+    "guided-tour",
+    "web-components",
+    "lit",
+    "shadow-dom",
+    "walkthrough",
+    "tooltip"
+  ],
+  "author": "Barry King (https://github.com/barryking)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/barryking/torchlit.git"
+  },
+  "homepage": "https://github.com/barryking/torchlit",
+  "bugs": "https://github.com/barryking/torchlit/issues",
+  "peerDependencies": {
+    "lit": "^3.0.0"
+  },
+  "devDependencies": {
+    "jsdom": "^28.0.0",
+    "lit": "^3.2.1",
+    "typescript": "^5.7.0",
+    "vite": "^6.1.0",
+    "vitest": "^3.0.0"
+  }
+}