packages/shared-onboarding/          # Reusable engine (no app imports)
├── src/
│   ├── types.ts                     # Tour, OnboardingStep, Placement, Align
│   ├── OnboardingProvider.tsx       # React context: useReducer state machine
│   ├── useOnboarding.ts            # Consumer hook: startTour, nextStep, etc.
│   ├── ShowcaseModal.tsx            # Fullscreen modal (lazy-loaded)
│   ├── GuidedOverlay.tsx            # Spotlight overlay (lazy-loaded)
│   ├── GuidedTooltip.tsx            # Radix Popover tooltip (side, align, sideOffset)
│   ├── storage.ts                   # localStorage: markTourCompleted, isTourCompleted
│   └── index.ts                     # Public exports

apps/raamattu-nyt/src/onboarding/    # App-level tour definitions
├── tours/
│   ├── showcaseHome.ts              # Showcase tour (7 steps, i18n keys + CTA)
│   ├── searchBasics.ts              # Guided tour: search basics (4 steps)
│   ├── searchQuestionsTab.ts        # Guided tour: Q&A tab (4 steps)
│   └── index.ts                     # useAllTours() hook: resolves i18n + images + overrides

apps/raamattu-nyt/src/hooks/
└── useOnboardingImages.ts           # Fetches images + guided overrides from app_config

apps/raamattu-nyt/src/pages/
└── AdminOnboardingPage.tsx          # Admin: tour list, image upload, guided placement

import type { Tour } from "@shared-onboarding";

interface ShowcaseStepDef {
  id: string;
  titleKey: string;
  descriptionKey: string;
  ctaKey?: string;
  ctaHref?: string;
}

const myTourDef: ShowcaseStepDef[] = [
  {
    id: "step1",
    titleKey: "onboarding.showcase.myTour.step1.title",
    descriptionKey: "onboarding.showcase.myTour.step1.description",
  },
];

export function createMyTour(
  images?: Record<string, string>,
  t?: (key: string) => string,
): Tour {
  const tr = t ?? ((key: string) => key);
  return {
    id: "my-tour",
    mode: "showcase",
    steps: myTourDef.map((def) => ({
      id: def.id,
      title: tr(def.titleKey),
      description: tr(def.descriptionKey),
      image: images?.[def.id],
      cta: def.ctaKey ? { label: tr(def.ctaKey), href: def.ctaHref } : undefined,
    })),
  };
}

export const myTour: Tour = createMyTour();

import type { GuidedStepDef } from "./searchBasics";

export const myGuidedDef: { id: string; mode: "guided"; steps: GuidedStepDef[] } = {
  id: "my-guided-tour",
  mode: "guided",
  steps: [
    {
      id: "first-element",
      titleKey: "onboarding.guided.myTour.first.title",
      descriptionKey: "onboarding.guided.myTour.first.description",
      target: '[data-onboard="my-first-element"]',
      placement: "bottom",
      align: "center",
      sideOffset: 12,
    },
  ],
};

const [searchParams] = useSearchParams();
const { startTour } = useOnboarding();
const tourTriggered = useRef(false);

useEffect(() => {
  const tourId = searchParams.get("tour");
  if (tourId && !tourTriggered.current) {
    tourTriggered.current = true;
    setTimeout(() => startTour(tourId), 500);
  }
}, []);

// packages/shared-onboarding/src/types.ts
type TourMode = "showcase" | "guided";
type Placement = "top" | "bottom" | "left" | "right";
type Align = "start" | "center" | "end";

interface OnboardingStep {
  id: string;
  title: string;
  description: string;
  image?: string;           // Showcase only
  target?: string;          // Guided only: CSS selector
  placement?: Placement;    // Guided only
  align?: Align;            // Guided only
  sideOffset?: number;      // Guided only (default 12)
  cta?: { label: string; href?: string; action?: () => void };
  beforeStep?: () => void | Promise<void>;
}

interface Tour { id: string; mode: TourMode; steps: OnboardingStep[] }

idle → START(tourId) → active { tourId, stepIndex: 0 }
     → NEXT          → stepIndex++ (or COMPLETE if last)
     → PREV          → stepIndex-- (min 0)
     → SKIP/COMPLETE → completed { tourId } → idle