@buildinternet/uploads 0.45.0 → 0.46.0

package/dist/commands/screenshot.js

@@ -82,7 +82,16 @@ Options:
   --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)
+  --wait-for <js>           Poll this JS expression in the page until truthy before --eval and
+                            capture (--via local only). Bridges framework hydration: load/
+                            networkidle settle before React/Next attach handlers, so a synthetic
+                            click in --eval hits the inert server-rendered DOM. Express the app's
+                            own "interactive" signal, e.g. --wait-for 'window.__hydrated===true' or
+                            --wait-for 'document.querySelector("[data-hydrated]")'. Times out with
+                            the capture timeout if it never becomes truthy.
+  --eval <js>               Run JS in the page after settle, before capture (--via local only).
+                            Note: synthetic events (el.click()) won't reach framework handlers
+                            until the app hydrates — pair with --wait-for on React/Next apps.
   --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
@@ -216,6 +225,7 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     // 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 waitForExpr = flagString(parsed.flags, "--wait-for");
     const evalJs = flagString(parsed.flags, "--eval");
     const initScriptPath = flagString(parsed.flags, "--init-script");
     let initScript;
@@ -445,6 +455,7 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
         hide,
         hideDevTools,
         reducedMotion,
+        waitForExpr,
         evalJs,
         initScript,
         // Skip folding when an explicit --key was given — --key sets the whole

package/dist/screenshot-local.d.ts

@@ -62,6 +62,15 @@ export interface LocalCaptureOptions {
     hide?: string[];
     /** Emulate prefers-reduced-motion: reduce so animations settle deterministically. */
     reducedMotion?: boolean;
+    /**
+     * JS expression polled in the page (page.waitForFunction) after settle and
+     * before `evalJs`/capture — the caller's "app is interactive" signal. Lets a
+     * synthetic click in `evalJs` land after a framework (React/Next/…) has
+     * hydrated and attached its handlers, instead of firing on the still-inert
+     * server-rendered DOM. Throws `RENDER_FAILED` if it never becomes truthy
+     * within the capture timeout.
+     */
+    waitForExpr?: string;
     /** JS run via page.evaluate after settle, before capture. */
     evalJs?: string;
     /** JS injected via addInitScript before navigation. */

package/dist/screenshot-local.js

@@ -346,9 +346,28 @@ export async function captureLocal(opts) {
             }
         }
         const waitUntil = typeof opts.waitUntil === "string" ? opts.waitUntil : "load";
-        await page.goto(opts.url, { waitUntil, timeout: opts.timeoutMs ?? 30_000 });
+        const timeoutMs = opts.timeoutMs ?? 30_000;
+        await page.goto(opts.url, { waitUntil, timeout: timeoutMs });
         if (typeof opts.waitUntil === "number")
             await page.waitForTimeout(opts.waitUntil);
+        // Hydration-aware gate (issue #715): poll the caller's "app is interactive"
+        // predicate before running any eval or capturing. The load/networkidle
+        // settle strategies fire before a framework hydrates, so a synthetic
+        // click in `evalJs` would hit the inert server-rendered DOM with no
+        // handler attached. Waiting for the caller's own signal (e.g.
+        // `window.__hydrated === true`, or a class/attribute the app sets once
+        // interactive) closes that gap. A timeout means the predicate never
+        // became truthy — surface it clearly rather than capturing the un-ready
+        // page silently.
+        if (opts.waitForExpr) {
+            try {
+                await page.waitForFunction(opts.waitForExpr, undefined, { timeout: timeoutMs });
+            }
+            catch (err) {
+                throw new UploadsError(`--wait-for expression never became truthy within ${timeoutMs}ms: ${opts.waitForExpr}` +
+                    ` (${err instanceof Error ? err.message : String(err)})`, "RENDER_FAILED");
+            }
+        }
         // 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) {

package/dist/screenshot.d.ts

@@ -99,6 +99,13 @@ export interface CaptureScreenshotOptions {
     hideDevTools?: boolean;
     /** Emulate prefers-reduced-motion: reduce so CSS/JS animations settle. */
     reducedMotion?: boolean;
+    /**
+     * JS expression polled in the page until truthy after settle, before
+     * `evalJs` and capture — the caller's "app is interactive" signal so a
+     * synthetic click in `evalJs` lands after framework hydration (issue #715).
+     * Local backend only — throws if the resolved backend is remote.
+     */
+    waitForExpr?: string;
     /** 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). */
@@ -127,6 +134,7 @@ export interface CaptureScreenshotOptions {
         waitUntil: WaitUntil;
         hide?: string[];
         reducedMotion?: boolean;
+        waitForExpr?: string;
         evalJs?: string;
         initScript?: string;
         measureSelectors?: string[];

package/dist/screenshot.js

@@ -290,6 +290,12 @@ 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");
     }
+    // --wait-for polls a JS predicate via the live local page (page.waitForFunction);
+    // the remote renderer has no eval escape hatch to evaluate it. Fail fast
+    // rather than silently ignore the caller's readiness signal.
+    if (backend === "remote" && opts.waitForExpr !== undefined) {
+        throw new UploadsError("--wait-for is 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
@@ -315,6 +321,7 @@ export async function captureScreenshot(opts) {
             waitUntil,
             hide,
             reducedMotion: opts.reducedMotion,
+            waitForExpr: opts.waitForExpr,
             evalJs: opts.evalJs,
             initScript: opts.initScript,
             measureSelectors: opts.measureSelectors,

package/package.json

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