@jitsusama/agentic-harness.core 0.1.0

package/dist/web/snapshot/query.js

@@ -0,0 +1,136 @@
+/**
+ * Asking the flattened page questions.
+ *
+ * The queries here are the ones that cannot be asked any other
+ * way: how many of these are there, where are they, which ones
+ * are not rendered, what is inside that frame. A CSS selector
+ * run in the page answers some of this, but it answers it inside
+ * one document and it cannot see into a closed shadow root or
+ * across a frame boundary. The index can, because the browser
+ * already flattened all of it.
+ */
+/** Whether one node answers the query. */
+export function matches(node, query) {
+    if (query.tag && node.nodeName.toLowerCase() !== query.tag.toLowerCase()) {
+        return false;
+    }
+    if (query.attribute !== undefined) {
+        const held = node.attributes[query.attribute];
+        if (held === undefined)
+            return false;
+        if (query.value !== undefined && held !== query.value)
+            return false;
+    }
+    else if (query.value !== undefined) {
+        // A value with no attribute to hold it. This used to fall
+        // through every predicate and return the whole document,
+        // rendered as a real total with the first page of nodes under
+        // it: an authoritative-looking answer to a filter that was
+        // never applied, which is the worst way for a read tool to
+        // fail. Match any attribute carrying the value instead.
+        const anywhere = Object.values(node.attributes).includes(query.value);
+        if (!anywhere)
+            return false;
+    }
+    if (query.className !== undefined) {
+        const classes = (node.attributes.class ?? "").split(/\s+/);
+        if (!classes.includes(query.className))
+            return false;
+    }
+    if (query.text !== undefined) {
+        const has = (node.text ?? "")
+            .toLowerCase()
+            .includes(query.text.toLowerCase());
+        if (!has)
+            return false;
+    }
+    if (query.rendered !== undefined && node.rendered !== query.rendered) {
+        return false;
+    }
+    if (query.inShadow !== undefined && node.inShadow !== query.inShadow) {
+        return false;
+    }
+    if (query.clickable !== undefined && node.clickable !== query.clickable) {
+        return false;
+    }
+    if (query.documentUrl !== undefined &&
+        node.documentUrl !== query.documentUrl) {
+        return false;
+    }
+    return true;
+}
+/** Everything that answers the query, in document order. */
+export function find(nodes, query) {
+    return nodes.filter((node) => matches(node, query));
+}
+/**
+ * Count nodes by some property of them.
+ *
+ * A page with four hundred divs is not usefully listed, but it
+ * is usefully counted, and the counting is what tells you the
+ * listing would be a waste.
+ */
+export function tally(nodes, by) {
+    const counts = new Map();
+    for (const node of nodes) {
+        const key = by(node);
+        if (key === undefined)
+            continue;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([key, count]) => ({ key, count }))
+        .sort((a, b) => b.count - a.count || a.key.localeCompare(b.key));
+}
+/**
+ * How a node reads in a listing.
+ *
+ * The position says which space it is measured in. A snapshot
+ * measures down the document, while an element inspection reports
+ * the box model, which measures from the viewport. The same element
+ * on a scrolled page reads differently in each, and saying so is
+ * what stops the two being compared as though they agreed.
+ */
+export function describeNode(node) {
+    const tag = node.nodeName.toLowerCase();
+    const id = node.attributes.id ? `#${node.attributes.id}` : "";
+    const classes = node.attributes.class
+        ? `.${node.attributes.class.trim().split(/\s+/).join(".")}`
+        : "";
+    const where = node.bounds ? ` at ${place(node.bounds)} on the page` : "";
+    const notes = [
+        node.rendered ? "" : "not rendered",
+        node.inShadow ? "in shadow" : "",
+        node.clickable ? "clickable" : "",
+    ].filter(Boolean);
+    const tail = notes.length > 0 ? ` (${notes.join(", ")})` : "";
+    const words = node.text ? ` "${clip(node.text)}"` : "";
+    return `${tag}${id}${classes}${where}${tail}${words}`;
+}
+/**
+ * Say what a node's named properties compute to.
+ *
+ * A property the snapshot carries no value for is named rather than
+ * dropped. Leaving it out would read exactly like a property nobody
+ * asked about, and a caller would take the silence for a value.
+ */
+export function describeStyles(node, wanted) {
+    return wanted
+        .map((property) => {
+        const value = node.styles[property];
+        // An empty string is what the snapshot gives for a property
+        // the browser did not answer, so it is the same absence.
+        return `${property}: ${value ? value : "not reported"}`;
+    })
+        .join("; ");
+}
+/** How much of a text run is worth showing in a listing. */
+const MAX_TEXT = 40;
+function clip(text) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > MAX_TEXT ? `${flat.slice(0, MAX_TEXT)}...` : flat;
+}
+function place(bounds) {
+    return (`${Math.round(bounds.x)},${Math.round(bounds.y)} ` +
+        `${Math.round(bounds.width)}x${Math.round(bounds.height)}`);
+}

package/dist/web/sourcemap/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Telling a position in generated code where it was authored.
+ *
+ * The browser reports which map belongs to a script or a
+ * stylesheet and then leaves the resolving to whoever is asking,
+ * so this is the one corner of the library that decodes a format
+ * itself rather than deferring to a protocol call.
+ */
+export { type AuthoredPosition, authoredPosition, decodeMappings, decodeVlq, parseSourceMap, type RawSourceMap, readSourceMap, resolveMapUrl, type Segment, type SourceMap, } from "./mappings.js";

package/dist/web/sourcemap/index.js

@@ -0,0 +1,9 @@
+/**
+ * Telling a position in generated code where it was authored.
+ *
+ * The browser reports which map belongs to a script or a
+ * stylesheet and then leaves the resolving to whoever is asking,
+ * so this is the one corner of the library that decodes a format
+ * itself rather than deferring to a protocol call.
+ */
+export { authoredPosition, decodeMappings, decodeVlq, parseSourceMap, readSourceMap, resolveMapUrl, } from "./mappings.js";

package/dist/web/sourcemap/mappings.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Reading a source map, so a position in generated code can be
+ * told where it came from.
+ *
+ * This is the one place in the library that reimplements
+ * something rather than asking the browser, and the reason is
+ * that the browser does not do it either. Chrome ships the
+ * source map URL on Debugger.scriptParsed and CSS.styleSheetAdded
+ * and stops there; resolving a position through the map is work
+ * the devtools front end does for itself. There is no protocol
+ * call to defer to.
+ *
+ * The format is a v3 source map: a run of base64 VLQ segments,
+ * semicolons for generated lines, commas for segments within a
+ * line, and every field after the first stored as a delta from
+ * the previous segment.
+ */
+/** A source map as it arrives, before anything is decoded. */
+export interface RawSourceMap {
+    readonly version?: number;
+    readonly file?: string;
+    readonly sourceRoot?: string;
+    readonly sources: readonly (string | null)[];
+    readonly sourcesContent?: readonly (string | null)[];
+    readonly names?: readonly string[];
+    readonly mappings: string;
+}
+/** One decoded mapping segment. */
+export interface Segment {
+    /** Column in the generated file, zero based. */
+    readonly generatedColumn: number;
+    /** Index into the map's sources, absent for a bare segment. */
+    readonly sourceIndex?: number;
+    /** Line in the authored file, zero based. */
+    readonly sourceLine?: number;
+    /** Column in the authored file, zero based. */
+    readonly sourceColumn?: number;
+    /** Index into the map's names. */
+    readonly nameIndex?: number;
+}
+/** A source map with its mappings decoded, ready to query. */
+export interface SourceMap {
+    readonly sources: readonly string[];
+    readonly sourcesContent: readonly (string | null)[];
+    readonly names: readonly string[];
+    /** Segments per generated line, each sorted by column. */
+    readonly lines: readonly (readonly Segment[])[];
+}
+/** Where a generated position came from. */
+export interface AuthoredPosition {
+    readonly source: string;
+    /** Zero based, to match how the protocol counts. */
+    readonly line: number;
+    readonly column: number;
+    /** The authored name, when the map recorded one. */
+    readonly name?: string;
+    /** The authored source's text, when the map carried it. */
+    readonly content?: string;
+}
+/**
+ * Decode one comma-free run of base64 VLQ into its numbers.
+ *
+ * Returns nothing when the run contains a character outside the
+ * alphabet, since a partly decoded segment is worse than an
+ * absent one: it would point somewhere confidently wrong.
+ */
+export declare function decodeVlq(segment: string): number[] | undefined;
+/**
+ * Decode a whole mappings string into segments by generated line.
+ *
+ * Every field but the generated column carries across lines,
+ * which is why the running totals sit outside the line loop.
+ */
+export declare function decodeMappings(mappings: string): (readonly Segment[])[];
+/**
+ * Prepare a raw map for querying.
+ *
+ * The source root is folded into each source here rather than at
+ * lookup time, so every later answer is a path the caller can
+ * use without knowing the map existed.
+ */
+export declare function readSourceMap(raw: RawSourceMap): SourceMap;
+/**
+ * Find where a generated position was authored.
+ *
+ * A map records the positions a compiler thought worth marking,
+ * not every column, so a lookup takes the nearest mapping at or
+ * before the column asked for. That is what makes a stack frame
+ * pointing into the middle of a minified expression resolve to
+ * the statement it belongs to.
+ */
+export declare function authoredPosition(map: SourceMap, generated: {
+    readonly line: number;
+    readonly column: number;
+}): AuthoredPosition | undefined;
+/**
+ * Work out where a map lives, given the file that named it.
+ *
+ * A map URL is usually relative to the file that references it,
+ * and is sometimes the map itself inlined as a data URL, which
+ * needs no fetching at all.
+ */
+export declare function resolveMapUrl(fileUrl: string, sourceMapUrl: string): {
+    readonly kind: "inline";
+    readonly json: string;
+} | {
+    readonly kind: "fetch";
+    readonly url: string;
+} | undefined;
+/** Read a map's JSON, refusing anything that is not one. */
+export declare function parseSourceMap(json: string): SourceMap | undefined;

package/dist/web/sourcemap/mappings.js

@@ -0,0 +1,218 @@
+/**
+ * Reading a source map, so a position in generated code can be
+ * told where it came from.
+ *
+ * This is the one place in the library that reimplements
+ * something rather than asking the browser, and the reason is
+ * that the browser does not do it either. Chrome ships the
+ * source map URL on Debugger.scriptParsed and CSS.styleSheetAdded
+ * and stops there; resolving a position through the map is work
+ * the devtools front end does for itself. There is no protocol
+ * call to defer to.
+ *
+ * The format is a v3 source map: a run of base64 VLQ segments,
+ * semicolons for generated lines, commas for segments within a
+ * line, and every field after the first stored as a delta from
+ * the previous segment.
+ */
+const BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const CHAR_VALUES = new Map([...BASE64].map((char, value) => [char, value]));
+/** The low bit of a decoded VLQ carries the sign, not magnitude. */
+const SIGN_BIT = 1;
+/** Five bits of payload per character, the sixth is continuation. */
+const PAYLOAD_BITS = 5;
+const CONTINUATION = 1 << PAYLOAD_BITS;
+const PAYLOAD_MASK = CONTINUATION - 1;
+/**
+ * Decode one comma-free run of base64 VLQ into its numbers.
+ *
+ * Returns nothing when the run contains a character outside the
+ * alphabet, since a partly decoded segment is worse than an
+ * absent one: it would point somewhere confidently wrong.
+ */
+export function decodeVlq(segment) {
+    const values = [];
+    let accumulated = 0;
+    let shift = 0;
+    for (const char of segment) {
+        const digit = CHAR_VALUES.get(char);
+        if (digit === undefined)
+            return undefined;
+        accumulated += (digit & PAYLOAD_MASK) << shift;
+        if (digit & CONTINUATION) {
+            shift += PAYLOAD_BITS;
+            continue;
+        }
+        const negative = (accumulated & SIGN_BIT) === SIGN_BIT;
+        const magnitude = accumulated >> 1;
+        values.push(negative ? -magnitude : magnitude);
+        accumulated = 0;
+        shift = 0;
+    }
+    // A trailing continuation means the run ended mid-number.
+    return shift === 0 ? values : undefined;
+}
+/**
+ * Decode a whole mappings string into segments by generated line.
+ *
+ * Every field but the generated column carries across lines,
+ * which is why the running totals sit outside the line loop.
+ */
+export function decodeMappings(mappings) {
+    const lines = [];
+    let sourceIndex = 0;
+    let sourceLine = 0;
+    let sourceColumn = 0;
+    let nameIndex = 0;
+    for (const rawLine of mappings.split(";")) {
+        const segments = [];
+        // The generated column restarts at every line, unlike the rest.
+        let generatedColumn = 0;
+        for (const rawSegment of rawLine.split(",")) {
+            if (rawSegment === "")
+                continue;
+            const fields = decodeVlq(rawSegment);
+            if (!fields || fields.length === 0)
+                continue;
+            generatedColumn += fields[0] ?? 0;
+            if (fields.length < 4) {
+                // A one-field segment marks generated code with no
+                // authored origin at all, which is a real answer.
+                segments.push({ generatedColumn });
+                continue;
+            }
+            sourceIndex += fields[1] ?? 0;
+            sourceLine += fields[2] ?? 0;
+            sourceColumn += fields[3] ?? 0;
+            if (fields.length > 4)
+                nameIndex += fields[4] ?? 0;
+            segments.push({
+                generatedColumn,
+                sourceIndex,
+                sourceLine,
+                sourceColumn,
+                ...(fields.length > 4 ? { nameIndex } : {}),
+            });
+        }
+        segments.sort((a, b) => a.generatedColumn - b.generatedColumn);
+        lines.push(segments);
+    }
+    return lines;
+}
+/**
+ * Prepare a raw map for querying.
+ *
+ * The source root is folded into each source here rather than at
+ * lookup time, so every later answer is a path the caller can
+ * use without knowing the map existed.
+ */
+export function readSourceMap(raw) {
+    const root = raw.sourceRoot ?? "";
+    return {
+        sources: raw.sources.map((source) => {
+            const named = source ?? "(anonymous)";
+            if (root === "")
+                return named;
+            return `${root.replace(/\/$/, "")}/${named.replace(/^\//, "")}`;
+        }),
+        sourcesContent: raw.sourcesContent ?? [],
+        names: raw.names ?? [],
+        lines: decodeMappings(raw.mappings),
+    };
+}
+/**
+ * Find where a generated position was authored.
+ *
+ * A map records the positions a compiler thought worth marking,
+ * not every column, so a lookup takes the nearest mapping at or
+ * before the column asked for. That is what makes a stack frame
+ * pointing into the middle of a minified expression resolve to
+ * the statement it belongs to.
+ */
+export function authoredPosition(map, generated) {
+    const segments = map.lines[generated.line];
+    if (!segments || segments.length === 0)
+        return undefined;
+    let found;
+    for (const segment of segments) {
+        if (segment.generatedColumn > generated.column)
+            break;
+        found = segment;
+    }
+    // Before the first mapping on the line there is nothing to say.
+    if (!found || found.sourceIndex === undefined)
+        return undefined;
+    const source = map.sources[found.sourceIndex];
+    if (source === undefined)
+        return undefined;
+    const content = map.sourcesContent[found.sourceIndex];
+    const name = found.nameIndex === undefined ? undefined : map.names[found.nameIndex];
+    return {
+        source,
+        line: found.sourceLine ?? 0,
+        column: found.sourceColumn ?? 0,
+        ...(name === undefined ? {} : { name }),
+        ...(content === undefined || content === null ? {} : { content }),
+    };
+}
+/**
+ * Work out where a map lives, given the file that named it.
+ *
+ * A map URL is usually relative to the file that references it,
+ * and is sometimes the map itself inlined as a data URL, which
+ * needs no fetching at all.
+ */
+export function resolveMapUrl(fileUrl, sourceMapUrl) {
+    if (sourceMapUrl.startsWith("data:")) {
+        const comma = sourceMapUrl.indexOf(",");
+        if (comma < 0)
+            return undefined;
+        const meta = sourceMapUrl.slice(0, comma);
+        const payload = sourceMapUrl.slice(comma + 1);
+        // Both branches are guarded, not just the base64 one. A
+        // sourceMappingURL is written by the page, so a stray percent
+        // sign in a plain-text inline map is page input, and
+        // decodeURIComponent throws a URIError on it. That escaped a
+        // function whose own comment promised a malformed data URL
+        // was not worth a thrown error.
+        try {
+            return {
+                kind: "inline",
+                json: meta.includes(";base64")
+                    ? Buffer.from(payload, "base64").toString("utf8")
+                    : decodeURIComponent(payload),
+            };
+        }
+        catch {
+            // The caller simply reports the generated position instead.
+            return undefined;
+        }
+    }
+    try {
+        return { kind: "fetch", url: new URL(sourceMapUrl, fileUrl).toString() };
+    }
+    catch {
+        // Relative resolution fails when the file URL is not a URL,
+        // which happens for eval'd script with no origin.
+        return undefined;
+    }
+}
+/** Read a map's JSON, refusing anything that is not one. */
+export function parseSourceMap(json) {
+    try {
+        const raw = JSON.parse(json);
+        if (typeof raw !== "object" ||
+            raw === null ||
+            !("mappings" in raw) ||
+            typeof raw.mappings !== "string" ||
+            !Array.isArray(raw.sources)) {
+            return undefined;
+        }
+        return readSourceMap(raw);
+    }
+    catch {
+        // Not JSON at all, which usually means the map URL 404'd and
+        // a server returned an HTML error page.
+        return undefined;
+    }
+}

package/dist/web/styles/capture.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Asking the browser for style facts.
+ *
+ * These are page sources rather than functions, for the same
+ * reason the accessibility observer is: the compiler wraps
+ * named inner bindings in a __name helper the page has never
+ * heard of, so a serialized function that declares helpers of
+ * its own throws on arrival. Source text survives untouched.
+ *
+ * They exist so that nothing in this domain has to restate what
+ * a browser already computes. CSS knowledge written down here
+ * would drift from the engine it claims to describe.
+ */
+/**
+ * Shorthands worth reading in place of the sides they cover.
+ *
+ * A computed-style enumeration yields longhands only, so a
+ * capture has to ask for these by name. The browser serializes
+ * them, which is why curation never composes one itself.
+ */
+export declare const SHORTHAND_PROPERTIES: readonly string[];
+/**
+ * Read every computed property of an element, plus the
+ * shorthands the enumeration leaves out.
+ *
+ * A function declaration, to be invoked with the element as its
+ * receiver: Runtime.callFunctionOn with the element's objectId.
+ */
+export declare const COMPUTED_STYLE_PROBE = "function (shorthands) {\n  var styles = getComputedStyle(this);\n  var out = {};\n  for (var i = 0; i < styles.length; i++) {\n    var name = styles[i];\n    out[name] = styles.getPropertyValue(name);\n  }\n  for (var j = 0; j < shorthands.length; j++) {\n    out[shorthands[j]] = styles.getPropertyValue(shorthands[j]);\n  }\n  return out;\n}";
+/**
+ * Read what every property computes to when nobody has set it.
+ *
+ * An element with all:initial reports the engine's own initial
+ * values, which is the honest answer to "was this touched".
+ * The element has to be in the document to have a computed
+ * style at all, so it is added and taken away again within the
+ * one evaluation, before anything can paint. It is left empty
+ * and otherwise unstyled: hiding it would report display none
+ * as the initial display and suppress that property everywhere.
+ *
+ * A function expression, to be invoked through asCall.
+ */
+export declare const INITIALS_PROBE = "(function (shorthands) {\n  var host = document.createElement(\"div\");\n  host.style.setProperty(\"all\", \"initial\");\n  document.documentElement.appendChild(host);\n  var styles = getComputedStyle(host);\n  var out = {};\n  for (var i = 0; i < styles.length; i++) {\n    var name = styles[i];\n    out[name] = styles.getPropertyValue(name);\n  }\n  for (var j = 0; j < shorthands.length; j++) {\n    out[shorthands[j]] = styles.getPropertyValue(shorthands[j]);\n  }\n  host.remove();\n  return out;\n})";
+/**
+ * Turn a function-expression source into an expression that
+ * calls it, for protocols that evaluate an expression rather
+ * than invoke a function.
+ */
+export declare function asCall(source: string, ...args: readonly unknown[]): string;

package/dist/web/styles/capture.js

@@ -0,0 +1,85 @@
+/**
+ * Asking the browser for style facts.
+ *
+ * These are page sources rather than functions, for the same
+ * reason the accessibility observer is: the compiler wraps
+ * named inner bindings in a __name helper the page has never
+ * heard of, so a serialized function that declares helpers of
+ * its own throws on arrival. Source text survives untouched.
+ *
+ * They exist so that nothing in this domain has to restate what
+ * a browser already computes. CSS knowledge written down here
+ * would drift from the engine it claims to describe.
+ */
+/**
+ * Shorthands worth reading in place of the sides they cover.
+ *
+ * A computed-style enumeration yields longhands only, so a
+ * capture has to ask for these by name. The browser serializes
+ * them, which is why curation never composes one itself.
+ */
+export const SHORTHAND_PROPERTIES = [
+    "margin",
+    "padding",
+    "inset",
+    "border-width",
+    "border-style",
+    "border-color",
+];
+/**
+ * Read every computed property of an element, plus the
+ * shorthands the enumeration leaves out.
+ *
+ * A function declaration, to be invoked with the element as its
+ * receiver: Runtime.callFunctionOn with the element's objectId.
+ */
+export const COMPUTED_STYLE_PROBE = `function (shorthands) {
+  var styles = getComputedStyle(this);
+  var out = {};
+  for (var i = 0; i < styles.length; i++) {
+    var name = styles[i];
+    out[name] = styles.getPropertyValue(name);
+  }
+  for (var j = 0; j < shorthands.length; j++) {
+    out[shorthands[j]] = styles.getPropertyValue(shorthands[j]);
+  }
+  return out;
+}`;
+/**
+ * Read what every property computes to when nobody has set it.
+ *
+ * An element with all:initial reports the engine's own initial
+ * values, which is the honest answer to "was this touched".
+ * The element has to be in the document to have a computed
+ * style at all, so it is added and taken away again within the
+ * one evaluation, before anything can paint. It is left empty
+ * and otherwise unstyled: hiding it would report display none
+ * as the initial display and suppress that property everywhere.
+ *
+ * A function expression, to be invoked through asCall.
+ */
+export const INITIALS_PROBE = `(function (shorthands) {
+  var host = document.createElement("div");
+  host.style.setProperty("all", "initial");
+  document.documentElement.appendChild(host);
+  var styles = getComputedStyle(host);
+  var out = {};
+  for (var i = 0; i < styles.length; i++) {
+    var name = styles[i];
+    out[name] = styles.getPropertyValue(name);
+  }
+  for (var j = 0; j < shorthands.length; j++) {
+    out[shorthands[j]] = styles.getPropertyValue(shorthands[j]);
+  }
+  host.remove();
+  return out;
+})`;
+/**
+ * Turn a function-expression source into an expression that
+ * calls it, for protocols that evaluate an expression rather
+ * than invoke a function.
+ */
+export function asCall(source, ...args) {
+    const call = args.map((arg) => JSON.stringify(arg)).join(", ");
+    return `(${source})(${call})`;
+}