@carlonicora/nextjs-jsonapi 3.9.0 → 3.10.0

package/src/features/assistant-action/data/AssistantActionInterface.ts

@@ -18,6 +18,15 @@ export type AssistantActionInput = {
 export interface AssistantActionInterface extends ApiDataInterface {
   get status(): AssistantActionStatus;
   get toolName(): string;
+  /** Raw JSON string of the frozen tool call's arguments. Audit copy — never rendered. */
+  get toolArgs(): string;
+  /**
+   * JSON string of the operator's presentation payload: the record being
+   * written with every referenced id already resolved to a display name.
+   * Empty when the action predates the payload (the card then falls back to
+   * the attributes in `toolArgs`).
+   */
+  get proposal(): string;
   get summary(): string;
   get resolvedAt(): Date | undefined;
   get expiresAt(): Date | undefined;

package/src/features/assistant-action/data/__tests__/AssistantAction.spec.ts

@@ -50,6 +50,7 @@ function makeHydratedData(overrides: Record<string, any> = {}) {
         status: "pending",
         toolName: "createNpc",
         toolArgs: '{"name":"A"}',
+        proposal: '{"type":"npcs","attributes":{"name":"A"}}',
         summary: "Create a new record",
         threadId: "thread-1",
         userModuleIds: ["module-1"],
@@ -74,6 +75,14 @@ describe("AssistantAction model", () => {
     expect(action.summary).toBe("Create a new record");
   });
 
+  it("rehydrates the resolved proposal payload", () => {
+    const action = new AssistantAction();
+    action.rehydrate(makeHydratedData() as any);
+
+    expect(action.toolArgs).toBe('{"name":"A"}');
+    expect(action.proposal).toBe('{"type":"npcs","attributes":{"name":"A"}}');
+  });
+
   it("parses expiresAt into a Date", () => {
     const action = new AssistantAction();
     action.rehydrate(makeHydratedData() as any);
@@ -114,6 +123,8 @@ describe("AssistantAction model", () => {
     // Missing status defaults to the fail-safe, non-actionable "expired" — never the actionable "pending".
     expect(action.status).toBe("expired");
     expect(action.toolName).toBe("");
+    // A pre-`proposal` action must degrade to the empty string, never to undefined.
+    expect(action.proposal).toBe("");
     expect(action.summary).toBe("");
     expect(action.resolvedAt).toBeUndefined();
     expect(action.expiresAt).toBeUndefined();

package/src/features/help/index.ts

@@ -15,6 +15,7 @@ export { HelpArticleBody } from "./components/HelpArticleBody";
 export { HelpTOC } from "./components/HelpTOC";
 export { HelpHint } from "./components/HelpHint";
 export { HelpAskAi } from "./components/HelpAskAi";
+export { HelpAssistantSheet } from "./components/HelpAssistantSheet";
 export { HelpSearchResultRow } from "./components/HelpSearchResultRow";
 export { useHelpFilter } from "./hooks/useHelpFilter";
 export { articleUrl, modeUrl } from "./utils/articleUrl";

package/src/features/onboarding/components/OnboardingCard.tsx

@@ -4,7 +4,6 @@ import { X } from "lucide-react";
 import { Button, Card, CardContent, CardHeader, CardTitle } from "../../../shadcnui";
 import { OnboardingCardRenderProps } from "../interfaces";
 
-// Matches a360ai ShepherdCard design exactly
 export function OnboardingCard({
   step,
   currentIndex,
@@ -17,7 +16,7 @@ export function OnboardingCard({
   isLast,
 }: OnboardingCardRenderProps) {
   return (
-    <Card className="w-[320px] relative" data-shepherd-card>
+    <Card className="w-[320px] relative" data-onboarding-card>
       <Button variant="ghost" size="icon" className="absolute end-2 top-2" onClick={onClose} aria-label={labels.close}>
         <X className="h-4 w-4" />
       </Button>

package/src/features/onboarding/contexts/OnboardingContext.spec.tsx

@@ -0,0 +1,191 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+
+type Hooks = {
+  onDestroyed?: () => void;
+  steps: Array<{
+    element?: () => Element | undefined;
+    disableActiveInteraction?: boolean;
+    popover: { side: string; align: string; onPopoverRender: (p: { wrapper: HTMLElement }) => void };
+    onHighlightStarted?: () => void;
+    onDeselected?: () => void;
+  }>;
+};
+
+const driverMock = vi.hoisted(() => {
+  const instance = {
+    drive: vi.fn(),
+    moveNext: vi.fn(),
+    movePrevious: vi.fn(),
+    moveTo: vi.fn(),
+    destroy: vi.fn(),
+  };
+  const state: { config?: Hooks } = {};
+  const driver = vi.fn((config: Hooks) => {
+    state.config = config;
+    return instance;
+  });
+  return { driver, instance, state };
+});
+
+vi.mock("driver.js", () => ({ driver: driverMock.driver }));
+vi.mock("driver.js/dist/driver.css", () => ({}));
+vi.mock("../styles/onboarding.css", () => ({}));
+
+import { OnboardingProvider, useOnboarding } from "./OnboardingContext";
+import type { OnboardingStepConfig } from "../interfaces";
+
+const steps: OnboardingStepConfig[] = [
+  { id: "a", title: "First", content: "one", selector: "[data-help='x']", side: "bottom-start" },
+  { id: "b", title: "Second", content: "two" },
+];
+
+function wrap(onTourEnd = vi.fn()) {
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <OnboardingProvider onTourEnd={onTourEnd}>{children}</OnboardingProvider>
+  );
+  return { wrapper, onTourEnd };
+}
+
+describe("OnboardingProvider on driver.js", () => {
+  beforeEach(() => {
+    driverMock.driver.mockClear();
+    driverMock.instance.drive.mockClear();
+    driverMock.instance.destroy.mockClear();
+    driverMock.instance.moveNext.mockClear();
+    driverMock.state.config = undefined;
+  });
+
+  it("maps steps to driver steps and starts the tour", () => {
+    const { wrapper } = wrap();
+    const { result } = renderHook(() => useOnboarding(), { wrapper });
+    act(() => result.current.startTour("t", steps));
+
+    const config = driverMock.state.config!;
+    expect(driverMock.instance.drive).toHaveBeenCalledTimes(1);
+    expect(config.steps).toHaveLength(2);
+    const resolveElement = config.steps[0].element!;
+    expect(typeof resolveElement).toBe("function");
+    expect(resolveElement()).toBeUndefined();
+    const target = document.createElement("div");
+    target.setAttribute("data-help", "x");
+    document.body.appendChild(target);
+    // jsdom lays nothing out, so getClientRects() is always empty; the resolver
+    // reads it to catch a display:none ancestor, so give it one box here.
+    const rects = vi.spyOn(Element.prototype, "getClientRects").mockReturnValue([{}] as unknown as DOMRectList);
+    expect(resolveElement()).toBe(target);
+    rects.mockRestore();
+    target.remove();
+    expect(resolveElement()).toBeUndefined();
+    expect(config.steps[0].popover.side).toBe("bottom");
+    expect(config.steps[0].popover.align).toBe("start");
+    expect(config.steps[0].disableActiveInteraction).toBe(true);
+    expect(config.steps[1].element).toBeUndefined();
+    expect(config.steps[1].popover.align).toBe("center");
+    expect(result.current.totalSteps).toBe(2);
+    expect(result.current.activeTourId).toBe("t");
+  });
+
+  it("renders the card into the popover wrapper and tracks the active step", () => {
+    const { wrapper } = wrap();
+    const { result } = renderHook(() => useOnboarding(), { wrapper });
+    act(() => result.current.startTour("t", steps));
+    const config = driverMock.state.config!;
+
+    const popoverWrapper = document.createElement("div");
+    act(() => {
+      config.steps[0].onHighlightStarted?.();
+      config.steps[0].popover.onPopoverRender({ wrapper: popoverWrapper });
+    });
+
+    expect(result.current.isTourActive).toBe(true);
+    expect(result.current.currentStepIndex).toBe(0);
+    expect(popoverWrapper.querySelector("[data-onboarding-card]")).not.toBeNull();
+    expect(popoverWrapper.textContent).toContain("First");
+  });
+
+  it("mounts the card synchronously, before driver.js positions the popover", () => {
+    const { wrapper } = wrap();
+    const { result } = renderHook(() => useOnboarding(), { wrapper });
+    act(() => result.current.startTour("t", steps));
+    const config = driverMock.state.config!;
+
+    // driver.js calls onPopoverRender, then measures and positions the popover in the
+    // same synchronous pass; the card must already be there at full size.
+    const popoverWrapper = document.createElement("div");
+    config.steps[0].popover.onPopoverRender({ wrapper: popoverWrapper });
+    expect(popoverWrapper.querySelector("[data-onboarding-card]")).not.toBeNull();
+    expect(popoverWrapper.textContent).toContain("First");
+  });
+
+  it("reports 'finished' when the last step's Finish is pressed", () => {
+    const { wrapper, onTourEnd } = wrap();
+    const { result } = renderHook(() => useOnboarding(), { wrapper });
+    act(() => result.current.startTour("t", steps));
+    const config = driverMock.state.config!;
+    const popoverWrapper = document.createElement("div");
+    act(() => {
+      config.steps[1].onHighlightStarted?.();
+      config.steps[1].popover.onPopoverRender({ wrapper: popoverWrapper });
+    });
+    const finish = Array.from(popoverWrapper.querySelectorAll("button")).find((b) => b.textContent === "Finish")!;
+    act(() => finish.click());
+    act(() => config.onDestroyed?.());
+
+    expect(driverMock.instance.destroy).toHaveBeenCalled();
+    expect(onTourEnd).toHaveBeenCalledWith("t", "finished");
+    expect(result.current.isTourActive).toBe(false);
+    expect(result.current.activeTourId).toBeNull();
+  });
+
+  it("ends the tour even when driver.js never fires onDestroyed", () => {
+    /* driver.js skips onDeselected/onDestroyed unless its 400ms transition callback has
+       set __activeElement and __activeStep, so a fast Finish click destroys the tour
+       without the hook ever running. The provider must still tear itself down. */
+    const { wrapper, onTourEnd } = wrap();
+    const { result } = renderHook(() => useOnboarding(), { wrapper });
+    act(() => result.current.startTour("t", steps));
+    const config = driverMock.state.config!;
+    const popoverWrapper = document.createElement("div");
+    act(() => {
+      config.steps[1].onHighlightStarted?.();
+      config.steps[1].popover.onPopoverRender({ wrapper: popoverWrapper });
+    });
+    expect(result.current.isTourActive).toBe(true);
+
+    const finish = Array.from(popoverWrapper.querySelectorAll("button")).find((b) => b.textContent === "Finish")!;
+    act(() => finish.click());
+
+    expect(driverMock.instance.destroy).toHaveBeenCalled();
+    expect(result.current.isTourActive).toBe(false);
+    expect(result.current.activeTourId).toBeNull();
+    expect(onTourEnd).toHaveBeenCalledWith("t", "finished");
+
+    // A late onDestroyed must not end the tour a second time.
+    act(() => config.onDestroyed?.());
+    expect(onTourEnd).toHaveBeenCalledTimes(1);
+  });
+
+  it("reports 'dismissed' when driver is destroyed without a card action", () => {
+    const { wrapper, onTourEnd } = wrap();
+    const { result } = renderHook(() => useOnboarding(), { wrapper });
+    act(() => result.current.startTour("t", steps));
+    act(() => driverMock.state.config!.onDestroyed?.());
+    expect(onTourEnd).toHaveBeenCalledWith("t", "dismissed");
+  });
+
+  it("warns and does nothing for an unknown tour id", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { wrapper } = wrap();
+    const { result } = renderHook(() => useOnboarding(), { wrapper });
+    act(() => result.current.startTour("missing"));
+    expect(driverMock.driver).not.toHaveBeenCalled();
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("throws when used outside the provider", () => {
+    expect(() => renderHook(() => useOnboarding())).toThrow(/OnboardingProvider/);
+  });
+});

package/src/features/onboarding/contexts/OnboardingContext.tsx

@@ -1,20 +1,61 @@
 "use client";
 
 import { createContext, useCallback, useContext, useEffect, useRef, useState } from "react";
+import { flushSync } from "react-dom";
 import { createRoot, Root } from "react-dom/client";
-import Shepherd from "shepherd.js";
-import "shepherd.js/dist/css/shepherd.css";
+import { driver, type Driver, type DriveStep, type PopoverDOM } from "driver.js";
+import "driver.js/dist/driver.css";
 import { OnboardingCard } from "../components/OnboardingCard";
 import {
   DEFAULT_ONBOARDING_LABELS,
   OnboardingContextValue,
   OnboardingProviderProps,
   OnboardingStepConfig,
+  OnboardingStepSide,
+  OnboardingTourEndReason,
 } from "../interfaces";
 import "../styles/onboarding.css";
 
 const OnboardingContext = createContext<OnboardingContextValue | null>(null);
 
+type DriverSide = "top" | "right" | "bottom" | "left";
+type DriverAlign = "start" | "center" | "end";
+
+/** "bottom-start" → { side: "bottom", align: "start" }; bare side → align "center". */
+export function mapOnboardingSide(side?: OnboardingStepSide): { side: DriverSide; align: DriverAlign } {
+  if (!side) return { side: "bottom", align: "center" };
+  const [s, a] = side.split("-") as [DriverSide, DriverAlign | undefined];
+  return { side: s, align: a ?? "center" };
+}
+
+/**
+ * Resolves a step's target, treating a hidden element as a missing one.
+ *
+ * driver.js only honours `skipMissingElement` when the element resolves to
+ * nothing. A selector string cannot express "present in the DOM but not
+ * displayed", so targets that exist yet are `display: none` (the section rail
+ * below `md`, for instance) would otherwise highlight an empty box. Returning
+ * `undefined` from the resolver takes the exact same path as an absent
+ * selector, so the step is skipped.
+ *
+ * The check is `getClientRects()`, not the element's own computed style: an
+ * element inherits invisibility from a `display: none` ancestor, whose own
+ * style says nothing. An element with no client rects generates no boxes, so
+ * it is not displayed, whatever its own `display` value is.
+ *
+ * The cast exists because driver.js types the resolver as `() => Element`,
+ * while its runtime (`typeof e === "function" ? e() : ...`) treats any falsy
+ * result as missing.
+ */
+function resolveVisibleElement(selector: string): DriveStep["element"] {
+  return (() => {
+    const element = document.querySelector(selector);
+    if (!element) return undefined;
+    if (element.getClientRects().length === 0) return undefined;
+    return element;
+  }) as DriveStep["element"];
+}
+
 export function OnboardingProvider({
   children,
   tours = [],
@@ -22,72 +63,78 @@ export function OnboardingProvider({
   labels = DEFAULT_ONBOARDING_LABELS,
   renderCard,
   zIndex: _zIndex = 9999,
+  onTourEnd,
 }: OnboardingProviderProps) {
   const [isTourActive, setIsTourActive] = useState(false);
   const [activeTourId, setActiveTourId] = useState<string | null>(null);
   const [currentStepIndex, setCurrentStepIndex] = useState(0);
   const [totalSteps, setTotalSteps] = useState(0);
 
-  const tourRef = useRef<InstanceType<typeof Shepherd.Tour> | null>(null);
-  const rootsRef = useRef<Map<string, Root>>(new Map());
+  const driverRef = useRef<Driver | null>(null);
+  const rootsRef = useRef<Map<number, Root>>(new Map());
+  const endReasonRef = useRef<OnboardingTourEndReason>("dismissed");
+  const activeTourIdRef = useRef<string | null>(null);
+
+  // Unmount on the next tick: a root cannot unmount synchronously from inside
+  // an event handler it rendered (React warns and skips the unmount).
+  const unmountRoot = (root: Root) => setTimeout(() => root.unmount(), 0);
 
   const cleanupRoots = useCallback(() => {
-    rootsRef.current.forEach((root) => {
-      try {
-        root.unmount();
-      } catch (_e) {
-        // Root may already be unmounted
-      }
-    });
+    rootsRef.current.forEach((root) => unmountRoot(root));
     rootsRef.current.clear();
   }, []);
 
-  const closeTour = useCallback(() => {
-    if (tourRef.current) {
-      tourRef.current.cancel();
-      tourRef.current = null;
-    }
-    cleanupRoots();
+  const resetState = useCallback(() => {
     setIsTourActive(false);
     setActiveTourId(null);
     setCurrentStepIndex(0);
     setTotalSteps(0);
-  }, [cleanupRoots]);
-
-  const nextStep = useCallback(() => {
-    if (tourRef.current) {
-      tourRef.current.next();
-    }
+    driverRef.current = null;
+    activeTourIdRef.current = null;
   }, []);
 
-  const previousStep = useCallback(() => {
-    if (tourRef.current) {
-      tourRef.current.back();
-    }
-  }, []);
+  /**
+   * Ends the tour on our side: unmount the cards, reset the state, report the reason.
+   *
+   * It cannot be left to driver.js's `onDestroyed`: driver only fires that hook when
+   * it holds both an active element and an active step, and both are set by a step's
+   * 400ms transition callback. A Next/Finish click that lands before the animation
+   * settles therefore destroys the DOM without ever calling the hook, and the provider
+   * would stay `isTourActive` forever. Every path that calls `destroy()` calls this
+   * straight after; `resetState()` nulls `driverRef.current`, so a later `onDestroyed`
+   * is a no-op.
+   */
+  const teardown = useCallback(
+    (reason: OnboardingTourEndReason) => {
+      if (!driverRef.current) return;
+      const id = activeTourIdRef.current;
+      cleanupRoots();
+      resetState();
+      if (id) onTourEnd?.(id, reason);
+    },
+    [cleanupRoots, resetState, onTourEnd],
+  );
 
-  const goToStep = useCallback((index: number) => {
-    if (tourRef.current) {
-      tourRef.current.show(index);
+  const closeTour = useCallback(() => {
+    if (driverRef.current) {
+      driverRef.current.destroy();
+      teardown("dismissed");
+      return;
     }
-  }, []);
+    cleanupRoots();
+    resetState();
+  }, [cleanupRoots, resetState, teardown]);
+
+  const nextStep = useCallback(() => driverRef.current?.moveNext(), []);
+  const previousStep = useCallback(() => driverRef.current?.movePrevious(), []);
+  const goToStep = useCallback((index: number) => driverRef.current?.moveTo(index), []);
 
   const startTour = useCallback(
     (tourId: string, steps?: OnboardingStepConfig[]) => {
       if (typeof window === "undefined") return;
+      if (driverRef.current) closeTour();
 
-      // Close any existing tour
-      if (tourRef.current) {
-        closeTour();
-      }
-
-      // Get steps from provided steps or find tour by ID
-      let tourSteps = steps;
-      if (!tourSteps) {
-        const tour = tours.find((t) => t.id === tourId);
-        tourSteps = tour?.steps;
-      }
-
+      const tourSteps = steps ?? tours.find((t) => t.id === tourId)?.steps;
       if (!tourSteps || tourSteps.length === 0) {
         console.warn(`No steps found for tour: ${tourId}`);
         return;
@@ -95,96 +142,102 @@ export function OnboardingProvider({
 
       setTotalSteps(tourSteps.length);
       setActiveTourId(tourId);
+      activeTourIdRef.current = tourId;
+      endReasonRef.current = "dismissed";
 
-      const tour = new Shepherd.Tour({
-        useModalOverlay: true,
-        defaultStepOptions: {
-          classes: "shepherd-theme-custom",
-          scrollTo: { behavior: "smooth", block: "center" },
-          cancelIcon: { enabled: false },
-        },
-      });
+      const move = (direction: "next" | "previous", from: number) => {
+        const target = tourSteps[direction === "next" ? from + 1 : from - 1];
+        const go = () => (direction === "next" ? driverRef.current?.moveNext() : driverRef.current?.movePrevious());
+        if (target?.showDelay) setTimeout(go, target.showDelay);
+        else go();
+      };
 
-      // Set up tour event listeners
-      tour.on("show", () => setIsTourActive(true));
-      tour.on("cancel", () => {
-        cleanupRoots();
-        setIsTourActive(false);
-        setActiveTourId(null);
-        setCurrentStepIndex(0);
-        setTotalSteps(0);
-        tourRef.current = null;
-      });
-      tour.on("complete", () => {
-        cleanupRoots();
-        setIsTourActive(false);
-        setActiveTourId(null);
-        setCurrentStepIndex(0);
-        setTotalSteps(0);
-        tourRef.current = null;
-      });
+      const end = (reason: OnboardingTourEndReason) => {
+        endReasonRef.current = reason;
+        driverRef.current?.destroy();
+        teardown(reason);
+      };
 
-      tourSteps.forEach((stepConfig, index) => {
-        const stepId = stepConfig.id || `step-${index}`;
-
-        tour.addStep({
-          id: stepId,
-          attachTo: stepConfig.selector ? { element: stepConfig.selector, on: stepConfig.side || "bottom" } : undefined,
-          arrow: true,
-          // Use text callback to return DOM element with React content
-          text: () => {
-            const container = document.createElement("div");
-            const root = createRoot(container);
-            rootsRef.current.set(stepId, root);
-
-            const cardProps = {
-              step: stepConfig,
-              currentIndex: index,
-              totalSteps: tourSteps!.length,
-              labels,
-              onNext: () => tour.next(),
-              onPrevious: () => tour.back(),
-              onClose: () => tour.cancel(),
-              onSkip: () => tour.cancel(),
-              isFirst: index === 0,
-              isLast: index === tourSteps!.length - 1,
-            };
-
-            root.render(renderCard ? renderCard(cardProps) : <OnboardingCard {...cardProps} />);
-
-            return container;
-          },
-          buttons: [], // Empty - our card handles navigation
-          beforeShowPromise: stepConfig.showDelay
-            ? () => new Promise((resolve) => setTimeout(resolve, stepConfig.showDelay))
-            : undefined,
-          canClickTarget: stepConfig.canClickTarget ?? false,
-          modalOverlayOpeningPadding: 8,
-          modalOverlayOpeningRadius: 8,
-          when: {
-            show: () => {
-              setCurrentStepIndex(index);
-              stepConfig.onShow?.();
-            },
-            hide: () => {
-              stepConfig.onHide?.();
+      const driveSteps: DriveStep[] = tourSteps.map((stepConfig, index) => {
+        const { side, align } = mapOnboardingSide(stepConfig.side);
+        return {
+          element: stepConfig.selector ? resolveVisibleElement(stepConfig.selector) : undefined,
+          disableActiveInteraction: !(stepConfig.canClickTarget ?? false),
+          popover: {
+            side,
+            align,
+            showButtons: [],
+            popoverClass: ["onboarding-popover", stepConfig.className].filter(Boolean).join(" "),
+            onPopoverRender: (popover: PopoverDOM) => {
+              popover.wrapper.querySelectorAll("[data-onboarding-root]").forEach((n) => n.remove());
+              const container = document.createElement("div");
+              container.setAttribute("data-onboarding-root", "");
+              const root = createRoot(container);
+              /* driver.js re-renders the popover on refresh(), so the same step can
+                 render twice; drop the root the previous render left behind. */
+              const prev = rootsRef.current.get(index);
+              if (prev) unmountRoot(prev);
+              rootsRef.current.set(index, root);
+              const cardProps = {
+                step: stepConfig,
+                currentIndex: index,
+                totalSteps: tourSteps.length,
+                labels,
+                onNext: () => move("next", index),
+                onPrevious: () => move("previous", index),
+                onClose: () => end(index === tourSteps.length - 1 ? "finished" : "skipped"),
+                onSkip: () => end("skipped"),
+                isFirst: index === 0,
+                isLast: index === tourSteps.length - 1,
+              };
+              /* driver.js positions the popover right after this hook returns (renderPopover
+                 calls onRender, then repositionPopover), so the card has to be in the DOM at
+                 its real size by then — an async render would be measured as an empty box and
+                 the card would overflow the viewport near a page edge. */
+              flushSync(() => {
+                root.render(renderCard ? renderCard(cardProps) : <OnboardingCard {...cardProps} />);
+              });
+              popover.wrapper.appendChild(container);
             },
           },
-        });
+          onHighlightStarted: () => {
+            setIsTourActive(true);
+            setCurrentStepIndex(index);
+            stepConfig.onShow?.();
+          },
+          onDeselected: () => {
+            stepConfig.onHide?.();
+            const root = rootsRef.current.get(index);
+            if (root) {
+              rootsRef.current.delete(index);
+              unmountRoot(root);
+            }
+          },
+        };
+      });
+
+      const instance = driver({
+        steps: driveSteps,
+        animate: true,
+        allowClose: true,
+        overlayOpacity: 0.75,
+        stagePadding: 8,
+        stageRadius: 8,
+        smoothScroll: true,
+        skipMissingElement: true,
+        showButtons: [],
+        onDestroyed: () => teardown(endReasonRef.current),
       });
 
-      tourRef.current = tour;
-      tour.start();
+      driverRef.current = instance;
+      instance.drive();
     },
-    [tours, labels, renderCard, closeTour, cleanupRoots],
+    [tours, labels, renderCard, closeTour, teardown],
   );
 
-  // Cleanup on unmount
   useEffect(() => {
     return () => {
-      if (tourRef.current) {
-        tourRef.current.cancel();
-      }
+      driverRef.current?.destroy();
       cleanupRoots();
     };
   }, [cleanupRoots]);
@@ -206,8 +259,6 @@ export function OnboardingProvider({
 
 export function useOnboarding(): OnboardingContextValue {
   const context = useContext(OnboardingContext);
-  if (!context) {
-    throw new Error("useOnboarding must be used within an OnboardingProvider");
-  }
+  if (!context) throw new Error("useOnboarding must be used within an OnboardingProvider");
   return context;
 }

package/src/features/onboarding/interfaces/onboarding.interface.ts

@@ -70,6 +70,8 @@ export interface OnboardingContextValue {
   totalSteps: number;
 }
 
+export type OnboardingTourEndReason = "finished" | "skipped" | "dismissed";
+
 export interface OnboardingProviderProps {
   children: React.ReactNode;
   tours?: OnboardingTourConfig[];
@@ -77,6 +79,8 @@ export interface OnboardingProviderProps {
   labels?: OnboardingLabels;
   renderCard?: (props: OnboardingCardRenderProps) => ReactNode;
   zIndex?: number;
+  /** Fires once when a tour ends. "finished" = last-step Finish, "skipped" = card Skip/close, "dismissed" = overlay click or Escape. */
+  onTourEnd?: (tourId: string, reason: OnboardingTourEndReason) => void;
 }
 
 export interface OnboardingCardRenderProps {