passenger-mode 0.0.0-stage → 0.3.0

package/dist/lib/crawl.js

@@ -0,0 +1,189 @@
+/**
+ * Browser scan: builds the manifest from the RUNNING site, for apps the source scanner can't read
+ * (plain HTML, vanilla TypeScript, Svelte, anything). Opens pages in headless Chrome, records the
+ * links, buttons and forms a person can see, and follows same-site links.
+ *
+ * It only reads pages: it never clicks or submits anything, so it is safe to point at a dev server.
+ * Run it against a local or preview build, not production, so analytics stay clean.
+ */
+import { loadChromium } from "./playwright.js";
+import { irreversibleReason, linkGateReason, humanize } from "./gates-text.js";
+import { GENERATOR, isAdminRoute, suggestDestinations } from "./scan.js";
+import { createHash } from "node:crypto";
+import { canonicalPath } from "./runtime/routes.js";
+// Runs inside the page. Kept self-contained: no imports, no closures.
+function collect() {
+    const out = [];
+    const norm = (s) => (s ?? "").replace(/\s+/g, " ").trim();
+    const visible = (el) => {
+        if (el.closest("[data-passenger-mode],[hidden],[inert],[aria-hidden='true']"))
+            return false;
+        const r = el.getBoundingClientRect();
+        if (r.width === 0 && r.height === 0)
+            return false;
+        for (let n = el; n; n = n.parentElement) {
+            const cs = getComputedStyle(n);
+            if (cs.display === "none" || cs.visibility === "hidden")
+                return false;
+        }
+        return true;
+    };
+    const labelOf = (el) => norm(el.getAttribute("aria-label")) || norm(el.innerText) || norm(el.getAttribute("value")) || norm(el.getAttribute("title")) || norm(el.getAttribute("name"));
+    const sels = (el, label) => {
+        const s = [];
+        const add = (by, v) => { if (v)
+            s.push({ by, value: v }); };
+        add("testid", el.getAttribute("data-testid") ?? el.getAttribute("data-test") ?? el.getAttribute("data-cy"));
+        const id = el.getAttribute("id");
+        if (id && !/^(?:[:_]?r\d|radix-|headlessui-|mui-|:\w+:)/.test(id) && !/\d{4,}/.test(id))
+            add("id", id);
+        add("name", el.getAttribute("name"));
+        add("aria-label", el.getAttribute("aria-label"));
+        const href = el.getAttribute("href");
+        if (href && !href.startsWith("javascript:"))
+            add("href", href);
+        if (label && label.length <= 80)
+            s.push({ by: "text", value: label });
+        return s;
+    };
+    const seen = new Set();
+    for (const form of Array.from(document.querySelectorAll("form"))) {
+        if (!visible(form))
+            continue;
+        const submit = form.querySelector('button:not([type="button"]):not([type="reset"]), input[type="submit"]');
+        if (submit)
+            seen.add(submit);
+        const inputs = Array.from(form.querySelectorAll("input, textarea, select"))
+            .filter((f) => !["hidden", "submit", "button"].includes(f.type) && visible(f))
+            .map((f) => ({
+            tag: f.tagName.toLowerCase(),
+            type: f.type || null,
+            name: f.getAttribute("name") ?? f.getAttribute("id"),
+            label: f.getAttribute("aria-label") ?? f.getAttribute("placeholder") ?? (f.id ? norm(document.querySelector(`label[for="${f.id}"]`)?.textContent) || null : null) ?? norm(f.closest("label")?.textContent) ?? null,
+            required: f.required,
+        }));
+        const label = (submit ? labelOf(submit) : "") || labelOf(form) || "Submit form";
+        out.push({ kind: "submit", label: label.slice(0, 120), selectors: sels(form, ""), inputs, code: [form.id, form.getAttribute("name") ?? "", form.getAttribute("action") ?? ""] });
+        if (submit && !out[out.length - 1].selectors.length)
+            out[out.length - 1].selectors.push({ by: "text", value: label.slice(0, 80) });
+    }
+    for (const el of Array.from(document.querySelectorAll("a[href], button, [role='button'], input[type='submit'], input[type='button']"))) {
+        // Disabled controls are kept: many apps enable their main buttons only once they've loaded data.
+        // The driver checks each control is usable at the moment it would press it.
+        if (seen.has(el) || !visible(el))
+            continue;
+        const label = labelOf(el).slice(0, 120);
+        if (el.tagName === "A") {
+            const raw = el.getAttribute("href") ?? "";
+            if (/^(mailto:|tel:|#|javascript:)/.test(raw))
+                continue;
+            let href = raw;
+            try {
+                const u = new URL(raw, location.href);
+                if (u.origin !== location.origin)
+                    continue; // other sites are out of scope
+                href = u.pathname + u.search;
+            }
+            catch {
+                continue;
+            }
+            out.push({ kind: "navigate", label, href, selectors: sels(el, label), code: [raw] });
+        }
+        else {
+            out.push({ kind: "click", label, selectors: sels(el, label), code: [el.id, el.getAttribute("name") ?? "", el.getAttribute("formaction") ?? ""] });
+        }
+    }
+    return out;
+}
+const STATIC_FILE = /\.(png|jpe?g|gif|webp|svg|ico|pdf|zip|mp4|mp3|wav|woff2?|css|js|json|xml|txt)$/i;
+export async function crawl(startUrls, opts = {}) {
+    const { maxPages = 30, includeAdmin = false, settleMs = 600, log = () => { } } = opts;
+    const chromium = await loadChromium("The browser scan");
+    const browser = await chromium.launch({ executablePath: opts.executablePath ?? process.env.CHROME, args: ["--no-sandbox"] });
+    const page = await browser.newPage({ viewport: opts.viewport ?? { width: 1280, height: 900 } });
+    const origin = new URL(startUrls[0]).origin;
+    const queue = startUrls.map((u) => canonicalPath(new URL(u).pathname + new URL(u).search));
+    const visited = new Set();
+    const routes = new Map();
+    const found = new Map();
+    let excluded = 0;
+    while (queue.length && visited.size < maxPages) {
+        const path = queue.shift();
+        if (visited.has(path))
+            continue;
+        visited.add(path);
+        const pathname = path.split("?")[0] || "/";
+        if (!includeAdmin && isAdminRoute(pathname)) {
+            excluded++;
+            continue;
+        }
+        try {
+            const res = await page.goto(origin + path, { waitUntil: "load", timeout: 20_000 });
+            if (!res || res.status() >= 400) {
+                log(`skip ${path} (${res?.status() ?? "no response"})`);
+                continue;
+            }
+            await page.waitForTimeout(settleMs);
+        }
+        catch (e) {
+            log(`skip ${path} (${e.message.split("\n")[0]})`);
+            continue;
+        }
+        const landed = new URL(page.url());
+        if (landed.origin !== origin)
+            continue;
+        // Apps that switch screens with parameters (?lobby=1) get one route per screen.
+        const route = canonicalPath(landed.pathname + landed.search);
+        routes.set(route, { path: route, file: `(browser) ${route}` });
+        // Sent as source text: TypeScript runners wrap functions in a __name() helper the page doesn't have.
+        const raws = await page.evaluate(`(() => { const __name = (f) => f; return (${collect.toString()})(); })()`);
+        log(`${path}: ${raws.length} actions`);
+        for (const r of raws) {
+            const key = `${r.kind}|${r.label}|${r.selectors[0]?.by}:${r.selectors[0]?.value ?? ""}`;
+            const entry = found.get(key) ?? { raw: r, routes: new Set() };
+            entry.routes.add(route);
+            found.set(key, entry);
+            if (r.kind === "navigate" && r.href) {
+                r.href = canonicalPath(r.href);
+                if (!STATIC_FILE.test(r.href.split("?")[0]) && !r.href.startsWith("/api/") && !visited.has(r.href) && !queue.includes(r.href))
+                    queue.push(r.href);
+            }
+        }
+    }
+    await browser.close();
+    const actions = [];
+    for (const { raw, routes: seenOn } of found.values()) {
+        // On one page: that page. On several: shared, with the pages it was seen on, so the planner
+        // routes to one of them instead of assuming it is everywhere.
+        const route = seenOn.size === 1 ? [...seenOn][0] : null;
+        const seen = seenOn.size > 1 ? { seenOn: [...seenOn].sort() } : {};
+        const reason = raw.kind === "navigate" ? linkGateReason(raw.label, raw.href) : irreversibleReason([raw.label], raw.code);
+        const slug = humanize(raw.label).replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 32) || "unlabeled";
+        const h = createHash("sha1").update(`${raw.kind}|${raw.label}|${JSON.stringify(raw.selectors[0] ?? null)}|${route}`).digest("hex").slice(0, 6);
+        actions.push({
+            id: `${raw.kind}.${slug}.${h}`,
+            kind: raw.kind,
+            label: raw.label || "(unlabeled)",
+            route,
+            ...seen,
+            file: "(browser scan)",
+            line: 0,
+            selectors: raw.selectors,
+            ...(raw.href ? { href: raw.href } : {}),
+            ...(raw.inputs ? { inputs: raw.inputs } : {}),
+            irreversible: reason !== null,
+            irreversibleReason: reason,
+        });
+    }
+    const routeList = [...routes.values()].sort((a, b) => a.path.localeCompare(b.path));
+    return {
+        version: 1,
+        generator: `${GENERATOR} (browser scan)`,
+        generatedAt: new Date().toISOString(),
+        framework: "unknown",
+        stats: { files: visited.size, routes: routeList.length, actions: actions.length, irreversible: actions.filter((a) => a.irreversible).length, excludedAdminRoutes: excluded },
+        routes: routeList,
+        actions,
+        destinations: suggestDestinations(actions),
+    };
+}

package/dist/lib/gates-text.d.ts

@@ -0,0 +1,10 @@
+/** A price on a button means pressing it spends money ("Try Kit · $4.99 once", "Choose · $9.99/month"). */
+export declare const PRICE: RegExp;
+export declare function humanize(s: string): string;
+/** labels: what the person sees. code: names, ids, handlers, hrefs. */
+export declare function irreversibleReason(labels: Array<string | null | undefined>, code?: Array<string | null | undefined>): string | null;
+/**
+ * Links only change pages: "Upgrade" opens the checkout, and paying happens there behind its own gate.
+ * So a link is a gate only when it acts by itself: sign-out, delete or unsubscribe URLs.
+ */
+export declare function linkGateReason(label: string, href: string | null | undefined): string | null;

package/dist/lib/gates-text.js

@@ -0,0 +1,48 @@
+// Shared by the scanner (build time) and the driver (in the page), so it must stay dependency-free.
+/** Errs toward flagging too much: a false flag costs the passenger one click, a missed one could cost them money. */
+const IRREVERSIBLE = [
+    [/\b(pay|payment|purchase|checkout|check ?out|buy|place (your )?order|order now|confirm (order|purchase)|donate|subscribe|upgrade)\b/, "payment"],
+    [/\b(cancel|end|stop)\b.{0,30}\b(plan|subscription|membership|club|trial|order|booking|reservation)\b|\bunsubscribe\b|\bdowngrade\b/, "cancels a plan or order"],
+    [/\b(delete|destroy|erase|wipe|purge)\b|\bremove (account|user|member|card|payment)\b|\b(close|deactivate) (my |your )?account\b/, "deletion"],
+    [/\b(change|update|reset|set)\b.{0,20}\b(password|e-?mail|2fa|passkey|two[- ]factor)\b|\bnew password\b/, "credential change"],
+    [/\b(sign ?out|log ?out)\b/, "ends the session"],
+];
+/** Checked against what the person sees only. Handler code is full of analytics calls like send() and share(). */
+const IRREVERSIBLE_LABEL_ONLY = [
+    [/\b(send|invite|share with)\b/, "sends to other people"],
+    [/\b(publish|go live|make public|unpublish)\b/, "publishes"],
+];
+/** A price on a button means pressing it spends money ("Try Kit · $4.99 once", "Choose · $9.99/month"). */
+export const PRICE = /[$€£¥₹]\s?\d|\d(?:[.,]\d{2})?\s?(?:usd|eur|gbp|dollars?)\b|\bper (?:month|year|seat)\b|\/\s?(?:mo|month|yr|year)\b/i;
+/** Analytics and logging calls that look like actions but aren't. */
+const ANALYTICS_CALL = /\b(send|track|capture|gtag|analytics|log|report|emit|posthog|plausible|umami)\s*\(/gi;
+export function humanize(s) {
+    return s
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/[_\-./]+/g, " ")
+        .toLowerCase();
+}
+/** labels: what the person sees. code: names, ids, handlers, hrefs. */
+export function irreversibleReason(labels, code = []) {
+    const seen = labels.filter(Boolean).map((t) => humanize(t)).join(" | ");
+    const all = [seen, ...code.filter(Boolean).map((t) => humanize(t.replace(ANALYTICS_CALL, "(")))].join(" | ");
+    for (const [re, reason] of IRREVERSIBLE)
+        if (re.test(all))
+            return reason;
+    for (const [re, reason] of IRREVERSIBLE_LABEL_ONLY)
+        if (re.test(seen))
+            return reason;
+    if (labels.some((t) => t && PRICE.test(t)))
+        return "payment";
+    return null;
+}
+/**
+ * Links only change pages: "Upgrade" opens the checkout, and paying happens there behind its own gate.
+ * So a link is a gate only when it acts by itself: sign-out, delete or unsubscribe URLs.
+ */
+export function linkGateReason(label, href) {
+    const h = href ?? "";
+    if (/(log-?out|sign-?out|logoff|\/delete|\/destroy|\/remove|unsubscribe)/i.test(h))
+        return irreversibleReason([label, h]) ?? "acts on its own";
+    return /\b(sign ?out|log ?out)\b/i.test(humanize(label)) ? "ends the session" : null;
+}

package/dist/lib/playwright.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Finds Playwright's chromium. Looks in the site's own project first (where `npm i -D playwright` puts it,
+ * even when this CLI runs through npx), then next to this package, then PASSENGER_MODE_PLAYWRIGHT.
+ */
+export declare function loadChromium(what: string): Promise<any>;

package/dist/lib/playwright.js

@@ -0,0 +1,35 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+/**
+ * Finds Playwright's chromium. Looks in the site's own project first (where `npm i -D playwright` puts it,
+ * even when this CLI runs through npx), then next to this package, then PASSENGER_MODE_PLAYWRIGHT.
+ */
+export async function loadChromium(what) {
+    const tries = [];
+    if (process.env.PASSENGER_MODE_PLAYWRIGHT)
+        tries.push(process.env.PASSENGER_MODE_PLAYWRIGHT);
+    try {
+        tries.push(createRequire(join(process.cwd(), "noop.js")).resolve("playwright"));
+    }
+    catch { }
+    tries.push("playwright");
+    for (const t of tries) {
+        try {
+            const mod = await import(__rewriteRelativeImportExtension(t.startsWith("/") ? pathToFileURL(t).href : t));
+            const chromium = mod.chromium ?? mod.default?.chromium;
+            if (chromium)
+                return chromium;
+        }
+        catch { }
+    }
+    throw new Error(`${what} needs Playwright: npm i -D playwright && npx playwright install chromium (or set PASSENGER_MODE_PLAYWRIGHT to its path).`);
+}

package/dist/lib/react.d.ts

@@ -0,0 +1,8 @@
+import { type MountOptions } from "./runtime/index.ts";
+/**
+ * <PassengerMode publicKey="pk_..." /> in your root layout. Renders nothing itself: the switch
+ * lives in its own overlay. Client-only (add "use client" above the import in Next.js).
+ */
+export declare function PassengerMode(props: Omit<MountOptions, "window" | "key"> & {
+    publicKey?: string;
+}): null;

package/dist/lib/react.js

@@ -0,0 +1,23 @@
+import { useEffect } from "react";
+import { mount } from "./runtime/index.js";
+/**
+ * <PassengerMode publicKey="pk_..." /> in your root layout. Renders nothing itself: the switch
+ * lives in its own overlay. Client-only (add "use client" above the import in Next.js).
+ */
+export function PassengerMode(props) {
+    const { publicKey, ...rest } = props;
+    useEffect(() => {
+        let handle = null;
+        let gone = false;
+        void mount({ ...rest, key: publicKey }).then((h) => {
+            if (gone)
+                h?.destroy();
+            else
+                handle = h;
+        });
+        return () => { gone = true; handle?.destroy(); };
+        // Mount once per key/endpoint; the manifest and planner are read at mount time.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [publicKey, rest.apiBase, rest.endpoint]);
+    return null;
+}

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

@@ -0,0 +1,101 @@
+import type { Manifest } from "../types.ts";
+import type { PageView, Planner, TripPlan } from "./planner.ts";
+export type DriverState = "off" | "open" | "planning" | "ready" | "driving" | "paused" | "gate" | "handoff" | "arrived" | "stuck";
+export interface TripStep {
+    actionId: string;
+    label: string;
+    route: string | null;
+    by: "driver" | "passenger";
+    at: number;
+}
+export interface TripLog {
+    /** Random per trip, so a later rating updates the same record. */
+    id: string;
+    destination: string;
+    startedAt: number;
+    endedAt?: number;
+    outcome?: "arrived" | "taken-over" | "ended" | "stuck";
+    reason?: string;
+    steps: TripStep[];
+    rating?: "up" | "down";
+}
+/** What the driver shows. The DOM overlay implements it; tests use a recorder. */
+export interface DriverUI {
+    render(state: DriverState, info: {
+        plan?: TripPlan | null;
+        caption?: string;
+        message?: string;
+        destination?: string;
+        step?: number;
+    }): void;
+    moveCursor(el: Element, caption: string): Promise<void>;
+    ring(el: Element | null, tone?: "drive" | "gate" | "handoff"): void;
+    /** True for nodes that belong to Passenger Mode's own UI (they never count as taking the wheel). */
+    owns(node: Node | null): boolean;
+}
+export interface DriverOptions {
+    manifest: Manifest;
+    planner: Planner;
+    window: Window;
+    ui?: DriverUI;
+    /** Where the route lives: the pathname (default), the hash, or your router's own answer. */
+    routeFrom?: "path" | "hash" | (() => string);
+    /** Defaults to event.isTrusted. Only tests replace it. */
+    isTrusted?: (e: Event) => boolean;
+    maxSteps?: number;
+    timeLimitMs?: number;
+    settleMs?: number;
+    storage?: Storage | null;
+    onTrip?: (log: TripLog) => void;
+}
+export declare class Driver {
+    state: DriverState;
+    plan: TripPlan | null;
+    log: TripLog | null;
+    private o;
+    private ui;
+    private run;
+    private gateEl;
+    private gateAction;
+    private stepCount;
+    private detach;
+    constructor(opts: DriverOptions);
+    get doc(): Document;
+    private path;
+    private set;
+    /** Flip the switch on. A script cannot do this: it needs a trusted event. */
+    open(e: Event): boolean;
+    /** Switch off. Always allowed: stopping is the safe direction. */
+    close(): void;
+    planTrip(destination: string, e: Event): Promise<TripPlan | null>;
+    /** Nothing moves until the passenger presses Go. */
+    go(e: Event): boolean;
+    /** Back to choosing a destination. */
+    notThis(): void;
+    takeWheel(): void;
+    resume(e: Event): boolean;
+    end(): void;
+    rate(up: boolean): void;
+    /** What the planner may see: the destination and the manifest actions on this page. No page text. */
+    view(): PageView;
+    private find;
+    private drive;
+    private live;
+    private loop;
+    /** The driver stops at the control and waits for the passenger's own, trusted click on it. */
+    private pullOver;
+    private onGateClick;
+    private record;
+    private arrive;
+    private stuck;
+    private finish;
+    /** Waits for the page to react: a route change or DOM changes, then a short quiet period. */
+    private settle;
+    private linksHere;
+    /** Full page loads end the script; a trip in flight is saved so the next page can carry on. */
+    private markNav;
+    private clearNav;
+    private restore;
+    private listen;
+    destroy(): void;
+}