@xtatistix/tour-agent

Full TourAgent package with a floating widget UI.

This package mounts a fixed widget on the page, similar to support/chat widgets such as tawk.to. Users interact with the agent through the built-in floating UI.

If you want to use your own UI and only reuse the core runtime, install @xtatistix/tour-agent-core instead.

Install

npm install @xtatistix/tour-agent

Next.js Quick Start

Use the package only in client components.

'use client';

import { useEffect } from 'react';
import { init, destroy } from '@xtatistix/tour-agent';

export function TourAgentBootstrap() {
  useEffect(() => {
    init({
      apiKey: process.env.NEXT_PUBLIC_OPENAI_API_KEY,
      tours: [
        {
          id: 'invite_user',
          label: 'Invite User',
          steps: [
            {
              elementQuery: "[data-tour-id='invite-user']",
              tooltipText: 'Open the invite flow from here.',
            },
          ],
        },
      ],
      healing: {
        enabled: true,
        useCache: true,
        useLocalAI: true,
        useLLM: true,
      },
      localAI: {
        model: 'Xenova/all-MiniLM-L6-v2',
        threshold: 0.25,
      },
      session: {
        storage: 'sessionStorage',
        resumeOnInit: true,
        followNavigation: true,
      },
    });

    return () => destroy();
  }, []);

  return null;
}

DOM Annotations

TourAgent works best when the host app adds stable annotations:

<button
  data-tour-id="invite-user"
  data-tour-hint="Invite a new teammate into the workspace"
>
  Invite user
</button>

• data-tour-id: stable target identifier
• data-tour-hint: semantic description used by self-healing

Recommended data-tour-id style:

• semantic, stable, and human-readable
• avoid generated ids and positional names
• prefer a surface/feature/role style

Examples:

• sidebar-reports-nav
• workspace-team-members-tab
• team-members-invite-email-input

Runtime Model

• Preset tours run from in-memory definitions supplied by the consumer.
• Free-text intent mode calls the configured LLM directly from the browser in the current release.
• Active tours persist in browser storage until they complete or are closed.
• Cross-page route following is opt-in with session.followNavigation: true.
• The built-in widget panel can update this preference at runtime without persisting unrelated session options.
• Self-healing uses a 4-step pipeline:
  • direct selector match
  • in-memory healing cache
  • local semantic matching with @xenova/transformers
  • LLM fallback

API Surface

init(config)
destroy()
startPreset(tourId)
startPrompt(text)
resumeActiveTour()
getActiveSession()
clearActiveTourSession()
setSessionConfig({ followNavigation: true })
resetSessionConfig()
setTours(tours)
addTour(tour)
getTours()
getLLMConfig()
getRuntimeConfig()
getSessionConfig()
getHealingCache()
clearHealingCache()

Browser Bundle

For script-tag usage:

<script src="https://cdn.jsdelivr.net/npm/@xtatistix/tour-agent/dist/tour-agent.js"></script>
<script>
  TourAgent.init({ apiKey: 'sk-...' });
</script>

Notes

• This is the widget package.
• For custom UI integrations, use @xtatistix/tour-agent-core.
• Production proxying, hosted API access, and credential hardening are planned and tracked in ROADMAP.md.