@buildinternet/uploads 0.12.1 → 0.13.1

package/dist/client.d.ts

@@ -1,4 +1,6 @@
 import type { UploadsClientConfig } from "./config.js";
+/** Scoped-operator-token permission scope. */
+export type TokenScope = "files:read" | "files:write" | "files:delete" | "operator:read" | "operator:write" | "workspace:invite" | "workspace:manage";
 /** Allowlisted object provenance (maps to X-Uploads-Meta-* on put). */
 export type ProvenanceInput = {
     client?: string;
@@ -212,7 +214,7 @@ export interface EnrollmentExchangeResult {
     apiUrl?: string;
     workspace: string;
     token: string;
-    scopes?: Array<"files:read" | "files:write" | "files:delete">;
+    scopes?: Array<TokenScope>;
     expiresAt?: string;
 }
 export interface EnrollmentCreateResult {
@@ -229,9 +231,16 @@ export declare function createEnrollment(apiUrl: string, adminToken: string, inp
     email?: string;
     enrollmentSeconds?: number;
     tokenExpiresInSeconds?: number;
-    scopes?: Array<"files:read" | "files:write" | "files:delete">;
+    scopes?: Array<TokenScope>;
 }): Promise<EnrollmentCreateResult>;
-/** Static OAuth client id allowlisted by the auth worker's `validateClient`. */
+/**
+ * OAuth client id for the device flow. Registered server-side as a managed
+ * official `oauth_client` row (seeded by apps/auth migration
+ * 20260719000000_seed_cli_oauth_client.sql — issue #251): public PKCE client,
+ * no secret, device-code grant only. The auth worker's device endpoints
+ * validate this id against that table, so operators can disable it from
+ * /admin/oauth. The literal must match the seeded row's client_id.
+ */
 export declare const DEVICE_CLIENT_ID = "uploads-cli";
 /**
  * User-Agent for device-flow requests. Stored on the Better Auth session row
@@ -302,7 +311,7 @@ export declare function createWorkspaceRequest(apiUrl: string, accessToken: stri
 export interface MintTokenResult {
     token: string;
     workspace: string;
-    scopes: Array<"files:read" | "files:write" | "files:delete">;
+    scopes: Array<TokenScope>;
     label: string | null;
     expiresAt: string | null;
 }
@@ -332,7 +341,7 @@ export declare function createWorkspaceInvite(apiUrl: string, accessToken: strin
  */
 export declare function mintWorkspaceToken(apiUrl: string, accessToken: string, input: {
     workspace: string;
-    scopes?: Array<"files:read" | "files:write" | "files:delete">;
+    scopes?: Array<TokenScope>;
     label?: string;
     ttlSeconds?: number;
 }): Promise<MintTokenResult>;

package/dist/client.js

@@ -37,7 +37,14 @@ export function createEnrollment(apiUrl, adminToken, input) {
 // D5). Better Auth's `device.code`/`device.token` endpoints take
 // `application/json` bodies, NOT the RFC's form-encoding — the JSON shapes
 // below are what the worker expects.
-/** Static OAuth client id allowlisted by the auth worker's `validateClient`. */
+/**
+ * OAuth client id for the device flow. Registered server-side as a managed
+ * official `oauth_client` row (seeded by apps/auth migration
+ * 20260719000000_seed_cli_oauth_client.sql — issue #251): public PKCE client,
+ * no secret, device-code grant only. The auth worker's device endpoints
+ * validate this id against that table, so operators can disable it from
+ * /admin/oauth. The literal must match the seeded row's client_id.
+ */
 export const DEVICE_CLIENT_ID = "uploads-cli";
 /**
  * User-Agent for device-flow requests. Stored on the Better Auth session row

package/dist/commands/screenshot.js

@@ -1,4 +1,4 @@
-import { writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
 import { flagBool, flagInt, flagString, flagValues, parseCommandArgs, UsageError, } from "../cli-args.js";
 import { writeCommandHelp } from "../cli-style.js";
@@ -10,7 +10,7 @@ import { ghMetadataFromTarget } from "../github.js";
 import { execRunner } from "../github-gh.js";
 import { parseMetaFlags, validateMetaMap } from "../metadata.js";
 import { writeJson, writeStdout } from "../io.js";
-import { captureScreenshot, parseViewport, parseWaitUntil, } from "../screenshot.js";
+import { assertHideSelector, captureScreenshot, parseViewport, parseWaitUntil, } from "../screenshot.js";
 const SCREENSHOT_HELP = `uploads screenshot <target> [options]
 
 Capture a URL or a local .html file and host it — a hosted, PR-embeddable
@@ -43,6 +43,12 @@ Options:
                             own prefers-color-scheme queries won't flip)
   --wait <load|domcontentloaded|networkidle|ms>  Settle strategy (default: load); a millisecond
                             count is local-only — use --via local
+  --hide <css>              Hide matching elements before capture (repeatable)
+  --no-hide-dev-tools       Don't auto-hide framework dev toolbars (auto-hidden on localhost/private)
+  --reduced-motion          Emulate prefers-reduced-motion: reduce so animations settle (best-effort
+                            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)
   --out <file>              Also write the PNG to a local file
   --no-upload                Skip hosting; requires --out (local file only)
   --destination <id>        Typed root: screenshots | gh | f
@@ -129,6 +135,26 @@ captureImpl = captureScreenshot) {
     const fullPage = flagBool(parsed.flags, "--full-page");
     const colorScheme = colorSchemeFromFlags(parsed.flags);
     const waitUntil = parseWaitUntil(flagString(parsed.flags, "--wait"));
+    const hide = flagValues(parsed.flags, "--hide");
+    // Fail fast before capture, using the shared policy (throws UploadsError
+    // code USAGE → exit 2, same as UsageError) so there's one source of truth.
+    for (const sel of hide)
+        assertHideSelector(sel);
+    // --no-hide-dev-tools opts out of auto-hiding framework toolbars; undefined
+    // lets captureScreenshot apply its localhost-aware default.
+    const hideDevTools = flagBool(parsed.flags, "--no-hide-dev-tools") ? false : undefined;
+    const reducedMotion = flagBool(parsed.flags, "--reduced-motion");
+    const evalJs = flagString(parsed.flags, "--eval");
+    const initScriptPath = flagString(parsed.flags, "--init-script");
+    let initScript;
+    if (initScriptPath !== undefined) {
+        try {
+            initScript = readFileSync(initScriptPath, "utf8");
+        }
+        catch (err) {
+            throw new UsageError(`could not read --init-script ${initScriptPath}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     const outFile = flagString(parsed.flags, "--out");
     const noUpload = flagBool(parsed.flags, "--no-upload");
     if (noUpload && !outFile)
@@ -207,6 +233,11 @@ captureImpl = captureScreenshot) {
         fullPage,
         colorScheme,
         waitUntil,
+        hide,
+        hideDevTools,
+        reducedMotion,
+        evalJs,
+        initScript,
         apiUrl: ctx.config.apiUrl,
         token: ctx.config.token,
     });

package/dist/mcp/server.d.ts

@@ -1,5 +1,6 @@
 export { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, type ToolArgs, } from "./args.js";
 export { ToolBatchError, batchFailureMessage } from "./batch-error.js";
+export { mapBounded } from "../async.js";
 export interface McpTool {
     name: string;
     description: string;

package/dist/mcp/server.js

@@ -12,6 +12,7 @@ import { errorCodeFromUnknown, recordEvent } from "../telemetry.js";
 import { ToolBatchError } from "./batch-error.js";
 export { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
 export { ToolBatchError, batchFailureMessage } from "./batch-error.js";
+export { mapBounded } from "../async.js";
 const SUPPORTED_PROTOCOL_VERSIONS = new Set(["2025-06-18", "2025-03-26", "2024-11-05"]);
 const LATEST_PROTOCOL_VERSION = "2025-06-18";
 function response(id, result) {
@@ -115,7 +116,11 @@ export function createMcpServer(opts) {
                         const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.has(requested)
                             ? requested
                             : LATEST_PROTOCOL_VERSION;
-                        return response(id, { protocolVersion, capabilities: { tools: {} }, serverInfo });
+                        return response(id, {
+                            protocolVersion,
+                            capabilities: { tools: {} },
+                            serverInfo,
+                        });
                     }
                     case "ping":
                         return response(id, {});

package/dist/mcp/tools.js

@@ -546,6 +546,19 @@ export function createUploadsMcpTools(opts) {
                         type: "string",
                         description: 'Settle strategy: load (default) | domcontentloaded | networkidle | a millisecond count (millisecond counts are local-only — via: "local").',
                     },
+                    hide: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "CSS selectors to hide (display:none) before capture. Works on both backends.",
+                    },
+                    noHideDevTools: {
+                        type: "boolean",
+                        description: "Don't auto-hide framework dev toolbars (Astro/Next/Nuxt/Vite), which are hidden by default for localhost/private-network targets.",
+                    },
+                    reducedMotion: {
+                        type: "boolean",
+                        description: 'Emulate prefers-reduced-motion: reduce so animations settle. Best-effort on via: "remote" (neutralizes animations via injected CSS).',
+                    },
                     key: {
                         type: "string",
                         description: "Explicit object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.png). Cannot be combined with pr/issue.",
@@ -684,6 +697,9 @@ export function createUploadsMcpTools(opts) {
                         fullPage: optBool(args, "fullPage"),
                         colorScheme: colorSchemeArg,
                         waitUntil: screenshotModule.parseWaitUntil(optString(args, "wait")),
+                        hide: optStringArray(args, "hide"),
+                        hideDevTools: optBool(args, "noHideDevTools") ? false : undefined,
+                        reducedMotion: optBool(args, "reducedMotion"),
                         apiUrl: config.apiUrl,
                         token: config.token,
                     });

package/dist/screenshot-local.d.ts

@@ -51,6 +51,14 @@ export interface LocalCaptureOptions {
     colorScheme?: "dark" | "light";
     /** "load" | "domcontentloaded" | "networkidle", or a millisecond settle delay. */
     waitUntil: "load" | "domcontentloaded" | "networkidle" | number;
+    /** CSS selectors hidden (display:none) just before capture. */
+    hide?: string[];
+    /** Emulate prefers-reduced-motion: reduce so animations settle deterministically. */
+    reducedMotion?: boolean;
+    /** JS run via page.evaluate after settle, before capture. */
+    evalJs?: string;
+    /** JS injected via addInitScript before navigation. */
+    initScript?: string;
     timeoutMs?: number;
     detectRoots?: DetectRoots;
     /**

package/dist/screenshot-local.js

@@ -285,19 +285,37 @@ export async function captureLocal(opts) {
                 viewport: { width: opts.viewport.width, height: opts.viewport.height },
                 deviceScaleFactor: opts.viewport.deviceScaleFactor,
                 colorScheme: opts.colorScheme,
+                reducedMotion: opts.reducedMotion ? "reduce" : undefined,
             });
+        // Runs before every navigation on this context — must be registered before
+        // the goto below so it's present when the page's own scripts first run.
+        if (opts.initScript)
+            await context.addInitScript({ content: opts.initScript });
         const page = usingCdp
             ? await context.newPage()
             : (context.pages()[0] ?? (await context.newPage()));
         if (usingCdp) {
             await page.setViewportSize({ width: opts.viewport.width, height: opts.viewport.height });
-            if (opts.colorScheme)
-                await page.emulateMedia({ colorScheme: opts.colorScheme });
+            // deviceScaleFactor + reducedMotion can't be set on an already-launched
+            // CDP context, but emulateMedia (colorScheme + reduced-motion) still can.
+            if (opts.colorScheme || opts.reducedMotion) {
+                await page.emulateMedia({
+                    colorScheme: opts.colorScheme,
+                    reducedMotion: opts.reducedMotion ? "reduce" : undefined,
+                });
+            }
         }
         const waitUntil = typeof opts.waitUntil === "string" ? opts.waitUntil : "load";
         await page.goto(opts.url, { waitUntil, timeout: opts.timeoutMs ?? 30_000 });
         if (typeof opts.waitUntil === "number")
             await page.waitForTimeout(opts.waitUntil);
+        // Hide overlays first, then run any user eval (which may depend on, or
+        // deliberately override, the hidden state).
+        if (opts.hide && opts.hide.length > 0) {
+            await page.addStyleTag({ content: `${opts.hide.join(",")}{display:none !important}` });
+        }
+        if (opts.evalJs)
+            await page.evaluate(opts.evalJs);
         const png = opts.selector
             ? await page.locator(opts.selector).screenshot({ timeout: opts.timeoutMs ?? 30_000 })
             : await page.screenshot({ fullPage: opts.fullPage === true });

package/dist/screenshot-remote.d.ts

@@ -12,6 +12,14 @@ export interface RemoteRenderRequest {
     fullPage?: boolean;
     colorScheme?: "dark" | "light";
     waitUntil?: "load" | "domcontentloaded" | "networkidle" | number;
+    /** CSS selectors hidden (display:none) server-side before capture. */
+    hide?: string[];
+    /**
+     * Best-effort reduced-motion on the remote backend: the render endpoint has
+     * no true media-feature emulation, so it neutralizes animations/transitions
+     * with an injected stylesheet (documented gap, like colorScheme).
+     */
+    reducedMotion?: boolean;
 }
 export interface RemoteRenderOptions {
     apiUrl: string;

package/dist/screenshot.d.ts

@@ -2,6 +2,23 @@ import { captureRemote } from "./screenshot-remote.js";
 import type { DetectRoots } from "./screenshot-local.js";
 export type ScreenshotBackend = "auto" | "local" | "remote";
 export type WaitUntil = "load" | "domcontentloaded" | "networkidle" | number;
+/**
+ * Host selectors for framework dev toolbars/overlays that otherwise pollute a
+ * screenshot of a running dev server. Hidden (display:none) automatically when
+ * the target is a localhost/private URL, unless `--no-hide-dev-tools`. Hiding
+ * the custom-element host also hides its shadow-DOM contents, so a single
+ * host-level rule is enough for the web-component toolbars.
+ */
+export declare const DEV_TOOLBAR_SELECTORS: readonly string[];
+/**
+ * Reject a `--hide` selector that could break out of the generated
+ * `selector{display:none}` rule (or inject markup server-side). The selectors
+ * are the caller's own, so this guards against footguns, not a trust boundary.
+ * `@` is rejected too: a leading at-rule (e.g. `@import url(...);*`) needs no
+ * braces to smuggle an `@import` into the injected stylesheet — and `@` is
+ * never valid in a CSS selector anyway.
+ */
+export declare function assertHideSelector(selector: string): void;
 export interface ScreenshotViewport {
     width: number;
     height: number;
@@ -41,6 +58,19 @@ export interface CaptureScreenshotOptions {
     fullPage?: boolean;
     colorScheme?: "dark" | "light";
     waitUntil?: WaitUntil;
+    /** Extra CSS selectors to hide (display:none) before capture. */
+    hide?: string[];
+    /**
+     * Auto-hide known framework dev toolbars. Defaults to on for localhost/
+     * private-network targets and off otherwise; pass `false` to opt out.
+     */
+    hideDevTools?: boolean;
+    /** Emulate prefers-reduced-motion: reduce so CSS/JS animations settle. */
+    reducedMotion?: boolean;
+    /** Run this JS in the page after settle, before capture (local backend only). */
+    evalJs?: string;
+    /** Inject this JS as an init script before navigation (local backend only). */
+    initScript?: string;
     apiUrl: string;
     token: string;
     /** Injectable for tests; forwarded to detectLocalBrowser. */
@@ -55,6 +85,10 @@ export interface CaptureScreenshotOptions {
         fullPage?: boolean;
         colorScheme?: "dark" | "light";
         waitUntil: WaitUntil;
+        hide?: string[];
+        reducedMotion?: boolean;
+        evalJs?: string;
+        initScript?: string;
         detectRoots?: DetectRoots;
         /** Pre-computed detection result from auto-routing, to avoid a second fs scan. */
         detectResult?: import("./screenshot-local.js").DetectResult;

package/dist/screenshot.js

@@ -13,6 +13,35 @@ import { basename, resolve as resolvePath } from "node:path";
 import { pathToFileURL } from "node:url";
 import { UploadsError } from "./errors.js";
 import { captureRemote, MAX_REMOTE_HTML_BYTES } from "./screenshot-remote.js";
+/**
+ * Host selectors for framework dev toolbars/overlays that otherwise pollute a
+ * screenshot of a running dev server. Hidden (display:none) automatically when
+ * the target is a localhost/private URL, unless `--no-hide-dev-tools`. Hiding
+ * the custom-element host also hides its shadow-DOM contents, so a single
+ * host-level rule is enough for the web-component toolbars.
+ */
+export const DEV_TOOLBAR_SELECTORS = [
+    "astro-dev-toolbar", // Astro
+    "#__next-build-watcher", // Next.js (legacy build-activity indicator)
+    "nextjs-portal", // Next.js dev overlay / indicators (App Router)
+    "#nuxt-devtools-anchor", // Nuxt DevTools launcher
+    "#nuxt-devtools-container",
+    "vite-plugin-checker-error-overlay", // vite-plugin-checker overlay
+    "vite-error-overlay", // Vite HMR error overlay
+];
+/**
+ * Reject a `--hide` selector that could break out of the generated
+ * `selector{display:none}` rule (or inject markup server-side). The selectors
+ * are the caller's own, so this guards against footguns, not a trust boundary.
+ * `@` is rejected too: a leading at-rule (e.g. `@import url(...);*`) needs no
+ * braces to smuggle an `@import` into the injected stylesheet — and `@` is
+ * never valid in a CSS selector anyway.
+ */
+export function assertHideSelector(selector) {
+    if (selector.length === 0 || /[@{}<>]/.test(selector)) {
+        throw new UploadsError(`invalid hide selector: ${JSON.stringify(selector)} (a CSS selector, no @, {, }, <, or >)`, "USAGE");
+    }
+}
 export const DEFAULT_SCREENSHOT_VIEWPORT = {
     width: 1280,
     height: 800,
@@ -159,6 +188,13 @@ export async function captureScreenshot(opts) {
     // is sent to the remote backend as an inline `html` body (though anything
     // it references via file:// or relative paths won't resolve there).
     const localOnly = target.kind === "url" && target.localOnly;
+    // Auto-hide framework dev toolbars only makes sense for a running dev server
+    // (a localhost/private URL); default off elsewhere. Combine with any
+    // explicit --hide selectors into one list shared by both backends.
+    const autoHideDevTools = opts.hideDevTools ?? localOnly;
+    for (const sel of opts.hide ?? [])
+        assertHideSelector(sel);
+    const hide = [...(opts.hide ?? []), ...(autoHideDevTools ? DEV_TOOLBAR_SELECTORS : [])];
     // Populated only when auto-routing actually probes the filesystem, so it
     // can be threaded into captureLocalImpl below to avoid a second scan.
     let detected;
@@ -192,6 +228,12 @@ export async function captureScreenshot(opts) {
     if (backend === "remote" && typeof waitUntil === "number") {
         throw new UploadsError(`numeric --wait (${waitUntil}ms) is local-only — use --via local, or one of load/domcontentloaded/networkidle for the remote backend`, "USAGE");
     }
+    // Arbitrary pre-capture JS runs only on the local backend — the shared
+    // remote renderer intentionally has no eval escape hatch (different security
+    // posture). Fail fast rather than silently dropping it.
+    if (backend === "remote" && (opts.evalJs !== undefined || opts.initScript !== undefined)) {
+        throw new UploadsError("--eval and --init-script are local-only — use --via local", "USAGE");
+    }
     if (backend === "local") {
         const captureLocalImpl = opts.captureLocalImpl ??
             (async (localOpts) => {
@@ -207,6 +249,10 @@ export async function captureScreenshot(opts) {
             fullPage: opts.fullPage,
             colorScheme: opts.colorScheme,
             waitUntil,
+            hide,
+            reducedMotion: opts.reducedMotion,
+            evalJs: opts.evalJs,
+            initScript: opts.initScript,
             detectRoots: opts.detectRoots,
             detectResult: detected,
         });
@@ -226,6 +272,8 @@ export async function captureScreenshot(opts) {
         fullPage: opts.fullPage,
         colorScheme: opts.colorScheme,
         waitUntil,
+        ...(hide.length > 0 ? { hide } : {}),
+        ...(opts.reducedMotion ? { reducedMotion: true } : {}),
     }, { apiUrl: opts.apiUrl, token: opts.token });
     return { png, filename, backend };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,