rcf-lite 0.27.0 → 0.28.1

package/blueprints/application-dashboard/contributions/probes/export-handle-formats.mjs

@@ -0,0 +1,75 @@
+// export-handle-formats probe for application-dashboard v1.0.9.
+//
+// AC-19106-1 (server-observable half): the export handle region
+// carries a labelled button with aria-haspopup="listbox" AND a
+// role="listbox" enumerating the applied formats. The fixture
+// accepts a startServer({ exportFormats: [...] }) override so the
+// probe DRIVES two distinct format sets and asserts the rendered
+// listbox follows the input on each run. Browser-observable
+// activation and focus-return are covered by the conformanceOnly
+// limitation on the single row.
+//
+// anchorAcId: application-dashboard-AC-19106-1.
+
+import { startFixture, evidenceFromResponse, conformanceOnlyResult } from './probe-utils.mjs';
+
+export const anchorReqId = 'application-dashboard-REQ-005';
+export const accountBound = false;
+
+async function driveOne(startServer, formatsInput) {
+ const started = await startServer({ port: 0, exportFormats: formatsInput });
+ const baseUrl = `http://127.0.0.1:${started.port}`;
+ const close = () => new Promise((res, rej) => started.server.close((e) => (e ? rej(e) : res())));
+ try {
+ const res = await fetch(`${baseUrl}/`);
+ const body = await res.text();
+ const exportRegion = body.match(/<section[^>]+data-region="export-handle"[^>]*>([\s\S]*?)<\/section>/);
+ const inner = exportRegion ? exportRegion[1] : '';
+ const hasBtn = /<button[^>]+aria-haspopup="listbox"[^>]*>/.test(inner);
+ const listbox = /<ul[^>]+role="listbox"[^>]*>/.test(inner);
+ const formats = Array.from(inner.matchAll(/data-export-format="([^"]+)"/g)).map((m) => m[1]);
+ const followsInput = formats.length === formatsInput.length
+ && formatsInput.every((f) => formats.includes(f))
+ && formats.every((f) => formatsInput.includes(f));
+ return { res, body, hasBtn, listbox, formats, followsInput, close };
+ } catch (e) {
+ try { await close(); }
+ catch (closeErr) { throw new AggregateError([e, closeErr], 'probe body threw and teardown also threw'); }
+ throw e;
+ }
+}
+
+export default async function runProbe() {
+ const { startServer } = await import('../../../../packages/rcf-lite/test/fixtures/probe-pack-application-dashboard/server.js');
+
+ const results = [];
+ const shipped = ['csv', 'pdf', 'png-chart'];
+ const elicited = ['csv', 'xlsx', 'json', 'png-chart'];
+ const runA = await driveOne(startServer, shipped);
+ try {
+ const runB = await driveOne(startServer, elicited);
+ try {
+ const derived = runA.followsInput && runB.followsInput
+ && JSON.stringify(runA.formats) !== JSON.stringify(runB.formats);
+ const pass = runA.res.status === 200 && runB.res.status === 200 && runA.hasBtn && runA.listbox && runB.hasBtn && runB.listbox && derived;
+ results.push(conformanceOnlyResult({
+ anchorAcId: 'application-dashboard-AC-19106-1',
+ anchorReqId: 'application-dashboard-REQ-005',
+ verdict: pass ? 'pass' : 'fail',
+ detail: `Given a rendered dashboard surface, the export handle - drove two distinct format sets: runA=[${runA.formats.join(',')}] runB=[${runB.formats.join(',')}]; listbox follows input (${derived})`,
+ evidence: evidenceFromResponse({
+ route: '/',
+ response: runB.res,
+ bodyText: runB.body,
+ extraFields: {
+ input: { runA: shipped, runB: elicited },
+ derived: { runAFormats: runA.formats, runBFormats: runB.formats, followsInput: derived, hasButtonA: runA.hasBtn, hasButtonB: runB.hasBtn },
+ altBodyExcerpt: runA.body.slice(0, 240),
+ },
+ }),
+ limitation: 'application-dashboard-AC-19106-1: control activation and Escape/focus-return are browser-only',
+ }));
+ } finally { await runB.close(); }
+ } finally { await runA.close(); }
+ return { results };
+}

package/blueprints/application-dashboard/contributions/probes/four-tile-states.mjs

@@ -0,0 +1,75 @@
+// four-tile-states probe for application-dashboard v1.0.9.
+//
+// Verifies AC-19103-1: every tile state (loading, empty, error,
+// populated) is rendered on each of two named tiles. The probe
+// drives ?tile=primary&state=<state> AND ?tile=active-users&state=<state>
+// so each state is observed on two tiles (the
+// varied input is the state and tile id, the derived output is the
+// state attribute and cue on the correct tile's region).
+//
+// anchorAcId: application-dashboard-AC-19103-1.
+
+import { startFixture, evidenceFromResponse } from './probe-utils.mjs';
+
+export const anchorReqId = 'application-dashboard-REQ-003';
+export const accountBound = false;
+
+const STATES = ['loading', 'empty', 'error', 'populated'];
+const TILES = ['primary', 'active-users'];
+
+function assertTileState({ body, tileId, state }) {
+ const articleRe = new RegExp(`<article[^>]+data-tile-id="${tileId}"[^>]*>([\\s\\S]*?)<\/article>`);
+ const article = body.match(articleRe);
+ if (!article) return { present: false, reason: `no article for ${tileId}` };
+ const inner = article[1];
+ const wrapperRe = /<div[^>]+role="region"[^>]+aria-live="polite"[^>]+data-tile-state="([^"]+)"[^>]+aria-label="([^"]+)"[^>]*>/;
+ const wrap = inner.match(wrapperRe);
+ if (!wrap) return { present: false, reason: 'inner region missing role/aria-live/data-tile-state/aria-label' };
+ const cueRe = new RegExp(`data-state-cue="${state}"`);
+ const hasCue = cueRe.test(inner);
+ return {
+ present: true,
+ stateAttr: wrap[1],
+ accessibleName: wrap[2],
+ hasCue,
+ matches: wrap[1] === state,
+ };
+}
+
+export default async function runProbe() {
+ const { startServer } = await import('../../../../packages/rcf-lite/test/fixtures/probe-pack-application-dashboard/server.js');
+ const fixture = await startFixture({ startServer, port: 0 });
+ try {
+ const results = [];
+ for (const tileId of TILES) {
+ for (const state of STATES) {
+ const res = await fetch(`${fixture.baseUrl}/?tile=${tileId}&state=${state}`);
+ const body = await res.text();
+ const observation = assertTileState({ body, tileId, state });
+ const pass = res.status === 200
+ && observation.present
+ && observation.matches
+ && observation.hasCue
+ && typeof observation.accessibleName === 'string' && observation.accessibleName.includes(state);
+ results.push({
+ anchorAcId: 'application-dashboard-AC-19103-1',
+ anchorReqId: 'application-dashboard-REQ-003',
+ verdict: pass ? 'pass' : 'fail',
+ detail: `Given a rendered tile in each of the - tile=${tileId} at state="${state}" carries role="region" aria-live="polite" data-tile-state="${observation.stateAttr}" data-state-cue="${state}" accessibleName="${observation.accessibleName}"`,
+ evidence: evidenceFromResponse({
+ route: `/?tile=${tileId}&state=${state}`,
+ response: res,
+ bodyText: body,
+ extraFields: {
+ input: { tileId, state },
+ derived: observation,
+ },
+ }),
+ });
+ }
+ }
+ return { results };
+ } finally {
+ await fixture.close();
+ }
+}

package/blueprints/application-dashboard/contributions/probes/primary-kpi-top-left.mjs

@@ -0,0 +1,58 @@
+// primary-kpi-top-left probe for application-dashboard v1.0.9.
+//
+// AC-19102-1 requires computed layout at 1440/1024/360 viewports;
+// that observation is browser-only and recorded as notObservableHere
+// per the browser-only rule. The server-observable half - primary tile
+// first in DOM order, inline grid-column-start:1 AND grid-row-start:1,
+// data-kpi-kind in the ADR-2001 enum - remains a real evidence row.
+//
+// anchorAcId: application-dashboard-AC-19102-1.
+
+import { startFixture, evidenceFromResponse, conformanceOnlyResult } from './probe-utils.mjs';
+
+export const anchorReqId = 'application-dashboard-REQ-002';
+export const accountBound = false;
+
+const KPI_ENUM = ['revenue', 'active-users', 'error-rate', 'throughput', 'custom'];
+
+export default async function runProbe() {
+ const { startServer } = await import('../../../../packages/rcf-lite/test/fixtures/probe-pack-application-dashboard/server.js');
+ const fixture = await startFixture({ startServer, port: 0 });
+ try {
+ const results = [];
+
+ const okRes = await fetch(`${fixture.baseUrl}/`);
+ const okBody = await okRes.text();
+ const tileRowMatch = okBody.match(/<section[^>]+data-region="tile-row"[^>]*>([\s\S]*?)<\/section>/);
+ const firstArticle = tileRowMatch ? tileRowMatch[1].match(/<article[^>]*>/) : null;
+ const firstAttrs = firstArticle ? firstArticle[0] : '';
+ const isPrimaryFirst = /data-tile-role="primary-kpi"/.test(firstAttrs);
+ const hasColumnStart = /grid-column-start:1/.test(firstAttrs);
+ const hasRowStart = /grid-row-start:1/.test(firstAttrs);
+ const kindMatch = firstAttrs.match(/data-kpi-kind="([^"]+)"/);
+ const kindValue = kindMatch ? kindMatch[1] : null;
+ const kindOk = kindValue !== null && KPI_ENUM.includes(kindValue);
+ const okPass = okRes.status === 200 && isPrimaryFirst && hasColumnStart && hasRowStart && kindOk;
+
+ results.push(conformanceOnlyResult({
+ anchorAcId: 'application-dashboard-AC-19102-1',
+ anchorReqId: 'application-dashboard-REQ-002',
+ verdict: okPass ? 'pass' : 'fail',
+ detail: `Given a rendered dashboard surface at each of - primary tile first in DOM order with inline grid-column-start:1, grid-row-start:1, data-kpi-kind="${kindValue}" (server-observable half of AC-19102-1)`,
+ evidence: evidenceFromResponse({
+ route: '/',
+ response: okRes,
+ bodyText: okBody,
+ extraFields: {
+ input: { adr2001Enum: KPI_ENUM },
+ derived: { firstArticleAttrs: firstAttrs.slice(0, 240), primaryFirst: isPrimaryFirst, colStart: hasColumnStart, rowStart: hasRowStart, kindValue },
+ },
+ }),
+ limitation: 'application-dashboard-AC-19102-1: computed CSS layout at 1440/1024/360 viewports is browser-only',
+ }));
+
+ return { results };
+ } finally {
+ await fixture.close();
+ }
+}

package/blueprints/application-dashboard/contributions/probes/probe-utils.mjs

@@ -0,0 +1,177 @@
+// Shared helpers for application-dashboard probes.
+//
+// The engine under probe is the sample-app fixture at
+// packages/rcf-lite/test/fixtures/probe-pack-application-dashboard/server.js. The
+// fixture stamps an x-fixture-request-id header on every response as
+// part of its own request pipeline (no probe-side monkey-patch), so
+// the identifier the probe records is the identifier the engine
+// itself issued. Probes call the fixture over real HTTP via node's
+// fetch, vary inputs, assert derived outputs, and record the
+// request-id, status, body excerpt, the varied input and the derived
+// output as evidence on every result row.
+// No account-bound branch: the engine is a local fixture, not a
+// third-party account, so no CI_HAS_* gate is invented. Every env
+// var this pack reads is declared on the fixture README.
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const PROJECT_ROOT = resolve(HERE, '..', '..', '..', '..');
+export const FIXTURE_DIR = resolve(PROJECT_ROOT, 'packages/rcf-lite/test/fixtures/probe-pack-application-dashboard');
+export const REPORT_DIR = resolve(PROJECT_ROOT, '.rcf/reports/blueprints/application-dashboard');
+
+export const DEFAULT_PORT = 0;
+
+export function aggregate(results) {
+  if (!Array.isArray(results) || results.length === 0) return 'fail';
+  if (results.some((r) => r.verdict === 'fail')) return 'fail';
+  if (results.some((r) => r.verdict === 'warn')) return 'warn';
+  return 'pass';
+}
+
+// Empty results never pass: a synthesised row is emitted with an actionable detail and its
+// own evidence object recording the empty condition so the row is
+// not a naked verdict scalar.
+export function normaliseResults(results) {
+  if (!Array.isArray(results) || results.length === 0) {
+    return [{
+      anchorReqId: 'unknown',
+      verdict: 'fail',
+      detail: 'no checks ran',
+      evidence: {
+        reason: 'empty-results',
+        route: 'n/a',
+        status: 0,
+        xFixtureRequestId: null,
+        bodyExcerpt: '',
+      },
+    }];
+  }
+  return results;
+}
+
+export async function writeReport({ probeName, engine, results, extra }) {
+  await mkdir(REPORT_DIR, { recursive: true });
+  const report = {
+    slug: 'application-dashboard',
+    probeName,
+    runAt: new Date().toISOString(),
+    engine,
+    results,
+    aggregateVerdict: aggregate(results),
+    ...(extra ?? {}),
+  };
+  const path = resolve(REPORT_DIR, `${probeName}.json`);
+  await writeFile(path, JSON.stringify(report, null, 2) + '\n', 'utf8');
+  return { report, path };
+}
+
+// Starts the fixture on an ephemeral port (or PROBE_PORT when set)
+// and returns { server, port, baseUrl, close }. The close helper
+// rejects when the underlying close callback carries an error;
+// swallowing a teardown error would hide a boundary failure.
+export async function startFixture({ startServer, port } = {}) {
+  const resolvedPort = typeof port === 'number'
+    ? port
+    : Number(process.env.PROBE_PORT ?? DEFAULT_PORT);
+  const started = await startServer({ port: resolvedPort });
+  return {
+    server: started.server,
+    port: started.port,
+    baseUrl: `http://127.0.0.1:${started.port}`,
+    close: () => new Promise((res, rej) => started.server.close((err) => {
+      if (err) rej(err);
+      else res();
+    })),
+  };
+}
+
+// Reads a distinctive slice of a response body: the first N chars
+// so the report carries a body excerpt alongside the header id.
+export function bodyExcerpt(text, max = 240) {
+  if (text == null) return '';
+  const s = typeof text === 'string' ? text : String(text);
+  return s.length > max ? s.slice(0, max) + '...' : s;
+}
+
+// Records the positive-evidence shape on a probe result. Every row
+// carries route, status, the request id the fixture stamped, and a
+// body excerpt; the caller may extend the object with the varied
+// input and the derived output for that row.
+export function evidenceFromResponse({ route, response, bodyText, extraFields }) {
+  return {
+    route,
+    status: response.status,
+    xFixtureRequestId: response.headers.get('x-fixture-request-id') || null,
+    bodyExcerpt: bodyExcerpt(bodyText),
+    ...(extraFields ?? {}),
+  };
+}
+
+export async function runShim(probeName, engine, mainFn) {
+  try {
+    const outcome = (await mainFn()) ?? { results: [] };
+    const { results, extra } = outcome;
+    const { report, path } = await writeReport({ probeName, engine, results: normaliseResults(results), extra });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stdout.write(`report written to ${path}\n`);
+    if (report.aggregateVerdict !== 'pass') process.exitCode = 1;
+  } catch (err) {
+    const results = [{
+      anchorReqId: 'unknown',
+      verdict: 'fail',
+      detail: `probe threw: ${err && err.message ? err.message : String(err)}`,
+      evidence: {
+        reason: 'probe-threw',
+        route: 'n/a',
+        status: 0,
+        xFixtureRequestId: null,
+        bodyExcerpt: err && err.stack ? String(err.stack).slice(0, 240) : '',
+      },
+    }];
+    const { report, path } = await writeReport({ probeName, engine, results });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stderr.write(`probe error: ${err && err.stack ? err.stack : String(err)}\n`);
+    process.stderr.write(`report written to ${path}\n`);
+    process.exitCode = 1;
+  }
+}
+
+// Browser-observable properties are AMBER on the shelf by ruling.
+// A row that names such a property is recorded as notObservableHere
+// carrying an object with the AC id and a reason; the tally script
+// reads notObservableHere.ac to accept the row.
+export function notObservableHereResult({ ac, anchorAcId, detail, reason, evidence } = {}) {
+  // A notObservableHere row anchors nothing else: no anchorAcId,
+  // no anchorReqId - only notObservableHere.ac.
+  const acId = ac || anchorAcId;
+  return {
+    verdict: 'pass',
+    notObservableHere: {
+      ac: acId,
+      reason: reason || 'not observable on server-side probe pack; needs a browser-driven runner',
+    },
+    detail: detail || 'not observable on server-side probe pack',
+    evidence: {
+      reason: reason || 'not observable here; needs a browser-driven probe runner',
+      ...(evidence || {}),
+    },
+  };
+}
+
+// A row that keeps a real observation but records that the
+// observation only covers part of an AC uses conformanceOnly +
+// limitation carrying the AC id and the property not observed.
+export function conformanceOnlyResult({ anchorAcId, anchorReqId, verdict, detail, evidence, limitation }) {
+  return {
+    ...(anchorAcId ? { anchorAcId } : {}),
+    ...(anchorReqId ? { anchorReqId } : {}),
+    verdict: verdict || 'pass',
+    conformanceOnly: true,
+    limitation: limitation || 'browser-observable property not asserted from the server-side probe',
+    detail,
+    evidence,
+  };
+}

package/blueprints/application-dashboard/contributions/probes/run-export-handle-formats.mjs

@@ -0,0 +1,4 @@
+import runProbe from './export-handle-formats.mjs';
+import { runShim } from './probe-utils.mjs';
+const engine = { kind: 'application-dashboard-fixture', server: 'packages/rcf-lite/test/fixtures/probe-pack-application-dashboard/server.js' };
+runShim('export-handle-formats', engine, runProbe);

package/blueprints/application-dashboard/contributions/probes/run-four-tile-states.mjs

@@ -0,0 +1,4 @@
+import runProbe from './four-tile-states.mjs';
+import { runShim } from './probe-utils.mjs';
+const engine = { kind: 'application-dashboard-fixture', server: 'packages/rcf-lite/test/fixtures/probe-pack-application-dashboard/server.js' };
+runShim('four-tile-states', engine, runProbe);

package/blueprints/application-dashboard/contributions/probes/run-primary-kpi-top-left.mjs

@@ -0,0 +1,4 @@
+import runProbe from './primary-kpi-top-left.mjs';
+import { runShim } from './probe-utils.mjs';
+const engine = { kind: 'application-dashboard-fixture', server: 'packages/rcf-lite/test/fixtures/probe-pack-application-dashboard/server.js' };
+runShim('primary-kpi-top-left', engine, runProbe);

package/blueprints/application-dashboard/contributions/probes/run-shell-five-regions.mjs

@@ -0,0 +1,4 @@
+import runProbe from './shell-five-regions.mjs';
+import { runShim } from './probe-utils.mjs';
+const engine = { kind: 'application-dashboard-fixture', server: 'packages/rcf-lite/test/fixtures/probe-pack-application-dashboard/server.js' };
+runShim('shell-five-regions', engine, runProbe);

package/blueprints/application-dashboard/contributions/probes/shell-five-regions.mjs

@@ -0,0 +1,93 @@
+// shell-five-regions probe for application-dashboard v1.0.9.
+//
+// AC-19101-1: the DOM carries five labelled role="region" elements.
+// The fixture accepts a startServer({ regions: [...] }) override, so
+// the probe DRIVES two distinct region sets and asserts the
+// rendered DOM follows each input (derived, not
+// fixed inventory).
+//
+// anchorAcId: application-dashboard-AC-19101-1.
+
+import { startFixture, evidenceFromResponse } from './probe-utils.mjs';
+
+const FULL_SET = ['tile-row', 'chart-region', 'filter-chrome', 'timeframe-picker', 'export-handle'];
+const REDUCED_SET = ['tile-row', 'timeframe-picker', 'export-handle'];
+
+function scrapeRegions(body) {
+ const sectionRe = /<section\b([^>]*)>/g;
+ const regions = [];
+ let match;
+ while ((match = sectionRe.exec(body)) !== null) {
+ const attrs = match[1];
+ if (!/role="region"/.test(attrs)) continue;
+ const labelMatch = attrs.match(/aria-label="([^"]+)"/);
+ const dataRegionMatch = attrs.match(/data-region="([^"]+)"/);
+ regions.push({
+ ariaLabel: labelMatch ? labelMatch[1] : null,
+ dataRegion: dataRegionMatch ? dataRegionMatch[1] : null,
+ });
+ }
+ return regions;
+}
+
+async function driveOne(startServer, regionsInput, expected) {
+ const fixture = await new Promise((resolve, reject) => {
+ startServer({ port: 0, regions: regionsInput }).then((started) => {
+ resolve({ server: started.server, port: started.port, baseUrl: `http://127.0.0.1:${started.port}`, close: () => new Promise((r, rj) => started.server.close((e) => (e ? rj(e) : r()))) });
+ }).catch(reject);
+ });
+ try {
+ const res = await fetch(`${fixture.baseUrl}/`);
+ const body = await res.text();
+ const regions = scrapeRegions(body);
+ const dataRegionsFound = regions.map((r) => r.dataRegion).filter(Boolean);
+ // Only count REAL known-content regions (skip shell-root wrapper if present).
+ const contentRegions = dataRegionsFound.filter((r) => r !== 'shell-root');
+ const matchesInput = contentRegions.length === expected.length
+ && expected.every((r) => contentRegions.includes(r))
+ && contentRegions.every((r) => expected.includes(r));
+ return { res, body, regions, dataRegionsFound, contentRegions, matchesInput, fixture };
+ } finally {
+ await fixture.close();
+ }
+}
+
+export const anchorReqId = 'application-dashboard-REQ-001';
+export const accountBound = false;
+
+export default async function runProbe() {
+ const { startServer } = await import('../../../../packages/rcf-lite/test/fixtures/probe-pack-application-dashboard/server.js');
+
+ const results = [];
+ const runFull = await driveOne(startServer, FULL_SET, FULL_SET);
+ const runReduced = await driveOne(startServer, REDUCED_SET, REDUCED_SET);
+ const derivedFromInput = runFull.matchesInput && runReduced.matchesInput
+ && JSON.stringify(runFull.contentRegions) !== JSON.stringify(runReduced.contentRegions);
+ const labelsUniqueFull = new Set(runFull.regions.map((r) => r.ariaLabel).filter(Boolean)).size === runFull.regions.length;
+ const allLabelledFull = runFull.regions.every((r) => typeof r.ariaLabel === 'string' && r.ariaLabel.length > 0);
+ const pass = runFull.res.status === 200 && runReduced.res.status === 200
+ && derivedFromInput && labelsUniqueFull && allLabelledFull && runFull.contentRegions.length === 5;
+
+ results.push({
+ anchorAcId: 'application-dashboard-AC-19101-1',
+ verdict: pass ? 'pass' : 'fail',
+ detail: `Given a rendered dashboard surface, the DOM carries - drove two distinct region sets: full=[${runFull.contentRegions.join(',')}] reduced=[${runReduced.contentRegions.join(',')}]; regions follow the input (${derivedFromInput}); five labels unique in the full run (${labelsUniqueFull})`,
+ evidence: evidenceFromResponse({
+ route: '/',
+ response: runFull.res,
+ bodyText: runFull.body,
+ extraFields: {
+ input: { runFull: FULL_SET, runReduced: REDUCED_SET },
+ derived: {
+ fullContentRegions: runFull.contentRegions,
+ reducedContentRegions: runReduced.contentRegions,
+ derivedFromInput,
+ fullLabelsUnique: labelsUniqueFull,
+ fullAllLabelled: allLabelledFull,
+ },
+ altBodyExcerpt: runReduced.body.slice(0, 240),
+ },
+ }),
+ });
+ return { results };
+}

package/blueprints/application-dashboard/contributions/requirements/application-dashboard-req-002.json

@@ -2,7 +2,7 @@
   "reqId": "application-dashboard-REQ-002",
   "prdId": "PRD-001",
   "title": "The primary KPI tile sits top-left in DOM order and in CSS Grid position across the ratified breakpoints",
-  "description": "The tile row's primary KPI carries a top-left placement the reader reaches first, on the NN/g F-scan of the surface, at every ratified breakpoint (1440, 1024, 360). At 1440 and 1024 the primary KPI is the first tile in DOM order and its computed CSS Grid column-start is 1 and row-start is 1; at 360 the tile row reflows to one column and the primary KPI is the first tile in DOM order and its row-start is 1. The tile carries a `data-tile-role=\"primary-kpi\"` attribute and a `data-kpi-kind` attribute whose value is one of the ADR-2001 enum values (revenue, active-users, error-rate, throughput, custom). A dashboard that ships no primary KPI tile fails this REQ at project-side review; a dashboard whose primary KPI is not top-left at any of the three breakpoints fails the pack check AC-19102-1. When the elicited `primary-kpi-kind` is `custom` the tile also carries a `data-kpi-name` attribute whose value is the operator-elicited `primary-kpi-custom-name` short name.",
+  "description": "The tile row's primary KPI carries a top-left placement the reader reaches first, on the NN/g F-scan of the surface, at every shipped breakpoint (1440, 1024, 360). At 1440 and 1024 the primary KPI is the first tile in DOM order and its computed CSS Grid column-start is 1 and row-start is 1; at 360 the tile row reflows to one column and the primary KPI is the first tile in DOM order and its row-start is 1. The tile carries a `data-tile-role=\"primary-kpi\"` attribute and a `data-kpi-kind` attribute whose value is one of the ADR-2001 enum values (revenue, active-users, error-rate, throughput, custom). A dashboard that ships no primary KPI tile fails this REQ at project-side check; a dashboard whose primary KPI is not top-left at any of the three breakpoints fails the pack check AC-19102-1. When the elicited `primary-kpi-kind` is `custom` the tile also carries a `data-kpi-name` attribute whose value is the operator-elicited `primary-kpi-custom-name` short name.",
   "category": "functional",
   "domain": "application",
   "priority": "must",

package/blueprints/application-dashboard/contributions/requirements/application-dashboard-req-003.json

@@ -2,7 +2,7 @@
   "reqId": "application-dashboard-REQ-003",
   "prdId": "PRD-001",
   "title": "Every tile honours a four-state contract with distinct visuals, role region, aria-live polite, and non-colour distinction",
-  "description": "Every tile on the shell renders one of four states at any moment: loading, empty, error, populated. Each state carries a distinct visual (a skeleton stripe or spinner for loading, a labelled empty-state block for empty, a labelled error block with the recorded reason for error, and the actual metric for populated). Each tile wraps its content in `role=\"region\"` with an `aria-live=\"polite\"` announcer that reads the state transition on change. The state distinction combines a visual cue and a text label (non-colour distinction, WCAG 1.4.1): the state's visual is not colour-only, and the state's accessible name reads `<tile title>, <state>` on entry. A tile that renders no visible state (a blank tile) fails REQ-003 at project-side review; a tile that carries state-only through colour fails the pack check AC-19103-1.",
+  "description": "Every tile on the shell renders one of four states at any moment: loading, empty, error, populated. Each state carries a distinct visual (a skeleton stripe or spinner for loading, a labelled empty-state block for empty, a labelled error block with the recorded reason for error, and the actual metric for populated). Each tile wraps its content in `role=\"region\"` with an `aria-live=\"polite\"` announcer that reads the state transition on change. The state distinction combines a visual cue and a text label (non-colour distinction, WCAG 1.4.1): the state's visual is not colour-only, and the state's accessible name reads `<tile title>, <state>` on entry. A tile that renders no visible state (a blank tile) fails REQ-003 at project-side check; a tile that carries state-only through colour fails the pack check AC-19103-1.",
   "category": "functional",
   "domain": "application",
   "priority": "must",

package/blueprints/application-dashboard/contributions/tacs/tac-2002-application-dashboard-filter-chrome.json

@@ -8,7 +8,7 @@
   "purpose": "Owns the shell's timeframe picker and filter chrome, and the refetch fan-out contract: a preset change or a filter change issues one refetch per tile and one per rendered chart, every fetch carrying the same boundary and the same preset name, and once the batch has returned the shell updates one `data-as-of` attribute the tiles inherit. The fan-out contract is the substitutable interface the pack asserts on (AC-19104-1).",
   "responsibilities": [
     "Render the timeframe picker as an accessible list of presets (labelled `<button>` elements or a `<select>`) with a keyboard-reachable default from ADR-2002 (`last-7-days` unless elicited) (AC-19104-1).",
-    "Render filter chrome as labelled interactive elements (chips, dropdowns, text inputs) keyboard-reachable in reading order before the tile row; a hover-only control is refused at project-side review (AC-19105-1).",
+    "Render filter chrome as labelled interactive elements (chips, dropdowns, text inputs) keyboard-reachable in reading order before the tile row; a hover-only control is refused at project-side check (AC-19105-1).",
     "On a preset change or a filter change, issue one refetch per tile and one per rendered chart; every fetch carries the same `from` and `to` boundary, the same `preset` name and the same active-filters set (AC-19104-1, AC-19105-2).",
     "Update one `data-as-of` attribute on the shell root once every fetch has returned (or the timeout has elapsed) and propagate the same value to every tile's `data-as-of` attribute (AC-19104-1).",
     "Expose a request log on `window.__dashboardFetches` (an append-only array of `{ from, to, preset, filters, tileId, chartId, at }` records) so the pack can read every fetch after each preset change (AC-19104-1)."

package/blueprints/application-dashboard/contributions/tacs/tac-2003-application-dashboard-export-handle.json

@@ -28,8 +28,8 @@
       "description": "PNG-of-chart export generation delegates to the charts shell; the dashboard export handle carries no PNG generator of its own."
     }
   ],
-  "tradeoffs": "The three shipped formats (CSV, PDF, PNG-of-chart) cover the common dashboard export cases; ADR-2003's elicited override handles SVG, XLSX and any operator-specific format. The delegation to the charts shell means a project that ships a bespoke chart engine outside the render shell needs a PNG output path of its own; the export handle names the residual under project-side review.",
-  "notes": "Known mechanism-reach gap: the pack browser has no download-capture seam today, so AC-19106-2 (PNG delegation) is proven at project-side review, not through the shipped pack. The README names it individually.",
+  "tradeoffs": "The three shipped formats (CSV, PDF, PNG-of-chart) cover the common dashboard export cases; ADR-2003's elicited override handles SVG, XLSX and any operator-specific format. The delegation to the charts shell means a project that ships a bespoke chart engine outside the render shell needs a PNG output path of its own; the export handle names the residual under project-side check.",
+  "notes": "Known mechanism-reach gap: the pack browser has no download-capture seam today, so AC-19106-2 (PNG delegation) is proven at project-side check, not through the shipped pack. The README names it individually.",
   "createdAt": "2026-09-04T22:10:00Z",
   "updatedAt": "2026-09-04T22:10:00Z"
 }

package/blueprints/application-dashboard/contributions/user-stories/application-dashboard-us-19101.json

@@ -21,7 +21,7 @@
     },
     {
       "id": "AC-19101-2",
-      "description": "Given the shell's chart region, the rendered chart mounts through the application-charts render shell (TAC-1901): the chart region contains at least one `section.chartRegion[role=\"region\"]` element carrying the shape the application-charts pack asserts on (an `svg.chartSvg` and a paired `<table>` element in the same landmark). A chart region that renders a chart outside the render shell fails project-side review.",
+      "description": "Given the shell's chart region, the rendered chart mounts through the application-charts render shell (TAC-1901): the chart region contains at least one `section.chartRegion[role=\"region\"]` element carrying the shape the application-charts pack asserts on (an `svg.chartSvg` and a paired `<table>` element in the same landmark). A chart region that renders a chart outside the render shell fails project-side check.",
       "given": "the rendered chart region",
       "when": "the mount seam is inspected",
       "then": "the chart mounts through the application-charts render shell",
@@ -31,7 +31,7 @@
     },
     {
       "id": "AC-19101-3",
-      "description": "Given a rendered dashboard surface, when a required region is omitted from the DOM (no export handle, no filter chrome, no timeframe picker), the surface either supersedes REQ-001 with a project-authored REQ documenting the omission (the pack looks up the sidecar `rcf/blueprints/application-dashboard.applied.json` for a `supersedes` entry) or renders the region as an empty labelled `role=\"region\"` element the pack can inspect; a silent omission fails project-side review.",
+      "description": "Given a rendered dashboard surface, when a required region is omitted from the DOM (no export handle, no filter chrome, no timeframe picker), the surface either supersedes REQ-001 with a project-authored REQ documenting the omission (the pack looks up the sidecar `rcf/blueprints/application-dashboard.applied.json` for a `supersedes` entry) or renders the region as an empty labelled `role=\"region\"` element the pack can inspect; a silent omission fails project-side check.",
       "given": "a rendered dashboard surface with a missing region and no documented supersedes entry",
       "when": "the pack inspects the shell",
       "then": "the surface fails the region-count check; the applying project must either supersede REQ-001 with a documented reason or render the region as an empty labelled role=region element",

package/blueprints/application-dashboard/contributions/user-stories/application-dashboard-us-19102.json

@@ -21,10 +21,10 @@
     },
     {
       "id": "AC-19102-2",
-      "description": "Given a rendered dashboard surface with no primary KPI tile, the surface either supersedes REQ-002 with a project-authored REQ documenting the omission or fails project-side review. This case is a documentation-and-review contract; the pack asserts the primary KPI tile exists (AC-19102-1) but does not itself enforce the fallback path.",
+      "description": "Given a rendered dashboard surface with no primary KPI tile, the surface either supersedes REQ-002 with a project-authored REQ documenting the omission or fails project-side check. This case is a documentation contract; the pack asserts the primary KPI tile exists (AC-19102-1) but does not itself enforce the fallback path.",
       "given": "a rendered dashboard with no primary KPI tile",
       "when": "the surface is reviewed",
-      "then": "the surface supersedes REQ-002 with a project-authored REQ or fails review",
+      "then": "the surface supersedes REQ-002 with a project-authored REQ or fails the check",
       "testable": true,
       "scope": "library",
       "disposition": "fixed"

package/blueprints/application-dashboard/contributions/user-stories/application-dashboard-us-19103.json

@@ -21,7 +21,7 @@
     },
     {
       "id": "AC-19103-2",
-      "description": "Given a tile transitioning between states (loading to populated, populated to error) at runtime, the tile's `aria-live=\"polite\"` region announces the new state's accessible name to the assistive tech; the announcement text reads `<tile title>, <new state>` and the visual cue changes in the same paint. This AC is a runtime-observable behaviour on state transition; the pack does not simulate the transition today (the runner has no synthetic-event seam beyond click/type/press), so the AC is proven at project-side review and the README names the transition-observation gap under known mechanism-reach gaps.",
+      "description": "Given a tile transitioning between states (loading to populated, populated to error) at runtime, the tile's `aria-live=\"polite\"` region announces the new state's accessible name to the assistive tech; the announcement text reads `<tile title>, <new state>` and the visual cue changes in the same paint. This AC is a runtime-observable behaviour on state transition; the pack does not simulate the transition today (the runner has no synthetic-event seam beyond click/type/press), so the AC is proven at project-side check and the README names the transition-observation gap under known mechanism-reach gaps.",
       "given": "a tile transitioning between states",
       "when": "the transition renders",
       "then": "the aria-live polite region announces the new state's accessible name and the visual cue changes",

package/blueprints/application-dashboard/contributions/user-stories/application-dashboard-us-19104.json

@@ -21,7 +21,7 @@
     },
     {
       "id": "AC-19104-2",
-      "description": "Given a rendered dashboard with an operator-elicited auto-refresh interval (ADR-2002), the shell refetches on the same fan-out contract at the interval: every tile refetches with the same from/to/preset, the as-of stamp updates on the shell root and every tile. When no auto-refresh interval is elicited, the shell does not refresh unattended (a dashboard that refreshes every ten seconds without an operator opt-in is a defect). The pack asserts the initial default is auto-refresh off through a `data-auto-refresh` attribute on the shell root; a fixture whose default is on fails project-side review. Applying agent sets: the elicited auto-refresh interval value in seconds (ADR-2002) or the explicit off default, recorded on the manifest and reflected on the shell root as `data-auto-refresh`.",
+      "description": "Given a rendered dashboard with an operator-elicited auto-refresh interval (ADR-2002), the shell refetches on the same fan-out contract at the interval: every tile refetches with the same from/to/preset, the as-of stamp updates on the shell root and every tile. When no auto-refresh interval is elicited, the shell does not refresh unattended (a dashboard that refreshes every ten seconds without an operator opt-in is a defect). The pack asserts the initial default is auto-refresh off through a `data-auto-refresh` attribute on the shell root; a fixture whose default is on fails project-side check. Applying agent sets: the elicited auto-refresh interval value in seconds (ADR-2002) or the explicit off default, recorded on the manifest and reflected on the shell root as `data-auto-refresh`.",
       "given": "a rendered dashboard with or without an elicited auto-refresh interval",
       "when": "the shell renders",
       "then": "auto-refresh is off unless the interval is elicited; refreshes follow the same fan-out contract",

package/blueprints/application-dashboard/contributions/user-stories/application-dashboard-us-19105.json

@@ -11,7 +11,7 @@
   "acceptanceCriteria": [
     {
       "id": "AC-19105-1",
-      "description": "Given a rendered dashboard surface with filter chrome, every filter control (chip, dropdown, search input) is a labelled interactive element (a `<button>`, a `<select>` or an `<input>`) with an accessible name; the controls are keyboard-reachable in reading order before the tile row; the operator's active filter selection is reflected on the shell as a `data-active-filters` attribute the pack can read. A filter chrome that ships hover-only controls (a hover-reveal menu on a mouseover element) fails project-side review.",
+      "description": "Given a rendered dashboard surface with filter chrome, every filter control (chip, dropdown, search input) is a labelled interactive element (a `<button>`, a `<select>` or an `<input>`) with an accessible name; the controls are keyboard-reachable in reading order before the tile row; the operator's active filter selection is reflected on the shell as a `data-active-filters` attribute the pack can read. A filter chrome that ships hover-only controls (a hover-reveal menu on a mouseover element) fails project-side check.",
       "given": "a rendered dashboard with filter chrome",
       "when": "the accessibility tree is read",
       "then": "every filter control is a labelled interactive element keyboard-reachable in reading order",