{"_id":"@eistatistik/tour-agent","name":"@eistatistik/tour-agent","dist-tags":{"latest":"0.4.0"},"versions":{"0.4.0":{"name":"@eistatistik/tour-agent","version":"0.4.0","description":"Floating widget package for TourAgent with built-in chat-style UI","main":"src/index.js","module":"src/index.js","types":"index.d.ts","exports":{".":{"types":"./index.d.ts","import":"./src/index.js","default":"./src/index.js"}},"unpkg":"dist/tour-agent.js","jsdelivr":"dist/tour-agent.js","scripts":{"build":"node build.mjs","dev":"node build.mjs --watch","serve":"npx -y serve dist","prepublishOnly":"npm run build"},"keywords":["tour","agent","intro","guide","onboarding","ai","self-healing"],"license":"MIT","dependencies":{"@eistatistik/tour-agent-core":"*"},"devDependencies":{"esbuild":"^0.25.0"},"_id":"@eistatistik/tour-agent@0.4.0","gitHead":"c46875200faab2e1e2c9a634d00740f418366074","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-7mA8mqyR9dZaM4OJfe7FqkAkyauuil5HWai6v8KK//RKMV9Ce7Ii+0Z5cTzU+PwlQl9hQmf5W60yHk3gBPF/rQ==","shasum":"4ceb56046c9c959e583c1325e5a09d63c2b02b58","tarball":"https://registry.npmjs.org/@eistatistik/tour-agent/-/tour-agent-0.4.0.tgz","fileCount":9,"unpackedSize":223155,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDFGLo8FbpHTH2ykpXsvQlEGX+W7IQxg7zSRrzqIw9mNQIgd9K4NlxkpEbzkT8txYb/PdfTg6yNavzQlGHZx299LXc="}]},"_npmUser":{"name":"eistatistik","email":"istabot.info@gmail.com"},"directories":{},"maintainers":[{"name":"eistatistik","email":"istabot.info@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tour-agent_0.4.0_1774886889523_0.6265989406676908"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-30T16:08:09.423Z","0.4.0":"2026-03-30T16:08:09.712Z","modified":"2026-03-30T16:08:09.895Z"},"maintainers":[{"name":"eistatistik","email":"istabot.info@gmail.com"}],"description":"Floating widget package for TourAgent with built-in chat-style UI","keywords":["tour","agent","intro","guide","onboarding","ai","self-healing"],"license":"MIT","readme":"# @xtatistix/tour-agent\n\nFull TourAgent package with a floating widget UI.\n\nThis 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.\n\nIf you want to use your own UI and only reuse the core runtime, install [`@xtatistix/tour-agent-core`](https://www.npmjs.com/package/@xtatistix/tour-agent-core) instead.\n\n## Install\n\n```bash\nnpm install @xtatistix/tour-agent\n```\n\n## Next.js Quick Start\n\nUse the package only in client components.\n\n```tsx\n'use client';\n\nimport { useEffect } from 'react';\nimport { init, destroy } from '@xtatistix/tour-agent';\n\nexport function TourAgentBootstrap() {\n  useEffect(() => {\n    init({\n      apiKey: process.env.NEXT_PUBLIC_OPENAI_API_KEY,\n      tours: [\n        {\n          id: 'invite_user',\n          label: 'Invite User',\n          steps: [\n            {\n              elementQuery: \"[data-tour-id='invite-user']\",\n              tooltipText: 'Open the invite flow from here.',\n            },\n          ],\n        },\n      ],\n      healing: {\n        enabled: true,\n        useCache: true,\n        useLocalAI: true,\n        useLLM: true,\n      },\n      localAI: {\n        model: 'Xenova/all-MiniLM-L6-v2',\n        threshold: 0.25,\n      },\n      session: {\n        storage: 'sessionStorage',\n        resumeOnInit: true,\n        followNavigation: true,\n      },\n    });\n\n    return () => destroy();\n  }, []);\n\n  return null;\n}\n```\n\n## DOM Annotations\n\nTourAgent works best when the host app adds stable annotations:\n\n```html\n<button\n  data-tour-id=\"invite-user\"\n  data-tour-hint=\"Invite a new teammate into the workspace\"\n>\n  Invite user\n</button>\n```\n\n- `data-tour-id`: stable target identifier\n- `data-tour-hint`: semantic description used by self-healing\n\nRecommended `data-tour-id` style:\n\n- semantic, stable, and human-readable\n- avoid generated ids and positional names\n- prefer a surface/feature/role style\n\nExamples:\n\n- `sidebar-reports-nav`\n- `workspace-team-members-tab`\n- `team-members-invite-email-input`\n\n## Runtime Model\n\n- Preset tours run from in-memory definitions supplied by the consumer.\n- Free-text intent mode calls the configured LLM directly from the browser in the current release.\n- Active tours persist in browser storage until they complete or are closed.\n- Cross-page route following is opt-in with `session.followNavigation: true`.\n- The built-in widget panel can update this preference at runtime without persisting unrelated session options.\n- Self-healing uses a 4-step pipeline:\n  - direct selector match\n  - in-memory healing cache\n  - local semantic matching with `@xenova/transformers`\n  - LLM fallback\n\n## API Surface\n\n```ts\ninit(config)\ndestroy()\nstartPreset(tourId)\nstartPrompt(text)\nresumeActiveTour()\ngetActiveSession()\nclearActiveTourSession()\nsetSessionConfig({ followNavigation: true })\nresetSessionConfig()\nsetTours(tours)\naddTour(tour)\ngetTours()\ngetLLMConfig()\ngetRuntimeConfig()\ngetSessionConfig()\ngetHealingCache()\nclearHealingCache()\n```\n\n## Browser Bundle\n\nFor script-tag usage:\n\n```html\n<script src=\"https://cdn.jsdelivr.net/npm/@xtatistix/tour-agent/dist/tour-agent.js\"></script>\n<script>\n  TourAgent.init({ apiKey: 'sk-...' });\n</script>\n```\n\n## Notes\n\n- This is the widget package.\n- For custom UI integrations, use `@xtatistix/tour-agent-core`.\n- Production proxying, hosted API access, and credential hardening are planned and tracked in [ROADMAP.md](https://github.com/xtatistix/tour-agent/blob/main/ROADMAP.md).\n","readmeFilename":"README.md","_rev":"1-df121913603ba935d7ede6460446da19"}