Branching, Gates & Funnel Events

import { useTourConditions } from '@absolutejs/tour';

// Conditions mirror actions: serializable refs resolved BY NAME against
// a keyed-singleton registry. Built-ins cover the DOM-shaped checks;
// anything product-shaped comes from the host.
const conditions = useTourConditions(); // default key 'absolute.tour'

const unregister = conditions.register(
	'hasDeals',
	() => dealCount.value > 0
);

conditions.registerAll({
	isSubscribed: () => Boolean(viewer.value?.subscription),
	onTrial: () => viewer.value?.plan === 'trial'
});

// Built-ins — no registration needed:
// { condition: 'element', args: { selector: '.pipeline-board' } }
// { condition: 'media', args: { query: '(max-width: 640px)' } }

const step = {
	body: 'Every deal, one board.',
	route: '/portal/pipeline',
	// ALL showIf predicates must hold, or the step is skipped.
	showIf: [{ condition: 'hasDeals' }],
	// ANY skipIf predicate holding skips the step.
	skipIf: [
		{ args: { query: '(max-width: 640px)' }, condition: 'media' }
	],
	target: '.pipeline-board',
	title: 'Your pipeline',
	// Hold the step until the app is ready for it: a selector that must
	// exist (and have a visible box), or a registered condition that
	// must return true. Past timeoutMs (default 3500) the step shows
	// anyway rather than stalling the tour.
	waitFor: { selector: '.pipeline-board', timeoutMs: 5000 }
};

// waitFor can also poll a registered condition (120ms interval):
// waitFor: { condition: { condition: 'hasDeals' }, timeoutMs: 4000 }

import { useSpotlight } from '@absolutejs/tour';

const t = useSpotlight({
	controller,
	onClose,
	// Every lifecycle moment lands in your analytics.
	onEvent: (event) => analytics.track(event.name, event),
	steps: () => activeTutorial.value?.steps ?? [],
	// Stamped on every event so tutorials don't blur together.
	tutorialSlug: () => activeTutorial.value?.slug
});

// A tour_skipped event — the one that matters — carries the exact
// screen the viewer was on when they'd had enough:
// {
//   at: '2026-07-12T17:03:11.302Z',
//   isReplay: false,
//   name: 'tour_skipped',
//   reason: 'escape',          // Skip button → 'skip'
//   route: '/portal/matches',  // window.location.pathname at fire time
//   stepCount: 7,
//   stepIndex: 4,
//   stepTitle: 'Swipe or list',
//   target: "[data-tour='match-view']",
//   tutorialSlug: 'portal-intro'
// }

import { useTourController, useTourGate } from '@absolutejs/tour';

const controller = useTourController('myapp.tour');

// The auto-play decision, centralized. Dismissal counts persist in
// localStorage — they must survive sessions.
const gate = useTourGate({ roles: () => viewer.roles });

// The one tutorial to auto-play now: eligible candidates on this route,
// highest trigger.priority wins (stable on ties).
const tutorial = gate.pick(publishedTutorials, route.path);
if (tutorial) {
	gate.recordAutoPlay(tutorial.slug ?? '');
	controller.start();
}

// From your onEvent sink:
const onEvent = (event) => {
	const slug = activeTutorial.value?.slug ?? '';
	if (event.name === 'tour_skipped') gate.recordDismissal(slug);
	if (event.name === 'tour_completed') gate.recordCompletion(slug);
};

// Manual replays bypass the gate entirely — it governs auto-play only.
controller.start(true);

import type { Tutorial } from '@absolutejs/tour';

const tutorial: Tutorial = {
	slug: 'portal-intro',
	steps: PORTAL_TOUR_STEPS,
	trigger: {
		// Auto-play once per viewer, on their first visit.
		firstVisitOnly: true,
		// Stop auto-playing after this many skips (default 2). Manual
		// replay stays available.
		maxDismissals: 2,
		// Only auto-play when the current path starts with this prefix.
		onRoutePrefix: '/portal',
		// Auto-play at most once per browser session.
		oncePerSession: true,
		// When several tutorials match a page, highest priority wins.
		priority: 10,
		// Restrict auto-play to these role slugs (at least one must
		// match the gate's roles getter).
		roles: ['member'],
		// Audience predicates — all must hold for auto-play.
		showIf: [{ condition: 'isSubscribed' }]
	}
};