Architecture and testing

Internal ownership

Nuxt module
  -> discovers app/tours files
  -> generates registry and types
  -> registers auto-imports, components, plugin, router adapter, and CSS

Vue runtime
  -> owns definitions, target registry, active tour, events, and transitions

Tour host
  -> reads runtime state
  -> owns dialog, overlay, positioning, focus, and visual transitions

The transition controller remains framework-light internally so it can be unit tested, but it is not a public core export. Domain behavior does not live in the Nuxt module or Vue component.

Source layout

src/
  module.ts
  discovery.ts
  runtime/
    controller.ts
    registry.ts
    router.ts
    nuxt-router.ts
    targets.ts
    types.ts
    vue/
playground/
test/
  fixtures/
  browser/
docs/

Use Nuxt Module Builder for the package entry and runtime files. Use Nuxt Kit for generated templates, imports, components, and type declarations. Do not invent a second module build system.

Contract tests

Unit and integration tests must prove:

• duplicate and empty definitions fail;
• the first step becomes active before start() resolves;
• false conditional steps cause no side effects;
• routes settle before preparation and target lookup;
• preparation cleanup runs once on every exit path;
• missing targets skip or fail according to policy;
• duplicate commands do not advance twice;
• conflicting commands fail predictably;
• cancellation aborts route, preparation, and target waits;
• replacement fully ends the previous tour; and
• another start works after every failure.

Browser tests

Browser coverage must include late and removed targets, nested and horizontal scrolling, fixed and sticky elements, transformed ancestors, responsive layout movement, cross-route tours, browser Back, keyboard-only use, focus restoration, Escape, reduced motion, a custom card, SSR hydration, and rapid double clicks.

The release browser gate runs Chromium, Firefox, WebKit, mobile Chromium, and mobile WebKit serially. A fixture setup failure fails the suite; it does not skip the contract.

Package proof

The packed consumer must install the tarball, load the Nuxt module, build a clean fixture, and exercise the smallest public tour. Documentation becomes another packed-package consumer before release. Local source aliases are not sufficient release evidence.