@tollbooth-dpyc/web 1.7.1 → 1.8.1

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/client.d.ts

@@ -24,8 +24,9 @@ type ProofExpiredListener = (message: string) => void;
 export declare function onProofExpired(cb: ProofExpiredListener): () => void;
 export interface CallOptions {
     /**
-     * A non-essential call — diagnostics, personalization. It never logs the
-     * patron out, whatever it gets back.
+     * A non-essential call — diagnostics, personalization, a board polled all
+     * match. A soft proof miss here never logs the patron out; a stored grant
+     * the service refused for good (expired, revoked) still does.
      */
     bestEffort?: boolean;
     timeoutMs?: number;

package/dist/client.js

@@ -17,7 +17,7 @@ import { clearStoredProof, forgetRecentLogin, getStoredNpub, getStoredProof, } f
 import { signInlineProof } from "./inlineProof.js";
 import { isTransportFailure, NetworkError } from "./networkError.js";
 import { clearSessionNsec, hasSessionNsec, sessionNsecNpub } from "./sessionNsec.js";
-import { errorText, looksFailed, proofBounceMessage, readToolResult, } from "./toolResult.js";
+import { errorText, deadGrantMessage, looksFailed, proofBounceMessage, readToolResult, } from "./toolResult.js";
 /**
  * Standard tools whose wheel signature takes no npub/proof envelope. Pydantic
  * strict mode rejects unexpected kwargs, so they must not get one.
@@ -77,14 +77,14 @@ function proofFor(tool) {
         const npub = getStoredNpub();
         const sessionNpub = hasSessionNsec() ? sessionNsecNpub() : null;
         if (sessionNpub && sessionNpub === npub)
-            return signInlineProof(toolName(tool));
+            return { token: signInlineProof(toolName(tool)), inline: true };
         if (sessionNpub)
             clearSessionNsec();
     }
     catch {
         /* fall through to the cached token */
     }
-    return getStoredProof();
+    return { token: getStoredProof(), inline: false };
 }
 export { isNetworkError, NetworkError } from "./networkError.js";
 /** A paid call bounced for a lapsed or missing proof. The gate re-arms sign-in. */
@@ -131,9 +131,10 @@ export async function callToolWithContent(tool, args = {}, opts = {}) {
     if (!quiet)
         debugPush("call", `${name}(${redact(JSON.stringify(args)).slice(0, 140)})`);
     const bootstrap = STANDARD_BOOTSTRAP.includes(tool) || cfg.extraBootstrapTools.includes(tool);
-    const merged = bootstrap
-        ? { ...args }
-        : { npub: getStoredNpub(), dpop_token: proofFor(tool), ...args };
+    const proof = bootstrap ? null : proofFor(tool);
+    const merged = proof
+        ? { npub: getStoredNpub(), dpop_token: proof.token, ...args }
+        : { ...args };
     let result;
     try {
         const c = await getClient();
@@ -163,18 +164,20 @@ export async function callToolWithContent(tool, args = {}, opts = {}) {
         const tail = images.length ? ` +${images.length} image` : "";
         debugPush(looksFailed(payload) ? "error" : "result", `${name} → ${redact(String(preview)).slice(0, 220)}${tail}`);
     }
-    if (!opts.bestEffort) {
-        const bounced = proofBounceMessage(payload);
-        if (bounced !== null) {
-            // The token just refused is the same one the recent-login shortcut
-            // would replay, so it goes too, or a returning patron re-bounces.
-            const npub = getStoredNpub();
-            clearStoredProof();
-            if (npub)
-                forgetRecentLogin(npub);
-            emitProofExpired(bounced);
-            throw new ProofRequiredError(bounced);
-        }
+    // A stored grant the service refused for good signs the patron out even
+    // from a best-effort call: that is not a blip, and staying "signed in" on a
+    // dead grant leaves every page failing with nothing to tell them why.
+    const bounced = (opts.bestEffort ? null : proofBounceMessage(payload)) ??
+        (proof && !proof.inline && proof.token ? deadGrantMessage(payload) : null);
+    if (bounced !== null) {
+        // The token just refused is the same one the recent-login shortcut
+        // would replay, so it goes too, or a returning patron re-bounces.
+        const npub = getStoredNpub();
+        clearStoredProof();
+        if (npub)
+            forgetRecentLogin(npub);
+        emitProofExpired(bounced);
+        throw new ProofRequiredError(bounced);
     }
     return { data: payload, images };
 }

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/toolResult.d.ts

@@ -33,5 +33,16 @@ export declare function readToolResult(result: RawToolResult): ReadResult;
  * silently never fired. Normalised here, once.
  */
 export declare function proofBounceMessage(payload: unknown): string | null;
+/**
+ * A stored proof grant the service refused for good: `{success: false,
+ * error_code: proof_invalid, reason}` where the reason is about the grant —
+ * expired, revoked, issued for another npub or operator, malformed. Retrying
+ * with it can never succeed, so the patron is signed out.
+ *
+ * Only meaningful when the call carried the stored grant. A session key's
+ * inline proof shares the code and even the word `expired` (outside its
+ * window), but it is signed afresh for the next call and loses nothing.
+ */
+export declare function deadGrantMessage(payload: unknown): string | null;
 /** Whether a payload reports failure, for the debug log's colouring. */
 export declare function looksFailed(payload: unknown): boolean;

package/dist/toolResult.js

@@ -51,6 +51,33 @@ export function proofBounceMessage(payload) {
     }
     return null;
 }
+/**
+ * Grant refusals that say nothing about the grant: the service could not
+ * establish its own identity, or could not read its revocation list. Both are
+ * the service's fault and retryable, so the patron stays signed in.
+ */
+const GRANT_STILL_GOOD = new Set(["operator_unknown", "revocations_unavailable"]);
+/**
+ * A stored proof grant the service refused for good: `{success: false,
+ * error_code: proof_invalid, reason}` where the reason is about the grant —
+ * expired, revoked, issued for another npub or operator, malformed. Retrying
+ * with it can never succeed, so the patron is signed out.
+ *
+ * Only meaningful when the call carried the stored grant. A session key's
+ * inline proof shares the code and even the word `expired` (outside its
+ * window), but it is signed afresh for the next call and loses nothing.
+ */
+export function deadGrantMessage(payload) {
+    if (!payload || typeof payload !== "object")
+        return null;
+    const p = payload;
+    const code = String(p.error_code ?? "").toLowerCase();
+    if (p.success !== false || code !== "proof_invalid")
+        return null;
+    if (GRANT_STILL_GOOD.has(String(p.reason ?? "").toLowerCase()))
+        return null;
+    return String(p.error ?? "Your sign-in has expired.");
+}
 /** Whether a payload reports failure, for the debug log's colouring. */
 export function looksFailed(payload) {
     if (!payload || typeof payload !== "object")

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[];