feat(chromium): skip lifecycle waits when waitForExpression or waitForSelector is set

pkg/modules/chromium/tasks.go

@@ -328,7 +328,32 @@ func userAgentOverride(logger *slog.Logger, userAgent string) chromedp.ActionFun
 // 	}
 // }
 
-func navigateActionFunc(logger *slog.Logger, url string, skipNetworkIdleEvent, skipNetworkAlmostIdleEvent bool) chromedp.ActionFunc {
+// navigateOptions carries the lifecycle-gating knobs for
+// [navigateActionFunc].
+type navigateOptions struct {
+	// SkipNetworkIdleEvent, when true, skips the wait for the
+	// "networkIdle" lifecycle event.
+	SkipNetworkIdleEvent bool
+
+	// SkipNetworkAlmostIdleEvent, when true, skips the wait for the
+	// "networkAlmostIdle" lifecycle event.
+	SkipNetworkAlmostIdleEvent bool
+
+	// SkipLifecycleEvents, when true, returns as soon as the
+	// [page.Navigate] RPC ack returns. All lifecycle waits
+	// (DomContentEventFired, LoadEventFired, LoadingFinished, and
+	// both network-idle events) are bypassed. Callers set this when
+	// the operator provided an explicit readiness signal
+	// (waitForExpression or waitForSelector) that will gate the
+	// downstream print or screenshot action, so Gotenberg does not
+	// need to also impose its own lifecycle gate. Pages whose load
+	// lifecycle never fires cleanly (blocking scripts, streaming
+	// responses, misbehaving iframes) otherwise stall navigate and
+	// starve the explicit signal.
+	SkipLifecycleEvents bool
+}
+
+func navigateActionFunc(logger *slog.Logger, url string, opts navigateOptions) chromedp.ActionFunc {
 	return func(ctx context.Context) error {
 		logger.DebugContext(ctx, fmt.Sprintf("navigate to '%s'", url))
 
@@ -337,19 +362,24 @@ func navigateActionFunc(logger *slog.Logger, url string, skipNetworkIdleEvent, s
 			return fmt.Errorf("navigate to '%s': %w", url, err)
 		}
 
+		if opts.SkipLifecycleEvents {
+			logger.DebugContext(ctx, "skipping lifecycle events; waitForExpression or waitForSelector gates readiness")
+			return nil
+		}
+
 		waitFunc := []func() error{
 			waitForEventDomContentEventFired(ctx, logger),
 			waitForEventLoadEventFired(ctx, logger),
 			waitForEventLoadingFinished(ctx, logger),
 		}
 
-		if !skipNetworkIdleEvent {
+		if !opts.SkipNetworkIdleEvent {
 			waitFunc = append(waitFunc, waitForEventNetworkIdle(ctx, logger))
 		} else {
 			logger.DebugContext(ctx, "skipping network idle event")
 		}
 
-		if !skipNetworkAlmostIdleEvent {
+		if !opts.SkipNetworkAlmostIdleEvent {
 			waitFunc = append(waitFunc, waitForEventNetworkAlmostIdle(ctx, logger))
 		} else {
 			logger.DebugContext(ctx, "skipping network almost idle event")