jev-compare 0.0.0-stage → 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,470 @@
+import { TypeSafeClient, TypeSafeClientConfig } from "@typesafe-ai/sdk";
+//#region src/image.d.ts
+/**
+ * An image to compare: a file path, a `data:` URL, `{ base64 }`, raw bytes, or a `Blob`.
+ * Only PNG and JPEG are supported.
+ */
+type ImageInput = string | Uint8Array | ArrayBuffer | Blob | {
+  base64: string;
+};
+type ImageFormat = "png" | "jpeg";
+/** Image bytes with their detected format and pixel size. */
+interface LoadedImage {
+  readonly bytes: Uint8Array;
+  readonly format: ImageFormat;
+  readonly width: number;
+  readonly height: number;
+}
+export declare class ImageFormatError extends Error {
+  constructor(message: string);
+}
+/** Read an `ImageInput` into bytes and detect its format and dimensions. */
+export declare function loadImage(input: ImageInput): Promise<LoadedImage>;
+/** Detect PNG/JPEG and read the pixel size from the file header. */
+export declare function readImageInfo(bytes: Uint8Array): {
+  format: ImageFormat;
+  width: number;
+  height: number;
+};
+//#endregion
+//#region src/cache.d.ts
+/**
+ * Where API answers are cached. Implement it to use your own storage, such as Redis.
+ * Values are plain JSON; `get` returns `undefined` on a miss.
+ */
+interface CacheStore {
+  get(key: string): Promise<unknown> | unknown;
+  set(key: string, value: unknown): Promise<void> | void;
+}
+interface MemoryCacheOptions {
+  /** Most entries kept; the least recently used are evicted first. Default: 500. */
+  maxEntries?: number;
+  /** Entry lifetime in milliseconds. Default: no expiry. */
+  ttl?: number;
+}
+interface MemoryCache extends CacheStore {
+  readonly size: number;
+  clear(): void;
+}
+/** An in-process LRU cache, shared by every comparison that is given it. */
+export declare function memoryCache(options?: MemoryCacheOptions): MemoryCache;
+interface FileCacheOptions {
+  /** Directory that holds the cache files. */
+  dir: string;
+  /** Entry lifetime in milliseconds, counted from when it was written. Default: no expiry. */
+  ttl?: number;
+  /** Most entries kept; the least recently used are evicted first. Default: no limit. */
+  maxEntries?: number;
+  /** Most bytes kept; the least recently used entries are evicted first. Default: no limit. */
+  maxBytes?: number;
+  /**
+   * Prune automatically after writes, at most once per `pruneInterval` across every process
+   * that shares the directory. Default: true when `ttl`, `maxEntries` or `maxBytes` is set.
+   */
+  autoPrune?: boolean;
+  /** Minimum time between automatic prunes, in milliseconds. Default: 1 hour. */
+  pruneInterval?: number;
+}
+/** What `prune` deleted and what is left. */
+interface CachePruneResult {
+  /** Entries past their `ttl`. */
+  expired: number;
+  /** Least recently used entries over `maxEntries` or `maxBytes`. */
+  evicted: number;
+  /** Unreadable entries. */
+  invalid: number;
+  /** Temp files left by interrupted writes. */
+  temp: number;
+  /** Bytes freed. */
+  freedBytes: number;
+  keptEntries: number;
+  keptBytes: number;
+}
+interface FileCache extends CacheStore {
+  readonly dir: string;
+  /** Delete every entry. */
+  clear(): Promise<void>;
+  /** Delete expired, unreadable and over-limit entries now. */
+  prune(): Promise<CachePruneResult>;
+}
+/**
+ * A cache on disk, one JSON file per entry, that survives restarts and can be shared by
+ * processes. Writes are atomic; unreadable or expired entries count as misses.
+ *
+ * With `maxEntries` or `maxBytes`, reads mark an entry as recently used (by its file time),
+ * and pruning evicts the least recently used entries first. Limits are enforced when pruning,
+ * so between prunes the cache can briefly grow past them.
+ */
+export declare function fileCache(options: FileCacheOptions | string): FileCache;
+//#endregion
+//#region src/report.d.ts
+/** The `report.json` format version; bumped on incompatible changes. */
+export declare const REPORT_SCHEMA_VERSION = 1;
+/** A JSON-compatible value, for report metadata. */
+type ReportMetaValue = string | number | boolean | null | ReportMetaValue[] | {
+  [key: string]: ReportMetaValue;
+};
+type ReportFormat = "full" | "json";
+interface SaveReportOptions {
+  /** Directory that holds reports; each report gets its own subdirectory. */
+  dir: string;
+  /** Report ID and subdirectory name. Default: a UTC timestamp plus a random suffix, so IDs sort by time. */
+  id?: string;
+  /**
+   * What to write: `full` writes `report.json`, `report.html` and copies of both images;
+   * `json` writes only `report.json`. `images` and `html` override it. Default: `full`.
+   */
+  format?: ReportFormat;
+  /** Copy both images into the report. Default: true for `full`, false for `json`. */
+  images?: boolean;
+  /** Write a self-contained `report.html`. Default: true for `full`, false for `json`. */
+  html?: boolean;
+  /** Your own data to keep with the report, such as a page name, build number or commit. */
+  meta?: Record<string, ReportMetaValue>;
+  /**
+   * Delete old reports in `dir` after this one is saved. The new report is never deleted.
+   * Default: keep everything.
+   */
+  retention?: RetentionPolicy;
+}
+/**
+ * Which reports to keep. A report is deleted when it breaks any limit, oldest first.
+ * Reports that `keep` protects are never deleted and don't count toward the limits.
+ */
+interface RetentionPolicy {
+  /** Delete reports older than this many milliseconds. */
+  maxAge?: number;
+  /** Keep at most this many reports. */
+  maxCount?: number;
+  /** Keep the newest reports whose total size fits in this many bytes. */
+  maxBytes?: number;
+  /** Return true to protect a report, such as a baseline, from deletion. */
+  keep?: (report: ReportSummary) => boolean;
+}
+interface PruneOptions extends RetentionPolicy {
+  /** Work out what would be deleted without deleting anything. Default: false. */
+  dryRun?: boolean;
+  /**
+   * IDs that are never deleted but still count toward the limits, such as the report that
+   * was just saved. (Reports that `keep` protects don't count.)
+   */
+  protect?: string[];
+}
+interface PruneResult {
+  /** Reports deleted (or, with `dryRun`, that would be deleted), oldest first. */
+  removed: Array<ReportSummary & {
+    bytes: number;
+    reason: "maxAge" | "maxCount" | "maxBytes";
+  }>;
+  /** Reports left in place. */
+  kept: number;
+  /** Bytes freed by the deleted reports. */
+  freedBytes: number;
+  /** Leftover temporary directories from interrupted saves that were deleted. */
+  removedTemp: number;
+  /** Reports that could not be deleted. */
+  errors: Array<{
+    id: string;
+    message: string;
+  }>;
+}
+interface ReportInput {
+  /** The file path the image was read from, or `null` when it was given as bytes. */
+  path: string | null;
+  sha256: string;
+  width: number;
+  height: number;
+  format: string;
+  /** The image's file name inside the report directory, or `null` when images aren't copied. */
+  file: string | null;
+}
+/** The contents of `report.json`. */
+interface StoredReport {
+  schemaVersion: number;
+  id: string;
+  /** ISO 8601 time the report was saved. */
+  createdAt: string;
+  tool: {
+    name: string;
+    version: string;
+  };
+  inputs: {
+    reference: ReportInput;
+    candidate: ReportInput;
+  };
+  meta: Record<string, ReportMetaValue>;
+  result: CompareResult;
+}
+/** Where a report was written. */
+interface SavedReport {
+  id: string;
+  /** Absolute path of the report directory. */
+  dir: string;
+  files: {
+    json: string;
+    html: string | null;
+    reference: string | null;
+    candidate: string | null;
+  };
+  /** What `retention` deleted, when it was given. */
+  pruned?: PruneResult;
+}
+/** One line of `listReports`. */
+interface ReportSummary {
+  id: string;
+  dir: string;
+  createdAt: string;
+  score: number;
+  differenceCount: number;
+  summary: string;
+  reference: {
+    path: string | null;
+    sha256: string;
+  };
+  candidate: {
+    path: string | null;
+    sha256: string;
+  };
+  meta: Record<string, ReportMetaValue>;
+}
+/**
+ * Save a comparison as a report directory with `report.json`, an offline `report.html`, and
+ * copies of both images. The directory appears complete or not at all.
+ */
+export declare function saveReport(result: CompareResult, reference: ImageInput, candidate: ImageInput, options: SaveReportOptions): Promise<SavedReport>;
+/** Read a saved report from its directory or its `report.json` path. */
+export declare function loadReport(path: string): Promise<StoredReport>;
+/** List the reports in `dir`, newest first. Directories without a readable report are skipped. */
+export declare function listReports(dir: string, options?: {
+  limit?: number;
+}): Promise<ReportSummary[]>;
+/**
+ * Delete old reports from `dir` by age, count and total size, oldest first. Only directories
+ * holding a readable `report.json` are touched; anything else in `dir` is left alone.
+ */
+export declare function pruneReports(dir: string, options: PruneOptions): Promise<PruneResult>;
+//#endregion
+//#region src/resize.d.ts
+/** Longest side, in pixels, the TypeSafe API accepts; larger images are rejected. */
+export declare const API_MAX_DIMENSION = 1568;
+/** How images are downscaled before upload. */
+interface ResizeOptions {
+  /** Longest side in pixels, at most 1568 (the API's limit). Default: 1568. */
+  maxDimension?: number;
+  /** Most pixels (width × height) to send; fewer pixels use fewer tokens. Default: 1,150,000. */
+  maxPixels?: number;
+  /** JPEG quality, 1–100, when a JPEG is re-encoded. Default: 90. */
+  quality?: number;
+}
+/** Image bytes ready to upload, with the size actually sent. */
+interface PreparedImage {
+  readonly bytes: Uint8Array;
+  readonly width: number;
+  readonly height: number;
+  readonly resized: boolean;
+}
+/** The size to send an image at, keeping its aspect ratio, or `null` when it already fits. */
+export declare function targetSize(width: number, height: number, options?: ResizeOptions): {
+  width: number;
+  height: number;
+} | null;
+/** Downscale `img` to fit `options`, re-encoding it in its own format; small images pass through. */
+export declare function prepareImage(img: LoadedImage, options?: ResizeOptions): PreparedImage;
+//#endregion
+//#region src/prompts.d.ts
+type Locale = "zh" | "en";
+/** What kind of difference was found. */
+type DifferenceType = "element_missing" | "content_missing" | "background_missing" | "element_extra" | "text_changed" | "color_changed" | "moved" | "resized" | "font_changed" | "icon_changed" | "style_changed";
+/** What kind of element the difference is on. */
+type ElementType = "text" | "button" | "container" | "icon" | "image" | "input" | "navigation" | "other";
+//#endregion
+//#region src/compare.d.ts
+/** A box as fractions (0–1) of the image's width and height. */
+interface NormalizedBox {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+/** A box in pixels of the image it refers to. */
+interface PixelBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+/** One located difference between the reference and the candidate. */
+interface Difference {
+  /** Rank, starting at 1 for the most significant difference. */
+  rank: number;
+  type: DifferenceType;
+  /** Localized label for `type`. */
+  typeLabel: string;
+  element: ElementType;
+  /** Localized label for `element`. */
+  elementLabel: string;
+  /** Localized fix suggestion. */
+  suggestion: string;
+  /** Probability, 0–1, that this difference exists. */
+  probability: number;
+  /** Confidence, 0–1, in the classified `type`. */
+  typeConfidence: number;
+  /** Where the difference is in the candidate image. */
+  box: NormalizedBox;
+  boxPx: PixelBox;
+  /** Confidence, 0–1, in `box`, or `null` when not reported. */
+  boxConfidence: number | null;
+  /** Where the difference is in the reference image. */
+  referenceBox: NormalizedBox;
+  referenceBoxPx: PixelBox;
+}
+/** A kind of difference detected somewhere in the image, with no location. */
+interface Issue {
+  type: DifferenceType;
+  label: string;
+  /** Probability, 0–1, that this kind of difference is present. */
+  probability: number;
+  suggestion: string;
+}
+interface CompareResult {
+  /** Similarity score from 1 (completely different) to 10 (identical), one decimal place. */
+  score: number;
+  /** The model's confidence, 0–1, in the holistic score. */
+  scoreConfidence: number;
+  /** The judgments `score` is combined from; see `combineScore`. */
+  scoreBreakdown: ScoreBreakdown;
+  /** Probability, 0–1, that the images are visually identical. */
+  identicalProbability: number;
+  /** `true` when `identicalProbability` reaches the threshold and no differences were located. */
+  identical: boolean;
+  /** One-line localized summary. */
+  summary: string;
+  /** Located differences, most significant first. */
+  differences: Difference[];
+  /** Kinds of difference detected over the whole image, most likely first. */
+  issues: Issue[];
+  /** Original sizes, which pixel boxes refer to, and the sizes sent after downscaling. */
+  images: {
+    reference: ImageSummary;
+    candidate: ImageSummary;
+  };
+  model: string;
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+  };
+  /** Language of the labels, suggestions and summary. */
+  locale: Locale;
+  /** API requests this comparison needed, and how many were answered from the cache. */
+  requests: {
+    total: number;
+    cached: number;
+  };
+  /** Where the report was saved, when the `report` option was given. */
+  report?: SavedReport;
+}
+interface ScoreBreakdown {
+  /** How closely the images match overall, 1–10, on a rubric anchored with examples. */
+  holistic: number;
+  /** How little of the image differs, 1–10, mapped from the estimated fraction that differs. */
+  extent: number;
+  /** Probability, 0–1, that the images are visually identical. */
+  identicalProbability: number;
+}
+/**
+ * Combine the two judgments into the 1–10 score. Each covers the other's blind spot: the
+ * holistic rubric tells "same layout, different colors" apart from "unrelated", while extent
+ * keeps a small local difference from dragging the score down as far as a large one. The
+ * mean is then pulled toward 10 by how likely the images are identical, since neither scale
+ * fully commits to its top step.
+ */
+export declare function combineScore(b: ScoreBreakdown): number;
+/** Map the expected extent bucket (0 = none … 5 = most of the image) to 1–10, interpolating. */
+export declare function extentScore(bucket: number): number;
+interface ImageSummary {
+  width: number;
+  height: number;
+  format: string;
+  /** Size sent to the API; smaller than `width` × `height` when the image was downscaled. */
+  sentWidth: number;
+  sentHeight: number;
+  resized: boolean;
+}
+interface CompareOptions {
+  /** TypeSafe API key. Default: `JEV_KEY`, then `TYPESAFE_API_KEY`. */
+  apiKey?: string;
+  /** Model name. `box` questions need `jev-preview`. Default: `jev-preview`. */
+  model?: string;
+  /** Language of labels, suggestions and summary. Default: `zh`. */
+  locale?: Locale;
+  /** How many ranked differences to look for, 0–8. Default: 4. */
+  maxDifferences?: number;
+  /** Minimum probability, 0–1, for a difference or issue to be reported. Default: 0.5. */
+  threshold?: number;
+  /**
+   * Look again at each difference found: classify it more precisely and widen its boxes to the
+   * whole affected element. Costs one extra request per difference, sent in parallel. Default: true.
+   */
+  refine?: boolean;
+  /** Extra context for the model, such as "a mobile app screen; ignore the status bar". */
+  context?: string;
+  /**
+   * How images are downscaled before upload. The API rejects images whose longest side is over
+   * 1568 px, and tokens grow with pixel count. Boxes are returned in the original images' pixels
+   * either way. `false` sends the original bytes. Default: longest side 1568, at most 1.15 MP.
+   */
+  resize?: ResizeOptions | false;
+  /** An existing client to use instead of creating one. It must send the image opt-in header. */
+  client?: TypeSafeClient;
+  /** Options for the created client, such as `baseURL`, `timeout` or a proxy-aware `fetch`. */
+  clientOptions?: TypeSafeClientConfig;
+  /**
+   * Cache API answers: a directory for an on-disk cache, or any `CacheStore`, such as
+   * `memoryCache()` or `fileCache({ dir, ttl })`. Requests are keyed by everything they send
+   * (images, model, prompt and questions), so changing `locale` reuses every answer, and
+   * changing other options reuses the ones that still apply. Default: no cache.
+   */
+  cache?: CacheStore | string | false;
+  /**
+   * Save a report after comparing: a directory to save into, or report options.
+   * The result's `report` says where it was written.
+   */
+  report?: string | SaveReportOptions;
+  /** Cancels the comparison. */
+  signal?: AbortSignal;
+}
+/** Create a client configured for image comparison. */
+export declare function createClient(options?: Pick<CompareOptions, "apiKey" | "clientOptions">): TypeSafeClient;
+/**
+ * Compare a candidate image against a reference image.
+ *
+ * Returns a 1–10 similarity score, the located differences with boxes in both images,
+ * and a fix suggestion for each.
+ */
+export declare function compareImages(reference: ImageInput, candidate: ImageInput, options?: CompareOptions): Promise<CompareResult>;
+/** Convert a fractional box to pixels of `img`. */
+export declare function toPixels(box: NormalizedBox, img: {
+  width: number;
+  height: number;
+}): PixelBox;
+/** Intersection over union of two fractional boxes. */
+export declare function iou(a: NormalizedBox, b: NormalizedBox): number;
+//#endregion
+//#region src/annotate.d.ts
+interface AnnotateOptions {
+  /** Which image the boxes are drawn on. Default: `candidate`. */
+  target?: "candidate" | "reference";
+  /** Box stroke color. Default: `#ff3b30`. */
+  color?: string;
+}
+/**
+ * Render an SVG of the image with each difference outlined and numbered by rank.
+ * The image is embedded, so the SVG can be saved and opened on its own.
+ */
+export declare function annotateDifferences(img: ImageInput, result: CompareResult, options?: AnnotateOptions): Promise<string>;
+//#endregion
+//#region src/report-html.d.ts
+/** Render a report as one self-contained HTML page, with both images embedded. */
+export declare function renderReportHtml(report: StoredReport, reference: LoadedImage, candidate: LoadedImage): string;
+//#endregion
+export type { AnnotateOptions, CachePruneResult, CacheStore, CompareOptions, CompareResult, Difference, DifferenceType, ElementType, FileCache, FileCacheOptions, ImageFormat, ImageInput, ImageSummary, Issue, LoadedImage, Locale, MemoryCache, MemoryCacheOptions, NormalizedBox, PixelBox, PreparedImage, PruneOptions, PruneResult, ReportFormat, ReportInput, ReportMetaValue, ReportSummary, ResizeOptions, RetentionPolicy, SaveReportOptions, SavedReport, ScoreBreakdown, StoredReport };