passenger-mode 0.0.0-stage → 0.3.0

package/dist/lib/runtime/driver.js

@@ -0,0 +1,422 @@
+import { runtimeGateReason } from "./gates.js";
+import { liveLabel, resolveElement } from "./resolve.js";
+import { canonicalPath, matchRoute } from "./routes.js";
+const STORAGE_KEY = "passenger-mode:trip";
+const MAX_DEST = 300;
+/** Bulk goals are refused here, whatever the planner says: one trip does one thing. */
+const BULK = /\b(all|every|each|everyone|everybody)\b.{0,40}\b(users?|members?|people|contacts?|customers?|items?|posts?|messages?|accounts?|orders?|friends?|followers?)\b|\b\d{2,}\s+times\b|\bmass\b|\bbulk\b/i;
+const GATE_NOUN = {
+    payment: "pay buttons",
+    "cancels a plan or order": "cancel buttons",
+    deletion: "delete buttons",
+    "sends to other people": "send buttons",
+    publishes: "publish buttons",
+    "credential change": "password or email changes",
+    "ends the session": "sign-out buttons",
+    "uses your password": "buttons that use your password",
+};
+function tripId() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return "t" + Date.now().toString(36) + Math.random().toString(36).slice(2, 10);
+}
+const noopUI = { render() { }, async moveCursor() { }, ring() { }, owns: () => false };
+export class Driver {
+    state = "off";
+    plan = null;
+    log = null;
+    o;
+    ui;
+    run = 0;
+    gateEl = null;
+    gateAction = null;
+    stepCount = 0;
+    detach = [];
+    constructor(opts) {
+        this.o = {
+            routeFrom: "path",
+            isTrusted: (e) => e.isTrusted,
+            maxSteps: 15,
+            timeLimitMs: 3 * 60_000,
+            settleMs: 250,
+            ...opts,
+        };
+        this.ui = opts.ui ?? noopUI;
+        if (this.o.storage === undefined) {
+            try {
+                this.o.storage = opts.window.sessionStorage;
+            }
+            catch {
+                this.o.storage = null;
+            }
+        }
+        this.listen();
+        this.restore();
+    }
+    get doc() { return this.o.window.document; }
+    path() {
+        const loc = this.o.window.location;
+        if (typeof this.o.routeFrom === "function")
+            return this.o.routeFrom();
+        // Path plus query: apps that switch screens with parameters (?lobby=1) have one route per screen.
+        return this.o.routeFrom === "hash" ? (loc.hash.replace(/^#/, "") || "/") : loc.pathname + loc.search;
+    }
+    set(state, info = {}) {
+        this.state = state;
+        this.ui.render(state, { plan: this.plan, destination: this.log?.destination, step: this.stepCount, ...info });
+    }
+    // ---------- what the passenger does (each needs a real gesture) ----------
+    /** Flip the switch on. A script cannot do this: it needs a trusted event. */
+    open(e) {
+        if (!this.o.isTrusted(e))
+            return false;
+        if (this.state === "off")
+            this.set("open");
+        return true;
+    }
+    /** Switch off. Always allowed: stopping is the safe direction. */
+    close() {
+        this.finish("ended");
+        this.plan = null;
+        this.set("off");
+    }
+    async planTrip(destination, e) {
+        if (!this.o.isTrusted(e))
+            return null;
+        const dest = destination.trim().slice(0, MAX_DEST);
+        if (!dest)
+            return null;
+        this.log = { id: tripId(), destination: dest, startedAt: Date.now(), steps: [] };
+        this.stepCount = 0;
+        if (BULK.test(dest)) {
+            this.set("stuck", { message: "Passenger Mode does one thing per trip. Try a single destination." });
+            return null;
+        }
+        this.set("planning");
+        let plan = null;
+        const view = this.view();
+        try {
+            plan = await this.o.planner.plan(view, this.o.manifest);
+        }
+        catch {
+            // The planner couldn't be reached: say so, rather than blaming how the passenger put it.
+            this.set("stuck", { message: "I can't plan trips right now. Try again in a moment." });
+            return null;
+        }
+        if (!plan) {
+            this.set("stuck", { message: "I don't know this road. Try saying it another way." });
+            return null;
+        }
+        this.plan = plan;
+        this.set("ready");
+        return plan;
+    }
+    /** Nothing moves until the passenger presses Go. */
+    go(e) {
+        if (!this.o.isTrusted(e) || this.state !== "ready")
+            return false;
+        this.log.startedAt = Date.now();
+        this.drive();
+        return true;
+    }
+    /** Back to choosing a destination. */
+    notThis() {
+        this.plan = null;
+        this.log = null;
+        this.set("open");
+    }
+    takeWheel() {
+        if (this.state !== "driving")
+            return;
+        this.run++;
+        this.ui.ring(null);
+        this.set("paused", { message: "Nothing moves until you resume." });
+    }
+    resume(e) {
+        if (!this.o.isTrusted(e) || (this.state !== "paused" && this.state !== "handoff"))
+            return false;
+        this.drive();
+        return true;
+    }
+    end() {
+        this.finish(this.state === "arrived" ? "arrived" : this.state === "paused" ? "taken-over" : "ended");
+        this.plan = null;
+        this.set("open");
+    }
+    rate(up) {
+        if (this.log) {
+            this.log.rating = up ? "up" : "down";
+            this.o.onTrip?.(this.log);
+        }
+    }
+    // ---------- the loop ----------
+    /** What the planner may see: the destination and the manifest actions on this page. No page text. */
+    view() {
+        const route = matchRoute(this.path(), this.o.manifest.routes);
+        const visible = [];
+        for (const a of this.o.manifest.actions) {
+            if (a.route !== null && a.route !== route)
+                continue;
+            if (a.route === null && a.seenOn && route !== null && !a.seenOn.includes(route))
+                continue;
+            const el = this.find(a);
+            if (!el)
+                continue;
+            const runtimeLabel = a.label.startsWith("{");
+            visible.push({ id: a.id, label: runtimeLabel ? liveLabel(el) : a.label, kind: a.kind, irreversible: a.irreversible, runtimeLabel });
+        }
+        return {
+            destination: this.log?.destination ?? "",
+            route,
+            path: this.path(),
+            visible,
+            history: (this.log?.steps ?? []).map((s) => ({ actionId: s.actionId, label: s.label, route: s.route })),
+            ...(this.plan ? { approvedPlan: this.plan.steps.slice(0, 8) } : {}),
+        };
+    }
+    find(a) {
+        const el = resolveElement(a, this.doc);
+        return el && !this.ui.owns(el) ? el : null;
+    }
+    drive() {
+        const id = ++this.run;
+        this.set("driving", { caption: "Starting the trip" });
+        void this.loop(id);
+    }
+    live(id) { return id === this.run && this.state === "driving"; }
+    async loop(id) {
+        // Pages that draw their controls after load (data fetches, client routers) get a moment first.
+        await this.settle();
+        let lookedAgain = false;
+        while (this.live(id)) {
+            if (this.stepCount >= this.o.maxSteps)
+                return this.stuck("That's more steps than one trip allows, so I stopped.");
+            if (Date.now() - this.log.startedAt > this.o.timeLimitMs)
+                return this.stuck("This trip is taking too long, so I stopped.");
+            const view = this.view();
+            let step;
+            try {
+                step = await this.o.planner.next(view, this.o.manifest);
+            }
+            catch {
+                return this.stuck("I lost the road. Try again in a moment.");
+            }
+            if (!this.live(id))
+                return;
+            if (step.kind === "arrived")
+                return this.arrive(step.summary);
+            if (step.kind === "stuck") {
+                // One more look before giving up: the control may still be on its way.
+                if (!lookedAgain) {
+                    lookedAgain = true;
+                    await this.settle(1500);
+                    continue;
+                }
+                // The driver's own last step brought the passenger to a page the scan never saw (a game table,
+                // an item with an id in its address). That is where the step leads; say so plainly.
+                const last = this.log.steps.at(-1);
+                if (view.route === null && last?.by === "driver") {
+                    return this.arrive(`This is where “${last.label}” leads. I don't know this page, so take it from here.`);
+                }
+                return this.stuck(step.reason);
+            }
+            lookedAgain = false;
+            // Going in circles: the same action twice in a row already, and the planner wants it again.
+            const recent = this.log.steps.slice(-2);
+            if (recent.length === 2 && recent.every((r) => r.actionId === step.actionId)) {
+                return this.stuck("I'm going in circles, so I stopped. Try saying it another way.");
+            }
+            // Scope is the manifest, and the action must be on this page right now.
+            const action = this.o.manifest.actions.find((a) => a.id === step.actionId);
+            if (!action || !view.visible.some((v) => v.id === action.id))
+                return this.stuck("I don't know this road.");
+            const el = this.find(action);
+            if (!el)
+                return this.stuck("I don't know this road.");
+            // A link to the page the passenger is already on goes nowhere: the planner is pointing at here.
+            if (action.kind === "navigate" && this.linksHere(el))
+                return this.arrive(step.caption ?? "You're already here.");
+            const label = action.label.startsWith("{") ? liveLabel(el) : action.label;
+            const gate = action.irreversible ? action.irreversibleReason : runtimeGateReason(el);
+            const caption = gate ? `Pull over: ${label} is yours to press` : step.caption ?? `Pressing ${label}`;
+            el.scrollIntoView?.({ block: "center", behavior: "smooth" });
+            this.ui.ring(el, gate ? "gate" : "drive");
+            await this.ui.moveCursor(el, caption);
+            if (!this.live(id))
+                return;
+            if (gate)
+                return this.pullOver(el, action, label, gate);
+            if (action.kind === "submit") {
+                const form = (el.tagName === "FORM" ? el : el.closest("form"));
+                const empty = form ? Array.from(form.querySelectorAll("input[required],select[required],textarea[required]")).filter((f) => !f.value) : [];
+                if (empty.length) {
+                    // The driver never types for the passenger: their values stay theirs.
+                    this.ui.ring(form, "handoff");
+                    // Middle of the screen, clear of the trip bar at the bottom.
+                    empty[0].scrollIntoView?.({ block: "center" });
+                    empty[0].focus?.({ preventScroll: true });
+                    this.set("handoff", { message: `Your turn: fill in ${empty.length === 1 ? "the highlighted field" : `the ${empty.length} highlighted fields`}, then press Resume.` });
+                    return;
+                }
+                this.record(action, label, "driver");
+                this.markNav();
+                if (form?.requestSubmit)
+                    form.requestSubmit();
+                else
+                    form?.submit();
+            }
+            else {
+                this.record(action, label, "driver");
+                this.markNav();
+                el.click();
+            }
+            await this.settle();
+            this.clearNav();
+        }
+    }
+    /** The driver stops at the control and waits for the passenger's own, trusted click on it. */
+    pullOver(el, action, label, reason) {
+        this.gateEl = el;
+        this.gateAction = { action, label };
+        // On a form, point at the button the passenger presses; the whole form still counts as the gate.
+        const face = el.tagName === "FORM"
+            ? el.querySelector('button:not([type="button"]):not([type="reset"]), input[type="submit"]') ?? el
+            : el;
+        this.ui.ring(face, "gate");
+        if (face !== el)
+            void this.ui.moveCursor(face, `Pull over: ${label} is yours to press`);
+        this.set("gate", { caption: `Pull over: ${label} is yours to press`, message: `This one's yours. Passenger Mode never presses ${GATE_NOUN[reason] ?? "buttons like this"}. Press ${label} to finish, or end the trip.` });
+    }
+    onGateClick(e) {
+        if (this.state !== "gate" || !this.gateEl || !this.gateAction || !this.o.isTrusted(e))
+            return;
+        const t = e.target;
+        if (!t || !this.gateEl.contains(t))
+            return;
+        const { action, label } = this.gateAction;
+        this.gateAction = null;
+        this.record(action, label, "passenger");
+        this.gateEl = null;
+        this.ui.ring(null);
+        // Let the passenger's own click do its work, then carry on to "You're here".
+        this.markNav();
+        const id = ++this.run;
+        this.state = "driving";
+        this.ui.render("driving", { plan: this.plan, caption: "Checking you arrived", destination: this.log?.destination, step: this.stepCount });
+        void this.settle().then(() => { this.clearNav(); return this.loop(id); });
+    }
+    record(action, label, by) {
+        this.stepCount++;
+        this.log?.steps.push({ actionId: action.id, label, route: matchRoute(this.path(), this.o.manifest.routes), by, at: Date.now() });
+    }
+    arrive(summary) {
+        this.ui.ring(null);
+        this.finish("arrived");
+        this.set("arrived", { message: summary });
+    }
+    stuck(reason) {
+        this.ui.ring(null);
+        this.finish("stuck", reason);
+        this.set("stuck", { message: reason });
+    }
+    finish(outcome, reason) {
+        this.run++;
+        this.gateEl = null;
+        this.clearNav(true);
+        if (this.log && !this.log.outcome) {
+            this.log.outcome = outcome;
+            this.log.reason = reason;
+            this.log.endedAt = Date.now();
+            this.o.onTrip?.(this.log);
+        }
+    }
+    // ---------- page plumbing ----------
+    /** Waits for the page to react: a route change or DOM changes, then a short quiet period. */
+    settle(quietMs) {
+        const win = this.o.window;
+        const quiet = quietMs ?? this.o.settleMs;
+        return new Promise((resolve) => {
+            let t;
+            const done = () => { obs?.disconnect(); clearTimeout(cap); resolve(); };
+            const bump = () => { clearTimeout(t); t = setTimeout(done, quiet); };
+            const MO = win.MutationObserver;
+            const obs = MO ? new MO(bump) : null;
+            obs?.observe(win.document.documentElement, { subtree: true, childList: true, attributes: true });
+            const cap = setTimeout(done, Math.max(2500, quiet * 4));
+            bump();
+        });
+    }
+    linksHere(el) {
+        const href = el.getAttribute("href");
+        if (!href || href.startsWith("#") || this.o.routeFrom === "hash" || typeof this.o.routeFrom === "function")
+            return false;
+        try {
+            const loc = this.o.window.location;
+            const to = new URL(href, loc.href);
+            return to.origin === loc.origin && canonicalPath(to.pathname + to.search) === canonicalPath(loc.pathname + loc.search);
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Full page loads end the script; a trip in flight is saved so the next page can carry on. */
+    markNav() {
+        try {
+            this.o.storage?.setItem(STORAGE_KEY, JSON.stringify({ log: this.log, plan: this.plan, stepCount: this.stepCount, at: Date.now(), origin: this.o.window.location.origin }));
+        }
+        catch { /* storage full or blocked: trips just won't survive reloads */ }
+    }
+    clearNav(always = false) {
+        if (always || this.state === "driving")
+            try {
+                this.o.storage?.removeItem(STORAGE_KEY);
+            }
+            catch { /* ignore */ }
+    }
+    restore() {
+        let saved = null;
+        try {
+            saved = JSON.parse(this.o.storage?.getItem(STORAGE_KEY) ?? "null");
+        }
+        catch {
+            saved = null;
+        }
+        if (!saved)
+            return;
+        try {
+            this.o.storage?.removeItem(STORAGE_KEY);
+        }
+        catch { /* ignore */ }
+        // Only a navigation the driver itself started, seconds ago, on this site, may continue.
+        if (Date.now() - saved.at > 15_000 || saved.origin !== this.o.window.location.origin || !saved.log)
+            return;
+        this.log = saved.log;
+        this.plan = saved.plan;
+        this.stepCount = saved.stepCount ?? 0;
+        setTimeout(() => this.drive(), 400);
+    }
+    listen() {
+        const win = this.o.window;
+        const takeover = (e) => {
+            if (this.state !== "driving" || !this.o.isTrusted(e))
+                return;
+            if (this.ui.owns(e.target))
+                return;
+            this.takeWheel();
+        };
+        for (const type of ["pointerdown", "mousedown", "keydown", "wheel", "touchstart"]) {
+            win.addEventListener(type, takeover, { capture: true, passive: true });
+            this.detach.push(() => win.removeEventListener(type, takeover, { capture: true }));
+        }
+        const gate = (e) => this.onGateClick(e);
+        win.addEventListener("click", gate, { capture: true });
+        win.addEventListener("submit", gate, { capture: true }); // pressing Enter in a gated form
+        this.detach.push(() => { win.removeEventListener("click", gate, { capture: true }); win.removeEventListener("submit", gate, { capture: true }); });
+    }
+    destroy() {
+        this.run++;
+        this.detach.forEach((f) => f());
+        this.detach = [];
+    }
+}

package/dist/lib/runtime/gates.d.ts

@@ -0,0 +1 @@
+export declare function runtimeGateReason(el: Element): string | null;

package/dist/lib/runtime/gates.js

@@ -0,0 +1,56 @@
+import { PRICE, irreversibleReason, linkGateReason } from "../gates-text.js";
+/**
+ * Gates found on the live page, on top of the manifest's flags. The manifest is a floor:
+ * a "Continue" button that charges a card is caught here even though its label looked harmless.
+ */
+const CARD_FIELDS = [
+    'input[autocomplete^="cc-"]',
+    'input[name*="card" i]',
+    'input[name*="cvc" i]',
+    'input[name*="cvv" i]',
+    'input[id*="card-number" i]',
+    "[data-stripe]",
+    'iframe[src*="js.stripe.com"]',
+    'iframe[name^="__privateStripeFrame"]',
+    'iframe[src*="paypal.com"]',
+    'iframe[src*="braintree"]',
+    'iframe[src*="squareup.com"]',
+    'iframe[src*="adyen"]',
+    'iframe[title*="payment" i]',
+].join(",");
+const visibleText = (el) => (el.textContent ?? "").replace(/\s+/g, " ").trim();
+export function runtimeGateReason(el) {
+    // A form is judged by its submit button's words, not by every word inside it.
+    const face = el.tagName === "FORM"
+        ? el.querySelector('button:not([type="button"]):not([type="reset"]), input[type="submit"]') ?? el
+        : el;
+    const label = [
+        face.getAttribute("aria-label"),
+        face === el && el.tagName === "FORM" ? "" : visibleText(face),
+        face.getAttribute("value"),
+        face.getAttribute("title"),
+    ].filter(Boolean).join(" ").slice(0, 300);
+    const isLink = el.tagName === "A";
+    if (isLink)
+        return linkGateReason(label, el.getAttribute("href"));
+    // What the control says right now (runtime labels can differ from the source).
+    const byText = irreversibleReason([label]);
+    if (byText)
+        return byText;
+    if (PRICE.test(label))
+        return "payment";
+    // What the control submits.
+    const form = el.tagName === "FORM" ? el : el.closest("form");
+    const scope = form ?? null;
+    if (scope) {
+        if (scope.querySelector(CARD_FIELDS))
+            return "payment";
+        if (scope.querySelector('input[type="password"]'))
+            return "uses your password";
+    }
+    else if (el.ownerDocument?.querySelector(CARD_FIELDS)) {
+        // A button outside any form on a page that takes card details: assume it pays.
+        return "payment";
+    }
+    return null;
+}

package/dist/lib/runtime/index.d.ts

@@ -0,0 +1,43 @@
+import type { Manifest } from "../types.ts";
+import { Driver, type DriverOptions, type TripLog } from "./driver.ts";
+import { RoutePlanner, type Planner } from "./planner.ts";
+import { RemotePlanner } from "./remote-planner.ts";
+import { OverlayUI } from "./ui.ts";
+export { Driver, RoutePlanner, RemotePlanner, OverlayUI };
+export type { Planner, TripLog };
+export declare const HOSTED = "https://passengermode.com";
+export interface MountOptions {
+    /**
+     * The site's public key from passengermode.com. With a key, the manifest, the on/off switch
+     * and planning all come from the hosted service, and trip outcomes go to the dashboard.
+     */
+    key?: string;
+    /** Hosted service origin (tests and self-hosting). */
+    apiBase?: string;
+    /** The manifest object, or a URL to fetch it from. Optional with a key. */
+    manifest?: Manifest | string;
+    /** Default: the site's planner endpoint if given, else the offline route planner. */
+    planner?: Planner;
+    /** POST endpoint that runs the Claude planner on your server (see passenger-mode/server). */
+    endpoint?: string;
+    window?: Window;
+    routeFrom?: DriverOptions["routeFrom"];
+    onTrip?: (log: TripLog) => void;
+    badge?: boolean;
+    /** Move the switch to clear the site's own corner buttons (px from the bottom-right). */
+    offset?: {
+        right?: number;
+        bottom?: number;
+    };
+    /**
+     * Off by default: inside a frame Passenger Mode does not appear, so another site can't
+     * frame yours and drive it. Only set this for your own previews.
+     */
+    allowInFrame?: boolean;
+}
+export interface Handle {
+    driver: Driver;
+    ui: OverlayUI;
+    destroy(): void;
+}
+export declare function mount(opts: MountOptions): Promise<Handle | null>;

package/dist/lib/runtime/index.js

@@ -0,0 +1,99 @@
+import { Driver } from "./driver.js";
+import { RoutePlanner } from "./planner.js";
+import { RemotePlanner } from "./remote-planner.js";
+import { OverlayUI } from "./ui.js";
+export { Driver, RoutePlanner, RemotePlanner, OverlayUI };
+export const HOSTED = "https://passengermode.com";
+function framed(win) {
+    try {
+        return win.top !== win.self;
+    }
+    catch {
+        return true;
+    }
+}
+export async function mount(opts) {
+    const win = opts.window ?? window;
+    if (framed(win) && !opts.allowInFrame) {
+        console.info("Passenger Mode is off inside frames.");
+        return null;
+    }
+    const api = (opts.apiBase ?? HOSTED).replace(/\/$/, "");
+    const keyed = opts.key ? `key=${encodeURIComponent(opts.key)}` : "";
+    // Hosted: the owner's kill switch and the free-tier cap are checked before the switch appears.
+    if (opts.key) {
+        try {
+            const st = await (await win.fetch(`${api}/api/v1/status?${keyed}`, { credentials: "omit" })).json();
+            if (!st?.on) {
+                console.info(`Passenger Mode is off for this site${st?.reason ? `: ${st.reason}` : ""}.`);
+                return null;
+            }
+        }
+        catch {
+            return null; // can't confirm it's on: stay off
+        }
+    }
+    const source = opts.manifest ?? (opts.key ? `${api}/api/v1/manifest?${keyed}` : undefined);
+    if (!source)
+        throw new Error("Passenger Mode needs a manifest or a key.");
+    const manifest = typeof source === "string"
+        ? await (await win.fetch(source, { credentials: opts.key ? "omit" : "same-origin" })).json()
+        : source;
+    const planner = opts.planner
+        ?? (opts.key ? new RemotePlanner(`${api}/api/v1/plan`, undefined, { "x-passenger-key": opts.key })
+            : opts.endpoint ? new RemotePlanner(opts.endpoint) : new RoutePlanner());
+    const report = opts.key
+        ? (log) => {
+            try {
+                void win.fetch(`${api}/api/v1/trips`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json", "x-passenger-key": opts.key },
+                    body: JSON.stringify(log),
+                    credentials: "omit",
+                    keepalive: true,
+                }).catch(() => { });
+            }
+            catch { /* reporting never breaks a trip */ }
+        }
+        : null;
+    const onTrip = (log) => { report?.(log); opts.onTrip?.(log); };
+    let driver;
+    const ui = new OverlayUI(win, {
+        open: (e) => driver.open(e),
+        close: () => driver.close(),
+        plan: (dest, e) => { void driver.planTrip(dest, e); },
+        go: (e) => driver.go(e),
+        notThis: () => driver.notThis(),
+        takeWheel: () => driver.takeWheel(),
+        resume: (e) => driver.resume(e),
+        end: () => driver.end(),
+        rate: (up) => driver.rate(up),
+    }, { suggestions: manifest.destinations.map((d) => d.goal), badge: opts.badge ?? true, offset: opts.offset });
+    driver = new Driver({ manifest, planner, window: win, ui, routeFrom: opts.routeFrom, onTrip });
+    return { driver, ui, destroy() { driver.destroy(); ui.destroy(); } };
+}
+/**
+ * Script-tag install:
+ *   <script src="https://passengermode.com/v1.js" data-key="pk_..."></script>          (hosted)
+ *   <script src="passenger-mode.js" data-manifest="/passenger.manifest.json" data-endpoint="/api/passenger-mode"></script>  (self-hosted)
+ * Optional: data-route="hash", data-badge="false", data-right / data-bottom (px) to move the switch.
+ */
+if (typeof document !== "undefined") {
+    const tag = document.currentScript;
+    if (tag?.dataset.manifest || tag?.dataset.key) {
+        const num = (v) => (v != null && v !== "" && !Number.isNaN(Number(v)) ? Number(v) : undefined);
+        const go = () => void mount({
+            key: tag.dataset.key,
+            apiBase: tag.dataset.api,
+            manifest: tag.dataset.manifest,
+            endpoint: tag.dataset.endpoint,
+            routeFrom: tag.dataset.route ?? "path",
+            badge: tag.dataset.badge !== "false",
+            offset: { right: num(tag.dataset.right), bottom: num(tag.dataset.bottom) },
+        });
+        if (document.readyState === "loading")
+            document.addEventListener("DOMContentLoaded", go);
+        else
+            go();
+    }
+}

package/dist/lib/runtime/planner.d.ts

@@ -0,0 +1,61 @@
+import type { ActionKind, Manifest } from "../types.ts";
+/**
+ * What the planner is allowed to see. Deliberately NO free page text: only the destination
+ * (the passenger's words, the one instruction) and the manifest actions present on this page.
+ * Labels filled in at runtime can be user-written, so they arrive flagged as data.
+ */
+export interface PageView {
+    destination: string;
+    route: string | null;
+    path: string;
+    visible: Array<{
+        id: string;
+        label: string;
+        kind: ActionKind;
+        irreversible: boolean;
+        runtimeLabel: boolean;
+    }>;
+    history: Array<{
+        actionId: string;
+        label: string;
+        route: string | null;
+    }>;
+    /** The plan the passenger approved with Go. The driver keeps to it. */
+    approvedPlan?: string[];
+}
+export type Step = {
+    kind: "act";
+    actionId: string;
+    caption?: string;
+} | {
+    kind: "arrived";
+    summary: string;
+} | {
+    kind: "stuck";
+    reason: string;
+};
+export interface TripPlan {
+    /** One line, e.g. "Cancel your Pro plan: 3 steps". */
+    summary: string;
+    /** Plain-language steps; the last one says if the passenger presses it. */
+    steps: string[];
+}
+export interface Planner {
+    plan(view: PageView, manifest: Manifest): Promise<TripPlan | null>;
+    next(view: PageView, manifest: Manifest): Promise<Step>;
+}
+/**
+ * Plans without a model: matches the destination to a manifest action, then walks the link graph
+ * from the current page to that action's page. Good for tests, demos and as a fallback when the
+ * model is unavailable. Production plans with Claude (see ../server/claude-planner.ts).
+ */
+export declare class RoutePlanner implements Planner {
+    private target;
+    private pickTarget;
+    /** Whether an action can be on a page: its own page, the pages it was seen on, or anywhere. */
+    private static on;
+    /** Breadth-first over navigate actions: which links to take from `from` to a page where `target` is. */
+    private path;
+    plan(view: PageView, m: Manifest): Promise<TripPlan | null>;
+    next(view: PageView, m: Manifest): Promise<Step>;
+}