@eifi1/ui-kit 0.42.0 → 0.44.0

package/src/tour/use-tour-progress.ts

@@ -0,0 +1,299 @@
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { readStored, removeStored, writeStored } from "../lib/safe-storage";
+import { isTourDone, type TourCompletions } from "./tour-info";
+
+/**
+ * Which tours this device has completed (docs/tours-harmonization.md §2.6, §6.2) —
+ * keksdose's `tour-progress-store` and kastlan's `completions.ts`, as one hook.
+ *
+ * - **Device storage, the app's key.** `storageKey` is always the app's: an app on shared
+ *   devices scopes it per account (KS, bench PCs), and an app that lists its keys
+ *   (KS `storage-keys.ts`) spells it there. Every access is guarded: a blocked or full
+ *   storage keeps the marks for this page's life instead of throwing.
+ * - **One store, every reader.** A change notifies every hook on the same key in this tab
+ *   (an in-tab emitter) and in other tabs (the `storage` event), so the tours page and
+ *   `TourMenu` agree without a reload (ka F3).
+ * - **`migrate(raw)`** reads an older shape, so nobody loses their done marks at adoption:
+ *   it gets the stored JSON (or the raw text, if it is no JSON) and returns the record for
+ *   a shape it recognises, `undefined` for any other — the kit's own shape included,
+ *   which it then reads itself. keksdose: zustand's `{state: {completed}, version: 1}`;
+ *   kastlan: an array of ids, completed without a date (`null`). It runs only on a stored
+ *   text that is not the kit's shape already, once per text and key. The FIRST `migrate`
+ *   any reader, `TourProvider` or {@link completeTour} passes for a key is remembered for
+ *   that key (later identities are ignored), so a reader without one, mounted first, no
+ *   longer hides the old marks from the rest (keksdose B-2). **Still, define the options
+ *   once, at module level, and hand the provider and every reader the same object.**
+ * - **Never overwritten unread** (keksdose B-1): a write (`complete`, the provider's,
+ *   `completeTour`) on a stored text that is neither empty nor the kit's shape, and that no
+ *   known `migrate` reads, THROWS instead of replacing the old marks.
+ * - **Resetting the device** (settings §11): register the key with `reset: () =>
+ *   resetTourProgress(storageKey)`, which clears storage and the page's memory and tells
+ *   every reader in this tab.
+ *
+ * **The stored shape** (§9.3, §9.6.6), for an app's tests and seeds: the JSON record
+ * `{ [id]: ISO instant | "" }` under `storageKey`, where `""` is a completion without a
+ * date (a migrated record: kastlan's id list). That is the one written form; the hooks
+ * and callbacks (`completed`, `TourCompletions`) give `null` for `""`. A `null` read from
+ * storage (or returned by `migrate`) is accepted as the same thing and written back as
+ * `""`. To write a completion from outside a page, use {@link completeTour}.
+ */
+export interface UseTourProgressOptions {
+  storageKey: string;
+  migrate?: (raw: unknown) => Record<string, string | null> | undefined;
+}
+
+/** What `complete` takes: a tour id, or the tour (`{id, updated}`, a `TourInfo` fits). */
+type CompletedTour = string | { id: string; updated?: { date: string } | null };
+
+export interface TourProgress {
+  /** Tour id → the completion's ISO timestamp, or `null` when recorded without a date. */
+  completed: TourCompletions;
+  /**
+   * Record a completion. Keeps the FIRST completion's date, so a replay changes nothing —
+   * unless the tour was reset by an update since (§8): pass the tour (`{id, updated}`) and
+   * a completion from before `updated.date` is replaced by today's.
+   *
+   * Returns `true` when this counts as a new completion — the moment to award the tour's
+   * points and show the app's toast (§6.1) — and `false` for a replay.
+   *
+   * A tour started with `start(steps, {tour})` under a `TourProvider` that has `progress`
+   * is recorded by the provider (§9.6.2): do not call this from that start's `onFinish`
+   * too, or the second write answers `false`.
+   */
+  complete: (tour: CompletedTour) => boolean;
+  /** "Mark as not done": forget the completion. */
+  reset: (id: string) => void;
+}
+
+/* ── The store: one per key, shared by every hook ───────────────────────────── */
+
+const EMPTY: TourCompletions = Object.freeze({});
+/** In-tab listeners per key. */
+const listeners = new Map<string, Set<() => void>>();
+/** What this page wrote where storage refused to keep it (blocked, full): per key. */
+const memory = new Map<string, string>();
+/**
+ * The last raw text read per key and what it parsed to, so a snapshot keeps its identity:
+ * the same text gives the same object, whichever reader asks and whatever `migrate` it
+ * holds. Several readers of one key with inline `migrate` arrows used to evict each other
+ * here and loop (kastlan B1, 0.43).
+ */
+const cache = new Map<string, { raw: string | null; value: TourCompletions; readable: boolean }>();
+type Migrate = NonNullable<UseTourProgressOptions["migrate"]>;
+/** Each key's migrate: the first one any reader, the provider or `completeTour` passes (B-2). */
+const migrates = new Map<string, Migrate>();
+
+/**
+ * Remember `migrate` for `key` if it is the first one, and return the key's migrate. A
+ * snapshot parsed before the key had one is dropped and re-parsed, and the key's readers
+ * hear of it after this render (never from inside one).
+ * @internal Not part of the barrel; `TourProvider` registers its `progress` with it.
+ */
+export function rememberMigrate(key: string, migrate: UseTourProgressOptions["migrate"]): Migrate | undefined {
+  if (migrate && !migrates.has(key)) {
+    migrates.set(key, migrate);
+    if (cache.delete(key)) queueMicrotask(() => emit(key));
+  }
+  return migrates.get(key);
+}
+
+function emit(key: string) {
+  listeners.get(key)?.forEach((listener) => listener());
+}
+
+function rawOf(key: string): string | null {
+  return memory.get(key) ?? readStored(key);
+}
+
+/** Is this the kit's own shape already: a record whose every value is a string or null? */
+function isKitShape(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  return Object.values(value as Record<string, unknown>).every((at) => at === null || typeof at === "string");
+}
+
+/** The kit's own shape: a record of string or null; anything else is dropped. */
+function fromRecord(value: unknown): TourCompletions | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const out: Record<string, string | null> = {};
+  for (const [id, at] of Object.entries(value as Record<string, unknown>)) {
+    if (at === null || at === "") out[id] = null;
+    else if (typeof at === "string") out[id] = at;
+  }
+  return out;
+}
+
+/**
+ * The record, and whether the text was READ (empty, the kit's shape, or a shape `migrate`
+ * knows) rather than dropped: a write over an unread text would lose it (B-1).
+ */
+function parse(raw: string | null, migrate: UseTourProgressOptions["migrate"]): { value: TourCompletions; readable: boolean } {
+  if (raw === null || raw.trim() === "") return { value: EMPTY, readable: true };
+  let value: unknown = raw;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    // Not JSON: `migrate` still sees the text.
+  }
+  if (migrate && !isKitShape(value)) {
+    try {
+      const migrated = fromRecord(migrate(value));
+      if (migrated !== undefined) return { value: migrated, readable: true };
+    } catch {
+      // A migrate that throws reads as "not a shape it knows".
+    }
+  }
+  return { value: fromRecord(value) ?? EMPTY, readable: isKitShape(value) };
+}
+
+function snapshot(key: string, migrate: UseTourProgressOptions["migrate"]): TourCompletions {
+  const known = rememberMigrate(key, migrate);
+  const raw = rawOf(key);
+  const hit = cache.get(key);
+  if (hit && hit.raw === raw) return hit.value;
+  const parsed = parse(raw, known);
+  cache.set(key, { raw, ...parsed });
+  return parsed.value;
+}
+
+/** The record a write builds on; throws rather than overwrite a text nobody could read (B-1). */
+function readForWrite(key: string, migrate: UseTourProgressOptions["migrate"], own = false): TourCompletions {
+  // `own`: this migrate, even where the key registered another (completeTour's `{migrate}`).
+  const known = rememberMigrate(key, migrate);
+  const { value, readable } =
+    own && migrate && known !== migrate
+      ? parse(rawOf(key), migrate)
+      : { value: snapshot(key, migrate), readable: cache.get(key)?.readable };
+  if (!readable) {
+    throw new Error(
+      `[ui-kit] tour progress: the text stored under "${key}" is not the kit's shape and no migrate reads it; ` +
+        "refusing to overwrite it. Pass the key's migrate (the shared useTourProgress / TourProvider options, " +
+        "or completeTour's {migrate}).",
+    );
+  }
+  return value;
+}
+
+/** The one written form (§9.6.6): a completion without a date is stored as `""`, never `null`. */
+function write(key: string, record: TourCompletions) {
+  const stored: Record<string, string> = {};
+  for (const [id, at] of Object.entries(record)) stored[id] = at ?? "";
+  const raw = JSON.stringify(stored);
+  writeStored(key, raw);
+  // Storage refused it (blocked, full): keep it for this page's life instead.
+  if (readStored(key) === raw) memory.delete(key);
+  else memory.set(key, raw);
+  emit(key);
+}
+
+function subscribe(key: string, listener: () => void): () => void {
+  let set = listeners.get(key);
+  if (!set) listeners.set(key, (set = new Set()));
+  set.add(listener);
+  // Another tab wrote (or cleared all storage: `key` null).
+  const onStorage = (event: StorageEvent) => {
+    if (event.key !== null && event.key !== key) return;
+    memory.delete(key);
+    listener();
+  };
+  if (typeof window !== "undefined") window.addEventListener("storage", onStorage);
+  return () => {
+    set.delete(listener);
+    if (typeof window !== "undefined") window.removeEventListener("storage", onStorage);
+  };
+}
+
+/**
+ * Forget every tour completion under `storageKey` on this device: the stored key, what the
+ * page kept in memory where storage refused it, and every reader in this tab moves at
+ * once. For "Reset this device's settings" (settings §11):
+ *
+ *     registerDeviceSetting({ key: TOUR_KEY, kind: "view", reset: () => resetTourProgress(TOUR_KEY) });
+ */
+export function resetTourProgress(storageKey: string): void {
+  removeStored(storageKey);
+  memory.delete(storageKey);
+  cache.delete(storageKey);
+  emit(storageKey);
+}
+
+/**
+ * Record a completion under `storageKey`, as {@link TourProgress.complete} does: through
+ * the one shared store and snapshot (never a copy), so every reader of the key moves.
+ * Returns `true` when it counts anew. `TourProvider` calls this on a tour's last step.
+ * @internal Not part of the barrel.
+ */
+export function completeStored(
+  storageKey: string,
+  migrate: UseTourProgressOptions["migrate"],
+  tour: CompletedTour,
+): boolean {
+  const subject = typeof tour === "string" ? { id: tour } : tour;
+  // Read now rather than from a render: two completions in one handler both count.
+  const current = readForWrite(storageKey, migrate);
+  if (isTourDone(subject, current[subject.id])) return false;
+  write(storageKey, { ...current, [subject.id]: new Date().toISOString() });
+  return true;
+}
+
+/**
+ * Write a completion from outside a page (§9.2): for an app's tests, seeds and scripts,
+ * beside {@link resetTourProgress}. It writes the kit's stored shape (`{[id]: ISO | ""}`)
+ * under `storageKey`, keeps the other tours' marks, and notifies every reader of the key
+ * in this tab directly (the `storage` event reaches only OTHER tabs), so a mounted
+ * `useTourProgress` or `TourCatalogue` moves at once.
+ *
+ * Unlike `complete`, it always writes (over a readable text; see below): `at` is the
+ * completion's instant (an ISO string or a `Date`, default now), `null` a completion
+ * without a date (stored as `""`, read back as `null`).
+ *
+ *     completeTour(TOUR_KEY, "budget", "2026-09-01T10:00:00Z");
+ *
+ * A stored text in an app's older shape is read through `opts.migrate`, or else the
+ * migrate a reader or the provider registered for the key. If the text is neither empty
+ * nor the kit's shape and no migrate reads it, this THROWS and writes nothing (B-1):
+ *
+ *     completeTour(TOUR_KEY, "budget", undefined, { migrate: fromZustand });
+ */
+export function completeTour(
+  storageKey: string,
+  tour: string | { id: string },
+  at?: string | Date | null,
+  opts?: { migrate?: UseTourProgressOptions["migrate"] },
+): void {
+  const id = typeof tour === "string" ? tour : tour.id;
+  const when = at === null ? null : at instanceof Date ? at.toISOString() : (at ?? new Date().toISOString());
+  write(storageKey, { ...readForWrite(storageKey, opts?.migrate, true), [id]: when });
+}
+
+/** The device's tour completions under `storageKey`; see {@link UseTourProgressOptions}. */
+export function useTourProgress({ storageKey, migrate }: UseTourProgressOptions): TourProgress {
+  // Held, not depended on: an inline arrow is a new function every render, and neither the
+  // snapshot nor the callbacks may change with it.
+  const migrateRef = useRef(migrate);
+  useEffect(() => {
+    migrateRef.current = migrate;
+  });
+  const completed = useSyncExternalStore(
+    useCallback((listener: () => void) => subscribe(storageKey, listener), [storageKey]),
+    () => snapshot(storageKey, migrateRef.current),
+    () => EMPTY,
+  );
+
+  const complete = useCallback(
+    (tour: CompletedTour) => completeStored(storageKey, migrateRef.current, tour),
+    [storageKey],
+  );
+
+  const reset = useCallback(
+    (id: string) => {
+      const current = snapshot(storageKey, migrateRef.current);
+      if (current[id] === undefined) return;
+      const next = { ...current };
+      delete next[id];
+      write(storageKey, next);
+    },
+    [storageKey],
+  );
+
+  return useMemo(() => ({ completed, complete, reset }), [completed, complete, reset]);
+}

package/src/tour/use-tour-url-sync.ts

@@ -0,0 +1,221 @@
+import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState, type Context } from "react";
+import * as ReactRouter from "react-router";
+import { useLocation, useNavigate, type Navigator } from "react-router";
+import { useSearchParamsState } from "../hooks/use-search-param-state";
+import { useTourOptional } from "./tour";
+
+/* ── useTourUrlSync ─────────────────────────────────────────────────────────── */
+
+export interface UseTourUrlSyncOptions {
+  /**
+   * Start the tour `id` at `startIndex` (0-based) — the app's launcher, which builds the
+   * steps, awaits its own `prepare()` and passes `onFinish` (the completion, the points
+   * toast) to `useTour().start`. An unknown id should do nothing. May return a promise:
+   * the parameters are kept until it settles.
+   */
+  launch: (id: string, options: { startIndex: number }) => void | Promise<unknown>;
+  /**
+   * Are the facts a tour's steps are built from loaded yet (keksdose's `ready`: the
+   * caches a branching tour reads)? A deep link waits for it, keeping its parameters, so
+   * an F5 mid-tour resumes the right variant at the right step. Default `true`.
+   */
+  ready?: boolean;
+  /**
+   * Older names of `tourStep`, read when it is absent and removed with it — kastlan's
+   * `ts` (§2.7, for one minor). Their value is a 0-based step index, as kastlan wrote it.
+   */
+  stepAliases?: readonly string[];
+}
+
+type Place = { pathname: string; search: string; hash: string };
+
+/**
+ * Has the router already moved on from the location React is still rendering?
+ * keksdose's check (tour-url-sync.tsx, tours audit 2026-10-02): a mirror write built
+ * from the page being LEFT is a replace back onto it, which cancels a step's `go()`.
+ *
+ * - A data router (`createBrowserRouter`, kastlan): its navigator has no location (build
+ *   review 0.43, kastlan A2), so the router's own state answers — a navigation still
+ *   loading, or a location it has committed that React has not rendered yet.
+ * - A declarative router (`BrowserRouter`, keksdose): its navigator is its history and
+ *   carries where it is.
+ * - Anything else answers "not in flight".
+ */
+function navigationInFlight(history: Navigator | undefined, dataRouter: DataRouterProbe, rendered: Place) {
+  const state = dataRouter?.router?.state;
+  if (state && (state.navigation?.state ?? "idle") !== "idle") return true;
+  const live = state?.location ?? (history as (Navigator & { location?: Partial<Place> }) | undefined)?.location;
+  if (!live) return false;
+  return (
+    live.pathname !== rendered.pathname || (live.search ?? "") !== rendered.search || (live.hash ?? "") !== rendered.hash
+  );
+}
+
+type NavigationProbe = { navigator?: Navigator } | null;
+const NO_NAVIGATION = createContext<NavigationProbe>(null);
+/** The data router's state, as `useSearchParamState` reads it. */
+type DataRouterProbe = {
+  router?: { state?: { navigation?: { state?: string }; location?: Partial<Place> } };
+} | null;
+const NO_DATA_ROUTER = createContext<DataRouterProbe>(null);
+const DataRouterContext: Context<DataRouterProbe> = (() => {
+  try {
+    return (
+      (ReactRouter as unknown as { UNSAFE_DataRouterContext?: Context<DataRouterProbe> }).UNSAFE_DataRouterContext ??
+      NO_DATA_ROUTER
+    );
+  } catch {
+    return NO_DATA_ROUTER;
+  }
+})();
+/** Read off the namespace inside a `try`, as `useSearchParamState` reads the data router:
+ *  a test's partial `vi.mock("react-router")` throws on an export it does not define. */
+const NavigationContext: Context<NavigationProbe> = (() => {
+  try {
+    return (
+      (ReactRouter as unknown as { UNSAFE_NavigationContext?: Context<NavigationProbe> }).UNSAFE_NavigationContext ??
+      NO_NAVIGATION
+    );
+  } catch {
+    return NO_NAVIGATION;
+  }
+})();
+
+/** The step a link asks for, 0-based: `tourStep` is 1-based (keksdose), an alias 0-based. */
+function stepOf(params: URLSearchParams, aliases: readonly string[]): number {
+  const step = Number(params.get("tourStep"));
+  if (params.has("tourStep")) return Number.isFinite(step) && step > 0 ? step - 1 : 0;
+  for (const alias of aliases) {
+    const value = Number(params.get(alias));
+    if (params.has(alias)) return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+  }
+  return 0;
+}
+
+/**
+ * Tours and the URL (docs/tours-harmonization.md §2.7, §6.4) — keksdose's `TourUrlSync`,
+ * on the kit's engine (`useTourOptional`):
+ *
+ * - **`?tour=<id>` starts that tour whenever it APPEARS** — on load, and on in-app
+ *   navigation too (kastlan's assistant links to `/help/tours?tour=<id>`, ka F4) —
+ *   resuming at `&tourStep=<n>` (1-based). It waits for `ready`.
+ * - **While a tour runs, `?tour=&tourStep=` mirror where it is**, so a reload or a copied
+ *   link pins the step (kk K-3). A step that navigates drops them; this puts them back.
+ * - **At the end it strips only its own parameters**; `?q=`, `?state=` and the hash stay.
+ *
+ * Mount it once inside the router and the `TourProvider`. Without a provider it still
+ * launches through `launch` and never mirrors.
+ */
+export function useTourUrlSync({ launch, ready = true, stepAliases = [] }: UseTourUrlSyncOptions): void {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const { pathname, search, hash } = location;
+  const history = useContext(NavigationContext)?.navigator;
+  const dataRouter = useContext(DataRouterContext);
+  const engine = useTourOptional();
+  const active = engine?.active ?? false;
+  const activeId = engine?.activeId ?? null;
+  const index = engine?.index ?? 0;
+  const urlTour = new URLSearchParams(search).get("tour");
+  const aliases = stepAliases.join("\n");
+
+  const launchRef = useRef(launch);
+  const activeIdRef = useRef(activeId);
+  useLayoutEffect(() => {
+    launchRef.current = launch;
+    activeIdRef.current = active ? activeId : null;
+  });
+  /** The `tour` value last seen in the URL: a tour starts when it CHANGES to an id. */
+  const seenRef = useRef<string | null>(null);
+  /** A deep link waiting for `ready`. */
+  const pendingRef = useRef<{ id: string; startIndex: number } | null>(null);
+  /** A launch under way (an app's `prepare()`). */
+  const launchingRef = useRef(false);
+  /** Bumped when a launch settles, so the mirror looks again. */
+  const [settled, setSettled] = useState(0);
+
+  useEffect(() => {
+    if (urlTour !== seenRef.current) {
+      seenRef.current = urlTour;
+      // Its own mirror writing the running tour back is no new link.
+      pendingRef.current =
+        urlTour && urlTour !== activeIdRef.current
+          ? { id: urlTour, startIndex: stepOf(new URLSearchParams(search), aliases ? aliases.split("\n") : []) }
+          : null;
+    }
+    const pending = pendingRef.current;
+    if (!pending || !ready) return;
+    pendingRef.current = null;
+    launchingRef.current = true;
+    void Promise.resolve()
+      .then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }))
+      .catch(() => undefined)
+      .finally(() => {
+        launchingRef.current = false;
+        setSettled((n) => n + 1);
+      });
+    // Only a change of the parameter, or readiness, starts a tour.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [urlTour, ready]);
+
+  useEffect(() => {
+    if (navigationInFlight(history, dataRouter, { pathname, search, hash })) return;
+    // A link not yet used keeps its parameters: a reload in that window resumes.
+    if (pendingRef.current || launchingRef.current) return;
+    const tourId = active && activeId ? activeId : null;
+    const own = ["tour", "tourStep", ...(aliases ? aliases.split("\n") : [])];
+    const current = new URLSearchParams(search);
+    // Nothing to mirror and nothing to strip: never touch the URL (a no-op replace
+    // clobbers a page's own just-issued navigation, keksdose feedback #4).
+    if (!tourId && !own.some((key) => current.has(key))) return;
+    const next = new URLSearchParams(search);
+    // `set` keeps a parameter where it stands; only the aliases (and, at the end, the
+    // tour's own) go.
+    for (const key of tourId ? own.slice(2) : own) next.delete(key);
+    if (tourId) {
+      next.set("tour", tourId);
+      next.set("tourStep", String(index + 1));
+    }
+    if (next.toString() === current.toString()) return;
+    // Spelled out, not `setSearchParams` ("?…" drops the hash, keksdose dev#495).
+    void navigate({ pathname, search: next.toString(), hash }, { replace: true, state: location.state });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [active, activeId, index, pathname, search, hash, settled, aliases]);
+}
+
+/* ── useTourCatalogueUrlState ───────────────────────────────────────────────── */
+
+/** The catalogue's state filter. */
+export type TourStateFilter = "all" | "todo" | "done";
+
+/** The catalogue's filters: the search, the group (`null`: every group), the state. */
+export interface TourCatalogueFilter {
+  query: string;
+  group: string | null;
+  state: TourStateFilter;
+}
+
+const STATES: readonly TourStateFilter[] = ["all", "todo", "done"];
+
+/**
+ * The catalogue's filters in the URL (§2.8) — keksdose's `?q`, `?topic`, `?state`, each
+ * written with `replace` (typing does not bury the Back button), the defaults as the
+ * clean URL. Spread it onto the catalogue: `<TourCatalogue {...useTourCatalogueUrlState()} … />`.
+ * `params` renames them (kastlan's `?group`). Requires a react-router Router.
+ */
+export function useTourCatalogueUrlState(
+  params: { query?: string; group?: string; state?: string } = {},
+): TourCatalogueFilter & { onChange: (patch: Partial<TourCatalogueFilter>) => void } {
+  const [filter, setFilter] = useSearchParamsState<TourCatalogueFilter>({
+    query: { param: params.query ?? "q", default: "", history: "replace" },
+    group: { param: params.group ?? "topic", default: null, history: "replace", parse: (raw) => raw || undefined },
+    state: {
+      param: params.state ?? "state",
+      default: "all",
+      history: "replace",
+      parse: (raw) => STATES.find((x) => x === raw),
+    },
+  });
+  // `group: null` is a value to the setter (it clears `?topic`); `undefined` leaves it.
+  return { ...filter, onChange: setFilter };
+}

package/src/tour.ts

@@ -1,3 +1,15 @@
 // `@eifi1/ui-kit/tour` — guided tours.
 // A re-slicing of the main barrel, not a new API.
 export * from "./tour/tour";
+// 0.43.0: the tours page (docs/tours-harmonization.md §3, §8) — keksdose's catalogue, its
+// card, the NEW and reset rules, device progress and the URL. `useTourUrlSync` and
+// `useTourCatalogueUrlState` need react-router (a peer already, for /shell).
+export { TourCatalogue, TourCatalogueCard, DEFAULT_TOUR_CATALOGUE_LABELS } from "./tour/tour-catalogue";
+export type { TourCatalogueProps, TourCatalogueCardProps, TourCatalogueLabels } from "./tour/tour-catalogue";
+export { isTourNew, isTourReset, isTourDone, doneCount, earnedPoints } from "./tour/tour-info";
+export type { TourInfo, TourGroup, TourUpdate, TourCompletions } from "./tour/tour-info";
+// 0.44.0: the writer outside a page (§9.2).
+export { useTourProgress, resetTourProgress, completeTour } from "./tour/use-tour-progress";
+export type { UseTourProgressOptions, TourProgress } from "./tour/use-tour-progress";
+export { useTourUrlSync, useTourCatalogueUrlState } from "./tour/use-tour-url-sync";
+export type { UseTourUrlSyncOptions, TourCatalogueFilter, TourStateFilter } from "./tour/use-tour-url-sync";