@docsxai/engine 0.2.0

package/dist/playwright-driver.js

@@ -0,0 +1,363 @@
+// Playwright-backed BrowserDriver — the real execution-mode browser.
+//
+// Implements the {@link BrowserDriver} the flow-runtime is written against, over a Playwright
+// `Page`. The runtime stays browser-agnostic; this is the one place that touches Playwright.
+//
+// Needs a browser binary. `playwright-core` ships the API but not the binaries — install one with
+// `pnpm -C packages/engine exec playwright-core install chromium` (source checkout) or
+// `npx playwright-core install chromium` (global/npx installs). For execution
+// against an authed site, the context is created with a captured `storageState` (see the auth layer).
+import { existsSync, promises as fs } from "node:fs";
+import * as path from "node:path";
+import { chromium, } from "playwright-core";
+import { VIEWPORT_PRESETS, } from "./doc-pack.js";
+import { applyRedactions } from "./redact.js";
+import { resolveWorkspacePathReal } from "./workspace.js";
+/**
+ * The cached Chromium binary path, or `undefined` when `playwright-core` has none installed.
+ *
+ * This is the single sanctioned entry point to `chromium.executablePath()`: keeping the
+ * availability probe here (the one module allowed to static-import playwright-core) means callers
+ * like `docsxai doctor` can ask "is a browser present?" without opening a second playwright-core
+ * import site. `executablePath()` only reports where the binary *would* live, so we existsSync it.
+ */
+export function chromiumExecutablePath() {
+    const p = chromium.executablePath();
+    return p && existsSync(p) ? p : undefined;
+}
+/** Map an {@link EnvironmentSpec} to the Playwright context options it pins (clock excluded — that's a page-level install). */
+export function environmentContextOptions(env) {
+    const viewport = typeof env.viewport === "string" ? VIEWPORT_PRESETS[env.viewport] : env.viewport;
+    return {
+        ...(env.locale ? { locale: env.locale } : {}),
+        ...(env.timezone ? { timezoneId: env.timezone } : {}),
+        ...(viewport ? { viewport } : {}),
+        ...(env.color_scheme ? { colorScheme: env.color_scheme } : {}),
+        ...(env.reduced_motion !== undefined
+            ? { reducedMotion: env.reduced_motion ? "reduce" : "no-preference" }
+            : {}),
+    };
+}
+async function installClock(page, env) {
+    if (!env?.clock)
+        return;
+    // `install({ time })` anchors the fake timers but still ticks with real time — millisecond
+    // jitter between runs would break byte-identical screenshots. `setFixedTime` is what actually
+    // freezes `Date`; timers keep running so timer-driven SPAs don't stall. The clock is
+    // context-wide in Playwright, so one install covers every page in the session.
+    await page.clock.install({ time: env.clock });
+    await page.clock.setFixedTime(env.clock);
+}
+/** Launch Chromium (or, with `connectOverCdp`, attach to a running one) and return a {@link PlaywrightSession}. */
+export async function launchPlaywrightSession(opts = {}) {
+    if (opts.connectOverCdp) {
+        const browser = await chromium.connectOverCDP(opts.connectOverCdp);
+        const context = browser.contexts()[0] ?? (await browser.newContext());
+        const pages = context.pages();
+        const page = pages.find((p) => /^https?:/.test(p.url())) ?? pages[0] ?? (await context.newPage());
+        // The attached context is externally owned — context-level environment fields can't apply.
+        // The clock is a page-level install, so it still does.
+        const skipped = ["locale", "timezone", "viewport", "color_scheme", "reduced_motion"].filter((k) => opts.environment?.[k] !== undefined);
+        if (skipped.length || opts.contextOptions) {
+            process.stderr.write(`launchPlaywrightSession: attached over CDP — the browser context is externally owned; skipped: ${[
+                ...skipped.map((k) => `environment.${k}`),
+                ...(opts.contextOptions ? ["contextOptions"] : []),
+            ].join(", ")}\n`);
+        }
+        await installClock(page, opts.environment);
+        const driver = new PlaywrightDriver(page, opts.docPackRoot ?? ".");
+        return {
+            browser,
+            context,
+            page,
+            driver,
+            storageState: () => context.storageState(),
+            // Attached — don't close the browser; just let the connection drop.
+            close: async () => { },
+        };
+    }
+    const browser = await chromium.launch({
+        headless: !opts.headed,
+        ...(opts.chromiumArgs ? { args: opts.chromiumArgs } : {}),
+    });
+    // Playwright's `newContext({ storageState })` accepts the `{ cookies, origins }` object directly.
+    const context = await browser.newContext({
+        ...(opts.baseURL ? { baseURL: opts.baseURL } : {}),
+        ...(opts.storageState ? { storageState: opts.storageState } : {}),
+        ...(opts.ignoreHTTPSErrors ? { ignoreHTTPSErrors: true } : {}),
+        ...(opts.environment ? environmentContextOptions(opts.environment) : {}),
+        ...(opts.contextOptions ?? {}),
+    });
+    const page = await context.newPage();
+    await installClock(page, opts.environment);
+    const driver = new PlaywrightDriver(page, opts.docPackRoot ?? ".");
+    return {
+        browser,
+        context,
+        page,
+        driver,
+        storageState: () => context.storageState(),
+        close: async () => {
+            await context.close().catch(() => { });
+            await browser.close().catch(() => { });
+        },
+    };
+}
+export class PlaywrightDriver {
+    page;
+    docPackRoot;
+    constructor(page, docPackRoot = ".") {
+        this.page = page;
+        this.docPackRoot = docPackRoot;
+    }
+    goto(url) {
+        return this.page.goto(url).then(() => undefined);
+    }
+    click(selector) {
+        return this.page.click(selector);
+    }
+    fill(selector, value) {
+        return this.page.fill(selector, value);
+    }
+    upload(selector, filePath) {
+        return this.page.setInputFiles(selector, path.resolve(this.docPackRoot, filePath));
+    }
+    press(selector, key) {
+        return selector ? this.page.press(selector, key) : this.page.keyboard.press(key);
+    }
+    hover(selector) {
+        return this.page.hover(selector);
+    }
+    selectOption(selector, value) {
+        return this.page.selectOption(selector, value).then(() => undefined);
+    }
+    setChecked(selector, checked) {
+        return this.page.setChecked(selector, checked);
+    }
+    waitForNetworkIdle() {
+        return this.page.waitForLoadState("networkidle");
+    }
+    waitForLoad() {
+        return this.page.waitForLoadState("load");
+    }
+    async waitForElementStable(selector) {
+        // Stable = two consecutive identical bounding boxes (±0.5 px), polled every 100 ms. Best-effort
+        // with a 10 s budget: a perpetually-animating element proceeds after the budget rather than
+        // wedging the run — Playwright's per-action stability check still guards the action itself.
+        const loc = this.page.locator(selector).first();
+        const deadline = Date.now() + 10_000;
+        let prev = null;
+        while (Date.now() < deadline) {
+            const box = await loc.boundingBox({ timeout: 250 }).catch(() => null);
+            if (box &&
+                prev &&
+                Math.abs(box.x - prev.x) <= 0.5 &&
+                Math.abs(box.y - prev.y) <= 0.5 &&
+                Math.abs(box.width - prev.width) <= 0.5 &&
+                Math.abs(box.height - prev.height) <= 0.5) {
+                return;
+            }
+            prev = box;
+            await this.page.waitForTimeout(100);
+        }
+    }
+    waitForSelector(selector, timeoutMs) {
+        return this.page
+            .waitForSelector(selector, timeoutMs ? { timeout: timeoutMs } : {})
+            .then(() => undefined);
+    }
+    waitForTimeout(ms) {
+        return this.page.waitForTimeout(ms);
+    }
+    isVisible(selector) {
+        return this.page.locator(selector).isVisible();
+    }
+    urlMatches(pattern) {
+        return Promise.resolve(new RegExp(pattern).test(this.page.url()));
+    }
+    async textContains(selector, text) {
+        const t = (await this.page
+            .locator(selector)
+            .first()
+            .textContent()
+            .catch(() => null)) ?? "";
+        return t.includes(text);
+    }
+    currentUrl() {
+        return Promise.resolve(this.page.url());
+    }
+    count(selector) {
+        return this.page.locator(selector).count();
+    }
+    textOf(selector) {
+        return this.page
+            .locator(selector)
+            .first()
+            .textContent()
+            .catch(() => null);
+    }
+    async boundingBox(selector, timeoutMs) {
+        // Visible rect, not the element's own rect — intersect with each clipping ancestor (overflow != visible)
+        // and the viewport. Playwright's `Locator.boundingBox()` returns the element's geometry, which for an
+        // element inside a scroll container includes parts that are clipped *off-screen-within-the-scroller* —
+        // the screenshot doesn't show those, so a halo drawn from that rect overflows into the void.
+        const loc = this.page.locator(selector).first();
+        try {
+            await loc.waitFor({
+                state: "visible",
+                ...(timeoutMs !== undefined ? { timeout: timeoutMs } : {}),
+            });
+        }
+        catch {
+            return null;
+        }
+        return loc
+            .evaluate((el) => {
+            const e = el;
+            const view = e.ownerDocument.defaultView;
+            const r = e.getBoundingClientRect();
+            let x = r.left, y = r.top, right = r.right, bottom = r.bottom;
+            let cur = e.parentElement;
+            while (cur) {
+                const cs = view.getComputedStyle(cur);
+                if (cs.overflow !== "visible" ||
+                    cs.overflowX !== "visible" ||
+                    cs.overflowY !== "visible") {
+                    const cr = cur.getBoundingClientRect();
+                    if (cr.left > x)
+                        x = cr.left;
+                    if (cr.top > y)
+                        y = cr.top;
+                    if (cr.right < right)
+                        right = cr.right;
+                    if (cr.bottom < bottom)
+                        bottom = cr.bottom;
+                }
+                cur = cur.parentElement;
+            }
+            if (x < 0)
+                x = 0;
+            if (y < 0)
+                y = 0;
+            if (right > view.innerWidth)
+                right = view.innerWidth;
+            if (bottom > view.innerHeight)
+                bottom = view.innerHeight;
+            if (right <= x || bottom <= y)
+                return null;
+            // `getBoundingClientRect` + innerWidth/Height are CSS pixels; `page.screenshot()` produces a
+            // *device-pixel* image (CSS × devicePixelRatio — e.g. ~2× on a Retina/zoomed Chrome attached
+            // over CDP). The viewer scales the bbox by clientWidth/naturalWidth where naturalWidth is the
+            // PNG's device-pixel width, so the stored bbox must be in that same device-pixel space or the
+            // halo lands at CSS-coords-÷-dpr (badly mispositioned, and a wrong target rect throws the
+            // callout into a clamped sliver). Scale here. dpr === 1 (headless default) → no-op.
+            const dpr = view.devicePixelRatio || 1;
+            return { x: x * dpr, y: y * dpr, width: (right - x) * dpr, height: (bottom - y) * dpr };
+        })
+            .catch(() => null);
+    }
+    async screenshot(relPath, redactions = []) {
+        // relPath segments carry flow names + step ids from the flow-file — containment-checked
+        // (symlink-aware) against the doc-pack root before writing.
+        const abs = await resolveWorkspacePathReal(this.docPackRoot, relPath);
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        // `animations: "disabled"` fast-forwards finite CSS animations/transitions to their end state
+        // and cancels infinite ones, so an element transitioning in (opacity/transform) is captured
+        // fully settled instead of mid-fade. `caret: "hide"` keeps a blinking text caret out of shots.
+        const shotOptions = { animations: "disabled", caret: "hide" };
+        if (redactions.length === 0) {
+            await this.page.screenshot({ path: abs, ...shotOptions });
+            return;
+        }
+        // Redacted path: capture to a buffer, mask, then write — the unredacted bytes never hit disk.
+        const boxes = await this.resolveRedactionBoxes(redactions);
+        const png = await this.page.screenshot(shotOptions);
+        await fs.writeFile(abs, applyRedactions(png, boxes));
+    }
+    /**
+     * Resolve redactions to pixel rects in the screenshot's device-pixel space: selector entries via
+     * {@link boundingBox} (already dpr-scaled), fixed regions scaled by the page's devicePixelRatio.
+     * A selector matching nothing on-page is skipped with a warning — an absent element is vacuously
+     * redacted; halting would punish flows for UI that legitimately isn't there.
+     */
+    async resolveRedactionBoxes(redactions) {
+        const boxes = [];
+        let dpr;
+        for (const r of redactions) {
+            if ("selector" in r) {
+                const bbox = await this.boundingBox(r.selector, 1000);
+                if (!bbox || bbox.width <= 0 || bbox.height <= 0) {
+                    process.stderr.write(`screenshot: redaction selector ${r.selector} has no visible box — skipped\n`);
+                    continue;
+                }
+                boxes.push({ ...bbox, style: r.style });
+            }
+            else {
+                dpr ??= await this.page.evaluate(() => globalThis.devicePixelRatio || 1);
+                boxes.push({
+                    x: r.region.x * dpr,
+                    y: r.region.y * dpr,
+                    width: r.region.width * dpr,
+                    height: r.region.height * dpr,
+                    style: r.style,
+                });
+            }
+        }
+        return boxes;
+    }
+    async actionable(selector, timeoutMs = 300) {
+        const loc = this.page.locator(selector);
+        let count;
+        try {
+            count = await loc.count();
+        }
+        catch {
+            return "not-found";
+        }
+        if (count === 0)
+            return "not-found";
+        if (count > 1)
+            return "multiple-matches";
+        const first = loc.first();
+        try {
+            const attached = await first.evaluate((el) => el.isConnected ?? false);
+            if (!attached)
+                return "detached";
+        }
+        catch {
+            return "detached";
+        }
+        const visible = await first.isVisible().catch(() => false);
+        if (!visible)
+            return "not-visible";
+        // Off-screen check via the visible-rect bbox we already compute (intersects with clipping ancestors
+        // + the viewport). `null` from bbox here means fully clipped — caller's most useful framing is
+        // "off-screen" rather than "not-visible" since CSS-wise the element IS visible.
+        const bbox = await this.boundingBox(selector, timeoutMs).catch(() => null);
+        if (!bbox)
+            return "off-screen";
+        const enabled = await first.isEnabled().catch(() => true);
+        if (!enabled)
+            return "disabled";
+        // "Covered" — hit-test the bbox center; if elementFromPoint returns something that isn't this
+        // element or a descendant of it, another layer is on top.
+        try {
+            const covered = await first.evaluate((el) => {
+                const e = el;
+                const r = e.getBoundingClientRect();
+                const cx = r.left + r.width / 2;
+                const cy = r.top + r.height / 2;
+                const top = e.ownerDocument.elementFromPoint(cx, cy);
+                if (!top || top === el)
+                    return false;
+                return !e.contains(top);
+            });
+            if (covered)
+                return "covered";
+        }
+        catch {
+            // ignore — covered check is best-effort
+        }
+        return "actionable";
+    }
+}

package/dist/playwright-instrumented-browser.d.ts

@@ -0,0 +1,51 @@
+import { type CaptureTrigger, type InstrumentedBrowser, type StorageState } from "./auth.js";
+/** Security-lowered Chromium args (see the module note). */
+export declare const SECURITY_LOWERED_ARGS: readonly string[];
+export interface PlaywrightInstrumentedBrowserOptions {
+    /** Headed by default (the human logs in there). Set true to run headless — for automated tests only. (Ignored when attaching.) */
+    headless?: boolean;
+    /** Accept self-signed / invalid TLS certs (e.g. the target app's local HTTPS dev cert). Default: false. (Ignored when attaching.) */
+    ignoreHTTPSErrors?: boolean;
+    /** Extra Chromium args appended after {@link SECURITY_LOWERED_ARGS}. (Ignored when attaching.) */
+    extraArgs?: string[];
+    /**
+     * If set, launch with a **persistent profile** at this directory (a `userDataDir`) — cookies, localStorage and
+     * login state survive between captures, so re-running `capture-auth` reuses the login instead of a fresh Chrome.
+     * `capture-auth` defaults this to `<workspace>/.auth/chrome-profile/` (gitignored, never leaves the machine).
+     * Mutually exclusive with `connectOverCdp` (attach short-circuits launching).
+     */
+    profileDir?: string;
+    /**
+     * If set, **attach to an already-running Chrome** at this CDP endpoint (e.g. `http://localhost:9222`) instead
+     * of launching a fresh one. Use this to capture from the *same* Chrome the engineer is already logged into —
+     * and that Claude in Chrome is driving for discovery — so they don't log in twice. Start that Chrome with
+     * `--remote-debugging-port=9222 --disable-web-security --disable-features=IsolateOrigins,site-per-process --user-data-dir=<dir>`.
+     * docsxai will **not** close it on `close()` — it's the engineer's session.
+     */
+    connectOverCdp?: string;
+}
+/**
+ * The injected page-side helper. Self-cleans when the Node-side binding is gone (which happens
+ * when the Playwright client detaches — e.g. `capture-auth` finishes and disconnects from a
+ * shared `--cdp` Chrome that stays alive). Without this guard, a stale `__docsxai.capture()`
+ * call after detach throws `Function "__docsxai_capture" is not exposed` in the page console —
+ * cosmetic, but alarming to operators sharing the Chrome with another tool.
+ *
+ * Exported for unit-testing (run the returned script in a `vm` sandbox against a mock window).
+ */
+export declare function helperScript(trigger: CaptureTrigger): string;
+export declare class PlaywrightInstrumentedBrowser implements InstrumentedBrowser {
+    private readonly opts;
+    private browser?;
+    private context?;
+    private page?;
+    private attached;
+    private persistent;
+    private captured;
+    private resolveCaptured;
+    constructor(opts?: PlaywrightInstrumentedBrowserOptions);
+    open(baseURL: string): Promise<void>;
+    waitForCapture(trigger: CaptureTrigger): Promise<void>;
+    storageState(): Promise<StorageState>;
+    close(): Promise<void>;
+}

package/dist/playwright-instrumented-browser.js

@@ -0,0 +1,189 @@
+// Playwright-backed InstrumentedBrowser — the security-lowered, instrumented Chrome `manual-capture` drives.
+//
+// The plugin spawns this; the engineer logs into the target site interactively (Azure AD SSO, MFA,
+// conditional access — anything a human can click through); a console call `window.__docsxai.capture()`
+// (or an injected on-page button) snapshots `storageState`. `--disable-web-security` etc. let the injected
+// helper work across the SSO-redirect origins and relaxed CSP. Headed by default — the human needs to see it.
+import { chromium } from "playwright-core";
+/** Security-lowered Chromium args (see the module note). */
+export const SECURITY_LOWERED_ARGS = [
+    "--disable-web-security",
+    "--disable-features=IsolateOrigins,site-per-process",
+    "--disable-site-isolation-trials",
+];
+const CAPTURE_BINDING = "__docsxai_capture";
+/**
+ * The injected page-side helper. Self-cleans when the Node-side binding is gone (which happens
+ * when the Playwright client detaches — e.g. `capture-auth` finishes and disconnects from a
+ * shared `--cdp` Chrome that stays alive). Without this guard, a stale `__docsxai.capture()`
+ * call after detach throws `Function "__docsxai_capture" is not exposed` in the page console —
+ * cosmetic, but alarming to operators sharing the Chrome with another tool.
+ *
+ * Exported for unit-testing (run the returned script in a `vm` sandbox against a mock window).
+ */
+export function helperScript(trigger) {
+    const button = trigger === "button"
+        ? `if (!document.getElementById("__docsxai_btn")) {
+           var b = document.createElement("button");
+           b.id = "__docsxai_btn"; b.textContent = "\\u2713 Capture session for docsxai";
+           b.style.cssText = "position:fixed;z-index:2147483647;right:12px;bottom:12px;padding:10px 14px;background:#1c1c1c;color:#fff;border:0;border-radius:8px;font:14px system-ui;cursor:pointer;box-shadow:0 2px 8px rgba(0,0,0,.3)";
+           b.onclick = function () { window.__docsxai.capture(); };
+           (document.body || document.documentElement).appendChild(b);
+         }`
+        : "";
+    return `(function () {
+    window.__docsxai = window.__docsxai || {};
+    window.__docsxai.capture = function () {
+      if (typeof window.${CAPTURE_BINDING} !== "function") {
+        // Backing binding is gone (the Playwright client that injected this helper has detached).
+        // Self-clean: drop the button + the helper, log a friendly note. Reload or re-run
+        // \`docsxai capture-auth\` to install a fresh helper.
+        var staleBtn = document.getElementById("__docsxai_btn");
+        if (staleBtn) staleBtn.remove();
+        delete window.__docsxai.capture;
+        if (typeof console !== "undefined" && console.info) {
+          console.info("[docsxai] capture helper detached; reload the page or re-run \`docsxai capture-auth\` to re-install.");
+        }
+        return undefined;
+      }
+      return window.${CAPTURE_BINDING}();
+    };
+    ${button}
+  })();`;
+}
+export class PlaywrightInstrumentedBrowser {
+    opts;
+    browser;
+    context;
+    page;
+    attached = false;
+    persistent = false;
+    captured = Promise.resolve();
+    resolveCaptured = () => { };
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    async open(baseURL) {
+        this.captured = new Promise((resolve) => {
+            this.resolveCaptured = resolve;
+        });
+        if (this.opts.connectOverCdp) {
+            // Attach to an already-running Chrome — the engineer's, already logged in (and being driven by Claude
+            // in Chrome for discovery). One login, one browser. We never close it.
+            this.attached = true;
+            this.browser = await chromium.connectOverCDP(this.opts.connectOverCdp);
+            this.context = this.browser.contexts()[0] ?? (await this.browser.newContext());
+            await this.context.exposeFunction(CAPTURE_BINDING, () => {
+                this.resolveCaptured();
+            });
+            const pages = this.context.pages();
+            this.page =
+                pages.find((p) => /^https?:/.test(p.url())) ?? pages[0] ?? (await this.context.newPage());
+            if (baseURL && this.page.url() === "about:blank")
+                await this.page.goto(baseURL).catch(() => undefined);
+            return;
+        }
+        this.attached = false;
+        if (this.opts.profileDir) {
+            // Launch with a persistent profile — cookies/login survive between captures.
+            this.persistent = true;
+            this.context = await chromium.launchPersistentContext(this.opts.profileDir, {
+                headless: this.opts.headless ?? false,
+                args: [...SECURITY_LOWERED_ARGS, ...(this.opts.extraArgs ?? [])],
+                ...(this.opts.ignoreHTTPSErrors ? { ignoreHTTPSErrors: true } : {}),
+                ...(baseURL ? { baseURL } : {}),
+            });
+            this.browser = this.context.browser() ?? undefined;
+            await this.context.exposeFunction(CAPTURE_BINDING, () => {
+                this.resolveCaptured();
+            });
+            this.page = this.context.pages()[0] ?? (await this.context.newPage());
+            await this.page.goto(baseURL);
+            return;
+        }
+        // Launch a fresh, ephemeral, security-lowered, instrumented Chrome.
+        this.persistent = false;
+        this.browser = await chromium.launch({
+            headless: this.opts.headless ?? false,
+            args: [...SECURITY_LOWERED_ARGS, ...(this.opts.extraArgs ?? [])],
+        });
+        this.context = await this.browser.newContext({
+            baseURL,
+            ...(this.opts.ignoreHTTPSErrors ? { ignoreHTTPSErrors: true } : {}),
+        });
+        // Node-side capture trigger; available on every page in the context (survives navigations).
+        await this.context.exposeFunction(CAPTURE_BINDING, () => {
+            this.resolveCaptured();
+        });
+        this.page = await this.context.newPage();
+        await this.page.goto(baseURL);
+    }
+    async waitForCapture(trigger) {
+        if (!this.context || !this.page)
+            throw new Error("open() must be called before waitForCapture()");
+        const script = helperScript(trigger);
+        await this.context.addInitScript(script); // future documents (incl. post-SSO-redirect)
+        await this.page.evaluate(script).catch(() => undefined); // the already-loaded document too
+        await this.captured;
+    }
+    async storageState() {
+        if (!this.context)
+            throw new Error("storageState() called before open()");
+        const state = await this.context.storageState();
+        for (const page of this.context.pages()) {
+            try {
+                const u = page.url();
+                if (!/^https?:/.test(u))
+                    continue;
+                const origin = new URL(u).origin;
+                const evalAsTyped = page.evaluate.bind(page);
+                const pairs = await evalAsTyped(() => {
+                    const ls = globalThis.localStorage;
+                    const o = [];
+                    for (let i = 0; i < ls.length; i++) {
+                        const k = ls.key(i);
+                        if (k != null)
+                            o.push([k, ls.getItem(k) ?? ""]);
+                    }
+                    return o;
+                });
+                if (!Array.isArray(pairs) || pairs.length === 0)
+                    continue;
+                const items = pairs.map(([name, value]) => ({ name, value }));
+                const existing = state.origins.find((o) => o.origin === origin);
+                if (existing) {
+                    const known = new Set(existing.localStorage.map((e) => e.name));
+                    for (const it of items)
+                        if (!known.has(it.name))
+                            existing.localStorage.push(it);
+                }
+                else {
+                    state.origins.push({ origin, localStorage: items });
+                }
+            }
+            catch {
+                // skip a page we can't read (cross-origin, closed, etc.)
+            }
+        }
+        return state;
+    }
+    async close() {
+        if (this.attached) {
+            // Don't touch the engineer's Chrome — just detach. The injected `__docsxai` helper detects
+            // the backing binding is gone on its next invocation, removes its injected button if any,
+            // logs a friendly info message, and self-deletes from `window.__docsxai.capture`. Safe to
+            // share the Chrome with other automation clients.
+            this.context = undefined;
+            this.browser = undefined;
+            this.page = undefined;
+            return;
+        }
+        // For a persistent context, `context.close()` flushes the profile to disk and closes the browser.
+        await this.context?.close().catch(() => undefined);
+        if (!this.persistent)
+            await this.browser?.close().catch(() => undefined);
+        this.context = undefined;
+        this.browser = undefined;
+        this.page = undefined;
+    }
+}

package/dist/plugins/load.d.ts

@@ -0,0 +1,22 @@
+import type { PluginKind } from "./manifest.js";
+import { PluginRegistry } from "./registry.js";
+import type { AuthStrategyPlugin, PluginLintRule, PluginLogger, PublisherPlugin, RendererPlugin } from "./types.js";
+import { type PluginPlan, type ResolvePluginsOptions } from "./plan.js";
+/** What a plugin's `register(api)` receives. Registered names are auto-prefixed `<ns>:<name>`. */
+export interface PluginRegisterApi {
+    readonly namespace: string;
+    readonly declaredKinds: ReadonlyArray<PluginKind>;
+    readonly declaredCapabilities: ReadonlyArray<string>;
+    registerPublisher(name: string, impl: PublisherPlugin): void;
+    registerRenderer(name: string, impl: RendererPlugin): void;
+    registerLintRules(name: string, rules: PluginLintRule[]): void;
+    registerAuthStrategy(name: string, impl: AuthStrategyPlugin): void;
+    readonly log: PluginLogger;
+    /** Workspace-contained path resolution — the only filesystem root a plugin may write under. */
+    workspacePath(...segments: string[]): string;
+}
+/**
+ * Commit the plan's disabled records, then import + register the surviving plugins in load order.
+ * Every failure is a status, never a throw. This is the only place plugin code is imported.
+ */
+export declare function loadPlugins(opts: ResolvePluginsOptions, plan: PluginPlan): Promise<PluginRegistry>;