@carlonicora/nextjs-jsonapi 3.8.2 → 3.10.0

package/src/features/assistant-action/components/__tests__/ApprovalActionCard.spec.tsx

@@ -0,0 +1,268 @@
+import { render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ApprovalActionCard } from "../ApprovalActionCard";
+
+const findOne = vi.fn();
+const approve = vi.fn();
+const deny = vi.fn();
+
+vi.mock("../../data/AssistantActionService", () => ({
+  AssistantActionService: {
+    findOne: (params: { id: string }) => findOne(params),
+    approve: (params: { id: string }) => approve(params),
+    deny: (params: { id: string }) => deny(params),
+  },
+}));
+
+/** Any uuid-ish run of hex — no id may ever reach the screen. */
+const UUID_LIKE = /[0-9a-f]{8}-[0-9a-f]{4}-/;
+
+const CREATE_TOOL_ARGS = JSON.stringify({
+  type: "npcs",
+  attributes: { name: "Marcus", tldr: "A nerd with bouts of rage" },
+  relationships: { related: { data: [{ type: "npcs", id: "042ec319-9d3c-4f0a-9a6c-1a2b3c4d5e6f" }] } },
+});
+
+const CREATE_PROPOSAL = JSON.stringify({
+  type: "npcs",
+  attributes: { name: "Marcus", tldr: "A nerd with bouts of rage" },
+  relationships: {
+    related: [{ id: "042ec319-9d3c-4f0a-9a6c-1a2b3c4d5e6f", type: "npcs", label: "Zoe" }],
+  },
+});
+
+function makeAction(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "act-1",
+    status: "pending",
+    toolName: "create_entity",
+    toolArgs: CREATE_TOOL_ARGS,
+    proposal: CREATE_PROPOSAL,
+    summary: 'Create a new npcs record named "Marcus".',
+    ...overrides,
+  } as any;
+}
+
+describe("ApprovalActionCard", () => {
+  beforeEach(() => {
+    findOne.mockReset();
+    approve.mockReset();
+    deny.mockReset();
+  });
+
+  it("renders the proposed record: the attributes and the related records by name", async () => {
+    findOne.mockResolvedValue(makeAction());
+
+    render(<ApprovalActionCard actionId="act-1" />);
+
+    // summary still renders
+    expect(await screen.findByText('Create a new npcs record named "Marcus".')).toBeInTheDocument();
+    // attributes
+    expect(await screen.findByText("Marcus")).toBeInTheDocument();
+    expect(screen.getByText("A nerd with bouts of rage")).toBeInTheDocument();
+    expect(screen.getByText("Name")).toBeInTheDocument();
+    // relationships: humanised key + the resolved display names, never ids
+    expect(screen.getByText("Related")).toBeInTheDocument();
+    expect(screen.getByText("Zoe")).toBeInTheDocument();
+    expect(screen.queryByText(UUID_LIKE)).toBeNull();
+    // buttons are actionable while the action is pending
+    expect(screen.getByRole("button", { name: "features.assistant.approval.approve" })).toBeEnabled();
+    expect(screen.getByRole("button", { name: "features.assistant.approval.deny" })).toBeEnabled();
+  });
+
+  it("renders booleans as Yes/No and numbers as-is", async () => {
+    findOne.mockResolvedValue(
+      makeAction({
+        proposal: JSON.stringify({
+          type: "factions",
+          attributes: { name: "The Cinder Pact", secret: true, rank: 3 },
+        }),
+      }),
+    );
+
+    render(<ApprovalActionCard actionId="act-1" />);
+
+    expect(await screen.findByText("The Cinder Pact")).toBeInTheDocument();
+    expect(screen.getByText("features.assistant.approval.proposal.yes")).toBeInTheDocument();
+    expect(screen.getByText("3")).toBeInTheDocument();
+  });
+
+  it("renders the plain text of a BlockNote document value", async () => {
+    const document = JSON.stringify([
+      { id: "1", type: "paragraph", content: [{ type: "text", text: "First line" }], children: [] },
+      {
+        id: "2",
+        type: "paragraph",
+        content: [
+          { type: "text", text: "Second " },
+          { type: "text", text: "line" },
+        ],
+      },
+    ]);
+    findOne.mockResolvedValue(
+      makeAction({ proposal: JSON.stringify({ type: "npcs", attributes: { description: document } }) }),
+    );
+
+    render(<ApprovalActionCard actionId="act-1" />);
+
+    // identity normalizer: the default one collapses the newline the reducer emits
+    expect(await screen.findByText("First line\nSecond line", { normalizer: (text) => text })).toBeInTheDocument();
+  });
+
+  it("skips null, undefined and empty attribute rows", async () => {
+    findOne.mockResolvedValue(
+      makeAction({
+        proposal: JSON.stringify({
+          type: "npcs",
+          attributes: { name: "Marcus", tldr: null, notes: "", tags: [] },
+        }),
+      }),
+    );
+
+    render(<ApprovalActionCard actionId="act-1" />);
+
+    expect(await screen.findByText("Marcus")).toBeInTheDocument();
+    expect(screen.queryByText("Tldr")).not.toBeInTheDocument();
+    expect(screen.queryByText("Notes")).not.toBeInTheDocument();
+    expect(screen.queryByText("Tags")).not.toBeInTheDocument();
+  });
+
+  it("shows the target record's name — never its id — for an update_entity proposal", async () => {
+    findOne.mockResolvedValue(
+      makeAction({
+        toolName: "update_entity",
+        summary: 'Update the npcs record "Marcus" (name).',
+        toolArgs: JSON.stringify({
+          type: "npcs",
+          id: "npc-9d3c4f0a-1a2b-4c4d-9a6c-042ec3199d3c",
+          attributes: { name: "Marcus the Calm" },
+        }),
+        proposal: JSON.stringify({
+          type: "npcs",
+          target: { id: "9d3c4f0a-1a2b-4c4d-9a6c-042ec3199d3c", type: "npcs", label: "Marcus" },
+          attributes: { name: "Marcus the Calm" },
+        }),
+      }),
+    );
+
+    render(<ApprovalActionCard actionId="act-1" />);
+
+    expect(await screen.findByText("features.assistant.approval.proposal.updateHeading")).toBeInTheDocument();
+    expect(screen.getByText("Marcus")).toBeInTheDocument();
+    expect(screen.getByText("Marcus the Calm")).toBeInTheDocument();
+    expect(screen.queryByText(UUID_LIKE)).toBeNull();
+  });
+
+  it("shows the relationship name and the linked records for a link proposal", async () => {
+    findOne.mockResolvedValue(
+      makeAction({
+        toolName: "link_entities",
+        summary: 'Link "Zoe", "Bob" to the "related" relationship of the npcs record "Marcus".',
+        proposal: JSON.stringify({
+          type: "npcs",
+          target: { id: "9d3c4f0a-1a2b-4c4d-9a6c-042ec3199d3c", type: "npcs", label: "Marcus" },
+          relationship: "related",
+          targets: [
+            { id: "042ec319-9d3c-4f0a-9a6c-1a2b3c4d5e6f", type: "npcs", label: "Zoe" },
+            { id: "c81d6ac7-1a2b-4c4d-9a6c-042ec3199d3c", type: "npcs", label: "Bob" },
+          ],
+        }),
+      }),
+    );
+
+    render(<ApprovalActionCard actionId="act-1" />);
+
+    expect(await screen.findByText("features.assistant.approval.proposal.relationship")).toBeInTheDocument();
+    expect(screen.getByText("Related")).toBeInTheDocument();
+    expect(screen.getByText("features.assistant.approval.proposal.records")).toBeInTheDocument();
+    expect(screen.getByText("Zoe, Bob")).toBeInTheDocument();
+    expect(screen.getByText("Marcus")).toBeInTheDocument();
+    expect(screen.queryByText(UUID_LIKE)).toBeNull();
+  });
+
+  it("shows the unlinked records by name for an unlink proposal", async () => {
+    findOne.mockResolvedValue(
+      makeAction({
+        toolName: "unlink_entities",
+        summary: 'Unlink "Zoe" from the "related" relationship of the npcs record "Marcus".',
+        proposal: JSON.stringify({
+          type: "npcs",
+          target: { id: "9d3c4f0a-1a2b-4c4d-9a6c-042ec3199d3c", type: "npcs", label: "Marcus" },
+          relationship: "related",
+          targets: [{ id: "042ec319-9d3c-4f0a-9a6c-1a2b3c4d5e6f", type: "npcs", label: "Zoe" }],
+        }),
+      }),
+    );
+
+    render(<ApprovalActionCard actionId="act-1" />);
+
+    expect(await screen.findByText("Zoe")).toBeInTheDocument();
+    expect(screen.getByText("features.assistant.approval.proposal.records")).toBeInTheDocument();
+    expect(screen.queryByText(UUID_LIKE)).toBeNull();
+  });
+
+  it("hides the relationship rows named by hiddenRelationshipKeys, and shows them when it does not", async () => {
+    // The write tools force the run's own scope and discard the model's, so
+    // the host app hides that relationship rather than showing a record the
+    // write may not even end up using.
+    const proposal = JSON.stringify({
+      type: "npcs",
+      attributes: { name: "Marcus" },
+      relationships: {
+        campaign: [{ id: "c81d6ac7-1a2b-4c4d-9a6c-042ec3199d3c", type: "campaigns", label: "The Ashen Crown" }],
+        related: [{ id: "042ec319-9d3c-4f0a-9a6c-1a2b3c4d5e6f", type: "npcs", label: "Zoe" }],
+      },
+    });
+    findOne.mockResolvedValue(makeAction({ proposal }));
+
+    const hidden = render(<ApprovalActionCard actionId="act-1" hiddenRelationshipKeys={["campaign"]} />);
+
+    expect(await screen.findByText("Marcus")).toBeInTheDocument();
+    expect(screen.queryByText("Campaign")).not.toBeInTheDocument();
+    expect(screen.queryByText("The Ashen Crown")).not.toBeInTheDocument();
+    // the relationships that are not listed keep rendering
+    expect(screen.getByText("Related")).toBeInTheDocument();
+    expect(screen.getByText("Zoe")).toBeInTheDocument();
+
+    hidden.unmount();
+    render(<ApprovalActionCard actionId="act-1" />);
+
+    expect(await screen.findByText("Campaign")).toBeInTheDocument();
+    expect(screen.getByText("The Ashen Crown")).toBeInTheDocument();
+    expect(screen.queryByText(UUID_LIKE)).toBeNull();
+  });
+
+  it("falls back to the toolArgs attributes — and to no relationship rows — for a legacy action", async () => {
+    findOne.mockResolvedValue(
+      makeAction({
+        proposal: "",
+        toolArgs: JSON.stringify({
+          type: "npcs",
+          fields: { name: "Marcus", tldr: "A nerd with bouts of rage" },
+          relationships: { related: { data: [{ type: "npcs", id: "042ec319-9d3c-4f0a-9a6c-1a2b3c4d5e6f" }] } },
+        }),
+      }),
+    );
+
+    render(<ApprovalActionCard actionId="act-1" />);
+
+    // attributes still render (`fields` is the key the create_entity tool emits)
+    expect(await screen.findByText("Marcus")).toBeInTheDocument();
+    expect(screen.getByText("A nerd with bouts of rage")).toBeInTheDocument();
+    // relationships from toolArgs carry ids only — no row, and no id on screen
+    expect(screen.queryByText("Related")).not.toBeInTheDocument();
+    expect(screen.queryByText(UUID_LIKE)).toBeNull();
+  });
+
+  it("still renders the summary and the buttons when neither payload parses", async () => {
+    findOne.mockResolvedValue(makeAction({ proposal: "{not-json", toolArgs: "{not-json" }));
+
+    render(<ApprovalActionCard actionId="act-1" />);
+
+    expect(await screen.findByText('Create a new npcs record named "Marcus".')).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "features.assistant.approval.approve" })).toBeEnabled();
+    expect(screen.getByRole("button", { name: "features.assistant.approval.deny" })).toBeEnabled();
+    expect(screen.queryByText("features.assistant.approval.proposal.heading")).not.toBeInTheDocument();
+    expect(screen.queryByText(UUID_LIKE)).toBeNull();
+  });
+});

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

@@ -4,6 +4,8 @@ import { AssistantActionInput, AssistantActionInterface, AssistantActionStatus }
 export class AssistantAction extends AbstractApiData implements AssistantActionInterface {
   private _status?: AssistantActionStatus;
   private _toolName?: string;
+  private _toolArgs?: string;
+  private _proposal?: string;
   private _summary?: string;
   private _resolvedAt?: Date;
   private _expiresAt?: Date;
@@ -17,6 +19,14 @@ export class AssistantAction extends AbstractApiData implements AssistantActionI
     return this._toolName ?? "";
   }
 
+  get toolArgs(): string {
+    return this._toolArgs ?? "";
+  }
+
+  get proposal(): string {
+    return this._proposal ?? "";
+  }
+
   get summary(): string {
     return this._summary ?? "";
   }
@@ -34,6 +44,8 @@ export class AssistantAction extends AbstractApiData implements AssistantActionI
 
     this._status = data.jsonApi.attributes.status;
     this._toolName = data.jsonApi.attributes.toolName;
+    this._toolArgs = data.jsonApi.attributes.toolArgs;
+    this._proposal = data.jsonApi.attributes.proposal;
     this._summary = data.jsonApi.attributes.summary;
     this._resolvedAt = data.jsonApi.attributes.resolvedAt ? new Date(data.jsonApi.attributes.resolvedAt) : undefined;
     this._expiresAt = data.jsonApi.attributes.expiresAt ? new Date(data.jsonApi.attributes.expiresAt) : undefined;

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/);
+  });
+});