@buildinternet/uploads 0.30.0 → 0.31.0

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/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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,
@@ -31,6 +31,7 @@
   "files": [
     "bin",
     "dist",
+    "assets",
     "README.md"
   ],
   "engines": {
@@ -57,6 +58,9 @@
   },
   "dependencies": {
     "exif-reader": "^2.0.3",
+    "opentype.js": "^2.0.0",
+    "perfect-freehand": "^1.2.3",
+    "roughjs": "^4.6.6",
     "sharp": "^0.35.3"
   },
   "optionalDependencies": {