@eifi1/ui-kit 0.50.0 → 0.50.1

package/dist/tour/use-tour-url-sync.js

@@ -4,6 +4,7 @@ import * as ReactRouter from "react-router";
 import { useLocation, useNavigate } from "react-router";
 import { useSearchParamsState } from "../hooks/use-search-param-state.js";
 import { useTourOptional } from "./tour.js";
+import { liveEngine } from "./tour-engine.js";
 import { devWarnings } from "./tour-gates.js";
 function navigationInFlight(history, dataRouter, rendered) {
   const state = dataRouter?.router?.state;
@@ -51,10 +52,12 @@ function useTourUrlSync({ launch, ready = true, stepAliases = [] }) {
   const aliases = stepAliases.join("\n");
   const launchRef = useRef(launch);
   const startRef = useRef(engine?.start ?? noProviderStart);
+  const [live] = useState(() => liveEngine(ENGINE_KEYS, NO_PROVIDER_ENGINE));
   const activeIdRef = useRef(activeId);
   useLayoutEffect(() => {
     launchRef.current = launch;
     startRef.current = engine?.start ?? noProviderStart;
+    live.set(engine ?? NO_PROVIDER_ENGINE);
     activeIdRef.current = active ? activeId : null;
   });
   const seenRef = useRef(null);
@@ -70,7 +73,7 @@ function useTourUrlSync({ launch, ready = true, stepAliases = [] }) {
     if (!pending || !ready) return;
     pendingRef.current = null;
     launchingRef.current = true;
-    void Promise.resolve().then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }, startRef.current)).catch(() => void 0).finally(() => {
+    void Promise.resolve().then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }, startRef.current, live.engine)).catch(() => void 0).finally(() => {
       launchingRef.current = false;
       setSettled((n) => n + 1);
     });
@@ -95,6 +98,23 @@ function useTourUrlSync({ launch, ready = true, stepAliases = [] }) {
 const noProviderStart = () => {
   if (devWarnings()) console.warn("[ui-kit] useTourUrlSync: the launcher's start needs a TourProvider above it.");
 };
+const noProviderCall = () => {
+  if (devWarnings()) console.warn("[ui-kit] useTourUrlSync: the launcher's engine needs a TourProvider above it.");
+};
+const NO_PROVIDER_ENGINE = {
+  active: false,
+  activeId: null,
+  start: noProviderStart,
+  stop: noProviderCall,
+  next: noProviderCall,
+  prev: noProviderCall,
+  goToStep: noProviderCall,
+  index: 0,
+  total: 0,
+  position: 0,
+  count: 0
+};
+const ENGINE_KEYS = Object.keys(NO_PROVIDER_ENGINE);
 const STATES = ["all", "todo", "done"];
 function useTourCatalogueUrlState(params = {}) {
   const [filter, setFilter] = useSearchParamsState({

package/dist/tour/use-tour-url-sync.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eifi1/ui-kit",
-  "version": "0.50.0",
+  "version": "0.50.1",
   "type": "module",
   "description": "App-agnostic shared design system: domain-free React components, theme and tokens.",
   "_sideEffects": "The barrel (src/index.ts) re-exports EVERY component, including components/chart, which statically imports recharts. Without this field a bundler must assume each of those modules has side effects, so it cannot drop the unused ones: importing a Button from '@eifi1/ui-kit' dragged all 433KB of recharts into the consumer's ENTRY chunk, and Keksdose was preloading it on every page load, login included. Nothing in src/ imports for side effects (no bare imports, no CSS imports from JS, no module-level global writes) — the token stylesheet is its own './tokens.css' export — so this is safe. CSS is still listed so any future stylesheet survives. Re-checked when `flag-icons` left `dependencies` and tsup started emitting a `\"use client\"` banner: neither touches this. The flag stylesheet was never imported from JS in the first place (that was the finding), and a directive prologue is a string literal every bundler lifts out before it decides whether a module is inert.",

package/src/components/autocomplete.tsx

@@ -7,6 +7,7 @@ import { Spinner } from "./spinner";
 import { useAnchoredPanel } from "../hooks/use-anchored-panel";
 import { takeEscape, useDismissLayer } from "../hooks/use-dismiss";
 import { isImeEnter } from "../lib/ime";
+import { isQuietFocus } from "../lib/quiet-focus";
 import { useAnchorDir } from "./use-anchor-dir";
 import {
   ComboboxFieldLabel,
@@ -268,6 +269,8 @@ export function Autocomplete<V extends string | number = string>(props: Autocomp
   // either way, so a caller that controls only SOMETIMES (`open={confirming ? false :
   // undefined}`) hands back a field that is exactly as open as focus says it is.
   const open = openProp ?? ownOpen;
+  // The field took the tour's quiet focus (§11.8) and has not opened since.
+  const quietRef = useRef(false);
   const setOpen = (next: boolean) => {
     setOwnOpen(next);
     if (next !== open) onOpenChange?.(next);
@@ -410,11 +413,26 @@ export function Autocomplete<V extends string | number = string>(props: Autocomp
                 onFocus?.(e);
                 // A locked field takes focus to say why, and opens nothing.
                 if (locked) return;
+                // The tour's focus on arrival (§11.8) looks nothing up: the list would
+                // cover its card (0.50.1). A click, ArrowDown or typing opens it.
+                if (isQuietFocus(e.currentTarget)) {
+                  quietRef.current = true;
+                  return;
+                }
                 // A seeded field (keksdose's `initialQuery`) is looked up as it is
                 // focused; an empty one asks nothing, because of `minChars`.
                 setOpen(true);
               }}
+              // After a quiet focus, the person's click on the already-focused field
+              // fires no `focus`: the click is their "open" instead.
+              onClick={(e) => {
+                rest.onClick?.(e);
+                if (!quietRef.current || locked) return;
+                quietRef.current = false;
+                setOpen(true);
+              }}
               onBlur={(e) => {
+                quietRef.current = false;
                 onBlur?.(e);
                 close();
               }}

package/src/components/combobox.tsx

@@ -6,6 +6,7 @@ import { cn } from "../lib/cn";
 import { useDropdown } from "./dropdown";
 import { takeEscape, useDismissLayer } from "../hooks/use-dismiss";
 import { isImeEnter } from "../lib/ime";
+import { isQuietFocus } from "../lib/quiet-focus";
 import { usePhoneLayout } from "../hooks/use-breakpoint";
 import { PickerSheet, SHEET_ROW_CLASS } from "./picker-sheet";
 import { ComboboxFieldLabel, endHintRowProps, GROUP_HEADING_STICKY, useActiveOptionScroll } from "./combobox-core";
@@ -421,11 +422,14 @@ export function Combobox(props: ComboboxProps) {
               autoFocus={autoFocus}
               onBlur={onBlur}
               onMouseDown={primaryOnly.onMouseDown}
-              onFocus={() => {
+              onFocus={(e) => {
                 // A back/forward mouse button focuses this field on its way to
                 // navigating; it is not a request to open anything (live #309 rework).
                 // A locked field takes focus to say why, and opens nothing.
                 if (primaryOnly.fromAuxButton() || locked) return;
+                // The tour's focus on arrival (§11.8) opens nothing: the list would cover
+                // its card (0.50.1). The click handler below still opens on a click.
+                if (isQuietFocus(e.currentTarget)) return;
                 setOpen(true);
                 setTyping(false);
                 // The sheet carries its own input, so the field behind it must not also

package/src/components/inline-entity-combobox.tsx

@@ -8,6 +8,7 @@ import { cn } from "../lib/cn";
 import { useDropdown } from "./dropdown";
 import { takeEscape, useDismissLayer } from "../hooks/use-dismiss";
 import { isImeEnter } from "../lib/ime";
+import { isQuietFocus } from "../lib/quiet-focus";
 import { usePhoneLayout } from "../hooks/use-breakpoint";
 import { PickerSheet, SHEET_ROW_CLASS } from "./picker-sheet";
 import {
@@ -255,6 +256,8 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
   // Escape layer is this field's own.
   const { open, setOpen, wrapperRef, panelRef } = useDropdown({ backCloses: !isPhone, escapeLayer: false });
   const primaryOnly = usePrimaryPressOnly();
+  // The field took the tour's quiet focus (§11.8) and has not opened since.
+  const quietRef = useRef(false);
   const [active, setActive] = useState(-1);
   // null = not editing → the input shows the selected option's label.
   const [text, setText] = useState<string | null>(null);
@@ -508,13 +511,27 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
                 // say why, and opens nothing.
                 if (primaryOnly.fromAuxButton() || locked) return;
                 setText(shown);
+                // The tour's focus on arrival (§11.8) opens nothing: the list would cover
+                // its card (0.50.1). A click, ArrowDown or typing opens it.
+                if (isQuietFocus(e.currentTarget)) {
+                  quietRef.current = true;
+                  return;
+                }
                 e.currentTarget.select();
                 setOpen(true);
                 // The sheet has its own input; the field behind it must not also pull up
                 // the keyboard and scroll the page under the dialog.
                 if (isPhone) sheetInputRef.current?.focus();
               }}
+              // After a quiet focus, the person's click on the already-focused field
+              // fires no `focus`: the click is their "open" instead.
+              onClick={() => {
+                if (!quietRef.current || locked) return;
+                quietRef.current = false;
+                setOpen(true);
+              }}
               onBlur={() => {
+                quietRef.current = false;
                 // On a phone the blur is the SHEET taking focus, not the user leaving the
                 // field — reconciling there would close the sheet the instant it opened.
                 if (!isPhone) reconcile();

package/src/lib/quiet-focus.ts

@@ -0,0 +1,32 @@
+/**
+ * Focus that is not a request to open anything (0.50.1, keksdose B1).
+ *
+ * A guided tour focuses a field step's first control on arrival (tours §11.8). The kit's
+ * pickers that open their list on focus — Combobox (and the category pickers built on it),
+ * Autocomplete, InlineEntityCombobox — opened it then too, and the list, a later layer
+ * (§11.6), covered the tour card with its Next and "Leave empty".
+ *
+ * {@link focusQuietly} marks the element for the length of its synchronous `focus()` call;
+ * a picker's `onFocus` asks {@link isQuietFocus} and, when it is, takes the focus without
+ * opening. React dispatches `onFocus` inside the native `focusin`, which `focus()` fires
+ * synchronously, so the mark is seen by exactly that focus and by no later one. A click or
+ * Tab of the person's own opens as before; from a quiet focus, ArrowDown, typing or a click
+ * opens the list.
+ */
+let quiet: Element | null = null;
+
+/** `el.focus(options)`, telling the kit's open-on-focus pickers not to open. */
+export function focusQuietly(el: HTMLElement, options?: FocusOptions): void {
+  const before = quiet;
+  quiet = el;
+  try {
+    el.focus(options);
+  } finally {
+    quiet = before;
+  }
+}
+
+/** True while `el` is being focused by {@link focusQuietly}. */
+export function isQuietFocus(el: Element): boolean {
+  return quiet === el;
+}

package/src/testing/index.ts

@@ -24,3 +24,11 @@ export {
   type StubbedBoxSize,
   type ViewportOptions,
 } from "./viewport";
+// 0.50.1 (keksdose N4): a valid `TourStepContext` for a test that calls a step's
+// `beforeStep` or `when` itself — `beforeStep!(tourStepContext())`.
+export {
+  tourStepContext,
+  type TestTourStepContext,
+  type TourStepContextOptions,
+  type TourStepVia,
+} from "./tour";

package/src/testing/tour.ts

@@ -0,0 +1,41 @@
+/**
+ * 0.50.1 (keksdose N4): a `TourStepContext` for a test that calls a step's `beforeStep` or
+ * `when` itself. 0.50 gave both the context, so `beforeStep!()` is a type error;
+ * `beforeStep!(tourStepContext())` is the drop-in.
+ *
+ * Spelled out here rather than imported from the tour module, so `@eifi1/ui-kit/testing`
+ * still reaches no package (the tour module reaches React); the kit's own test pins that it
+ * is assignable to `TourStepContext`.
+ */
+
+/** How a step is entered: `TourStepContext["via"]`. */
+export type TourStepVia = "start" | "at" | "next" | "back" | "goto";
+
+/** The shape of `TourStepContext` (`@eifi1/ui-kit/tour`). */
+export interface TestTourStepContext {
+  gate(key: string): boolean | undefined;
+  via: TourStepVia;
+}
+
+export interface TourStepContextOptions {
+  /** How the step is entered. Default `"start"`. */
+  via?: TourStepVia;
+  /**
+   * The published gates, as the form would publish them: `{ "txn.transfer": true }`. A key
+   * left out answers `undefined` (nobody publishes it). Default: none.
+   */
+  gates?: Readonly<Record<string, boolean | undefined>>;
+}
+
+/**
+ * A valid step context: `via: "start"` and no gates published, unless `options` say
+ * otherwise. `step.beforeStep!(tourStepContext())`, `step.when!(tourStepContext({ gates:
+ * { "txn.transfer": true } }))`, `tourStepContext({ via: "at" })` for a "Guide me" entry.
+ */
+export function tourStepContext(options: TourStepContextOptions = {}): TestTourStepContext {
+  const gates = options.gates ?? {};
+  return {
+    gate: (key) => (Object.prototype.hasOwnProperty.call(gates, key) ? gates[key] : undefined),
+    via: options.via ?? "start",
+  };
+}

package/src/tour/tour-engine.ts

@@ -0,0 +1,41 @@
+/**
+ * 0.50.1 (keksdose N1): the tour engine a launcher is handed as its fourth argument — one
+ * object for the life of the provider (or of `useTourUrlSync`) whose fields always read the
+ * engine's LATEST render: `engine.active`, `engine.index` after an `await` are current, and
+ * `engine.stop()` mid-run stops the run that is up now. Internal: the type is `TourEngine`.
+ *
+ * `set` is called from a layout effect with each render's engine; `engine` reads it.
+ */
+export function liveEngine<T extends object>(
+  keys: readonly (keyof T & string)[],
+  initial: T | null = null,
+): { engine: T; set: (current: T) => void } {
+  let current = initial;
+  const read = () => {
+    if (!current)
+      throw new Error(
+        "[ui-kit] The tour engine was read before its provider rendered.",
+      );
+    return current;
+  };
+  const engine = {} as T;
+  for (const key of keys) {
+    Object.defineProperty(engine, key, {
+      enumerable: true,
+      get: () => {
+        const value = read()[key];
+        // A method is looked up when it is CALLED, so a kept `engine.stop` is the latest too.
+        return typeof value === "function"
+          ? (...args: unknown[]) =>
+              (read()[key] as (...a: unknown[]) => unknown)(...args)
+          : value;
+      },
+    });
+  }
+  return {
+    engine,
+    set: (next) => {
+      current = next;
+    },
+  };
+}

package/src/tour/tour.tsx

@@ -20,11 +20,13 @@ import { useDismissLayer } from "../hooks/use-dismiss";
 import { sameRect } from "../hooks/use-anchored-rect";
 import { dirOf, horizontalStep } from "../lib/direction";
 import { isComposing } from "../lib/ime";
+import { focusQuietly } from "../lib/quiet-focus";
 import type { Direction } from "../lib/direction";
 import { DEFAULT_TOUR_LABELS } from "./tour-labels";
 import type { TourInfo } from "./tour-info";
 import { completeStored, rememberAccount, rememberMigrate, type UseTourProgressOptions } from "./use-tour-progress";
 import { createGateRegistry, devWarnings, TourInternalContext, type GateRegistry } from "./tour-gates";
+import { liveEngine } from "./tour-engine";
 import { DOCK_MAX_WIDTH, dockEdge, dockStyle, readBand, scrollIntoFreeHalf, type DockEdge } from "./tour-dock";
 
 export { useTourGate, useTourGateRelease } from "./tour-gates";
@@ -193,15 +195,42 @@ export type TourStart = TourContextValue["start"];
  * `useTourUrlSync`.
  *
  * `start` is the provider's own `start` (keksdose N4), so the launcher needs no ref to a
- * component below the provider and may be defined above it. `useTourUrlSync` passes it too
- * (under a provider). A two-argument launcher that reaches `start` its own way still works.
+ * component below the provider and may be defined above it. `engine` (0.50.1, keksdose N1)
+ * is the rest of the engine — `stop`, `next`, `active`, … — read live, see {@link TourEngine}.
+ * `useTourUrlSync` passes both (under a provider). A launcher taking fewer arguments still
+ * works.
  */
 export type TourLauncher = (
   id: string,
   opts: { startIndex?: number; at?: TourAt },
   start: TourStart,
+  engine: TourEngine,
 ) => void | Promise<unknown>;
 
+/**
+ * 0.50.1 (keksdose N1): the whole engine `useTour()` returns, handed to a launcher as its
+ * FOURTH argument by `TourProvider` and `useTourUrlSync`, so a tour built above the provider
+ * can also `stop`, `next` or read `active` with no `useTour()` registered from below. One
+ * object per provider whose fields read the latest render (`engine.active` after an
+ * `await` is current); its methods are the provider's own. `start` (the third argument) is
+ * `engine.start`.
+ */
+export type TourEngine = TourContextValue;
+
+const ENGINE_KEYS = [
+  "active",
+  "activeId",
+  "start",
+  "stop",
+  "next",
+  "prev",
+  "goToStep",
+  "index",
+  "total",
+  "position",
+  "count",
+] as const satisfies readonly (keyof TourContextValue)[];
+
 interface StartOptions {
   /** Stable id of the tour, surfaced as `activeId` so the app can mirror it to
    *  the URL (deep-link / evaluation tracking) and record completion. Defaults to
@@ -463,8 +492,11 @@ export function TourProvider({
     },
     [arrive, forward, backward],
   );
-  // The provider's own `start`, handed to `launch` as its third argument (keksdose N4).
+  // The provider's own `start` and the live engine, handed to `launch` as its third and
+  // fourth arguments (keksdose N4, N1).
   const ownStartRef = useRef<TourContextValue["start"] | null>(null);
+  const [live] = useState(() => liveEngine<TourEngine>(ENGINE_KEYS));
+  const engine = live.engine;
   const start = useCallback(
     (what: TourStep[] | string, opts?: StartOptions | { at?: TourAt }) => {
       if (typeof what !== "string") {
@@ -476,11 +508,11 @@ export function TourProvider({
         if (devWarnings()) console.warn(`[ui-kit] start("${what}") needs TourProvider's \`launch\` prop.`);
         return;
       }
-      void Promise.resolve(run(what, { at: opts?.at }, ownStartRef.current!)).catch((error: unknown) =>
+      void Promise.resolve(run(what, { at: opts?.at }, ownStartRef.current!, engine)).catch((error: unknown) =>
         console.error(error),
       );
     },
-    [startSteps],
+    [startSteps, engine],
   ) as TourContextValue["start"];
   useLayoutEffect(() => {
     ownStartRef.current = start;
@@ -573,23 +605,27 @@ export function TourProvider({
     });
   }, [active, gates, arrive, forward, finish]);
 
+  const value: TourContextValue = {
+    active,
+    activeId,
+    start,
+    stop,
+    next,
+    prev,
+    goToStep,
+    index,
+    total,
+    position: active ? nav.position : 0,
+    count: active ? nav.count : 0,
+  };
+  // Read by the live engine (`launch`'s fourth argument) after this render commits.
+  useLayoutEffect(() => {
+    live.set(value);
+  });
+
   return (
     <TourInternalContext.Provider value={internals}>
-      <TourContext.Provider
-        value={{
-          active,
-          activeId,
-          start,
-          stop,
-          next,
-          prev,
-          goToStep,
-          index,
-          total,
-          position: active ? nav.position : 0,
-          count: active ? nav.count : 0,
-        }}
-      >
+      <TourContext.Provider value={value}>
         {children}
         {active && (
           <TourOverlay
@@ -1104,11 +1140,14 @@ function TourOverlay({
     if (!ready || !guided || !step.target) return;
     const el = queryVisibleTarget(step.target);
     const control = el ? firstFocusable(el) : null;
+    // Described BEFORE it is focused, so a screen reader reads the step with the field's
+    // name. Focused quietly (0.50.1, keksdose B1): a picker that opens on focus stays
+    // closed, or its list would cover the card; ArrowDown, typing or a click opens it.
+    const previous = control ? control.getAttribute("aria-describedby") : null;
+    if (control) control.setAttribute("aria-describedby", previous ? `${previous} ${bodyId}` : bodyId);
     if (coarsePointer() || !control) cardRef.current?.focus();
-    else if (!el!.contains(document.activeElement)) control.focus();
+    else if (!el!.contains(document.activeElement)) focusQuietly(control);
     if (!control) return;
-    const previous = control.getAttribute("aria-describedby");
-    control.setAttribute("aria-describedby", previous ? `${previous} ${bodyId}` : bodyId);
     return () => {
       if (previous === null) control.removeAttribute("aria-describedby");
       else control.setAttribute("aria-describedby", previous);
@@ -1238,7 +1277,8 @@ function TourOverlay({
   const lockedNext = useCallback(() => {
     const el = step.target ? queryVisibleTarget(step.target) : null;
     const control = el ? firstFocusable(el) : null;
-    control?.focus();
+    // Quietly, as on arrival: the hint is read with the card in view, not under a list.
+    if (control) focusQuietly(control);
     announce(gateHint);
   }, [step.target, announce, gateHint]);
   const tryNext = awaitsRelease ? NOOP : locked ? lockedNext : onNext;

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

@@ -2,7 +2,8 @@ import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState
 import * as ReactRouter from "react-router";
 import { useLocation, useNavigate, type Navigator } from "react-router";
 import { useSearchParamsState } from "../hooks/use-search-param-state";
-import { useTourOptional, type TourStart } from "./tour";
+import { useTourOptional, type TourEngine, type TourStart } from "./tour";
+import { liveEngine } from "./tour-engine";
 import { devWarnings } from "./tour-gates";
 
 /* ── useTourUrlSync ─────────────────────────────────────────────────────────── */
@@ -14,9 +15,16 @@ export interface UseTourUrlSyncOptions {
    * toast) to `useTour().start`. An unknown id should do nothing. May return a promise:
    * the parameters are kept until it settles. Under a `TourProvider` the third argument is
    * that provider's `start` (0.50, as `TourProvider launch` gets it), so one launcher serves
-   * both. Without a provider it is a `start` that does nothing (a development build warns).
+   * both; the fourth is its whole engine, read live (0.50.1, `TourEngine`: `stop`, `next`,
+   * `active`, …). Without a provider `start` and the engine's methods do nothing (a
+   * development build warns) and the engine reads as idle.
    */
-  launch: (id: string, options: { startIndex: number }, start: TourStart) => void | Promise<unknown>;
+  launch: (
+    id: string,
+    options: { startIndex: number },
+    start: TourStart,
+    engine: TourEngine,
+  ) => 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
@@ -124,10 +132,12 @@ export function useTourUrlSync({ launch, ready = true, stepAliases = [] }: UseTo
 
   const launchRef = useRef(launch);
   const startRef = useRef<TourStart>(engine?.start ?? noProviderStart);
+  const [live] = useState(() => liveEngine<TourEngine>(ENGINE_KEYS, NO_PROVIDER_ENGINE));
   const activeIdRef = useRef(activeId);
   useLayoutEffect(() => {
     launchRef.current = launch;
     startRef.current = engine?.start ?? noProviderStart;
+    live.set(engine ?? NO_PROVIDER_ENGINE);
     activeIdRef.current = active ? activeId : null;
   });
   /** The `tour` value last seen in the URL: a tour starts when it CHANGES to an id. */
@@ -153,7 +163,7 @@ export function useTourUrlSync({ launch, ready = true, stepAliases = [] }: UseTo
     pendingRef.current = null;
     launchingRef.current = true;
     void Promise.resolve()
-      .then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }, startRef.current))
+      .then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }, startRef.current, live.engine))
       .catch(() => undefined)
       .finally(() => {
         launchingRef.current = false;
@@ -193,6 +203,25 @@ const noProviderStart: TourStart = () => {
   if (devWarnings()) console.warn("[ui-kit] useTourUrlSync: the launcher's start needs a TourProvider above it.");
 };
 
+const noProviderCall = () => {
+  if (devWarnings()) console.warn("[ui-kit] useTourUrlSync: the launcher's engine needs a TourProvider above it.");
+};
+/** The engine for a launcher run with no `TourProvider` above `useTourUrlSync`: idle. */
+const NO_PROVIDER_ENGINE: TourEngine = {
+  active: false,
+  activeId: null,
+  start: noProviderStart,
+  stop: noProviderCall,
+  next: noProviderCall,
+  prev: noProviderCall,
+  goToStep: noProviderCall,
+  index: 0,
+  total: 0,
+  position: 0,
+  count: 0,
+};
+const ENGINE_KEYS = Object.keys(NO_PROVIDER_ENGINE) as (keyof TourEngine)[];
+
 /* ── useTourCatalogueUrlState ───────────────────────────────────────────────── */
 
 /** The catalogue's state filter. */