@tollbooth-dpyc/web 1.7.1 → 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/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/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[];

package/dist/tour/lint.js

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+const CONTRAST = /\b(not|no|never|nothing|instead of|rather than)\b/i;
+export const MAX_SAYS = 180;
+export const MAX_TITLE = 28;
+export const MAX_SENTENCES = 2;
+function sentences(text) {
+    return text.split(/[.!?](\s|$)/).filter((x) => x.trim()).length;
+}
+/** The problems with one step's words, each a sentence; none when it is well said. */
+export function lintStep(s, page = "") {
+    const where = page ? `${page} "${s.title}"` : `"${s.title}"`;
+    const out = [];
+    if (!s.title.trim())
+        out.push(`${where}: has no title`);
+    if (s.title.length > MAX_TITLE)
+        out.push(`${where}: the title runs ${s.title.length} characters`);
+    if (!s.says.trim())
+        out.push(`${where}: says nothing`);
+    if (s.says.length > MAX_SAYS)
+        out.push(`${where}: runs ${s.says.length} characters`);
+    if (sentences(s.says) > MAX_SENTENCES)
+        out.push(`${where}: is more than ${MAX_SENTENCES} sentences`);
+    const m = CONTRAST.exec(s.says) ?? CONTRAST.exec(s.title);
+    if (m)
+        out.push(`${where}: says what something is not ("${m[0]}"): ${s.says}`);
+    return out;
+}
+/** Every problem in a tour's words. */
+export function lintTour(t) {
+    const out = [];
+    if (!t.steps.length)
+        out.push(`${t.page}: has no steps`);
+    for (const s of t.steps)
+        out.push(...lintStep(s, t.page));
+    return out;
+}
+/** Every problem across a site's tours. */
+export function lintTours(tours) {
+    return Object.values(tours).flatMap(lintTour);
+}

package/dist/tour/run.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A tour as driver.js runs it, and the offer that precedes it.
+ *
+ * driver.js draws the popover and the cutout. This adds what it has no idea
+ * of: a page action before a step whose control must be opened first, a tour
+ * that ends when nothing later can be shown, a "Stop the tutorial" link in
+ * every popover, and the centred question a page asks after a quiet while.
+ *
+ * DOM code, so it is untested here as its peers are; the rules it applies
+ * live in `./state.ts` and `./idle.ts`, which are.
+ */
+import type { Tour } from "./types.ts";
+export interface TourRun {
+    start(): void;
+    /** Take the tour down. `silent` is for the page leaving under it. */
+    stop(silent?: boolean): void;
+}
+export interface TourHooks {
+    /** Do what a step asks for before it is pointed at. */
+    run(action: string): void | Promise<void>;
+    /** The tour ended by its last step or its ✕: this page is done. */
+    onEnd(): void;
+    /** "Stop the tutorial": off on every page. */
+    onStop(): void;
+}
+export declare const POPOVER_CLASS = "tb-tour";
+export declare function selector(name: string): string;
+export declare function buildTour(tour: Tour, hooks: TourHooks): TourRun;
+export interface OfferHooks {
+    onYes(): void;
+    /** "No", the ✕, or a tap outside: this page is done being asked. */
+    onNo(): void;
+}
+export interface Offer {
+    show(): void;
+    /** Take the question down without answering it. */
+    dismiss(): void;
+}
+/** The question a page asks after a quiet while, centred, with Yes and No. */
+export declare function offerTour(hooks: OfferHooks, words?: OfferWords): Offer;
+export interface OfferWords {
+    title: string;
+    says: string;
+    yes: string;
+    no: string;
+}
+export declare const OFFER_WORDS: OfferWords;

package/dist/tour/run.js

@@ -0,0 +1,163 @@
+/**
+ * A tour as driver.js runs it, and the offer that precedes it.
+ *
+ * driver.js draws the popover and the cutout. This adds what it has no idea
+ * of: a page action before a step whose control must be opened first, a tour
+ * that ends when nothing later can be shown, a "Stop the tutorial" link in
+ * every popover, and the centred question a page asks after a quiet while.
+ *
+ * DOM code, so it is untested here as its peers are; the rules it applies
+ * live in `./state.ts` and `./idle.ts`, which are.
+ */
+import { driver } from "driver.js";
+/** How long to wait for a control that a page action is still opening. */
+const WAIT_MS = 1500;
+export const POPOVER_CLASS = "tb-tour";
+export function selector(name) {
+    return `[data-tour="${name}"]`;
+}
+/** Whether a step's control is on the page right now. */
+function present(s) {
+    return typeof s.target === "string" ? !!document.querySelector(selector(s.target)) : !!s.target();
+}
+export function buildTour(tour, hooks) {
+    let silent = false;
+    // The step at or after `from` that can be shown: its control is on the
+    // page, or its page action will put it there. driver.js's own skipping of
+    // a missing element loses its place when the FIRST steps are missing, so
+    // the tour moves by index and decides for itself.
+    const showable = (from) => tour.steps.findIndex((s, j) => j >= from && (Boolean(s.before) || present(s)));
+    const showableBack = (from) => {
+        for (let j = from; j >= 0; j--)
+            if (present(tour.steps[j]))
+                return j;
+        return -1;
+    };
+    const steps = tour.steps.map((s) => ({
+        // driver.js types a finder as returning an Element; one that finds
+        // nothing returns null, which it treats as a missing element and skips.
+        element: typeof s.target === "string" ? selector(s.target) : s.target,
+        popover: {
+            title: s.title,
+            description: s.says,
+            side: s.side ?? "bottom",
+            align: s.align ?? "start",
+        },
+    }));
+    const d = driver({
+        steps,
+        popoverClass: POPOVER_CLASS,
+        showProgress: true,
+        progressText: "{{current}} of {{total}}",
+        nextBtnText: "Next",
+        prevBtnText: "Back",
+        doneBtnText: "Done",
+        allowClose: true,
+        overlayOpacity: 0.45,
+        stagePadding: 6,
+        stageRadius: 8,
+        smoothScroll: true,
+        skipMissingElement: true,
+        waitForElement: WAIT_MS,
+        onPopoverRender(popover) {
+            const stop = document.createElement("button");
+            stop.type = "button";
+            stop.className = "tb-tour-stop";
+            stop.textContent = "Stop the tutorial";
+            stop.addEventListener("click", () => { silent = true; hooks.onStop(); d.destroy(); });
+            popover.wrapper.appendChild(stop);
+        },
+        async onNextClick() {
+            // With no showable step left the tour is over.
+            const i = d.getActiveIndex() ?? 0;
+            const n = showable(i + 1);
+            if (n < 0) {
+                d.destroy();
+                return;
+            }
+            const next = tour.steps[n];
+            if (next.before)
+                await hooks.run(next.before);
+            d.moveTo(n);
+        },
+        onPrevClick() {
+            const i = d.getActiveIndex() ?? 0;
+            const b = showableBack(i - 1);
+            if (b >= 0)
+                d.moveTo(b);
+        },
+        onDestroyed() {
+            if (!silent)
+                hooks.onEnd();
+        },
+    });
+    return {
+        start() {
+            const i = showable(0);
+            if (i < 0) {
+                hooks.onEnd();
+                return;
+            }
+            const first = tour.steps[i];
+            if (first.before)
+                void Promise.resolve(hooks.run(first.before)).then(() => d.drive(i));
+            else
+                d.drive(i);
+        },
+        stop(quiet = true) {
+            silent = quiet;
+            if (d.isActive())
+                d.destroy();
+        },
+    };
+}
+/** The question a page asks after a quiet while, centred, with Yes and No. */
+export function offerTour(hooks, words = OFFER_WORDS) {
+    let answered = false;
+    let quiet = false;
+    const d = driver({
+        popoverClass: `${POPOVER_CLASS} tb-tour-offer`,
+        showButtons: [],
+        allowClose: true,
+        overlayOpacity: 0.3,
+        onPopoverRender(popover) {
+            const row = document.createElement("div");
+            row.className = "tb-tour-answer";
+            const no = document.createElement("button");
+            no.type = "button";
+            no.className = "tb-tour-no";
+            no.textContent = words.no;
+            no.addEventListener("click", () => { answered = true; d.destroy(); hooks.onNo(); });
+            const yes = document.createElement("button");
+            yes.type = "button";
+            yes.className = "tb-tour-yes";
+            yes.textContent = words.yes;
+            // The tour starts on the next tick. Started inside this click, the
+            // click would go on to the new tour's outside-click listener and close
+            // it before it was seen.
+            yes.addEventListener("click", () => { answered = true; d.destroy(); window.setTimeout(hooks.onYes, 0); });
+            row.append(no, yes);
+            popover.wrapper.appendChild(row);
+        },
+        onDestroyed() {
+            if (!answered && !quiet)
+                hooks.onNo();
+        },
+    });
+    return {
+        show() {
+            d.highlight({ popover: { title: words.title, description: words.says } });
+        },
+        dismiss() {
+            quiet = true;
+            if (d.isActive())
+                d.destroy();
+        },
+    };
+}
+export const OFFER_WORDS = {
+    title: "A tour?",
+    says: "Would you like a tour of this page? It points at each control and says what it is for.",
+    yes: "Yes",
+    no: "No",
+};

package/dist/tour/state.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Who sees a tour, and when it stops.
+ *
+ * Three facts, kept per site and per device: whether the live tutorial is on,
+ * which pages have had their tour, and a page asked to replay once from its
+ * guide. A new device starts with the tutorial on. A device that already
+ * holds a patron npub but no tour preference has been here since before the
+ * tour existed, and starts with it off — a patron who has used the site for a
+ * season is shown nothing until they ask.
+ */
+export interface TourPrefs {
+    on: boolean;
+    toured: Record<string, true>;
+    /** A page asked to show its tour once more, whatever the switch says. */
+    replay: string | null;
+}
+export declare const TOUR_DEFAULTS: TourPrefs;
+/** Should this page's tour be offered now? */
+export declare function shouldRun(p: TourPrefs, page: string): boolean;
+/** The page's tour ended — by its last step, its ✕, or a "No". Done for this device. */
+export declare function markToured<P extends TourPrefs>(p: P, page: string): P;
+/** "Stop the tutorial", from any popover: off on every page. */
+export declare function stopAll<P extends TourPrefs>(p: P): P;
+/** The switch turned on in the profile: every page offers its tour again. */
+export declare function replayAll<P extends TourPrefs>(p: P): P;
+/** "Show me on the page", from a guide: that page once more, and only it. */
+export declare function replayPage<P extends TourPrefs>(p: P, page: string): P;
+/**
+ * The preference as stored, read back. `raw` is the parsed JSON or null when
+ * nothing is stored; `oldHand` says whether this device already held a patron
+ * npub, which is what makes a device with no preference an old hand rather
+ * than a newcomer.
+ */
+export declare function fromStored(raw: unknown, oldHand: boolean): TourPrefs;

package/dist/tour/state.js

@@ -0,0 +1,54 @@
+/**
+ * Who sees a tour, and when it stops.
+ *
+ * Three facts, kept per site and per device: whether the live tutorial is on,
+ * which pages have had their tour, and a page asked to replay once from its
+ * guide. A new device starts with the tutorial on. A device that already
+ * holds a patron npub but no tour preference has been here since before the
+ * tour existed, and starts with it off — a patron who has used the site for a
+ * season is shown nothing until they ask.
+ */
+export const TOUR_DEFAULTS = { on: true, toured: {}, replay: null };
+/** Should this page's tour be offered now? */
+export function shouldRun(p, page) {
+    if (p.replay === page)
+        return true;
+    return p.on && !p.toured[page];
+}
+/** The page's tour ended — by its last step, its ✕, or a "No". Done for this device. */
+export function markToured(p, page) {
+    return { ...p, toured: { ...p.toured, [page]: true }, replay: p.replay === page ? null : p.replay };
+}
+/** "Stop the tutorial", from any popover: off on every page. */
+export function stopAll(p) {
+    return { ...p, on: false, replay: null };
+}
+/** The switch turned on in the profile: every page offers its tour again. */
+export function replayAll(p) {
+    return { ...p, on: true, toured: {}, replay: null };
+}
+/** "Show me on the page", from a guide: that page once more, and only it. */
+export function replayPage(p, page) {
+    const toured = { ...p.toured };
+    delete toured[page];
+    return { ...p, toured, replay: page };
+}
+/**
+ * The preference as stored, read back. `raw` is the parsed JSON or null when
+ * nothing is stored; `oldHand` says whether this device already held a patron
+ * npub, which is what makes a device with no preference an old hand rather
+ * than a newcomer.
+ */
+export function fromStored(raw, oldHand) {
+    if (raw == null || typeof raw !== "object")
+        return { ...TOUR_DEFAULTS, on: !oldHand };
+    const r = raw;
+    const toured = r.toured && typeof r.toured === "object"
+        ? Object.fromEntries(Object.entries(r.toured).filter(([, v]) => v === true))
+        : {};
+    return {
+        on: typeof r.on === "boolean" ? r.on : !oldHand,
+        toured,
+        replay: typeof r.replay === "string" ? r.replay : null,
+    };
+}

package/dist/tour/tours.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The two tours every site shares, because the pages are the package's: the
+ * sign-in gate, and the account page's panels. A site puts them in its tour
+ * map beside its own, and adds its own steps after the panels' for whatever
+ * else its account page holds.
+ *
+ * The copy says what each thing is, in the words the network uses — Patron,
+ * npub, MCP tool, api_sats — in a sentence or two.
+ */
+import type { Tour, TourStep } from "./types.ts";
+/** The `data-tour` names the package's own markup carries. */
+export declare const TB_TARGETS: {
+    readonly gateNpub: "tb.gate.npub";
+    readonly gateLinks: "tb.gate.links";
+    readonly gateSend: "tb.gate.send";
+    readonly gateSteps: "tb.gate.steps";
+    readonly gateVerify: "tb.gate.verify";
+    readonly accountProfile: "tb.account.profile";
+    readonly accountUsage: "tb.account.usage";
+    readonly accountCoupons: "tb.account.coupons";
+    readonly accountSessionKey: "tb.account.sessionKey";
+};
+/** The sign-in gate, from the field to the moment of being in. */
+export declare function signInTour(page?: string): Tour;
+/** The account page's package panels: the usage table, the persona, coupons, the session key. */
+export declare function accountPanelsSteps(): TourStep[];
+/** The account page as the package knows it; a site appends its own steps. */
+export declare function accountTour(page?: string, own?: TourStep[]): Tour;

package/dist/tour/tours.js

@@ -0,0 +1,54 @@
+/**
+ * The two tours every site shares, because the pages are the package's: the
+ * sign-in gate, and the account page's panels. A site puts them in its tour
+ * map beside its own, and adds its own steps after the panels' for whatever
+ * else its account page holds.
+ *
+ * The copy says what each thing is, in the words the network uses — Patron,
+ * npub, MCP tool, api_sats — in a sentence or two.
+ */
+/** The `data-tour` names the package's own markup carries. */
+export const TB_TARGETS = {
+    gateNpub: "tb.gate.npub",
+    gateLinks: "tb.gate.links",
+    gateSend: "tb.gate.send",
+    gateSteps: "tb.gate.steps",
+    gateVerify: "tb.gate.verify",
+    accountProfile: "tb.account.profile",
+    accountUsage: "tb.account.usage",
+    accountCoupons: "tb.account.coupons",
+    accountSessionKey: "tb.account.sessionKey",
+};
+/** The sign-in gate, from the field to the moment of being in. */
+export function signInTour(page = "signin") {
+    const steps = [
+        { target: TB_TARGETS.gateNpub, title: "Your npub",
+            says: "Paste your npub here. An nsec works too and stays in this browser." },
+        { target: TB_TARGETS.gateLinks, title: "Get a key",
+            says: "Get a free key in 0xchat or Pricing Studio. Either makes one in a minute.", side: "top" },
+        { target: TB_TARGETS.gateSend, title: "Send",
+            says: "We send a message to your Nostr client. Reply to it with any words." },
+        { target: TB_TARGETS.gateSteps, title: "The proof",
+            says: "Your signed reply is the proof. The tiles show where you are.", side: "top" },
+        { target: TB_TARGETS.gateVerify, title: "Verify",
+            says: "Replied? Tap here and you are in." },
+    ];
+    return { page, steps };
+}
+/** The account page's package panels: the usage table, the persona, coupons, the session key. */
+export function accountPanelsSteps() {
+    return [
+        { target: TB_TARGETS.accountUsage, title: "What each tool drew",
+            says: "Every MCP tool you have called, how many times, and the api_sats each cost. The operator sets the prices; this is what was paid.", side: "top" },
+        { target: TB_TARGETS.accountProfile, title: "Your Nostr persona",
+            says: "The name, picture, bio and addresses Nostr shows for your npub. Tap Edit to change them; they publish to your Nostr profile.", side: "top" },
+        { target: TB_TARGETS.accountCoupons, title: "Coupons",
+            says: "A code an operator hands out. Redeem it once here and it discounts your MCP tool fees on its own after that.", side: "top" },
+        { target: TB_TARGETS.accountSessionKey, title: "Your session key",
+            says: "This browser holds a key that signs each call for you. Claim it here to carry it to another device.", side: "top" },
+    ];
+}
+/** The account page as the package knows it; a site appends its own steps. */
+export function accountTour(page = "account", own = []) {
+    return { page, steps: [...accountPanelsSteps(), ...own] };
+}

package/dist/tour/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The shape of a page's guided tour: a handful of steps, each pointing at one
+ * control and saying what it is for.
+ *
+ * Data with no DOM in it, so a site's copy can be tested: every target drawn,
+ * every sentence saying what a thing IS. The mechanics that run it are in
+ * `./run.ts` and `react/useTour.ts`; the words are each site's own, except
+ * for the two pages every site shares (`./tours.ts`).
+ */
+export interface TourStep {
+    /**
+     * A `data-tour` name on the element, or — for markup a site does not own —
+     * a function that finds it. A function that finds nothing skips the step.
+     */
+    target: string | (() => Element | null);
+    title: string;
+    /** One or two short sentences: what the control is, what to do with it. */
+    says: string;
+    side?: "top" | "right" | "bottom" | "left";
+    align?: "start" | "center" | "end";
+    /**
+     * Something the page must do before this step can be pointed at — open the
+     * add form, pick a tag. The page registers the action by this name.
+     */
+    before?: string;
+    /** The guide step this abbreviates, for a site's own test: [group, control]. */
+    guide?: [group: string, control: string];
+}
+export interface Tour {
+    /** The page's key, as the site names its views. */
+    page: string;
+    steps: TourStep[];
+}
+/** What a step may ask the page to do first, by name. */
+export type TourActions = Record<string, () => void | Promise<void>>;

package/dist/tour/types.js

@@ -0,0 +1,10 @@
+/**
+ * The shape of a page's guided tour: a handful of steps, each pointing at one
+ * control and saying what it is for.
+ *
+ * Data with no DOM in it, so a site's copy can be tested: every target drawn,
+ * every sentence saying what a thing IS. The mechanics that run it are in
+ * `./run.ts` and `react/useTour.ts`; the words are each site's own, except
+ * for the two pages every site shares (`./tours.ts`).
+ */
+export {};

package/dist/tourPrefs.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The guided tour's preference, stored per site and per device under
+ * `<prefix>:tour:v1`: whether the live tutorial is on, which pages have had
+ * their tour, and a page asked to replay once. The rules are in
+ * `tour/state.ts`; this is their storage, in the shape `timezone.ts` set.
+ */
+import { type TourPrefs } from "./tour/state.ts";
+/** `<prefix>:tour:v1` — for a `storage` event listener. */
+export declare function tourStorageKey(): string;
+export declare function readTourPrefs(): TourPrefs;
+/** Store the preference and tell every listener on the page. */
+export declare function writeTourPrefs(next: TourPrefs): TourPrefs;
+/** Hear every `writeTourPrefs` on this page. Returns an unsubscribe. */
+export declare function onTourChange(fn: (p: TourPrefs) => void): () => void;
+/**
+ * Write the preference down if nothing is stored yet. A newcomer is read as
+ * "on" while they hold no npub; the moment they sign in they would read as
+ * an old hand and the tutorial would go quiet mid-welcome. Settling the
+ * first reading keeps a newcomer a newcomer.
+ */
+export declare function settleTourPrefs(): TourPrefs;

package/dist/tourPrefs.js

@@ -0,0 +1,70 @@
+/**
+ * The guided tour's preference, stored per site and per device under
+ * `<prefix>:tour:v1`: whether the live tutorial is on, which pages have had
+ * their tour, and a page asked to replay once. The rules are in
+ * `tour/state.ts`; this is their storage, in the shape `timezone.ts` set.
+ */
+import { getStoredNpub } from "./identity.js";
+import { key, readStored, writeStored } from "./storage.js";
+import { fromStored } from "./tour/state.js";
+const PREF = "tour:v1";
+/** `<prefix>:tour:v1` — for a `storage` event listener. */
+export function tourStorageKey() {
+    return key(PREF);
+}
+// The last raw value read and what it parsed to. `useSyncExternalStore`
+// wants the same object back while nothing changed; a fresh parse each read
+// would be a new object every time and a render that never settles.
+let lastRaw = null;
+let lastOldHand = false;
+let lastPrefs = null;
+export function readTourPrefs() {
+    const raw = readStored(PREF);
+    // A device that already holds a patron npub but no tour preference has
+    // been here since before the tour existed, and is left in peace. Read each
+    // time: signing in changes it.
+    const oldHand = raw === "" && !!getStoredNpub();
+    if (lastPrefs && raw === lastRaw && oldHand === lastOldHand)
+        return lastPrefs;
+    let parsed = null;
+    if (raw) {
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            parsed = null;
+        }
+    }
+    lastPrefs = fromStored(parsed, oldHand);
+    lastRaw = raw;
+    lastOldHand = oldHand;
+    return lastPrefs;
+}
+const listeners = new Set();
+/** Store the preference and tell every listener on the page. */
+export function writeTourPrefs(next) {
+    writeStored(PREF, JSON.stringify(next));
+    lastRaw = null;
+    const stored = readTourPrefs();
+    listeners.forEach((fn) => fn(stored));
+    return stored;
+}
+/** Hear every `writeTourPrefs` on this page. Returns an unsubscribe. */
+export function onTourChange(fn) {
+    listeners.add(fn);
+    return () => {
+        listeners.delete(fn);
+    };
+}
+/**
+ * Write the preference down if nothing is stored yet. A newcomer is read as
+ * "on" while they hold no npub; the moment they sign in they would read as
+ * an old hand and the tutorial would go quiet mid-welcome. Settling the
+ * first reading keeps a newcomer a newcomer.
+ */
+export function settleTourPrefs() {
+    const current = readTourPrefs();
+    if (readStored(PREF) === "")
+        writeTourPrefs(current);
+    return current;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tollbooth-dpyc/web",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Shared browser SDK for Tollbooth DPYC operator front ends: npub sign-in, proofs, MCP client, profile and wallet",
   "license": "Apache-2.0",
   "author": "Lonnie VanZandt",
@@ -25,11 +25,13 @@
       "types": "./dist/pagesProxy.d.ts",
       "default": "./dist/pagesProxy.js"
     },
-    "./theme.css": "./theme.css"
+    "./theme.css": "./theme.css",
+    "./tour.css": "./tour.css"
   },
   "files": [
     "dist",
     "theme.css",
+    "tour.css",
     "README.md",
     "LICENSE"
   ],
@@ -55,5 +57,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "driver.js": "1.9.0"
   }
 }

package/tour.css

@@ -0,0 +1,103 @@
+/*
+ * The guided tour's popover, in the site's own tokens.
+ *
+ * driver.js draws it; these rules give it the site's surface, ink and line
+ * through the --tb-* variables theme.css defines, and the structure the
+ * tour adds: the "Stop the tutorial" link under the buttons, and the Yes/No
+ * pair on the offer. Colours are the site's; a site may restyle `.tb-tour`
+ * further (the title's font, say) in its own stylesheet.
+ */
+
+@import "driver.js/dist/driver.css";
+
+.driver-popover.tb-tour {
+  font-family: inherit;
+  color: var(--tb-ink);
+  background-color: var(--tb-surface);
+  border: 1px solid var(--tb-line);
+  border-radius: 10px;
+  box-shadow: 0 8px 28px rgba(0, 0, 0, 0.18);
+  max-width: min(320px, calc(100vw - 24px));
+  padding: 14px 16px 12px;
+}
+.tb-tour .driver-popover-title {
+  font-size: 17px;
+  font-weight: 600;
+  line-height: 1.3;
+  color: var(--tb-ink);
+}
+.tb-tour .driver-popover-description {
+  margin-top: 6px;
+  font-size: 13.5px;
+  line-height: 1.45;
+  color: var(--tb-ink);
+}
+.tb-tour .driver-popover-close-btn {
+  top: 2px;
+  right: 2px;
+  width: 36px;
+  height: 36px;
+  color: var(--tb-muted);
+}
+.tb-tour .driver-popover-close-btn:hover,
+.tb-tour .driver-popover-close-btn:focus { color: var(--tb-ink); }
+.tb-tour .driver-popover-footer { margin-top: 12px; gap: 8px; }
+.tb-tour .driver-popover-progress-text {
+  font-size: 11px;
+  color: var(--tb-muted);
+}
+.tb-tour .driver-popover-footer-btn,
+.tb-tour .tb-tour-yes,
+.tb-tour .tb-tour-no {
+  font-family: inherit;
+  font-size: 12.5px;
+  font-weight: 500;
+  min-height: 36px;
+  padding: 0 14px;
+  border-radius: 999px;
+  border: 1.5px solid var(--tb-line);
+  background-color: var(--tb-surface);
+  color: var(--tb-muted);
+  cursor: pointer;
+}
+.tb-tour .driver-popover-next-btn,
+.tb-tour .tb-tour-yes {
+  border-color: var(--tb-accent);
+  background-color: var(--tb-accent);
+  color: var(--tb-on-accent);
+}
+.tb-tour .driver-popover-footer-btn:hover,
+.tb-tour .driver-popover-footer-btn:focus,
+.tb-tour .tb-tour-no:hover,
+.tb-tour .tb-tour-no:focus { background-color: var(--tb-surface-2); }
+.tb-tour .driver-popover-next-btn:hover,
+.tb-tour .driver-popover-next-btn:focus,
+.tb-tour .tb-tour-yes:hover,
+.tb-tour .tb-tour-yes:focus { background-color: var(--tb-accent); }
+.tb-tour .tb-tour-stop {
+  display: block;
+  margin-top: 10px;
+  padding: 0;
+  border: 0;
+  background: none;
+  font-family: inherit;
+  font-size: 11.5px;
+  color: var(--tb-muted);
+  text-decoration: underline;
+  text-decoration-style: dotted;
+  text-underline-offset: 2px;
+  cursor: pointer;
+}
+.tb-tour .tb-tour-answer {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  margin-top: 14px;
+}
+/* The offer has no element to point at; it sits in the middle of the page. */
+.tb-tour.tb-tour-offer .driver-popover-arrow { display: none; }
+/* The arrow takes the surface colour on whichever side it points from. */
+.tb-tour .driver-popover-arrow-side-left { border-left-color: var(--tb-surface); }
+.tb-tour .driver-popover-arrow-side-right { border-right-color: var(--tb-surface); }
+.tb-tour .driver-popover-arrow-side-top { border-top-color: var(--tb-surface); }
+.tb-tour .driver-popover-arrow-side-bottom { border-bottom-color: var(--tb-surface); }