@eifi1/ui-kit 0.42.0 → 0.44.0

package/src/tour/tour-catalogue.tsx

@@ -0,0 +1,316 @@
+import { useId, type ReactNode } from "react";
+import { Circle, CircleCheck, Clock, Play } from "lucide-react";
+import { cn } from "../lib/cn";
+import { useKitFormat } from "../lib/format";
+import { foldForSearch } from "../lib/text-match";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { Button } from "../components/button";
+import { Card } from "../components/card";
+import { Chip } from "../components/chip";
+import { Caption } from "../components/text";
+import { EmptyState } from "../components/empty-state";
+import { SearchField } from "../components/search-field";
+import { Select } from "../components/select";
+import { ToggleGroup } from "../components/toggle-group";
+import { DEFAULT_TOUR_CATALOGUE_LABELS, type TourCatalogueLabels } from "./tour-catalogue-labels";
+import { isTourDone, isTourNew, isTourReset, type TourCompletions, type TourGroup, type TourInfo } from "./tour-info";
+import type { TourCatalogueFilter, TourStateFilter } from "./use-tour-url-sync";
+
+export { DEFAULT_TOUR_CATALOGUE_LABELS };
+export type { TourCatalogueLabels };
+
+/* ── The card ───────────────────────────────────────────────────────────────── */
+
+export interface TourCatalogueCardProps {
+  tour: TourInfo;
+  /** The completion's ISO timestamp, `null` for one without a date; absent while untaken. */
+  completedAt?: string | null;
+  /** NEW — `isTourNew`. The catalogue works it out; a card on its own is told. */
+  isNew?: boolean;
+  onLaunch: (id: string) => void;
+  /** "Mark as not done". Without it, the link is not drawn. */
+  onReset?: (id: string) => void;
+  /** Formats the completion and update days. Default: the kit's medium date in the provider's locale. */
+  formatDate?: (iso: string) => string;
+  labels?: LabelOverride<TourCatalogueLabels>;
+  className?: string;
+}
+
+/**
+ * One tour's card — keksdose's (tours-page.tsx `TourCard`, dev#557), laid out top to
+ * bottom so the cards sit side by side: the state icon beside a column holding the tour's
+ * icon, title, NEW (or "Updated", §8) and the app's `badge`, the one-liner and, from `sm`,
+ * the longer account. The foot is pinned to the bottom edge, so every Start in a row of
+ * cards lands on one line: the points chip, the step count and the duration, the
+ * completion (or reset) line, "Mark as not done" and Start / Replay. Points, steps and
+ * duration are each left out when the tour has none — no gap, no "0 points" (KS).
+ */
+export function TourCatalogueCard({
+  tour,
+  completedAt,
+  isNew = false,
+  onLaunch,
+  onReset,
+  formatDate: formatDateProp,
+  labels: labelsProp,
+  className,
+}: TourCatalogueCardProps) {
+  const words = useKitLabels("tourCatalogue", DEFAULT_TOUR_CATALOGUE_LABELS, labelsProp);
+  const { formatDate } = useKitFormat();
+  const day = formatDateProp ?? ((iso: string) => formatDate(iso, "medium"));
+  const titleId = useId();
+  const done = isTourDone(tour, completedAt);
+  const reset = isTourReset(tour, completedAt);
+  const hasFacts = tour.points != null || tour.steps != null || tour.duration != null;
+  const note = done
+    ? completedAt
+      ? words.completedOn(day(completedAt))
+      : words.completed
+    : reset && tour.updated
+      ? words.resetOn(day(tour.updated.date), tour.updated.reason)
+      : null;
+
+  return (
+    <Card className={cn("flex h-full flex-col p-4", className)}>
+      {/* Title, one-liner and the long body share ONE left edge, in the column beside the
+          state icon. */}
+      <div className="flex flex-1 items-start gap-3">
+        <div className={cn("mt-0.5 shrink-0", done ? "text-success" : "text-muted")}>
+          {done ? <CircleCheck aria-hidden className="size-5" /> : <Circle aria-hidden className="size-5" />}
+          <span className="sr-only">{done ? words.completed : words.notCompleted}</span>
+        </div>
+        <div className="min-w-0 flex-1">
+          <div className="flex flex-wrap items-center gap-2">
+            {tour.icon != null && (
+              <span aria-hidden className="inline-flex shrink-0 text-brand [&_svg]:size-4">
+                {tour.icon}
+              </span>
+            )}
+            {/* The id on the words, not the heading: the Start button is described by them. */}
+            <h3 className="font-medium">
+              <span id={titleId}>{tour.title}</span>
+            </h3>
+            {/* It retires itself the moment the tour is taken — nothing to dismiss. */}
+            {isNew && !reset && (
+              <Chip size="sm" tone="brand" caps className="px-1.5">
+                {words.badgeNew}
+              </Chip>
+            )}
+            {reset && (
+              <Chip size="sm" tone="brand" caps className="px-1.5">
+                {words.badgeUpdated}
+              </Chip>
+            )}
+            {tour.badge}
+          </div>
+          {tour.description && <p className="mt-1 text-sm text-muted">{tour.description}</p>}
+          {/* `hidden sm:block`: one card per row is the phone, where these paragraphs
+              would turn the page into a scroll; the search still reads them. */}
+          {tour.about && <p className="mt-2 hidden text-sm leading-relaxed text-secondary sm:block">{tour.about}</p>}
+        </div>
+      </div>
+      <div className="mt-3 flex flex-wrap items-end justify-between gap-2">
+        <div className="min-w-0">
+          {hasFacts && (
+            <div className="flex flex-wrap items-center gap-1.5">
+              {tour.points != null && (
+                <Chip size="sm" tone="brand">
+                  {words.points(tour.points)}
+                </Chip>
+              )}
+              {tour.steps != null && <Caption as="span">{words.steps(tour.steps)}</Caption>}
+              {tour.duration != null && (
+                <Caption as="span" className="inline-flex items-center gap-1">
+                  <Clock aria-hidden className="size-3" />
+                  {words.duration(tour.duration)}
+                </Caption>
+              )}
+            </div>
+          )}
+          {note && <p className={cn("text-xs text-muted", hasFacts && "mt-1")}>{note}</p>}
+        </div>
+        <div className="flex shrink-0 items-center gap-2">
+          {done && onReset && (
+            <Button variant="link" tone="muted" size="sm" aria-describedby={titleId} onClick={() => onReset(tour.id)}>
+              {words.markUndone}
+            </Button>
+          )}
+          <Button aria-describedby={titleId} onClick={() => onLaunch(tour.id)}>
+            <Play aria-hidden className="size-4" /> {done ? words.replay : words.start}
+          </Button>
+        </div>
+      </div>
+    </Card>
+  );
+}
+
+/* ── The page body ─────────────────────────────────────────────────────────── */
+
+export interface TourCatalogueProps extends TourCatalogueFilter {
+  /** The tours this person may take, already filtered by role and data (§6.3). */
+  tours: readonly TourInfo[];
+  /** The sections, in the app's order. A tour whose group is not here is not listed. */
+  groups: readonly TourGroup[];
+  completed: TourCompletions;
+  /** The account's `created_at`: a tour shipped after it, untaken, is NEW. Unknown → none is. */
+  joined?: string | null;
+  /** A filter changed — `{query}`, `{group}`, `{state}`, or all three for "Clear filters". */
+  onChange: (patch: Partial<TourCatalogueFilter>) => void;
+  onLaunch: (id: string) => void;
+  /** "Mark as not done" — `useTourProgress().reset`. */
+  onReset?: (id: string) => void;
+  /** Above the filter bar: the app's page header with its points tile (§6.1). */
+  header?: ReactNode;
+  formatDate?: (iso: string) => string;
+  /** The search's locale (case folding). Default: the provider's. */
+  locale?: string;
+  labels?: LabelOverride<TourCatalogueLabels>;
+  className?: string;
+}
+
+const STATE_FILTERS: readonly TourStateFilter[] = ["all", "todo", "done"];
+
+/**
+ * The tours page's body (docs/tours-harmonization.md §2.1, §3) — keksdose's /tours:
+ *
+ * - **The filter bar**: a search, a group select and an all / to do / done toggle,
+ *   stacked below `lg` and side by side from it. Each count is what the OTHER filters
+ *   leave: the toggle counts the search and the group, each group the search and the
+ *   state. Under it, while a filter is on, "Showing X of Y tours".
+ * - **The sections**: one per group, in the app's order — an h2 with its icon and help
+ *   line over a `sm:2 / xl:3` grid of `TourCatalogueCard`s. A group the filters empty is
+ *   hidden; when nothing is left, an empty state with "Clear filters".
+ * - **Controlled**: `query`, `group`, `state` and `onChange`, so the app keeps them in its
+ *   URL (`useTourCatalogueUrlState`).
+ *
+ * A tour reset by an update (§8) is "to do" for the toggle and the counts.
+ */
+export function TourCatalogue({
+  tours,
+  groups,
+  completed,
+  joined,
+  query,
+  group: groupProp,
+  state: stateProp,
+  onChange,
+  onLaunch,
+  onReset,
+  header,
+  formatDate,
+  locale: localeProp,
+  labels: labelsProp,
+  className,
+}: TourCatalogueProps) {
+  const words = useKitLabels("tourCatalogue", DEFAULT_TOUR_CATALOGUE_LABELS, labelsProp);
+  const uid = useId();
+  const { locale: kitLocale } = useKitFormat();
+  const locale = localeProp ?? kitLocale;
+  // A group or state the list does not have is no filter at all (an old link).
+  const group = groups.some((g) => g.id === groupProp) ? groupProp : null;
+  const state = STATE_FILTERS.includes(stateProp) ? stateProp : "all";
+
+  const listed = tours.filter((t) => groups.some((g) => g.id === t.group));
+  const done = (tour: TourInfo) => isTourDone(tour, completed[tour.id]);
+  const needle = foldForSearch(query.trim(), locale);
+  const matchesQuery = (tour: TourInfo) =>
+    !needle || [tour.title, tour.description, tour.about].some((text) => !!text && foldForSearch(text, locale).includes(needle));
+  const inState = (tour: TourInfo) => (state === "all" ? true : state === "done" ? done(tour) : !done(tour));
+  const inGroup = (tour: TourInfo, id: string | null = group) => id === null || tour.group === id;
+
+  const found = listed.filter((t) => matchesQuery(t) && inGroup(t));
+  const foundDone = found.filter(done).length;
+  const visible = found.filter(inState);
+  const groupCount = (id: string | null) => listed.filter((t) => matchesQuery(t) && inState(t) && inGroup(t, id)).length;
+  const filtering = needle.length > 0 || state !== "all" || group !== null;
+  const sections = groups
+    .map((g) => ({ ...g, tours: visible.filter((t) => t.group === g.id) }))
+    .filter((g) => g.tours.length > 0);
+
+  return (
+    <div className={cn("space-y-4", className)}>
+      {header}
+      <div className="flex flex-col gap-2 lg:flex-row lg:items-center">
+        <SearchField
+          className="lg:max-w-xs lg:flex-1"
+          value={query}
+          onChange={(value) => onChange({ query: value })}
+          aria-label={words.searchLabel}
+          placeholder={words.searchPlaceholder}
+        />
+        {/* A select, not a chip per group: on a phone those wrap into rows above the list
+            they filter, and an app may have ten groups (ka F8). Named, not labelled: a
+            floating label makes it taller than the search box beside it (dev #589). */}
+        <Select
+          className="lg:w-60"
+          aria-label={words.groupLabel}
+          value={group ?? ""}
+          onChange={(event) => onChange({ group: event.target.value || null })}
+        >
+          <option value="">{words.groupAll(groupCount(null))}</option>
+          {groups.map((g) => (
+            <option key={g.id} value={g.id}>
+              {words.groupOption(g.title, groupCount(g.id))}
+            </option>
+          ))}
+        </Select>
+        <ToggleGroup
+          value={state}
+          onChange={(value: TourStateFilter) => onChange({ state: value })}
+          aria-label={words.stateLabel}
+          className="lg:w-auto"
+          options={[
+            { value: "all", label: words.stateAll(found.length) },
+            { value: "todo", label: words.stateTodo(found.length - foundDone) },
+            { value: "done", label: words.stateDone(foundDone) },
+          ]}
+        />
+      </div>
+      {filtering && (
+        <p role="status" className="-mt-2 text-xs text-muted">
+          {words.showing(visible.length, listed.length)}
+        </p>
+      )}
+
+      {visible.length === 0 ? (
+        <div className="space-y-3">
+          <EmptyState title={words.noMatches} hint={words.noMatchesHint} />
+          <div className="flex justify-center">
+            <Button variant="secondary" onClick={() => onChange({ query: "", group: null, state: "all" })}>
+              {words.clearFilters}
+            </Button>
+          </div>
+        </div>
+      ) : (
+        // A GRID, never columns: a section holding one card keeps a cell's width.
+        sections.map((section) => (
+          <section key={section.id} aria-labelledby={`${uid}-${section.id}`} className="space-y-3">
+            <h2 id={`${uid}-${section.id}`} className="flex items-center gap-1.5 text-sm font-semibold text-muted">
+              {section.icon != null && (
+                <span aria-hidden className="inline-flex shrink-0 [&_svg]:size-4">
+                  {section.icon}
+                </span>
+              )}
+              {section.title}
+            </h2>
+            {section.help && <p className="-mt-2 text-xs text-muted">{section.help}</p>}
+            <div className="grid gap-3 sm:grid-cols-2 xl:grid-cols-3">
+              {section.tours.map((tour) => (
+                <TourCatalogueCard
+                  key={tour.id}
+                  tour={tour}
+                  completedAt={completed[tour.id]}
+                  isNew={isTourNew({ since: tour.since, joined, completed: completed[tour.id] !== undefined })}
+                  onLaunch={onLaunch}
+                  onReset={onReset}
+                  formatDate={formatDate}
+                  labels={labelsProp}
+                />
+              ))}
+            </div>
+          </section>
+        ))
+      )}
+    </div>
+  );
+}

package/src/tour/tour-info.ts

@@ -0,0 +1,144 @@
+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; stored as `""`,
+ * §9.6.6). A tour that is not a key is untaken.
+ */
+export type TourCompletions = Readonly<Record<string, string | null>>;
+
+/** The calendar day of an ISO date or timestamp — `"2026-10-17T08:00:00Z"` → `"2026-10-17"`. */
+const dayOf = (iso: string) => iso.slice(0, 10);
+
+/** What a reset reads of a tour (§8): the update's day, nothing else. */
+type TourUpdated = { updated?: { date: string } | null };
+
+const BARE_DAY = /^\d{4}-\d{2}-\d{2}$/;
+
+/** The start of an ISO day (`YYYY-MM-DD`) in THIS device's time zone, as an instant. */
+function startOfLocalDay(day: string): number {
+  const [y, m, d] = dayOf(day).split("-").map(Number);
+  return new Date(y, m - 1, d).getTime();
+}
+
+/** A completion as an instant: a timestamp as written, a bare day from its local start. */
+const instantOf = (iso: string) => (BARE_DAY.test(iso) ? startOfLocalDay(iso) : Date.parse(iso));
+
+/**
+ * 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 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 {
+  return !!since && !!joined && dayOf(since) > dayOf(joined) && !completed;
+}
+
+/**
+ * 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 function isTourReset(tour: TourUpdated, completedAt: string | null | undefined): boolean {
+  if (completedAt === undefined || !tour.updated) return false;
+  return completedAt === null || instantOf(completedAt) < startOfLocalDay(tour.updated.date);
+}
+
+/** Does this completion count — completed, and not reset by a later update (§8)? */
+export function isTourDone(tour: TourUpdated, completedAt: string | null | undefined): boolean {
+  return completedAt !== undefined && !isTourReset(tour, completedAt);
+}
+
+/**
+ * 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 function doneCount(tours: readonly ({ id: string } & TourUpdated)[], completed: TourCompletions): number {
+  return tours.filter((tour) => isTourDone(tour, completed[tour.id])).length;
+}
+
+/**
+ * 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 function earnedPoints(
+  tours: readonly ({ id: string; points?: number | null } & TourUpdated)[],
+  completed: TourCompletions,
+): number {
+  return tours.reduce((sum, tour) => sum + (isTourDone(tour, completed[tour.id]) ? (tour.points ?? 0) : 0), 0);
+}

package/src/tour/tour.tsx

@@ -17,6 +17,8 @@ import { sameRect } from "../hooks/use-anchored-rect";
 import { dirOf, horizontalStep } from "../lib/direction";
 import type { Direction } from "../lib/direction";
 import { DEFAULT_TOUR_LABELS } from "./tour-labels";
+import type { TourInfo } from "./tour-info";
+import { completeStored, rememberMigrate, type UseTourProgressOptions } from "./use-tour-progress";
 
 /**
  * `start`/`end` follow the reading direction (`end` is the right side in LTR and the
@@ -67,16 +69,34 @@ export { DEFAULT_TOUR_LABELS };
 
 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. */
+   *  the URL (deep-link / evaluation tracking) and record completion. Defaults to
+   *  `tour.id`. */
   id?: string;
+  /** The tour being started, as the app lists it (docs/tours-harmonization.md §9.6.1).
+   *  When its last step is finished, the provider records the completion in its
+   *  `progress` and hands this to `onComplete`. */
+  tour?: TourInfo;
   /** Start at this step index instead of 0 (clamped) — for URL/deep-link resume. */
   startIndex?: number;
   /** Fires synchronously when the tour starts (e.g. enable a mock interceptor). */
   onStart?: () => void;
+  /** After the last step: runs after the provider's progress write and `onComplete`. */
   onFinish?: () => void;
   onSkip?: () => void;
 }
 
+/** What `TourProvider`'s `onComplete` learns besides the tour (§9.1, §9.6). */
+export interface TourCompletion {
+  /**
+   * `true` when the completion counts anew (the first time, or the first time after the
+   * tour's update, §8): the moment for the app's points toast. `false` for a replay, and
+   * when the stored text is in an old shape no `migrate` reads: nothing is overwritten
+   * then, and the error goes to `console.error` (keksdose B-1). `undefined` when the provider has no `progress` or the start carried no `tour`, so
+   * nothing was recorded.
+   */
+  awarded: boolean | undefined;
+}
+
 interface TourContextValue {
   active: boolean;
   /** Id of the running tour (from {@link StartOptions.id}), else null. */
@@ -129,6 +149,11 @@ export function useTourOptional(): TourContextValue | null {
   return useContext(TourContext);
 }
 
+/** The kit's dev switch (as number-input's): a development build, never under vitest. */
+function devWarnings(): boolean {
+  return Boolean(import.meta.env?.DEV) && !import.meta.env?.VITEST;
+}
+
 /**
  * Provides the guided-tour engine: a dimmed spotlight overlay + step card driven
  * by a list of {@link TourStep}s. Domain-free — the app supplies the steps (copy,
@@ -136,13 +161,32 @@ export function useTourOptional(): TourContextValue | null {
  * Mount once inside the router; start a tour from anywhere via {@link useTour},
  * which also exposes step control (`next`/`prev`/`goToStep`) and the current
  * `index`/`total` for URL mirroring, `awaitClick` and deep-link resume.
+ *
+ * **Completion in one place** (docs/tours-harmonization.md §9.6): give the provider the
+ * app's `progress` (the same `{storageKey, migrate}` as `useTourProgress`) and start each
+ * tour with `start(steps, {tour})`. When the last step is finished the provider writes the
+ * completion ONCE, through the store every `useTourProgress` reader of the key shares
+ * (never a second copy), then calls `onComplete(tour, {awarded})`, then the start's own
+ * `onFinish`. A skip or `stop()` records nothing and calls neither. The app removes its
+ * own `complete()` from `onFinish`, or that second write answers `false`.
+ *
+ * Both props are optional: without `progress` or a `tour` on the start, `onComplete`
+ * still fires, with `awarded: undefined` (and `tour` as given, possibly `undefined`). A
+ * new `storageKey` (an account switch on a shared PC) is followed on the next
+ * completion, without a remount.
  */
 export function TourProvider({
   children,
   labels,
+  progress,
+  onComplete,
 }: {
   children: ReactNode;
   labels?: LabelOverride<TourLabels>;
+  /** The app's tour progress: the same options its `useTourProgress` readers use. */
+  progress?: UseTourProgressOptions;
+  /** A tour's last step was finished; see {@link TourCompletion}. */
+  onComplete?: (tour: TourInfo | undefined, completion: TourCompletion) => void;
 }) {
   // `labels` over the provider's `tour` over English. Resolved once here and handed
   // down: the step card is portalled, but context crosses portals anyway — this is
@@ -152,6 +196,20 @@ export function TourProvider({
   const [index, setIndex] = useState(0);
   const [activeId, setActiveId] = useState<string | null>(null);
   const optsRef = useRef<StartOptions>({});
+  // The latest props, read at the finish: a new `storageKey` or callback needs no remount.
+  const progressRef = useRef(progress);
+  const onCompleteRef = useRef(onComplete);
+  useLayoutEffect(() => {
+    progressRef.current = progress;
+    onCompleteRef.current = onComplete;
+  });
+  // The provider's migrate becomes the key's, for readers that pass none (keksdose B-2).
+  const storageKey = progress?.storageKey;
+  const migrate = progress?.migrate;
+  useLayoutEffect(() => {
+    if (storageKey !== undefined) rememberMigrate(storageKey, migrate);
+  }, [storageKey, migrate]);
+  const warnedNoTourRef = useRef(false);
   // Live mirrors so the step-control callbacks can stay stable (identity-safe for
   // consumers) while still reading the current steps/index. Synced in a layout
   // effect — after the commit, before paint and before any passive effect or event
@@ -169,7 +227,7 @@ export function TourProvider({
     optsRef.current = opts ?? {};
     optsRef.current.onStart?.();
     setIndex(Math.min(Math.max(0, opts?.startIndex ?? 0), Math.max(0, s.length - 1)));
-    setActiveId(opts?.id ?? null);
+    setActiveId(opts?.id ?? opts?.tour?.id ?? null);
     setSteps(s);
   }, []);
   const stop = useCallback(() => {
@@ -177,7 +235,30 @@ export function TourProvider({
     setActiveId(null);
   }, []);
   const finish = useCallback(() => {
-    optsRef.current.onFinish?.();
+    // Once per tour: a second "Done" before the overlay unmounts records nothing more.
+    if (!stepsRef.current) return;
+    stepsRef.current = null;
+    const { tour, onFinish } = optsRef.current;
+    const store = progressRef.current;
+    // Exactly one write per completion (§9.6.2), so `awarded` is what `complete(tour)` answered.
+    let awarded: boolean | undefined;
+    if (store && tour) {
+      try {
+        awarded = completeStored(store.storageKey, store.migrate, tour);
+      } catch (error) {
+        // A stored text no migrate reads is left as it is (keksdose B-1); the tour still ends.
+        console.error(error);
+        awarded = false;
+      }
+    } else if (store && !tour && devWarnings() && !warnedNoTourRef.current) {
+      warnedNoTourRef.current = true;
+      console.warn(
+        "[ui-kit] TourProvider has `progress`, but a finished tour's start carried no `tour`: " +
+          "nothing was recorded and `awarded` is undefined. Start it with `start(steps, { tour })`.",
+      );
+    }
+    onCompleteRef.current?.(tour, { awarded });
+    onFinish?.();
     setSteps(null);
     setActiveId(null);
   }, []);