@reticlehq/browser 2.13.1 → 3.1.0

package/dist/presenter/presenter.js

@@ -1,28 +1,23 @@
-import { ActionType, ReticleCommand, PresenterMode, SessionState, isPresenterTone, isSessionState, } from '@reticlehq/core';
-import { refs } from '../dom/refs.js';
+import { ActionType, HumanControlKind, ReticleCommand, PresenterMode, SessionState, isPresenterTone, isSessionState, } from '@reticlehq/core';
+import { refs } from '../dom/addressing/refs.js';
 import { unreachableStripText } from '../transport/unreachable-message.js';
-import { actionVerb } from './presenter-verbs.js';
-import { nativeSetTimeout, nativeClearTimeout, nativeNow } from '../timers/native-timers.js';
-import { LOG_KIND, CHIP_LABEL, DATA_RETICLE_LOG, clampLogMax, formatElapsed, humanDuration, appendLogRow, } from './presenter-log.js';
+import { actionVerb } from './chrome/presenter-verbs.js';
+import { nativeSetTimeout, nativeClearTimeout, nativeNow } from '../timers/native/native-timers.js';
+import { LOG_KIND, CHIP_LABEL, DATA_RETICLE_LOG, clampLogMax, formatElapsed, humanDuration, appendLogRow, } from './chrome/presenter-log.js';
 import { PRESENTER_CSS } from './presenter-styles.js';
 import { HudShell } from './presenter-shell.js';
-import { parseImpactSnapshot } from './presenter-report-copy.js';
+import { parseImpactSnapshot } from './chrome/presenter-report-copy.js';
 import { BorderMode, DEFAULT_BORDER_MODE, DATA_BUSY, BUSY_OFF, effectivePaceMs, IDLE_AFTER_MS, HEARTBEAT_MS, IDLE_NOTICE_MS, IDLE_END_MS, IDLE_END_MIN_MS, ACT_STRIP, STATE_ATTR, UNREACHABLE_STATE, GLOW_FADE_MS, GLOW_ON, GLOW_OFF, DATA_ON, THROTTLED_ATTR, LIVENESS_ATTR, MARKERS_BTN_ATTR, CLEAR_MARKS_ATTR, MARK_COUNT_ATTR, } from './presenter-config.js';
 import { buildRunState } from './presenter-run-state.js';
-import { moveCursor, ringAround, spawnRipple, pace } from './presenter-effects.js';
+import { moveCursor, ringAround, spawnRipple, pace } from './chrome/presenter-effects.js';
 import { GlowController } from './presenter-glow.js';
-import { PresenterIcon, PRESENTER_ICON_SIZE, hiIcon } from './presenter-icons.js';
-import { renderTally } from './presenter-tally.js';
+import { PresenterIcon, PRESENTER_ICON_SIZE, hiIcon } from './icons/presenter-icons.js';
+import { renderTally } from './chrome/presenter-tally.js';
 import { CONTROLS_BANNER_HTML, CONTROLS_FLOWS_HTML, CONTROLS_FOOT_HTML, ENDED_FADE_MS, ControlPanel, } from './presenter-controls.js';
 import { statusTheme, blockerHtml, getPresenterSettings, OutputDetail, syncPageBlocker, } from './presenter-settings.js';
 import { Annotator } from '../review/annotator.js';
-// Re-export the config surface so the public import path (`./presenter.js`) is unchanged.
 export { GlowPhase } from './presenter-config.js';
-export { LOG_KIND, LOG_RESULT } from './presenter-log.js';
-// Presenter / transparency layer: a human watches the agent work. Glowing border while
-// active, a synthetic cursor that flies to targets, click/hover/type effects, and a HUD that
-// shows the current action + the agent's narrated intent. All nodes carry data-reticle-* attrs
-// so they're excluded from snapshots/observers (see dom-ignore.ts).
+export { LOG_KIND, LOG_RESULT } from './chrome/presenter-log.js';
 export class Presenter {
     #paceMs;
     #root;
@@ -32,12 +27,9 @@ export class Presenter {
     #hud;
     #actLine;
     #actStrip;
-    /** Label inside the minimised-chat capsule; mirrors the act strip. */
     #chatPillText;
-    /** Age of the last action, shown in the capsule's own slot. */
     #chatPillTime;
     #chip;
-    /** Live verdict tally (✓N ✗M) in the header - the running testing score the human watches. */
     #tally;
     #tallied = { passes: 0, fails: 0 };
     #mode = PresenterMode.IDLE;
@@ -45,25 +37,18 @@ export class Presenter {
     #heartbeatMs;
     #idleNoticeMs;
     #borderMode;
-    /** The glow / activity state machine (border shimmer + cursor visibility from activity timing). */
     #glowCtl;
-    /** Liveness: the most recent action text + a 1s ticker that ages it into an "idle · {dur}" clock. */
     #lastActionText = '';
     #heartbeatTimer;
-    /** Session lifecycle: idle-end window (tweakable), session id, start/end cursors, structured run log. */
     #idleEndMs;
     #sessionId;
     #startMs;
     #endMs;
     #runLog = [];
-    /** Tracks sessionStart/sessionEnd so both are idempotent (no strobe / no spurious off-write). */
     #sessionActive = false;
-    // v2: narration + action status accumulate in a persistent, timestamped, scrollable log.
     #logMax;
     #log;
-    /** now of the first row, the baseline for the +elapsed timestamps. */
     #logBaseMs;
-    // Live-control panel: the two-way control surface (Pause/Resume + End + message Send).
     #onControl;
     #panel;
     #shell;
@@ -100,6 +85,7 @@ export class Presenter {
             onExpand: () => this.#syncAnnotator(),
             onAnnotateToggle: () => this.#syncAnnotator(),
             onCollapse: () => this.#syncAnnotator(),
+            onSyncNow: () => this.#onControl?.({ kind: HumanControlKind.SYNC }),
             settings: {
                 onBeforeOpen: () => {
                     if (this.#shell.isCollapsed())
@@ -110,26 +96,18 @@ export class Presenter {
             },
         });
     }
-    /** Setter so reticle.ts can wire the control callback after construction. */
     setControlHandler(handler) {
         this.#onControl = handler;
     }
-    /** Current live-control session state mirrored onto the panel (data-reticle-state). */
     get state() {
         return this.#panel.state;
     }
-    /** Whether a run is currently being presented (false before the agent's first activity / after end). */
     get sessionActive() {
         return this.#sessionActive;
     }
-    /** Drive the panel's live-control visual state (server-push / agent path; never emits). */
     setState(state, text, tone) {
         this.#panel.setState(state, text, tone);
     }
-    /** Apply a bridge→browser presenter push: PRESENTER (state echo) or FLOWS (replay list, the human's
-     * no-agent replay surface). Owns the wire parsing so the SDK dispatcher stays a thin router;
-     * setState-only so an echo can't re-emit. */
-    /** Re-scope the replay-flow chips to the current page (called by the SDK on route change). */
     refilterFlows() {
         this.#panel.refilterFlows();
     }
@@ -139,8 +117,15 @@ export class Presenter {
             return void this.#panel.setFlows(a['flows']);
         if (command.name === ReticleCommand.IMPACT) {
             const snapshot = parseImpactSnapshot(a['snapshot']);
-            if (snapshot !== undefined)
+            if (snapshot !== undefined) {
                 this.#shell.report.setSnapshot(snapshot);
+                this.#shell.paintAccount(snapshot.account, snapshot.dashboardUrl, {
+                    projectName: snapshot.projectName,
+                    dashboardUrl: snapshot.dashboardUrl,
+                    verdicts: snapshot.project.counts.verdicts,
+                    defects: snapshot.project.counts.failed,
+                });
+            }
             return;
         }
         const state = a['state'];
@@ -149,7 +134,6 @@ export class Presenter {
         if (isSessionState(state))
             this.setState(state, text, isPresenterTone(tone) ? tone : undefined);
     }
-    /** Current cap on accumulated log rows. */
     get logMax() {
         return this.#logMax;
     }
@@ -166,10 +150,6 @@ export class Presenter {
         document.head.appendChild(style);
         const root = document.createElement('div');
         root.setAttribute('data-reticle-overlay', '');
-        // The mode rides ON the status row, next to the dot and the elapsed time it already reports.
-        // It used to be a sibling BELOW the strip, hidden except while reading or acting — so every
-        // single tool call popped a block into the panel and took it away again, which reads as a
-        // second UI flashing in rather than as the one status line changing what it says.
         const actStrip = `<div class="reticle-act-strip" data-liveness="idle"><span class="reticle-act-dot" aria-hidden="true"></span><span class="reticle-act">${ACT_STRIP.READY}</span><span class="reticle-chip" data-reticle-chip></span></div>`;
         root.innerHTML = `
       ${blockerHtml()}
@@ -195,12 +175,10 @@ export class Presenter {
         this.#shell.mount(root);
         syncPageBlocker(root, getPresenterSettings(), false);
         this.#glowCtl.setElements(this.#glow, this.#cursor);
-        // The panel queries its refs, binds listeners, and paints the initial active state.
         this.#panel.mount(root, this.#glow);
         this.setMode(this.#mode);
         this.#renderTally();
     }
-    /** Wire annotation chrome; expanding the HUD enters annotate mode. */
     bindAnnotator(annotator) {
         this.#annotator = annotator;
         const root = this.#root;
@@ -220,12 +198,7 @@ export class Presenter {
         annotator.setAccent(statusTheme(getPresenterSettings().statusThemeId).active);
         this.#syncAnnotator();
     }
-    /** Annotate whenever the HUD is open and the person asked for it - agent or no agent. */
     #syncAnnotator() {
-        // Two things have to agree, and both are the user's: the HUD is open, and annotate is switched
-        // on. Session state used to be a third, so the mode was refused the moment the agent
-        // disconnected - which is precisely when someone opens the HUD to record what they just saw.
-        // The button still lit up, so the refusal was invisible: no outline, no composer, no reason.
         const live = !this.#shell.isCollapsed() && this.#shell.isAnnotateOn();
         this.#annotator?.toggle(live);
         if (this.#root !== undefined) {
@@ -246,19 +219,13 @@ export class Presenter {
         document.querySelectorAll('style[data-reticle-overlay]').forEach((s) => s.remove());
         this.#root = undefined;
     }
-    /**
-     * Session start: in 'session' border mode this fades the base border IN and keeps it on until
-     * sessionEnd. Idempotent, and a no-op when unmounted or in 'busy' border mode.
-     */
     sessionStart() {
-        // Returning agent activity after the session ended (idle or explicit) revives it as a fresh run.
         if (this.state === SessionState.ENDED) {
             this.#revive();
             return;
         }
         if (this.#sessionActive)
             return;
-        // A bridge that answered supersedes whatever the failed connect left on screen.
         if (UNREACHABLE_STATE === this.#root?.getAttribute(STATE_ATTR))
             this.#root.removeAttribute(STATE_ATTR);
         this.#sessionActive = true;
@@ -271,43 +238,25 @@ export class Presenter {
             this.#shell.openChat();
         }
     }
-    /**
-     * The bridge never answered: show that, rather than showing nothing.
-     *
-     * An instrumented page with a dead bridge used to be indistinguishable from a page with no
-     * Reticle in it — overlay mounted, dock off, nothing on screen. The user cannot tell "I forgot to
-     * start the daemon" from "the install did not work", and the commonest cause is the cheapest to
-     * say: the port. So the HUD appears, states the URL it tried, and marks itself unreachable so it
-     * is never mistaken for a live session.
-     *
-     * Not an error dialog and not modal: the page is the user's, and a dev overlay that shouts is one
-     * they turn off. It is the same capsule they would have had, saying the one thing it knows.
-     */
     showUnreachable(url, attempts) {
         if (this.#sessionActive)
             return;
         this.#root?.setAttribute(STATE_ATTR, UNREACHABLE_STATE);
-        // Dock and HUD, but NOT the border glow: the glow means the agent is working, and nothing is.
         const dock = this.#root?.querySelector('[data-reticle-dock]');
         dock?.setAttribute(DATA_ON, GLOW_ON);
         this.#hud?.setAttribute(DATA_ON, GLOW_ON);
         this.#lastActionText = unreachableStripText(url, attempts);
         this.#paintActStrip(this.#lastActionText, true);
-        // The message IS the reason this state exists, and a collapsed capsule hides it. Same setting
-        // a live session honours, so a user who wants the bare toolbar still gets one.
         if (getPresenterSettings().autoOpenChat)
             this.#shell.openChat();
     }
-    /** Turn the base border (session mode) + the HUD/log on - the visible "session is live" state. */
     #showSession() {
         const dock = this.#root?.querySelector('[data-reticle-dock]');
         dock?.setAttribute(DATA_ON, GLOW_ON);
         this.#hud?.setAttribute(DATA_ON, GLOW_ON);
-        // Base border persists in 'session' mode; 'busy' mode leaves it to the busy machine.
         if (this.#borderMode === BorderMode.SESSION)
             this.#glow?.setAttribute(DATA_ON, GLOW_ON);
     }
-    /** Revive after an ended session (new agent activity): clear the ended state + glow back on. */
     #revive() {
         this.#panel.setState(SessionState.ACTIVE);
         this.#endMs = undefined;
@@ -315,10 +264,6 @@ export class Presenter {
         this.#glowCtl.resetActivity(this.#now());
         this.#startHeartbeat();
     }
-    /**
-     * Session end: hides the log/HUD and (in 'session' mode) clears the base border. Idempotent; a
-     * no-op without a prior sessionStart or when unmounted.
-     */
     sessionEnd() {
         if (!this.#sessionActive)
             return;
@@ -336,30 +281,18 @@ export class Presenter {
             this.#glow?.setAttribute(DATA_BUSY, BUSY_OFF);
         }
     }
-    /**
-     * Record agent activity. Idempotent while busy - only the first activity from idle/fading flips
-     * the glow on, so a burst never restarts the reticle-pulse animation (no strobe). Subsequent calls
-     * just refresh the last-activity timestamp and re-arm the idle check.
-     */
     markActivity() {
         this.#glowCtl.markActivity();
     }
-    /** Re-arm the quiet-window idle check (kept for reticle.ts's finally block). */
     scheduleIdle() {
         this.#glowCtl.scheduleIdle();
     }
-    /** Test/diagnostic accessor for the current glow phase. */
     glowPhase() {
         return this.#glowCtl.phase();
     }
-    /** Current intent (reading vs acting), exposed for tests + the watcher. */
     get mode() {
         return this.#mode;
     }
-    /**
-     * Set the presenter intent. READING shows a cyan scan + chip and hides the cursor; ACTING
-     * keeps the warm cursor/ripple + chip; IDLE clears the chip. Drives color via data-reticle-mode.
-     */
     setMode(mode) {
         this.#mode = mode;
         this.#root?.setAttribute('data-reticle-mode', mode);
@@ -381,7 +314,6 @@ export class Presenter {
                 this.#chip.appendChild(labelEl);
             }
         }
-        // READING has no real pointer to show (synthetic-hover pointer is native-only) - hide the cursor.
         if (mode === PresenterMode.READING)
             this.#cursor?.setAttribute(DATA_ON, GLOW_OFF);
     }
@@ -392,13 +324,6 @@ export class Presenter {
         this.#lastActionText = text;
         this.#paintActStrip(text, false);
     }
-    /**
-     * Sync act-strip text + the live/idle state.
-     *
-     * The liveness is mirrored onto the overlay root as well as the strip, because that is what the
-     * status COLOUR resolves against: the page glow, the collapsed FAB's halo and the minimised
-     * capsule all live outside the strip and still have to say whether the agent is working.
-     */
     #paintActStrip(text, idle) {
         if (this.#actLine !== undefined)
             this.#actLine.textContent = text;
@@ -407,9 +332,6 @@ export class Presenter {
             this.#actStrip.setAttribute('data-liveness', liveness);
         this.#root?.setAttribute(LIVENESS_ATTR, liveness);
         if (this.#chatPillText !== undefined) {
-            // The capsule reads "logo | what the agent did | how long ago | expand", so it takes the
-            // ACTION, never the composed "idle · 12s since last action" line the strip shows: the age
-            // lives in its own slot next to it.
             this.#chatPillText.textContent = idle
                 ? this.#lastActionText !== ''
                     ? this.#lastActionText
@@ -417,12 +339,6 @@ export class Presenter {
                 : text;
         }
     }
-    /**
-     * Liveness heartbeat (native 1s timer - never rAF, so it ticks in a foreground tab regardless of
-     * agent activity). Once the agent has been quiet for IDLE_NOTICE_MS, the act strip shows a LIVE,
-     * growing "◌ idle · {duration} since last action" - the signal that was missing when a stopped
-     * agent left the panel frozen and indistinguishable from one still thinking.
-     */
     #startHeartbeat() {
         if (this.#heartbeatTimer !== undefined)
             nativeClearTimeout(this.#heartbeatTimer);
@@ -436,39 +352,35 @@ export class Presenter {
         if (!this.#sessionActive || this.#actLine === undefined)
             return;
         if (this.state === SessionState.ENDED)
-            return; // already ended - leave the summary
+            return;
         const idleMs = this.#now() - this.#glowCtl.lastActivityMs();
         if (idleMs >= this.#idleEndMs) {
-            this.#endIdle(idleMs); // crossed the idle-end window → auto-end (glow off, panel kept)
+            this.#endIdle(idleMs);
             return;
         }
         if (idleMs < this.#idleNoticeMs)
-            return; // still active (or a brief think) - keep the action text
-        const since = this.#lastActionText !== '' ? ACT_STRIP.SINCE_LAST : '';
-        this.#paintActStrip(`${ACT_STRIP.IDLE_PREFIX}${humanDuration(idleMs)}${since}`, true);
+            return;
+        if ('' === this.#lastActionText)
+            return;
+        const since = ACT_STRIP.SINCE_LAST;
+        this.#paintActStrip(`${ACT_STRIP.PLANNING_PREFIX}${humanDuration(idleMs)}${since}`, true);
         if (this.#chatPillTime !== undefined)
             this.#chatPillTime.textContent = humanDuration(idleMs);
     }
-    /** Auto-end after the idle window: stamp the end, drive the panel to ENDED, stop the heartbeat. */
     #endIdle(idleMs) {
         this.#endMs = this.#now();
-        this.#panel.setState(SessionState.ENDED, `idle ${humanDuration(idleMs)}`);
+        this.#panel.setState(SessionState.ENDED, `${ACT_STRIP.STOPPED_PREFIX}${humanDuration(idleMs)} quiet`);
+        this.#paintActStrip(ACT_STRIP.STOPPED, false);
         if (this.#heartbeatTimer !== undefined) {
             nativeClearTimeout(this.#heartbeatTimer);
             this.#heartbeatTimer = undefined;
         }
     }
-    /** Agent-tunable idle-end window (reticle_session). Floored so it can't be set uselessly small. */
     setIdleEndMs(ms) {
         if (!Number.isFinite(ms))
             return;
         this.#idleEndMs = Math.max(IDLE_END_MIN_MS, Math.floor(ms));
     }
-    /**
-     * The exported "run state" for the Copy/Export buttons - everything the page holds about this
-     * run: session id, url, duration, capability surface, per-kind counts, and the full activity log.
-     * (The full network/console ring-buffer lives server-side; this is the in-page run summary.)
-     */
     runState() {
         const base = buildRunState({
             sessionId: this.#sessionId,
@@ -518,11 +430,6 @@ export class Presenter {
             syncPageBlocker(this.#root, settings, live);
         }
     }
-    /**
-     * Append an activity-log row. Accumulates (never overwrites): each call adds a timestamped row
-     * with a mode chip + text. Returns a handle to stamp the row's outcome glyph (✓/✗) later, or
-     * undefined when unmounted / when the text is empty after trimming.
-     */
     log(kind, text, result) {
         const ms = this.#now();
         this.#glowCtl.markActivity(ms);
@@ -532,7 +439,6 @@ export class Presenter {
         if (0 === trimmed.length)
             return undefined;
         this.#logBaseMs ??= ms;
-        // Structured run-log entry (mirrors the DOM row) for the exported run state, capped like the DOM.
         const entry = result !== undefined
             ? { at: ms - this.#logBaseMs, kind, text: trimmed, result }
             : { at: ms - this.#logBaseMs, kind, text: trimmed };
@@ -546,16 +452,14 @@ export class Presenter {
         if (this.#shell.isCollapsed())
             this.#shell.pulseFab(true);
         this.#renderTally();
-        // Wrap the handle so a later outcome stamp updates BOTH the DOM glyph and the run-log entry.
         return {
             result: (r) => {
                 handle.result(r);
                 entry.result = r;
-                this.#renderTally(); // a deferred ✓/✗ stamp bumps the header tally
+                this.#renderTally();
             },
         };
     }
-    /** Repaint the header verdict tally from the run log; the side that grew gets a one-shot pop. */
     #renderTally() {
         if (!getPresenterSettings().showTally) {
             this.#tally?.setAttribute('hidden', '');
@@ -563,7 +467,6 @@ export class Presenter {
         }
         this.#tallied = renderTally(this.#tally, this.#runLog, this.#tallied);
     }
-    /** Back-compat: narration appends to the live log (append-only, never overwrites). */
     narrate(text, level = 'info') {
         const line = 'info' === level ? text : `[${level}] ${text}`;
         return this.log(LOG_KIND.NARRATION, line);
@@ -575,11 +478,6 @@ export class Presenter {
             this.#log.firstElementChild?.remove();
         }
     }
-    /**
-     * Mirror the server's session.throttled state onto the HUD border. When throttled (tab
-     * backgrounded or stale), the border turns amber so the developer knows actions are no-oping -
-     * the same signal the agent already reads from result.session.throttled.
-     */
     setThrottled(throttled) {
         this.#root?.setAttribute(THROTTLED_ATTR, throttled ? '1' : '0');
         if (throttled && this.#actLine !== undefined) {
@@ -587,7 +485,6 @@ export class Presenter {
                 'Tab backgrounded - actions throttled. Bring tab to front or use `reticle drive`.';
         }
     }
-    /** Fly the cursor to an element, play the action's effect, then pace for the human. */
     async beforeAct(refId, action, label) {
         const el = refs.resolve(refId);
         this.status(`${actionVerb(action)} ${label}`);

package/dist/presenter/tour/tour-view.d.ts

@@ -0,0 +1,33 @@
+import { TourAnchor, type TourPrompt } from '@reticlehq/core/tour';
+export declare const HANDOFF_INDEX: number;
+export declare const SLIDE_COUNT: number;
+export declare const TOUR_ATTR = "data-reticle-tour";
+export declare const TOUR_TARGET_ATTR = "data-reticle-tour-target";
+export declare const TOUR_PROMPT_ATTR = "data-reticle-tour-prompt";
+export declare const COPY_LABEL = "Copy";
+export declare const COPIED_LABEL = "Copied";
+export declare const COPY_MANUAL_LABEL = "Selected \u2014 press Ctrl/Cmd+C";
+export declare const COPY_FLASH_MS = 1600;
+export interface TourSlide {
+    readonly index: number;
+    readonly title: string;
+    readonly body: string;
+    readonly anchor: TourAnchor;
+    readonly tryIt?: string;
+    readonly prompts?: readonly TourPrompt[];
+}
+export declare const isInteractive: (slide: TourSlide) => boolean;
+export declare function tourSlides(): readonly TourSlide[];
+export declare function escapeHtml(text: string): string;
+export declare function withInlineCode(text: string): string;
+export declare function nextIndex(current: number, delta: number): number;
+export declare const isLastSlide: (index: number) => boolean;
+export interface TourRect {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+}
+export declare function holeRects(box: TourRect, viewWidth: number, viewHeight: number): readonly TourRect[];
+export declare function slideHtml(slide: TourSlide): string;
+export declare const TOUR_CSS: string;

package/dist/presenter/tour/tour-view.js

@@ -0,0 +1,188 @@
+import { TOUR_STEPS, TOUR_HUD_STEPS, TOUR_HANDOFF_PROMPTS, TourAnchor, } from '@reticlehq/core/tour';
+import { Z_TOUR } from '../chrome/layers.js';
+const ORDERED_STEPS = [...TOUR_STEPS.slice(0, 1), ...TOUR_HUD_STEPS];
+export const HANDOFF_INDEX = ORDERED_STEPS.length;
+export const SLIDE_COUNT = ORDERED_STEPS.length + 1;
+export const TOUR_ATTR = 'data-reticle-tour';
+export const TOUR_TARGET_ATTR = 'data-reticle-tour-target';
+export const TOUR_PROMPT_ATTR = 'data-reticle-tour-prompt';
+export const COPY_LABEL = 'Copy';
+export const COPIED_LABEL = 'Copied';
+export const COPY_MANUAL_LABEL = 'Selected — press Ctrl/Cmd+C';
+export const COPY_FLASH_MS = 1600;
+const stepSlide = (step, index) => ({
+    index,
+    title: step.title,
+    body: step.say,
+    anchor: step.anchor ?? TourAnchor.NONE,
+    ...(undefined === step.tryIt ? {} : { tryIt: step.tryIt }),
+});
+export const isInteractive = (slide) => undefined !== slide.tryIt;
+export function tourSlides() {
+    return [
+        ...ORDERED_STEPS.map(stepSlide),
+        {
+            index: HANDOFF_INDEX,
+            title: 'Get Started',
+            body: 'Paste one of these into Claude Code, Cursor, Codex, or whatever you use.',
+            anchor: TourAnchor.NONE,
+            prompts: TOUR_HANDOFF_PROMPTS,
+        },
+    ];
+}
+export function escapeHtml(text) {
+    return text
+        .split('&')
+        .join('&')
+        .split('<')
+        .join('&lt;')
+        .split('>')
+        .join('&gt;')
+        .split('"')
+        .join('&quot;');
+}
+export function withInlineCode(text) {
+    return escapeHtml(text).replace(/`([^`]+)`/g, '<code class="reticle-tour-code">$1</code>');
+}
+export function nextIndex(current, delta) {
+    const wanted = current + delta;
+    if (wanted < 0)
+        return 0;
+    if (wanted > SLIDE_COUNT - 1)
+        return SLIDE_COUNT - 1;
+    return wanted;
+}
+export const isLastSlide = (index) => index === SLIDE_COUNT - 1;
+export function holeRects(box, viewWidth, viewHeight) {
+    const left = Math.max(0, box.left);
+    const top = Math.max(0, box.top);
+    const right = Math.min(viewWidth, box.left + box.width);
+    const bottom = Math.min(viewHeight, box.top + box.height);
+    const candidates = [
+        { left: 0, top: 0, width: viewWidth, height: top },
+        { left: 0, top: bottom, width: viewWidth, height: viewHeight - bottom },
+        { left: 0, top, width: left, height: bottom - top },
+        { left: right, top, width: viewWidth - right, height: bottom - top },
+    ];
+    return candidates.filter((r) => r.width > 0 && r.height > 0);
+}
+export function slideHtml(slide) {
+    const dots = tourSlides()
+        .map((s) => `<span class="reticle-tour-dot${s.index === slide.index ? ' is-on' : ''}" aria-hidden="true"></span>`)
+        .join('');
+    const tryIt = undefined === slide.tryIt
+        ? ''
+        : `<p class="reticle-tour-try" ${TOUR_TARGET_ATTR}="try">${escapeHtml(slide.tryIt)}</p>`;
+    const prompt = undefined === slide.prompts
+        ? ''
+        : `<div class="reticle-tour-prompts">` +
+            slide.prompts
+                .map((p, i) => `<div class="reticle-tour-prompt" ${TOUR_PROMPT_ATTR}="${String(i)}">` +
+                `<span class="reticle-tour-prompt-label">${escapeHtml(p.label)}</span>` +
+                `<pre class="reticle-tour-prompt-text">${escapeHtml(p.text)}</pre>` +
+                `<button type="button" class="reticle-tour-copy" ${TOUR_TARGET_ATTR}="copy" ` +
+                `${TOUR_PROMPT_ATTR}="${String(i)}">${COPY_LABEL}</button></div>`)
+                .join('') +
+            `</div>`;
+    const back = 0 === slide.index
+        ? ''
+        : `<button type="button" class="reticle-tour-back" ${TOUR_TARGET_ATTR}="back">Back</button>`;
+    const forward = isLastSlide(slide.index)
+        ? `<button type="button" class="reticle-tour-next" ${TOUR_TARGET_ATTR}="done">Done</button>`
+        : `<button type="button" class="reticle-tour-next" ${TOUR_TARGET_ATTR}="next">Next</button>`;
+    return (`<div class="reticle-tour-card" role="dialog" aria-modal="false" aria-label="Reticle tour">` +
+        `<button type="button" class="reticle-tour-skip" ${TOUR_TARGET_ATTR}="skip" aria-label="Skip the tour">Skip</button>` +
+        `<p class="reticle-tour-step">Step ${String(slide.index + 1)} of ${String(SLIDE_COUNT)}</p>` +
+        `<h2 class="reticle-tour-title">${escapeHtml(slide.title)}</h2>` +
+        `<p class="reticle-tour-body">${withInlineCode(slide.body)}</p>` +
+        tryIt +
+        prompt +
+        `<div class="reticle-tour-foot"><div class="reticle-tour-dots">${dots}</div>` +
+        `<div class="reticle-tour-nav">${back}${forward}</div></div>` +
+        `</div>`);
+}
+export const TOUR_CSS = `
+[${TOUR_ATTR}]{position:fixed;inset:0;z-index:${String(Z_TOUR)};pointer-events:none;
+  font:13px/1.55 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif;}
+[${TOUR_ATTR}] .reticle-tour-scrim{position:absolute;inset:0;background:rgba(6,8,14,.55);
+  backdrop-filter:blur(1.5px);pointer-events:auto;z-index:0;}
+/* Blocks the click everywhere the hole is not. Same job as the scrim, minus the one rectangle the
+   slide is inviting somebody to press. */
+[${TOUR_ATTR}] .reticle-tour-blocker{position:absolute;pointer-events:auto;z-index:0;}
+/* Ringed slides dim through the ring's own 9999px shadow, which leaves a hole over the thing being
+   pointed at. The scrim would cover that hole -- dimming the HUD the slide is ABOUT, and washing
+   the page twice (~80% rather than 55%). Cleared, not removed: it is also what swallows clicks
+   meant for the app underneath, and a tour that lets you click through is not a tour. */
+[${TOUR_ATTR}] .reticle-tour-scrim.is-clear{background:transparent;backdrop-filter:none;}
+/* Above the ring, and the z-index is the whole point.
+   The ring is appended after the card, and both are positioned with an auto z-index, so the ring
+   painted on top of it -- and the ring's dimming IS a 9999px shadow, which therefore fell across the
+   card as well. On every ringed slide the card was washed at 55% and read as sitting BEHIND the page
+   it was drawn over. The ring must stay above the scrim and below the card; saying so explicitly is
+   the fix, because DOM order alone cannot express "between these two". */
+[${TOUR_ATTR}] .reticle-tour-card{position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);
+  width:min(430px,calc(100vw - 32px));box-sizing:border-box;pointer-events:auto;z-index:3;
+  background:#14161d;color:#e8eaf0;border:1px solid #2b303d;border-radius:14px;padding:20px 20px 16px;
+  box-shadow:0 24px 60px rgba(0,0,0,.5);}
+[${TOUR_ATTR}] .reticle-tour-skip{position:absolute;top:10px;right:12px;background:none;border:0;
+  color:#8a93a6;font:inherit;font-size:12px;cursor:pointer;padding:4px 6px;border-radius:6px;}
+[${TOUR_ATTR}] .reticle-tour-skip:hover{color:#e8eaf0;background:rgba(255,255,255,.06);}
+[${TOUR_ATTR}] .reticle-tour-step{margin:0 0 6px;font-size:11px;letter-spacing:.06em;
+  text-transform:uppercase;color:#7f8798;}
+[${TOUR_ATTR}] .reticle-tour-title{margin:0 0 8px;font-size:18px;line-height:1.25;font-weight:650;
+  color:#f2f4f8;}
+[${TOUR_ATTR}] .reticle-tour-body{margin:0 0 10px;color:#c9cedb;}
+/* A call named inside a sentence. Sets its own colour for the reason every other text class does:
+   an inherited one loses to any direct element selector in the host app. */
+[${TOUR_ATTR}] .reticle-tour-code{padding:1px 5px;border-radius:5px;background:#0c0e14;
+  border:1px solid #232834;color:#9fb6ff;
+  font:11.5px/1.45 ui-monospace,SFMono-Regular,Menlo,monospace;overflow-wrap:anywhere;}
+[${TOUR_ATTR}] .reticle-tour-try{margin:0 0 12px;padding:8px 10px;border-radius:8px;
+  background:rgba(99,102,241,.1);border:1px solid rgba(99,102,241,.32);color:#c7cbff;
+  font-size:12.5px;font-weight:550;}
+[${TOUR_ATTR}] .reticle-tour-prompts{display:flex;flex-direction:column;gap:8px;margin:0 0 12px;}
+[${TOUR_ATTR}] .reticle-tour-prompt{display:grid;gap:6px;padding:9px 10px;border-radius:8px;
+  background:#0c0e14;border:1px solid #232834;
+  grid-template-columns:1fr auto;grid-template-areas:"label copy" "text text";align-items:center;}
+[${TOUR_ATTR}] .reticle-tour-prompt-label{grid-area:label;color:#8a93a6;font-size:11px;
+  letter-spacing:.05em;text-transform:uppercase;}
+[${TOUR_ATTR}] .reticle-tour-prompt-text{grid-area:text;width:100%;box-sizing:border-box;margin:0;
+  white-space:pre-wrap;overflow-wrap:anywhere;color:#c9cedb;
+  font:12px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;}
+[${TOUR_ATTR}] .reticle-tour-copy{grid-area:copy;padding:5px 10px;border-radius:6px;
+  border:1px solid #2b303d;background:transparent;color:#c9cedb;font:inherit;font-size:11.5px;
+  font-weight:600;cursor:pointer;white-space:nowrap;}
+[${TOUR_ATTR}] .reticle-tour-copy:hover{background:rgba(255,255,255,.07);color:#fff;}
+/* The flash that tells somebody the click did something. Colour AND text: colour alone is not an
+   answer for the people who cannot see the difference. */
+[${TOUR_ATTR}] .reticle-tour-copy.is-done{background:#16a34a;border-color:#16a34a;color:#fff;}
+[${TOUR_ATTR}] .reticle-tour-copy.is-manual{background:#b45309;border-color:#b45309;color:#fff;}
+[${TOUR_ATTR}] .reticle-tour-foot{display:flex;align-items:center;justify-content:space-between;gap:12px;}
+[${TOUR_ATTR}] .reticle-tour-dots{display:flex;gap:6px;}
+[${TOUR_ATTR}] .reticle-tour-dot{width:6px;height:6px;border-radius:50%;background:#333a49;}
+[${TOUR_ATTR}] .reticle-tour-dot.is-on{background:#6366f1;}
+[${TOUR_ATTR}] .reticle-tour-nav{display:flex;gap:8px;}
+[${TOUR_ATTR}] .reticle-tour-back,[${TOUR_ATTR}] .reticle-tour-next{padding:8px 14px;border-radius:8px;
+  font:inherit;font-weight:600;cursor:pointer;border:1px solid #2b303d;background:transparent;color:#c9cedb;}
+[${TOUR_ATTR}] .reticle-tour-next{background:#6366f1;border-color:#6366f1;color:#fff;}
+[${TOUR_ATTR}] .reticle-tour-next:hover{filter:brightness(1.08);}
+[${TOUR_ATTR}] .reticle-tour-back:hover{background:rgba(255,255,255,.06);color:#e8eaf0;}
+[${TOUR_ATTR}] .reticle-tour-ring{position:absolute;border-radius:14px;pointer-events:none;z-index:1;
+  box-shadow:0 0 0 3px #6366f1,0 0 0 9999px rgba(6,8,14,.55);transition:all .25s ease;}
+/* A ring somebody is being asked to press, rather than to look at: it pulses, so the invitation in
+   the prose has something on the page agreeing with it. */
+[${TOUR_ATTR}] .reticle-tour-ring.is-live{animation:reticle-tour-pulse 1.8s ease-in-out infinite;}
+@keyframes reticle-tour-pulse{
+  0%,100%{box-shadow:0 0 0 3px #6366f1,0 0 0 9999px rgba(6,8,14,.55);}
+  50%{box-shadow:0 0 0 6px rgba(99,102,241,.55),0 0 0 9999px rgba(6,8,14,.55);}
+}
+/* A REGION, not a target. The spotlight above cuts a hole in the dimming, which is right for
+   something small and wrong for the app: the hole becomes the whole viewport, the dimming
+   disappears, and the card is left competing with a fully lit page while the ring edges sit off at
+   the margins pointing at nothing. An outline says "all of this" without turning the lights on. */
+[${TOUR_ATTR}] .reticle-tour-ring.is-region{box-shadow:none;border:2px dashed #7c83f5;
+  background:rgba(99,102,241,.06);}
+@media (prefers-reduced-motion:reduce){
+  [${TOUR_ATTR}] .reticle-tour-ring{transition:none;}
+}
+`;