@eifi1/ui-kit 0.42.0 → 0.43.0

package/dist/tour/tour-info.d.ts

@@ -0,0 +1,112 @@
+import type { ReactNode } from "react";
+/**
+ * The tours an app offers, as data (docs/tours-harmonization.md §2.2, §6) — one list for
+ * the tours page (`TourCatalogue`) and the top bar's `TourMenu`. The step lists stay the
+ * app's own: the kit's engine runs them (`useTour().start`), and this describes them.
+ *
+ * The kit takes finished strings, never i18n keys (§6.3, kk K-1). Role- and data-gated
+ * tours are filtered by the app before they come in; every count counts what it is given
+ * (§6.3, kk K-2, ka F6).
+ */
+export interface TourInfo {
+    /** Stable id: what `onLaunch` gets, the progress key, `?tour=`. */
+    id: string;
+    title: string;
+    /** The one-liner under the title (and what the menu could carry). */
+    description?: string;
+    /** The longer account: which screens it visits, what it explains. Shown from `sm`. */
+    about?: string;
+    /** The tour's icon, drawn at 16px in the brand colour. */
+    icon?: ReactNode;
+    /** The id of its `TourGroup`: the section it is listed under. */
+    group: string;
+    /** The page the tour starts on — `TourMenu`'s "On this page". */
+    route?: string;
+    /** The day it shipped (ISO `YYYY-MM-DD`): what makes it NEW (§6.4). Without it, never NEW. */
+    since?: string;
+    /** The last update or fix (§8): a completion from before `updated.date` no longer counts. */
+    updated?: TourUpdate;
+    /** How many steps it has. Left out, the card shows no step count. */
+    steps?: number;
+    /** The points it awards (§6.1). Left out, the card draws no chip (never "0 points"). */
+    points?: number;
+    /** About how long it takes, in minutes — worded by the kit ("About 3 min", §6.5). */
+    duration?: number;
+    /** A chip beside NEW in the app's words — kastlan's practice mode (§6.5, ka F1). */
+    badge?: ReactNode;
+}
+/** A tour's last update or fix (§8). One at a time: a later update replaces it. */
+export interface TourUpdate {
+    /** The day it shipped (ISO `YYYY-MM-DD`). */
+    date: string;
+    /** Why, in a short sentence in the app's words: "The import screen moved; the tour follows it now."
+     *  Only shown (the card's reset line); the reset itself reads `date` alone, so an app that
+     *  keeps a reason KEY on its tour definitions passes those to `complete(tour)` as they are. */
+    reason?: string;
+}
+/** A section of the tours page, in the app's words and order (§2.3). An empty one is hidden. */
+export interface TourGroup {
+    id: string;
+    title: string;
+    /** The help line under the heading. */
+    help?: string;
+    /** The heading's icon, drawn at 16px. */
+    icon?: ReactNode;
+}
+/**
+ * Which tours are completed and when: tour id → the ISO timestamp of the completion, or
+ * `null` for one recorded without a date (kastlan's old id list, §6.2). A tour that is
+ * not a key is untaken.
+ */
+export type TourCompletions = Readonly<Record<string, string | null>>;
+/** What a reset reads of a tour (§8): the update's day, nothing else. */
+type TourUpdated = {
+    updated?: {
+        date: string;
+    } | null;
+};
+/**
+ * Is this tour NEW for the person looking at it (§2.4, §6.4)? It shipped AFTER the
+ * account was opened — compared by calendar day, so a tour shipped on the joining day was
+ * already there to be found — and it is not taken yet. No `since`, or no `joined` date,
+ * is never NEW: a pill that appears late is better than one that flickers, and a first
+ * tour shipped with a feature should not flash NEW at every older account (KS, ka F7).
+ *
+ * `completed` is whether the tour was EVER completed — a tour reset by an update (§8) is
+ * not NEW again; it carries the "Updated" pill instead, and `since` stays its first ship
+ * date.
+ */
+export declare function isTourNew({ since, joined, completed, }: {
+    since?: string | null;
+    /** The account's `created_at` (a date or a timestamp); unknown → never NEW. */
+    joined?: string | null;
+    completed?: boolean;
+}): boolean;
+/**
+ * Was this completion reset by an update (§8)? True when the tour carries `updated` and
+ * the completion happened BEFORE the update day began on this device — instants compared:
+ * the completion's timestamp against the start of `updated.date` in local time, so one
+ * taken at 00:30 in Zurich on the update day counts (its UTC day is the day before) — or
+ * has no date at all, which predates any update. A tour never completed (`completedAt`
+ * undefined) is never reset: for that person there is nothing to reset. The check itself
+ * deletes nothing; a new `complete(tour)` replaces the old date.
+ */
+export declare function isTourReset(tour: TourUpdated, completedAt: string | null | undefined): boolean;
+/** Does this completion count — completed, and not reset by a later update (§8)? */
+export declare function isTourDone(tour: TourUpdated, completedAt: string | null | undefined): boolean;
+/**
+ * How many of `tours` count as done (§8): the header's "x of y". A tour reset by an update
+ * does not count until it is taken again, as on its card.
+ */
+export declare function doneCount(tours: readonly ({
+    id: string;
+} & TourUpdated)[], completed: TourCompletions): number;
+/**
+ * The points earned on `tours` (§6.1, §8): the sum of each done tour's `points`. A reset
+ * tour's points are not earned until it is taken again; a tour without points adds none.
+ */
+export declare function earnedPoints(tours: readonly ({
+    id: string;
+    points?: number | null;
+} & TourUpdated)[], completed: TourCompletions): number;
+export {};

package/dist/tour/tour-info.js

@@ -0,0 +1,36 @@
+"use client";
+const dayOf = (iso) => iso.slice(0, 10);
+const BARE_DAY = /^\d{4}-\d{2}-\d{2}$/;
+function startOfLocalDay(day) {
+  const [y, m, d] = dayOf(day).split("-").map(Number);
+  return new Date(y, m - 1, d).getTime();
+}
+const instantOf = (iso) => BARE_DAY.test(iso) ? startOfLocalDay(iso) : Date.parse(iso);
+function isTourNew({
+  since,
+  joined,
+  completed
+}) {
+  return !!since && !!joined && dayOf(since) > dayOf(joined) && !completed;
+}
+function isTourReset(tour, completedAt) {
+  if (completedAt === void 0 || !tour.updated) return false;
+  return completedAt === null || instantOf(completedAt) < startOfLocalDay(tour.updated.date);
+}
+function isTourDone(tour, completedAt) {
+  return completedAt !== void 0 && !isTourReset(tour, completedAt);
+}
+function doneCount(tours, completed) {
+  return tours.filter((tour) => isTourDone(tour, completed[tour.id])).length;
+}
+function earnedPoints(tours, completed) {
+  return tours.reduce((sum, tour) => sum + (isTourDone(tour, completed[tour.id]) ? tour.points ?? 0 : 0), 0);
+}
+export {
+  doneCount,
+  earnedPoints,
+  isTourDone,
+  isTourNew,
+  isTourReset
+};
+//# sourceMappingURL=tour-info.js.map

package/dist/tour/tour-info.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tour/tour-info.ts"],"sourcesContent":["import type { ReactNode } from \"react\";\n\n/**\n * The tours an app offers, as data (docs/tours-harmonization.md §2.2, §6) — one list for\n * the tours page (`TourCatalogue`) and the top bar's `TourMenu`. The step lists stay the\n * app's own: the kit's engine runs them (`useTour().start`), and this describes them.\n *\n * The kit takes finished strings, never i18n keys (§6.3, kk K-1). Role- and data-gated\n * tours are filtered by the app before they come in; every count counts what it is given\n * (§6.3, kk K-2, ka F6).\n */\nexport interface TourInfo {\n  /** Stable id: what `onLaunch` gets, the progress key, `?tour=`. */\n  id: string;\n  title: string;\n  /** The one-liner under the title (and what the menu could carry). */\n  description?: string;\n  /** The longer account: which screens it visits, what it explains. Shown from `sm`. */\n  about?: string;\n  /** The tour's icon, drawn at 16px in the brand colour. */\n  icon?: ReactNode;\n  /** The id of its `TourGroup`: the section it is listed under. */\n  group: string;\n  /** The page the tour starts on — `TourMenu`'s \"On this page\". */\n  route?: string;\n  /** The day it shipped (ISO `YYYY-MM-DD`): what makes it NEW (§6.4). Without it, never NEW. */\n  since?: string;\n  /** The last update or fix (§8): a completion from before `updated.date` no longer counts. */\n  updated?: TourUpdate;\n  /** How many steps it has. Left out, the card shows no step count. */\n  steps?: number;\n  /** The points it awards (§6.1). Left out, the card draws no chip (never \"0 points\"). */\n  points?: number;\n  /** About how long it takes, in minutes — worded by the kit (\"About 3 min\", §6.5). */\n  duration?: number;\n  /** A chip beside NEW in the app's words — kastlan's practice mode (§6.5, ka F1). */\n  badge?: ReactNode;\n}\n\n/** A tour's last update or fix (§8). One at a time: a later update replaces it. */\nexport interface TourUpdate {\n  /** The day it shipped (ISO `YYYY-MM-DD`). */\n  date: string;\n  /** Why, in a short sentence in the app's words: \"The import screen moved; the tour follows it now.\"\n   *  Only shown (the card's reset line); the reset itself reads `date` alone, so an app that\n   *  keeps a reason KEY on its tour definitions passes those to `complete(tour)` as they are. */\n  reason?: string;\n}\n\n/** A section of the tours page, in the app's words and order (§2.3). An empty one is hidden. */\nexport interface TourGroup {\n  id: string;\n  title: string;\n  /** The help line under the heading. */\n  help?: string;\n  /** The heading's icon, drawn at 16px. */\n  icon?: ReactNode;\n}\n\n/**\n * Which tours are completed and when: tour id → the ISO timestamp of the completion, or\n * `null` for one recorded without a date (kastlan's old id list, §6.2). A tour that is\n * not a key is untaken.\n */\nexport type TourCompletions = Readonly<Record<string, string | null>>;\n\n/** The calendar day of an ISO date or timestamp — `\"2026-10-17T08:00:00Z\"` → `\"2026-10-17\"`. */\nconst dayOf = (iso: string) => iso.slice(0, 10);\n\n/** What a reset reads of a tour (§8): the update's day, nothing else. */\ntype TourUpdated = { updated?: { date: string } | null };\n\nconst BARE_DAY = /^\\d{4}-\\d{2}-\\d{2}$/;\n\n/** The start of an ISO day (`YYYY-MM-DD`) in THIS device's time zone, as an instant. */\nfunction startOfLocalDay(day: string): number {\n  const [y, m, d] = dayOf(day).split(\"-\").map(Number);\n  return new Date(y, m - 1, d).getTime();\n}\n\n/** A completion as an instant: a timestamp as written, a bare day from its local start. */\nconst instantOf = (iso: string) => (BARE_DAY.test(iso) ? startOfLocalDay(iso) : Date.parse(iso));\n\n/**\n * Is this tour NEW for the person looking at it (§2.4, §6.4)? It shipped AFTER the\n * account was opened — compared by calendar day, so a tour shipped on the joining day was\n * already there to be found — and it is not taken yet. No `since`, or no `joined` date,\n * is never NEW: a pill that appears late is better than one that flickers, and a first\n * tour shipped with a feature should not flash NEW at every older account (KS, ka F7).\n *\n * `completed` is whether the tour was EVER completed — a tour reset by an update (§8) is\n * not NEW again; it carries the \"Updated\" pill instead, and `since` stays its first ship\n * date.\n */\nexport function isTourNew({\n  since,\n  joined,\n  completed,\n}: {\n  since?: string | null;\n  /** The account's `created_at` (a date or a timestamp); unknown → never NEW. */\n  joined?: string | null;\n  completed?: boolean;\n}): boolean {\n  return !!since && !!joined && dayOf(since) > dayOf(joined) && !completed;\n}\n\n/**\n * Was this completion reset by an update (§8)? True when the tour carries `updated` and\n * the completion happened BEFORE the update day began on this device — instants compared:\n * the completion's timestamp against the start of `updated.date` in local time, so one\n * taken at 00:30 in Zurich on the update day counts (its UTC day is the day before) — or\n * has no date at all, which predates any update. A tour never completed (`completedAt`\n * undefined) is never reset: for that person there is nothing to reset. The check itself\n * deletes nothing; a new `complete(tour)` replaces the old date.\n */\nexport function isTourReset(tour: TourUpdated, completedAt: string | null | undefined): boolean {\n  if (completedAt === undefined || !tour.updated) return false;\n  return completedAt === null || instantOf(completedAt) < startOfLocalDay(tour.updated.date);\n}\n\n/** Does this completion count — completed, and not reset by a later update (§8)? */\nexport function isTourDone(tour: TourUpdated, completedAt: string | null | undefined): boolean {\n  return completedAt !== undefined && !isTourReset(tour, completedAt);\n}\n\n/**\n * How many of `tours` count as done (§8): the header's \"x of y\". A tour reset by an update\n * does not count until it is taken again, as on its card.\n */\nexport function doneCount(tours: readonly ({ id: string } & TourUpdated)[], completed: TourCompletions): number {\n  return tours.filter((tour) => isTourDone(tour, completed[tour.id])).length;\n}\n\n/**\n * The points earned on `tours` (§6.1, §8): the sum of each done tour's `points`. A reset\n * tour's points are not earned until it is taken again; a tour without points adds none.\n */\nexport function earnedPoints(\n  tours: readonly ({ id: string; points?: number | null } & TourUpdated)[],\n  completed: TourCompletions,\n): number {\n  return tours.reduce((sum, tour) => sum + (isTourDone(tour, completed[tour.id]) ? (tour.points ?? 0) : 0), 0);\n}\n"],"mappings":";AAmEA,MAAM,QAAQ,CAAC,QAAgB,IAAI,MAAM,GAAG,EAAE;AAK9C,MAAM,WAAW;AAGjB,SAAS,gBAAgB,KAAqB;AAC5C,QAAM,CAAC,GAAG,GAAG,CAAC,IAAI,MAAM,GAAG,EAAE,MAAM,GAAG,EAAE,IAAI,MAAM;AAClD,SAAO,IAAI,KAAK,GAAG,IAAI,GAAG,CAAC,EAAE,QAAQ;AACvC;AAGA,MAAM,YAAY,CAAC,QAAiB,SAAS,KAAK,GAAG,IAAI,gBAAgB,GAAG,IAAI,KAAK,MAAM,GAAG;AAavF,SAAS,UAAU;AAAA,EACxB;AAAA,EACA;AAAA,EACA;AACF,GAKY;AACV,SAAO,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,MAAM,KAAK,IAAI,MAAM,MAAM,KAAK,CAAC;AACjE;AAWO,SAAS,YAAY,MAAmB,aAAiD;AAC9F,MAAI,gBAAgB,UAAa,CAAC,KAAK,QAAS,QAAO;AACvD,SAAO,gBAAgB,QAAQ,UAAU,WAAW,IAAI,gBAAgB,KAAK,QAAQ,IAAI;AAC3F;AAGO,SAAS,WAAW,MAAmB,aAAiD;AAC7F,SAAO,gBAAgB,UAAa,CAAC,YAAY,MAAM,WAAW;AACpE;AAMO,SAAS,UAAU,OAAkD,WAAoC;AAC9G,SAAO,MAAM,OAAO,CAAC,SAAS,WAAW,MAAM,UAAU,KAAK,EAAE,CAAC,CAAC,EAAE;AACtE;AAMO,SAAS,aACd,OACA,WACQ;AACR,SAAO,MAAM,OAAO,CAAC,KAAK,SAAS,OAAO,WAAW,MAAM,UAAU,KAAK,EAAE,CAAC,IAAK,KAAK,UAAU,IAAK,IAAI,CAAC;AAC7G;","names":[]}

package/dist/tour/use-tour-progress.d.ts

@@ -0,0 +1,61 @@
+import { type TourCompletions } from "./tour-info.js";
+/**
+ * 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, whichever reader
+ *   reads it first; its identity is ignored. **Define `migrate` once, at module level**,
+ *   and hand every reader of the key the same one: readers of one key share one snapshot.
+ * - **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 kit's own shape is the record itself, `{ [id]: ISO | null }`; an empty string reads
+ * as `null` (kastlan's record of 0.42).
+ */
+export interface UseTourProgressOptions {
+    storageKey: string;
+    migrate?: (raw: unknown) => Record<string, string | null> | undefined;
+}
+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.
+     */
+    complete: (tour: string | {
+        id: string;
+        updated?: {
+            date: string;
+        } | null;
+    }) => boolean;
+    /** "Mark as not done": forget the completion. */
+    reset: (id: string) => void;
+}
+/**
+ * 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 declare function resetTourProgress(storageKey: string): void;
+/** The device's tour completions under `storageKey`; see {@link UseTourProgressOptions}. */
+export declare function useTourProgress({ storageKey, migrate }: UseTourProgressOptions): TourProgress;

package/dist/tour/use-tour-progress.js

@@ -0,0 +1,116 @@
+"use client";
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { readStored, removeStored, writeStored } from "../lib/safe-storage.js";
+import { isTourDone } from "./tour-info.js";
+const EMPTY = Object.freeze({});
+const listeners = /* @__PURE__ */ new Map();
+const memory = /* @__PURE__ */ new Map();
+const cache = /* @__PURE__ */ new Map();
+function emit(key) {
+  listeners.get(key)?.forEach((listener) => listener());
+}
+function rawOf(key) {
+  return memory.get(key) ?? readStored(key);
+}
+function isKitShape(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  return Object.values(value).every((at) => at === null || typeof at === "string");
+}
+function fromRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const out = {};
+  for (const [id, at] of Object.entries(value)) {
+    if (at === null || at === "") out[id] = null;
+    else if (typeof at === "string") out[id] = at;
+  }
+  return out;
+}
+function parse(raw, migrate) {
+  if (raw === null) return EMPTY;
+  let value = raw;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+  }
+  if (migrate && !isKitShape(value)) {
+    try {
+      const migrated = migrate(value);
+      if (migrated !== void 0) return fromRecord(migrated) ?? EMPTY;
+    } catch {
+    }
+  }
+  return fromRecord(value) ?? EMPTY;
+}
+function snapshot(key, migrate) {
+  const raw = rawOf(key);
+  const hit = cache.get(key);
+  if (hit && hit.raw === raw) return hit.value;
+  const value = parse(raw, migrate);
+  cache.set(key, { raw, value });
+  return value;
+}
+function write(key, record) {
+  const raw = JSON.stringify(record);
+  writeStored(key, raw);
+  if (readStored(key) === raw) memory.delete(key);
+  else memory.set(key, raw);
+  emit(key);
+}
+function subscribe(key, listener) {
+  let set = listeners.get(key);
+  if (!set) listeners.set(key, set = /* @__PURE__ */ new Set());
+  set.add(listener);
+  const onStorage = (event) => {
+    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);
+  };
+}
+function resetTourProgress(storageKey) {
+  removeStored(storageKey);
+  memory.delete(storageKey);
+  cache.delete(storageKey);
+  emit(storageKey);
+}
+function useTourProgress({ storageKey, migrate }) {
+  const migrateRef = useRef(migrate);
+  useEffect(() => {
+    migrateRef.current = migrate;
+  });
+  const completed = useSyncExternalStore(
+    useCallback((listener) => subscribe(storageKey, listener), [storageKey]),
+    () => snapshot(storageKey, migrateRef.current),
+    () => EMPTY
+  );
+  const complete = useCallback(
+    (tour) => {
+      const subject = typeof tour === "string" ? { id: tour } : tour;
+      const current = snapshot(storageKey, migrateRef.current);
+      if (isTourDone(subject, current[subject.id])) return false;
+      write(storageKey, { ...current, [subject.id]: (/* @__PURE__ */ new Date()).toISOString() });
+      return true;
+    },
+    [storageKey]
+  );
+  const reset = useCallback(
+    (id) => {
+      const current = snapshot(storageKey, migrateRef.current);
+      if (current[id] === void 0) return;
+      const next = { ...current };
+      delete next[id];
+      write(storageKey, next);
+    },
+    [storageKey]
+  );
+  return useMemo(() => ({ completed, complete, reset }), [completed, complete, reset]);
+}
+export {
+  resetTourProgress,
+  useTourProgress
+};
+//# sourceMappingURL=use-tour-progress.js.map

package/dist/tour/use-tour-progress.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tour/use-tour-progress.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from \"react\";\nimport { readStored, removeStored, writeStored } from \"../lib/safe-storage\";\nimport { isTourDone, type TourCompletions } from \"./tour-info\";\n\n/**\n * Which tours this device has completed (docs/tours-harmonization.md §2.6, §6.2) —\n * keksdose's `tour-progress-store` and kastlan's `completions.ts`, as one hook.\n *\n * - **Device storage, the app's key.** `storageKey` is always the app's: an app on shared\n *   devices scopes it per account (KS, bench PCs), and an app that lists its keys\n *   (KS `storage-keys.ts`) spells it there. Every access is guarded: a blocked or full\n *   storage keeps the marks for this page's life instead of throwing.\n * - **One store, every reader.** A change notifies every hook on the same key in this tab\n *   (an in-tab emitter) and in other tabs (the `storage` event), so the tours page and\n *   `TourMenu` agree without a reload (ka F3).\n * - **`migrate(raw)`** reads an older shape, so nobody loses their done marks at adoption:\n *   it gets the stored JSON (or the raw text, if it is no JSON) and returns the record for\n *   a shape it recognises, `undefined` for any other — the kit's own shape included,\n *   which it then reads itself. keksdose: zustand's `{state: {completed}, version: 1}`;\n *   kastlan: an array of ids, completed without a date (`null`). It runs only on a stored\n *   text that is not the kit's shape already, once per text and key, whichever reader\n *   reads it first; its identity is ignored. **Define `migrate` once, at module level**,\n *   and hand every reader of the key the same one: readers of one key share one snapshot.\n * - **Resetting the device** (settings §11): register the key with `reset: () =>\n *   resetTourProgress(storageKey)`, which clears storage and the page's memory and tells\n *   every reader in this tab.\n *\n * The kit's own shape is the record itself, `{ [id]: ISO | null }`; an empty string reads\n * as `null` (kastlan's record of 0.42).\n */\nexport interface UseTourProgressOptions {\n  storageKey: string;\n  migrate?: (raw: unknown) => Record<string, string | null> | undefined;\n}\n\nexport interface TourProgress {\n  /** Tour id → the completion's ISO timestamp, or `null` when recorded without a date. */\n  completed: TourCompletions;\n  /**\n   * Record a completion. Keeps the FIRST completion's date, so a replay changes nothing —\n   * unless the tour was reset by an update since (§8): pass the tour (`{id, updated}`) and\n   * a completion from before `updated.date` is replaced by today's.\n   *\n   * Returns `true` when this counts as a new completion — the moment to award the tour's\n   * points and show the app's toast (§6.1) — and `false` for a replay.\n   */\n  complete: (tour: string | { id: string; updated?: { date: string } | null }) => boolean;\n  /** \"Mark as not done\": forget the completion. */\n  reset: (id: string) => void;\n}\n\n/* ── The store: one per key, shared by every hook ───────────────────────────── */\n\nconst EMPTY: TourCompletions = Object.freeze({});\n/** In-tab listeners per key. */\nconst listeners = new Map<string, Set<() => void>>();\n/** What this page wrote where storage refused to keep it (blocked, full): per key. */\nconst memory = new Map<string, string>();\n/**\n * The last raw text read per key and what it parsed to, so a snapshot keeps its identity:\n * the same text gives the same object, whichever reader asks and whatever `migrate` it\n * holds. Several readers of one key with inline `migrate` arrows used to evict each other\n * here and loop (kastlan B1, 0.43).\n */\nconst cache = new Map<string, { raw: string | null; value: TourCompletions }>();\n\nfunction emit(key: string) {\n  listeners.get(key)?.forEach((listener) => listener());\n}\n\nfunction rawOf(key: string): string | null {\n  return memory.get(key) ?? readStored(key);\n}\n\n/** Is this the kit's own shape already: a record whose every value is a string or null? */\nfunction isKitShape(value: unknown): boolean {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n  return Object.values(value as Record<string, unknown>).every((at) => at === null || typeof at === \"string\");\n}\n\n/** The kit's own shape: a record of string or null; anything else is dropped. */\nfunction fromRecord(value: unknown): TourCompletions | undefined {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) return undefined;\n  const out: Record<string, string | null> = {};\n  for (const [id, at] of Object.entries(value as Record<string, unknown>)) {\n    if (at === null || at === \"\") out[id] = null;\n    else if (typeof at === \"string\") out[id] = at;\n  }\n  return out;\n}\n\nfunction parse(raw: string | null, migrate: UseTourProgressOptions[\"migrate\"]): TourCompletions {\n  if (raw === null) return EMPTY;\n  let value: unknown = raw;\n  try {\n    value = JSON.parse(raw);\n  } catch {\n    // Not JSON: `migrate` still sees the text.\n  }\n  if (migrate && !isKitShape(value)) {\n    try {\n      const migrated = migrate(value);\n      if (migrated !== undefined) return fromRecord(migrated) ?? EMPTY;\n    } catch {\n      // A migrate that throws reads as \"not a shape it knows\".\n    }\n  }\n  return fromRecord(value) ?? EMPTY;\n}\n\nfunction snapshot(key: string, migrate: UseTourProgressOptions[\"migrate\"]): TourCompletions {\n  const raw = rawOf(key);\n  const hit = cache.get(key);\n  if (hit && hit.raw === raw) return hit.value;\n  const value = parse(raw, migrate);\n  cache.set(key, { raw, value });\n  return value;\n}\n\nfunction write(key: string, record: TourCompletions) {\n  const raw = JSON.stringify(record);\n  writeStored(key, raw);\n  // Storage refused it (blocked, full): keep it for this page's life instead.\n  if (readStored(key) === raw) memory.delete(key);\n  else memory.set(key, raw);\n  emit(key);\n}\n\nfunction subscribe(key: string, listener: () => void): () => void {\n  let set = listeners.get(key);\n  if (!set) listeners.set(key, (set = new Set()));\n  set.add(listener);\n  // Another tab wrote (or cleared all storage: `key` null).\n  const onStorage = (event: StorageEvent) => {\n    if (event.key !== null && event.key !== key) return;\n    memory.delete(key);\n    listener();\n  };\n  if (typeof window !== \"undefined\") window.addEventListener(\"storage\", onStorage);\n  return () => {\n    set.delete(listener);\n    if (typeof window !== \"undefined\") window.removeEventListener(\"storage\", onStorage);\n  };\n}\n\n/**\n * Forget every tour completion under `storageKey` on this device: the stored key, what the\n * page kept in memory where storage refused it, and every reader in this tab moves at\n * once. For \"Reset this device's settings\" (settings §11):\n *\n *     registerDeviceSetting({ key: TOUR_KEY, kind: \"view\", reset: () => resetTourProgress(TOUR_KEY) });\n */\nexport function resetTourProgress(storageKey: string): void {\n  removeStored(storageKey);\n  memory.delete(storageKey);\n  cache.delete(storageKey);\n  emit(storageKey);\n}\n\n/** The device's tour completions under `storageKey`; see {@link UseTourProgressOptions}. */\nexport function useTourProgress({ storageKey, migrate }: UseTourProgressOptions): TourProgress {\n  // Held, not depended on: an inline arrow is a new function every render, and neither the\n  // snapshot nor the callbacks may change with it.\n  const migrateRef = useRef(migrate);\n  useEffect(() => {\n    migrateRef.current = migrate;\n  });\n  const completed = useSyncExternalStore(\n    useCallback((listener: () => void) => subscribe(storageKey, listener), [storageKey]),\n    () => snapshot(storageKey, migrateRef.current),\n    () => EMPTY,\n  );\n\n  const complete = useCallback(\n    (tour: string | { id: string; updated?: { date: string } | null }) => {\n      const subject = typeof tour === \"string\" ? { id: tour } : tour;\n      // Read now rather than from the render: two completions in one handler both count.\n      const current = snapshot(storageKey, migrateRef.current);\n      if (isTourDone(subject, current[subject.id])) return false;\n      write(storageKey, { ...current, [subject.id]: new Date().toISOString() });\n      return true;\n    },\n    [storageKey],\n  );\n\n  const reset = useCallback(\n    (id: string) => {\n      const current = snapshot(storageKey, migrateRef.current);\n      if (current[id] === undefined) return;\n      const next = { ...current };\n      delete next[id];\n      write(storageKey, next);\n    },\n    [storageKey],\n  );\n\n  return useMemo(() => ({ completed, complete, reset }), [completed, complete, reset]);\n}\n"],"mappings":"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","names":[]}

package/dist/tour/use-tour-url-sync.d.ts

@@ -0,0 +1,58 @@
+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[];
+}
+/**
+ * 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 declare function useTourUrlSync({ launch, ready, stepAliases }: UseTourUrlSyncOptions): void;
+/** 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;
+}
+/**
+ * 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 declare function useTourCatalogueUrlState(params?: {
+    query?: string;
+    group?: string;
+    state?: string;
+}): TourCatalogueFilter & {
+    onChange: (patch: Partial<TourCatalogueFilter>) => void;
+};

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

@@ -0,0 +1,110 @@
+"use client";
+import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState } from "react";
+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";
+function navigationInFlight(history, dataRouter, rendered) {
+  const state = dataRouter?.router?.state;
+  if (state && (state.navigation?.state ?? "idle") !== "idle") return true;
+  const live = state?.location ?? history?.location;
+  if (!live) return false;
+  return live.pathname !== rendered.pathname || (live.search ?? "") !== rendered.search || (live.hash ?? "") !== rendered.hash;
+}
+const NO_NAVIGATION = createContext(null);
+const NO_DATA_ROUTER = createContext(null);
+const DataRouterContext = (() => {
+  try {
+    return ReactRouter.UNSAFE_DataRouterContext ?? NO_DATA_ROUTER;
+  } catch {
+    return NO_DATA_ROUTER;
+  }
+})();
+const NavigationContext = (() => {
+  try {
+    return ReactRouter.UNSAFE_NavigationContext ?? NO_NAVIGATION;
+  } catch {
+    return NO_NAVIGATION;
+  }
+})();
+function stepOf(params, aliases) {
+  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;
+}
+function useTourUrlSync({ launch, ready = true, stepAliases = [] }) {
+  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;
+  });
+  const seenRef = useRef(null);
+  const pendingRef = useRef(null);
+  const launchingRef = useRef(false);
+  const [settled, setSettled] = useState(0);
+  useEffect(() => {
+    if (urlTour !== seenRef.current) {
+      seenRef.current = urlTour;
+      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(() => void 0).finally(() => {
+      launchingRef.current = false;
+      setSettled((n) => n + 1);
+    });
+  }, [urlTour, ready]);
+  useEffect(() => {
+    if (navigationInFlight(history, dataRouter, { pathname, search, hash })) return;
+    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);
+    if (!tourId && !own.some((key) => current.has(key))) return;
+    const next = new URLSearchParams(search);
+    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;
+    void navigate({ pathname, search: next.toString(), hash }, { replace: true, state: location.state });
+  }, [active, activeId, index, pathname, search, hash, settled, aliases]);
+}
+const STATES = ["all", "todo", "done"];
+function useTourCatalogueUrlState(params = {}) {
+  const [filter, setFilter] = useSearchParamsState({
+    query: { param: params.query ?? "q", default: "", history: "replace" },
+    group: { param: params.group ?? "topic", default: null, history: "replace", parse: (raw) => raw || void 0 },
+    state: {
+      param: params.state ?? "state",
+      default: "all",
+      history: "replace",
+      parse: (raw) => STATES.find((x) => x === raw)
+    }
+  });
+  return { ...filter, onChange: setFilter };
+}
+export {
+  useTourCatalogueUrlState,
+  useTourUrlSync
+};
+//# sourceMappingURL=use-tour-url-sync.js.map

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

@@ -0,0 +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 } from \"./tour\";\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.\n   */\n  launch: (id: string, options: { startIndex: number }) => 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 activeIdRef = useRef(activeId);\n  useLayoutEffect(() => {\n    launchRef.current = launch;\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 }))\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/* ── 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":";AAAA,SAAS,eAAe,YAAY,WAAW,iBAAiB,QAAQ,gBAA8B;AACtG,YAAY,iBAAiB;AAC7B,SAAS,aAAa,mBAAmC;AACzD,SAAS,4BAA4B;AACrC,SAAS,uBAAuB;AAuChC,SAAS,mBAAmB,SAAgC,YAA6B,UAAiB;AACxG,QAAM,QAAQ,YAAY,QAAQ;AAClC,MAAI,UAAU,MAAM,YAAY,SAAS,YAAY,OAAQ,QAAO;AACpE,QAAM,OAAO,OAAO,YAAa,SAAqE;AACtG,MAAI,CAAC,KAAM,QAAO;AAClB,SACE,KAAK,aAAa,SAAS,aAAa,KAAK,UAAU,QAAQ,SAAS,WAAW,KAAK,QAAQ,QAAQ,SAAS;AAErH;AAGA,MAAM,gBAAgB,cAA+B,IAAI;AAKzD,MAAM,iBAAiB,cAA+B,IAAI;AAC1D,MAAM,qBAA+C,MAAM;AACzD,MAAI;AACF,WACG,YAAmF,4BACpF;AAAA,EAEJ,QAAQ;AACN,WAAO;AAAA,EACT;AACF,GAAG;AAGH,MAAM,qBAA+C,MAAM;AACzD,MAAI;AACF,WACG,YAAmF,4BACpF;AAAA,EAEJ,QAAQ;AACN,WAAO;AAAA,EACT;AACF,GAAG;AAGH,SAAS,OAAO,QAAyB,SAAoC;AAC3E,QAAM,OAAO,OAAO,OAAO,IAAI,UAAU,CAAC;AAC1C,MAAI,OAAO,IAAI,UAAU,EAAG,QAAO,OAAO,SAAS,IAAI,KAAK,OAAO,IAAI,OAAO,IAAI;AAClF,aAAW,SAAS,SAAS;AAC3B,UAAM,QAAQ,OAAO,OAAO,IAAI,KAAK,CAAC;AACtC,QAAI,OAAO,IAAI,KAAK,EAAG,QAAO,OAAO,SAAS,KAAK,KAAK,QAAQ,IAAI,KAAK,MAAM,KAAK,IAAI;AAAA,EAC1F;AACA,SAAO;AACT;AAgBO,SAAS,eAAe,EAAE,QAAQ,QAAQ,MAAM,cAAc,CAAC,EAAE,GAAgC;AACtG,QAAM,WAAW,YAAY;AAC7B,QAAM,WAAW,YAAY;AAC7B,QAAM,EAAE,UAAU,QAAQ,KAAK,IAAI;AACnC,QAAM,UAAU,WAAW,iBAAiB,GAAG;AAC/C,QAAM,aAAa,WAAW,iBAAiB;AAC/C,QAAM,SAAS,gBAAgB;AAC/B,QAAM,SAAS,QAAQ,UAAU;AACjC,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,QAAQ,QAAQ,SAAS;AAC/B,QAAM,UAAU,IAAI,gBAAgB,MAAM,EAAE,IAAI,MAAM;AACtD,QAAM,UAAU,YAAY,KAAK,IAAI;AAErC,QAAM,YAAY,OAAO,MAAM;AAC/B,QAAM,cAAc,OAAO,QAAQ;AACnC,kBAAgB,MAAM;AACpB,cAAU,UAAU;AACpB,gBAAY,UAAU,SAAS,WAAW;AAAA,EAC5C,CAAC;AAED,QAAM,UAAU,OAAsB,IAAI;AAE1C,QAAM,aAAa,OAAkD,IAAI;AAEzE,QAAM,eAAe,OAAO,KAAK;AAEjC,QAAM,CAAC,SAAS,UAAU,IAAI,SAAS,CAAC;AAExC,YAAU,MAAM;AACd,QAAI,YAAY,QAAQ,SAAS;AAC/B,cAAQ,UAAU;AAElB,iBAAW,UACT,WAAW,YAAY,YAAY,UAC/B,EAAE,IAAI,SAAS,YAAY,OAAO,IAAI,gBAAgB,MAAM,GAAG,UAAU,QAAQ,MAAM,IAAI,IAAI,CAAC,CAAC,EAAE,IACnG;AAAA,IACR;AACA,UAAM,UAAU,WAAW;AAC3B,QAAI,CAAC,WAAW,CAAC,MAAO;AACxB,eAAW,UAAU;AACrB,iBAAa,UAAU;AACvB,SAAK,QAAQ,QAAQ,EAClB,KAAK,MAAM,UAAU,QAAQ,QAAQ,IAAI,EAAE,YAAY,QAAQ,WAAW,CAAC,CAAC,EAC5E,MAAM,MAAM,MAAS,EACrB,QAAQ,MAAM;AACb,mBAAa,UAAU;AACvB,iBAAW,CAAC,MAAM,IAAI,CAAC;AAAA,IACzB,CAAC;AAAA,EAGL,GAAG,CAAC,SAAS,KAAK,CAAC;AAEnB,YAAU,MAAM;AACd,QAAI,mBAAmB,SAAS,YAAY,EAAE,UAAU,QAAQ,KAAK,CAAC,EAAG;AAEzE,QAAI,WAAW,WAAW,aAAa,QAAS;AAChD,UAAM,SAAS,UAAU,WAAW,WAAW;AAC/C,UAAM,MAAM,CAAC,QAAQ,YAAY,GAAI,UAAU,QAAQ,MAAM,IAAI,IAAI,CAAC,CAAE;AACxE,UAAM,UAAU,IAAI,gBAAgB,MAAM;AAG1C,QAAI,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,QAAQ,QAAQ,IAAI,GAAG,CAAC,EAAG;AACrD,UAAM,OAAO,IAAI,gBAAgB,MAAM;AAGvC,eAAW,OAAO,SAAS,IAAI,MAAM,CAAC,IAAI,IAAK,MAAK,OAAO,GAAG;AAC9D,QAAI,QAAQ;AACV,WAAK,IAAI,QAAQ,MAAM;AACvB,WAAK,IAAI,YAAY,OAAO,QAAQ,CAAC,CAAC;AAAA,IACxC;AACA,QAAI,KAAK,SAAS,MAAM,QAAQ,SAAS,EAAG;AAE5C,SAAK,SAAS,EAAE,UAAU,QAAQ,KAAK,SAAS,GAAG,KAAK,GAAG,EAAE,SAAS,MAAM,OAAO,SAAS,MAAM,CAAC;AAAA,EAErG,GAAG,CAAC,QAAQ,UAAU,OAAO,UAAU,QAAQ,MAAM,SAAS,OAAO,CAAC;AACxE;AAcA,MAAM,SAAqC,CAAC,OAAO,QAAQ,MAAM;AAQ1D,SAAS,yBACd,SAA6D,CAAC,GACqB;AACnF,QAAM,CAAC,QAAQ,SAAS,IAAI,qBAA0C;AAAA,IACpE,OAAO,EAAE,OAAO,OAAO,SAAS,KAAK,SAAS,IAAI,SAAS,UAAU;AAAA,IACrE,OAAO,EAAE,OAAO,OAAO,SAAS,SAAS,SAAS,MAAM,SAAS,WAAW,OAAO,CAAC,QAAQ,OAAO,OAAU;AAAA,IAC7G,OAAO;AAAA,MACL,OAAO,OAAO,SAAS;AAAA,MACvB,SAAS;AAAA,MACT,SAAS;AAAA,MACT,OAAO,CAAC,QAAQ,OAAO,KAAK,CAAC,MAAM,MAAM,GAAG;AAAA,IAC9C;AAAA,EACF,CAAC;AAED,SAAO,EAAE,GAAG,QAAQ,UAAU,UAAU;AAC1C;","names":[]}

package/dist/tour.d.ts

@@ -1 +1,9 @@
 export * from "./tour/tour.js";
+export { TourCatalogue, TourCatalogueCard, DEFAULT_TOUR_CATALOGUE_LABELS } from "./tour/tour-catalogue.js";
+export type { TourCatalogueProps, TourCatalogueCardProps, TourCatalogueLabels } from "./tour/tour-catalogue.js";
+export { isTourNew, isTourReset, isTourDone, doneCount, earnedPoints } from "./tour/tour-info.js";
+export type { TourInfo, TourGroup, TourUpdate, TourCompletions } from "./tour/tour-info.js";
+export { useTourProgress, resetTourProgress } from "./tour/use-tour-progress.js";
+export type { UseTourProgressOptions, TourProgress } from "./tour/use-tour-progress.js";
+export { useTourUrlSync, useTourCatalogueUrlState } from "./tour/use-tour-url-sync.js";
+export type { UseTourUrlSyncOptions, TourCatalogueFilter, TourStateFilter } from "./tour/use-tour-url-sync.js";

package/dist/tour.js

@@ -1,3 +1,21 @@
 "use client";
 export * from "./tour/tour.js";
+import { TourCatalogue, TourCatalogueCard, DEFAULT_TOUR_CATALOGUE_LABELS } from "./tour/tour-catalogue.js";
+import { isTourNew, isTourReset, isTourDone, doneCount, earnedPoints } from "./tour/tour-info.js";
+import { useTourProgress, resetTourProgress } from "./tour/use-tour-progress.js";
+import { useTourUrlSync, useTourCatalogueUrlState } from "./tour/use-tour-url-sync.js";
+export {
+  DEFAULT_TOUR_CATALOGUE_LABELS,
+  TourCatalogue,
+  TourCatalogueCard,
+  doneCount,
+  earnedPoints,
+  isTourDone,
+  isTourNew,
+  isTourReset,
+  resetTourProgress,
+  useTourCatalogueUrlState,
+  useTourProgress,
+  useTourUrlSync
+};
 //# sourceMappingURL=tour.js.map

package/dist/tour.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/tour.ts"],"sourcesContent":["// `@eifi1/ui-kit/tour` — guided tours.\n// A re-slicing of the main barrel, not a new API.\nexport * from \"./tour/tour\";\n"],"mappings":";AAEA,cAAc;","names":[]}
+{"version":3,"sources":["../src/tour.ts"],"sourcesContent":["// `@eifi1/ui-kit/tour` — guided tours.\n// A re-slicing of the main barrel, not a new API.\nexport * from \"./tour/tour\";\n// 0.43.0: the tours page (docs/tours-harmonization.md §3, §8) — keksdose's catalogue, its\n// card, the NEW and reset rules, device progress and the URL. `useTourUrlSync` and\n// `useTourCatalogueUrlState` need react-router (a peer already, for /shell).\nexport { TourCatalogue, TourCatalogueCard, DEFAULT_TOUR_CATALOGUE_LABELS } from \"./tour/tour-catalogue\";\nexport type { TourCatalogueProps, TourCatalogueCardProps, TourCatalogueLabels } from \"./tour/tour-catalogue\";\nexport { isTourNew, isTourReset, isTourDone, doneCount, earnedPoints } from \"./tour/tour-info\";\nexport type { TourInfo, TourGroup, TourUpdate, TourCompletions } from \"./tour/tour-info\";\nexport { useTourProgress, resetTourProgress } from \"./tour/use-tour-progress\";\nexport type { UseTourProgressOptions, TourProgress } from \"./tour/use-tour-progress\";\nexport { useTourUrlSync, useTourCatalogueUrlState } from \"./tour/use-tour-url-sync\";\nexport type { UseTourUrlSyncOptions, TourCatalogueFilter, TourStateFilter } from \"./tour/use-tour-url-sync\";\n"],"mappings":";AAEA,cAAc;AAId,SAAS,eAAe,mBAAmB,qCAAqC;AAEhF,SAAS,WAAW,aAAa,YAAY,WAAW,oBAAoB;AAE5E,SAAS,iBAAiB,yBAAyB;AAEnD,SAAS,gBAAgB,gCAAgC;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eifi1/ui-kit",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "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.",