tapline-host 1.3.1 → 1.5.0

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;