Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Make Workloads reading explanations accessible without hover

pulse-triage[bot]adef8413972f
diff --git a/docs/release-control/v6/internal/subsystems/performance-and-scalability.md b/docs/release-control/v6/internal/subsystems/performance-and-scalability.md
index 19c4fefe68..fca45804ca 100644
--- a/docs/release-control/v6/internal/subsystems/performance-and-scalability.md
+++ b/docs/release-control/v6/internal/subsystems/performance-and-scalability.md
@@ -15,6 +15,31 @@
## Purpose
+### Workloads reading explanations work without hover
+
+The existing Memory/Disk freshness and cache cues are native disclosure buttons.
+`WorkloadReadingStatus` opens the shared Dialog only on activation and shows the
+already-qualified reason, source and original observation time supplied to the
+row. It creates no read, timer, layout observer, collection or recovery action.
+Unmarked current cache-aware readings add no component or control. Dense row
+geometry, column widths, bars/sparklines and hover-history ownership remain.
+The phone target extends within the cell without increasing the row rhythm.
+
+Same-identity observations update an open explanation; a genuinely current
+observation removes the cue and returns focus to the row's existing disclosure.
+A changed canonical identity closes the old explanation, even when names match.
+Dialog Escape, backdrop and Close return focus to the original cue; activation
+never opens the enclosing row. This is accessible evidence, not confirmation of
+thaw, writes, guest-agent availability or ordinary restart recovery.
+
+`GuestRow.test.tsx` covers the actual row/control, safe fixed copy, cache caveat,
+original time, identity replacement and current-reading withdrawal. The
+production fixture `browser-tests/reading-status-access.cjs` consumes canonical
+Resources through `useWorkloads` and verifies desktop keyboard/narrow touch,
+settled captures, request counts, unchanged row nodes and target bounds. Browser
+proof must be recorded separately; a fixture is not accepted pixel evidence.
+
+
### Guest memory alerts do not translate unrelated samples (12 October 2026)
When the Workloads row uses host-relative memory, its existing guest drawer
@@ -323,9 +348,9 @@ proof, not a native CPU improvement, QGA/thaw result or delivery acceptance.
Visible retained/unavailable filesystem cues must fit the existing dense row
rhythm, including canonical phone/narrow column weights, without adding a new
-collector, history request, layout observer, focus target or event path. Keep
-compact copy on narrow rows and the full safe reason in assistive text and the
-existing drawer. Inline sparkline plots may shrink to preserve their numeric
+collector, history request or layout observer. Keep compact copy on narrow rows
+and the full safe reason in assistive text, the existing drawer and the
+read-only reading disclosure described below. Inline sparkline plots may shrink to preserve their numeric
value within the already assigned column; do not add forced minimum widths,
observers or a larger row to compensate. The cue stays outside the
bars/sparkline/history-lens branch, so changing display mode cannot discard freshness information; removing it
diff --git a/frontend-modern/browser-tests/build-reading-status-access.mjs b/frontend-modern/browser-tests/build-reading-status-access.mjs
new file mode 100644
index 0000000000..231f7dc49d
--- /dev/null
+++ b/frontend-modern/browser-tests/build-reading-status-access.mjs
@@ -0,0 +1,84 @@
+// Compile the real reading-access fixture before bounded browser execution.
+// Only a bounded static preview runs in the browser tree; no live compiler or guest command.
+import { build } from 'vite';
+import solid from 'vite-plugin-solid';
+import tailwindcss from '@tailwindcss/vite';
+import { stop } from 'esbuild';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const output = path.resolve(root, '../tmp/reading-status-static');
+const hash = (data) => crypto.createHash('sha256').update(data).digest('hex');
+
+try {
+ for (const variant of ['final']) {
+ const sources = {};
+ const artifacts = {};
+ const outDir = path.join(output, variant);
+ await build({
+ root,
+ // Both variants are served below their own prefix, including nested HTML.
+ base: './',
+ configFile: false,
+ publicDir: false,
+ plugins: [
+ {
+ name: 'exact-reading-access-fixture-binding',
+ enforce: 'pre',
+ generateBundle(_options, bundle) {
+ for (const id of this.getModuleIds()) {
+ if (!id.startsWith(root + '/') || id.includes('/node_modules/')) continue;
+ const file = id.split('?')[0];
+ if (!fs.existsSync(file) || !fs.statSync(file).isFile()) continue;
+ sources[path.relative(root, file)] = hash(fs.readFileSync(file));
+ }
+ for (const [file, asset] of Object.entries(bundle)) {
+ artifacts[file] = hash(asset.type === 'chunk' ? asset.code : asset.source);
+ }
+ },
+ },
+ tailwindcss(),
+ solid(),
+ ],
+ resolve: {
+ alias: { '@': path.join(root, 'src') },
+ conditions: ['import', 'browser', 'default'],
+ },
+ build: {
+ // Match the application's declared target, not Vite's older default.
+ target: 'esnext',
+ outDir,
+ emptyOutDir: true,
+ rollupOptions: { input: path.join(root, 'browser-tests/reading-status-access.html') },
+ },
+ });
+ // Hash the bytes actually written, including HTML post-processing.
+ const walk = (dir) => {
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+ const file = path.join(dir, entry.name);
+ if (entry.isDirectory()) walk(file);
+ else artifacts[path.relative(outDir, file)] = hash(fs.readFileSync(file));
+ }
+ };
+ walk(outDir);
+ fs.writeFileSync(
+ path.join(outDir, 'binding.json'),
+ JSON.stringify(
+ {
+ variant,
+ graph: hash(fs.readFileSync(path.join(root, 'package-lock.json'))),
+ builder: hash(fs.readFileSync(fileURLToPath(import.meta.url))),
+ sources,
+ artifacts,
+ },
+ null,
+ 2,
+ ) + '\n',
+ );
+ }
+} finally {
+ stop();
+}
diff --git a/frontend-modern/browser-tests/reading-status-access.cjs b/frontend-modern/browser-tests/reading-status-access.cjs
new file mode 100644
index 0000000000..337664a293
--- /dev/null
+++ b/frontend-modern/browser-tests/reading-status-access.cjs
@@ -0,0 +1,499 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const http = require('node:http');
+const { chromium, webkit } = require('playwright');
+const root = '/workspace';
+const frontend = path.join(root, 'frontend-modern');
+const output = path.join(root, 'tmp/reading-details/browser');
+const origin = 'http://127.0.0.1:5296';
+const time = '2026-10-12T20:00:00Z';
+const runtime = [
+ 'frontend-modern/src/components/Workloads/GuestRow.tsx',
+ 'frontend-modern/src/components/Workloads/WorkloadReadingStatus.tsx',
+];
+const hash = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+const result = {
+ base: 'a2e5d0fb93d69abe9eabc682126a64d12443594c',
+ sourceHashes: Object.fromEntries(
+ runtime.map((p) => [p, hash(fs.readFileSync(path.join(root, p)))]),
+ ),
+ playwright: require('playwright/package.json').version,
+ scope:
+ 'Real canonical Resources API and useWorkloads producer, actual production GuestRow, reading disclosure, shared Dialog and CSS. Synthetic read state; no guest command, native recovery, publication or availability claim.',
+ checks: [],
+ requests: [],
+ captures: [],
+ loaded: {},
+ browsers: [],
+ errors: [],
+ consoleErrors: [],
+ cleanup: {},
+};
+const initial = () => ({
+ reason: 'prev-agent-timeout',
+ state: 'last-known',
+ source: 'guest-agent-meminfo',
+ observedAt: time,
+ percent: 55,
+ instance: 'fixture-pve',
+});
+const resource = (read, control = false) => {
+ const total = 10 * 1024 ** 3;
+ const vmid = control ? 102 : 101;
+ const percent = control ? 25 : read.percent;
+ const observation = control
+ ? { state: 'current', source: 'guest-agent-meminfo', observedAt: time }
+ : {
+ state: read.state,
+ source: read.source,
+ ...(read.observedAt ? { observedAt: read.observedAt } : {}),
+ };
+ const reason = control ? undefined : read.reason;
+ return {
+ id: `${control ? 'fixture-pve' : read.instance}-pve-a-${vmid}`,
+ type: 'vm',
+ name: control ? 'fresh-control' : 'reading-guest',
+ status: 'online',
+ sources: ['proxmox'],
+ lastSeen: '2026-10-12T20:30:00Z',
+ metrics: {
+ cpu: { percent: 10 },
+ memory: { percent, used: (total * percent) / 100, total, observation },
+ disk: { percent: 50, used: total / 2, total },
+ },
+ proxmox: {
+ vmid,
+ instance: control ? 'fixture-pve' : read.instance,
+ nodeName: 'pve-a',
+ runtimeStatus: 'running',
+ guestAgentStatus: reason ? 'deferred' : 'available',
+ ...(reason ? { diskStatusReason: reason } : {}),
+ disks: [{ mountpoint: '/data', filesystem: 'ext4', total, used: total / 2 }],
+ },
+ };
+};
+let server;
+const staticRoot = path.join(root, 'tmp/reading-status-static');
+const binding = JSON.parse(fs.readFileSync(path.join(staticRoot, 'final/binding.json')));
+result.buildBindings = { final: binding };
+for (const [p, digest] of Object.entries(binding.sources)) {
+ const local = path.join(frontend, p);
+ assert.equal(hash(fs.readFileSync(local)), digest);
+ if (p.startsWith('src/')) result.loaded['frontend-modern/' + p] = digest;
+}
+(async () => {
+ fs.mkdirSync(output, { recursive: true });
+ assert.equal(
+ result.playwright,
+ JSON.parse(fs.readFileSync(path.join(root, 'tests/integration/package-lock.json'))).packages[
+ 'node_modules/@playwright/test'
+ ].version,
+ );
+ server = http.createServer((request, response) => {
+ const pathname = decodeURIComponent(new URL(request.url, origin).pathname);
+ const local = path.resolve(staticRoot, '.' + pathname);
+ if (
+ !local.startsWith(staticRoot + '/') ||
+ !fs.existsSync(local) ||
+ !fs.statSync(local).isFile()
+ ) {
+ response.writeHead(404);
+ response.end();
+ return;
+ }
+ const extension = path.extname(local);
+ response.writeHead(200, {
+ 'Content-Type':
+ extension === '.html'
+ ? 'text/html'
+ : extension === '.js'
+ ? 'text/javascript'
+ : extension === '.css'
+ ? 'text/css'
+ : 'application/octet-stream',
+ });
+ response.end(fs.readFileSync(local));
+ });
+ await new Promise((resolve, reject) => {
+ server.once('error', reject);
+ server.listen(5296, '127.0.0.1', resolve);
+ });
+ for (const spec of [
+ {
+ name: 'desktop',
+ engine: chromium,
+ width: 1365,
+ height: 900,
+ colorScheme: 'light',
+ locale: 'en-GB',
+ timezoneId: 'Europe/London',
+ },
+ {
+ name: 'phone',
+ engine: webkit,
+ width: 390,
+ height: 844,
+ colorScheme: 'dark',
+ locale: 'en-GB',
+ timezoneId: 'Asia/Tokyo',
+ },
+ ]) {
+ const browser = await spec.engine.launch(
+ spec.engine === chromium
+ ? { headless: true, channel: 'chromium', args: ['--no-sandbox'] }
+ : { headless: true },
+ );
+ const context = await browser.newContext({
+ viewport: { width: spec.width, height: spec.height },
+ isMobile: spec.width < 768,
+ hasTouch: spec.width < 768,
+ colorScheme: spec.colorScheme,
+ locale: spec.locale,
+ timezoneId: spec.timezoneId,
+ });
+ result.browsers.push({
+ name: spec.name,
+ version: browser.version(),
+ width: spec.width,
+ height: spec.height,
+ locale: spec.locale,
+ timezoneId: spec.timezoneId,
+ });
+ try {
+ const page = await context.newPage();
+ page.setDefaultTimeout(10000);
+ page.on('pageerror', (error) =>
+ result.errors.push({ browser: spec.name, message: error.message }),
+ );
+ page.on('console', (entry) => {
+ if (entry.type() === 'error')
+ result.consoleErrors.push({ browser: spec.name, message: entry.text() });
+ });
+ await page.clock.setFixedTime(new Date('2026-10-12T20:30:00Z'));
+ let read = initial();
+ await page.route('**/*', async (route) => {
+ const url = new URL(route.request().url());
+ if (url.origin !== origin) {
+ result.errors.push({ external: url.origin });
+ return route.abort();
+ }
+ if (url.pathname.startsWith('/api/')) {
+ const record = {
+ browser: spec.name,
+ path: url.pathname,
+ method: route.request().method(),
+ };
+ result.requests.push(record);
+ assert.equal(record.method, 'GET');
+ let body;
+ if (url.pathname === '/api/resources')
+ body = { data: [resource(read), resource(read, true)], meta: { totalPages: 1 } };
+ else if (url.pathname === '/api/alerts/activation') body = { enabled: false };
+ else if (url.pathname === '/api/alerts/config')
+ body = { guestDefaults: {}, hostDefaults: {} };
+ else if (url.pathname === '/api/alerts/active') body = [];
+ else if (url.pathname === '/api/ai/intelligence/anomalies')
+ body = { anomalies: [], count: 0 };
+ else if (url.pathname === '/api/ai/intelligence') body = null;
+ else if (url.pathname === '/api/metrics-store/history')
+ body = {
+ resourceType: url.searchParams.get('resourceType'),
+ resourceId: url.searchParams.get('resourceId'),
+ range: url.searchParams.get('range'),
+ start: Date.parse(time),
+ end: Date.parse(time) + 1800000,
+ metrics: {},
+ source: 'store',
+ };
+ else if (url.pathname.startsWith('/api/guests/metadata/')) body = { customUrl: '' };
+ else if (
+ url.pathname.startsWith('/api/resources/') &&
+ url.pathname.endsWith('/operator-state')
+ )
+ body = { configured: false, state: null };
+ else {
+ record.unmatched = true;
+ result.errors.push({ unmatched: url.pathname });
+ body = {};
+ }
+ return route.fulfill({ json: body });
+ }
+ const variant = 'final';
+ const artifact = url.pathname.slice(variant.length + 2);
+ if (['.js', '.css', '.html'].includes(path.extname(artifact))) {
+ const digest = hash(fs.readFileSync(path.join(staticRoot, variant, artifact)));
+ assert.equal(digest, result.buildBindings[variant].artifacts[artifact]);
+ }
+ if (url.pathname.startsWith('/src/')) {
+ const local = path.join(frontend, decodeURIComponent(url.pathname));
+ if (fs.existsSync(local))
+ result.loaded[path.relative(root, local)] = hash(fs.readFileSync(local));
+ }
+ return route.continue();
+ });
+ await page.routeWebSocket(/\/ws(?:\?|$)/, () => {});
+ await page.goto(`${origin}/final/browser-tests/reading-status-access.html`, {
+ waitUntil: 'domcontentloaded',
+ timeout: 30000,
+ });
+ if (spec.colorScheme === 'dark')
+ await page.evaluate(() => document.documentElement.classList.add('dark'));
+ const row = page.locator('tr.workload-row').first();
+ await row.getByRole('button', { name: /^Disk reading for/ }).waitFor();
+ await page.evaluate(() => {
+ window.__originalReadingRow = document.querySelector('tr.workload-row');
+ });
+ const baselineHeight = await row.evaluate(
+ (element) => element.getBoundingClientRect().height,
+ );
+ const check = (name, detail = {}) =>
+ result.checks.push({ browser: spec.name, name, ...detail });
+ const capture = async (name) => {
+ await page.evaluate(async () => {
+ await document.fonts.ready;
+ await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+ });
+ await page.waitForFunction(() => {
+ const panel = document.querySelector('[role="dialog"]');
+ const backdrop = document.querySelector('[data-dialog-backdrop]');
+ return (
+ panel &&
+ backdrop &&
+ getComputedStyle(panel).opacity === '1' &&
+ getComputedStyle(backdrop).opacity === '1' &&
+ panel.getAnimations().every((animation) => animation.playState === 'finished')
+ );
+ });
+ const p = path.join(output, `${spec.name}-${name}.png`);
+ await page.screenshot({ path: p, fullPage: true, animations: 'disabled' });
+ result.captures.push({
+ path: path.relative(root, p),
+ bytes: fs.statSync(p).size,
+ sha256: hash(fs.readFileSync(p)),
+ });
+ };
+ const update = async (change) => {
+ read = { ...read, ...change };
+ await page.evaluate(async () => window.__readingStatusAccess.refetch());
+ await page.evaluate(() => new Promise((r) => requestAnimationFrame(r)));
+ assert.equal(
+ await page.evaluate(
+ () => window.__originalReadingRow === document.querySelector('tr.workload-row'),
+ ),
+ true,
+ );
+ };
+ const trigger = (metric) =>
+ row.getByRole('button', { name: new RegExp(`^${metric} reading for`) });
+ const dialog = () => page.getByRole('dialog');
+ const geometry = async (metric) => {
+ const value = await trigger(metric).evaluate((element) => {
+ const rect = element.getBoundingClientRect();
+ const cell = element.closest('td').getBoundingClientRect();
+ const label = element.querySelector('span').getBoundingClientRect();
+ return {
+ width: rect.width,
+ height: rect.height,
+ rowHeight: element.closest('tr').getBoundingClientRect().height,
+ fits:
+ rect.left >= cell.left - 1 &&
+ rect.right <= cell.right + 1 &&
+ rect.top >= cell.top - 1 &&
+ rect.bottom <= cell.bottom + 1,
+ textFits: label.left >= cell.left - 1 && label.right <= cell.right + 1,
+ };
+ });
+ assert.ok(value.fits, `Reading target escapes its cell: ${JSON.stringify(value)}`);
+ assert.ok(value.textFits, `Reading label clipped: ${JSON.stringify(value)}`);
+ assert.ok(
+ value.rowHeight <= baselineHeight + 0.5,
+ `Dense row grew: ${JSON.stringify(value)}`,
+ );
+ if (spec.width < 768) {
+ assert.ok(value.width >= 24);
+ assert.ok(value.height >= 24);
+ }
+ return value;
+ };
+ const open = async (metric) => {
+ const before = result.requests.length;
+ const button = trigger(metric);
+ const shape = await geometry(metric);
+ if (spec.width < 768) await button.tap();
+ else {
+ await button.focus();
+ await page.keyboard.press('Enter');
+ }
+ await dialog().waitFor();
+ assert.equal(await button.getAttribute('aria-expanded'), 'true');
+ assert.equal(await page.evaluate(() => window.__readingStatusAccess.actions()), 0);
+ assert.equal(result.requests.length, before, 'Disclosure added an API request');
+ assert.equal(await dialog().locator('button').count(), 1);
+ assert.equal(
+ await page.evaluate(() => document.activeElement?.getAttribute('aria-label')),
+ 'Close reading details',
+ );
+ assert.ok(
+ await dialog().evaluate((element) => element.scrollWidth <= element.clientWidth + 1),
+ );
+ assert.ok(
+ await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth + 1),
+ );
+ check(`${metric} native disclosure and dense target`, shape);
+ };
+ const close = async (metric, backdrop = false) => {
+ if (backdrop)
+ await page.locator('[data-dialog-backdrop]').click({ position: { x: 5, y: 5 } });
+ else await page.keyboard.press('Escape');
+ await dialog().waitFor({ state: 'detached' });
+ assert.equal(await trigger(metric).getAttribute('aria-expanded'), 'false');
+ assert.equal(
+ await trigger(metric).evaluate((element) => element === document.activeElement),
+ true,
+ );
+ assert.equal(await page.evaluate(() => window.__readingStatusAccess.actions()), 0);
+ };
+ await open('Disk');
+ assert.match(
+ await dialog().innerText(),
+ /Completion is uncertain\. Do not restart the guest agent during a backup/,
+ );
+ await page.keyboard.press('Tab');
+ assert.equal(
+ await page.evaluate(() => document.activeElement?.getAttribute('aria-label')),
+ 'Close reading details',
+ );
+ await capture('disk-timeout');
+ await close('Disk');
+ await open('Memory');
+ assert.match(
+ await dialog().innerText(),
+ /Last known\. Source: QEMU guest agent\. Observed: 2026-10-12 20:00:00 UTC\. Not a current measurement\./,
+ );
+ await capture('memory-prior');
+ await close('Memory', true);
+ const deferrals = [
+ 'vm-locked',
+ 'lock-unverified',
+ 'agent-busy',
+ 'agent-cooldown',
+ 'agent-response-incomplete',
+ 'agent-capacity',
+ 'invalid-guest-key',
+ 'agent-timeout',
+ ];
+ for (const mode of ['bars', 'sparklines']) {
+ await page.evaluate((value) => window.__readingStatusAccess.mode(value), mode);
+ await open('Disk');
+ for (const reason of deferrals) {
+ await update({ reason: `prev-${reason}` });
+ assert.match(await dialog().innerText(), /Using last known disk stats\./);
+ assert.equal(
+ (await row.locator('[data-workload-col="disk"] [aria-hidden="true"]').count()) > 0,
+ true,
+ );
+ check(`${mode}: same-guest open retained ${reason}`);
+ await update({ reason });
+ assert.doesNotMatch(await dialog().innerText(), /Using last known disk stats\./);
+ assert.doesNotMatch(await row.locator('[data-workload-col="disk"]').innerText(), /50%/);
+ check(`${mode}: same-guest open unavailable ${reason}`);
+ }
+ await update({ reason: 'permission-denied' });
+ assert.match(await dialog().innerText(), /Do not widen intentionally scoped access/);
+ if (mode === 'sparklines') await capture('disk-permission');
+ await close('Disk');
+ }
+ await update({ state: 'current', source: 'status-mem' });
+ await open('Memory');
+ assert.match(await dialog().innerText(), /Source: Proxmox/);
+ assert.match(
+ await dialog().innerText(),
+ /high percentage alone does not mean it is short of memory/,
+ );
+ assert.match(
+ await dialog().innerText(),
+ /Defer agent setup, restarts and live guest-agent probes during backups or a guest incident/,
+ );
+ await capture('memory-cache');
+ for (const [state, observedAt, expected] of [
+ ['last-known', time, 'Last known.'],
+ ['future-state', time, 'Freshness unknown.'],
+ ['current', 'not-a-date', 'Observation time unknown.'],
+ ['current', '2026-10-13T20:00:00Z', 'Observation time unknown.'],
+ ['unavailable', time, 'Unavailable.'],
+ ]) {
+ await update({ state, observedAt });
+ assert.ok((await dialog().innerText()).includes(expected));
+ assert.doesNotMatch(await dialog().innerText(), /Invalid Date/);
+ check(`Memory open ${state}/${observedAt}`);
+ }
+ await update({ state: 'current', source: 'guest-agent-meminfo', observedAt: time });
+ await dialog().waitFor({ state: 'detached' });
+ assert.equal(await trigger('Memory').count(), 0);
+ assert.equal(
+ await row
+ .locator('[data-row-action]')
+ .evaluate((element) => element === document.activeElement),
+ true,
+ );
+ check('Fresh current memory withdraws disclosure and returns focus to the same row');
+ await update({ reason: 'prev-agent-timeout' });
+ await open('Disk');
+ await update({ reason: undefined });
+ await dialog().waitFor({ state: 'detached' });
+ assert.equal(await trigger('Disk').count(), 0);
+ check('Fresh disk withdraws disclosure without remount or a row action');
+ await update({ reason: 'permission-denied' });
+ await open('Disk');
+ await update({ instance: 'another-site' });
+ await dialog().waitFor({ state: 'detached' });
+ check('Same-name different canonical identity closes old disclosure');
+ await open('Disk');
+ await close('Disk');
+ // The original row disclosure still works, separately from evidence controls.
+ const disclosure = row.locator('[data-row-action]');
+ if (spec.width < 768) await row.locator('[data-workload-col="name"]').tap();
+ else {
+ await disclosure.focus();
+ await page.keyboard.press('Enter');
+ }
+ await page.getByRole('region', { name: 'Guest details' }).waitFor();
+ assert.equal(await page.evaluate(() => window.__readingStatusAccess.actions()), 1);
+ check('Original row disclosure still opens the production guest drawer');
+ } finally {
+ await context.close();
+ result.cleanup[`${spec.name}-context`] = 'closed';
+ await browser.close();
+ result.cleanup[`${spec.name}-browser`] = 'closed';
+ }
+ }
+ assert.deepEqual(result.errors, []);
+ assert.deepEqual(result.consoleErrors, []);
+ result.result = 'passed';
+})()
+ .catch((error) => {
+ result.result = 'failed';
+ result.failure = { message: error.message, stack: error.stack };
+ process.exitCode = 1;
+ })
+ .finally(async () => {
+ if (server) {
+ await new Promise((resolve, reject) =>
+ server.close((error) => (error ? reject(error) : resolve())),
+ );
+ result.cleanup.server = 'closed';
+ }
+ fs.writeFileSync(path.join(output, 'result.json'), JSON.stringify(result, null, 2) + '\n');
+ console.log(
+ JSON.stringify({
+ result: result.result,
+ checks: result.checks.length,
+ captures: result.captures.length,
+ loaded: Object.keys(result.loaded).length,
+ cleanup: result.cleanup,
+ failure: result.failure?.message,
+ }),
+ );
+ });
diff --git a/frontend-modern/browser-tests/reading-status-access.html b/frontend-modern/browser-tests/reading-status-access.html
new file mode 100644
index 0000000000..1dd6beb8dc
--- /dev/null
+++ b/frontend-modern/browser-tests/reading-status-access.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Workload reading access fixture</title>
+ </head>
+ <body>
+ <div id="root"></div>
+ <script type="module" src="/browser-tests/reading-status-access.tsx"></script>
+ </body>
+</html>
diff --git a/frontend-modern/browser-tests/reading-status-access.tsx b/frontend-modern/browser-tests/reading-status-access.tsx
new file mode 100644
index 0000000000..8bcc1864b8
--- /dev/null
+++ b/frontend-modern/browser-tests/reading-status-access.tsx
@@ -0,0 +1,127 @@
+// Actual canonical resource API -> useWorkloads -> row/disclosure/CSS.
+// Only synthetic observations are supplied; this sends no guest commands.
+import { createSignal, For, Show } from 'solid-js';
+import { render } from 'solid-js/web';
+import { Router, Route } from '@solidjs/router';
+import { useWorkloads } from '../src/hooks/useWorkloads';
+import { GuestRow } from '../src/components/Workloads/GuestRow';
+import { GuestDrawer } from '../src/components/Workloads/GuestDrawer';
+import {
+ GUEST_COLUMNS,
+ getGuestColumnWidthStyle,
+ getWorkloadTableLayoutModeForContainer,
+ getWorkloadVisibleColumnsForLayout,
+} from '../src/components/Workloads/guestRowModel';
+import { DarkModeContext } from '../src/contexts/appRuntime';
+import type { WorkloadMetricHistoryReader } from '../src/components/Workloads/workloadMetricHistoryModel';
+import '../src/index.css';
+
+function Fixture() {
+ const state = useWorkloads(() => true);
+ const [mode, setMode] = createSignal<'bars' | 'sparklines'>('bars');
+ const [expanded, setExpanded] = createSignal(false);
+ const [actions, setActions] = createSignal(0);
+ const primary = () => state.workloads().find((guest) => guest.vmid === 101)!;
+ const control = () => state.workloads().find((guest) => guest.vmid === 102)!;
+ const layout = getWorkloadTableLayoutModeForContainer(window.innerWidth - 24);
+ const requested = new Set(['name', 'cpu', 'memory', 'disk', 'uptime']);
+ const columns = getWorkloadVisibleColumnsForLayout(
+ GUEST_COLUMNS.filter((column) => requested.has(column.id)),
+ layout,
+ );
+ const columnIds = columns.map((column) => column.id);
+ const history: WorkloadMetricHistoryReader = {
+ hasData: () => true,
+ getGuestMetricSeries: () => [
+ {
+ label: 'Recorded',
+ color: '#64748b',
+ points: [
+ { timestamp: Date.parse('2026-10-12T20:00:00Z'), value: 25 },
+ { timestamp: Date.parse('2026-10-12T20:01:00Z'), value: 55 },
+ ],
+ },
+ ],
+ getNodeMetricSeries: () => [],
+ };
+ (window as any).__readingStatusAccess = {
+ refetch: state.refetch,
+ mode: setMode,
+ actions,
+ evidence: () => ({ id: primary().id, memory: primary().memory, disk: primary().disk }),
+ };
+ return (
+ <main class="min-h-screen space-y-3 bg-surface p-3 text-base-content pulse-wide-data-surface">
+ <h1 class="text-base font-semibold">Workload reading access</h1>
+ <p class="text-xs text-muted">Synthetic resource observations; no guest commands.</p>
+ <Show when={primary() && control()}>
+ <div class="table-scroll-shell overflow-x-auto">
+ <table class="w-full platform-table workload-table table-fixed">
+ <colgroup>
+ <For each={columnIds}>
+ {(id) => (
+ <col
+ style={getGuestColumnWidthStyle(
+ id,
+ window.innerWidth <= 768,
+ layout,
+ columnIds,
+ )}
+ />
+ )}
+ </For>
+ </colgroup>
+ <thead>
+ <tr>
+ <For each={columns}>{(column) => <th scope="col">{column.label}</th>}</For>
+ </tr>
+ </thead>
+ <tbody>
+ <GuestRow
+ guest={primary()}
+ visibleColumnIds={columnIds}
+ workloadTableLayoutMode={layout}
+ metricDisplayMode={mode()}
+ metricHistory={history}
+ isExpanded={expanded()}
+ onClick={() => {
+ setActions((value) => value + 1);
+ setExpanded((value) => !value);
+ }}
+ />
+ <GuestRow
+ guest={control()}
+ visibleColumnIds={columnIds}
+ workloadTableLayoutMode={layout}
+ metricDisplayMode={mode()}
+ metricHistory={history}
+ />
+ </tbody>
+ </table>
+ </div>
+ <Show when={expanded()}>
+ <section aria-label="Guest details">
+ <GuestDrawer guest={primary()} onClose={() => setExpanded(false)} />
+ </section>
+ </Show>
+ </Show>
+ </main>
+ );
+}
+render(
+ () => (
+ <Router>
+ <Route
+ path="*"
+ component={() => (
+ <DarkModeContext.Provider
+ value={() => document.documentElement.classList.contains('dark')}
+ >
+ <Fixture />
+ </DarkModeContext.Provider>
+ )}
+ />
+ </Router>
+ ),
+ document.getElementById('root')!,
+);
diff --git a/frontend-modern/browser-verification/f98645649acf13e9.json b/frontend-modern/browser-verification/f98645649acf13e9.json
new file mode 100644
index 0000000000..4b640c9581
--- /dev/null
+++ b/frontend-modern/browser-verification/f98645649acf13e9.json
@@ -0,0 +1,75 @@
+{
+ "version": 1,
+ "result": "passed",
+ "base_sha": "a2e5d0fb93d69abe9eabc682126a64d12443594c",
+ "changed_paths": [
+ "frontend-modern/src/components/Workloads/GuestRow.tsx",
+ "frontend-modern/src/components/Workloads/WorkloadReadingStatus.tsx"
+ ],
+ "content_sha256": {
+ "frontend-modern/src/components/Workloads/GuestRow.tsx": "7e5649652746c31bd1a25f3ab9204c5fd9460037c2033a93a7329a2bb18b8204",
+ "frontend-modern/src/components/Workloads/WorkloadReadingStatus.tsx": "d79a5a8dbdd9141aed7db62321e50f3b72a3f5a073d8009feaf7d3088449cb26"
+ },
+ "routes": [
+ "/final/browser-tests/reading-status-access.html (isolated existing production Workloads consumer; no product route added)"
+ ],
+ "states": [
+ "Eight fixed retained/unavailable guest-read deferrals",
+ "memory last-known, unknown, invalid/future original time, unavailable, cache-inclusive current and cache-aware current",
+ "same-guest update and different same-name canonical identity",
+ "bars and sparklines; original row drawer still usable"
+ ],
+ "interactions": [
+ "Canonical Resources API -> useWorkloads -> production GuestRow",
+ "Desktop native keyboard/touch-phone native disclosure, Tab trapping, Escape/backdrop closure and focus return",
+ "Zero added API requests and no row action on disclosure",
+ "Fresh evidence withdraws cue; same-resource fallback focus; changed canonical identity closes old details",
+ "24px phone targets wholly inside cells; unchanged 32px desktop / 37px phone dense rows",
+ "Static build source/artifact bindings and native view_image inspection of eight settled captures"
+ ],
+ "viewports": [
+ {
+ "width": 1365,
+ "height": 900
+ },
+ {
+ "width": 390,
+ "height": 844
+ }
+ ],
+ "verified_at": "2026-10-12T20:35:39.226988Z",
+ "proof_scope": "Real canonical Resources API and useWorkloads producer, actual production GuestRow, reading disclosure, shared Dialog and CSS. Synthetic read state; no guest command, native recovery, publication or availability claim.",
+ "browser_proof": {
+ "checks": 98,
+ "compiled_production_hashes": 239,
+ "captures": 8,
+ "client_exit": 0,
+ "playwright": "1.56.1",
+ "browsers": [
+ {
+ "name": "desktop",
+ "version": "141.0.7390.37",
+ "width": 1365,
+ "height": 900,
+ "locale": "en-GB",
+ "timezoneId": "Europe/London"
+ },
+ {
+ "name": "phone",
+ "version": "26.0",
+ "width": 390,
+ "height": 844,
+ "locale": "en-GB",
+ "timezoneId": "Asia/Tokyo"
+ }
+ ],
+ "cleanup": {
+ "desktop-context": "closed",
+ "desktop-browser": "closed",
+ "phone-context": "closed",
+ "phone-browser": "closed",
+ "server": "closed"
+ },
+ "dossier": "RECEIPTS.md / browser/result.json and native-image-review.json"
+ }
+}
diff --git a/frontend-modern/src/components/Workloads/GuestRow.tsx b/frontend-modern/src/components/Workloads/GuestRow.tsx
index 932401e99f..9a2053c3cb 100644
--- a/frontend-modern/src/components/Workloads/GuestRow.tsx
+++ b/frontend-modern/src/components/Workloads/GuestRow.tsx
@@ -5,6 +5,7 @@ import type { WorkloadGuest } from '@/types/workloads';
import { formatUptime, formatSpeed, getShortImageName } from '@/utils/format';
import { StackedDiskBar } from './StackedDiskBar';
import { StackedMemoryBar } from './StackedMemoryBar';
+import { WorkloadReadingStatus } from './WorkloadReadingStatus';
import {
AvailabilityProbeCell,
BackupIndicator,
@@ -657,14 +658,13 @@ export function GuestRow(props: GuestRowProps) {
</Show>
<Show when={memoryReadStatus()}>
{(status) => (
- <p
- data-workload-memory-read-status
- class="mt-0.5 text-center text-[10px] leading-none text-muted"
- title={status().message}
- >
- <span aria-hidden="true">{status().label}</span>
- <span class="sr-only">{status().message}</span>
- </p>
+ <WorkloadReadingStatus
+ metric="Memory"
+ guestId={guestId()}
+ guestName={props.guest.name}
+ label={status().label}
+ message={status().message}
+ />
)}
</Show>
</td>
@@ -712,16 +712,14 @@ export function GuestRow(props: GuestRowProps) {
</Show>
<Show when={diskReadStatus()}>
{(status) => (
- <p
- data-workload-disk-read-status
- class={`mt-0.5 text-center text-[10px] leading-none ${
- status().needsAction ? 'text-amber-700 dark:text-amber-300' : 'text-muted'
- }`}
- title={status().message}
- >
- <span aria-hidden="true">{status().label}</span>
- <span class="sr-only">{status().message}</span>
- </p>
+ <WorkloadReadingStatus
+ metric="Disk"
+ guestId={guestId()}
+ guestName={props.guest.name}
+ label={status().label}
+ message={status().message}
+ needsAction={status().needsAction}
+ />
)}
</Show>
</td>
diff --git a/frontend-modern/src/components/Workloads/WorkloadReadingStatus.tsx b/frontend-modern/src/components/Workloads/WorkloadReadingStatus.tsx
new file mode 100644
index 0000000000..15775ee12d
--- /dev/null
+++ b/frontend-modern/src/components/Workloads/WorkloadReadingStatus.tsx
@@ -0,0 +1,89 @@
+import { createEffect, createSignal, on, onCleanup, Show } from 'solid-js';
+import { Dialog } from '@/components/shared/Dialog';
+
+interface WorkloadReadingStatusProps {
+ metric: 'Memory' | 'Disk';
+ guestId: string;
+ guestName: string;
+ label: string;
+ message: string;
+ needsAction?: boolean;
+}
+
+// This is disclosure of already supplied evidence, not a refresh, diagnostic
+// or recovery action. Keep the existing compact cue and its screen-reader
+// explanation; the same explanation must also be readable without hovering.
+export function WorkloadReadingStatus(props: WorkloadReadingStatusProps) {
+ const [open, setOpen] = createSignal(false);
+ let trigger: HTMLButtonElement | undefined;
+ createEffect(
+ on(
+ () => props.guestId,
+ () => setOpen(false),
+ { defer: true },
+ ),
+ );
+ onCleanup(() => {
+ if (!open()) return;
+ const rowAction = trigger?.closest('tr')?.querySelector<HTMLButtonElement>('[data-row-action]');
+ // A new current observation withdraws this cue. After its button is
+ // removed, return keyboard users to the same row's existing disclosure.
+ queueMicrotask(() => {
+ if (!trigger?.isConnected && rowAction?.isConnected) rowAction.focus({ preventScroll: true });
+ });
+ });
+
+ return (
+ <>
+ <p
+ data-workload-memory-read-status={props.metric === 'Memory' ? '' : undefined}
+ data-workload-disk-read-status={props.metric === 'Disk' ? '' : undefined}
+ class={`mt-0.5 text-center text-[10px] leading-none ${
+ props.needsAction ? 'text-amber-700 dark:text-amber-300' : 'text-muted'
+ }`}
+ title={props.message}
+ >
+ <button
+ ref={trigger}
+ type="button"
+ class="inline-flex min-h-6 min-w-6 -my-1.5 items-center justify-center rounded-sm px-1 underline decoration-dotted underline-offset-2 sm:my-0 sm:min-h-0 focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-1 focus-visible:ring-offset-surface"
+ aria-label={`${props.metric} reading for ${props.guestName}: ${props.label}`}
+ aria-haspopup="dialog"
+ aria-expanded={open()}
+ onClick={(event) => {
+ event.stopPropagation();
+ setOpen(true);
+ }}
+ >
+ <span aria-hidden="true">{props.label}</span>
+ </button>
+ <span class="sr-only">{props.message}</span>
+ </p>
+ <Show when={open()}>
+ <Dialog
+ isOpen
+ ariaLabel={`${props.metric} reading for ${props.guestName}`}
+ onClose={() => setOpen(false)}
+ returnFocus={() => trigger}
+ panelClass="max-w-sm"
+ >
+ <div class="flex items-center justify-between gap-3 border-b border-border px-4 py-2">
+ <h2 class="text-sm font-semibold text-base-content">{props.metric} reading</h2>
+ <button
+ type="button"
+ aria-label="Close reading details"
+ class="min-h-11 rounded-sm px-3 text-xs text-muted hover:bg-surface-hover focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-blue-500"
+ onClick={() => setOpen(false)}
+ >
+ Close
+ </button>
+ </div>
+ <div class="space-y-2 overflow-y-auto p-4 text-sm text-base-content">
+ <p class="font-semibold wrap-break-word">{props.guestName}</p>
+ <p class="whitespace-normal wrap-break-word leading-relaxed">{props.message}</p>
+ </div>
+ </Dialog>
+ </Show>
+ </>
+ );
+}
diff --git a/frontend-modern/src/components/Workloads/__tests__/GuestRow.test.tsx b/frontend-modern/src/components/Workloads/__tests__/GuestRow.test.tsx
index abeca143d6..2f9afa1007 100644
--- a/frontend-modern/src/components/Workloads/__tests__/GuestRow.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/GuestRow.test.tsx
@@ -3115,3 +3115,131 @@ describe('GuestRow backup evidence disclosure', () => {
},
);
});
+
+describe('GuestRow accessible reading explanations', () => {
+ it.each(['bars', 'sparklines'] as const)(
+ 'regression: %s exposes safe disk evidence without opening the enclosing row',
+ async (metricDisplayMode) => {
+ const onClick = vi.fn();
+ renderGuestRow({
+ guest: makeGuest({ diskStatusReason: 'prev-agent-timeout' }),
+ visibleColumnIds: ['name', 'disk'],
+ metricDisplayMode,
+ onClick,
+ });
+ const trigger = screen.getByRole('button', { name: 'Disk reading for test-vm: Last known' });
+ expect(trigger).toHaveAttribute('type', 'button');
+ expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ expect(screen.queryByRole('dialog')).toBeNull();
+ trigger.focus();
+ fireEvent.click(trigger);
+ const dialog = screen.getByRole('dialog', { name: 'Disk reading for test-vm' });
+ expect(dialog).toHaveTextContent('Using last known disk stats.');
+ expect(dialog).toHaveTextContent(
+ 'Completion is uncertain. Do not restart the guest agent during a backup.',
+ );
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ expect(onClick).not.toHaveBeenCalled();
+ await Promise.resolve();
+ const close = screen.getByRole('button', { name: 'Close reading details' });
+ expect(close).toHaveFocus();
+ fireEvent.keyDown(document, { key: 'Tab' });
+ expect(close).toHaveFocus();
+ fireEvent.keyDown(document, { key: 'Escape' });
+ expect(screen.queryByRole('dialog')).toBeNull();
+ expect(trigger).toHaveFocus();
+ expect(onClick).not.toHaveBeenCalled();
+ },
+ );
+
+ it('regression: exposes source, original time and cache/setup caveat without a hover', () => {
+ const onClick = vi.fn();
+ renderGuestRow({
+ guest: makeGuest({
+ memory: makeMemory({
+ observation: {
+ state: 'current',
+ source: 'status-mem',
+ observedAt: '2026-01-01T00:00:00Z',
+ },
+ }),
+ }),
+ visibleColumnIds: ['name', 'memory'],
+ workloadTableLayoutMode: 'phone',
+ onClick,
+ });
+ fireEvent.click(screen.getByRole('button', { name: 'Memory reading for test-vm: Cache?' }));
+ const dialog = screen.getByRole('dialog', { name: 'Memory reading for test-vm' });
+ expect(dialog).toHaveTextContent('Source: Proxmox. Observed: 2026-01-01 00:00:00 UTC.');
+ expect(dialog).toHaveTextContent('a high percentage alone does not mean it is short of memory');
+ expect(dialog).toHaveTextContent('Defer agent setup, restarts and live guest-agent probes');
+ expect(onClick).not.toHaveBeenCalled();
+ expect(dialog.querySelectorAll('button')).toHaveLength(1);
+ });
+
+ it('updates already open evidence for the same guest, closes on fresh source, and does not add a read', () => {
+ const [guest, setGuest] = createSignal(makeGuest({ diskStatusReason: 'prev-agent-timeout' }));
+ const { container } = render(() => (
+ <table>
+ <tbody>
+ <GuestRow guest={guest()} visibleColumnIds={['name', 'disk']} />
+ </tbody>
+ </table>
+ ));
+ const row = container.querySelector('tr');
+ fireEvent.click(screen.getByRole('button', { name: 'Disk reading for test-vm: Last known' }));
+ const dialog = screen.getByRole('dialog');
+ setGuest(makeGuest({ diskStatusReason: 'permission-denied' }));
+ expect(screen.getByRole('dialog')).toBe(dialog);
+ expect(dialog).toHaveTextContent('Permission denied.');
+ expect(dialog).toHaveTextContent('Do not widen intentionally scoped access');
+ expect(dialog).not.toHaveTextContent('Using last known disk stats.');
+ expect(dialog).not.toHaveTextContent('Guest request timed out.');
+ setGuest(makeGuest({ diskStatusReason: undefined }));
+ expect(screen.queryByRole('dialog')).toBeNull();
+ expect(screen.queryByRole('button', { name: /^Disk reading for/ })).toBeNull();
+ expect(container.querySelector('tr')).toBe(row);
+ expect(document.body.style.overflow).not.toBe('hidden');
+ });
+
+ it('closes rather than transferring an open explanation to another resource with the same name', () => {
+ const [guest, setGuest] = createSignal(makeGuest({ diskStatusReason: 'prev-agent-timeout' }));
+ render(() => (
+ <table>
+ <tbody>
+ <GuestRow guest={guest()} visibleColumnIds={['name', 'disk']} />
+ </tbody>
+ </table>
+ ));
+ fireEvent.click(screen.getByRole('button', { name: /^Disk reading for/ }));
+ setGuest(
+ makeGuest({
+ id: 'another-instance-node1-100',
+ instance: 'another-instance',
+ diskStatusReason: 'permission-denied',
+ }),
+ );
+ expect(screen.queryByRole('dialog')).toBeNull();
+ fireEvent.click(screen.getByRole('button', { name: /^Disk reading for/ }));
+ expect(screen.getByRole('dialog')).toHaveTextContent('Permission denied.');
+ expect(screen.getByRole('dialog')).not.toHaveTextContent('Guest request timed out.');
+ });
+
+ it('leaves current cache-aware readings without extra buttons, dialogs or mutations', () => {
+ renderGuestRow({
+ guest: makeGuest({
+ memory: makeMemory({
+ observation: {
+ state: 'current',
+ source: 'guest-agent-meminfo',
+ observedAt: '2026-01-01T00:00:00Z',
+ },
+ }),
+ }),
+ visibleColumnIds: ['name', 'memory', 'disk'],
+ });
+ expect(screen.queryByRole('button', { name: /^(Memory|Disk) reading for/ })).toBeNull();
+ expect(screen.queryByRole('dialog')).toBeNull();
+ });
+});