@jitsusama/agentic-harness.core 0.1.0

package/dist/web/input/keys.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Chords, as a person would write them.
+ *
+ * "Ctrl+Shift+K" is how a keyboard shortcut is written down
+ * everywhere except in the protocol, which wants an ordered
+ * sequence of key events and a bitmask. Parsing happens here so
+ * that a mistyped chord is refused by name before anything is
+ * dispatched, rather than silently pressing the wrong thing.
+ *
+ * The set of real key names is passed in rather than kept here.
+ * The browser driver owns that table, and copying it would mean
+ * maintaining a second opinion about what keys exist.
+ */
+/** The four modifiers the protocol tracks as a bitmask. */
+export type ModifierName = "Alt" | "Control" | "Meta" | "Shift";
+/**
+ * The protocol's modifier bits.
+ *
+ * These are positional flags in a single integer, not an
+ * arbitrary enumeration, so they are written as the powers of
+ * two they are.
+ */
+export declare const MODIFIER_BITS: Readonly<Record<ModifierName, number>>;
+/** One keypress, with whatever was held down for it. */
+export interface Chord {
+    readonly modifiers: readonly ModifierName[];
+    readonly key: string;
+    readonly bitmask: number;
+}
+/** What went wrong, and what might have been meant. */
+export interface ChordRefusal {
+    readonly token: string;
+    readonly message: string;
+    readonly candidates: readonly string[];
+}
+/**
+ * Parse a sequence of chords: "Tab Tab Enter", "Ctrl+K",
+ * "Shift+ArrowDown".
+ *
+ * Chords are separated by spaces and keys within a chord by
+ * plus. A literal space is written as the word Space, since a
+ * space character is already doing the separating.
+ */
+export declare function parseChords(text: string, knownKeys: ReadonlySet<string>): {
+    chords: readonly Chord[];
+} | {
+    refusal: ChordRefusal;
+};

package/dist/web/input/keys.js

@@ -0,0 +1,189 @@
+/**
+ * Chords, as a person would write them.
+ *
+ * "Ctrl+Shift+K" is how a keyboard shortcut is written down
+ * everywhere except in the protocol, which wants an ordered
+ * sequence of key events and a bitmask. Parsing happens here so
+ * that a mistyped chord is refused by name before anything is
+ * dispatched, rather than silently pressing the wrong thing.
+ *
+ * The set of real key names is passed in rather than kept here.
+ * The browser driver owns that table, and copying it would mean
+ * maintaining a second opinion about what keys exist.
+ */
+/**
+ * The protocol's modifier bits.
+ *
+ * These are positional flags in a single integer, not an
+ * arbitrary enumeration, so they are written as the powers of
+ * two they are.
+ */
+export const MODIFIER_BITS = {
+    Alt: 1,
+    Control: 2,
+    Meta: 4,
+    Shift: 8,
+};
+/**
+ * Names people actually type, mapped to what the browser calls
+ * them. Cmd and Super are the same key under different
+ * traditions, and refusing either would be pedantry.
+ */
+const ALIASES = {
+    cmd: "Meta",
+    command: "Meta",
+    super: "Meta",
+    win: "Meta",
+    meta: "Meta",
+    ctrl: "Control",
+    control: "Control",
+    alt: "Alt",
+    opt: "Alt",
+    option: "Alt",
+    shift: "Shift",
+    esc: "Escape",
+    escape: "Escape",
+    del: "Delete",
+    delete: "Delete",
+    ins: "Insert",
+    return: "Enter",
+    enter: "Enter",
+    space: " ",
+    spacebar: " ",
+    up: "ArrowUp",
+    down: "ArrowDown",
+    left: "ArrowLeft",
+    right: "ArrowRight",
+    pgup: "PageUp",
+    pgdn: "PageDown",
+    pagedown: "PageDown",
+    pageup: "PageUp",
+};
+/** How many near misses are worth offering. */
+const MAX_CANDIDATES = 5;
+/** Modifiers are reported in this order, so chords compare. */
+const MODIFIER_ORDER = [
+    "Control",
+    "Alt",
+    "Shift",
+    "Meta",
+];
+const isModifier = (name) => name in MODIFIER_BITS;
+/**
+ * Parse a sequence of chords: "Tab Tab Enter", "Ctrl+K",
+ * "Shift+ArrowDown".
+ *
+ * Chords are separated by spaces and keys within a chord by
+ * plus. A literal space is written as the word Space, since a
+ * space character is already doing the separating.
+ */
+export function parseChords(text, knownKeys) {
+    const words = text.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0) {
+        return {
+            refusal: {
+                token: "",
+                message: "No keys were given.",
+                candidates: [],
+            },
+        };
+    }
+    const chords = [];
+    for (const word of words) {
+        const parsed = parseChord(word, knownKeys);
+        if ("refusal" in parsed)
+            return parsed;
+        chords.push(parsed.chord);
+    }
+    return { chords };
+}
+/** Parse one chord: modifiers, then the key they apply to. */
+function parseChord(word, knownKeys) {
+    // A lone plus is a key, not a separator with nothing around
+    // it, so splitting has to leave it alone.
+    const tokens = word === "+" ? ["+"] : word.split("+").filter(Boolean);
+    if (tokens.length === 0) {
+        return {
+            refusal: {
+                token: word,
+                message: `'${word}' is not a key.`,
+                candidates: [],
+            },
+        };
+    }
+    const modifiers = [];
+    let key;
+    for (const token of tokens) {
+        const canonical = canonicalize(token, knownKeys);
+        if (canonical === undefined) {
+            return {
+                refusal: {
+                    token,
+                    message: `There is no key called '${token}'.`,
+                    candidates: nearest(token, knownKeys),
+                },
+            };
+        }
+        // A modifier is the key being pressed only when it stands
+        // alone. Holding Shift is a real thing to do; Ctrl+Shift is
+        // someone who has not finished typing the chord.
+        const alone = tokens.length === 1;
+        if (isModifier(canonical) && !alone) {
+            modifiers.push(canonical);
+            continue;
+        }
+        key = canonical;
+    }
+    if (key === undefined) {
+        return {
+            refusal: {
+                token: word,
+                message: `'${word}' is only modifiers, with no key to press.`,
+                candidates: [],
+            },
+        };
+    }
+    const held = new Set(modifiers);
+    const ordered = MODIFIER_ORDER.filter((name) => held.has(name));
+    let bitmask = 0;
+    for (const name of ordered)
+        bitmask |= MODIFIER_BITS[name];
+    return { chord: { modifiers: ordered, key, bitmask } };
+}
+/** What the browser calls the key this token names. */
+function canonicalize(token, knownKeys) {
+    // An exact match wins outright, so a single lowercase letter
+    // stays lowercase and is not read as an alias.
+    if (knownKeys.has(token))
+        return token;
+    const alias = ALIASES[token.toLowerCase()];
+    if (alias !== undefined && (knownKeys.has(alias) || isModifier(alias))) {
+        return alias;
+    }
+    // Case-insensitive last, so that 'tab' finds Tab without
+    // letting 'A' quietly become 'a'.
+    for (const known of knownKeys) {
+        if (known.toLowerCase() === token.toLowerCase())
+            return known;
+    }
+    return undefined;
+}
+/** Key names close enough to the token to be worth offering. */
+function nearest(token, knownKeys) {
+    const wanted = token.toLowerCase();
+    const scored = [];
+    for (const known of knownKeys) {
+        const name = known.toLowerCase();
+        if (name.startsWith(wanted))
+            scored.push({ name: known, score: 0 });
+        else if (name.includes(wanted))
+            scored.push({ name: known, score: 1 });
+        else if (wanted.includes(name) && name.length > 1) {
+            scored.push({ name: known, score: 2 });
+        }
+    }
+    return scored
+        .sort((a, b) => a.score - b.score || a.name.length - b.name.length)
+        .slice(0, MAX_CANDIDATES)
+        .map((entry) => entry.name);
+}

package/dist/web/input/pointer.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Mouse movement as a sequence, not a teleport.
+ *
+ * A click can be delivered at a point, but a drag cannot: an
+ * element that follows the pointer needs to see it move, and a
+ * hover menu that opens on entry needs the pointer to arrive
+ * rather than appear. So a gesture is composed as the ordered
+ * events a real hand would produce, and the composition is pure
+ * so it can be checked without a browser.
+ */
+/** A point in viewport coordinates. */
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** Which button an event carries. */
+export type MouseButton = "left" | "middle" | "right" | "back" | "forward";
+/** One mouse event, ready to dispatch. */
+export interface PointerEventStep {
+    readonly type: "mouseMoved" | "mousePressed" | "mouseReleased";
+    readonly x: number;
+    readonly y: number;
+    readonly button: MouseButton | "none";
+    readonly clickCount: number;
+}
+/** How a drag is drawn between two points. */
+export interface DragOptions {
+    /** How many intermediate moves to make on the way. */
+    readonly steps?: number;
+    readonly button?: MouseButton;
+}
+/**
+ * How far along the way each step is, ending exactly at one.
+ *
+ * Everything that travels shares this: a pointer crossing the
+ * screen and two fingers changing their distance are the same
+ * ramp applied to different quantities.
+ *
+ * Fewer than one step still has to arrive somewhere, and the
+ * only defensible somewhere is the destination.
+ */
+export declare function ratios(steps: number): readonly number[];
+/** Points along a straight line, ending exactly at the end. */
+export declare function interpolate(from: Point, to: Point, steps: number): readonly Point[];
+/**
+ * A drag: arrive, press, travel, release.
+ *
+ * The move before the press matters. Dragging from wherever the
+ * pointer happened to be left would press the wrong element.
+ */
+export declare function composeDrag(from: Point, to: Point, options?: DragOptions): readonly PointerEventStep[];
+/** A click at a point, optionally repeated for double or triple. */
+export declare function composeClick(at: Point, options?: {
+    button?: MouseButton;
+    count?: number;
+}): readonly PointerEventStep[];

package/dist/web/input/pointer.js

@@ -0,0 +1,77 @@
+/**
+ * Mouse movement as a sequence, not a teleport.
+ *
+ * A click can be delivered at a point, but a drag cannot: an
+ * element that follows the pointer needs to see it move, and a
+ * hover menu that opens on entry needs the pointer to arrive
+ * rather than appear. So a gesture is composed as the ordered
+ * events a real hand would produce, and the composition is pure
+ * so it can be checked without a browser.
+ */
+/**
+ * How many moves a drag makes by default.
+ *
+ * One move is a teleport and anything watching mousemove sees a
+ * single jump. Enough intermediate points that a drag handler
+ * runs several times is the difference between exercising the
+ * interaction and merely landing on its endpoint.
+ */
+const DEFAULT_DRAG_STEPS = 10;
+/**
+ * How far along the way each step is, ending exactly at one.
+ *
+ * Everything that travels shares this: a pointer crossing the
+ * screen and two fingers changing their distance are the same
+ * ramp applied to different quantities.
+ *
+ * Fewer than one step still has to arrive somewhere, and the
+ * only defensible somewhere is the destination.
+ */
+export function ratios(steps) {
+    if (steps < 1)
+        return [1];
+    return Array.from({ length: steps }, (_, index) => (index + 1) / steps);
+}
+/** Points along a straight line, ending exactly at the end. */
+export function interpolate(from, to, steps) {
+    return ratios(steps).map((ratio) => ({
+        x: from.x + (to.x - from.x) * ratio,
+        y: from.y + (to.y - from.y) * ratio,
+    }));
+}
+/**
+ * A drag: arrive, press, travel, release.
+ *
+ * The move before the press matters. Dragging from wherever the
+ * pointer happened to be left would press the wrong element.
+ */
+export function composeDrag(from, to, options = {}) {
+    const button = options.button ?? "left";
+    const steps = options.steps ?? DEFAULT_DRAG_STEPS;
+    return [
+        { type: "mouseMoved", ...from, button: "none", clickCount: 0 },
+        { type: "mousePressed", ...from, button, clickCount: 1 },
+        ...interpolate(from, to, steps).map((point) => ({
+            type: "mouseMoved",
+            ...point,
+            button,
+            clickCount: 1,
+        })),
+        { type: "mouseReleased", ...to, button, clickCount: 1 },
+    ];
+}
+/** A click at a point, optionally repeated for double or triple. */
+export function composeClick(at, options = {}) {
+    const button = options.button ?? "left";
+    const count = Math.max(1, options.count ?? 1);
+    const steps = [
+        { type: "mouseMoved", ...at, button: "none", clickCount: 0 },
+    ];
+    // A double click is two clicks whose count rises, not one
+    // event with a count of two. Anything listening for dblclick
+    // is watching that number climb.
+    for (let click = 1; click <= count; click += 1) {
+        steps.push({ type: "mousePressed", ...at, button, clickCount: click }, { type: "mouseReleased", ...at, button, clickCount: click });
+    }
+    return steps;
+}

package/dist/web/input/touch.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Gestures, composed from touch points.
+ *
+ * A tap is not a click. A page that handles touchstart, or that
+ * distinguishes a swipe from a scroll, cannot be exercised with
+ * a mouse at all, and on a phone layout those handlers are
+ * usually the only way to reach half the interface.
+ *
+ * Pinch is the reason these are sequences rather than events: it
+ * needs two points moving relative to each other, which no
+ * single event can express.
+ */
+import { type Point } from "./pointer.js";
+/** One finger, at a moment. */
+export interface TouchPoint {
+    readonly x: number;
+    readonly y: number;
+    /** Which finger this is, stable across the gesture. */
+    readonly id: number;
+}
+/** One touch event, ready to dispatch. */
+export interface TouchStep {
+    readonly type: "touchStart" | "touchMove" | "touchEnd" | "touchCancel";
+    readonly points: readonly TouchPoint[];
+    /** How long to wait after dispatching, when it matters. */
+    readonly pauseMs?: number;
+}
+/**
+ * How long a press has to last to count as long.
+ *
+ * Chrome's own gesture recognizer uses half a second, and a
+ * context menu that opens on long press is watching for roughly
+ * that, so a shorter hold is just a tap.
+ */
+export declare const LONG_PRESS_MS = 500;
+/** A tap: one finger down, one finger up. */
+export declare function composeTap(at: Point): readonly TouchStep[];
+/**
+ * A long press: the same as a tap, held.
+ *
+ * The end carries no points because a touch that has lifted is
+ * not at a position any more, which is the protocol's rule and
+ * a sensible one.
+ */
+export declare function composeLongPress(at: Point, holdMs?: number): readonly TouchStep[];
+/** A swipe: down, travel, up. */
+export declare function composeSwipe(from: Point, to: Point, options?: {
+    steps?: number;
+}): readonly TouchStep[];
+/**
+ * A pinch: two fingers either side of a centre, moving together
+ * or apart.
+ *
+ * The spread is the distance between the fingers, so a spread
+ * that grows is a zoom in and one that shrinks is a zoom out.
+ * Expressing it that way means the caller never has to work out
+ * where two fingers should individually go.
+ */
+export declare function composePinch(centre: Point, from: number, to: number, options?: {
+    steps?: number;
+}): readonly TouchStep[];

package/dist/web/input/touch.js

@@ -0,0 +1,83 @@
+/**
+ * Gestures, composed from touch points.
+ *
+ * A tap is not a click. A page that handles touchstart, or that
+ * distinguishes a swipe from a scroll, cannot be exercised with
+ * a mouse at all, and on a phone layout those handlers are
+ * usually the only way to reach half the interface.
+ *
+ * Pinch is the reason these are sequences rather than events: it
+ * needs two points moving relative to each other, which no
+ * single event can express.
+ */
+import { interpolate, ratios } from "./pointer.js";
+/** How many moves a swipe makes by default. */
+const DEFAULT_SWIPE_STEPS = 10;
+/** How many moves a pinch makes by default. */
+const DEFAULT_PINCH_STEPS = 10;
+/**
+ * How long a press has to last to count as long.
+ *
+ * Chrome's own gesture recognizer uses half a second, and a
+ * context menu that opens on long press is watching for roughly
+ * that, so a shorter hold is just a tap.
+ */
+export const LONG_PRESS_MS = 500;
+/** A tap: one finger down, one finger up. */
+export function composeTap(at) {
+    return [
+        { type: "touchStart", points: [{ ...at, id: 0 }] },
+        { type: "touchEnd", points: [] },
+    ];
+}
+/**
+ * A long press: the same as a tap, held.
+ *
+ * The end carries no points because a touch that has lifted is
+ * not at a position any more, which is the protocol's rule and
+ * a sensible one.
+ */
+export function composeLongPress(at, holdMs = LONG_PRESS_MS) {
+    return [
+        { type: "touchStart", points: [{ ...at, id: 0 }], pauseMs: holdMs },
+        { type: "touchEnd", points: [] },
+    ];
+}
+/** A swipe: down, travel, up. */
+export function composeSwipe(from, to, options = {}) {
+    const steps = options.steps ?? DEFAULT_SWIPE_STEPS;
+    return [
+        { type: "touchStart", points: [{ ...from, id: 0 }] },
+        ...interpolate(from, to, steps).map((point) => ({
+            type: "touchMove",
+            points: [{ ...point, id: 0 }],
+        })),
+        { type: "touchEnd", points: [] },
+    ];
+}
+/**
+ * A pinch: two fingers either side of a centre, moving together
+ * or apart.
+ *
+ * The spread is the distance between the fingers, so a spread
+ * that grows is a zoom in and one that shrinks is a zoom out.
+ * Expressing it that way means the caller never has to work out
+ * where two fingers should individually go.
+ */
+export function composePinch(centre, from, to, options = {}) {
+    const steps = options.steps ?? DEFAULT_PINCH_STEPS;
+    const fingers = (spread) => [
+        { x: centre.x - spread / 2, y: centre.y, id: 0 },
+        { x: centre.x + spread / 2, y: centre.y, id: 1 },
+    ];
+    return [
+        { type: "touchStart", points: fingers(from) },
+        ...ratios(steps)
+            .map((ratio) => from + (to - from) * ratio)
+            .map((spread) => ({
+            type: "touchMove",
+            points: fingers(spread),
+        })),
+        { type: "touchEnd", points: [] },
+    ];
+}

package/dist/web/mermaid.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Mermaid diagram rendering.
+ *
+ * Renders Mermaid source to two artifacts: the vector SVG Mermaid
+ * produces (crisp at any zoom, the human's readable copy) and a PNG
+ * rasterized from it (the portable raster and the inline image a vision
+ * model sees). The PNG is scaled to sit just under the vision-model
+ * pixel cap, because sending a larger image only makes the API
+ * downscale and blur the text server-side. Rendering rides the shared
+ * browser lifecycle from browser.ts rather than launching its own, so
+ * it inherits the same teardown.
+ */
+/** A width and height in pixels. */
+interface Dimensions {
+    width: number;
+    height: number;
+}
+/**
+ * Compute the raster scale for a diagram of the given intrinsic size so
+ * the PNG lands as close to the pixel budget as possible without
+ * crossing the long-edge or total-area cap. A diagram already larger
+ * than the cap is scaled down to fit; a smaller one is scaled up to the
+ * upscale ceiling so its text stays crisp.
+ */
+export declare function pngRenderScale({ width, height }: Dimensions): number;
+/**
+ * Final integer PNG dimensions for a diagram of the given intrinsic
+ * size. The continuous scale is chosen so the unrounded box fits the
+ * budget; flooring to whole pixels can only shrink it, so the returned
+ * dimensions never cross the long-edge or total-area cap even after
+ * integerization (which independent rounding would not guarantee).
+ */
+export declare function pngPixelSize({ width, height }: Dimensions): Dimensions;
+/**
+ * Fetch the Mermaid library source once, in Node, and cache it.
+ * Injecting the cached content into the render page means the page
+ * itself does no network work mid-render, which is what made
+ * rendering hang under a busy shared browser.
+ */
+export declare function loadMermaidSource(fetchImpl?: typeof fetch): Promise<string>;
+/** Thrown when Mermaid source cannot be rendered (bad syntax or no library). */
+export declare class MermaidRenderError extends Error {
+    constructor(message: string);
+}
+/** A rendered Mermaid diagram. */
+export interface MermaidRender {
+    /** Path to the PNG file on disk (the caller's path, or a temp path). */
+    pngPath: string;
+    /** Path to the SVG file on disk, beside the PNG (crisp at any zoom). */
+    svgPath: string;
+    /** Base64 PNG, for returning to a vision model inline. */
+    base64: string;
+    /** Final PNG width in pixels, after scaling to the cap. */
+    width: number;
+    /** Final PNG height in pixels, after scaling to the cap. */
+    height: number;
+}
+/**
+ * Render Mermaid source to an SVG and a PNG on disk and return their
+ * paths plus a base64 copy of the PNG and its final dimensions. The SVG
+ * is the vector artifact (crisp at any zoom); the PNG is rasterized from
+ * it, scaled toward the vision-model pixel budget (up to an upscale
+ * ceiling) without crossing it. The output path must name the PNG; the
+ * SVG is written beside it with the same base name. Reuses the shared
+ * headless browser. Throws MermaidRenderError when the library cannot
+ * load, the path is not a PNG, or the source is invalid.
+ */
+export declare function renderMermaid(source: string, outputPath?: string): Promise<MermaidRender>;
+export {};