tapline-host 1.4.0 → 1.5.0

package/dist/journeygif.js

@@ -0,0 +1,192 @@
+import gifencDefault, * as gifencNamespace from "gifenc";
+import { markRing, scaleToWidth } from "./images.js";
+function isGifenc(value) {
+    return typeof value === "object" && value !== null && "GIFEncoder" in value && typeof value.GIFEncoder === "function" && "quantize" in value && "applyPalette" in value;
+}
+/** gifenc is CommonJS with a `default` of its own: Node hands over its exports as the default, bundlers and test runners as the module. */
+function loadGifenc() {
+    const inner = typeof gifencDefault === "object" && gifencDefault !== null && "default" in gifencDefault ? gifencDefault.default : undefined;
+    for (const candidate of [gifencDefault, inner, gifencNamespace])
+        if (isGifenc(candidate))
+            return candidate;
+    throw new Error("The GIF encoder (gifenc) could not be loaded.");
+}
+const gifenc = loadGifenc();
+export const GIF_WIDTH = 360;
+export const GIF_MAX_BYTES = 3 * 1024 * 1024;
+/** A still stretch shows its frame this long at most (two frames a second); closer frames keep their real gap. */
+const STILL_MS = 500;
+const MIN_DELAY_MS = 40;
+const RING_MS = 350;
+const LAST_MS = 1500;
+/** Time handed to the frame before when a frame is dropped, at most. */
+const MERGED_MS = 1200;
+const COLOURS = 128;
+/** The frames made the same size as the first one. */
+export function fitted(frames, width) {
+    const first = frames[0];
+    if (first === undefined)
+        return [];
+    const scaledFirst = scaleToWidth(first.pixels, width);
+    const height = scaledFirst.height;
+    return frames.map((frame, i) => {
+        const scaled = i === 0 ? scaledFirst : scaleToWidth(frame.pixels, width);
+        if (scaled.height === height)
+            return { ...frame, pixels: scaled };
+        // Another shape (the phone turned): the whole picture is fitted inside the canvas, centred, never cropped.
+        const k = Math.min(width / frame.pixels.width, height / frame.pixels.height);
+        const inner = scaleToWidth(frame.pixels, Math.max(1, Math.round(frame.pixels.width * k)));
+        const data = new Uint8Array(width * height * 4).fill(255);
+        const left = Math.max(0, Math.floor((width - inner.width) / 2));
+        const top = Math.max(0, Math.floor((height - inner.height) / 2));
+        const rows = Math.min(inner.height, height - top);
+        const columns = Math.min(inner.width, width - left);
+        for (let y = 0; y < rows; y++) {
+            data.set(inner.data.subarray(y * inner.width * 4, (y * inner.width + columns) * 4), ((top + y) * width + left) * 4);
+        }
+        // Where the picture sits in the canvas (shares of it), so a tap's share of the screen can be moved to match.
+        return { ...frame, pixels: { width, height, data }, fit: { x: left / width, y: top / height, w: inner.width / width, h: inner.height / height } };
+    });
+}
+/** A tap (a share of the screen) as a share of the canvas the screen was fitted in. */
+function tapOnCanvas(tap, fit) {
+    return fit === undefined ? tap : { x: fit.x + tap.x * fit.w, y: fit.y + tap.y * fit.h };
+}
+export function slidesOf(frames) {
+    const slides = [];
+    frames.forEach((frame, i) => {
+        const previous = frames[i - 1];
+        if (frame.tap !== undefined) {
+            // The tap was made on the screen before it: the ring goes there, a moment before the result.
+            // The ring sits on the picture it is drawn on, so it follows that picture's scale and offset in the canvas.
+            const shown = previous ?? frame;
+            slides.push({ pixels: markRing(shown.pixels, tapOnCanvas(frame.tap, shown.fit)), delay: RING_MS, still: false, ring: true });
+        }
+        const next = frames[i + 1];
+        const gap = next === undefined ? LAST_MS : Math.max(0, next.at - frame.at);
+        slides.push({
+            pixels: frame.pixels,
+            delay: next === undefined ? LAST_MS : Math.min(STILL_MS, Math.max(MIN_DELAY_MS, gap)),
+            still: next !== undefined && gap > STILL_MS,
+            ring: false,
+        });
+    });
+    return slides;
+}
+/** Every second one of `indexes` (or the only one), dropped; the time goes to the picture before. */
+function dropHalf(slides, indexes) {
+    if (indexes.length === 0)
+        return null;
+    const gone = new Set(indexes.length === 1 ? indexes : indexes.filter((_, n) => n % 2 === 1));
+    const kept = [];
+    slides.forEach((slide, i) => {
+        if (!gone.has(i)) {
+            kept.push(slide);
+            return;
+        }
+        const before = kept[kept.length - 1];
+        if (before !== undefined)
+            kept[kept.length - 1] = { ...before, delay: Math.min(MERGED_MS, before.delay + slide.delay) };
+    });
+    return kept;
+}
+/** Fewer pictures: the still ones first, then every second one but the first and the last; null when there is nothing left to drop. */
+function shrink(slides) {
+    const inner = slides.map((_, i) => i).filter((i) => i > 0 && i < slides.length - 1);
+    const still = inner.filter((i) => slides[i]?.still === true);
+    return dropHalf(slides, still) ?? dropHalf(slides, inner);
+}
+/** How the frames are laid out in time (for tests): each picture's delay in ms, whether it is a still stretch, whether it is a tap ring. */
+export function slidePlan(frames) {
+    return slidesOf([...frames].sort((a, b) => a.at - b.at)).map(({ delay, still, ring }) => ({ delay, still, ring }));
+}
+function encode(slides, coded) {
+    const first = slides[0];
+    if (first === undefined)
+        throw new Error("There are no frames for a GIF.");
+    const encoder = gifenc.GIFEncoder();
+    const { width, height } = first.pixels;
+    for (const slide of slides) {
+        let entry = coded.get(slide.pixels);
+        if (entry === undefined) {
+            const palette = gifenc.quantize(slide.pixels.data, COLOURS, { format: "rgb444" });
+            entry = { palette, index: gifenc.applyPalette(slide.pixels.data, palette, "rgb444") };
+            coded.set(slide.pixels, entry);
+        }
+        encoder.writeFrame(entry.index, width, height, { palette: entry.palette, delay: slide.delay, repeat: 0 });
+    }
+    encoder.finish();
+    return encoder.bytes();
+}
+/** The GIF of a journey. `maxBytes` and `width` are for tests; the defaults are the spec's (3 MB, 360 px). */
+export function encodeJourneyGif(frames, options = {}) {
+    if (frames.length === 0)
+        throw new Error("There are no frames for a GIF.");
+    const maxBytes = options.maxBytes ?? GIF_MAX_BYTES;
+    let width = options.width ?? GIF_WIDTH;
+    let shrunk = false;
+    let ordered = [...frames].sort((a, b) => a.at - b.at);
+    for (;;) {
+        let slides = slidesOf(fitted(ordered, width));
+        const total = slides.length;
+        const coded = new Map();
+        let bytes = encode(slides, coded);
+        while (bytes.length > maxBytes) {
+            const fewer = shrink(slides);
+            if (fewer === null)
+                break;
+            slides = fewer;
+            bytes = encode(slides, coded);
+        }
+        const first = slides[0];
+        if (bytes.length <= maxBytes || width <= 90 || first === undefined) {
+            return { bytes, frames: slides.length, width: first?.pixels.width ?? width, height: first?.pixels.height ?? 0, dropped: total - slides.length, shrunk };
+        }
+        // Even two pictures are over the cap: the same pictures at half the size.
+        width = Math.max(90, Math.round(width / 2));
+        shrunk = true;
+        ordered = ordered.map((frame) => ({ ...frame, pixels: scaleToWidth(frame.pixels, width) }));
+    }
+}
+/** Reads a GIF's header and counts its pictures by walking its blocks; throws when it isn't one. */
+export function gifInfo(bytes) {
+    const text = (from, to) => String.fromCharCode(...bytes.subarray(from, to));
+    const head = text(0, 6);
+    if (!/^GIF8[79]a$/.test(head))
+        throw new Error("not a GIF");
+    const u16 = (at) => (bytes[at] ?? 0) | ((bytes[at + 1] ?? 0) << 8);
+    const width = u16(6);
+    const height = u16(8);
+    const packed = bytes[10] ?? 0;
+    let at = 13 + ((packed & 0x80) !== 0 ? 3 * 2 ** ((packed & 7) + 1) : 0);
+    let frames = 0;
+    let loops;
+    const skipBlocks = () => {
+        while (at < bytes.length && (bytes[at] ?? 0) !== 0)
+            at += (bytes[at] ?? 0) + 1;
+        at += 1;
+    };
+    while (at < bytes.length) {
+        const marker = bytes[at];
+        if (marker === 0x3b)
+            break;
+        if (marker === 0x21) {
+            const label = bytes[at + 1];
+            if (label === 0xff && text(at + 3, at + 14) === "NETSCAPE2.0")
+                loops = u16(at + 16);
+            at += 2;
+            skipBlocks();
+        }
+        else if (marker === 0x2c) {
+            const flags = bytes[at + 9] ?? 0;
+            at += 10 + ((flags & 0x80) !== 0 ? 3 * 2 ** ((flags & 7) + 1) : 0);
+            at += 1; // the LZW minimum code size
+            skipBlocks();
+            frames++;
+        }
+        else
+            throw new Error("not a GIF");
+    }
+    return { version: head, width, height, frames, loops };
+}
+//# sourceMappingURL=journeygif.js.map

package/dist/journeygif.js.map

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

package/dist/journeyreport.d.ts

@@ -0,0 +1,202 @@
+import type { ShotImage } from "./annotate.js";
+import { type ShareBox } from "./images.js";
+import { type JourneyState } from "./journey.js";
+import type { UxAction, UxFindingSummary } from "./uxcheck.js";
+/**
+ * The journey's visual report (AGENT-TOOLS 1.12 §17.5): the frames kept after each counted step, the findings, and
+ * the folder written at `stop`: `report.md`, `report.html`, `frames/`, `findings/`, `journey.gif`, `key-1.jpg`,
+ * `key-2.jpg`. Pictures stay in files; only the two key pictures reach the agent.
+ */
+export declare const FRAME_WIDTH = 360;
+/** The report lists this many findings at most (the worst first) and says how many more there were; it never blocks `stop`. */
+export declare const MAX_FINDINGS = 100;
+/** What the app showed at one moment, from a cheap read that touches nothing. */
+export interface Peek {
+    /** Hash of what is on screen: same hash, same screen. */
+    signature: string;
+    screen?: {
+        w: number;
+        h: number;
+    };
+    route: string[];
+}
+/** Where the recorder gets its pictures: the host's requests to the app, or a fake in tests. */
+export interface FrameSource {
+    /** Whether the journey's app is connected and in front: frames are only taken then. */
+    where(): "front" | "background" | "disconnected" | "other";
+    peek(): Promise<Peek | undefined>;
+    shot(width: number, quality: number): Promise<ShotImage | undefined>;
+}
+/** The screen's elements as one hash: texts, values, positions and the route, not refs. */
+export declare function screenSignature(elements: ReadonlyArray<{
+    role?: string | null;
+    text?: string | null;
+    label?: string | null;
+    value?: unknown;
+    frame?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+}>, route: string[], alerts: number): string;
+/** Where a step touched, in points, and the frame of the element it touched. */
+export interface Touch {
+    point?: {
+        x: number;
+        y: number;
+    };
+    frame?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface FrameRecord {
+    /** 1-based, in the order kept. */
+    n: number;
+    /** The step this frame follows; 0 is the screen at the start. */
+    step: number;
+    /** Relative to the report folder. */
+    file: string;
+    at: number;
+    /** The journey's screen number. */
+    screen: number | undefined;
+    signature: string;
+    /** Where the step touched and the touched element's box, as shares of the screen. */
+    tap?: {
+        x: number;
+        y: number;
+    };
+    box?: ShareBox;
+}
+/** One finding of a `ux_check` the agent made during the journey, with its marked-up picture. */
+export interface SeenFinding extends UxFindingSummary {
+    screen: number | undefined;
+    title: string;
+    /** Relative path of the picture with the red box. */
+    shot?: string;
+}
+export declare class JourneyRecorder {
+    readonly folder: string;
+    private readonly source;
+    private readonly clock;
+    readonly frames: FrameRecord[];
+    readonly seen: SeenFinding[];
+    /** Skipped frames: the list hadn't changed and nothing animated. */
+    skipped: number;
+    /** Frames not taken because the journey's app was not connected and in front, by where it was. */
+    readonly away: Map<string, number>;
+    private readonly actions;
+    private queue;
+    private lastSignature;
+    private uxCount;
+    /** Times the app's photo picker was skipped (`media` with `picker`) during the journey. */
+    pickerSkips: number;
+    pickerPictures: number;
+    constructor(folder: string, source: FrameSource, clock: () => number);
+    get name(): string;
+    /** Runs `work` after the ones before it: the pictures come in the order of the steps. */
+    private later;
+    /**
+     * Keeps a small picture of the screen after a step. Skipped when the element list is what it was and nothing
+     * animates (AGENTS.md: don't look twice). Never fails the step.
+     */
+    frame(step: number, screen: number | undefined, touch: Touch | undefined, animating: boolean): Promise<void>;
+    /** The action labels of the screens seen before `current`, for `ux_check`'s naming check. */
+    earlier(current: number | undefined): UxAction[];
+    /** A `ux_check` was made: keep its actions, and a picture per finding with the element boxed in red. */
+    uxSeen(screen: number | undefined, title: string, actions: UxAction[], findings: UxFindingSummary[]): Promise<void>;
+    /** Everything asked for is on disk. */
+    done(): Promise<void>;
+}
+export type Severity = "high" | "medium" | "low";
+export interface Finding {
+    severity: Severity;
+    kind: string;
+    /** One line: what is wrong. */
+    title: string;
+    screen: number | undefined;
+    basis: string;
+    /** Relative path of the marked-up picture. */
+    shot?: string;
+}
+/**
+ * Simple rules, written in the report's footer. A `ux_check` kind not named here is low.
+ */
+export declare const SEVERITY_RULES: string[];
+/** The findings of a finished journey, worst first. `steps` pictures are filled in by `markSteps`. */
+export declare function buildFindings(state: JourneyState, seen: readonly SeenFinding[], maxTaps: number | undefined): Finding[];
+export declare function countFindings(findings: readonly Finding[]): Record<Severity, number>;
+/** `Findings: 2 high, 3 medium, 1 low.` or `Findings: none.` */
+export declare function findingsLine(counts: Record<Severity, number>): string;
+/** `2026-11-12-1530-log-breakfast-by-scanning-its-barcode`, in the computer's local time. */
+export declare function reportFolderName(goal: string, at: number): string;
+/** A folder name that doesn't exist yet in `root` (`-2`, `-3` when the same goal ran in the same minute). */
+/** How many journey reports a host keeps in its journeys folder (1.5 review, finding 6). */
+export declare const JOURNEYS_KEPT = 20;
+/**
+ * Keeps the newest `keep` report folders in `root` (by when they were last changed) and removes the rest. Only folders
+ * that hold a report or frames (what a journey writes) are counted or removed; anything else in `root` is left alone.
+ */
+export declare function pruneJourneys(root: string, keep: number): number;
+export declare function freshFolder(root: string, goal: string, at: number): string;
+export interface ReportResult {
+    folder: string;
+    name: string;
+    findings: Finding[];
+    counts: Record<Severity, number>;
+    /** Files of the folder, relative, for the export. */
+    files: string[];
+    /** What an export uploads: the report, the GIF and the pictures the report uses; not every raw frame. */
+    exportFiles: string[];
+    /** The first picture of the path, for an export's comment when there is no GIF. */
+    firstPicture: string | undefined;
+    /** Findings beyond the 100 the report lists. */
+    omitted: number;
+    gif: {
+        frames: number;
+        bytes: number;
+        dropped: number;
+    } | null;
+    /** The key pictures, relative: where the journey ended, and the worst finding. */
+    keys: string[];
+    notes: string[];
+}
+/** At most this many pictures are decoded for the GIF (each is about 1 MB as pixels): 1.5 review, finding 6. */
+export declare const GIF_MAX_SOURCE_FRAMES = 150;
+/**
+ * The frames the GIF is made of, at most `max`: every tap and every first picture of a screen stays (they tell the
+ * story); the other, still pictures are thinned evenly. Chosen before anything is decoded.
+ */
+export declare function framesForGif(frames: readonly FrameRecord[], max?: number): FrameRecord[];
+/**
+ * The report's own folder, in whatever slash style a step's text carries it, replaced by `<report>`: an export
+ * must not publish this computer's user name and folders.
+ */
+export declare function scrubFolder(text: string, folder: string): string;
+export interface Ctx {
+    state: JourneyState;
+    rec: JourneyRecorder;
+    findings: Finding[];
+    counts: Record<Severity, number>;
+    /** Findings past the cap, not listed. */
+    omitted: number;
+    gif: ReportResult["gif"];
+    maxTaps: number | undefined;
+    textRules: readonly string[];
+}
+export declare function renderMarkdown(ctx: Ctx): string;
+export declare function renderHtml(ctx: Ctx): string;
+export interface WriteOptions {
+    state: JourneyState;
+    rec: JourneyRecorder;
+    maxTaps: number | undefined;
+    textRules?: readonly string[];
+    gifMaxBytes?: number;
+}
+/** Writes the report folder: waits for the pictures asked for, then the findings, GIF, key pictures, `report.md` and `report.html`. */
+export declare function writeReport(options: WriteOptions): Promise<ReportResult>;
+/** A picture inside the report folder: a relative path of plain names, no `..`, ending .png, .jpg or .gif. */
+export declare function isReportPicture(path: string): boolean;