@tollbooth-dpyc/web 1.7.0 → 1.8.0

package/README.md

@@ -261,6 +261,48 @@ with the step under way lit from the gate's real stage, and `SignInLinks` —
 headless and exported on their own; `classNames.steps` / `classNames.links`
 restyle them inside the gate. `steps={false}` / `links={false}` remove them.
 
+### Guided tour
+
+A page can walk itself through: small popovers in turn, each pointing at a
+control and saying what it is for. The package carries the mechanics — the
+popover (driver.js), the preference, who sees it, the offer, the copy lint
+and the two tours every site shares (the sign-in gate and the account page's
+panels). A site supplies its `data-tour` names and its own words.
+
+```tsx
+import { signInTour, accountTour, type Tour } from "@tollbooth-dpyc/web";
+import { TourProvider, useTour, useTourSwitch, useTourReplay, tourTarget } from "@tollbooth-dpyc/web/react";
+
+const TOURS: Record<string, Tour> = {
+  signin: signInTour(),
+  account: accountTour("account", [{ target: "account.sound", title: "Sound", says: "The hive hums. Switch it off here." }]),
+  play: { page: "play", steps: [
+    { target: "play.practice", title: "Practice", says: "A round against the house, free. Tap it to learn the moves." },
+  ]},
+};
+
+<TourProvider tours={TOURS}>…</TourProvider>          // once, around the app
+useTour("play", { actions: { "open-lobby": () => setMode("live") } });  // once per page
+<button {...tourTarget("play.practice")}>Practice</button>
+```
+
+Who sees it: a new device starts with the live tutorial on; a device that
+already holds a patron npub starts with it off. On a page that is due, after
+ten seconds untouched (`configureTollbooth({ tourIdleMs })`, or
+`TourProvider idleMs`), a centred popover asks whether they would like a tour;
+Yes starts it, No marks the page. A step whose control is absent is skipped;
+a step with `before` has the page open something first, by the name the page
+registered in `actions`. "Stop the tutorial" sits in every popover. The site's
+own switch and replay button take their mechanics from `useTourSwitch()` and
+`useTourReplay()`.
+
+Import `@tollbooth-dpyc/web/tour.css` beside `theme.css`; the popover takes the
+site's `--tb-*` tokens, and `.tb-tour` can be restyled further. The package's
+markup carries `tb.gate.*` and `tb.account.*` names (`TB_TARGETS`); the two
+shared tours point at them. `lintTours(TOURS)` in a site's test holds the copy
+to the voice: one or two short sentences saying what a thing is. A sentence
+carrying "not", "no", "never", "instead of" or "rather than" fails it.
+
 ### Debug panel
 
 `callTool` logs to a shared, scrubbed ring buffer; `DebugPanel` shows it as a

package/dist/config.d.ts

@@ -29,11 +29,14 @@ export interface TollboothConfig {
     quietTools?: string[];
     /** Avatar glyphs in this site's voice. Defaults to a general set. */
     avatarChoices?: string[];
+    /** How long a page sits untouched before its guided tour is offered, in ms. Defaults to 10 s. */
+    tourIdleMs?: number;
 }
-interface Resolved extends Required<Omit<TollboothConfig, "extraBootstrapTools" | "quietTools" | "avatarChoices">> {
+interface Resolved extends Required<Omit<TollboothConfig, "extraBootstrapTools" | "quietTools" | "avatarChoices" | "tourIdleMs">> {
     extraBootstrapTools: string[];
     quietTools: string[];
     avatarChoices?: string[];
+    tourIdleMs?: number;
 }
 export declare function configureTollbooth(config: TollboothConfig): void;
 export declare function tollboothConfig(): Resolved;

package/dist/config.js

@@ -20,6 +20,7 @@ export function configureTollbooth(config) {
         extraBootstrapTools: config.extraBootstrapTools ?? [],
         quietTools: config.quietTools ?? [],
         avatarChoices: config.avatarChoices,
+        tourIdleMs: config.tourIdleMs,
     };
 }
 export function tollboothConfig() {

package/dist/index.d.ts

@@ -22,3 +22,9 @@ export * from "./funding.ts";
 export { errorReport } from "./errorReport.ts";
 export { loadQuotes, peekQuotes, shuffle, validQuotes, type Quote } from "./quotes.ts";
 export { captureGlobalErrors, clearDebug, configureDebugLog, debugEntries, debugLogText, debugPush, debugSeverity, onDebug, redact, type DebugEntry, type DebugLogOptions, type DebugSeverity, } from "./debugLog.ts";
+export type { Tour, TourActions, TourStep } from "./tour/types.ts";
+export { fromStored as tourPrefsFromStored, markToured, replayAll, replayPage, shouldRun, stopAll, TOUR_DEFAULTS, type TourPrefs, } from "./tour/state.ts";
+export { ACTIVITY_EVENTS, DEFAULT_IDLE_MS, idleThreshold, offerDue } from "./tour/idle.ts";
+export { lintStep, lintTour, lintTours, MAX_SAYS, MAX_SENTENCES, MAX_TITLE } from "./tour/lint.ts";
+export { accountPanelsSteps, accountTour, signInTour, TB_TARGETS } from "./tour/tours.ts";
+export { onTourChange, readTourPrefs, settleTourPrefs, tourStorageKey, writeTourPrefs } from "./tourPrefs.ts";

package/dist/index.js

@@ -21,3 +21,8 @@ export * from "./funding.js";
 export { errorReport } from "./errorReport.js";
 export { loadQuotes, peekQuotes, shuffle, validQuotes } from "./quotes.js";
 export { captureGlobalErrors, clearDebug, configureDebugLog, debugEntries, debugLogText, debugPush, debugSeverity, onDebug, redact, } from "./debugLog.js";
+export { fromStored as tourPrefsFromStored, markToured, replayAll, replayPage, shouldRun, stopAll, TOUR_DEFAULTS, } from "./tour/state.js";
+export { ACTIVITY_EVENTS, DEFAULT_IDLE_MS, idleThreshold, offerDue } from "./tour/idle.js";
+export { lintStep, lintTour, lintTours, MAX_SAYS, MAX_SENTENCES, MAX_TITLE } from "./tour/lint.js";
+export { accountPanelsSteps, accountTour, signInTour, TB_TARGETS } from "./tour/tours.js";
+export { onTourChange, readTourPrefs, settleTourPrefs, tourStorageKey, writeTourPrefs } from "./tourPrefs.js";

package/dist/react/CouponsPanel.js

@@ -84,7 +84,7 @@ export default function CouponsPanel({ heading = "My coupons", intro = DEFAULT_I
             setMsg({ ok: false, text: e.message });
         }
     }
-    return (_jsxs("section", { className: c.root, children: [heading && _jsx("div", { className: c.heading, children: heading }), intro && _jsx("p", { className: c.intro, children: intro }), formHeading && _jsx("div", { className: c.subheading, children: formHeading }), _jsxs("div", { className: c.form, children: [_jsx("input", { type: "text", value: code, onChange: (e) => setCode(e.target.value.toUpperCase()), onKeyDown: (e) => {
+    return (_jsxs("section", { className: c.root, "data-tour": "tb.account.coupons", children: [heading && _jsx("div", { className: c.heading, children: heading }), intro && _jsx("p", { className: c.intro, children: intro }), formHeading && _jsx("div", { className: c.subheading, children: formHeading }), _jsxs("div", { className: c.form, children: [_jsx("input", { type: "text", value: code, onChange: (e) => setCode(e.target.value.toUpperCase()), onKeyDown: (e) => {
                             if (e.key === "Enter")
                                 void redeem();
                         }, placeholder: placeholder, "aria-label": "Coupon code", autoCapitalize: "characters", autoCorrect: "off", spellCheck: false, disabled: redeeming, className: c.input }), _jsx("button", { type: "button", onClick: () => void redeem(), disabled: redeeming || !code.trim(), className: c.primary ?? c.chip, children: redeeming ? "Redeeming…" : redeemLabel })] }), msg && (_jsx("p", { role: "status", className: cx(c.message, msg.ok ? c.ok : c.error), children: msg.text })), loading ? (_jsx("p", { className: c.loading, children: "Loading\u2026" })) : loadError ? (_jsx("p", { className: cx(c.message, c.error), children: loadError })) : coupons.length === 0 ? (empty && _jsx("p", { className: c.empty, children: empty })) : (_jsxs(_Fragment, { children: [listHeading && _jsx("div", { className: c.subheading, children: listHeading }), _jsx("ul", { className: c.list, children: coupons.map((coupon) => renderCoupon ? (_jsx("li", { className: c.row, children: renderCoupon(coupon, () => void forget(coupon)) }, coupon.coupon_id)) : (_jsx(CouponRow, { coupon: coupon, c: c, forgetLabel: forgetLabel, onForget: () => void forget(coupon) }, coupon.coupon_id))) })] }))] }));

package/dist/react/DebugPanel.d.ts

@@ -14,8 +14,8 @@
  * Touch-first: every control is a real button at least 40px square, nothing
  * hides behind hover, and the page under the bar stays tappable.
  *
- * The panel keeps its own space: beside the fixed bar it renders an in-flow
- * spacer as tall as the bar is right now (collapsed or open, measured with a
+ * While open, the panel keeps its own space: beside the fixed bar it renders
+ * an in-flow spacer as tall as the log is right now (measured with a
  * ResizeObserver) plus the iOS safe-area inset, so the page's last line can
  * always scroll clear of it. Mount it LAST in the app shell so that spacer is
  * the last thing in the page's flow.

package/dist/react/DebugPanel.js

@@ -15,8 +15,8 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
  * Touch-first: every control is a real button at least 40px square, nothing
  * hides behind hover, and the page under the bar stays tappable.
  *
- * The panel keeps its own space: beside the fixed bar it renders an in-flow
- * spacer as tall as the bar is right now (collapsed or open, measured with a
+ * While open, the panel keeps its own space: beside the fixed bar it renders
+ * an in-flow spacer as tall as the log is right now (measured with a
  * ResizeObserver) plus the iOS safe-area inset, so the page's last line can
  * always scroll clear of it. Mount it LAST in the app shell so that spacer is
  * the last thing in the page's flow.
@@ -25,7 +25,7 @@ import { useEffect, useRef, useState } from "react";
 import { onProofExpired } from "../client.js";
 import { captureGlobalErrors, clearDebug, debugLogText, debugPush, debugSeverity, } from "../debugLog.js";
 import { readStored, writeStored } from "../storage.js";
-import { debugSpacerHeight, debugSpacerPx } from "./debugSpacer.js";
+import { debugSpacerPx, debugSpacerRoom } from "./debugSpacer.js";
 import { useDebugLog } from "./useDebugLog.js";
 const OPEN_KEY = "debug-open";
 const TYPE_INK = {
@@ -100,7 +100,7 @@ export default function DebugPanel({ title = "Debug", defaultOpen = false, captu
         : notices > 0
             ? "bg-[var(--tb-notice-bg)] text-[var(--tb-notice-ink)] border-[var(--tb-notice-line)]"
             : "bg-[var(--tb-surface-2)] text-[var(--tb-ink)] border-[var(--tb-line)]";
-    return (_jsxs(_Fragment, { children: [_jsx("div", { "aria-hidden": "true", "data-tb-debug-spacer": "", style: { height: debugSpacerHeight(barHeight), flexShrink: 0 } }), _jsxs("div", { ref: barRef, className: "pointer-events-none fixed inset-x-0 bottom-0 z-50 flex flex-col items-end", children: [_jsxs("div", { className: "pointer-events-auto flex flex-wrap justify-end gap-1 pr-3", children: [open && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", onClick: copy, className: plainTab, "aria-label": "Copy the whole log", children: copied === "ok" ? "Copied" : copied === "failed" ? "Copy failed" : "Copy" }), _jsx("button", { type: "button", onClick: clearDebug, className: plainTab, children: "Clear" })] })), _jsxs("button", { type: "button", onClick: toggle, "aria-expanded": open, className: `${tab} ${toggleTone}`, children: [open ? "Hide" : title, " (", log.length, failures > 0 ? ` · ${failures} err` : "", notices > 0 ? ` · ${notices} notice` : "", ")"] })] }), open && (_jsxs("div", { className: "pointer-events-auto max-h-[40vh] w-full overflow-y-auto border-t border-[var(--tb-line)] bg-[var(--tb-surface)] p-3 font-mono text-xs text-[var(--tb-ink)]", children: [children && _jsx("div", { className: "mb-2 border-b border-[var(--tb-line)] pb-2 font-sans", children: children }), log.length === 0 && _jsx("div", { className: "text-[var(--tb-muted)]", children: "No MCP activity yet." }), log.map((entry, i) => {
+    return (_jsxs(_Fragment, { children: [_jsx("div", { "aria-hidden": "true", "data-tb-debug-spacer": "", style: { height: debugSpacerRoom(open, barHeight), flexShrink: 0 } }), _jsxs("div", { ref: barRef, className: "pointer-events-none fixed inset-x-0 bottom-0 z-50 flex flex-col items-end", children: [_jsxs("div", { className: "pointer-events-auto flex flex-wrap justify-end gap-1 pr-3", children: [open && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", onClick: copy, className: plainTab, "aria-label": "Copy the whole log", children: copied === "ok" ? "Copied" : copied === "failed" ? "Copy failed" : "Copy" }), _jsx("button", { type: "button", onClick: clearDebug, className: plainTab, children: "Clear" })] })), _jsxs("button", { type: "button", onClick: toggle, "aria-expanded": open, className: `${tab} ${toggleTone}`, children: [open ? "Hide" : title, " (", log.length, failures > 0 ? ` · ${failures} err` : "", notices > 0 ? ` · ${notices} notice` : "", ")"] })] }), open && (_jsxs("div", { className: "pointer-events-auto max-h-[40vh] w-full overflow-y-auto border-t border-[var(--tb-line)] bg-[var(--tb-surface)] p-3 font-mono text-xs text-[var(--tb-ink)]", children: [children && _jsx("div", { className: "mb-2 border-b border-[var(--tb-line)] pb-2 font-sans", children: children }), log.length === 0 && _jsx("div", { className: "text-[var(--tb-muted)]", children: "No MCP activity yet." }), log.map((entry, i) => {
                                 const sev = debugSeverity(entry);
                                 const flag = sev === "ok" ? null : FLAGGED[sev];
                                 return (_jsxs("div", { className: `-mx-1 flex gap-2 rounded px-1 py-0.5 ${flag?.row ?? ""}`, children: [_jsx("span", { className: "shrink-0 text-[var(--tb-muted)]", children: entry.ts }), _jsxs("span", { className: `w-14 shrink-0 ${flag?.ink ?? TYPE_INK[entry.type]}`, children: [sev === "notice" ? "notice" : entry.type, sev === "failure" && entry.type !== "error" ? " !" : ""] }), _jsx("span", { className: `min-w-0 break-all ${flag?.ink ?? ""}`, children: entry.message })] }, log.length - i));

package/dist/react/NostrProfilePanel.js

@@ -112,7 +112,7 @@ export default function NostrProfilePanel({ npub, onPublished, }) {
             setPublishing(false);
         }
     }
-    return (_jsxs("div", { className: `${card} px-4 py-3`, children: [_jsxs("div", { className: "flex items-start gap-3", children: [_jsxs("div", { className: "relative flex-none", children: [_jsx(Avatar, { value: profile.picture || avatarFor(npub), size: 56 }), _jsx("button", { type: "button", onClick: () => {
+    return (_jsxs("div", { className: `${card} px-4 py-3`, "data-tour": "tb.account.profile", children: [_jsxs("div", { className: "flex items-start gap-3", children: [_jsxs("div", { className: "relative flex-none", children: [_jsx(Avatar, { value: profile.picture || avatarFor(npub), size: 56 }), _jsx("button", { type: "button", onClick: () => {
                                     setExpanded(true);
                                     setShowPicker((v) => !v);
                                 }, "aria-label": showPicker ? "Done changing avatar" : "Change avatar", "aria-expanded": showPicker, className: "absolute -bottom-0.5 -right-0.5 inline-flex h-6 w-6 items-center justify-center rounded-full border border-[var(--tb-line)] bg-[var(--tb-surface)] shadow-sm", children: _jsx(Camera, { className: "h-3.5 w-3.5", "aria-hidden": "true" }) })] }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsxs("div", { className: "flex items-center gap-2 flex-wrap", children: [_jsx("div", { className: "text-sm font-medium truncate", children: collapsedDisplayName(profile.display_name ?? "") }), mode === "how-to-set" && (_jsx("span", { className: `text-[11px] px-1.5 py-0.5 rounded-md bg-[var(--tb-surface-2)] ${muted}`, children: "Read-only" }))] }), _jsx("button", { type: "button", onClick: copyNpub, title: "Copy full npub", className: `mt-0.5 font-mono text-xs ${muted}`, children: copied ? "Copied" : shortNpub(npub) })] }), _jsxs("button", { type: "button", onClick: () => setExpanded((v) => !v), "aria-expanded": expanded, "aria-controls": fieldsId, className: "flex-none inline-flex items-center gap-1 rounded-full border border-[var(--tb-line)] px-2.5 py-1.5 text-xs", children: [expanded ? "Hide" : "Edit", _jsx(ChevronDown, { className: `h-3.5 w-3.5 transition-transform ${expanded ? "rotate-180" : ""}`, "aria-hidden": "true" })] })] }), showPicker && (_jsx("div", { className: "mt-3", children: _jsx(AvatarPicker, { value: profile.picture ?? "", onChange: pickAvatar }) })), loading ? (_jsxs("div", { className: `flex items-center gap-1.5 text-xs py-2 mt-3 ${muted}`, children: [_jsx(Loader2, { className: "h-3.5 w-3.5 animate-spin" }), " Reading from relays\u2026"] })) : (_jsxs("div", { id: fieldsId, hidden: !expanded, className: expanded ? "mt-3 grid gap-x-3 gap-y-2 sm:grid-cols-2" : undefined, children: [FIELDS.map((f) => (_jsxs("label", { className: `block text-xs ${muted} ${f.key === "about" ? "sm:col-span-2" : ""}`, children: [f.label, f.key === "about" ? (_jsx("textarea", { value: profile[f.key] ?? "", onChange: (e) => set(f.key, e.target.value), rows: 2, className: `mt-1 ${input} font-sans resize-none`, placeholder: f.placeholder, readOnly: mode === "how-to-set" })) : (_jsx("input", { value: profile[f.key] ?? "", onChange: (e) => set(f.key, e.target.value), className: `mt-1 ${input} font-sans`, placeholder: f.placeholder, readOnly: mode === "how-to-set" }))] }, f.key))), msg && (_jsx("div", { className: `text-xs sm:col-span-2 ${msg.ok ? "text-[var(--tb-ok)]" : "text-[var(--tb-err-ink)]"}`, children: msg.text })), _jsxs("div", { className: "relative flex items-center gap-3 sm:col-span-2", ref: howToRef, children: [_jsx("button", { type: "button", onClick: () => (mode === "how-to-set" ? setShowHowTo((v) => !v) : void publish()), disabled: publishControlDisabled(mode, publishing), "aria-haspopup": mode === "how-to-set" ? "dialog" : undefined, "aria-expanded": mode === "how-to-set" ? showHowTo : undefined, className: mode === "publish"

package/dist/react/NpubGate.js

@@ -167,7 +167,7 @@ export default function NpubGate({ onLogin, startFresh = false, operatorHash, no
         setPendingProof("");
         setError("");
     }
-    return (_jsxs("div", { className: cx("max-w-md mx-auto mt-12 px-4", c.root), children: [_jsxs("h1", { className: "text-xl font-semibold mb-1", children: ["Sign in to ", appName] }), welcome && _jsx("div", { className: cx("text-sm mb-3", c.welcome), children: welcome }), _jsxs("p", { className: cx(`text-sm mb-5 ${muted}`, c.register), children: [appName, " is an operator on the Tollbooth DPYC\u2122 network. DPYC\u2122 \u2014 Don't Pester Your Customer\u2122: no email, no password, no KYC. Your Nostr key is your identity."] }), notice && _jsx("div", { className: `mb-5 ${warnBox}`, children: notice }), stage === "begin" && recents.length > 0 && (_jsxs("div", { className: "mb-5", children: [_jsx("div", { className: `text-xs uppercase tracking-wider mb-2 ${muted}`, children: "Recent identities" }), _jsx("div", { className: "space-y-1.5", children: recents.map((e) => (_jsxs("div", { className: "flex gap-1.5", children: [_jsxs("button", { type: "button", onClick: () => reuseRecent(e), disabled: busy, title: `Re-enter as ${e.npub} on the cached proof`, className: `${card} flex-1 flex items-center justify-between px-3 py-2.5 text-left hover:border-[var(--tb-accent)]`, children: [_jsxs("span", { className: "font-mono text-xs truncate", children: [e.npub.slice(0, 12), "\u2026", e.npub.slice(-6)] }), _jsxs("span", { className: `text-xs shrink-0 ml-2 ${muted}`, children: [ttl(e.expiresAt), " left"] })] }), _jsx("button", { type: "button", onClick: () => forget(e.npub), disabled: busy, title: "Forget this identity", "aria-label": "Forget this identity", className: `w-9 rounded-lg border border-[var(--tb-line)] ${muted}`, children: "\u00D7" })] }, e.npub))) })] })), _jsxs("div", { className: `${card} p-4 space-y-3`, children: [stage === "begin" ? (_jsxs(_Fragment, { children: [_jsx("label", { className: `block text-xs uppercase tracking-wider ${muted}`, htmlFor: "tb-npub-field", children: "Enter npub (secure) or nsec (convenient)" }), _jsx("input", { id: "tb-npub-field", type: isNsec ? "password" : "text", value: value, onChange: (e) => {
+    return (_jsxs("div", { className: cx("max-w-md mx-auto mt-12 px-4", c.root), children: [_jsxs("h1", { className: "text-xl font-semibold mb-1", children: ["Sign in to ", appName] }), welcome && _jsx("div", { className: cx("text-sm mb-3", c.welcome), children: welcome }), _jsxs("p", { className: cx(`text-sm mb-5 ${muted}`, c.register), children: [appName, " is an operator on the Tollbooth DPYC\u2122 network. DPYC\u2122 \u2014 Don't Pester Your Customer\u2122: no email, no password, no KYC. Your Nostr key is your identity."] }), notice && _jsx("div", { className: `mb-5 ${warnBox}`, children: notice }), stage === "begin" && recents.length > 0 && (_jsxs("div", { className: "mb-5", children: [_jsx("div", { className: `text-xs uppercase tracking-wider mb-2 ${muted}`, children: "Recent identities" }), _jsx("div", { className: "space-y-1.5", children: recents.map((e) => (_jsxs("div", { className: "flex gap-1.5", children: [_jsxs("button", { type: "button", onClick: () => reuseRecent(e), disabled: busy, title: `Re-enter as ${e.npub} on the cached proof`, className: `${card} flex-1 flex items-center justify-between px-3 py-2.5 text-left hover:border-[var(--tb-accent)]`, children: [_jsxs("span", { className: "font-mono text-xs truncate", children: [e.npub.slice(0, 12), "\u2026", e.npub.slice(-6)] }), _jsxs("span", { className: `text-xs shrink-0 ml-2 ${muted}`, children: [ttl(e.expiresAt), " left"] })] }), _jsx("button", { type: "button", onClick: () => forget(e.npub), disabled: busy, title: "Forget this identity", "aria-label": "Forget this identity", className: `w-9 rounded-lg border border-[var(--tb-line)] ${muted}`, children: "\u00D7" })] }, e.npub))) })] })), _jsxs("div", { className: `${card} p-4 space-y-3`, children: [stage === "begin" ? (_jsxs(_Fragment, { children: [_jsx("label", { className: `block text-xs uppercase tracking-wider ${muted}`, htmlFor: "tb-npub-field", children: "Enter npub (secure) or nsec (convenient)" }), _jsx("input", { id: "tb-npub-field", "data-tour": "tb.gate.npub", type: isNsec ? "password" : "text", value: value, onChange: (e) => {
                                     setValue(e.target.value);
                                     setGeneratedHint(false);
                                 }, onKeyDown: (e) => {
@@ -177,7 +177,7 @@ export default function NpubGate({ onLogin, startFresh = false, operatorHash, no
                                         signInWithNsec();
                                     else
                                         void begin();
-                                }, placeholder: "npub1\u2026", spellCheck: false, autoCapitalize: "off", autoCorrect: "off", className: input }), generatedHint && (_jsxs("div", { className: warnBox, children: ["New key generated. ", _jsx("b", { children: "Save this nsec" }), " somewhere safe \u2014 it's the only copy and it lives only in this browser."] })), _jsx("button", { type: "button", onClick: () => (isNsec ? signInWithNsec() : void begin()), disabled: !valid || busy, className: primary, children: busy ? "Sending…" : isNpub ? "Send message" : "Sign in" }), isNsec && _jsx("p", { className: `text-xs ${muted}`, children: "Your nsec stays in this browser and signs each call." }), isNpub && (_jsx("p", { className: `text-xs ${muted}`, children: "We send a message to your npub. Approve it from your Nostr client \u2014 your signature is the proof." })), _jsx("p", { className: `text-xs pt-1 ${muted}`, children: "Need a new identity?" }), _jsx("button", { type: "button", onClick: generateKey, className: ghost, children: "Generate a new key" })] })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: `${warnBox} space-y-1.5`, children: [_jsx("div", { className: "font-medium", children: "Message sent \u2014 open your Nostr client." }), _jsx("div", { children: "Reply with any text. Your signature on that reply is the proof." }), operatorHash && (_jsxs("div", { children: ["Sender fingerprint: ", _jsxs("span", { className: "font-mono", children: ["\uD83D\uDD12 ", operatorHash] })] }))] }), pendingProof && (_jsxs("div", { className: "rounded-lg p-3 text-xs border border-[var(--tb-accent)] space-y-2", children: [_jsx("div", { className: `uppercase tracking-wider text-[10px] ${muted}`, children: "Confirmation code" }), _jsx("div", { className: "font-mono text-base select-all", children: pendingProof }), _jsxs("div", { className: `leading-relaxed ${muted}`, children: ["The same code appears in the message. ", _jsx("b", { children: "Approve it only if the codes match." }), " If they differ \u2014 or the message points you somewhere other than this site \u2014 do not reply."] })] })), _jsx("button", { type: "button", onClick: () => void finish(), disabled: busy, className: primary, children: busy ? "Checking…" : "I've replied — verify" }), _jsx("button", { type: "button", onClick: () => void begin(), disabled: busy, className: ghost, children: "Resend" }), _jsx("button", { type: "button", onClick: reset, disabled: busy, className: `w-full text-xs py-1.5 ${muted}`, children: "Use a different npub" })] })), error && _jsx(Trouble, { raw: error, appName: appName }), note && _jsx("div", { className: `text-xs text-center italic ${muted}`, children: note })] }), steps && _jsx(SignInSteps, { stage: gateStage(stage, busy), classNames: { ...STEPS_LOOK, ...c.steps } }), links && _jsx(SignInLinks, { credit: linksCredit, classNames: { ...LINKS_LOOK, ...c.links } })] }));
+                                }, placeholder: "npub1\u2026", spellCheck: false, autoCapitalize: "off", autoCorrect: "off", className: input }), generatedHint && (_jsxs("div", { className: warnBox, children: ["New key generated. ", _jsx("b", { children: "Save this nsec" }), " somewhere safe \u2014 it's the only copy and it lives only in this browser."] })), _jsx("button", { type: "button", onClick: () => (isNsec ? signInWithNsec() : void begin()), disabled: !valid || busy, className: primary, "data-tour": "tb.gate.send", children: busy ? "Sending…" : isNpub ? "Send message" : "Sign in" }), isNsec && _jsx("p", { className: `text-xs ${muted}`, children: "Your nsec stays in this browser and signs each call." }), isNpub && (_jsx("p", { className: `text-xs ${muted}`, children: "We send a message to your npub. Approve it from your Nostr client \u2014 your signature is the proof." })), _jsx("p", { className: `text-xs pt-1 ${muted}`, children: "Need a new identity?" }), _jsx("button", { type: "button", onClick: generateKey, className: ghost, children: "Generate a new key" })] })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: `${warnBox} space-y-1.5`, children: [_jsx("div", { className: "font-medium", children: "Message sent \u2014 open your Nostr client." }), _jsx("div", { children: "Reply with any text. Your signature on that reply is the proof." }), operatorHash && (_jsxs("div", { children: ["Sender fingerprint: ", _jsxs("span", { className: "font-mono", children: ["\uD83D\uDD12 ", operatorHash] })] }))] }), pendingProof && (_jsxs("div", { className: "rounded-lg p-3 text-xs border border-[var(--tb-accent)] space-y-2", children: [_jsx("div", { className: `uppercase tracking-wider text-[10px] ${muted}`, children: "Confirmation code" }), _jsx("div", { className: "font-mono text-base select-all", children: pendingProof }), _jsxs("div", { className: `leading-relaxed ${muted}`, children: ["The same code appears in the message. ", _jsx("b", { children: "Approve it only if the codes match." }), " If they differ \u2014 or the message points you somewhere other than this site \u2014 do not reply."] })] })), _jsx("button", { type: "button", onClick: () => void finish(), disabled: busy, className: primary, "data-tour": "tb.gate.verify", children: busy ? "Checking…" : "I've replied — verify" }), _jsx("button", { type: "button", onClick: () => void begin(), disabled: busy, className: ghost, children: "Resend" }), _jsx("button", { type: "button", onClick: reset, disabled: busy, className: `w-full text-xs py-1.5 ${muted}`, children: "Use a different npub" })] })), error && _jsx(Trouble, { raw: error, appName: appName }), note && _jsx("div", { className: `text-xs text-center italic ${muted}`, children: note })] }), steps && _jsx(SignInSteps, { stage: gateStage(stage, busy), classNames: { ...STEPS_LOOK, ...c.steps } }), links && _jsx(SignInLinks, { credit: linksCredit, classNames: { ...LINKS_LOOK, ...c.links } })] }));
 }
 /** A failure, read to the person: the lead first, the service's own words underneath. */
 function Trouble({ raw, appName }) {

package/dist/react/SessionKeyClaim.js

@@ -155,9 +155,9 @@ function SessionKeyClaimInner({ actionClass }) {
         }
     }
     if (!revealed) {
-        return (_jsxs("div", { className: `${card} px-4 py-3`, children: [_jsx("div", { className: "eyebrow mb-1", children: "Session key" }), _jsxs("div", { className: "flex flex-wrap items-center gap-x-4 gap-y-2", children: [_jsx("p", { className: `min-w-[14rem] flex-1 text-[12.5px] leading-snug ${muted}`, children: "This browser is holding the secret key that signs you in. Take a copy before you clear site data or switch devices \u2014 without it, this identity is gone." }), _jsx("button", { type: "button", onClick: () => setRevealed(true), className: "min-h-11 shrink-0 rounded-full border border-[var(--tb-accent)] bg-[var(--tb-accent)] px-4 text-[13px] font-semibold text-[var(--tb-on-accent)]", children: "Claim your session key" })] })] }));
+        return (_jsxs("div", { className: `${card} px-4 py-3`, "data-tour": "tb.account.sessionKey", children: [_jsx("div", { className: "eyebrow mb-1", children: "Session key" }), _jsxs("div", { className: "flex flex-wrap items-center gap-x-4 gap-y-2", children: [_jsx("p", { className: `min-w-[14rem] flex-1 text-[12.5px] leading-snug ${muted}`, children: "This browser is holding the secret key that signs you in. Take a copy before you clear site data or switch devices \u2014 without it, this identity is gone." }), _jsx("button", { type: "button", onClick: () => setRevealed(true), className: "min-h-11 shrink-0 rounded-full border border-[var(--tb-accent)] bg-[var(--tb-accent)] px-4 text-[13px] font-semibold text-[var(--tb-on-accent)]", children: "Claim your session key" })] })] }));
     }
-    return (_jsxs("div", { className: `relative ${card} px-4 py-3`, children: [_jsxs("div", { className: "flex flex-wrap items-baseline justify-between gap-2", children: [_jsx("div", { className: "eyebrow mb-1", children: "Session key" }), _jsx("button", { type: "button", onClick: () => {
+    return (_jsxs("div", { className: `relative ${card} px-4 py-3`, "data-tour": "tb.account.sessionKey", children: [_jsxs("div", { className: "flex flex-wrap items-baseline justify-between gap-2", children: [_jsx("div", { className: "eyebrow mb-1", children: "Session key" }), _jsx("button", { type: "button", onClick: () => {
                             setRevealed(false);
                             setShowKey(false);
                             setDmOpen(false);

package/dist/react/SignInLinks.js

@@ -2,5 +2,5 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from "./cx.js";
 import { SIGN_IN_LINKS, SIGN_IN_LINKS_CREDIT } from "./signInTools.js";
 export default function SignInLinks({ links = SIGN_IN_LINKS, lead = "New to Nostr? These two are all it takes.", credit = true, classNames: c = {}, }) {
-    return (_jsxs("nav", { "aria-label": "Tools for signing in", className: c.root, children: [lead && _jsx("p", { className: c.lead, children: lead }), _jsx("ul", { className: c.list, children: links.map((l) => (_jsx("li", { className: c.item, children: _jsxs("a", { href: l.href, target: "_blank", rel: "noopener noreferrer", className: cx(c.link), children: [l.logo && _jsx("img", { src: l.logo, alt: "", width: 40, height: 40, className: c.logo }), _jsxs("span", { className: c.text, children: [_jsx("span", { className: c.name, children: l.name }), _jsx("span", { className: c.line, children: l.line })] })] }) }, l.id))) }), credit && _jsx("p", { className: c.credit, children: SIGN_IN_LINKS_CREDIT })] }));
+    return (_jsxs("nav", { "aria-label": "Tools for signing in", className: c.root, "data-tour": "tb.gate.links", children: [lead && _jsx("p", { className: c.lead, children: lead }), _jsx("ul", { className: c.list, children: links.map((l) => (_jsx("li", { className: c.item, children: _jsxs("a", { href: l.href, target: "_blank", rel: "noopener noreferrer", className: cx(c.link), children: [l.logo && _jsx("img", { src: l.logo, alt: "", width: 40, height: 40, className: c.logo }), _jsxs("span", { className: c.text, children: [_jsx("span", { className: c.name, children: l.name }), _jsx("span", { className: c.line, children: l.line })] })] }) }, l.id))) }), credit && _jsx("p", { className: c.credit, children: SIGN_IN_LINKS_CREDIT })] }));
 }

package/dist/react/SignInSteps.js

@@ -13,7 +13,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from "./cx.js";
 import { SIGN_IN_ACTORS, SIGN_IN_STEPS, stepState, } from "./signInFlow.js";
 export default function SignInSteps({ stage, steps = SIGN_IN_STEPS, actors = SIGN_IN_ACTORS, label = "How signing in works", classNames: c = {}, }) {
-    return (_jsx("ol", { "aria-label": label, className: c.root, children: steps.map((s, i) => {
+    return (_jsx("ol", { "aria-label": label, className: c.root, "data-tour": "tb.gate.steps", children: steps.map((s, i) => {
             const state = stepState(s, stage);
             return (_jsxs("li", { "data-state": state, "aria-current": state === "current" ? "step" : undefined, className: cx(c.step, c[state]), children: [_jsx("span", { "aria-hidden": true, className: c.glyph, children: s.glyph }), _jsx("span", { className: c.label, children: s.label }), _jsx("span", { className: c.actor, children: actors[s.actor] }), i < steps.length - 1 && (_jsx("span", { "aria-hidden": true, className: c.connector, children: "\u203A" }))] }, s.id));
         }) }));

package/dist/react/UsageSummary.js

@@ -48,6 +48,6 @@ export default function UsageSummary({ days = 30, heading, figures = ALL, labels
         void load();
     }, [load]);
     const shown = facts ? figures.filter((f) => f !== "expired" || facts.expired > 0) : [];
-    return (_jsxs("section", { className: c.root, children: [_jsxs("div", { className: c.header, children: [_jsx("div", { className: c.heading, children: heading ?? `Last ${days} days` }), refreshLabel !== null && (_jsx("button", { type: "button", onClick: () => void load(), disabled: loading, className: c.chip, children: loading ? "Loading…" : refreshLabel }))] }), error ? (_jsx("p", { className: c.error, children: error })) : !facts ? (loading && _jsx("p", { className: c.loading, children: "Loading\u2026" })) : (_jsxs(_Fragment, { children: [_jsx("div", { className: c.figures, children: shown.map((f) => (_jsxs("div", { className: c.figure, children: [_jsx("div", { className: c.value, children: facts[f].toLocaleString() }), _jsx("div", { className: c.label, children: labels[f] ?? LABELS[f] })] }, f))) }), topTools > 0 &&
+    return (_jsxs("section", { className: c.root, "data-tour": "tb.account.usage", children: [_jsxs("div", { className: c.header, children: [_jsx("div", { className: c.heading, children: heading ?? `Last ${days} days` }), refreshLabel !== null && (_jsx("button", { type: "button", onClick: () => void load(), disabled: loading, className: c.chip, children: loading ? "Loading…" : refreshLabel }))] }), error ? (_jsx("p", { className: c.error, children: error })) : !facts ? (loading && _jsx("p", { className: c.loading, children: "Loading\u2026" })) : (_jsxs(_Fragment, { children: [_jsx("div", { className: c.figures, children: shown.map((f) => (_jsxs("div", { className: c.figure, children: [_jsx("div", { className: c.value, children: facts[f].toLocaleString() }), _jsx("div", { className: c.label, children: labels[f] ?? LABELS[f] })] }, f))) }), topTools > 0 &&
                         (facts.tools.length === 0 ? (empty && _jsx("p", { className: c.empty, children: empty })) : (_jsxs(_Fragment, { children: [toolsHeading && _jsx("div", { className: c.subheading, children: toolsHeading }), _jsx("ul", { className: c.list, children: facts.tools.map((t) => (_jsx("li", { className: c.row, children: renderRow ? (renderRow(t)) : (_jsxs(_Fragment, { children: [_jsx("span", { className: c.tool, children: t.tool }), " ", _jsxs("span", { className: c.calls, children: [t.calls.toLocaleString(), " call", t.calls === 1 ? "" : "s"] }), " ", _jsxs("span", { className: c.sats, children: [t.sats.toLocaleString(), " sats"] })] })) }, t.tool))) })] })))] }))] }));
 }

package/dist/react/debugSpacer.d.ts

@@ -1,11 +1,13 @@
 /**
- * The room the DebugPanel keeps for itself.
+ * The room the DebugPanel keeps for itself — only while its log is open.
  *
- * The panel is fixed to the bottom of the viewport, so on its own it would sit
- * over whatever the page puts last — on a phone, a loading quote or a Save
- * button. Beside it the panel renders an in-flow spacer as tall as the panel is
- * right now (the collapsed tab, or the open log), plus the iOS home-indicator
- * inset, so the page can always scroll its last line clear of the bar.
+ * The panel is fixed to the bottom of the viewport. Collapsed, it is one small
+ * tab in the corner and overlays the page: an in-flow spacer for it stole a
+ * whole row from every screen (owner, 2026-09-27: "we want an overlay and not
+ * a row stealer"). Open, the log is tall and would hide whatever the page puts
+ * last — a Save button, a loading quote — so then, and only then, the panel
+ * renders an in-flow spacer as tall as it is, plus the iOS home-indicator
+ * inset, so the page can scroll its last line clear.
  */
 /** The collapsed tab: one `min-h-10` (2.5rem) button. Used until measured. */
 export declare const DEBUG_BAR_PX = 40;
@@ -13,3 +15,5 @@ export declare const DEBUG_BAR_PX = 40;
 export declare function debugSpacerPx(measured: number | null | undefined): number;
 /** The spacer's CSS height: the panel's height plus the safe-area inset. */
 export declare function debugSpacerHeight(measured: number | null | undefined): string;
+/** What the spacer takes: nothing while the panel is collapsed, its height while open. */
+export declare function debugSpacerRoom(open: boolean, measured: number | null | undefined): string;

package/dist/react/debugSpacer.js

@@ -1,11 +1,13 @@
 /**
- * The room the DebugPanel keeps for itself.
+ * The room the DebugPanel keeps for itself — only while its log is open.
  *
- * The panel is fixed to the bottom of the viewport, so on its own it would sit
- * over whatever the page puts last — on a phone, a loading quote or a Save
- * button. Beside it the panel renders an in-flow spacer as tall as the panel is
- * right now (the collapsed tab, or the open log), plus the iOS home-indicator
- * inset, so the page can always scroll its last line clear of the bar.
+ * The panel is fixed to the bottom of the viewport. Collapsed, it is one small
+ * tab in the corner and overlays the page: an in-flow spacer for it stole a
+ * whole row from every screen (owner, 2026-09-27: "we want an overlay and not
+ * a row stealer"). Open, the log is tall and would hide whatever the page puts
+ * last — a Save button, a loading quote — so then, and only then, the panel
+ * renders an in-flow spacer as tall as it is, plus the iOS home-indicator
+ * inset, so the page can scroll its last line clear.
  */
 /** The collapsed tab: one `min-h-10` (2.5rem) button. Used until measured. */
 export const DEBUG_BAR_PX = 40;
@@ -19,3 +21,7 @@ export function debugSpacerPx(measured) {
 export function debugSpacerHeight(measured) {
     return `calc(${debugSpacerPx(measured)}px + env(safe-area-inset-bottom, 0px))`;
 }
+/** What the spacer takes: nothing while the panel is collapsed, its height while open. */
+export function debugSpacerRoom(open, measured) {
+    return open ? debugSpacerHeight(measured) : "0px";
+}

package/dist/react/index.d.ts

@@ -33,3 +33,5 @@ export { useDebugLog } from "./useDebugLog.ts";
 export { useTheme } from "./useTheme.ts";
 export { useTimezone } from "./useTimezone.ts";
 export { useTopUp, type TopUp, type UseTopUpOptions } from "./useTopUp.ts";
+export { TourProvider, tourTarget, useTour, useTourReplay, useTourSwitch, type TourProviderProps, type UseTourOptions, } from "./useTour.tsx";
+export { buildTour, offerTour, OFFER_WORDS, type Offer, type OfferHooks, type OfferWords, type TourHooks, type TourRun } from "../tour/run.ts";

package/dist/react/index.js

@@ -32,3 +32,5 @@ export { useDebugLog } from "./useDebugLog.js";
 export { useTheme } from "./useTheme.js";
 export { useTimezone } from "./useTimezone.js";
 export { useTopUp } from "./useTopUp.js";
+export { TourProvider, tourTarget, useTour, useTourReplay, useTourSwitch, } from "./useTour.js";
+export { buildTour, offerTour, OFFER_WORDS } from "../tour/run.js";

package/dist/react/useTour.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The guided tour: who sees it, when it is offered, and how a page asks for
+ * its own.
+ *
+ * `TourProvider` holds the site's tours and the preference. A page calls
+ * `useTour(page, {actions})` once; when this device is due that page's tour,
+ * the page is watched for a quiet stretch and then asked, centred, whether it
+ * would like one. Yes starts the tour; No marks the page. A page asked to
+ * replay from its guide starts at once. `actions` are what a step may ask
+ * the page to do first — open the add form, pick a tag — by the names the
+ * copy uses.
+ *
+ * The site keeps its own switch and its own replay button: `useTourSwitch`
+ * and `useTourReplay` give them their mechanics.
+ */
+import { type ReactNode } from "react";
+import { type OfferWords } from "../tour/run.ts";
+import type { Tour, TourActions } from "../tour/types.ts";
+export interface TourProviderProps {
+    /** The site's tours, by page key — its own and the package's two. */
+    tours: Record<string, Tour>;
+    /** The quiet stretch before a page offers its tour. Defaults to the site's `tourIdleMs`, else 10 s. */
+    idleMs?: number;
+    /** The offer's words, when a site wants its own. */
+    words?: OfferWords;
+    children: ReactNode;
+}
+export declare function TourProvider({ tours, idleMs, words, children }: TourProviderProps): import("react").JSX.Element;
+export interface UseTourOptions {
+    actions?: TourActions;
+    /** False while the page has yet to draw what the tour points at. */
+    ready?: boolean;
+}
+/** Ask for this page's tour, if this device is due it. */
+export declare function useTour(page: string, { actions, ready }?: UseTourOptions): void;
+/** The site's "Live tutorial" switch: on replays every page, off stops them all. */
+export declare function useTourSwitch(): {
+    on: boolean;
+    setOn: (on: boolean) => void;
+};
+/** The site's "Show me on the page" button: that page's tour once more, at once. */
+export declare function useTourReplay(): (page: string) => void;
+/** The attribute to spread on the element a step points at. */
+export declare function tourTarget(name: string): {
+    "data-tour": string;
+};

package/dist/react/useTour.js

@@ -0,0 +1,128 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The guided tour: who sees it, when it is offered, and how a page asks for
+ * its own.
+ *
+ * `TourProvider` holds the site's tours and the preference. A page calls
+ * `useTour(page, {actions})` once; when this device is due that page's tour,
+ * the page is watched for a quiet stretch and then asked, centred, whether it
+ * would like one. Yes starts the tour; No marks the page. A page asked to
+ * replay from its guide starts at once. `actions` are what a step may ask
+ * the page to do first — open the add form, pick a tag — by the names the
+ * copy uses.
+ *
+ * The site keeps its own switch and its own replay button: `useTourSwitch`
+ * and `useTourReplay` give them their mechanics.
+ */
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { tollboothConfig } from "../config.js";
+import { ACTIVITY_EVENTS, idleThreshold, offerDue } from "../tour/idle.js";
+import { buildTour, offerTour } from "../tour/run.js";
+import { markToured, replayAll, replayPage, shouldRun, stopAll } from "../tour/state.js";
+import { onTourChange, readTourPrefs, settleTourPrefs, tourStorageKey, writeTourPrefs } from "../tourPrefs.js";
+const Ctx = createContext(null);
+function subscribe(changed) {
+    const stopPage = onTourChange(changed);
+    const onStorage = (e) => {
+        try {
+            if (e.key === tourStorageKey())
+                changed();
+        }
+        catch {
+            /* not configured yet: nothing of ours changed */
+        }
+    };
+    globalThis.addEventListener?.("storage", onStorage);
+    return () => {
+        stopPage();
+        globalThis.removeEventListener?.("storage", onStorage);
+    };
+}
+const onServer = () => ({ on: false, toured: {}, replay: null });
+export function TourProvider({ tours, idleMs, words, children }) {
+    const prefs = useSyncExternalStore(subscribe, readTourPrefs, onServer);
+    const update = useCallback((change) => {
+        writeTourPrefs(change(readTourPrefs()));
+    }, []);
+    const threshold = idleThreshold(tollboothConfig().tourIdleMs, idleMs);
+    // A newcomer's first reading is written down, so signing in a minute later
+    // does not turn them into an old hand.
+    useEffect(() => { settleTourPrefs(); }, []);
+    const value = useMemo(() => ({ prefs, update, tours, idleMs: threshold, words }), [prefs, update, tours, threshold, words]);
+    return _jsx(Ctx.Provider, { value: value, children: children });
+}
+/** Ask for this page's tour, if this device is due it. */
+export function useTour(page, { actions, ready = true } = {}) {
+    const ctx = useContext(Ctx);
+    const acts = useRef(actions);
+    acts.current = actions;
+    const due = ctx ? shouldRun(ctx.prefs, page) : false;
+    const atOnce = ctx?.prefs.replay === page;
+    const update = ctx?.update;
+    const tour = ctx?.tours[page];
+    const idleMs = ctx?.idleMs ?? 0;
+    const words = ctx?.words;
+    useEffect(() => {
+        if (!due || !ready || !update || !tour)
+            return;
+        let gone = false;
+        let run = null;
+        let offer = null;
+        const start = () => {
+            if (gone)
+                return;
+            run = buildTour(tour, {
+                run: (name) => acts.current?.[name]?.(),
+                onEnd: () => update((p) => markToured(p, page)),
+                onStop: () => update(stopAll),
+            });
+            run.start();
+        };
+        // From a guide, at once; otherwise after a quiet while, and only asked.
+        if (atOnce) {
+            const timer = window.setTimeout(start, 600);
+            return () => { gone = true; window.clearTimeout(timer); run?.stop(true); };
+        }
+        let last = Date.now();
+        const touched = () => { last = Date.now(); };
+        for (const ev of ACTIVITY_EVENTS)
+            window.addEventListener(ev, touched, { passive: true, capture: true });
+        const tick = window.setInterval(() => {
+            if (!offerDue(last, Date.now(), document.visibilityState === "visible", idleMs))
+                return;
+            window.clearInterval(tick);
+            for (const ev of ACTIVITY_EVENTS)
+                window.removeEventListener(ev, touched, { capture: true });
+            offer = offerTour({
+                onYes: start,
+                onNo: () => update((p) => markToured(p, page)),
+            }, words);
+            offer.show();
+        }, 1000);
+        return () => {
+            gone = true;
+            window.clearInterval(tick);
+            for (const ev of ACTIVITY_EVENTS)
+                window.removeEventListener(ev, touched, { capture: true });
+            offer?.dismiss();
+            run?.stop(true);
+        };
+    }, [page, due, atOnce, ready, update, tour, idleMs, words]);
+}
+/** The site's "Live tutorial" switch: on replays every page, off stops them all. */
+export function useTourSwitch() {
+    const ctx = useContext(Ctx);
+    const update = ctx?.update;
+    const setOn = useCallback((on) => { update?.(on ? replayAll : stopAll); }, [update]);
+    return { on: ctx?.prefs.on ?? false, setOn };
+}
+/** The site's "Show me on the page" button: that page's tour once more, at once. */
+export function useTourReplay() {
+    const ctx = useContext(Ctx);
+    const update = ctx?.update;
+    return useCallback((page) => { update?.((p) => replayPage(p, page)); }, [update]);
+}
+/** The attribute to spread on the element a step points at. */
+export function tourTarget(name) {
+    return { "data-tour": name };
+}

package/dist/tour/idle.d.ts

@@ -0,0 +1,19 @@
+/**
+ * When to offer a tour: after a stretch with nothing touched.
+ *
+ * A tour that starts the moment a page opens gets in the way of someone who
+ * knows the page. One offered after a pause finds the person who is looking
+ * for where to start. The policy is data here, so it is tested; the hook
+ * that listens for the events is in `react/useTour.ts`.
+ */
+/** How long a page may sit untouched before a tour is offered. */
+export declare const DEFAULT_IDLE_MS = 10000;
+/** Anything a person does to a page. */
+export declare const ACTIVITY_EVENTS: readonly ["pointerdown", "pointermove", "keydown", "wheel", "touchstart", "scroll"];
+/** The idle stretch a site asked for, or the default; never under a second. */
+export declare function idleThreshold(configured: number | undefined, override?: number): number;
+/**
+ * Whether a page has sat untouched long enough. A hidden tab is never idle:
+ * someone reading another tab has not gone quiet on this one.
+ */
+export declare function offerDue(lastActivityAt: number, now: number, visible: boolean, idleMs: number): boolean;

package/dist/tour/idle.js

@@ -0,0 +1,24 @@
+/**
+ * When to offer a tour: after a stretch with nothing touched.
+ *
+ * A tour that starts the moment a page opens gets in the way of someone who
+ * knows the page. One offered after a pause finds the person who is looking
+ * for where to start. The policy is data here, so it is tested; the hook
+ * that listens for the events is in `react/useTour.ts`.
+ */
+/** How long a page may sit untouched before a tour is offered. */
+export const DEFAULT_IDLE_MS = 10_000;
+/** Anything a person does to a page. */
+export const ACTIVITY_EVENTS = ["pointerdown", "pointermove", "keydown", "wheel", "touchstart", "scroll"];
+/** The idle stretch a site asked for, or the default; never under a second. */
+export function idleThreshold(configured, override) {
+    const ms = override ?? configured ?? DEFAULT_IDLE_MS;
+    return Number.isFinite(ms) && ms >= 1_000 ? ms : DEFAULT_IDLE_MS;
+}
+/**
+ * Whether a page has sat untouched long enough. A hidden tab is never idle:
+ * someone reading another tab has not gone quiet on this one.
+ */
+export function offerDue(lastActivityAt, now, visible, idleMs) {
+    return visible && now - lastActivityAt >= idleMs;
+}

package/dist/tour/lint.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The voice a tour speaks in, checked.
+ *
+ * A step says what a control is and what to do with it, in one or two short
+ * sentences. It never says what something is not, and never contrasts: "your
+ * npub is your key" and never "your key, not a password". A site's test runs
+ * its tours through this so every site holds the same voice.
+ */
+import type { Tour, TourStep } from "./types.ts";
+export declare const MAX_SAYS = 180;
+export declare const MAX_TITLE = 28;
+export declare const MAX_SENTENCES = 2;
+/** The problems with one step's words, each a sentence; none when it is well said. */
+export declare function lintStep(s: TourStep, page?: string): string[];
+/** Every problem in a tour's words. */
+export declare function lintTour(t: Tour): string[];
+/** Every problem across a site's tours. */
+export declare function lintTours(tours: Record<string, Tour>): string[];