@buildinternet/uploads 0.41.0 → 0.42.0

package/README.md

@@ -58,7 +58,12 @@ answers `did you mean: uploads meta set`. With `--json`, an unknown command
 returns `{ "error", "code": "USAGE", "didYouMean" }` on stdout.
 
 **Shell completion:** `uploads completion bash|zsh|fish` prints a script to
-stdout. Example (zsh): `uploads completion zsh > ~/.zsh/completions/_uploads`.
+stdout. Save it where your shell looks for completions, then start a new shell.
+For zsh, write the script to `~/.zsh/completions/_uploads`, then bind it at the
+end of `~/.zshrc` with `fpath=(~/.zsh/completions $fpath)` and
+`autoload -Uz _uploads && compdef _uploads uploads`. The `compdef` line matters:
+a cached `compinit -C` never rescans fpath, so the file alone can go unnoticed.
+`uploads completion --help` covers the rest.
 
 **Globals (before the command):** `--api-url`, `--token`, `--workspace` / `-w`,
 `--env-file`, `--json`, `--quiet`, `--version` / `-V`, `-h` / `--help`, `--all`

package/dist/cli-args.d.ts

@@ -79,4 +79,6 @@ export declare function flagBool(flags: CommandFlags["flags"], name: string): bo
 export declare function flagValues(flags: CommandFlags["flags"], name: string): string[];
 /** Command-level workspace override (`--workspace` / `-w`). */
 export declare function commandWorkspace(flags: CommandFlags["flags"]): string | undefined;
-export declare function flagInt(flags: CommandFlags["flags"], name: string, label: string): number | undefined;
+export declare function flagInt(flags: CommandFlags["flags"], name: string, label: string, options?: {
+    allowZero?: boolean;
+}): number | undefined;

package/dist/cli-args.js

@@ -198,16 +198,18 @@ export function flagValues(flags, name) {
 export function commandWorkspace(flags) {
     return flagString(flags, "--workspace") ?? flagString(flags, "-w");
 }
-export function flagInt(flags, name, label) {
+export function flagInt(flags, name, label, options) {
+    const allowZero = options?.allowZero ?? false;
+    const kind = allowZero ? "non-negative" : "positive";
     const raw = flagString(flags, name);
     if (raw === undefined)
         return undefined;
     if (!/^\d+$/.test(raw)) {
-        throw new UsageError(`invalid ${label}: must be a positive integer (got ${raw})`);
+        throw new UsageError(`invalid ${label}: must be a ${kind} integer (got ${raw})`);
     }
     const n = Number.parseInt(raw, 10);
-    if (!Number.isFinite(n) || n <= 0) {
-        throw new UsageError(`invalid ${label}: must be a positive integer (got ${raw})`);
+    if (!Number.isFinite(n) || (allowZero ? n < 0 : n <= 0)) {
+        throw new UsageError(`invalid ${label}: must be a ${kind} integer (got ${raw})`);
     }
     return n;
 }

package/dist/cli-catalog.js

@@ -56,6 +56,7 @@ export const SCREENSHOT_FLAGS = [
     "--viewport",
     "--selector",
     "--full-page",
+    "--max-height",
     "--dark",
     "--light",
     "--wait",

package/dist/commands/completion.js

@@ -3,8 +3,9 @@ import { ANNOTATE_FLAGS, COMPLETION_SHELLS, GLOBAL_FLAGS, LIST_LIKE_FLAGS, PUT_L
 import { writeCommandHelp } from "../cli-style.js";
 const HELP = `uploads completion <shell>
 
-Print a shell completion script to stdout. Source it or install it so Tab
-completes commands, subcommands, and common flags.
+Print a shell completion script to stdout. Save it where your shell looks for
+completions, then start a new shell. Tab then completes commands, subcommands,
+and common flags.
 
 Shells:
   bash   Bash (complete -F)
@@ -12,16 +13,36 @@ Shells:
   fish   Fish (complete -c)
 
 Examples:
-  # zsh (Oh My Zsh / fpath)
-  uploads completion zsh > ~/.zsh/completions/_uploads
-
-  # bash
-  uploads completion bash > ~/.local/share/bash-completion/completions/uploads
-  # or for the current session:
+  # bash — for the current session:
   eval "$(uploads completion bash)"
+  # or save it:
+  uploads completion bash > ~/.local/share/bash-completion/completions/uploads
 
   # fish
   uploads completion fish > ~/.config/fish/completions/uploads.fish
+
+  # zsh — save the script:
+  uploads completion zsh > ~/.zsh/completions/_uploads
+  # then add these two lines to the END of ~/.zshrc:
+  #   fpath=(~/.zsh/completions $fpath)
+  #   autoload -Uz _uploads && compdef _uploads uploads
+
+Zsh notes:
+  Saving the file into an fpath directory is often not enough. compinit caches
+  its scan in ~/.zcompdump, and \`compinit -C\` reuses that cache instead of
+  rescanning, so it never sees the new file. Oh My Zsh and several installers
+  call compinit that way. Some plugins also rewrite fpath as they load, which
+  drops entries added before them; zsh-autocomplete is one.
+
+  The \`compdef\` line avoids both problems, because it binds the function
+  directly instead of relying on a scan. Put it after any framework or plugin
+  setup. If completion still does nothing, delete ~/.zcompdump* and start a
+  new shell.
+
+  Check the result with: print $_comps[uploads] — it prints _uploads when the
+  completion is active, and nothing when it is not.
+
+After you upgrade the CLI, generate the script again so it lists new commands.
 `;
 function bashScript() {
     const cmds = ROOT_COMMANDS.map((c) => c.name).join(" ");
@@ -140,18 +161,19 @@ function zshScript() {
     }).join("\n");
     const globalArgs = GLOBAL_FLAGS.map((g) => {
         const desc = g.summary.replace(/'/g, "'\\''");
-        // Short and long flags as separate specs when needed.
-        if (g.flag === "-w")
-            return `    '(-w --workspace)'{-w,--workspace}'[${desc}]:workspace:'`;
+        // Pair each short flag with its long form, keeping the long form's cleaner
+        // summary; the short entry then contributes nothing of its own.
         if (g.flag === "--workspace")
-            return null; // paired with -w
-        if (g.flag === "-V")
-            return `    '(-V --version)'{-V,--version}'[${desc}]'`;
+            return `    '(-w --workspace)'{-w,--workspace}'[${desc}]:workspace:'`;
+        if (g.flag === "-w")
+            return null; // paired with --workspace
         if (g.flag === "--version")
+            return `    '(-V --version)'{-V,--version}'[${desc}]'`;
+        if (g.flag === "-V")
             return null;
-        if (g.flag === "-h")
-            return `    '(-h --help)'{-h,--help}'[${desc}]'`;
         if (g.flag === "--help")
+            return `    '(-h --help)'{-h,--help}'[${desc}]'`;
+        if (g.flag === "-h")
             return null;
         if (g.flag === "--api-url")
             return `    '--api-url[${desc}]:url:'`;
@@ -162,7 +184,9 @@ function zshScript() {
         return `    '${g.flag}[${desc}]'`;
     })
         .filter(Boolean)
-        .join("\n");
+        // Every spec but the last needs a line continuation — without them zsh ends
+        // the `_arguments` call after the first spec and tries to *run* the rest.
+        .join(" \\\n");
     const subCases = ROOT_COMMANDS.filter((c) => c.subcommands?.length)
         .map((c) => {
         const lines = c

package/dist/commands/screenshot.js

@@ -13,7 +13,7 @@ import { parseMetaFlags, validateMetaMap } from "../metadata.js";
 import { mergeDerivedMeta } from "../metadata-vocab.js";
 import { writeSidecarMeta } from "../sidecar.js";
 import { readStdin, writeJson, writeStdout } from "../io.js";
-import { assertHideSelector, captureScreenshot, parseViewport, parseWaitUntil, } from "../screenshot.js";
+import { assertHideSelector, captureScreenshot, clipHintText, DEFAULT_FULL_PAGE_MAX_HEIGHT, 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
@@ -59,6 +59,10 @@ Options:
   --viewport <WxH[@Sx]>     Size + device scale factor (default: 1280x800@2)
   --selector <css>          Capture one element instead of the viewport
   --full-page               Capture the full scrollable page
+  --max-height <px>         Cap on full-page capture height in CSS px (default: ${DEFAULT_FULL_PAGE_MAX_HEIGHT},
+                            or 0 for uncapped). A page over the cap is clipped, with a note printed
+                            to stderr and a --format json \`hint\`. Requires --full-page. Applied on
+                            both --via local and --via remote so behavior matches.
   --dark / --light          Emulate prefers-color-scheme (full media-query emulation on --via local
                             only; --via remote just sets the CSS color-scheme property, so a page's
                             own prefers-color-scheme queries won't flip)
@@ -182,6 +186,14 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     const viewport = parseViewport(flagString(parsed.flags, "--viewport"));
     const selector = flagString(parsed.flags, "--selector");
     const fullPage = flagBool(parsed.flags, "--full-page");
+    // Unlike every other --…-px flag, 0 is a valid (uncapped) value here, not
+    // an error — flagInt's allowZero option covers it.
+    const maxHeightFlag = flagInt(parsed.flags, "--max-height", "--max-height", {
+        allowZero: true,
+    });
+    if (maxHeightFlag !== undefined && !fullPage) {
+        throw new UsageError("--max-height requires --full-page");
+    }
     const colorScheme = colorSchemeFromFlags(parsed.flags);
     const waitUntil = parseWaitUntil(flagString(parsed.flags, "--wait"));
     const hide = flagValues(parsed.flags, "--hide");
@@ -387,6 +399,7 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
         viewport,
         selector,
         fullPage,
+        maxHeight: maxHeightFlag,
         colorScheme,
         waitUntil,
         hide,
@@ -403,6 +416,14 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     });
     if (logHuman)
         process.stderr.write(`>> captured via ${captured.backend} backend\n`);
+    // Full-page height cap note (issue #652): printed regardless of --format
+    // (only --quiet suppresses it) since it's directly actionable info about
+    // the image that was just captured, same as the upload-tail warnings below.
+    const clipHint = captured.capped?.clipped
+        ? clipHintText(captured.capped.maxHeightPx, "--max-height")
+        : undefined;
+    if (clipHint && !ctx.quiet)
+        process.stderr.write(`${clipHint}\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.
@@ -543,9 +564,11 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
             process.stderr.write(`${bindingWarning}\n`);
         process.stderr.write("\n");
     }
-    // One JSON `hint` slot (mirrors bare put): the binding warning is more
-    // actionable than the generic staging note, so it wins when both fire; a
-    // replaced-object note (issue #618) is the lowest priority of the three —
+    // One JSON `hint` slot (mirrors bare put): the clip note (issue #652) wins
+    // first — it's about the just-captured image itself, more immediately
+    // actionable than the other three, which are about upload/staging
+    // mechanics. Then the binding warning, more actionable than the generic
+    // staging note; a replaced-object note (issue #618) is lowest priority —
     // it only surfaces when nothing else already claimed the slot. Since state
     // folds into the derived key, replaced + state means a same-side re-capture,
     // which is the intended replace-in-place flow — word it as informational,
@@ -553,7 +576,7 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     const replacedHint = result.replaced && explicitMeta.state
         ? `re-capture replaced the previous state=${explicitMeta.state} object at ${result.key} — expected for repeat captures of the same URL + state`
         : undefined;
-    const jsonHint = bindingWarning ?? stagingNote ?? replacedHint;
+    const jsonHint = clipHint ?? bindingWarning ?? stagingNote ?? replacedHint;
     switch (format) {
         case "json":
             await writeJson({

package/dist/mcp/args.d.ts

@@ -3,7 +3,9 @@ export declare function usage(msg: string): never;
 export declare function optString(args: ToolArgs, name: string): string | undefined;
 /** A boolean flag argument; missing/null reads as `false`. */
 export declare function optBool(args: ToolArgs, name: string): boolean;
-export declare function optPosInt(args: ToolArgs, name: string): number | undefined;
+export declare function optPosInt(args: ToolArgs, name: string, options?: {
+    allowZero?: boolean;
+}): number | undefined;
 /** A JSON-object argument of string→string pairs (e.g. a `metadata` or `filters` param). */
 export declare function optStringRecord(args: ToolArgs, name: string): Record<string, string> | undefined;
 /** A JSON-array argument of strings (e.g. a `delete` or `files` param). */

package/dist/mcp/args.js

@@ -25,12 +25,13 @@ export function optBool(args, name) {
         usage(`${name} must be a boolean`);
     return v;
 }
-export function optPosInt(args, name) {
+export function optPosInt(args, name, options) {
+    const allowZero = options?.allowZero ?? false;
     const v = args[name];
     if (v === undefined || v === null)
         return undefined;
-    if (typeof v !== "number" || !Number.isInteger(v) || v <= 0) {
-        usage(`${name} must be a positive integer`);
+    if (typeof v !== "number" || !Number.isInteger(v) || (allowZero ? v < 0 : v <= 0)) {
+        usage(`${name} must be a ${allowZero ? "non-negative" : "positive"} integer`);
     }
     return v;
 }

package/dist/mcp/tools.js

@@ -584,6 +584,12 @@ export function createUploadsMcpTools(opts) {
                     },
                     selector: { type: "string", description: "Capture one element instead of the viewport." },
                     fullPage: { type: "boolean", description: "Capture the full scrollable page." },
+                    maxHeight: {
+                        type: "number",
+                        description: "Cap on full-page capture height in CSS px (default: 5000, 0 = uncapped). A page over " +
+                            "the cap is clipped, with a `hint` in the result. Requires fullPage. Applied on both " +
+                            "via: local and via: remote so behavior matches.",
+                    },
                     colorScheme: {
                         type: "string",
                         description: "Emulate prefers-color-scheme: dark | light. Full media-query emulation requires via: \"local\" — the remote backend only sets the CSS color-scheme property and won't flip a page's own prefers-color-scheme queries.",
@@ -678,6 +684,12 @@ export function createUploadsMcpTools(opts) {
                 if (colorSchemeArg && colorSchemeArg !== "dark" && colorSchemeArg !== "light") {
                     usage("colorScheme must be dark or light");
                 }
+                const fullPageArg = optBool(args, "fullPage");
+                // Unlike other px args, 0 is valid here (uncapped) — optPosInt's
+                // allowZero option covers it.
+                const maxHeightArg = optPosInt(args, "maxHeight", { allowZero: true });
+                if (maxHeightArg !== undefined && !fullPageArg)
+                    usage("maxHeight requires fullPage");
                 const target = ghTargetFromArgs(args, run);
                 const wantComment = optBool(args, "comment");
                 const dryRun = optBool(args, "dryRun");
@@ -778,7 +790,8 @@ export function createUploadsMcpTools(opts) {
                         cdp: optString(args, "cdp"),
                         viewport,
                         selector: optString(args, "selector"),
-                        fullPage: optBool(args, "fullPage"),
+                        fullPage: fullPageArg,
+                        maxHeight: maxHeightArg,
                         colorScheme: colorSchemeArg,
                         waitUntil: screenshotModule.parseWaitUntil(optString(args, "wait")),
                         hide: optStringArray(args, "hide"),
@@ -863,6 +876,11 @@ export function createUploadsMcpTools(opts) {
                     frame: prepared.frame,
                     gallery,
                     ...(dryRun ? { dryRun: true } : {}),
+                    // Full-page height cap note (issue #652), mirrors the CLI's stderr
+                    // note + `hint` field.
+                    ...(captured.capped?.clipped
+                        ? { hint: screenshotModule.clipHintText(captured.capped.maxHeightPx, "maxHeight") }
+                        : {}),
                 };
                 if (wantComment && target) {
                     const { comment, commentError } = await syncComment(client, target, config.workspace);

package/dist/screenshot-local.d.ts

@@ -48,6 +48,13 @@ export interface LocalCaptureOptions {
     };
     selector?: string;
     fullPage?: boolean;
+    /**
+     * Cap (CSS px) on full-page capture height (issue #652). Only consulted
+     * when `fullPage` is true; 0 or undefined means uncapped. When the page's
+     * measured scroll height exceeds this, the capture is clipped to exactly
+     * this height instead of the full scroll height.
+     */
+    maxHeightPx?: number;
     colorScheme?: "dark" | "light";
     /** "load" | "domcontentloaded" | "networkidle", or a millisecond settle delay. */
     waitUntil: "load" | "domcontentloaded" | "networkidle" | number;
@@ -86,6 +93,16 @@ export interface MeasuredBox {
 interface EvaluatablePage {
     evaluate<T>(fn: (selectors: string[]) => T, arg: string[]): Promise<T>;
 }
+/**
+ * Measures the page's full scrollable height in CSS px — the same quantity
+ * a `fullPage: true` screenshot would otherwise capture in its entirety.
+ * `document.documentElement.scrollHeight` is the standard measure; `body`'s
+ * is included too since some pages (quirks-mode, non-standard layouts) only
+ * grow one or the other.
+ */
+export declare function measureFullPageHeight(page: {
+    evaluate<T>(fn: () => T): Promise<T>;
+}): Promise<number>;
 /**
  * Measures each selector's getBoundingClientRect on the page in a single
  * `page.evaluate` round-trip, scaling CSS pixels to device (raster) pixels so
@@ -99,5 +116,6 @@ export declare function measureSelectorBoxes(page: EvaluatablePage, selectors: r
 export declare function captureLocal(opts: LocalCaptureOptions): Promise<{
     png: Uint8Array;
     measures?: Record<string, MeasuredBox>;
+    clipped?: boolean;
 }>;
 export {};

package/dist/screenshot-local.js

@@ -203,6 +203,16 @@ export function detectLocalBrowser(roots = {}) {
     const winner = [...candidates].toSorted((a, b) => rank(a) - rank(b))[0];
     return { envOverride, candidates, winner };
 }
+/**
+ * Measures the page's full scrollable height in CSS px — the same quantity
+ * a `fullPage: true` screenshot would otherwise capture in its entirety.
+ * `document.documentElement.scrollHeight` is the standard measure; `body`'s
+ * is included too since some pages (quirks-mode, non-standard layouts) only
+ * grow one or the other.
+ */
+export async function measureFullPageHeight(page) {
+    return page.evaluate(() => Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight ?? 0));
+}
 /**
  * Measures each selector's getBoundingClientRect on the page in a single
  * `page.evaluate` round-trip, scaling CSS pixels to device (raster) pixels so
@@ -349,11 +359,33 @@ export async function captureLocal(opts) {
         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 });
+        // Full-page height cap (issue #652): measure the actual scroll height
+        // first so a page under the cap keeps its normal exact-content-height
+        // fullPage capture — only a page that genuinely exceeds the cap gets
+        // clipped to it. `clip` (CSS px, captures beyond the current viewport)
+        // is the mechanism; it can't be combined with `fullPage: true`.
+        let clipped = false;
+        let png;
+        if (opts.selector) {
+            png = await page.locator(opts.selector).screenshot({ timeout: opts.timeoutMs ?? 30_000 });
+        }
+        else if (opts.fullPage && opts.maxHeightPx && opts.maxHeightPx > 0) {
+            const fullHeight = await measureFullPageHeight(page);
+            if (fullHeight > opts.maxHeightPx) {
+                clipped = true;
+                png = await page.screenshot({
+                    clip: { x: 0, y: 0, width: opts.viewport.width, height: opts.maxHeightPx },
+                });
+            }
+            else {
+                png = await page.screenshot({ fullPage: true });
+            }
+        }
+        else {
+            png = await page.screenshot({ fullPage: opts.fullPage === true });
+        }
         // Buffer extends Uint8Array — return it as-is rather than copying.
-        return { png, measures };
+        return { png, measures, clipped };
     }
     finally {
         await browser.close();

package/dist/screenshot-remote.d.ts

@@ -10,6 +10,14 @@ export interface RemoteRenderRequest {
     };
     selector?: string;
     fullPage?: boolean;
+    /**
+     * Cap (CSS px) on full-page capture height (issue #652). Only sent when
+     * `fullPage` is true and the cap is active (nonzero); the server applies a
+     * best-effort clamp (see apps/api's render.ts) and reports whether it
+     * actually kicked in via the `X-Uploads-Full-Page-Clipped` response header,
+     * surfaced back on the result as `clipped`.
+     */
+    maxHeight?: number;
     colorScheme?: "dark" | "light";
     waitUntil?: "load" | "domcontentloaded" | "networkidle" | number;
     /** CSS selectors hidden (display:none) server-side before capture. */
@@ -27,5 +35,14 @@ export interface RemoteRenderOptions {
     fetchImpl?: typeof fetch;
     timeoutMs?: number;
 }
-/** POST the render request; resolves with raw PNG bytes on 200. */
-export declare function captureRemote(body: RemoteRenderRequest, opts: RemoteRenderOptions): Promise<Uint8Array>;
+export interface RemoteRenderResult {
+    png: Uint8Array;
+    /**
+     * True when the server's best-effort full-page height clamp actually
+     * kicked in (read from the `X-Uploads-Full-Page-Clipped` response header).
+     * Always false when `maxHeight` wasn't sent.
+     */
+    clipped: boolean;
+}
+/** POST the render request; resolves with raw PNG bytes (+ clip status) on 200. */
+export declare function captureRemote(body: RemoteRenderRequest, opts: RemoteRenderOptions): Promise<RemoteRenderResult>;

package/dist/screenshot-remote.js

@@ -32,7 +32,7 @@ function mapRenderError(status, message, code) {
         return new UploadsError(message, "RATE_LIMITED", status);
     return new UploadsError(message, "API_ERROR", status);
 }
-/** POST the render request; resolves with raw PNG bytes on 200. */
+/** POST the render request; resolves with raw PNG bytes (+ clip status) on 200. */
 export async function captureRemote(body, opts) {
     if (body.html !== undefined) {
         const htmlBytes = new TextEncoder().encode(body.html).byteLength;
@@ -65,7 +65,7 @@ export async function captureRemote(body, opts) {
         if (bytes.byteLength === 0) {
             throw new UploadsError("render endpoint returned an empty response", "RENDER_FAILED");
         }
-        return bytes;
+        return { png: bytes, clipped: res.headers.get("x-uploads-full-page-clipped") === "true" };
     }
     catch (err) {
         if (err instanceof UploadsError)

package/dist/screenshot.d.ts

@@ -25,6 +25,16 @@ export interface ScreenshotViewport {
     deviceScaleFactor: number;
 }
 export declare const DEFAULT_SCREENSHOT_VIEWPORT: ScreenshotViewport;
+/**
+ * Default cap (CSS px) on `--full-page` capture height (issue #652). Picked
+ * from the 4000-6000px range the issue proposed: generous enough to cover a
+ * long single-viewport marketing/docs page without clipping, but well short
+ * of the multi-thousand-entry-list case that motivated this (a 53-entry
+ * changelog page, PR #651) — those still clip, with a note pointing at
+ * `--max-height` to raise or remove the cap. `0` (via `--max-height 0`) means
+ * uncapped, for the rare case the full strip is genuinely wanted.
+ */
+export declare const DEFAULT_FULL_PAGE_MAX_HEIGHT = 5000;
 /** Parses `WIDTHxHEIGHT[@SCALEx]`, e.g. "1280x800", "1280x800@2x", "1280x800@2". */
 export declare function parseViewport(raw: string | undefined): ScreenshotViewport;
 /** Parses `--wait`: "load" | "domcontentloaded" | "networkidle" | a millisecond count. */
@@ -63,6 +73,13 @@ export interface CaptureScreenshotOptions {
     viewport?: ScreenshotViewport;
     selector?: string;
     fullPage?: boolean;
+    /**
+     * Cap (CSS px) on `--full-page` capture height. Only meaningful with
+     * `fullPage: true`; ignored otherwise. `undefined` applies
+     * `DEFAULT_FULL_PAGE_MAX_HEIGHT`; `0` means uncapped. Wired through both
+     * capture backends so behavior matches regardless of `via` (issue #652).
+     */
+    maxHeight?: number;
     colorScheme?: "dark" | "light";
     waitUntil?: WaitUntil;
     /**
@@ -104,6 +121,8 @@ export interface CaptureScreenshotOptions {
         viewport: ScreenshotViewport;
         selector?: string;
         fullPage?: boolean;
+        /** CSS px cap on full-page height; 0 or undefined = uncapped. */
+        maxHeightPx?: number;
         colorScheme?: "dark" | "light";
         waitUntil: WaitUntil;
         hide?: string[];
@@ -117,6 +136,8 @@ export interface CaptureScreenshotOptions {
     }) => Promise<{
         png: Uint8Array;
         measures?: Record<string, MeasuredBox>;
+        /** Present when `fullPage` + a positive `maxHeightPx` were given. */
+        clipped?: boolean;
     }>;
     /** Injectable for tests: replaces the remote capture implementation. */
     captureRemoteImpl?: typeof captureRemote;
@@ -127,7 +148,23 @@ export interface CaptureScreenshotResult {
     backend: "local" | "remote";
     /** Present when `measureSelectors` was given and the local backend ran. */
     measures?: Record<string, MeasuredBox>;
+    /**
+     * Present when `fullPage` was requested with a nonzero max-height cap
+     * (explicit or default) — regardless of backend. `clipped` tells the
+     * caller whether the cap actually kicked in, so it can print the
+     * "exceeds Npx; clipped" note and JSON `hint` (issue #652).
+     */
+    capped?: {
+        maxHeightPx: number;
+        clipped: boolean;
+    };
 }
+/**
+ * The "clipped by the max-height cap" note shared by the CLI's stderr
+ * message and the MCP tool's JSON `hint` field (issue #652) — identical
+ * except for how each surface names the flag to raise the cap.
+ */
+export declare function clipHintText(maxHeightPx: number, flagName: string): string;
 /**
  * Folds a `--state` value into an auto-derived filename's stem, e.g.
  * `localhost-docs-mcp.png` + "before" → `localhost-docs-mcp-before.png`. This

package/dist/screenshot.js

@@ -48,6 +48,16 @@ export const DEFAULT_SCREENSHOT_VIEWPORT = {
     height: 800,
     deviceScaleFactor: 2,
 };
+/**
+ * Default cap (CSS px) on `--full-page` capture height (issue #652). Picked
+ * from the 4000-6000px range the issue proposed: generous enough to cover a
+ * long single-viewport marketing/docs page without clipping, but well short
+ * of the multi-thousand-entry-list case that motivated this (a 53-entry
+ * changelog page, PR #651) — those still clip, with a note pointing at
+ * `--max-height` to raise or remove the cap. `0` (via `--max-height 0`) means
+ * uncapped, for the rare case the full strip is genuinely wanted.
+ */
+export const DEFAULT_FULL_PAGE_MAX_HEIGHT = 5000;
 /** Parses `WIDTHxHEIGHT[@SCALEx]`, e.g. "1280x800", "1280x800@2x", "1280x800@2". */
 export function parseViewport(raw) {
     if (!raw)
@@ -146,6 +156,14 @@ export function classifyTarget(target) {
     }
     return { kind: "html-file", path: abs, html: readFileSync(abs, "utf8") };
 }
+/**
+ * The "clipped by the max-height cap" note shared by the CLI's stderr
+ * message and the MCP tool's JSON `hint` field (issue #652) — identical
+ * except for how each surface names the flag to raise the cap.
+ */
+export function clipHintText(maxHeightPx, flagName) {
+    return `full page exceeds ${maxHeightPx}px; clipped — use ${flagName} to raise`;
+}
 /** Derives a filename from a URL (host+path) or the source .html filename. */
 function deriveFilename(target) {
     if (target.kind === "html-file") {
@@ -225,6 +243,14 @@ export async function captureScreenshot(opts) {
     for (const sel of opts.hide ?? [])
         assertHideSelector(sel);
     const hide = [...(opts.hide ?? []), ...(autoHideDevTools ? DEV_TOOLBAR_SELECTORS : [])];
+    // Full-page height cap (issue #652): only meaningful with fullPage. 0
+    // (explicit --max-height 0) means uncapped; undefined applies the default.
+    const effectiveMaxHeight = opts.fullPage ? (opts.maxHeight ?? DEFAULT_FULL_PAGE_MAX_HEIGHT) : 0;
+    // Shared by both backends below — only meaningful when fullPage capped at
+    // a positive height; `clipped` is the one thing that differs per backend.
+    const cappedFrom = (clipped) => opts.fullPage && effectiveMaxHeight > 0
+        ? { maxHeightPx: effectiveMaxHeight, clipped }
+        : undefined;
     // Populated only when auto-routing actually probes the filesystem, so it
     // can be threaded into captureLocalImpl below to avoid a second scan.
     let detected;
@@ -284,6 +310,7 @@ export async function captureScreenshot(opts) {
             viewport,
             selector: opts.selector,
             fullPage: opts.fullPage,
+            maxHeightPx: effectiveMaxHeight,
             colorScheme: opts.colorScheme,
             waitUntil,
             hide,
@@ -294,7 +321,8 @@ export async function captureScreenshot(opts) {
             detectRoots: opts.detectRoots,
             detectResult: detected,
         });
-        return { png: localResult.png, filename, backend, measures: localResult.measures };
+        const capped = cappedFrom(localResult.clipped === true);
+        return { png: localResult.png, filename, backend, measures: localResult.measures, capped };
     }
     if (target.kind === "html-file") {
         const bytes = new TextEncoder().encode(target.html).byteLength;
@@ -303,15 +331,17 @@ export async function captureScreenshot(opts) {
         }
     }
     const captureRemoteImpl = opts.captureRemoteImpl ?? captureRemote;
-    const png = await captureRemoteImpl({
+    const remoteResult = await captureRemoteImpl({
         ...(target.kind === "html-file" ? { html: target.html } : { url: target.url }),
         viewport,
         selector: opts.selector,
         fullPage: opts.fullPage,
+        ...(opts.fullPage && effectiveMaxHeight > 0 ? { maxHeight: effectiveMaxHeight } : {}),
         colorScheme: opts.colorScheme,
         waitUntil,
         ...(hide.length > 0 ? { hide } : {}),
         ...(opts.reducedMotion ? { reducedMotion: true } : {}),
     }, { apiUrl: opts.apiUrl, token: opts.token });
-    return { png, filename, backend };
+    const capped = cappedFrom(remoteResult.clipped === true);
+    return { png: remoteResult.png, filename, backend, capped };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,
@@ -38,7 +38,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "files-sdk": "^2.2.3"
+    "files-sdk": "^2.2.4"
   },
   "peerDependenciesMeta": {
     "files-sdk": {
@@ -48,7 +48,7 @@
   "devDependencies": {
     "@types/node": "^26.1.0",
     "ai": "^6.0.0",
-    "files-sdk": "^2.2.3",
+    "files-sdk": "^2.2.4",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"
   },