Merge pull request #16 from HarperFast/fix/scroll-reactive-header-settle

fix(browser): settle at top after scroll so scroll-reactive headers re-reveal (v1.6.0)

Author: harper-joseph

packages/browser/README.md

@@ -91,7 +91,7 @@ include what you change:
 		"networkIdleMs": 300,
 		"networkIdleTimeoutMs": 1000,
 	},
-	"scroll": { "enabled": true, "stepMs": 200 }, // scroll to bottom to trigger lazy content
+	"scroll": { "enabled": true, "stepMs": 200, "topSettleMs": 300 }, // scroll to bottom for lazy content; topSettleMs lets scroll-reactive headers re-reveal at the top before serializing
 	"postProcess": {
 		"stripScripts": true, // remove executable <script> (keeps application/ld+json etc.)
 		"inlineEmptyStyleSheets": true,

packages/browser/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@harperfast/prerender-browser",
-	"version": "1.5.3",
+	"version": "1.6.0",
 	"type": "module",
 	"description": "Headless-browser render library for Harper Prerender: claims render jobs from the @harperfast/prerender queue, renders pages in headless Chrome (Puppeteer), and posts the HTML back. Embedded by a render service and configured entirely via startWorker() options.",
 	"keywords": [

packages/browser/src/config.ts

@@ -96,6 +96,15 @@ export type ScrollConfig = {
 	 * `navigation.domStableTolerance` controls how much late churn is ignored. Default 2.
 	 */
 	settleStablePasses: number;
+	/**
+	 * After scrolling back to the top (end of the scroll/settle phase), wait this many ms
+	 * before serializing so scroll-reactive UI returns to its top state. Sticky/compact
+	 * headers commonly hide the main header on scroll-down and re-reveal it only at the
+	 * top via a throttled scroll handler that runs a tick *after* `scrollTo(0, 0)` — with
+	 * no wait, the snapshot captures the header mid-hide (a blank band). `0` disables the
+	 * wait. Default 300.
+	 */
+	topSettleMs: number;
 };
 
 export type PostProcessConfig = {
@@ -166,7 +175,7 @@ export const defaultConfig = (): PrerenderConfig => ({
 		domStablePollMs: 250,
 		domStableTolerance: 8,
 	},
-	scroll: { enabled: true, stepMs: 200, settleUntilStable: false, settleStablePasses: 2 },
+	scroll: { enabled: true, stepMs: 200, settleUntilStable: false, settleStablePasses: 2, topSettleMs: 300 },
 	postProcess: {
 		stripScripts: true,
 		inlineEmptyStyleSheets: true,

packages/browser/src/renderer.ts

@@ -232,7 +232,22 @@ const renderer: Renderer = async (page, job) => {
 			else stablePasses = 0;
 			last = count;
 		}
+		await scrollToTop();
+	};
+
+	// Return to the top and let scroll-reactive UI settle before we serialize. Sticky/
+	// compact headers hide the main header on scroll-down and re-reveal it only at the top
+	// via a throttled scroll handler that fires a tick *after* scrollTo(0, 0); serializing
+	// immediately captures the header mid-hide (a blank band). Hold for topSettleMs so that
+	// handler runs first. The wait is a Node-side timer (not an in-page requestAnimationFrame
+	// flush) on purpose: rAF can be paused indefinitely in a backgrounded headless tab, which
+	// would hang the render — and since we serialize the DOM (not a paint), only the handler's
+	// class flip needs to land, which the wall-clock wait covers regardless of how it's scheduled.
+	const scrollToTop = async () => {
 		await page.evaluate(() => window.scrollTo(0, 0)).catch(noop);
+		if (config.scroll.topSettleMs > 0) {
+			await new Promise((resolve) => setTimeout(resolve, config.scroll.topSettleMs));
+		}
 	};
 
 	if (config.scroll.enabled && config.scroll.settleUntilStable) {
@@ -243,7 +258,7 @@ const renderer: Renderer = async (page, job) => {
 			// (e.g. so a scroll-aware navbar renders in its default state).
 			await page.evaluate(scrollToBottom, config.scroll.stepMs);
 			await networkIdle();
-			await page.evaluate(() => window.scrollTo(0, 0));
+			await scrollToTop();
 		}
 		await networkIdle();
 		await domStable();

packages/browser/test/config.test.ts

@@ -22,6 +22,7 @@ test('defaults reproduce the original hardcoded behavior', () => {
 	assert.deepEqual(config.block.urlPatterns, []);
 	assert.equal(config.navigation.waitUntil, 'domcontentloaded');
 	assert.equal(config.scroll.enabled, true);
+	assert.equal(config.scroll.topSettleMs, 300);
 	assert.equal(config.postProcess.stripScripts, true);
 	assert.equal(config.injectWebComponentsPolyfill, true);
 });