@tribe-nest/forge 1.13.0

package/src/ui/headless/community/useCommunitySpaceFeed.ts

@@ -0,0 +1,122 @@
+import { useEffect, useMemo } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import {
+  applyReactionDelta,
+  bumpFeedReplyCount,
+  prependPostToFeed,
+  useCommunitySocket,
+  useCommunitySpacePosts,
+  useCommunitySpaces,
+  useCreateCommunityPost,
+  useJoinCommunitySpace,
+  useLeaveCommunitySpace,
+  useToggleCommunityReaction,
+  type CommunityPost,
+  type CommunityReactionEvent,
+  type CommunityReply,
+} from "../../../data/queries/useCommunity";
+
+/**
+ * Headless space feed: the space (from the gated spaces list), its paginated
+ * posts, realtime new-post/reaction updates over the shared Socket.io gateway
+ * (room `community:<spaceId>`, joined via `communityJoinSpace` exactly like
+ * chat joins channels), plus create-post and toggle-reaction actions.
+ *
+ * The single primitive a creator needs to rebuild a space feed page.
+ *
+ * `idOrSlug` accepts either a space uuid or its per-profile slug — the space is
+ * resolved from the gated spaces list by id OR slug, so slug-addressed deep
+ * links load the right space without a separate lookup.
+ */
+export function useCommunitySpaceFeed(idOrSlug?: string) {
+  const { user } = usePublicAuth();
+  const queryClient = useQueryClient();
+
+  const { data: spaces = [], isLoading: spacesLoading } = useCommunitySpaces();
+  const space = useMemo(
+    () => spaces.find((s) => s.id === idOrSlug || s.slug === idOrSlug) ?? null,
+    [spaces, idOrSlug],
+  );
+  // Downstream hooks (posts, realtime room, create) are keyed by the canonical
+  // space uuid — only wire them up once the space resolves from the list, so a
+  // slug-addressed link never leaks a slug into a uuid-keyed request/room.
+  const spaceId = space?.id;
+
+  const {
+    data: postPages,
+    isLoading: postsLoading,
+    fetchNextPage,
+    hasNextPage,
+    isFetchingNextPage,
+  } = useCommunitySpacePosts(spaceId);
+  const posts = useMemo(() => postPages?.pages.flatMap((p) => p.data) ?? [], [postPages]);
+
+  const createPost = useCreateCommunityPost(spaceId);
+  const toggleReaction = useToggleCommunityReaction();
+  const joinSpace = useJoinCommunitySpace();
+  const leaveSpace = useLeaveCommunitySpace();
+
+  // ── Realtime ───────────────────────────────────────────────────────────────
+  const socket = useCommunitySocket(!!user);
+
+  useEffect(() => {
+    if (!socket || !spaceId) return;
+    const onMessage = (data: {
+      event?: string;
+      data?: {
+        spaceId?: string;
+        postId?: string;
+        post?: CommunityPost;
+        reply?: CommunityReply;
+      } & Partial<CommunityReactionEvent>;
+    }) => {
+      if (data.event === "communityNewPost" && data.data?.spaceId === spaceId && data.data?.post) {
+        prependPostToFeed(queryClient, spaceId, data.data.post);
+      }
+      if (data.event === "communityNewReply" && data.data?.spaceId === spaceId && data.data?.postId) {
+        bumpFeedReplyCount(queryClient, spaceId, data.data.postId);
+      }
+      if (data.event === "communityReaction" && data.data?.entityId && data.data?.accountId !== user?.id) {
+        applyReactionDelta(queryClient, data.data as CommunityReactionEvent);
+      }
+    };
+    socket.on("message", onMessage);
+    return () => {
+      socket.off("message", onMessage);
+    };
+  }, [socket, spaceId, queryClient, user?.id]);
+
+  // Join/leave the space room (mirrors chatJoinChannel).
+  useEffect(() => {
+    if (!spaceId || !socket) return;
+    const join = () => socket.emit("communityJoinSpace", { spaceId });
+    if (socket.connected) join();
+    socket.on("connect", join);
+    return () => {
+      socket.off("connect", join);
+      socket.emit("communityLeaveSpace", { spaceId });
+    };
+  }, [spaceId, socket]);
+
+  return {
+    space,
+    spaces,
+    spacesLoading,
+    posts,
+    postsLoading,
+    fetchNextPage,
+    hasMore: !!hasNextPage && !isFetchingNextPage,
+    currentAccountId: user?.id,
+    // Belonging — tiers govern access, join governs new-post notifications.
+    isJoined: space?.isJoined ?? false,
+    memberCount: space?.memberCount ?? null,
+    joinPending: joinSpace.isPending || leaveSpace.isPending,
+    // Actions
+    createPost,
+    join: () => spaceId && joinSpace.mutate(spaceId),
+    leave: () => spaceId && leaveSpace.mutate(spaceId),
+    react: (entityId: string, emoji: string) =>
+      toggleReaction.mutate({ entityType: "community_post", entityId, emoji, spaceId }),
+  };
+}

package/src/ui/headless/community/useCommunityThread.ts

@@ -0,0 +1,95 @@
+import { useEffect, useMemo } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import {
+  appendReplyToThread,
+  applyReactionDelta,
+  useCommunityPost,
+  useCommunityReplies,
+  useCommunitySocket,
+  useCreateCommunityReply,
+  useToggleCommunityReaction,
+  type CommunityReactionEvent,
+  type CommunityReply,
+  type ReactableEntityType,
+} from "../../../data/queries/useCommunity";
+import { buildReplyTree } from "./replyTree";
+
+/**
+ * Headless post thread: the post, its full reply tree (assembled from the flat
+ * pages — data nesting is unlimited, display capping is the renderer's job),
+ * realtime reply/reaction updates via the post's space room, plus reply and
+ * toggle-reaction actions.
+ */
+export function useCommunityThread(postId?: string) {
+  const { user } = usePublicAuth();
+  const queryClient = useQueryClient();
+
+  const { data: post, isLoading: postLoading, error: postError } = useCommunityPost(postId);
+  const {
+    data: replyPages,
+    isLoading: repliesLoading,
+    fetchNextPage,
+    hasNextPage,
+    isFetchingNextPage,
+  } = useCommunityReplies(postId);
+
+  const replies = useMemo(() => replyPages?.pages.flatMap((p) => p.data) ?? [], [replyPages]);
+  const replyTree = useMemo(() => buildReplyTree(replies), [replies]);
+
+  const createReply = useCreateCommunityReply(postId);
+  const toggleReaction = useToggleCommunityReaction();
+
+  const spaceId = post?.spaceId;
+
+  // ── Realtime (same space room the feed uses) ──────────────────────────────
+  const socket = useCommunitySocket(!!user);
+
+  useEffect(() => {
+    if (!socket || !postId) return;
+    const onMessage = (data: {
+      event?: string;
+      data?: { spaceId?: string; postId?: string; reply?: CommunityReply } & Partial<CommunityReactionEvent>;
+    }) => {
+      if (data.event === "communityNewReply" && data.data?.postId === postId && data.data?.reply) {
+        // Skip own replies — the mutation already appended them.
+        if (data.data.reply.authorAccountId === user?.id) return;
+        appendReplyToThread(queryClient, postId, data.data.reply);
+      }
+      if (data.event === "communityReaction" && data.data?.entityId && data.data?.accountId !== user?.id) {
+        applyReactionDelta(queryClient, data.data as CommunityReactionEvent, { postId });
+      }
+    };
+    socket.on("message", onMessage);
+    return () => {
+      socket.off("message", onMessage);
+    };
+  }, [socket, postId, queryClient, user?.id]);
+
+  useEffect(() => {
+    if (!spaceId || !socket) return;
+    const join = () => socket.emit("communityJoinSpace", { spaceId });
+    if (socket.connected) join();
+    socket.on("connect", join);
+    return () => {
+      socket.off("connect", join);
+      socket.emit("communityLeaveSpace", { spaceId });
+    };
+  }, [spaceId, socket]);
+
+  return {
+    post,
+    postLoading,
+    postError,
+    replies,
+    replyTree,
+    repliesLoading,
+    fetchNextPage,
+    hasMore: !!hasNextPage && !isFetchingNextPage,
+    currentAccountId: user?.id,
+    // Actions
+    createReply,
+    react: (entityType: Extract<ReactableEntityType, "community_post" | "community_reply">, entityId: string, emoji: string) =>
+      toggleReaction.mutate({ entityType, entityId, emoji, spaceId, postId }),
+  };
+}

package/src/ui/headless/community/useMentionComposer.ts

@@ -0,0 +1,105 @@
+import { useCallback, useMemo, useState } from "react";
+import {
+  communityMemberName,
+  useCommunityMentionDirectory,
+  type CommunityLeaderboardEntry,
+} from "../../../data/queries/useCommunity";
+import { buildLexicalState, mentionsInText, type MentionRef } from "./lexical";
+
+export interface MentionSuggestion {
+  accountId: string;
+  name: string;
+  avatarUrl: string | null;
+  level: number;
+}
+
+/**
+ * Headless @mention textarea state machine. Track the draft + caret; when the
+ * text before the caret ends in an `@query` token, `suggestions` lights up with
+ * matching members (from the community member directory). `insertMention`
+ * replaces the token and records the ref so `getBody()` can emit Lexical
+ * mention nodes + explicit mentionedAccountIds.
+ */
+export function useMentionComposer(initialText = "") {
+  const [text, setText] = useState(initialText);
+  const [caret, setCaret] = useState(initialText.length);
+  const [trackedMentions, setTrackedMentions] = useState<MentionRef[]>([]);
+  const { data: directory = [] } = useCommunityMentionDirectory();
+
+  const members: MentionSuggestion[] = useMemo(
+    () =>
+      directory.map((m: CommunityLeaderboardEntry) => ({
+        accountId: m.accountId,
+        name: communityMemberName(m),
+        avatarUrl: m.avatarUrl,
+        level: m.level,
+      })),
+    [directory],
+  );
+
+  /** The active "@query" token immediately before the caret, if any. */
+  const activeToken = useMemo(() => {
+    const upToCaret = text.slice(0, caret);
+    const match = /(^|\s)@([^\s@]{0,40})$/.exec(upToCaret);
+    if (!match) return null;
+    return { query: match[2], start: caret - match[2].length - 1 };
+  }, [text, caret]);
+
+  const suggestions: MentionSuggestion[] = useMemo(() => {
+    if (!activeToken) return [];
+    const q = activeToken.query.toLowerCase();
+    return members
+      .filter((m) => m.name.toLowerCase().includes(q))
+      .slice(0, 6);
+  }, [activeToken, members]);
+
+  const onTextChange = useCallback((nextText: string, nextCaret: number) => {
+    setText(nextText);
+    setCaret(nextCaret);
+  }, []);
+
+  const insertMention = useCallback(
+    (member: MentionSuggestion) => {
+      if (!activeToken) return;
+      const before = text.slice(0, activeToken.start);
+      const after = text.slice(caret);
+      const inserted = `@${member.name} `;
+      const nextText = before + inserted + after;
+      setText(nextText);
+      setCaret(before.length + inserted.length);
+      setTrackedMentions((prev) =>
+        prev.some((m) => m.accountId === member.accountId)
+          ? prev
+          : [...prev, { accountId: member.accountId, name: member.name }],
+      );
+    },
+    [activeToken, text, caret],
+  );
+
+  /** Mentions that still literally appear in the draft (survive edits/deletes). */
+  const liveMentions = useMemo(() => mentionsInText(text, trackedMentions), [text, trackedMentions]);
+
+  /** Lexical editor state for the current draft, mention nodes included. */
+  const getBody = useCallback(() => buildLexicalState(text, liveMentions), [text, liveMentions]);
+
+  const reset = useCallback(() => {
+    setText("");
+    setCaret(0);
+    setTrackedMentions([]);
+  }, []);
+
+  return {
+    text,
+    onTextChange,
+    setCaret,
+    isEmpty: !text.trim(),
+    // Autocomplete
+    suggestions,
+    isSuggesting: !!activeToken && suggestions.length > 0,
+    insertMention,
+    // Submission
+    getBody,
+    mentionedAccountIds: liveMentions.map((m) => m.accountId),
+    reset,
+  };
+}

package/src/ui/headless/community/useRichMentionComposer.ts

@@ -0,0 +1,193 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import {
+  communityMemberName,
+  useCommunityMentionDirectory,
+  type CommunityLeaderboardEntry,
+} from "../../../data/queries/useCommunity";
+import type { MentionSuggestion } from "./useMentionComposer";
+import { collectMentions, isRichEmpty, serializeRichToLexical } from "./richLexical";
+
+export type { MentionSuggestion } from "./useMentionComposer";
+
+export type RichCommand = "bold" | "italic" | "underline" | "insertUnorderedList" | "insertOrderedList";
+
+/** The active "@query" token immediately before the caret, if any. */
+interface ActiveToken {
+  query: string;
+  /** The text node holding the token, and the char offset where `@` starts. */
+  textNode: Text;
+  atOffset: number;
+  caretOffset: number;
+}
+
+/**
+ * Headless rich-text + @mention composer over a contentEditable div. The DOM is
+ * the source of truth: formatting goes through `document.execCommand`, mentions
+ * are inserted as non-editable chip spans, and `getBody()` serializes the live
+ * DOM to the Lexical JSON CommunityRichText renders. Replaces the plain-text
+ * `useMentionComposer` for the community composer while keeping its onSubmit
+ * contract (body / mentionedAccountIds).
+ */
+export function useRichMentionComposer() {
+  const editorRef = useRef<HTMLDivElement | null>(null);
+  const [activeToken, setActiveToken] = useState<ActiveToken | null>(null);
+  // Bumps whenever DOM content changes so `isEmpty` recomputes.
+  const [tick, setTick] = useState(0);
+  const bump = useCallback(() => setTick((n) => n + 1), []);
+
+  const { data: directory = [] } = useCommunityMentionDirectory();
+
+  const members: MentionSuggestion[] = useMemo(
+    () =>
+      directory.map((m: CommunityLeaderboardEntry) => ({
+        accountId: m.accountId,
+        name: communityMemberName(m),
+        avatarUrl: m.avatarUrl,
+        level: m.level,
+      })),
+    [directory],
+  );
+
+  const suggestions: MentionSuggestion[] = useMemo(() => {
+    if (!activeToken) return [];
+    const q = activeToken.query.toLowerCase();
+    return members.filter((m) => m.name.toLowerCase().includes(q)).slice(0, 6);
+  }, [activeToken, members]);
+
+  /** Recompute the active @query token from the current selection. */
+  const detectToken = useCallback(() => {
+    const editor = editorRef.current;
+    if (!editor) return setActiveToken(null);
+    const sel = typeof window !== "undefined" ? window.getSelection() : null;
+    if (!sel || sel.rangeCount === 0 || !sel.isCollapsed) return setActiveToken(null);
+
+    const range = sel.getRangeAt(0);
+    const node = range.startContainer;
+    // Only text nodes inside the editor carry a typeable @query.
+    if (node.nodeType !== 3 || !editor.contains(node)) return setActiveToken(null);
+    const textNode = node as Text;
+    const caretOffset = range.startOffset;
+    const upToCaret = (textNode.textContent ?? "").slice(0, caretOffset);
+    const match = /(^|\s)@([^\s@]{0,40})$/.exec(upToCaret);
+    if (!match) return setActiveToken(null);
+    const query = match[2];
+    setActiveToken({ query, textNode, atOffset: caretOffset - query.length - 1, caretOffset });
+  }, []);
+
+  /** Fired on input/keyup/click/select — refresh emptiness + token. */
+  const onEditorChange = useCallback(() => {
+    bump();
+    detectToken();
+  }, [bump, detectToken]);
+
+  /** Run a formatting command against the current selection. */
+  const format = useCallback(
+    (command: RichCommand) => {
+      const editor = editorRef.current;
+      if (!editor) return;
+      editor.focus();
+      document.execCommand(command);
+      onEditorChange();
+    },
+    [onEditorChange],
+  );
+
+  /** Prompt for a URL and wrap the current selection in a link. */
+  const insertLink = useCallback(
+    (url?: string) => {
+      const editor = editorRef.current;
+      if (!editor) return;
+      editor.focus();
+      const href = url ?? (typeof window !== "undefined" ? window.prompt("Link URL") ?? "" : "");
+      if (!href.trim()) return;
+      const normalized = /^https?:\/\//i.test(href) || href.startsWith("/") ? href : `https://${href}`;
+      document.execCommand("createLink", false, normalized);
+      onEditorChange();
+    },
+    [onEditorChange],
+  );
+
+  /** Replace the active @token with a non-editable mention chip. */
+  const insertMention = useCallback(
+    (member: MentionSuggestion) => {
+      const editor = editorRef.current;
+      const token = activeToken;
+      if (!editor || !token) return;
+      const doc = editor.ownerDocument;
+      const sel = doc.defaultView?.getSelection();
+      if (!sel) return;
+
+      // Select the "@query" span and replace it with a chip + trailing space.
+      const range = doc.createRange();
+      range.setStart(token.textNode, token.atOffset);
+      range.setEnd(token.textNode, token.caretOffset);
+      range.deleteContents();
+
+      const chip = doc.createElement("span");
+      chip.setAttribute("data-account-id", member.accountId);
+      chip.setAttribute("data-mention-name", member.name);
+      chip.setAttribute("contenteditable", "false");
+      chip.textContent = `@${member.name}`;
+
+      const trailing = doc.createTextNode(" ");
+      range.insertNode(trailing);
+      range.insertNode(chip);
+
+      // Move the caret after the trailing space.
+      const after = doc.createRange();
+      after.setStartAfter(trailing);
+      after.collapse(true);
+      sel.removeAllRanges();
+      sel.addRange(after);
+
+      setActiveToken(null);
+      bump();
+    },
+    [activeToken, bump],
+  );
+
+  const getBody = useCallback(() => {
+    const editor = editorRef.current;
+    if (!editor) return serializeRichToLexical(document.createElement("div"));
+    return serializeRichToLexical(editor);
+  }, []);
+
+  const getMentionedAccountIds = useCallback(() => {
+    const editor = editorRef.current;
+    if (!editor) return [];
+    return collectMentions(editor).map((m) => m.accountId);
+  }, []);
+
+  const isEmpty = useMemo(() => {
+    // `tick` is the recompute trigger: it bumps on every DOM mutation.
+    void tick;
+    const editor = editorRef.current;
+    if (!editor) return true;
+    return isRichEmpty(editor);
+  }, [tick]);
+
+  const reset = useCallback(() => {
+    const editor = editorRef.current;
+    if (editor) editor.innerHTML = "";
+    setActiveToken(null);
+    bump();
+  }, [bump]);
+
+  return {
+    editorRef,
+    onEditorChange,
+    // Formatting
+    format,
+    insertLink,
+    // Autocomplete
+    suggestions,
+    isSuggesting: !!activeToken && suggestions.length > 0,
+    insertMention,
+    dismissSuggestions: () => setActiveToken(null),
+    // Submission / state
+    isEmpty,
+    getBody,
+    getMentionedAccountIds,
+    reset,
+  };
+}

package/src/ui/headless/consent/useCookieConsent.ts

@@ -0,0 +1,81 @@
+import { useCallback, useEffect, useState } from "react";
+import {
+  type CookieConsent,
+  getCookieConsent,
+  saveCookieConsent,
+  clearCookieConsent,
+  onCookieConsentChange,
+  DENY_ALL,
+  GRANT_ALL,
+} from "../../../utils/cookieConsent";
+
+export interface UseCookieConsentResult {
+  /** The current decision, or `null` if the visitor hasn't chosen yet. */
+  consent: CookieConsent | null;
+  /** False until the stored choice has been read from storage after mount. Gate
+   * an auto-showing banner on this so it doesn't flash for a returning visitor
+   * who already decided (whose decision only loads post-mount). */
+  ready: boolean;
+  /** True once a decision exists (used to show/hide a banner). */
+  decided: boolean;
+  /** Convenience booleans (false until decided). */
+  performance: boolean;
+  marketing: boolean;
+  /** Grant every category. */
+  acceptAll: () => void;
+  /** Reject everything but strictly-necessary. */
+  rejectAll: () => void;
+  /** Persist a specific set of choices (functional is forced on). */
+  save: (consent: Partial<CookieConsent>) => void;
+  /** Wipe the decision so the banner shows again (e.g. a "Cookie settings" link). */
+  reopen: () => void;
+}
+
+/**
+ * Headless cookie-consent state. Reads the shared consent store and stays in
+ * sync across components and tabs, so a banner and the analytics layer agree
+ * without prop-drilling. This is the primitive behind `<CookieConsent />` and
+ * the gate `<ForgeAnalytics />` uses — a creator can build their own banner on
+ * top of it.
+ */
+export function useCookieConsent(): UseCookieConsentResult {
+  // Always start `null` so the first client render matches the server (which has
+  // no `localStorage`). Reading storage during render would desync SSR ↔ client
+  // and abort hydration — leaving the banner visible but with no event handlers
+  // (dead toggles/buttons). Populate from storage after mount instead.
+  const [consent, setConsent] = useState<CookieConsent | null>(null);
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    setConsent(getCookieConsent());
+    setReady(true);
+    return onCookieConsentChange(() => setConsent(getCookieConsent()));
+  }, []);
+
+  const acceptAll = useCallback(() => saveCookieConsent(GRANT_ALL), []);
+  const rejectAll = useCallback(() => saveCookieConsent(DENY_ALL), []);
+  const save = useCallback(
+    (next: Partial<CookieConsent>) =>
+      saveCookieConsent({
+        functional: true,
+        performance: !!next.performance,
+        marketing: !!next.marketing,
+      }),
+    [],
+  );
+  // Broadcast so a `<CookieConsent/>` rendered elsewhere (e.g. TribeNestApp) re-opens
+  // — the event handler above re-reads the (now-empty) store for every instance.
+  const reopen = useCallback(() => clearCookieConsent(), []);
+
+  return {
+    consent,
+    ready,
+    decided: consent !== null,
+    performance: consent?.performance ?? false,
+    marketing: consent?.marketing ?? false,
+    acceptAll,
+    rejectAll,
+    save,
+    reopen,
+  };
+}

package/src/ui/headless/course/useCourseCheckout.ts

@@ -0,0 +1,99 @@
+import { useState } from "react";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { useGetCourse, useCreateCourseBooking } from "../../../data/queries/useCourses";
+import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import { readAttributionRef } from "../../../utils/attribution";
+import { readLanding } from "../../../utils/landing";
+
+export type CourseCheckoutStep = "details" | "payment";
+
+export interface UseCourseCheckoutOptions {
+  /** Stripe return URL for a PAID purchase (its `return_url`). Default
+   * `/i/courses/:slug/finalise`. A real URL is required for the redirect leg. */
+  finalisePath?: (slug: string, bookingId: string) => string;
+  /** Called when a FREE enrollment completes in-app — the host navigates however
+   * it wants, instead of Forge doing a `window.location` redirect. */
+  onComplete?: (info: { slug: string; bookingId: string }) => void;
+}
+
+const errMessage = (e: unknown) =>
+  (e as { response?: { data?: { message?: string } } })?.response?.data?.message || "Something went wrong.";
+
+/**
+ * Headless course purchase: buyer details → payment. Composes `useGetCourse`,
+ * `useCreateCourseBooking`, `usePaymentFlow`. Free courses skip payment and
+ * redirect to the finalise page. Finalize via `useCourseBookingFinalize`.
+ */
+export function useCourseCheckout(slug?: string, opts: UseCourseCheckoutOptions = {}) {
+  const { user } = usePublicAuth();
+  // Detail by slug; the booking is created against the real course id.
+  const { data: course, isLoading } = useGetCourse(slug);
+  const courseId = course?.id;
+  const createBooking = useCreateCourseBooking(courseId);
+  const flow = usePaymentFlow({ path: `/public/courses/${courseId}/start-payment`, autoStart: false });
+
+  const [step, setStep] = useState<CourseCheckoutStep>("details");
+  const [firstName, setFirstName] = useState(user?.firstName ?? "");
+  const [lastName, setLastName] = useState(user?.lastName ?? "");
+  const [email, setEmail] = useState(user?.email ?? "");
+  const [questionnaire, setQuestionnaire] = useState<unknown>(undefined);
+  const [returnUrl, setReturnUrl] = useState("");
+  const [error, setError] = useState<string | null>(null);
+
+  const finalisePath =
+    opts.finalisePath ?? ((s, bookingId) => `/i/courses/${s}/finalise?bookingId=${bookingId}`);
+
+  const continueToPayment = async () => {
+    setError(null);
+    if (!slug || !courseId) return;
+    if (!firstName.trim() || !lastName.trim() || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      setError("Please enter your name and a valid email.");
+      return;
+    }
+    try {
+      const data = await createBooking.mutateAsync({
+        email,
+        firstName,
+        lastName,
+        questionnaire,
+        attributionRefId: readAttributionRef() ?? undefined,
+        ...(readLanding() ?? {}),
+      });
+      const origin = typeof window !== "undefined" ? window.location.origin : "";
+      const ru = `${origin}${finalisePath(slug, data.bookingId)}`;
+      setReturnUrl(ru);
+      if (data.isFree) {
+        if (opts.onComplete) opts.onComplete({ slug, bookingId: data.bookingId });
+        else if (typeof window !== "undefined") window.location.href = ru;
+        return;
+      }
+      const result = await flow.start({ bookingId: data.bookingId, returnUrl: ru });
+      if (result.provider && result.provider !== "stripe") return;
+      setStep("payment");
+    } catch (e) {
+      setError(errMessage(e));
+    }
+  };
+
+  return {
+    course,
+    isLoading,
+    step,
+    setStep,
+    firstName,
+    setFirstName,
+    lastName,
+    setLastName,
+    email,
+    setEmail,
+    questionnaire,
+    setQuestionnaire,
+    continueToPayment,
+    clientSecret: flow.clientSecret,
+    /** Authoritative sales-tax quote from start-payment (display only). */
+    taxQuote: flow.result?.taxQuote ?? null,
+    returnUrl,
+    isProcessing: createBooking.isPending || flow.isStarting,
+    error,
+  };
+}