sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/frame-sessions.d.ts

@@ -0,0 +1,71 @@
+import type { CDPSession, Frame, Page } from '@playwright/test';
+/** An execution context: one world in one frame. */
+export interface ContextInfo {
+    /** The CDP id of its frame. */
+    frameId: string;
+    /** The world's name: '' for the page's own. */
+    name: string;
+    /** The frame's own (main) world. */
+    isDefault: boolean;
+    /** For an extension's world, its origin (`chrome-extension://<id>`). */
+    origin: string;
+}
+/** One session: the page's, or an out-of-process iframe's. */
+export interface FrameSession {
+    cdp: CDPSession;
+    /** The frame it was made for: the page's main frame, or the iframe. */
+    root: Frame;
+    /** Its execution contexts by id, as `Runtime` reports them. */
+    contexts: Map<number, ContextInfo>;
+    /** Its CDP target's id, once asked for (`targetIdOf`). */
+    targetId?: Promise<string | undefined>;
+}
+/** What a session's setup can listen for besides its contexts. */
+export type SessionSetup = (session: FrameSession) => void | Promise<void>;
+export declare class FrameSessions {
+    private readonly page;
+    private readonly setup;
+    private readonly sessions;
+    private readonly inParent;
+    private disposed;
+    private generation;
+    private readonly trees;
+    private readonly onAttached;
+    private readonly onNavigated;
+    private readonly onDetached;
+    private constructor();
+    /**
+     * Sessions for `page` and each out-of-process iframe it has or gets,
+     * each set up with `setup` before `Runtime` is on (so it hears the
+     * contexts that exist already). Null when the page has closed.
+     */
+    static attach(page: Page, setup?: SessionSetup): Promise<FrameSessions | null>;
+    /** The page's own session. */
+    pageSession(): Promise<FrameSession | null>;
+    /** Every session open now. */
+    all(): Promise<FrameSession[]>;
+    /**
+     * The session `frame` runs in, and its CDP frame id there, or null
+     * when it can't be found (detached, or between documents).
+     */
+    locate(frame: Frame): Promise<{
+        session: FrameSession;
+        frameId: string;
+    } | null>;
+    /**
+     * The CDP target id of an iframe Chrome runs in a process of its own,
+     * which a raw CDP client attaches to (`Target.attachToTarget`).
+     * Undefined for one in its parent's process, which is part of the
+     * page's target.
+     */
+    targetIdOf(frame: Frame): Promise<string | undefined>;
+    /** The frame a session's CDP frame id names, or undefined. */
+    frameOf(session: FrameSession, frameId: string): Promise<Frame | undefined>;
+    /** Detach all its sessions. */
+    dispose(): Promise<void>;
+    private childNode;
+    private treeOf;
+    private close;
+    private sessionFor;
+    private open;
+}

package/lib/harness/frame-sessions.js

@@ -0,0 +1,248 @@
+// A tab's DevTools (CDP) sessions, one per process its frames run in:
+// the page's own, and one for each iframe Chrome runs in a process of
+// its own (an out-of-process iframe): one from another site than its
+// parent (another registrable domain: not just another subdomain or
+// port), with site isolation on, as it is by default. The page's session
+// never sees inside those, so evaluating in such a frame, or telling
+// which frame a console line came from, needs the frame's own session.
+// See docs/sm-dev-frames.md.
+//
+// - Each session has `Runtime` on, and keeps its execution contexts
+//   (each world of each frame it covers).
+// - A session's frames are known by CDP frame ids; sm-dev knows frames
+//   by Playwright's `Frame`. A session's root is exact (the page, or
+//   the frame the session was made for). Below it, a frame is matched
+//   by its parent and URL, as `matchFrameTrees` does for the extension.
+export class FrameSessions {
+    page;
+    setup;
+    sessions = new Map();
+    // Frames tried and found to be in their parent's process, by the URL
+    // they had: a navigation can move a frame into a process of its own.
+    inParent = new WeakMap();
+    disposed = false;
+    // Bumped on each frame change, which can change a session's frame tree.
+    generation = 0;
+    trees = new WeakMap();
+    onAttached = (frame) => {
+        this.generation++;
+        if (frame !== this.page.mainFrame())
+            void this.sessionFor(frame);
+    };
+    // A navigation can move a frame into a process of its own or back into
+    // its parent's, which ends its own target: its session is opened again.
+    onNavigated = (frame) => {
+        this.generation++;
+        if (frame === this.page.mainFrame())
+            return;
+        this.close(frame);
+        void this.sessionFor(frame);
+    };
+    onDetached = (frame) => {
+        this.generation++;
+        this.close(frame);
+    };
+    constructor(page, setup) {
+        this.page = page;
+        this.setup = setup;
+    }
+    /**
+     * Sessions for `page` and each out-of-process iframe it has or gets,
+     * each set up with `setup` before `Runtime` is on (so it hears the
+     * contexts that exist already). Null when the page has closed.
+     */
+    static async attach(page, setup = () => undefined) {
+        const sessions = new FrameSessions(page, setup);
+        const main = await sessions.open(page.mainFrame());
+        if (typeof main !== 'object' || main === null)
+            return null;
+        page.on('frameattached', sessions.onAttached);
+        page.on('framenavigated', sessions.onNavigated);
+        page.on('framedetached', sessions.onDetached);
+        for (const frame of page.frames())
+            sessions.onAttached(frame);
+        return sessions;
+    }
+    /** The page's own session. */
+    async pageSession() {
+        return this.sessions.get(this.page.mainFrame()) ?? null;
+    }
+    /** Every session open now. */
+    async all() {
+        return (await Promise.all(this.sessions.values())).filter((s) => s !== null);
+    }
+    /**
+     * The session `frame` runs in, and its CDP frame id there, or null
+     * when it can't be found (detached, or between documents).
+     */
+    async locate(frame) {
+        if (frame.isDetached())
+            return null;
+        // The nearest of the frame and its ancestors with a session.
+        const path = [];
+        let session = null;
+        for (let f = frame; f; f = f.parentFrame()) {
+            session = f === this.page.mainFrame() ? await this.pageSession() : await this.sessionFor(f);
+            if (session)
+                break;
+            path.unshift(f);
+        }
+        if (!session)
+            return null;
+        const tree = await this.treeOf(session);
+        if (!tree)
+            return null;
+        let node = tree;
+        let at = session.root;
+        for (const step of path) {
+            const child = await this.childNode(node, at, step);
+            if (!child)
+                return null;
+            node = child;
+            at = step;
+        }
+        return { session, frameId: node.frame.id };
+    }
+    /**
+     * The CDP target id of an iframe Chrome runs in a process of its own,
+     * which a raw CDP client attaches to (`Target.attachToTarget`).
+     * Undefined for one in its parent's process, which is part of the
+     * page's target.
+     */
+    async targetIdOf(frame) {
+        if (frame === this.page.mainFrame())
+            return undefined;
+        const session = await this.sessionFor(frame);
+        if (!session)
+            return undefined;
+        session.targetId ??= session.cdp.send('Target.getTargetInfo').then((r) => r.targetInfo.targetId, () => undefined);
+        return session.targetId;
+    }
+    /** The frame a session's CDP frame id names, or undefined. */
+    async frameOf(session, frameId) {
+        const tree = await this.treeOf(session);
+        if (!tree)
+            return undefined;
+        const walk = async (node, frame) => {
+            if (node.frame.id === frameId)
+                return frame;
+            for (const child of frame.childFrames()) {
+                const childNode = await this.childNode(node, frame, child);
+                if (!childNode)
+                    continue;
+                const found = await walk(childNode, child);
+                if (found)
+                    return found;
+            }
+            return undefined;
+        };
+        return walk(tree, session.root);
+    }
+    /** Detach all its sessions. */
+    async dispose() {
+        this.disposed = true;
+        this.page.off('frameattached', this.onAttached);
+        this.page.off('framenavigated', this.onNavigated);
+        this.page.off('framedetached', this.onDetached);
+        const all = await this.all();
+        await Promise.all(all.map((s) => s.cdp.detach().catch(() => undefined)));
+    }
+    // The CDP node of `child` (a Playwright child of `frame`) among the
+    // children of `node` (`frame`'s CDP node): one in its own process
+    // isn't in this tree. Siblings with one URL go by order.
+    async childNode(node, frame, child) {
+        const local = [];
+        for (const c of frame.childFrames())
+            if (!await this.sessionFor(c))
+                local.push(c);
+        const url = child.url();
+        const same = local.filter((c) => c.url() === url);
+        const nodes = (node.childFrames ?? []).filter((n) => n.frame.url + (n.frame.urlFragment ?? '') === url || n.frame.url === url);
+        return nodes[same.indexOf(child)];
+    }
+    // A session's CDP frame tree, read once until the frames change: a
+    // console line from each frame asks for it.
+    treeOf(session) {
+        const known = this.trees.get(session);
+        if (known?.generation === this.generation)
+            return known.tree;
+        const tree = session.cdp.send('Page.getFrameTree').then((r) => r.frameTree, () => null);
+        this.trees.set(session, { generation: this.generation, tree });
+        return tree;
+    }
+    // Ends an iframe's own session, if it has one.
+    close(frame) {
+        const known = this.sessions.get(frame);
+        if (!known)
+            return;
+        this.sessions.delete(frame);
+        void known.then((session) => session?.cdp.detach()).catch(() => undefined);
+    }
+    // A frame's own session, opened if it runs out of process; null when
+    // it shares its parent's. Asked again after the frame navigates
+    // elsewhere, which can move it.
+    sessionFor(frame) {
+        if (frame === this.page.mainFrame())
+            return this.sessions.get(frame) ?? Promise.resolve(null);
+        const known = this.sessions.get(frame);
+        if (known)
+            return known;
+        if (this.inParent.get(frame) === frame.url())
+            return Promise.resolve(null);
+        const url = frame.url();
+        const opening = this.open(frame).then((session) => {
+            if (session === 'in-parent')
+                this.inParent.set(frame, url);
+            // A failure other than that is tried again next time.
+            if (typeof session !== 'object' || session === null) {
+                if (this.sessions.get(frame) === opening)
+                    this.sessions.delete(frame);
+                return null;
+            }
+            // Its target went (the frame left): the next look opens another.
+            session.cdp.on('Inspector.detached', () => { if (this.sessions.get(frame) === opening)
+                this.sessions.delete(frame); });
+            return session;
+        });
+        this.sessions.set(frame, opening);
+        return opening;
+    }
+    // A session for `frame`; 'in-parent' when it shares its parent's
+    // process, so has none of its own; null when it couldn't be opened.
+    async open(frame) {
+        if (this.disposed || frame.isDetached())
+            return null;
+        let cdp;
+        try {
+            // Playwright refuses a frame that shares its parent's process.
+            cdp = await this.page.context().newCDPSession(frame === this.page.mainFrame() ? this.page : frame);
+        }
+        catch {
+            return frame.isDetached() ? null : 'in-parent';
+        }
+        const session = { cdp, root: frame, contexts: new Map() };
+        cdp.on('Runtime.executionContextCreated', ({ context }) => {
+            const aux = (context.auxData ?? {});
+            session.contexts.set(context.id, { frameId: aux.frameId ?? '', name: context.name, isDefault: aux.isDefault === true, origin: context.origin });
+        });
+        cdp.on('Runtime.executionContextDestroyed', (ev) => { session.contexts.delete(ev.executionContextId); });
+        cdp.on('Runtime.executionContextsCleared', () => { session.contexts.clear(); });
+        try {
+            await this.setup(session);
+            await cdp.send('Page.enable');
+            await cdp.send('Runtime.enable');
+        }
+        catch {
+            await cdp.detach().catch(() => undefined);
+            return null;
+        }
+        // Disposed meanwhile: nothing would detach it later.
+        if (this.disposed) {
+            await cdp.detach().catch(() => undefined);
+            return null;
+        }
+        if (frame === this.page.mainFrame())
+            this.sessions.set(frame, Promise.resolve(session));
+        return session;
+    }
+}

package/lib/harness/frames.d.ts

@@ -0,0 +1,68 @@
+import type { Frame, Page } from '@playwright/test';
+/** One frame of a tab as the extension lists it (`webNavigation.getAllFrames`). */
+export interface ExtensionFrame {
+    /** 0 for the top frame. Kept across the frame's navigations. */
+    frameId: number;
+    /** -1 for the top frame. */
+    parentFrameId: number;
+    documentId: string;
+    url: string;
+}
+/** One of a tab's iframes, as `frameNodes` lists them. */
+export interface FrameNode {
+    frame: Frame;
+    /** Its id's number: `F3` is 3. */
+    n: number;
+    /** Its parent's id number, or null for a frame in the top frame. */
+    parent: number | null;
+    /** How deep it is: 1 for a frame in the top frame. */
+    depth: number;
+    url: string;
+}
+/**
+ * The run's frame ids: `F1`, `F2`, ... across all tabs, in the order
+ * frames are first seen (a page's together, in document order). The top
+ * frame has none: the tab's id names it.
+ *
+ * A frame that has gone gives its id to the next one in its place: one
+ * with the same parent and URL, as after the tab reloads. So `F2` names
+ * the same iframe after a reload, though Playwright makes new `Frame`s
+ * for them. Otherwise ids aren't reused.
+ */
+export declare class FrameIds {
+    private next;
+    private readonly numbers;
+    private readonly places;
+    private readonly seen;
+    number(frame: Frame): number;
+    /**
+     * Whether `frame` is waiting to be numbered: see `waits`. Listings
+     * leave such a frame out until it loads.
+     */
+    waiting(frame: Frame): boolean;
+    private waits;
+    private reused;
+}
+/** `F3` or `T1.F3`: the frame's number, and the tab's if given. */
+export declare function parseFrameRef(text: string): {
+    tab?: number;
+    frame: number;
+} | null;
+/** A page's iframes, each after its parent, with ids given to new ones. */
+export declare function frameNodes(page: Page, ids: FrameIds): FrameNode[];
+/** The iframe `F<n>` names in `page`, while it's there. */
+export declare function findFrame(page: Page, ids: FrameIds, n: number): Frame | undefined;
+/**
+ * Which of `nodes` each of the extension's frames is, by tree shape and
+ * URL: from the top down, a frame is its parent's child with the same
+ * URL. `known` (the last answer) goes first, so that of two sibling
+ * frames with one URL, each keeps its match.
+ *
+ * Returns the extension's frame ids mapped to the node keys. The top
+ * frame (frameId 0) maps to null.
+ */
+export declare function matchFrameTrees<K>(frames: readonly ExtensionFrame[], nodes: readonly {
+    key: K;
+    parent: K | null;
+    url: string;
+}[], known?: ReadonlyMap<number, K>): Map<number, K | null>;

package/lib/harness/frames.js

@@ -0,0 +1,216 @@
+// A run's iframes (frames, below): their ids, the tree of a tab's
+// frames, and which of the extension's frames each is.
+// See docs/sm-dev-frames.md.
+//
+// - Ids come from Playwright's frames (`mainFrame().childFrames()`,
+//   down the tree), which cover every frame of a page, cross-origin
+//   ones included (the page's own CDP frame tree leaves those out).
+//   Playwright keeps one `Frame` per frame across its navigations, so
+//   an id names the frame, not its document.
+// - The extension knows a frame by its `frameId` and documents by
+//   `documentId` (`chrome.webNavigation.getAllFrames`); nothing in
+//   either side names the other's. So the two trees are matched by
+//   their shape and URLs (`matchFrameTrees`).
+/**
+ * The run's frame ids: `F1`, `F2`, ... across all tabs, in the order
+ * frames are first seen (a page's together, in document order). The top
+ * frame has none: the tab's id names it.
+ *
+ * A frame that has gone gives its id to the next one in its place: one
+ * with the same parent and URL, as after the tab reloads. So `F2` names
+ * the same iframe after a reload, though Playwright makes new `Frame`s
+ * for them. Otherwise ids aren't reused.
+ */
+export class FrameIds {
+    next = 1;
+    numbers = new WeakMap();
+    // Each page's numbered frames, the gone ones' places included.
+    places = new WeakMap();
+    // When a frame was first found waiting (`waits`).
+    seen = new WeakMap();
+    number(frame) {
+        const known = this.numbers.get(frame);
+        if (known !== undefined)
+            return known;
+        const page = frame.page();
+        let places = this.places.get(page);
+        if (!places)
+            this.places.set(page, places = []);
+        const give = (child, parent) => {
+            const n = this.reused(places, child, parent) ?? this.next++;
+            this.numbers.set(child, n);
+            places.push({ frame: child, n, parent });
+            // Gone frames' places are kept only so long, for a page that keeps
+            // replacing its ad frames.
+            const gone = places.filter((p) => p.frame.isDetached());
+            for (const old of gone.slice(0, Math.max(0, gone.length - MAX_GONE)))
+                places.splice(places.indexOf(old), 1);
+        };
+        // The page's new frames are numbered together, down its tree, so
+        // ids read in document order whichever frame was heard from first.
+        const walk = (parent, parentN) => {
+            // Once a frame waits, so do its later siblings: of two with one
+            // URL, the one loaded first mustn't take the earlier one's id.
+            let held = false;
+            for (const child of parent.childFrames()) {
+                if (!this.numbers.has(child) && !child.isDetached()) {
+                    held ||= this.waits(places, child, parentN);
+                    if (!held || child === frame)
+                        give(child, parentN);
+                }
+                const n = this.numbers.get(child);
+                if (n !== undefined)
+                    walk(child, n);
+            }
+        };
+        if (!page.isClosed())
+            walk(page.mainFrame(), null);
+        // Detached already, or not in the tree yet (under a frame that
+        // waits). Its place is kept all the same, for a later frame in it.
+        if (!this.numbers.has(frame)) {
+            const parent = frame.parentFrame();
+            const parentN = parent && parent !== page.mainFrame() ? this.numbers.get(parent) : null;
+            if (parentN === undefined || frame.isDetached())
+                this.numbers.set(frame, this.next++);
+            else
+                give(frame, parentN);
+        }
+        return this.numbers.get(frame);
+    }
+    /**
+     * Whether `frame` is waiting to be numbered: see `waits`. Listings
+     * leave such a frame out until it loads.
+     */
+    waiting(frame) {
+        if (this.numbers.has(frame) || frame.isDetached())
+            return false;
+        const parent = frame.parentFrame();
+        if (!parent)
+            return false;
+        const parentN = parent === frame.page().mainFrame() ? null : this.numbers.get(parent);
+        if (parentN === undefined)
+            return false;
+        const places = this.places.get(frame.page()) ?? [];
+        // It, or an earlier sibling that holds it back (as in `number`).
+        for (const sibling of parent.childFrames()) {
+            if (!this.numbers.has(sibling) && !sibling.isDetached() && this.waits(places, sibling, parentN))
+                return true;
+            if (sibling === frame)
+                return false;
+        }
+        return false;
+    }
+    // Whether a frame waits to be numbered: it hasn't loaded its first
+    // document (no URL yet, or the `about:blank` a new frame starts with),
+    // and a gone frame's id could be its once it has. Numbered now, it
+    // would take a new id. Only for so long, as some frames stay on
+    // `about:blank` (one with no `src`, or one a script writes into).
+    waits(places, frame, parent) {
+        const url = frame.url();
+        if (url !== '' && url !== 'about:blank')
+            return false;
+        if (!places.some((p) => p.parent === parent && p.frame.isDetached() && p.frame.url() !== url))
+            return false;
+        const now = Date.now();
+        let since = this.seen.get(frame);
+        if (since === undefined)
+            this.seen.set(frame, since = now);
+        return now - since < WAIT_MS;
+    }
+    // The id of a gone frame in `child`'s place: the same parent, and its
+    // URL, or failing that the same page at another query or fragment.
+    reused(places, child, parent) {
+        const url = child.url();
+        const gone = places.filter((p) => p.parent === parent && p.frame.isDetached());
+        // A frame keeps its last URL once detached.
+        const place = gone.find((p) => p.frame.url() === url) ?? gone.find((p) => bareUrl(p.frame.url()) === bareUrl(url));
+        if (!place)
+            return undefined;
+        // Its place is taken: the new frame's from now on.
+        places.splice(places.indexOf(place), 1);
+        return place.n;
+    }
+}
+// How many gone frames' places a page keeps.
+const MAX_GONE = 100;
+// How long a frame that hasn't loaded waits to be numbered (`waits`).
+const WAIT_MS = 3000;
+// A URL without its query and fragment.
+function bareUrl(url) {
+    return url.replace(/[?#].*$/, '');
+}
+/** `F3` or `T1.F3`: the frame's number, and the tab's if given. */
+export function parseFrameRef(text) {
+    const m = /^(?:[Tt](\d+)\.)?[Ff](\d+)$/.exec(text);
+    if (!m)
+        return null;
+    return { ...(m[1] !== undefined ? { tab: Number(m[1]) } : {}), frame: Number(m[2]) };
+}
+/** A page's iframes, each after its parent, with ids given to new ones. */
+export function frameNodes(page, ids) {
+    const out = [];
+    const walk = (parent, parentN, depth) => {
+        for (const frame of parent.childFrames()) {
+            if (frame.isDetached() || ids.waiting(frame))
+                continue;
+            const n = ids.number(frame);
+            out.push({ frame, n, parent: parentN, depth, url: frame.url() });
+            walk(frame, n, depth + 1);
+        }
+    };
+    if (!page.isClosed())
+        walk(page.mainFrame(), null, 1);
+    return out;
+}
+/** The iframe `F<n>` names in `page`, while it's there. */
+export function findFrame(page, ids, n) {
+    return frameNodes(page, ids).find((node) => node.n === n)?.frame;
+}
+/**
+ * Which of `nodes` each of the extension's frames is, by tree shape and
+ * URL: from the top down, a frame is its parent's child with the same
+ * URL. `known` (the last answer) goes first, so that of two sibling
+ * frames with one URL, each keeps its match.
+ *
+ * Returns the extension's frame ids mapped to the node keys. The top
+ * frame (frameId 0) maps to null.
+ */
+export function matchFrameTrees(frames, nodes, known = new Map()) {
+    const out = new Map();
+    if (!frames.some((f) => f.frameId === 0))
+        return out;
+    out.set(0, null);
+    const used = new Set();
+    // Down the tree a level at a time: a frame is placed once its parent is.
+    let level = frames.filter((f) => f.parentFrameId === 0);
+    while (level.length > 0) {
+        const placed = [];
+        // Siblings among nodes under the same parent, in order.
+        const free = (f) => {
+            const parent = out.get(f.parentFrameId);
+            return nodes.filter((n) => n.parent === parent && !used.has(n.key));
+        };
+        const sorted = level.filter((f) => out.has(f.parentFrameId)).sort((a, b) => a.frameId - b.frameId);
+        const take = (f, key) => {
+            out.set(f.frameId, key);
+            used.add(key);
+            placed.push(f);
+        };
+        for (const f of sorted) {
+            const was = known.get(f.frameId);
+            const match = free(f).find((n) => n.key === was && n.url === f.url);
+            if (match)
+                take(f, match.key);
+        }
+        for (const f of sorted) {
+            if (out.has(f.frameId))
+                continue;
+            const match = free(f).find((n) => n.url === f.url);
+            if (match)
+                take(f, match.key);
+        }
+        const ids = new Set(placed.map((f) => f.frameId));
+        level = frames.filter((f) => ids.has(f.parentFrameId));
+    }
+    return out;
+}

package/lib/harness/help-format.d.ts

@@ -0,0 +1,17 @@
+/** Text as a code span with no backticks in plain help: a list's term, a usage line. */
+export declare const quiet: (text: string) => string;
+/** Lays out lines for color or not, then paints them: one string, ending in a newline. */
+export declare function render(inColor: boolean, layout: () => string[]): string;
+/** How wide text shows. */
+export declare function visibleLength(text: string): number;
+/** Text padded with spaces to show `width` wide. */
+export declare function padTo(text: string, width: number): string;
+/** Text wrapped to `width`, by the width it shows. A span is never split. */
+export declare function wrap(text: string, width: number): string[];
+/**
+ * A line of text, wrapped to `width`. A bullet (`- `) or numbered item
+ * (`1. `), after any spaces of its own, wraps under its text. Any other
+ * line starting with spaces is a line of a code block, shown as is, two
+ * spaces further in.
+ */
+export declare function textLines(text: string, width: number): string[];