diff --git a/.github/scripts/integration-governance.cjs b/.github/scripts/integration-governance.cjs index 84de24ec01..b82a4b1381 100644 --- a/.github/scripts/integration-governance.cjs +++ b/.github/scripts/integration-governance.cjs @@ -9,7 +9,7 @@ const MAX_COMMITS = 1000; const MAX_AUTHOR_BATCH = 50; // This literal is inside the enrolled .github closure. A caller-supplied // preparedBy.sourceSHA must never choose a new executable verifier tree. -const TRUSTED_SCRIPTS_TREE = '55bc8023d6e79acf4b3eeb284bd4c2f927537630'; +const TRUSTED_SCRIPTS_TREE = 'aa20dad41934337be58b07e3812d78e9c41310e2'; const SOURCE = 'https://github.com/kubernetes-sigs/kubebuilder-release-tools/tree/012269a88fa4c034a0acf1ba84c26b195c0dbab4'; const sha = value => crypto.createHash('sha256').update(value).digest('hex'); const git = (args, cwd = process.cwd()) => diff --git a/src/docs/dashboard-source-layout.md b/src/docs/dashboard-source-layout.md index e3066e0b92..98c36cb959 100644 --- a/src/docs/dashboard-source-layout.md +++ b/src/docs/dashboard-source-layout.md @@ -67,9 +67,19 @@ focuses decision actions without scrolling, which would otherwise close the dialog through its scroll-away listener. Control probes await a bounded stable scroll/visual viewport before every mandatory hit-test; native pointer/keyboard reports also retain each decision action's bounds and actual hit target. -Fixture transitions close the preceding terminal/export dialog through its -native close API, releasing its captured keyboard listener instead of leaving -an unrelated modal over the activity controls. Native pointer preconditions +Before any state probes or screenshots, bounded render readiness waits for +the actual body/root opacity and visibility and two stable layout frames. +It never forces styles or treats a fixed sleep as proof: the file-page cannot +receive the status refresh that normally reveals the body before its boot +fallback. Each viewport/theme report records page readiness; viewport captures +also record their own readiness. A real timeout remains a capture failure, +including when animation frames never arrive. +Fixture transitions use the existing native overlay dismissal policy for all +three legacy modal producers: Settings, Knowledge Sources, and terminal/export. +Cleanup is bounded, waits for the production modal observer, and rejects any +remaining fixture modal or root/body scroll lock. It does not delete modal DOM, +hide overlays manually, or remove scroll-lock classes to manufacture a pass. +Each activity report records cleanup evidence. Native pointer preconditions also hit-test the trigger itself. Viewport captures explicitly target the current document scroll rectangle; density and pointer/keyboard reports inspect their actual PNG pixels, excluding scrollbars, and fail a uniform-background diff --git a/src/pkg/dashboard/stage_tracker_activity.test.js b/src/pkg/dashboard/stage_tracker_activity.test.js index 40be0adeb4..5e0f1cd250 100644 --- a/src/pkg/dashboard/stage_tracker_activity.test.js +++ b/src/pkg/dashboard/stage_tracker_activity.test.js @@ -2,6 +2,8 @@ const test = require('node:test'); const assert = require('node:assert/strict'); const fs = require('node:fs'); const path = require('node:path'); +const vm = require('node:vm'); +const { pathToFileURL } = require('node:url'); const root = path.join(__dirname, 'static-src', 'js'); const strip = fs.readFileSync(path.join(root, 'tracker-row-strip.js'), 'utf8'); @@ -277,8 +279,10 @@ test('canonical activity browser wiring is retained (not browser/visual proof)', assert.match(harness, /failures\.push\(\.\.\.pointerCapture\.failures\)/); assert.match(harness, /failures\.push\(\.\.\.keyboardCapture\.failures\)/); assert.match(harness, /if \(!point\.triggerReachable\) failures\.push/); - assert.match(harness, /document\.querySelectorAll\('\.hive-dialog-overlay'\)[\s\S]*?el\.hiveDialogClose\(\)/); - assert.match(harness, /Prior fixture dialog survived native cleanup/); + assert.match(harness, /resetDashboardFixtureOverlays\.toString\(\)/); + assert.match(harness, /const pageReadiness = await renderReady\(\)/); + assert.match(harness, /const readiness = await renderReady\(\)/); + assert.match(harness, /provenance, pageReadiness, fixtureCleanup, fixture, results/); assert.match(harness, /screenshot\(prefix \+ '-decision-pointer\.png', true\)/); assert.match(harness, /screenshot\(prefix \+ '-decision-keyboard\.png', true\)/); assert.match(harness, /every native decision action must be reachable and unobscured/); @@ -297,6 +301,130 @@ test('canonical activity browser wiring is retained (not browser/visual proof)', assert.match(fixture, /__activityDensityCleanup/); }); +function simulatedBrowser() { + let time = 0, sequence = 0, locked = false; + const frames = new Map(), timers = new Map(), overlays = []; + const style = { opacity: '0', visibility: 'visible', display: 'block' }; + const classList = { contains: name => name === 'modal-open' && locked }; + const body = { classList, getBoundingClientRect: () => ({ width: 1440, height: 2000 }) }; + const context = { + document: { body, documentElement: { classList }, readyState: 'complete', + visibilityState: 'visible', querySelectorAll: () => overlays }, + getComputedStyle: node => node === body ? style : { opacity: '1', visibility: 'visible', display: 'block' }, + performance: { now: () => time }, + requestAnimationFrame: callback => { const id = ++sequence; frames.set(id, callback); return id; }, + cancelAnimationFrame: id => frames.delete(id), + setTimeout: callback => { const id = ++sequence; timers.set(id, callback); return id; }, + clearTimeout: id => timers.delete(id), + hiveOverlayIsOpen: overlay => overlay.open, + hiveDismissTopOverlay: () => { + const overlay = overlays.find(candidate => candidate.open); + if (!overlay) return false; + overlay.open = false; + return true; + }, + }; + return { context, style, overlays, frames, timers, + lock(value) { locked = value; }, + frame() { + time += 16; + const callbacks = [...frames.values()]; frames.clear(); + callbacks.forEach(callback => callback(time)); + }, + expire() { + time += 10000; + const callbacks = [...timers.values()]; timers.clear(); + callbacks.forEach(callback => callback()); + }, + }; +} + +test('canonical paint readiness waits for real opacity and stable frames without changing page styles', async () => { + const helpers = await import(pathToFileURL(path.join(__dirname, '../../scripts/fixtures/dashboard-browser-readiness.mjs')).href); + assert.throws(() => helpers.waitForDashboardPaint(), /dedicated preview/); + const browser = simulatedBrowser(); + const ready = vm.runInNewContext('(' + helpers.waitForDashboardPaint.toString() + ')', browser.context); + const pending = ready({ dedicatedPreview: true }); + browser.frame(); + assert.equal(browser.frames.size, 1, 'body opacity zero cannot pass'); + browser.style.opacity = '0.5'; + browser.frame(); + assert.equal(browser.frames.size, 1, 'the boot fade-in must finish, not merely start'); + browser.style.opacity = '1'; + browser.frame(); + assert.equal(browser.frames.size, 1, 'one visible frame cannot pass'); + browser.style.visibility = 'hidden'; + browser.frame(); + browser.style.visibility = 'visible'; + browser.frame(); + assert.equal(browser.frames.size, 1, 'hidden frames reset consecutive readiness'); + browser.frame(); + const result = await pending; + assert.equal(result.ready, true); + assert.equal(result.stableFrames, 2); + assert.equal(result.state.opacity, '1'); + assert.equal(browser.frames.size, 0); + assert.equal(browser.timers.size, 0); + assert.equal(browser.context.document.body.style, undefined, 'readiness never forces body styles'); +}); + +test('render readiness has a real deadline even when animation frames never arrive', async () => { + const helpers = await import(pathToFileURL(path.join(__dirname, '../../scripts/fixtures/dashboard-browser-readiness.mjs')).href); + for (const sample of [false, true]) { + const browser = simulatedBrowser(); + const ready = vm.runInNewContext('(' + helpers.waitForDashboardPaint.toString() + ')', browser.context); + const pending = ready({ dedicatedPreview: true }); + if (sample) browser.frame(); + browser.expire(); + await assert.rejects(pending, error => /render readiness timed out/.test(error.message) && + (!sample || /"opacity":"0"/.test(error.message))); + assert.equal(browser.frames.size, 0, 'timeout cancels a pending animation frame'); + assert.equal(browser.timers.size, 0); + assert.equal(browser.style.opacity, '0', 'timeout must not turn invisible content into a pass'); + } +}); + +test('native fixture reset closes every legacy modal and waits for the production scroll-lock observer', async () => { + const helpers = await import(pathToFileURL(path.join(__dirname, '../../scripts/fixtures/dashboard-browser-readiness.mjs')).href); + await assert.rejects(helpers.resetDashboardFixtureOverlays(), /dedicated preview/); + const browser = simulatedBrowser(); + browser.overlays.push({ id: 'terminal-export', open: true }, { id: 'kb-modal-overlay', open: true }, { id: 'config-overlay', open: true }); + browser.lock(true); + const reset = vm.runInNewContext('(' + helpers.resetDashboardFixtureOverlays.toString() + ')', browser.context); + const pending = reset({ dedicatedPreview: true }); + assert.ok(browser.overlays.every(overlay => !overlay.open), 'all three legacy producers use native dismissal'); + browser.lock(false); + browser.frame(); + const result = await pending; + assert.equal(result.dismissals, 3); + assert.equal(result.remaining.length, 0); + assert.equal(result.scrollLocked, false); + assert.equal(browser.timers.size, 0); + const source = helpers.resetDashboardFixtureOverlays.toString(); + assert.doesNotMatch(source, /\.remove\(|classList\.(?:add|remove)|style\.\w+\s*=/, 'no raw modal deletion, hiding, or manual scroll-lock override'); +}); + +test('native cleanup rejects undispatched overlays, stuck dismissal loops, scroll locks and stalled observer frames', async () => { + const helpers = await import(pathToFileURL(path.join(__dirname, '../../scripts/fixtures/dashboard-browser-readiness.mjs')).href); + for (const failure of ['overlay', 'bound', 'lock', 'frame']) { + const browser = simulatedBrowser(); + let calls = 0; + browser.context.hiveDismissTopOverlay = () => { calls++; return failure === 'bound'; }; + if (failure === 'overlay') browser.overlays.push({ id: 'kb-modal-overlay', open: true }); + if (failure === 'lock') browser.lock(true); + const reset = vm.runInNewContext('(' + helpers.resetDashboardFixtureOverlays.toString() + ')', browser.context); + const pending = reset({ dedicatedPreview: true, maxDismissals: 3 }); + if (failure === 'frame') browser.expire(); else browser.frame(); + await assert.rejects(pending, error => { + const expected = { overlay: 'kb-modal-overlay', bound: 'dismissal bound', lock: '"scrollLocked":true', frame: 'observer did not settle' }; + return error.message.includes(expected[failure]); + }); + assert.ok(calls <= 3, 'native cleanup is bounded'); + assert.equal(browser.frames.size, 0); + assert.equal(browser.timers.size, 0); + } +}); + test('browser probes require a dedicated preview and cannot count offscreen header controls as success', async () => { for (const name of ['tracker-header-geometry.js', 'tracker-decision-interaction.js']) { const source = fs.readFileSync(path.join(__dirname, 'webstatic/testdata', name), 'utf8'); diff --git a/src/scripts/dashboard-mobile-shots.mjs b/src/scripts/dashboard-mobile-shots.mjs index 2e35d1cfd5..635a342f1e 100644 --- a/src/scripts/dashboard-mobile-shots.mjs +++ b/src/scripts/dashboard-mobile-shots.mjs @@ -31,6 +31,7 @@ import path from 'node:path'; import { createHash } from 'node:crypto'; import { preparationRailLayoutFixture } from './fixtures/dashboard-preparation-rail.mjs'; import { activityDensityFixture } from './fixtures/dashboard-activity-density.mjs'; +import { waitForDashboardPaint, resetDashboardFixtureOverlays } from './fixtures/dashboard-browser-readiness.mjs'; const CHROME_CANDIDATES = [ process.env.CHROME_BIN, @@ -300,7 +301,9 @@ async function main() { if (result.result.exceptionDetails) throw new Error(result.result.exceptionDetails.exception?.description || 'evaluate failed'); return result.result.result.value; }; + const renderReady = () => evaluate('(' + waitForDashboardPaint.toString() + ')({ dedicatedPreview: true })'); const screenshot = async (file, viewportOnly = false) => { + const readiness = await renderReady(); const viewport = viewportOnly ? await evaluate(`({ x: scrollX, y: scrollY, width: innerWidth, height: innerHeight, clientWidth: document.documentElement.clientWidth, @@ -329,7 +332,7 @@ async function main() { } return { painted, width: canvas.width, height: canvas.height, inspectedWidth: width, inspectedHeight: height }; })()`); - return { file, viewport, clip, ...pixels, + return { file, readiness, viewport, clip, ...pixels, failures: pixels.painted ? [] : ['Viewport capture contains only a uniform background; DOM assertions are not visual proof'] }; }; const nativeDecisionInput = async prefix => { @@ -414,19 +417,10 @@ async function main() { // Each state callback is best-effort: a missing helper yields a skipped shot, not a harness error. const setThemeJS = (theme) => `document.body.classList.toggle('light-mode', ${theme === 'light'}); document.documentElement.style.colorScheme = '${theme}'; true`; - const resetJS = `(() => { + const resetJS = `(async () => { window.__activityDensityCleanup?.(); document.getElementById('preparation-rail-layout-fixture')?.remove(); - // The preceding terminal state owns a native dialog and capture listener. - // Close it through its API, not by hiding/removing its DOM. - document.querySelectorAll('.hive-dialog-overlay').forEach((el) => { - if (typeof el.hiveDialogClose !== 'function') throw new Error('Cannot clean up prior fixture dialog'); - el.hiveDialogClose(); - }); - if (document.querySelector('.hive-dialog-overlay')) throw new Error('Prior fixture dialog survived native cleanup'); - document.querySelectorAll('.config-overlay, .modal-overlay').forEach((el) => { el.classList.add('hidden'); }); - document.documentElement.classList.remove('modal-open'); document.body.classList.remove('modal-open'); - return true; + return await (${resetDashboardFixtureOverlays.toString()})({ dedicatedPreview: true }); })()`; const collapseAllJS = `(() => { const ids = Array.from(document.querySelectorAll('[data-dashboard-section]')).map((el) => el.id).filter(Boolean); @@ -471,6 +465,8 @@ async function main() { link.href = url; })))`); await evaluate(setThemeJS(theme)); + const pageReadiness = await renderReady(); + let fixtureCleanup; const sectionIDs = await evaluate(collapseAllJS); const states = [{ name: 'collapsed', run: async () => true }]; @@ -515,14 +511,14 @@ async function main() { const nativeOK = native.failures.length === 0; results.push({ probe: 'native-CDP-pointer-keyboard', ok: nativeOK, result: native }); if (!nativeOK) activityFailures.push(vp.name + ' ' + theme + ' native input'); - const result = { viewport: vp.name, theme, provenance, fixture, results }; + const result = { viewport: vp.name, theme, provenance, pageReadiness, fixtureCleanup, fixture, results }; activityReport.push(result); fs.writeFileSync(path.join(opts.out, `${vp.name}-${theme}-activity-probes.json`), JSON.stringify(result, null, 2) + '\n'); return true; } }); for (const state of states) { - await evaluate(resetJS); + fixtureCleanup = await evaluate(resetJS); let ok; try { ok = await state.run(); } catch (error) { diff --git a/src/scripts/fixtures/dashboard-browser-readiness.mjs b/src/scripts/fixtures/dashboard-browser-readiness.mjs new file mode 100644 index 0000000000..b731382721 --- /dev/null +++ b/src/scripts/fixtures/dashboard-browser-readiness.mjs @@ -0,0 +1,72 @@ +// Serialized into the existing harness's isolated file:// Chrome page only. +export function waitForDashboardPaint({ dedicatedPreview = false, timeoutMs = 10000, stableFrames = 2 } = {}) { + if (!dedicatedPreview) throw new Error('Render readiness requires a dedicated preview page'); + return new Promise((resolve, reject) => { + const started = performance.now(); + let frame, last = null, previous = '', stable = 0; + const finish = (error, value) => { + clearTimeout(timer); + cancelAnimationFrame(frame); + if (error) reject(error); else resolve(value); + }; + const timer = setTimeout(() => finish(new Error(JSON.stringify({ + failures: ['Dashboard render readiness timed out'], timeoutMs, last, + }))), timeoutMs); + const sample = () => { + const body = document.body, root = document.documentElement; + const bodyStyle = body && getComputedStyle(body), rootStyle = root && getComputedStyle(root); + const box = body?.getBoundingClientRect(); + last = { readyState: document.readyState, visibilityState: document.visibilityState, + opacity: bodyStyle?.opacity, visibility: bodyStyle?.visibility, display: bodyStyle?.display, + rootOpacity: rootStyle?.opacity, rootVisibility: rootStyle?.visibility, rootDisplay: rootStyle?.display, + width: box?.width, height: box?.height }; + const ready = document.readyState !== 'loading' && document.visibilityState === 'visible' && + last.opacity === '1' && last.visibility === 'visible' && last.display !== 'none' && + last.rootOpacity === '1' && last.rootVisibility === 'visible' && last.rootDisplay !== 'none' && + last.width > 0 && last.height > 0; + const signature = JSON.stringify(last); + stable = ready ? (signature === previous ? stable + 1 : 1) : 0; + previous = signature; + if (stable >= stableFrames) { + finish(null, { ready: true, elapsedMs: performance.now() - started, stableFrames: stable, state: last }); + } else { + frame = requestAnimationFrame(sample); + } + }; + frame = requestAnimationFrame(sample); + }); +} + +export async function resetDashboardFixtureOverlays({ dedicatedPreview = false, maxDismissals = 32, settleTimeoutMs = 1000 } = {}) { + if (!dedicatedPreview) throw new Error('Fixture cleanup requires a dedicated preview page'); + if (typeof hiveDismissTopOverlay !== 'function' || typeof hiveOverlayIsOpen !== 'function') { + throw new Error('Native dashboard overlay cleanup is unavailable'); + } + // These are the three modal producers in the legacy screenshot sequence. + const ownedSelector = '#config-overlay, #kb-modal-overlay, .hive-dialog-overlay'; + const remaining = () => [...document.querySelectorAll(ownedSelector)] + .filter(overlay => hiveOverlayIsOpen(overlay)) + .map(overlay => overlay.id || overlay.className); + let dismissals = 0; + for (; dismissals < maxDismissals; dismissals++) { + if (!hiveDismissTopOverlay()) break; + } + if (dismissals === maxDismissals) { + throw new Error(JSON.stringify({ failures: ['Native overlay cleanup exceeded its dismissal bound'], + maxDismissals, remaining: remaining() })); + } + // Let the production modal observer release its root/body scroll lock. + await new Promise((resolve, reject) => { + const frame = requestAnimationFrame(() => { clearTimeout(timer); resolve(); }); + const timer = setTimeout(() => { + cancelAnimationFrame(frame); + reject(new Error('Native fixture cleanup observer did not settle before timeout')); + }, settleTimeoutMs); + }); + const state = { dismissals, remaining: remaining(), + scrollLocked: document.documentElement.classList.contains('modal-open') || document.body.classList.contains('modal-open') }; + if (state.remaining.length || state.scrollLocked) { + throw new Error(JSON.stringify({ failures: ['Prior fixture overlay or modal-open scroll lock survived native cleanup'], ...state })); + } + return state; +}