Getting started

Add a product tour to this app with Hintbeam (https://hintbeam.js.org). First download https://hintbeam.js.org/llms-full.txt and read all of it (for example with curl; a summarised fetch leaves out details you need). It is the complete documentation. Then:
1. Detect the framework (Next.js App Router, React Router, Expo Router, React Navigation or plain React) and install `hintbeam`.
2. Follow "Getting started" for that framework: list the targets with `defineTargets` in `tours.ts`, add the `declare module "hintbeam"` Register block, and wrap the app in `TourProvider` with the matching router adapter and storage (`browserTourStorage()` on the web, `createTourStorage(AsyncStorage)` on React Native).
3. Ask me which flow to guide, or propose a 3–5 step first-run tour of the main screens.
4. Attach `useTarget("name")` to those elements. Never use CSS selectors. In the Next.js App Router, keep pages as Server Components and put the tagged elements in small "use client" components; import `tours.ts` only from client files.
5. Write the tour with `defineTour`, and start it with `useTour().startOnce(tour)` from a client component rendered inside `TourProvider`.
6. Run the type check, the build and the tests (say so if the project has none), then show me the diff.

npm install hintbeam

import { defineTargets, defineTour } from "hintbeam";

export const targets = defineTargets({
  search:   { screen: "/food",     about: "The food search box" },
  logMeal:  { screen: "/food",     about: "The button that logs a meal" },
  weight:   { screen: "/progress", about: "This week's weight chart" },
  helpIcon: {                      about: "The ? in the header, on every page" },
});

// Lets TypeScript check every useTarget("…") name against this list.
declare module "hintbeam" {
  interface Register {
    targets: typeof targets;
  }
}

export const firstMeal = defineTour(targets, {
  id: "first-meal",
  steps: [
    { target: "search",  title: "Find food", text: "Search anything you ate." },
    { target: "logMeal", text: "Log it with one tap.", advanceOn: "tap" },
    { target: "weight",  text: "Your progress lives here." },
  ],
});

import { TourProvider } from "hintbeam";
import { useReactRouter } from "hintbeam/react-router";
import { targets } from "./tours";

function Tours({ children }) {
  return <TourProvider targets={targets} router={useReactRouter()}>{children}</TourProvider>;
}

// Inside your <BrowserRouter> / <RouterProvider> tree:
<Tours><App /></Tours>

// app/tour-provider.tsx
"use client";
import { TourProvider, browserTourStorage } from "hintbeam";
import { useNextRouter } from "hintbeam/next";
import { targets } from "./tours";

// Remembers who finished or skipped a tour. Safe during server rendering.
const storage = browserTourStorage();

export function Tours({ children }: { children: React.ReactNode }) {
  return (
    <TourProvider targets={targets} router={useNextRouter()} storage={storage}>
      {children}
    </TourProvider>
  );
}

// app/layout.tsx (stays a Server Component)
<body><Tours>{children}</Tours></body>

// app/_layout.tsx
import { Stack } from "expo-router";
import { TourProvider } from "hintbeam";
import { useExpoRouter } from "hintbeam/expo-router";
import { targets } from "../tours";

export default function Root() {
  return (
    <TourProvider targets={targets} router={useExpoRouter()}>
      <Stack />
    </TourProvider>
  );
}

import { NavigationContainer, createNavigationContainerRef } from "@react-navigation/native";
import { TourProvider } from "hintbeam";
import { useReactNavigation } from "hintbeam/react-navigation";

const navigationRef = createNavigationContainerRef();

export default function App() {
  return (
    <TourProvider targets={targets} router={useReactNavigation(navigationRef)}>
      <NavigationContainer ref={navigationRef}>
        <RootStack /> {/* your navigator */}
      </NavigationContainer>
    </TourProvider>
  );
}

import { useTarget } from "hintbeam";

function FoodPage() {
  const search = useTarget("search");
  const logMeal = useTarget("logMeal");
  return (
    <>
      <input ref={search} placeholder="Search" />          {/* web */}
      <button ref={logMeal}>Log meal</button>
    </>
  );
}
// React Native: <TextInput ref={search} />, <Pressable ref={logMeal} />

// app/food/search-box.tsx
"use client";
import { useTarget } from "hintbeam";

export function SearchBox() {
  return <input ref={useTarget("search")} placeholder="Search" />;
}

"use client";
import { useTour } from "hintbeam";
import { firstMeal } from "./tours";

export function HelpMenu() {
  const { start } = useTour();
  return <button onClick={() => start(firstMeal)}>Show me around</button>;
}

"use client";
import { useEffect } from "react";
import { useTour } from "hintbeam";
import { firstMeal } from "./tours";

export function FirstVisitTour() {
  const { startOnce } = useTour();
  useEffect(() => {
    void startOnce(firstMeal);
  }, [startOnce]);
  return null;
}

import { TourProvider, createTourTheme } from "hintbeam";

const theme = createTourTheme({ brand: "#E5484D", mode: "light", style: "balanced" });

<TourProvider targets={targets} router={…} theme={theme}>

// jest.config.js
module.exports = {
  // …your config
  transformIgnorePatterns: ["/node_modules/(?!hintbeam/)"],
};