@descryy/mcp 0.11.5 → 0.11.6

package/dist/browser/page-probe.js

@@ -0,0 +1,202 @@
+/**
+ * The in-page half of the capability probe: one function, serialized into the
+ * page, that counts the shapes `capability-probe.ts` turns into a reach
+ * estimate.
+ *
+ * ## Why it lives here and not in the driver
+ *
+ * `playwright-driver.ts` is one lane's file and this is another's. Keeping the
+ * probe body here means the driver gains a six-line delegating method rather
+ * than two hundred lines of DOM walking, which is the difference between a
+ * mergeable change and a rewritten file.
+ *
+ * ## Structural DOM types, again, and why
+ *
+ * `tsc` omits the DOM lib on purpose repo-wide — pulling it in would put
+ * `document` and `window` in scope in every engine file. The driver already
+ * declares the minimum it needs for `computeSelector`; this declares the
+ * minimum the probe needs. Both are structural, both are checked by the
+ * compiler, and neither leaks browser globals into modules that have no
+ * business with them.
+ *
+ * ## Every count is defensive, and an uncountable thing is null, never zero
+ *
+ * A probe that throws takes the session's opening disclosure with it, and a
+ * probe that reports `0` for something it could not look at teaches a false
+ * fact — which is the failure the five result states exist to prevent, applied
+ * one level down. So each group is wrapped, and `clientSideRouting` is
+ * `boolean | null` because a static probe genuinely cannot see it.
+ */
+/** Same list the snapshot enumerates. Duplicated deliberately rather than
+ *  imported: the driver's constant is that lane's to change, and a probe that
+ *  silently followed it would report a different page than the one that moved. */
+const INTERACTIVE = "a, button, input, select, textarea, [role], [onclick], summary";
+/**
+ * Selectors a human-verification challenge leaves behind. Detection only —
+ * §4's "out of scope, deliberately": these are things to disclose, never to
+ * defeat. Matching is on markup a widget publishes about itself, so a false
+ * positive costs one over-cautious disclosure and never a bypass attempt.
+ */
+const CHALLENGE_MARKERS = [
+    ['[data-sitekey]', "a challenge widget declaring a site key"],
+    ['iframe[title*="captcha" i]', "a challenge frame"],
+    ['iframe[src*="captcha" i]', "a challenge frame"],
+    ['iframe[title*="challenge" i]', "a challenge frame"],
+    ['[class*="captcha" i]', "an element marked as a challenge"],
+    ['[id*="captcha" i]', "an element marked as a challenge"],
+    ['form[action*="challenge" i]', "a challenge form"],
+];
+/** Below this, a scrollable box is a scrollbar artefact rather than a windowed list. */
+const SCROLL_OVERFLOW_RATIO = 1.5;
+/** Share of the viewport a fixed element must cover to be an overlay rather than a header. */
+const OVERLAY_COVERS = 0.4;
+/**
+ * Runs inside the page. Must not close over anything in this module — it is
+ * serialized, so every constant it uses is passed in.
+ */
+export function probeInPage(root, constants) {
+    const doc = root.ownerDocument;
+    const count = (selector, scope) => {
+        try {
+            return scope.querySelectorAll(selector).length;
+        }
+        catch {
+            return 0;
+        }
+    };
+    let openShadowRoots = 0;
+    let shadowInteractive = 0;
+    try {
+        const all = doc.querySelectorAll("*");
+        for (let i = 0; i < all.length; i += 1) {
+            const shadow = all[i]?.shadowRoot ?? null;
+            if (shadow === null)
+                continue;
+            openShadowRoots += 1;
+            shadowInteractive += count(constants.interactive, shadow);
+        }
+    }
+    catch {
+        // A page that refuses a full-document walk keeps its other counts.
+    }
+    let childFrames = 0;
+    let crossOriginChildFrames = 0;
+    try {
+        const frames = doc.querySelectorAll("iframe, frame");
+        childFrames = frames.length;
+        for (let i = 0; i < frames.length; i += 1) {
+            const src = frames[i]?.getAttribute("src") ?? "";
+            if (src === "" || src.startsWith("about:"))
+                continue;
+            try {
+                if (new URL(src, doc.location.href).origin !== doc.location.origin)
+                    crossOriginChildFrames += 1;
+            }
+            catch {
+                // An unparseable src is not evidence of another origin; leave it uncounted.
+            }
+        }
+    }
+    catch {
+        // Leave both at 0 rather than guessing one from the other.
+    }
+    let scrollableRegions = 0;
+    try {
+        const all = doc.querySelectorAll("div, ul, ol, section, main, table, tbody");
+        for (let i = 0; i < all.length; i += 1) {
+            const el = all[i];
+            if (el === undefined)
+                continue;
+            if (el.clientHeight > 0 && el.scrollHeight > el.clientHeight * constants.scrollOverflowRatio)
+                scrollableRegions += 1;
+        }
+    }
+    catch {
+        // ditto
+    }
+    const view = doc.defaultView;
+    const viewport = view === null ? 0 : view.innerWidth * view.innerHeight;
+    let canvasViewportShare = 0;
+    let largestCanvasArea = 0;
+    try {
+        const canvases = doc.querySelectorAll("canvas");
+        for (let i = 0; i < canvases.length; i += 1) {
+            const box = canvases[i]?.getBoundingClientRect();
+            if (box === undefined)
+                continue;
+            const area = box.width * box.height;
+            largestCanvasArea = Math.max(largestCanvasArea, area);
+            if (viewport > 0)
+                canvasViewportShare = Math.max(canvasViewportShare, area / viewport);
+        }
+    }
+    catch {
+        // ditto
+    }
+    // An overlay is the state this probe is most dangerous in when it misses it:
+    // the app beneath a consent banner is fully enumerable and entirely
+    // unclickable, so a `full` estimate there is the most misleading answer
+    // available. Measured on the corpus, the share rule alone missed both.
+    let fixedOverlays = 0;
+    try {
+        if (view !== null && viewport > 0) {
+            const candidates = doc.querySelectorAll("div, section, aside, dialog, header, footer, nav");
+            for (let i = 0; i < candidates.length; i += 1) {
+                const el = candidates[i];
+                if (el === undefined)
+                    continue;
+                const position = view.getComputedStyle(el).position;
+                if (position !== "fixed" && position !== "sticky")
+                    continue;
+                const box = el.getBoundingClientRect();
+                if ((box.width * box.height) / viewport >= constants.overlayCovers)
+                    fixedOverlays += 1;
+            }
+        }
+    }
+    catch {
+        // ditto
+    }
+    const markers = [];
+    for (const [selector, description] of constants.challengeMarkers) {
+        if (count(selector, doc) > 0 && !markers.includes(description))
+            markers.push(description);
+    }
+    const scrollHeight = doc.documentElement?.scrollHeight ?? 0;
+    const innerHeight = view?.innerHeight ?? 0;
+    return {
+        url: doc.location.href,
+        interactiveElements: count(constants.interactive, doc) + shadowInteractive,
+        openShadowRoots,
+        shadowInteractiveElements: shadowInteractive,
+        childFrames,
+        crossOriginChildFrames,
+        scrollableRegions,
+        canvasViewportShare,
+        largestCanvasArea,
+        fixedOverlays,
+        // `inert` is a reflected boolean attribute, so a subtree marked from script
+        // is visible here — which is why this is an attribute query and not a
+        // property walk.
+        inertSubtrees: count("[inert]", doc),
+        openModalDialogs: count("dialog[open]", doc),
+        passwordFields: count('input[type="password"]', doc),
+        // The standard attribute and nothing else. A name- or placeholder-based
+        // guess would put a wall in front of every page with a field called "code",
+        // and a wall is now a session-level claim rather than a hint.
+        oneTimeCodeFields: count('input[autocomplete="one-time-code"]', doc),
+        challengeMarkers: markers,
+        // A single static look cannot tell a routed application from a server-rendered
+        // one. Null is that fact; `false` would be a claim nothing supports.
+        clientSideRouting: null,
+        documentHeightRatio: innerHeight > 0 ? scrollHeight / innerHeight : 1,
+    };
+}
+/** The constants `probeInPage` must be handed, since it cannot close over them. */
+export const PROBE_CONSTANTS = {
+    interactive: INTERACTIVE,
+    challengeMarkers: CHALLENGE_MARKERS,
+    scrollOverflowRatio: SCROLL_OVERFLOW_RATIO,
+    overlayCovers: OVERLAY_COVERS,
+};
+//# sourceMappingURL=page-probe.js.map

package/dist/browser/page-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-probe.js","sourceRoot":"","sources":["../../src/browser/page-probe.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,115 @@
+/**
+ * The real `BrowserDriver`, over `@descryy/runtime-browser`. Import stays
+ * dynamic — `loadRuntimeModule` is a test injection seam (fake module, no
+ * browser needed). Adds only element refs over the runtime; stack-trace parsing is caller-supplied (rule 1: no language named here).
+ */
+import type { StackTrace, ServiceRootLookup } from "@descryy/runtime-contracts";
+import type { StackTraceParser } from "@descryy/runtime-backend-observation";
+/** DOM surface used by the in-page callback; `tsc` omits the DOM lib on purpose (would put `document`/`window` in scope repo-wide). `PageQueryable` is the shared shape `computeSelector` needs to verify a candidate is unique. */
+interface PageQueryable {
+    querySelectorAll(selector: string): {
+        readonly length: number;
+        item(index: number): PageElement | null;
+    };
+}
+interface PageElement extends PageQueryable {
+    readonly tagName: string;
+    readonly innerText?: string;
+    readonly textContent: string | null;
+    getAttribute(name: string): string | null;
+    readonly parentElement: PageElement | null;
+    readonly ownerDocument: PageQueryable;
+    /** The `Document` for a light-DOM element, the `ShadowRoot` for one inside an open shadow
+     *  root — the only in-page way to tell the two apart, and the right scope for a uniqueness
+     *  check (`ownerDocument` is the *document* even for a shadow child, where it matches nothing). */
+    getRootNode?(): PageRoot;
+    /** Present only on an open shadow host. Null for a closed root **and** for no root at all —
+     *  the ambiguity that makes a closed root undetectable rather than merely unread. */
+    readonly shadowRoot?: PageQueryable | null;
+    readonly childElementCount?: number;
+    /** Present on a chooser, absent everywhere else — which is exactly the test `select` needs. */
+    readonly options?: ArrayLike<{
+        readonly value: string;
+        readonly label: string;
+        readonly text: string;
+    }>;
+    /** The owning form, for `submit`. Null when the element is in none, a real and common shape. */
+    closest?(selector: string): PageFormElement | null;
+    readonly disabled?: boolean;
+    /** The browser's own answer to "are you rendering this". It is **not** a viewport test: an
+     *  element below the fold answers true, which is what the reveal pass depends on. Optional
+     *  because an older backend may not have it; `renderedState` falls back rather than guessing.
+     *  An option the browser does not know is ignored, so this degrades to the display-only
+     *  answer instead of throwing — less filtering, never more. */
+    checkVisibility?(options?: {
+        visibilityProperty?: boolean;
+    }): boolean;
+    /** Every box the page lays out for this element. Zero of them means it lays out none. */
+    getClientRects?(): {
+        readonly length: number;
+    };
+}
+/** A `Document` or a `ShadowRoot`. `host` is what distinguishes them: only a shadow root has one. */
+interface PageRoot extends PageQueryable {
+    readonly host?: PageElement | null;
+}
+/** The form members `submit` uses. `requestSubmit` rather than `submit()`: it fires the page's
+ *  own submit handler and runs the form's validation, which `submit()` skips — so a page that
+ *  refuses an invalid form refuses here too, instead of being driven past its own guard. */
+interface PageFormElement {
+    querySelector(selector: string): unknown;
+    requestSubmit(submitter?: unknown): void;
+}
+import type { BrowserDriver, BrowserObservation, ObservedAction, UnsettledAction } from "./driver.ts";
+export interface PlaywrightDriverOptions {
+    /** Turns a raw stack into resolved frames; caller-supplied (rule 1: no language named here). Absent, initiator capture isn't installed and no R4 caller edge is written. */
+    readonly stackParser?: StackTraceParser;
+    /** Maps a page origin to the on-disk root that served it. Absent means script URLs stay unresolved. */
+    readonly resolveSourceRoot?: SourceRootResolver;
+    /** Which service the evidence is attributed to. */
+    readonly service?: string;
+    /** Loads the runtime browser module; overridable because the settle logic below is timing-dependent and this build has no browser backend to test it against otherwise. Keep narrow — do not export `openSession` instead. */
+    readonly loadRuntimeModule?: () => Promise<unknown>;
+    /**
+     * Ground each snapshot element's producing component, additive to role+name (B1). Off by
+     * default: it installs a page-side probe before first navigation and costs one
+     * `page.evaluate` per element with a selector, on every snapshot.
+     */
+    readonly groundIdentity?: boolean;
+    /** Loads the identity-grounding module; overridable for the same reason `loadRuntimeModule` is. */
+    readonly loadIdentityGroundingModule?: () => Promise<unknown>;
+}
+type SourceRootResolver = (origin: string) => ServiceRootLookup;
+/** What `describeElement` decides about one element. `rendered` is three-valued on purpose:
+ *  `null` is "nothing here could answer", which is a different fact from "answered no" and
+ *  must not be read as either (rule 7). */
+export interface DescribedElement {
+    readonly role: string;
+    readonly name: string;
+    readonly selector: string | null;
+    readonly inShadowRoot: boolean;
+    readonly rendered: boolean | null;
+}
+/** What one element looks like from inside the page. Serialized and run there, so it closes over
+ *  nothing in this module — every helper it needs is declared inside it.
+ *
+ *  Exported for `browser-element-describe.test.ts`: role, name and renderedness are pure
+ *  functions of one element, and pinning their decision table should not need a browser. */
+export declare function describeElement(el: PageElement): DescribedElement;
+export declare class BrowserBackendMissingError extends Error {
+    constructor(cause: unknown);
+}
+/** `Evidence`-shaped record (typed structurally; only 4 fields are read). Exported for `browser-request-outcome-mapping.test.ts` — regression test for B3, where `outcome` shipped never populated despite passing tests. */
+export interface EmittedEvidence {
+    readonly eventType: string;
+    readonly payload: Record<string, unknown>;
+    readonly stackTrace: StackTrace | null;
+    readonly requestId: string | null;
+    readonly timestamp: string;
+}
+export declare function disposeSharedPlaywrightBrowsers(): Promise<void>;
+export declare function createPlaywrightBrowserDriver(options?: PlaywrightDriverOptions): Promise<BrowserDriver>;
+/** Turns collector evidence into the port's vocabulary. Joins request/response on `requestId`, keeping `status: null` (not guessed) when unanswered. Exported for `browser-request-outcome-mapping.test.ts`. */
+export declare function collect(emitted: readonly EmittedEvidence[], actions: readonly ObservedAction[], unsettled: readonly UnsettledAction[]): BrowserObservation;
+export {};
+//# sourceMappingURL=playwright-driver.d.ts.map

package/dist/browser/playwright-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-driver.d.ts","sourceRoot":"","sources":["../../src/browser/playwright-driver.ts"],"names":[],"mappings":"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"}