@buildinternet/uploads 0.29.0 → 0.31.0

package/dist/commands/screenshot.d.ts

@@ -1,6 +1,19 @@
 import { type CliContext } from "../commands.js";
 import { type CommandRunner } from "../github-gh.js";
 import { captureScreenshot } from "../screenshot.js";
+/**
+ * The slice of `../annotate/index.js` this command needs. Typed against the
+ * real module (so signatures stay honest) but loaded only via dynamic
+ * `import()` — never statically — to keep sharp/roughjs out of any bundle
+ * that pulls in commands/screenshot.ts. Injectable for tests as
+ * `loadAnnotateModule`, mirroring the `captureLocalImpl`-style seams
+ * elsewhere in this file's tests.
+ */
+export type AnnotateModule = Pick<typeof import("../annotate/index.js"), "validateSpec" | "hasSelectors" | "specSelectors" | "resolveSelectors" | "renderAnnotations" | "clampReport" | "AnnotateSpecError">;
 export declare function runScreenshot(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner, 
 /** Injectable for tests — avoids launching a real browser or hitting the network. */
-captureImpl?: typeof captureScreenshot): Promise<number>;
+captureImpl?: typeof captureScreenshot, 
+/** Injectable for tests — avoids depending on a real stdin stream. */
+readStdinImpl?: () => Promise<string>, 
+/** Injectable for tests — avoids depending on sharp/roughjs. */
+loadAnnotateModule?: () => Promise<AnnotateModule>): Promise<number>;

package/dist/commands/screenshot.js

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
-import { flagBool, flagInt, flagString, flagValues, parseCommandArgs, UsageError, } from "../cli-args.js";
+import { extractDashValue, flagBool, flagInt, flagString, flagValues, parseCommandArgs, UsageError, } from "../cli-args.js";
 import { writeCommandHelp } from "../cli-style.js";
 import { branchFromFlags, derivedMetaEnabled, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, stateAppMetaFromFlags, warnNearMissMeta, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, resolvePutStagingTarget, putStagingNoteText, resolveStageBindingWarning, mergeStagingMeta, } from "../commands.js";
 import { resolvePutDefaults } from "../config.js";
@@ -12,7 +12,7 @@ import { safeCaptureFacts } from "../capture-facts.js";
 import { parseMetaFlags, validateMetaMap } from "../metadata.js";
 import { mergeDerivedMeta } from "../metadata-vocab.js";
 import { writeSidecarMeta } from "../sidecar.js";
-import { writeJson, writeStdout } from "../io.js";
+import { readStdin, writeJson, writeStdout } from "../io.js";
 import { assertHideSelector, captureScreenshot, parseViewport, parseWaitUntil, } from "../screenshot.js";
 const SCREENSHOT_HELP = `uploads screenshot <target> [options]
 
@@ -61,6 +61,12 @@ Options:
                             on --via remote — neutralizes animations via injected CSS)
   --eval <js>               Run JS in the page after settle, before capture (--via local only)
   --init-script <file>      Inject a JS file before navigation (--via local only)
+  --annotate <file|->       Bake hand-drawn boxes, arrows, labels, and redactions from a JSON
+                            annotation spec onto the capture before upload (file path or - for
+                            stdin; see the annotate-screenshots skill for the spec format). Specs
+                            that target a CSS selector instead of pixel coordinates need a live
+                            page to resolve, so they require --via local (or auto resolving to
+                            local) — a selector spec on the remote backend is rejected up front.
   --out <file>              Also write the PNG to a local file. Also writes a sidecar manifest,
                             <file>.uploads.json, recording this capture's derived metadata
                             (path/url/env/viewport, plus --state if given) with a content hash; a
@@ -110,6 +116,7 @@ Examples:
   uploads screenshot https://uploads.sh --pr 128 --comment
   uploads screenshot ./card.html --no-upload --out ./card.png
   uploads screenshot https://app.example/settings --branch
+  uploads screenshot http://localhost:3000 --via local --annotate ./callouts.json
 `;
 function colorSchemeFromFlags(flags) {
     const dark = flagBool(flags, "--dark");
@@ -132,12 +139,17 @@ function viaFromFlags(flags, fallback) {
 }
 export async function runScreenshot(ctx, args, help = false, run = execRunner, 
 /** Injectable for tests — avoids launching a real browser or hitting the network. */
-captureImpl = captureScreenshot) {
+captureImpl = captureScreenshot, 
+/** Injectable for tests — avoids depending on a real stdin stream. */
+readStdinImpl = readStdin, 
+/** Injectable for tests — avoids depending on sharp/roughjs. */
+loadAnnotateModule = () => import("../annotate/index.js")) {
     if (help) {
         writeCommandHelp(SCREENSHOT_HELP);
         return 0;
     }
-    const parsed = parseCommandArgs(args);
+    const { args: preArgs, dash: annotateFromDash } = extractDashValue(args, "--annotate");
+    const parsed = parseCommandArgs(preArgs);
     if (parsed.help) {
         writeCommandHelp(SCREENSHOT_HELP);
         return 0;
@@ -182,6 +194,61 @@ captureImpl = captureScreenshot) {
             throw new UsageError(`could not read --init-script ${initScriptPath}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    // Parse + validate the annotation spec (if any) before capturing anything —
+    // fail fast rather than burning a browser launch / render-endpoint budget
+    // hit on a spec that was never going to work.
+    const annotateArg = annotateFromDash ? "-" : flagString(parsed.flags, "--annotate");
+    let annotateModule;
+    let annotateSpec;
+    let annotateSelectors = [];
+    if (annotateArg !== undefined) {
+        annotateModule = await loadAnnotateModule();
+        let specText;
+        if (annotateArg === "-") {
+            specText = await readStdinImpl();
+        }
+        else {
+            try {
+                specText = readFileSync(annotateArg, "utf8");
+            }
+            catch (err) {
+                throw new UsageError(`could not read --annotate ${annotateArg}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        let specJson;
+        try {
+            specJson = JSON.parse(specText);
+        }
+        catch (err) {
+            throw new UsageError(`--annotate spec is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            annotateSpec = annotateModule.validateSpec(specJson);
+        }
+        catch (err) {
+            if (err instanceof annotateModule.AnnotateSpecError) {
+                const lines = err.errors.map((e) => e.index === null ? e.message : `annotations[${e.index}]: ${e.message}`);
+                throw new UsageError(`--annotate spec is invalid: ${lines.join("; ")}`);
+            }
+            throw err;
+        }
+        annotateSelectors = annotateModule.specSelectors(annotateSpec);
+        // The remote render endpoint has no eval escape hatch to measure a live
+        // selector — fail fast on an explicit --via remote rather than let the
+        // capture succeed and only then discover the annotation step can't
+        // resolve. (auto resolving to remote is caught below, after capture,
+        // once the actual backend is known.)
+        if (annotateSelectors.length > 0 && via === "remote") {
+            throw new UsageError("selector annotations need --via local in v1");
+        }
+        // An element capture (--selector) crops the PNG to the element, but the
+        // annotation boxes are measured in viewport coordinates (and playwright
+        // may scroll the element into view first) — the two coordinate systems
+        // don't line up, so annotations would land in the wrong place.
+        if (annotateSelectors.length > 0 && selector) {
+            throw new UsageError("--annotate with selector targets cannot combine with --selector element capture; use pixel coordinates or capture the full viewport");
+        }
+    }
     const outFile = flagString(parsed.flags, "--out");
     const noUpload = flagBool(parsed.flags, "--no-upload");
     if (noUpload && !outFile)
@@ -313,21 +380,48 @@ captureImpl = captureScreenshot) {
         reducedMotion,
         evalJs,
         initScript,
+        measureSelectors: annotateSelectors.length > 0 ? annotateSelectors : undefined,
         apiUrl: ctx.config.apiUrl,
         token: ctx.config.token,
     });
     if (logHuman)
         process.stderr.write(`>> captured via ${captured.backend} backend\n`);
+    // Resolve selectors + render annotations before the frame/optimize/upload
+    // pipeline runs — everything downstream (the --out write, the sidecar
+    // hash, and the upload itself) should see the annotated bytes.
+    let finalPng = captured.png;
+    if (annotateModule && annotateSpec) {
+        let resolvedSpec = annotateSpec;
+        if (annotateSelectors.length > 0) {
+            // Covers auto-routing landing on remote: the explicit --via remote
+            // case already failed fast above, before capture.
+            if (captured.backend !== "local") {
+                throw new UsageError("selector annotations need --via local in v1");
+            }
+            try {
+                resolvedSpec = annotateModule.resolveSelectors(annotateSpec, captured.measures ?? {});
+            }
+            catch (err) {
+                if (err instanceof annotateModule.AnnotateSpecError) {
+                    throw new UsageError(`--annotate: ${err.errors.map((e) => e.message).join("; ")}`);
+                }
+                throw err;
+            }
+        }
+        finalPng = await annotateModule.renderAnnotations(captured.png, resolvedSpec);
+        if (logHuman)
+            process.stderr.write(">> annotated\n");
+    }
     if (outFile) {
-        writeFileSync(outFile, captured.png);
+        writeFileSync(outFile, finalPng);
         if (logHuman)
             process.stderr.write(`>> wrote ${outFile}\n`);
         if (!noSidecar)
-            writeSidecarMeta(outFile, captured.png, withFacts);
+            writeSidecarMeta(outFile, finalPng, withFacts);
     }
     if (noUpload) {
         if (ctx.json) {
-            await writeJson({ file: outFile, backend: captured.backend, size: captured.png.byteLength });
+            await writeJson({ file: outFile, backend: captured.backend, size: finalPng.byteLength });
         }
         else {
             await writeStdout(`FILE: ${outFile}\n`);
@@ -340,7 +434,7 @@ captureImpl = captureScreenshot) {
         ? ghBranchAttachmentKey(stagingTarget.repo, stagingTarget.branch, captured.filename)
         : undefined;
     const alt = altFlag ?? basename(captured.filename);
-    const { result, prepared, markdown } = await uploadPreparedImage(ctx.client, captured.png, captured.filename, {
+    const { result, prepared, markdown } = await uploadPreparedImage(ctx.client, finalPng, captured.filename, {
         frame: frameOpts,
         optimize: optimizeOpts,
         ghTarget,

package/dist/commands.d.ts

@@ -123,6 +123,13 @@ export interface UploadPreparedImageResult {
     result: PutResult;
     prepared: PreparedUpload;
     markdown: string;
+    /**
+     * The queryable metadata this upload actually sent — `opts.metadata` after
+     * any derived image facts were merged in. Callers that need to reason about
+     * what was stored (see `pathMetaHintFor`) must read this, not
+     * `result.metadata`, which is the API's R2 provenance echo.
+     */
+    sentMetadata?: Record<string, string>;
 }
 /**
  * Shared bytes-oriented upload tail: frame + optimize the bytes, resolve the
@@ -182,15 +189,22 @@ export declare function syncAttachmentsComment(client: UploadsClient, target: Gh
  * (same tier as `state=`), and unlike `uploads screenshot` (which derives it
  * from the captured URL), a plain `attach`/`put --pr`/`put --issue` of an
  * already-existing image has nothing to derive it from, so it's easy to
- * forget. Fires once per batch (not per file) — checks the metadata the
- * server actually stored (`PutResult.metadata`), not what was requested, so
- * a merge/validation drop still surfaces the gap. Non-image uploads (zips,
+ * forget. Fires once per batch (not per file). Non-image uploads (zips,
  * PDFs, etc.) are exempt — "findable by page" doesn't apply to them.
+ *
+ * Checks the *resolved* metadata each upload actually sent (`--meta` pairs +
+ * sidecar manifest + derived image facts, index-aligned with `uploads`) —
+ * NOT `PutResult.metadata`. That field is the API's echo of the object's R2
+ * provenance bag (`client`, `source-name`, `content-sha256`, `uploaded-at`),
+ * never the queryable D1 tags, so it can't answer this question: reading it
+ * made the tip fire on every image, including ones uploaded with an explicit
+ * `--meta path=` (PR #509).
  */
-export declare function pathMetaHintFor(uploads: {
+export declare function pathMetaHintFor(uploads: readonly {
     contentType: string;
-    metadata?: Record<string, string>;
-}[]): string | undefined;
+}[], 
+/** Index-aligned with `uploads` — see `uploadPuts`/`uploadAttachments`. */
+sentMetadata: readonly (Record<string, string> | undefined)[]): string | undefined;
 export type AttachUploadItem = PutResult & {
     file: string;
     markdown: string;
@@ -211,6 +225,20 @@ export type AttachFailure = {
         status?: number;
     };
 };
+/** Shared shape of every prepare + put batch (`uploadPuts`/`uploadAttachments`). */
+export interface UploadBatchResult<T> {
+    uploads: T[];
+    failures: AttachFailure[];
+    /** The original cause of the first failure — for rethrowing single-file CLI paths. */
+    firstError?: unknown;
+    /**
+     * Index-aligned with `uploads`: the queryable metadata each upload actually
+     * sent (flags + sidecar + derived image facts). Kept beside the items rather
+     * than on them so it stays out of the `--format json` upload objects, which
+     * spread the item wholesale. See `pathMetaHintFor`.
+     */
+    sentMetadata: (Record<string, string> | undefined)[];
+}
 /**
  * Prepare + put each path as a PR/issue attachment with bounded concurrency.
  * Per-file errors collect in `failures` (does not throw). `firstError` is the
@@ -233,11 +261,7 @@ export declare function uploadAttachments(opts: {
     /** Provenance `client` field (default uploads-cli). */
     provenanceClient?: string;
     concurrency?: number;
-}): Promise<{
-    uploads: AttachUploadItem[];
-    failures: AttachFailure[];
-    firstError?: unknown;
-}>;
+}): Promise<UploadBatchResult<AttachUploadItem>>;
 /** A branch to stage attachments against pre-PR (`uploads attach --branch`). */
 export interface BranchTarget {
     repo: string;
@@ -266,11 +290,7 @@ export declare function uploadBranchAttachments(opts: {
     deriveImageFacts?: boolean;
     provenanceClient?: string;
     concurrency?: number;
-}): Promise<{
-    uploads: AttachUploadItem[];
-    failures: AttachFailure[];
-    firstError?: unknown;
-}>;
+}): Promise<UploadBatchResult<AttachUploadItem>>;
 export type PutUploadItem = PutResult & {
     file: string;
     markdown: string;
@@ -317,11 +337,7 @@ export declare function uploadPuts(opts: {
     alt?: string;
     width?: number;
     concurrency?: number;
-}): Promise<{
-    uploads: PutUploadItem[];
-    failures: AttachFailure[];
-    firstError?: unknown;
-}>;
+}): Promise<UploadBatchResult<PutUploadItem>>;
 export declare function runAttach(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 /**
  * One source of truth for the "staged, but not going to auto-attach" advisory

package/dist/commands.js

@@ -410,7 +410,7 @@ export async function uploadPreparedImage(client, bytes, sourceName, opts) {
         alt: opts.alt(prepared),
         width: opts.width,
     });
-    return { result, prepared, markdown };
+    return { result, prepared, markdown, sentMetadata: metadata };
 }
 export function frameOptionsFromFlags(flags) {
     const raw = flagString(flags, "--frame");
@@ -647,13 +647,21 @@ Examples:
  * (same tier as `state=`), and unlike `uploads screenshot` (which derives it
  * from the captured URL), a plain `attach`/`put --pr`/`put --issue` of an
  * already-existing image has nothing to derive it from, so it's easy to
- * forget. Fires once per batch (not per file) — checks the metadata the
- * server actually stored (`PutResult.metadata`), not what was requested, so
- * a merge/validation drop still surfaces the gap. Non-image uploads (zips,
+ * forget. Fires once per batch (not per file). Non-image uploads (zips,
  * PDFs, etc.) are exempt — "findable by page" doesn't apply to them.
+ *
+ * Checks the *resolved* metadata each upload actually sent (`--meta` pairs +
+ * sidecar manifest + derived image facts, index-aligned with `uploads`) —
+ * NOT `PutResult.metadata`. That field is the API's echo of the object's R2
+ * provenance bag (`client`, `source-name`, `content-sha256`, `uploaded-at`),
+ * never the queryable D1 tags, so it can't answer this question: reading it
+ * made the tip fire on every image, including ones uploaded with an explicit
+ * `--meta path=` (PR #509).
  */
-export function pathMetaHintFor(uploads) {
-    const missingPath = uploads.some((u) => u.contentType.startsWith("image/") && !u.metadata?.path);
+export function pathMetaHintFor(uploads, 
+/** Index-aligned with `uploads` — see `uploadPuts`/`uploadAttachments`. */
+sentMetadata) {
+    const missingPath = uploads.some((u, i) => u.contentType.startsWith("image/") && !sentMetadata[i]?.path);
     return missingPath ? "tip: add --meta path=/route so this shot is findable by page" : undefined;
 }
 /**
@@ -697,6 +705,7 @@ async function uploadAttachmentBatch(opts) {
             });
             return {
                 ok: true,
+                sentMetadata: metadata,
                 upload: {
                     ...result,
                     file,
@@ -719,17 +728,21 @@ async function uploadAttachmentBatch(opts) {
         }
     });
     const uploads = [];
+    const sentMetadata = [];
     const failures = [];
     let firstError;
     for (const slot of slots) {
-        if (slot.ok)
+        // Pushed together so the two arrays stay index-aligned across failures.
+        if (slot.ok) {
             uploads.push(slot.upload);
+            sentMetadata.push(slot.sentMetadata);
+        }
         else {
             firstError ??= slot.err;
             failures.push({ file: slot.file, error: errorDetail(slot.err) });
         }
     }
-    return { uploads, failures, firstError };
+    return { uploads, failures, firstError, sentMetadata };
 }
 /**
  * Prepare + put each path as a PR/issue attachment with bounded concurrency.
@@ -786,7 +799,7 @@ export async function uploadPuts(opts) {
             // Sidecar manifest from a prior `screenshot --out` of this exact file
             // (issue #469 lever 2) — see mergeSidecarMeta. Not applicable to stdin.
             const metadata = file !== "-" ? mergeSidecarMeta(file, bytes, opts.metadata) : opts.metadata;
-            const { result, prepared, markdown } = await uploadPreparedImage(opts.client, bytes, sourceName, {
+            const { result, prepared, markdown, sentMetadata } = await uploadPreparedImage(opts.client, bytes, sourceName, {
                 frame: opts.frame,
                 optimize: opts.optimize,
                 ghTarget: opts.ghTarget,
@@ -807,6 +820,7 @@ export async function uploadPuts(opts) {
             });
             return {
                 ok: true,
+                sentMetadata,
                 upload: {
                     ...result,
                     file,
@@ -827,17 +841,21 @@ export async function uploadPuts(opts) {
         }
     });
     const uploads = [];
+    const sentMetadata = [];
     const failures = [];
     let firstError;
     for (const slot of slots) {
-        if (slot.ok)
+        // Pushed together so the two arrays stay index-aligned across failures.
+        if (slot.ok) {
             uploads.push(slot.upload);
+            sentMetadata.push(slot.sentMetadata);
+        }
         else {
             firstError ??= slot.err;
             failures.push({ file: slot.file, error: errorDetail(slot.err) });
         }
     }
-    return { uploads, failures, firstError };
+    return { uploads, failures, firstError, sentMetadata };
 }
 /**
  * Best-effort call to `POST /v1/:workspace/github/promote` (server contract,
@@ -931,7 +949,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
         const n = parsed.positionals.length;
         process.stderr.write(`>> uploading ${n} file${n === 1 ? "" : "s"}\n`);
     }
-    const { uploads, failures, firstError } = await uploadAttachments({
+    const { uploads, failures, firstError, sentMetadata } = await uploadAttachments({
         client: ctx.client,
         target,
         files: parsed.positionals,
@@ -979,7 +997,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
         }
     }
     // Lever 3 (issue #469): tip when an image lands here with no `path` meta.
-    const pathHint = uploads.length > 0 && !ctx.quiet ? pathMetaHintFor(uploads) : undefined;
+    const pathHint = uploads.length > 0 && !ctx.quiet ? pathMetaHintFor(uploads, sentMetadata) : undefined;
     if (ctx.json) {
         await writeJson({
             target,
@@ -1672,7 +1690,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         if (attachedRef)
             process.stderr.write(`>> attached to ${attachedRef}\n`);
     }
-    const { uploads, failures, firstError } = await uploadPuts({
+    const { uploads, failures, firstError, sentMetadata } = await uploadPuts({
         client: ctx.client,
         files,
         nameOverride: nameFlag,
@@ -1707,7 +1725,9 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     // `path` meta. Only relevant on the ghTarget path — the bare-put paths
     // above (staging/auto/dated) aren't attached to a PR/issue yet, so there's
     // nothing to look up from a page later.
-    const pathHint = ghTarget && uploads.length > 0 && !ctx.quiet ? pathMetaHintFor(uploads) : undefined;
+    const pathHint = ghTarget && uploads.length > 0 && !ctx.quiet
+        ? pathMetaHintFor(uploads, sentMetadata)
+        : undefined;
     // One JSON `hint` slot, shared with the #393 nudge (mutually exclusive with
     // it — nudge is undefined whenever staging took over). When staging fires,
     // prefer the more actionable binding warning over the generic staging note

package/dist/io.d.ts

@@ -1,3 +1,5 @@
 /** Backpressure-aware stdout helpers shared by the CLI commands and the stdio MCP transport. */
 export declare function writeStdout(text: string): Promise<void>;
 export declare function writeJson(value: unknown): Promise<void>;
+/** Reads stdin to end as UTF-8 (the `--flag -` convention). */
+export declare function readStdin(): Promise<string>;

package/dist/io.js

@@ -7,3 +7,11 @@ export async function writeStdout(text) {
 export async function writeJson(value) {
     await writeStdout(JSON.stringify(value, null, 2) + "\n");
 }
+/** Reads stdin to end as UTF-8 (the `--flag -` convention). */
+export async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}

package/dist/screenshot-local.d.ts

@@ -59,6 +59,13 @@ export interface LocalCaptureOptions {
     evalJs?: string;
     /** JS injected via addInitScript before navigation. */
     initScript?: string;
+    /**
+     * CSS selectors to measure (getBoundingClientRect, scaled to device pixels)
+     * after settle, before capture — for resolving annotation-spec selectors.
+     * Every selector must match exactly one element; a miss throws naming the
+     * selector (no silent skips).
+     */
+    measureSelectors?: string[];
     timeoutMs?: number;
     detectRoots?: DetectRoots;
     /**
@@ -68,5 +75,29 @@ export interface LocalCaptureOptions {
      */
     detectResult?: DetectResult;
 }
+/** A measured element box in device (raster) pixels — CSS pixels × deviceScaleFactor. */
+export interface MeasuredBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Minimal page shape this needs — matches playwright-core's `Page.evaluate`. */
+interface EvaluatablePage {
+    evaluate<T>(fn: (selectors: string[]) => T, arg: string[]): Promise<T>;
+}
+/**
+ * Measures each selector's getBoundingClientRect on the page in a single
+ * `page.evaluate` round-trip, scaling CSS pixels to device (raster) pixels so
+ * the resulting boxes line up with the captured PNG. Throws `UploadsError`
+ * naming any selector that matches zero elements or more than one — an
+ * ambiguous selector would silently measure the first match and place the
+ * annotation confidently in the wrong spot.
+ */
+export declare function measureSelectorBoxes(page: EvaluatablePage, selectors: readonly string[], scale: number): Promise<Record<string, MeasuredBox>>;
 /** Capture a PNG screenshot using a local (already-installed) browser. */
-export declare function captureLocal(opts: LocalCaptureOptions): Promise<Uint8Array>;
+export declare function captureLocal(opts: LocalCaptureOptions): Promise<{
+    png: Uint8Array;
+    measures?: Record<string, MeasuredBox>;
+}>;
+export {};

package/dist/screenshot-local.js

@@ -203,6 +203,36 @@ export function detectLocalBrowser(roots = {}) {
     const winner = [...candidates].toSorted((a, b) => rank(a) - rank(b))[0];
     return { envOverride, candidates, winner };
 }
+/**
+ * Measures each selector's getBoundingClientRect on the page in a single
+ * `page.evaluate` round-trip, scaling CSS pixels to device (raster) pixels so
+ * the resulting boxes line up with the captured PNG. Throws `UploadsError`
+ * naming any selector that matches zero elements or more than one — an
+ * ambiguous selector would silently measure the first match and place the
+ * annotation confidently in the wrong spot.
+ */
+export async function measureSelectorBoxes(page, selectors, scale) {
+    if (selectors.length === 0)
+        return {};
+    const boxes = await page.evaluate((sels) => sels.map((selector) => {
+        const matches = document.querySelectorAll(selector);
+        if (matches.length !== 1)
+            return { count: matches.length };
+        const r = matches[0].getBoundingClientRect();
+        return { x: r.x, y: r.y, w: r.width, h: r.height };
+    }), [...selectors]);
+    const measures = {};
+    selectors.forEach((sel, i) => {
+        const box = boxes[i];
+        if ("count" in box) {
+            throw new UploadsError(box.count === 0
+                ? `--annotate selector matched no element: ${sel}`
+                : `--annotate selector is ambiguous (${box.count} matches): ${sel}`, "USAGE");
+        }
+        measures[sel] = { x: box.x * scale, y: box.y * scale, w: box.w * scale, h: box.h * scale };
+    });
+    return measures;
+}
 async function loadPlaywrightCore() {
     try {
         // Dynamic import only — never hoist this to a static `import` statement.
@@ -316,11 +346,14 @@ export async function captureLocal(opts) {
         }
         if (opts.evalJs)
             await page.evaluate(opts.evalJs);
+        const measures = opts.measureSelectors && opts.measureSelectors.length > 0
+            ? await measureSelectorBoxes(page, opts.measureSelectors, opts.viewport.deviceScaleFactor)
+            : undefined;
         const png = opts.selector
             ? await page.locator(opts.selector).screenshot({ timeout: opts.timeoutMs ?? 30_000 })
             : await page.screenshot({ fullPage: opts.fullPage === true });
         // Buffer extends Uint8Array — return it as-is rather than copying.
-        return png;
+        return { png, measures };
     }
     finally {
         await browser.close();

package/dist/screenshot.d.ts

@@ -48,6 +48,13 @@ export type ScreenshotTarget = {
 export declare function isPrivateOrLocalHost(hostname: string): boolean;
 /** Classifies a CLI target: http(s) URL, or a path to a local .html file. */
 export declare function classifyTarget(target: string): ScreenshotTarget;
+/** A measured element box in device (raster) pixels — CSS pixels × deviceScaleFactor. */
+export interface MeasuredBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
 export interface CaptureScreenshotOptions {
     target: string;
     via: ScreenshotBackend;
@@ -71,6 +78,12 @@ export interface CaptureScreenshotOptions {
     evalJs?: string;
     /** Inject this JS as an init script before navigation (local backend only). */
     initScript?: string;
+    /**
+     * CSS selectors to measure (getBoundingClientRect, scaled to device pixels)
+     * before capture, for resolving annotation-spec selectors. Local backend
+     * only — throws if the resolved backend is remote.
+     */
+    measureSelectors?: string[];
     apiUrl: string;
     token: string;
     /** Injectable for tests; forwarded to detectLocalBrowser. */
@@ -89,10 +102,14 @@ export interface CaptureScreenshotOptions {
         reducedMotion?: boolean;
         evalJs?: string;
         initScript?: string;
+        measureSelectors?: string[];
         detectRoots?: DetectRoots;
         /** Pre-computed detection result from auto-routing, to avoid a second fs scan. */
         detectResult?: import("./screenshot-local.js").DetectResult;
-    }) => Promise<Uint8Array>;
+    }) => Promise<{
+        png: Uint8Array;
+        measures?: Record<string, MeasuredBox>;
+    }>;
     /** Injectable for tests: replaces the remote capture implementation. */
     captureRemoteImpl?: typeof captureRemote;
 }
@@ -100,6 +117,8 @@ export interface CaptureScreenshotResult {
     png: Uint8Array;
     filename: string;
     backend: "local" | "remote";
+    /** Present when `measureSelectors` was given and the local backend ran. */
+    measures?: Record<string, MeasuredBox>;
 }
 /**
  * Resolve target + options into PNG bytes via the local or remote backend.

package/dist/screenshot.js

@@ -234,13 +234,20 @@ export async function captureScreenshot(opts) {
     if (backend === "remote" && (opts.evalJs !== undefined || opts.initScript !== undefined)) {
         throw new UploadsError("--eval and --init-script are local-only — use --via local", "USAGE");
     }
+    // Selector-based annotation measurement needs a live local page — the
+    // remote render endpoint has no eval escape hatch to run
+    // getBoundingClientRect. Covers both explicit --via remote and auto
+    // resolving to remote.
+    if (backend === "remote" && opts.measureSelectors && opts.measureSelectors.length > 0) {
+        throw new UploadsError("selector annotations need --via local in v1", "USAGE");
+    }
     if (backend === "local") {
         const captureLocalImpl = opts.captureLocalImpl ??
             (async (localOpts) => {
                 const { captureLocal } = await import("./screenshot-local.js");
                 return captureLocal(localOpts);
             });
-        const png = await captureLocalImpl({
+        const localResult = await captureLocalImpl({
             url: target.kind === "html-file" ? pathToFileURL(target.path).href : target.url,
             browserPath: opts.browserPath,
             cdp: opts.cdp,
@@ -253,10 +260,11 @@ export async function captureScreenshot(opts) {
             reducedMotion: opts.reducedMotion,
             evalJs: opts.evalJs,
             initScript: opts.initScript,
+            measureSelectors: opts.measureSelectors,
             detectRoots: opts.detectRoots,
             detectResult: detected,
         });
-        return { png, filename, backend };
+        return { png: localResult.png, filename, backend, measures: localResult.measures };
     }
     if (target.kind === "html-file") {
         const bytes = new TextEncoder().encode(target.html).byteLength;