@guideflow/core

Zero-dependency FSM engine for product tours, spotlights, hotspots, and hints.

The core engine behind GuideFlow. Framework-agnostic — use it with vanilla JS or pair it with @guideflow/react, @guideflow/vue, or @guideflow/svelte.

Installation

npm install @guideflow/core

Quick Start

import { createGuideFlow } from '@guideflow/core'
import '@guideflow/core/styles'

const gf = createGuideFlow()

gf.start({
  id: 'welcome',
  initial: 'intro',
  states: {
    intro: {
      steps: [
        {
          id: 'step-1',
          content: { title: 'Welcome!', body: 'This is your dashboard.' },
          target: '#sidebar',
          placement: 'right',
        },
        {
          id: 'step-2',
          content: { title: 'Your profile', body: 'Manage your account here.' },
          target: '#profile-btn',
          placement: 'bottom',
        },
      ],
      final: true,
    },
  },
})

Key Exports

| Export | Description | |--------|-------------| | createGuideFlow() | Main factory — returns a GuideFlowInstance | | createMachine() | Low-level FSM state machine | | TourEngine | Tour lifecycle management | | SpotlightOverlay | Animated SVG cutout overlay | | HotspotManager | Persistent pulsing beacons | | HintSystem | Hint badge management | | ProgressStore | localStorage / IndexedDB persistence | | BroadcastSync | Cross-tab sync via BroadcastChannel | | I18nRegistry | Translation registry with locale fallback | | DefaultRenderer | Built-in step renderer |

Hotspots & Hints

// Persistent pulsing beacon
const id = gf.hotspot('#new-feature-btn', {
  title: 'New!',
  body: 'Check out the new export feature.',
  placement: 'top',
  color: '#6366f1',
})
gf.removeHotspot(id)

// Hint badges
gf.hints([
  { id: 'hint-1', target: '#settings', hint: 'Configure your preferences here' },
])
gf.showHints()

Events

gf.on('tour:start',    ({ flowId }) => { /* ... */ })
gf.on('tour:complete', ({ flowId }) => { /* ... */ })
gf.on('tour:abandon',  ({ flowId, stepId }) => { /* ... */ })
gf.on('step:enter',    ({ stepId, stepIndex }) => { /* ... */ })
gf.on('step:exit',     ({ stepId, stepIndex }) => { /* ... */ })
gf.on('hotspot:open',  ({ id }) => { /* ... */ })
gf.on('hint:click',    ({ id }) => { /* ... */ })

Configuration

const gf = createGuideFlow({
  spotlight: { padding: 8, borderRadius: 4, animated: true },
  persistence: { driver: 'localStorage', ttl: 30 * 24 * 60 * 60 * 1000 },
  context: { userId: 'user-123', roles: ['admin'] },
  debug: false,
})

Related Packages

• @guideflow/react — React hooks & components
• @guideflow/vue — Vue 3 composables
• @guideflow/svelte — Svelte stores
• @guideflow/ai — AI-powered tour generation
• @guideflow/analytics — Analytics & A/B testing
• @guideflow/cli — CLI tools

License

MIT