@jitsusama/agentic-harness.core 0.1.0

package/dist/web/environment/devices.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Turning a device name into something to emulate.
+ *
+ * The catalogue of devices is Chrome's own, which arrives through
+ * puppeteer and so cannot be imported here: this module is on the
+ * pure side of the library and must stay loadable without a
+ * browser. So the catalogue is a parameter. The caller that has
+ * one passes it; the tests pass a small one and can describe
+ * devices that do not exist.
+ *
+ * This lived in the extension, where it worked, and left
+ * `EmulationState.device` as a field the library accepted and
+ * ignored. A consumer asking the library for an iPhone got no
+ * phone, no error and no divergence: the viewport stayed at
+ * 800x600 while the report echoed the device name back as though
+ * it had been honoured. A field that lies is worse than a field
+ * that is missing, and this is meant to be a library other
+ * packages build on.
+ */
+import type { EmulationState } from "./emulation.js";
+/**
+ * The shape this needs from a device catalogue.
+ *
+ * Deliberately narrower than what puppeteer's KnownDevices
+ * provides, so that the widest possible range of catalogues
+ * satisfies it, including one written by hand in a test.
+ */
+export interface DeviceProfile {
+    readonly userAgent?: string;
+    readonly viewport: {
+        readonly width: number;
+        readonly height: number;
+        readonly deviceScaleFactor?: number;
+        readonly isMobile?: boolean;
+        readonly hasTouch?: boolean;
+    };
+}
+/** A set of device profiles by name, as Chrome ships them. */
+export type DeviceCatalogue = Readonly<Record<string, DeviceProfile>>;
+/**
+ * What emulating a named device means, or undefined if unknown.
+ *
+ * Only the fields the device itself determines are returned, so a
+ * caller can layer it under an explicit request and let the
+ * explicit one win.
+ */
+export declare function deviceEmulation(name: string, catalogue: DeviceCatalogue): EmulationState | undefined;
+/**
+ * Device names close enough to what was asked for to be worth
+ * offering back.
+ *
+ * A wrong model number is the likeliest way to miss, so a failed
+ * match on the whole string falls back to the family name: asking
+ * for an "iPhone 99" should still hear about the iPhones rather
+ * than nothing at all.
+ */
+export declare function nearestDevices(name: string, catalogue: DeviceCatalogue): readonly string[];
+/**
+ * Say that a device could not be found, and what was nearby.
+ *
+ * Written once here because both the tool, which refuses before
+ * doing anything, and the library, which reports it as a
+ * divergence, have to say the same thing.
+ */
+export declare function noSuchDevice(name: string, catalogue: DeviceCatalogue): string;

package/dist/web/environment/devices.js

@@ -0,0 +1,82 @@
+/**
+ * Turning a device name into something to emulate.
+ *
+ * The catalogue of devices is Chrome's own, which arrives through
+ * puppeteer and so cannot be imported here: this module is on the
+ * pure side of the library and must stay loadable without a
+ * browser. So the catalogue is a parameter. The caller that has
+ * one passes it; the tests pass a small one and can describe
+ * devices that do not exist.
+ *
+ * This lived in the extension, where it worked, and left
+ * `EmulationState.device` as a field the library accepted and
+ * ignored. A consumer asking the library for an iPhone got no
+ * phone, no error and no divergence: the viewport stayed at
+ * 800x600 while the report echoed the device name back as though
+ * it had been honoured. A field that lies is worse than a field
+ * that is missing, and this is meant to be a library other
+ * packages build on.
+ */
+/** How many near matches are worth offering. */
+const MAX_SUGGESTIONS = 5;
+/**
+ * What emulating a named device means, or undefined if unknown.
+ *
+ * Only the fields the device itself determines are returned, so a
+ * caller can layer it under an explicit request and let the
+ * explicit one win.
+ */
+export function deviceEmulation(name, catalogue) {
+    const profile = catalogue[name];
+    if (!profile)
+        return undefined;
+    return {
+        device: name,
+        viewport: {
+            width: profile.viewport.width,
+            height: profile.viewport.height,
+            deviceScaleFactor: profile.viewport.deviceScaleFactor ?? 1,
+            mobile: profile.viewport.isMobile ?? false,
+        },
+        touch: profile.viewport.hasTouch ?? false,
+        // Half of what makes a site serve its phone layout is the
+        // string it is asked in. Emulating the screen and not the
+        // user agent meant a phone that every server still took for
+        // a desktop, so the page under test was often not the page a
+        // phone would get.
+        ...(profile.userAgent ? { userAgent: profile.userAgent } : {}),
+    };
+}
+/**
+ * Device names close enough to what was asked for to be worth
+ * offering back.
+ *
+ * A wrong model number is the likeliest way to miss, so a failed
+ * match on the whole string falls back to the family name: asking
+ * for an "iPhone 99" should still hear about the iPhones rather
+ * than nothing at all.
+ */
+export function nearestDevices(name, catalogue) {
+    const asked = name.toLowerCase();
+    const names = Object.keys(catalogue);
+    const holds = (needle) => names.filter((candidate) => candidate.toLowerCase().includes(needle));
+    const direct = holds(asked);
+    if (direct.length > 0)
+        return direct.slice(0, MAX_SUGGESTIONS);
+    const family = asked.split(" ")[0] ?? asked;
+    return holds(family).slice(0, MAX_SUGGESTIONS);
+}
+/**
+ * Say that a device could not be found, and what was nearby.
+ *
+ * Written once here because both the tool, which refuses before
+ * doing anything, and the library, which reports it as a
+ * divergence, have to say the same thing.
+ */
+export function noSuchDevice(name, catalogue) {
+    const near = nearestDevices(name, catalogue);
+    return (`No device named '${name}'.` +
+        (near.length > 0
+            ? ` Did you mean ${near.join(", ")}?`
+            : " Chrome ships names like 'iPhone 15 Pro' and 'Pixel 5'."));
+}

package/dist/web/environment/emulation.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Pretending to be a different visitor.
+ *
+ * Two measured facts shape everything here. Chrome's media
+ * emulation is a replacement, not a merge: sending one feature
+ * silently clears every other, so the session keeps the whole
+ * intent and re-sends all of it each time. And several
+ * overrides only partly land, notably locale, which changes
+ * how dates format without ever reaching navigator.language.
+ * So nothing here reports what it asked for; it reports what
+ * the page turned out to observe, and says where the two
+ * disagree.
+ */
+/** Sight conditions Chrome can simulate. */
+export type VisionDeficiency = "none" | "achromatopsia" | "blurredVision" | "deuteranopia" | "protanopia" | "tritanopia" | "reducedContrast";
+/** What we have asked the browser to pretend. */
+export interface EmulationState {
+    readonly colorScheme?: "light" | "dark";
+    readonly reducedMotion?: boolean;
+    readonly contrast?: "more" | "less" | "no-preference";
+    readonly forcedColors?: boolean;
+    readonly media?: "screen" | "print";
+    readonly vision?: VisionDeficiency;
+    readonly device?: string;
+    readonly viewport?: {
+        readonly width: number;
+        readonly height: number;
+        readonly deviceScaleFactor?: number;
+        readonly mobile?: boolean;
+    };
+    readonly touch?: boolean;
+    /** What to answer when the page or a server asks who it is. */
+    readonly userAgent?: string;
+    readonly timezone?: string;
+    readonly locale?: string;
+    readonly cpuThrottle?: number;
+    readonly geolocation?: {
+        readonly latitude: number;
+        readonly longitude: number;
+        readonly accuracy?: number;
+    };
+}
+/** What the page says it is actually experiencing. */
+export interface ObservedEnvironment {
+    readonly colorScheme: string;
+    readonly reducedMotion: boolean;
+    readonly contrast: string;
+    readonly forcedColors: boolean;
+    readonly print: boolean;
+    readonly width: number;
+    readonly height: number;
+    readonly devicePixelRatio: number;
+    readonly maxTouchPoints: number;
+    readonly touchEvents: boolean;
+    readonly language: string;
+    readonly timezone: string;
+}
+/** One media feature as the protocol wants it. */
+export interface MediaFeature {
+    readonly name: string;
+    readonly value: string;
+}
+/**
+ * Fold a change into the standing intent.
+ *
+ * Undefined means "leave as it was", so a caller can turn on
+ * reduced motion without having to restate the colour scheme.
+ * Clearing is done by asking for the neutral value, not by
+ * omitting the key, because omission cannot be told from
+ * indifference.
+ */
+export declare function mergeEmulation(current: EmulationState, change: EmulationState, clear?: readonly (keyof EmulationState)[]): EmulationState;
+/**
+ * Every media feature the intent implies, always in full.
+ *
+ * Chrome treats each setEmulatedMedia call as the complete
+ * truth and forgets anything not mentioned, measured directly:
+ * setting prefers-contrast alone cleared a
+ * prefers-reduced-motion set moments earlier. Sending the whole
+ * set every time is what stops one change from undoing
+ * another.
+ */
+export declare function mediaFeaturesOf(state: EmulationState): readonly MediaFeature[];
+/**
+ * Name the media feature a failed emulation call refused.
+ *
+ * Only this one shape counts. A dropped connection or a closed
+ * target says nothing about the feature, and treating any failure as
+ * a refusal would quietly discard an intent the browser never
+ * objected to.
+ */
+export declare function refusedFeature(message: string): string | undefined;
+/**
+ * Drop one media feature from a standing intent.
+ *
+ * Chrome is given the whole set at once and rejects the set on the
+ * first feature it does not know, so a refusal that stays in the
+ * intent takes every working feature down with it, on this call and
+ * on every navigation that replays it.
+ */
+export declare function withoutFeature(state: EmulationState, feature: string): EmulationState;
+/** One place where the page disagrees with what was asked. */
+export interface Divergence {
+    readonly what: string;
+    readonly asked: string;
+    readonly observed: string;
+    readonly note?: string;
+}
+/**
+ * Report fields that will be ignored, as divergences.
+ *
+ * A request this cannot honour used to be accepted in silence,
+ * echoed back under `asked`, and reported with no gaps at all: a
+ * call asking for a 1024px viewport did nothing, said nothing, and
+ * left the page at 800px while claiming to have been understood.
+ * That cost me twenty minutes of measuring the wrong viewport and
+ * concluding a page was fine.
+ *
+ * Reported rather than thrown because the rest of the request is
+ * still worth applying, and because gaps are already the channel
+ * for "you asked for something you did not get".
+ */
+export declare function unsupportedFields(change: Readonly<Record<string, unknown>>): readonly Divergence[];
+export declare function divergences(asked: EmulationState, observed: ObservedEnvironment): readonly Divergence[];

package/dist/web/environment/emulation.js

@@ -0,0 +1,258 @@
+/**
+ * Pretending to be a different visitor.
+ *
+ * Two measured facts shape everything here. Chrome's media
+ * emulation is a replacement, not a merge: sending one feature
+ * silently clears every other, so the session keeps the whole
+ * intent and re-sends all of it each time. And several
+ * overrides only partly land, notably locale, which changes
+ * how dates format without ever reaching navigator.language.
+ * So nothing here reports what it asked for; it reports what
+ * the page turned out to observe, and says where the two
+ * disagree.
+ */
+/**
+ * Fold a change into the standing intent.
+ *
+ * Undefined means "leave as it was", so a caller can turn on
+ * reduced motion without having to restate the colour scheme.
+ * Clearing is done by asking for the neutral value, not by
+ * omitting the key, because omission cannot be told from
+ * indifference.
+ */
+export function mergeEmulation(current, change, clear = []) {
+    const merged = { ...current };
+    // Skipping undefined is what lets a caller mention one field
+    // without disturbing the rest, and it is also why taking an
+    // override off again needs saying separately: an absent key and
+    // a key set to nothing arrive here as the same thing. Without
+    // this list, nothing could ever be cleared. A session that
+    // emulated Tokyo once stayed in Tokyo for the rest of its life,
+    // quietly recolouring every later reading, and stopping
+    // pretending to be a phone was impossible.
+    for (const key of clear)
+        delete merged[key];
+    for (const [key, value] of Object.entries(change)) {
+        if (value !== undefined)
+            merged[key] = value;
+    }
+    return merged;
+}
+/**
+ * Every media feature the intent implies, always in full.
+ *
+ * Chrome treats each setEmulatedMedia call as the complete
+ * truth and forgets anything not mentioned, measured directly:
+ * setting prefers-contrast alone cleared a
+ * prefers-reduced-motion set moments earlier. Sending the whole
+ * set every time is what stops one change from undoing
+ * another.
+ */
+export function mediaFeaturesOf(state) {
+    const features = [];
+    if (state.colorScheme !== undefined) {
+        features.push({ name: "prefers-color-scheme", value: state.colorScheme });
+    }
+    if (state.reducedMotion !== undefined) {
+        features.push({
+            name: "prefers-reduced-motion",
+            value: state.reducedMotion ? "reduce" : "no-preference",
+        });
+    }
+    if (state.contrast !== undefined) {
+        features.push({ name: "prefers-contrast", value: state.contrast });
+    }
+    if (state.forcedColors !== undefined) {
+        features.push({
+            name: "forced-colors",
+            value: state.forcedColors ? "active" : "none",
+        });
+    }
+    return features;
+}
+/**
+ * Which state field each media feature is spoken for by.
+ *
+ * The pairing has to be total in one direction: every feature
+ * mediaFeaturesOf can send must map back, or a refusal would be
+ * reported and then kept, which is the sticky refusal it exists to
+ * prevent.
+ */
+const FEATURE_FIELDS = {
+    "prefers-color-scheme": "colorScheme",
+    "prefers-reduced-motion": "reducedMotion",
+    "prefers-contrast": "contrast",
+    "forced-colors": "forcedColors",
+};
+const REFUSED_PATTERN = /Unsupported media feature:\s*(\S+)/;
+/**
+ * Name the media feature a failed emulation call refused.
+ *
+ * Only this one shape counts. A dropped connection or a closed
+ * target says nothing about the feature, and treating any failure as
+ * a refusal would quietly discard an intent the browser never
+ * objected to.
+ */
+export function refusedFeature(message) {
+    return REFUSED_PATTERN.exec(message)?.[1];
+}
+/**
+ * Drop one media feature from a standing intent.
+ *
+ * Chrome is given the whole set at once and rejects the set on the
+ * first feature it does not know, so a refusal that stays in the
+ * intent takes every working feature down with it, on this call and
+ * on every navigation that replays it.
+ */
+export function withoutFeature(state, feature) {
+    const field = FEATURE_FIELDS[feature];
+    if (!field || state[field] === undefined)
+        return state;
+    const left = { ...state };
+    delete left[field];
+    return left;
+}
+/**
+ * Where what was asked for and what the page sees disagree.
+ *
+ * Not every override lands completely, and a report that
+ * repeated the request back would hide exactly the cases worth
+ * knowing about.
+ */
+/** Every field this library knows how to emulate. */
+const EMULATION_FIELDS = [
+    "colorScheme",
+    "reducedMotion",
+    "contrast",
+    "forcedColors",
+    "media",
+    "vision",
+    "device",
+    "viewport",
+    "touch",
+    "userAgent",
+    "timezone",
+    "locale",
+    "cpuThrottle",
+    "geolocation",
+];
+/** Fields a caller invented, with the one they probably meant. */
+const LIKELY_MEANT = {
+    width: "viewport",
+    height: "viewport",
+    deviceScaleFactor: "viewport",
+    mobile: "viewport",
+    scale: "viewport",
+    darkMode: "colorScheme",
+    theme: "colorScheme",
+    timeZone: "timezone",
+    language: "locale",
+};
+/**
+ * Report fields that will be ignored, as divergences.
+ *
+ * A request this cannot honour used to be accepted in silence,
+ * echoed back under `asked`, and reported with no gaps at all: a
+ * call asking for a 1024px viewport did nothing, said nothing, and
+ * left the page at 800px while claiming to have been understood.
+ * That cost me twenty minutes of measuring the wrong viewport and
+ * concluding a page was fine.
+ *
+ * Reported rather than thrown because the rest of the request is
+ * still worth applying, and because gaps are already the channel
+ * for "you asked for something you did not get".
+ */
+export function unsupportedFields(change) {
+    const gaps = [];
+    for (const key of Object.keys(change)) {
+        if (EMULATION_FIELDS.includes(key))
+            continue;
+        if (change[key] === undefined)
+            continue;
+        const instead = LIKELY_MEANT[key];
+        gaps.push({
+            what: key,
+            asked: String(change[key]),
+            observed: "ignored, there is no such thing to emulate",
+            ...(instead ? { note: `${instead} is the field that carries this` } : {}),
+        });
+    }
+    return gaps;
+}
+export function divergences(asked, observed) {
+    const found = [];
+    if (asked.colorScheme !== undefined &&
+        observed.colorScheme !== asked.colorScheme) {
+        found.push({
+            what: "colour scheme",
+            asked: asked.colorScheme,
+            observed: observed.colorScheme,
+        });
+    }
+    if (asked.reducedMotion !== undefined &&
+        observed.reducedMotion !== asked.reducedMotion) {
+        found.push({
+            what: "reduced motion",
+            asked: String(asked.reducedMotion),
+            observed: String(observed.reducedMotion),
+        });
+    }
+    if (asked.forcedColors !== undefined &&
+        observed.forcedColors !== asked.forcedColors) {
+        found.push({
+            what: "forced colours",
+            asked: String(asked.forcedColors),
+            observed: String(observed.forcedColors),
+        });
+    }
+    if (asked.locale !== undefined && observed.language !== asked.locale) {
+        found.push({
+            what: "locale",
+            asked: asked.locale,
+            observed: observed.language,
+            note: "the override reaches date and number formatting but not " +
+                "navigator.language, which scripts read",
+        });
+    }
+    if (asked.timezone !== undefined && observed.timezone !== asked.timezone) {
+        found.push({
+            what: "timezone",
+            asked: asked.timezone,
+            observed: observed.timezone,
+        });
+    }
+    // Two signals, and a page can be given one without the other.
+    // A script may ask either: ontouchstart is the old sniff, and
+    // navigator.maxTouchPoints is what current guidance recommends,
+    // so touch is only really there when both agree. Checking the
+    // sniff alone let a half-applied phone pass as a whole one,
+    // which is the reverse of this function's whole purpose.
+    if (asked.touch === true && !observed.touchEvents) {
+        found.push({
+            what: "touch",
+            asked: "touch events available",
+            observed: `maxTouchPoints ${observed.maxTouchPoints}, ontouchstart absent`,
+            note: "a script sniffing for ontouchstart will still decide this " +
+                "is not a touch device",
+        });
+    }
+    else if (asked.touch === true && observed.maxTouchPoints === 0) {
+        found.push({
+            what: "touch",
+            asked: "a touch screen the page can count",
+            observed: "maxTouchPoints 0, ontouchstart present",
+            note: "a script asking navigator.maxTouchPoints, which is the " +
+                "usual way to ask, will decide this is not a touch device",
+        });
+    }
+    if (asked.viewport !== undefined && observed.width !== asked.viewport.width) {
+        found.push({
+            what: "viewport width",
+            asked: `${asked.viewport.width}px`,
+            observed: `${observed.width}px`,
+            note: "a page with no viewport meta tag is laid out at the " +
+                "desktop default regardless of the device",
+        });
+    }
+    return found;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * The environment a page thinks it is running in: viewport,
+ * media preferences, sight, locale and clock.
+ *
+ * The analysis here is capture-agnostic, so an observation
+ * taken by another driver reads the same way.
+ */
+export { type DeviceCatalogue, type DeviceProfile, deviceEmulation, nearestDevices, noSuchDevice, } from "./devices.js";
+export { type Divergence, divergences, type EmulationState, type MediaFeature, mediaFeaturesOf, mergeEmulation, type ObservedEnvironment, refusedFeature, unsupportedFields, type VisionDeficiency, withoutFeature, } from "./emulation.js";
+export { ENVIRONMENT_PROBE } from "./probes.js";
+export { matchesPattern, type NetworkRule, renderShaping, resolveThrottle, ruleFor, type ShapeAction, THROTTLE_PROFILES, type ThrottleConditions, throttleNames, throttleProfile, } from "./shaping.js";
+export { renderStatus, type SessionStatus } from "./status.js";
+export { type CookieRecord, captureState, readState, renderStorage, type SavedState, type StorageSnapshot, } from "./storage.js";
+export { chooseTab, renderTabs, type TabRecord } from "./tabs.js";
+export { renderEnvironment } from "./view.js";

package/dist/web/environment/index.js

@@ -0,0 +1,15 @@
+/**
+ * The environment a page thinks it is running in: viewport,
+ * media preferences, sight, locale and clock.
+ *
+ * The analysis here is capture-agnostic, so an observation
+ * taken by another driver reads the same way.
+ */
+export { deviceEmulation, nearestDevices, noSuchDevice, } from "./devices.js";
+export { divergences, mediaFeaturesOf, mergeEmulation, refusedFeature, unsupportedFields, withoutFeature, } from "./emulation.js";
+export { ENVIRONMENT_PROBE } from "./probes.js";
+export { matchesPattern, renderShaping, resolveThrottle, ruleFor, THROTTLE_PROFILES, throttleNames, throttleProfile, } from "./shaping.js";
+export { renderStatus } from "./status.js";
+export { captureState, readState, renderStorage, } from "./storage.js";
+export { chooseTab, renderTabs } from "./tabs.js";
+export { renderEnvironment } from "./view.js";

package/dist/web/environment/probes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Asking the page what it is actually experiencing.
+ *
+ * Page source rather than a function, 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.
+ */
+/**
+ * Read the environment as the page sees it.
+ *
+ * Every value here comes from the page's own APIs rather than
+ * from what we asked the browser for, because the two differ
+ * often enough that reporting the request would be reporting a
+ * guess.
+ */
+export declare const ENVIRONMENT_PROBE = "(() => {\n  const on = (query) => window.matchMedia(query).matches;\n  const pick = (name, values, fallback) => {\n    for (const value of values) {\n      if (on(\"(\" + name + \": \" + value + \")\")) return value;\n    }\n    return fallback;\n  };\n  return {\n    colorScheme: pick(\"prefers-color-scheme\", [\"dark\", \"light\"], \"light\"),\n    reducedMotion: on(\"(prefers-reduced-motion: reduce)\"),\n    contrast: pick(\"prefers-contrast\", [\"more\", \"less\", \"custom\"], \"no-preference\"),\n    forcedColors: on(\"(forced-colors: active)\"),\n    print: on(\"print\"),\n    width: window.innerWidth,\n    height: window.innerHeight,\n    devicePixelRatio: window.devicePixelRatio,\n    maxTouchPoints: navigator.maxTouchPoints,\n    touchEvents: \"ontouchstart\" in window,\n    language: navigator.language,\n    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,\n  };\n})()";

package/dist/web/environment/probes.js

@@ -0,0 +1,40 @@
+/**
+ * Asking the page what it is actually experiencing.
+ *
+ * Page source rather than a function, 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.
+ */
+/**
+ * Read the environment as the page sees it.
+ *
+ * Every value here comes from the page's own APIs rather than
+ * from what we asked the browser for, because the two differ
+ * often enough that reporting the request would be reporting a
+ * guess.
+ */
+export const ENVIRONMENT_PROBE = `(() => {
+  const on = (query) => window.matchMedia(query).matches;
+  const pick = (name, values, fallback) => {
+    for (const value of values) {
+      if (on("(" + name + ": " + value + ")")) return value;
+    }
+    return fallback;
+  };
+  return {
+    colorScheme: pick("prefers-color-scheme", ["dark", "light"], "light"),
+    reducedMotion: on("(prefers-reduced-motion: reduce)"),
+    contrast: pick("prefers-contrast", ["more", "less", "custom"], "no-preference"),
+    forcedColors: on("(forced-colors: active)"),
+    print: on("print"),
+    width: window.innerWidth,
+    height: window.innerHeight,
+    devicePixelRatio: window.devicePixelRatio,
+    maxTouchPoints: navigator.maxTouchPoints,
+    touchEvents: "ontouchstart" in window,
+    language: navigator.language,
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+  };
+})()`;