@docentjs/core 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -610,6 +610,12 @@ interface DocentOptions {
   /** Builds a platform controller for a tour. The DOM package supplies this. */
   createController: (tour: Tour, options: SharedControllerOptions) => TourController;
   now?: () => number;
+  /**
+   * Start watching triggers right away. Default true. Framework bindings pass
+   * `false` and call `connect()` / `disconnect()` from their mount lifecycle,
+   * which keeps construction free of side effects (React StrictMode).
+   */
+  connect?: boolean;
 }
 interface DocentState {
   /** Id of the tour currently running or paused, if any. */
@@ -623,8 +629,6 @@ interface StartOptions {
   at?: number | string;
 }
 export declare class Docent {
-  /** Resolves once tours and progress are loaded and triggers are armed. */
-  readonly ready: Promise<void>;
   private readonly options;
   private readonly env;
   private readonly baseStorage;
@@ -642,8 +646,30 @@ export declare class Docent {
   private readonly cleanups;
   private readonly timers;
   private readonly listeners;
+  private readonly eventListeners;
   private destroyed;
+  private loading;
+  /** Wanted by the owner (between connect and disconnect). */
+  private connected;
+  /** Listening to routes, the source and triggers. */
+  private attached;
   constructor(options: DocentOptions);
+  /** Resolves once tours and progress are loaded. Loading starts on first use. */
+  get ready(): Promise<void>;
+  /** Start watching routes, the tour source and triggers. Idempotent. */
+  connect(): void;
+  /**
+   * Stop watching and remove any running tour without recording an outcome.
+   * `connect()` resumes. Unlike `destroy()`, the manager stays usable.
+   */
+  disconnect(): Promise<void>;
+  /** The tours currently managed. */
+  getTours(): Tour[];
+  /**
+   * Observe every lifecycle event from every tour, in addition to the `sink`
+   * option. Returns an unsubscribe function. Used by devtools.
+   */
+  onEvent(listener: (event: DocentEvent) => void): () => void;
   getState(): DocentState;
   subscribe(listener: DocentListener): () => void;
   /** The controller of the running tour, for fine-grained control. */
@@ -677,7 +703,8 @@ export declare class Docent {
   /** Stop the running tour (recorded as skipped). */
   stop(): Promise<void>;
   destroy(): Promise<void>;
-  private init;
+  private load;
+  private attach;
   private setTours;
   private loadRecords;
   private disarmTriggers;
@@ -693,7 +720,8 @@ export declare class Docent {
   private fire;
   /** Route triggers are only valid while the user is still on a matching route. */
   private triggerStillHolds;
-  private conditionEnv;
+  /** What conditions are evaluated against right now. Used by `isEligible` and devtools. */
+  getConditionEnv(): ConditionEnv;
   private sharedOptions;
   private run;
   /**

package/dist/index.d.ts

@@ -610,6 +610,12 @@ interface DocentOptions {
   /** Builds a platform controller for a tour. The DOM package supplies this. */
   createController: (tour: Tour, options: SharedControllerOptions) => TourController;
   now?: () => number;
+  /**
+   * Start watching triggers right away. Default true. Framework bindings pass
+   * `false` and call `connect()` / `disconnect()` from their mount lifecycle,
+   * which keeps construction free of side effects (React StrictMode).
+   */
+  connect?: boolean;
 }
 interface DocentState {
   /** Id of the tour currently running or paused, if any. */
@@ -623,8 +629,6 @@ interface StartOptions {
   at?: number | string;
 }
 export declare class Docent {
-  /** Resolves once tours and progress are loaded and triggers are armed. */
-  readonly ready: Promise<void>;
   private readonly options;
   private readonly env;
   private readonly baseStorage;
@@ -642,8 +646,30 @@ export declare class Docent {
   private readonly cleanups;
   private readonly timers;
   private readonly listeners;
+  private readonly eventListeners;
   private destroyed;
+  private loading;
+  /** Wanted by the owner (between connect and disconnect). */
+  private connected;
+  /** Listening to routes, the source and triggers. */
+  private attached;
   constructor(options: DocentOptions);
+  /** Resolves once tours and progress are loaded. Loading starts on first use. */
+  get ready(): Promise<void>;
+  /** Start watching routes, the tour source and triggers. Idempotent. */
+  connect(): void;
+  /**
+   * Stop watching and remove any running tour without recording an outcome.
+   * `connect()` resumes. Unlike `destroy()`, the manager stays usable.
+   */
+  disconnect(): Promise<void>;
+  /** The tours currently managed. */
+  getTours(): Tour[];
+  /**
+   * Observe every lifecycle event from every tour, in addition to the `sink`
+   * option. Returns an unsubscribe function. Used by devtools.
+   */
+  onEvent(listener: (event: DocentEvent) => void): () => void;
   getState(): DocentState;
   subscribe(listener: DocentListener): () => void;
   /** The controller of the running tour, for fine-grained control. */
@@ -677,7 +703,8 @@ export declare class Docent {
   /** Stop the running tour (recorded as skipped). */
   stop(): Promise<void>;
   destroy(): Promise<void>;
-  private init;
+  private load;
+  private attach;
   private setTours;
   private loadRecords;
   private disarmTriggers;
@@ -693,7 +720,8 @@ export declare class Docent {
   private fire;
   /** Route triggers are only valid while the user is still on a matching route. */
   private triggerStillHolds;
-  private conditionEnv;
+  /** What conditions are evaluated against right now. Used by `isEligible` and devtools. */
+  getConditionEnv(): ConditionEnv;
   private sharedOptions;
   private run;
   /**

package/dist/index.js

@@ -467,8 +467,9 @@ var TourController = class {
 	async destroy() {
 		this.cancelPending();
 		this.listeners.clear();
-		await this.renderer.hide();
+		const hidden = this.renderer.hide();
 		this.state = IDLE_STATE;
+		await hidden;
 	}
 	isActive() {
 		return this.state.status === "running" || this.state.status === "paused";
@@ -691,8 +692,6 @@ function isTourSource(value) {
 	return !!value && !Array.isArray(value) && typeof value.load === "function";
 }
 var Docent = class {
-	/** Resolves once tours and progress are loaded and triggers are armed. */
-	ready;
 	options;
 	env;
 	baseStorage;
@@ -710,14 +709,61 @@ var Docent = class {
 	cleanups = [];
 	timers = /* @__PURE__ */ new Set();
 	listeners = /* @__PURE__ */ new Set();
+	eventListeners = /* @__PURE__ */ new Set();
 	destroyed = false;
+	loading;
+	/** Wanted by the owner (between connect and disconnect). */
+	connected = false;
+	/** Listening to routes, the source and triggers. */
+	attached = false;
 	constructor(options) {
 		this.options = options;
 		this.env = options.environment;
 		this.identity = options.identity ?? ANONYMOUS_IDENTITY;
 		this.baseStorage = options.storage ?? createMemoryStorage();
 		this.store = new ProgressStore(scopeStorage(this.baseStorage, this.identity.id));
-		this.ready = this.init();
+		if (options.connect !== false) this.connect();
+	}
+	/** Resolves once tours and progress are loaded. Loading starts on first use. */
+	get ready() {
+		this.loading ??= this.load();
+		return this.loading;
+	}
+	/** Start watching routes, the tour source and triggers. Idempotent. */
+	connect() {
+		if (this.destroyed || this.connected) return;
+		this.connected = true;
+		this.ready.then(() => {
+			if (this.connected && !this.attached && !this.destroyed) this.attach();
+		});
+	}
+	/**
+	* Stop watching and remove any running tour without recording an outcome.
+	* `connect()` resumes. Unlike `destroy()`, the manager stays usable.
+	*/
+	async disconnect() {
+		this.connected = false;
+		if (this.attached) {
+			this.attached = false;
+			this.disarmTriggers();
+			for (const c of this.cleanups) c();
+			this.cleanups.length = 0;
+		}
+		this.queue = [];
+		await this.stopActive();
+		this.emitState();
+	}
+	/** The tours currently managed. */
+	getTours() {
+		return [...this.tours.values()];
+	}
+	/**
+	* Observe every lifecycle event from every tour, in addition to the `sink`
+	* option. Returns an unsubscribe function. Used by devtools.
+	*/
+	onEvent(listener) {
+		this.eventListeners.add(listener);
+		return () => this.eventListeners.delete(listener);
 	}
 	getState() {
 		return {
@@ -778,7 +824,7 @@ var Docent = class {
 	isEligible(tourId) {
 		const tour = this.tours.get(tourId);
 		if (!tour) return false;
-		return shouldShow(tour, this.records.get(tourId) ?? null) && evaluateAll(tour.conditions, this.conditionEnv());
+		return shouldShow(tour, this.records.get(tourId) ?? null) && evaluateAll(tour.conditions, this.getConditionEnv());
 	}
 	/** Progress state of a tour for the current user. */
 	tourState(tourId) {
@@ -813,22 +859,20 @@ var Docent = class {
 		await this.controller?.skip();
 	}
 	async destroy() {
+		await this.disconnect();
 		this.destroyed = true;
-		this.disarmTriggers();
-		for (const c of this.cleanups) c();
-		this.cleanups.length = 0;
-		const controller = this.controller;
-		this.controller = void 0;
-		this.activeId = null;
-		await controller?.destroy();
 		this.listeners.clear();
+		this.eventListeners.clear();
 	}
-	async init() {
+	async load() {
 		const source = this.options.tours;
 		const initial = isTourSource(source) ? await source.load() : source ?? [];
 		this.setTours(initial);
 		await this.loadRecords();
-		if (this.destroyed) return;
+	}
+	attach() {
+		this.attached = true;
+		const source = this.options.tours;
 		if (isTourSource(source) && source.subscribe) this.cleanups.push(source.subscribe((tours) => {
 			this.setTours(tours);
 			this.loadRecords().then(() => this.armTriggers());
@@ -857,7 +901,7 @@ var Docent = class {
 	* `except` skips one tour, used for the tour that just finished.
 	*/
 	armTriggers(except) {
-		if (this.destroyed) return;
+		if (this.destroyed || !this.attached) return;
 		this.disarmTriggers();
 		for (const tour of this.tours.values()) {
 			const trigger = tour.trigger;
@@ -899,7 +943,7 @@ var Docent = class {
 	}
 	/** A trigger fired: start the tour if eligible, or queue it behind the running one. */
 	fire(tourId) {
-		if (this.destroyed || tourId === this.activeId) return;
+		if (this.destroyed || !this.attached || tourId === this.activeId) return;
 		if (!this.isEligible(tourId) || !this.triggerStillHolds(tourId)) return;
 		if (this.tours.get(tourId)?.trigger?.type === "auto") this.autoFired.add(tourId);
 		if (this.activeId) {
@@ -916,7 +960,8 @@ var Docent = class {
 		const route = this.env.currentRoute?.();
 		return route !== void 0 && matchRoute(trigger.pattern, route);
 	}
-	conditionEnv() {
+	/** What conditions are evaluated against right now. Used by `isEligible` and devtools. */
+	getConditionEnv() {
 		const env = {
 			identity: this.identity,
 			elementExists: (t) => this.env.hasTarget(t),
@@ -933,7 +978,10 @@ var Docent = class {
 			storage: scopeStorage(this.baseStorage, this.identity.id),
 			tourState: (id) => this.tourState(id)
 		};
-		if (this.options.sink) shared.sink = this.options.sink;
+		shared.sink = { emit: (event) => {
+			this.options.sink?.emit(event);
+			for (const l of this.eventListeners) l(event);
+		} };
 		const hooks = this.options.hooks?.[tour.id];
 		if (hooks) shared.hooks = hooks;
 		if (this.options.custom) shared.custom = this.options.custom;
@@ -945,6 +993,12 @@ var Docent = class {
 		const controller = this.options.createController(tour, this.sharedOptions(tour));
 		this.controller = controller;
 		this.activeId = tour.id;
+		this.records.set(tour.id, {
+			tourId: tour.id,
+			version: tourVersion(tour),
+			state: "in-progress",
+			updatedAt: (this.options.now ?? Date.now)()
+		});
 		this.emitState();
 		const off = controller.subscribe((state) => {
 			if (state.status === "completed" || state.status === "skipped" || state.status === "aborted") {