rcf-lite 0.20.0 → 0.22.0

package/blueprints/application-datatable/contributions/user-stories/application-datatable-us-17105.json

@@ -0,0 +1,44 @@
+{
+  "usId": "application-datatable-US-17105",
+  "prdId": "PRD-001",
+  "reqId": "application-datatable-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Empty, loading, error and no-results states each render a distinct region with a polite live announcement",
+  "asA": "screen-reader user or keyboard-only user navigating a datatable that has no rows to show",
+  "iWant": "each of the four states to render inside its own `role=\"region\"` element with `aria-live=\"polite\"` and a distinct visual so the reason no rows show is announced and readable",
+  "soThat": "the state is unambiguous and not confused with stale content",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17105-1",
+      "description": "Given a datatable route in each of the four states (empty, loading, error, no-results), the rendered DOM carries a `role=\"region\"` element with `aria-live=\"polite\"` per state; the no-results state is distinguished from empty by the presence of a non-empty active filter (`q`). The check drives the shell to each state via query parameter, reads the accessibility tree, and asserts the region and live values. Probed by pack check AC-17105-1.",
+      "given": "the datatable route driven to each of the four states",
+      "when": "the state region renders",
+      "then": "each state carries a `role=\"region\"` element with `aria-live=\"polite\"` and a distinct heading",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17105-2",
+      "description": "Given a datatable route in each of the four states, no state relies on colour alone to convey its meaning (WCAG 1.4.1): each state includes text content that names the state (empty, loading, error, or no results).",
+      "given": "the datatable route driven to each of the four states",
+      "when": "the state region renders",
+      "then": "each state region includes text content that names the state without relying on colour",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17105-3",
+      "description": "Given a rendered datatable in the loading state, when the fetch resolves and rows arrive, the loading region is removed from the accessibility tree and the populated data region replaces it (never overlaid). The check drives the surface into loading, waits for resolution, and asserts the loading region is gone.",
+      "given": "a datatable in the loading state",
+      "when": "the fetch resolves and rows arrive",
+      "then": "the loading region is removed and the populated data region renders without the loading region present",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1801-application-datatable-shell"],
+  "tags": ["blueprint:application-datatable"],
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/user-stories/application-datatable-us-17106.json

@@ -0,0 +1,44 @@
+{
+  "usId": "application-datatable-US-17106",
+  "prdId": "PRD-001",
+  "reqId": "application-datatable-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Column visibility, reorder and resize each expose a keyboard-reachable alternative to any drag pointer path",
+  "asA": "operator who cannot drag with a pointer",
+  "iWant": "column visibility, reorder and resize to expose a non-drag path so the column layout is fully operable from the keyboard",
+  "soThat": "WCAG 2.5.7 Dragging Movements is met and the surface stays operable on assistive input devices",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17106-1",
+      "description": "Given a rendered datatable, the surface exposes a non-drag path to reorder columns: a paired move-left / move-right button per column, or a menu ordering. The check reads the initial header order, activates a move-left control on a middle column, and asserts the header order changed. Probed by pack check AC-17106-1.",
+      "given": "a rendered datatable with more than one column",
+      "when": "the operator activates a keyboard-reachable move control on a column",
+      "then": "the header order changes to reflect the move",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17106-2",
+      "description": "Given a rendered datatable, the column visibility toggle exposes a keyboard-reachable control (a checkbox or menu item) per toggleable column; activating the control hides or shows that column and its header cell without a page reload.",
+      "given": "a rendered datatable with toggleable columns",
+      "when": "the operator activates a column visibility control",
+      "then": "the target column's header and body cells hide or show accordingly",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17106-3",
+      "description": "Given a rendered datatable that supports column resize, the surface exposes a keyboard-reachable resize path (an increment or decrement control per column, or an equivalent menu option) so the width is operable without a pointer drag.",
+      "given": "a rendered datatable that supports column resize",
+      "when": "the operator activates the keyboard resize path on a column",
+      "then": "the column width changes by the declared increment without a pointer drag",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1801-application-datatable-shell"],
+  "tags": ["blueprint:application-datatable"],
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/user-stories/application-datatable-us-17107.json

@@ -0,0 +1,44 @@
+{
+  "usId": "application-datatable-US-17107",
+  "prdId": "PRD-001",
+  "reqId": "application-datatable-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The rendered table shell uses the ARIA APG pattern that matches the surface's interactivity",
+  "asA": "assistive-tech user reading the datatable",
+  "iWant": "the shell to render as an ARIA APG table for read-only rows and as an ARIA APG grid once cells contain interactive controls",
+  "soThat": "the assistive-tech pattern matches the interactivity of the surface (ADR-1801)",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17107-1",
+      "description": "Given a datatable shell that renders interactive per-row controls (sort buttons, selection checkboxes, inline actions), the rendered element is a `<table role=\"grid\">` with `<th>` cells scoped to `col`; a read-only variant that renders no per-row interactive controls stays on the plain `<table>` pattern. The check reads the accessibility tree at the shell route and asserts the presence of the grid role when the shell ships interactive controls.",
+      "given": "a datatable route that ships interactive per-row controls",
+      "when": "the shell renders",
+      "then": "the rendered table has `role=\"grid\"` and header cells scoped to `col`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17107-2",
+      "description": "Given a rendered datatable, every per-row inline action (edit, delete, resend) has an accessible name that includes the acted-on row's identifier or a semantically equivalent noun (not `Edit` alone); the accessible name is readable by assistive tech per WCAG 4.1.2.",
+      "given": "a rendered datatable with per-row inline actions",
+      "when": "assistive tech reads the action controls",
+      "then": "each action's accessible name identifies the acted-on row",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17107-3",
+      "description": "Given a rendered datatable, the header row exposes each column's role (`<th scope=\"col\">` or `role=\"columnheader\"`) and every data cell resolves to a column header for row-and-column readouts on assistive tech (WCAG 1.3.1).",
+      "given": "a rendered datatable",
+      "when": "assistive tech traverses a data cell",
+      "then": "the announced context includes the column header the cell resolves to",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1801-application-datatable-shell"],
+  "tags": ["blueprint:application-datatable"],
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/user-stories/application-datatable-us-17108.json

@@ -0,0 +1,44 @@
+{
+  "usId": "application-datatable-US-17108",
+  "prdId": "PRD-001",
+  "reqId": "application-datatable-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "URL state serialisation preserves sort, filter and page across reload and share",
+  "asA": "operator sharing a specific datatable view with a colleague",
+  "iWant": "the sort, filter and page state to serialise into the URL so a reload or a shared link lands on the same view",
+  "soThat": "the surface is deep-linkable and reload-stable (ADR-1802's recommended default)",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17108-1",
+      "description": "Given a rendered datatable where the operator applied a sort, a filter and advanced past page 1, the current URL carries the state as query parameters (`sort`, `q`, `page`) per ADR-1802's recommended default; reloading the URL rerenders the same view.",
+      "given": "a rendered datatable with an applied sort, filter and non-first page",
+      "when": "the operator reloads the URL",
+      "then": "the reloaded surface renders the same sort, filter and page",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17108-2",
+      "description": "Given the elicited client-side sort alternative (ADR-1802 elicited variant) applied to a small in-memory collection, the sort direction still writes to the URL so reload stability is preserved; the client-side branch never invents a URL state divergent from the server-side default.",
+      "given": "a rendered datatable applying the client-side sort alternative",
+      "when": "the operator activates a sort control",
+      "then": "the URL query parameters update with `sort=<column>:<direction>` in the same shape as the server-side default",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17108-3",
+      "description": "Given a rendered datatable, the default page size on the recommended default (ADR-1803) applies when no `pageSize` is present in the URL; the operator's elicited page-size override at apply time changes the default without changing the URL contract.",
+      "given": "a rendered datatable landed at the shell route without a `pageSize` query parameter",
+      "when": "the initial render fetches the first page",
+      "then": "the fetch carries `pageSize=<applied-default>` and the URL is left untouched",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1801-application-datatable-shell", "TAC-1802-application-datatable-query-adapter"],
+  "tags": ["blueprint:application-datatable"],
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/user-stories/application-datatable-us-17109.json

@@ -0,0 +1,44 @@
+{
+  "usId": "application-datatable-US-17109",
+  "prdId": "PRD-001",
+  "reqId": "application-datatable-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Selection persistence across pages holds the elicited contract and announces the running count",
+  "asA": "operator selecting rows across several pages before running a bulk action",
+  "iWant": "the selection model to persist my row selections across pagination and announce the running count",
+  "soThat": "cross-page bulk operations are visible and reversible",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17109-1",
+      "description": "Given an operator elicited `selectionPersistence=cross-page` (ADR-1804), when the operator selects rows on page 1 and advances to page 2, the previously selected row ids remain in the selection model; a return to page 1 re-renders the checkboxes as checked. The check clicks a row checkbox, advances the page, returns, and asserts the checkbox is still checked.",
+      "given": "a rendered datatable with elicited cross-page selection persistence",
+      "when": "the operator selects rows on page 1 and paginates away and back",
+      "then": "the row checkboxes on page 1 remain in the selected state on return",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17109-2",
+      "description": "Given a running row selection, the surface renders the current count in an accessible location adjacent to the bulk action controls; the count updates when a row is toggled without a full re-render of the surface.",
+      "given": "a rendered datatable with at least one row selected",
+      "when": "the operator toggles a second row",
+      "then": "the accessible selection count updates by one without a full page re-render",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17109-3",
+      "description": "Given the operator did not elicit cross-page persistence (ADR-1804's non-elicited default), the selection resets on pagination; the surface names this behaviour in the accessible copy near the bulk action control so operators are not surprised on advance.",
+      "given": "a rendered datatable without cross-page persistence elicited",
+      "when": "the operator selects rows and paginates away",
+      "then": "the selection clears on advance and the accessible copy on the bulk-action region names the per-page-only behaviour",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1803-application-datatable-selection-model"],
+  "tags": ["blueprint:application-datatable"],
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/docs/topics.md

@@ -0,0 +1,42 @@
+# application-datatable: coordination vocabulary
+
+## Global topics
+
+The blueprint claims no new global topics at v1.0.0. The datatable shell is a general enterprise practice contract; every ADR (pattern choice, URL state, page size, selection persistence) is non-global.
+
+## Deliberately unclaimed topics
+
+- `dataGridEngine` (the chosen data-table library). Reserved for the applying project as an elicited choice, not a global topic; a second datatable-shaped blueprint that composes with a specific engine would either supersede this blueprint or share the shell TAC.
+- `columnRegistry` (a shared column vocabulary across surfaces). No blueprint claims it today; a future admin-console blueprint (visual round T-5) may elicit column reuse without minting a global topic.
+
+## Shelf id band and suffix block
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-datatable | 17101-17899 | 18xx | shipped v1.0.0 | none |
+| application-charts | 18101-18899 | 19xx | shipped v1.0.0 | none |
+| application-dashboard | 19101-19899 | 20xx | shipped v1.0.0 | none |
+| application-notifications-in-app | 20101-20899 | 21xx | shipped v1.0.0 | none |
+| application-admin-console | 21101-21899 | 22xx | shipped v1.0.0 | none |
+| application-empty-error-states | 22101-22899 | 23xx | shipped v1.0.0 | none |
+| application-file-upload | 23101-23899 | 24xx | shipped v1.0.0 | none |
+| application-forms-wizard | 24101-24899 | 25xx | shipped v1.0.0 | none |
+| application-account-settings | 25101-25899 | 26xx | shipped v1.0.0 | none |
+| application-onboarding-tour | 26101-26899 | 27xx | shipped v1.0.0 | none |
+| persistence-data-postgres | 27101-27899 | 28xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| object-storage-s3 | 28101-28899 | 29xx | shipped v1.0.0 | `objectStorageContract` |
+
+The shelf-wide band registry lives in `packages/rcf-lite/docs/blueprint-authoring.md` section 5.
+
+## Probe pack
+
+`probe-packs/application-datatable.pack.mjs` ships six checks anchored to blueprint AC ids:
+
+- `AC-17101-1` sort click reorders rows
+- `AC-17102-1` filter text search issues q request
+- `AC-17103-2` pagination announcement in aria-live region
+- `AC-17104-3` bulk-action confirmation dialog returns focus to originating row
+- `AC-17105-1` state distinctness (empty / loading / error / no-results)
+- `AC-17106-1` column reorder keyboard alternative
+
+The pack applies to any FBS binding `TAC-1801-application-datatable-shell` or whose navModel routes name a datatable path. See `packages/rcf-lite/docs/blueprint-authoring.md` section 8c for the pack authoring rules.

package/blueprints/application-datatable/guide/application-datatable.md

@@ -0,0 +1,38 @@
+# Guide: application-datatable (v1.0.0)
+
+## What it is
+
+A shipped, vendor-neutral datatable contract for a rcf-lite application. One shell (TAC-1801), one query adapter (TAC-1802), one selection model (TAC-1803), plus a shipped Playwright probe pack that gates ship on the six runtime-observable surfaces the shelf assures: sort activation reorders rendered rows, filter text search issues a `q` request, pagination announces `Page N of M` through an aria-live region, bulk actions open an APG dialog and return focus to the originating row, four states each render in their own region, and columns reorder without a drag.
+
+## What it deliberately is not
+
+- Not a data-table library. The shell is a contract; the applying project chooses TanStack Table, MUI DataGrid, AG Grid, a hand-rolled `<table>`, or any other realisation. The ACs are what ship must meet; the HOW is the project's decision.
+- Not a data-source contract. The query adapter (TAC-1802) targets a REST endpoint on the applied `application-api-rest`, a GraphQL query, or an in-memory adapter for small collections; the adapter shape is one project decision above the data source.
+- Not a row-level authorisation contract. The applied auth blueprint owns row-level visibility; the datatable reads the rows it is given.
+
+## When to reach for it
+
+- Any surface with tabular data the operator sorts, filters, paginates, or bulk-operates on. Users tables, orders, notifications, records, audit views. The dashboard blueprint (visual round T-3) consumes this shell for its `application-datatable` recent-items strip.
+- Projects that want the ARIA APG discipline (table vs grid per interactivity) enforced at ship without hand-authoring the rule per surface.
+
+## When it does not fit
+
+- Read-only presentation of static data where sort, filter or pagination are not needed. A plain `<table>` inside a marketing surface does not need this shell.
+- Highly bespoke tabular surfaces that render two-dimensional keyboard navigation over a non-table structure (a spreadsheet-shaped editor). Those supersede TAC-1801 with a project-authored shell.
+
+## What a good outcome looks like
+
+The rendered surface is a `<table role="grid">` when the shell ships interactive controls; sort activation reorders rows against the query adapter's response and announces the direction via `aria-sort`; the filter input carries `q` into the adapter; the pagination status region reads `Page N of M` and updates on advance; the bulk-action confirmation dialog opens as `role="dialog"` `aria-modal="true"` with `aria-labelledby` and `aria-describedby` set, initial focus lands on confirm, and cancel returns focus to the row control that opened the dialog; the four states each render inside their own `role="region"` with `aria-live="polite"`; column reorder has a paired left / right keyboard control per column; the shipped probe pack runs green on the delivery-ci-workflows gate.
+
+## The operator decisions that remain open
+
+- **The data-table realisation** (framework choice). TanStack Table, MUI DataGrid, AG Grid, hand-rolled `<table>`, or another. The ACs shape the outcome; the HOW is elicited at build time.
+- **Server-side or client-side query adapter** (ADR-1802). Server-side default; client-side elicited alternative for small in-memory collections.
+- **URL-state serialisation** (ADR-1802). Recommended default writes sort, filter and page into the URL; the session-scoped alternative is elicited for surfaces where deep-linking is undesirable.
+- **Default page size** (ADR-1803). Default 25; elicit an override at apply.
+- **Selection persistence across pages** (ADR-1804). Default `perPage`; `crossPage` elicited for high-cardinality bulk workflows.
+- **Per-column filter dropdowns** (REQ-003). Which columns expose them, and what the value set is per column. Elicited at build.
+
+## Cost-honesty
+
+Adds six REQs, nine USs (with 27 runtime-observable ACs), three TACs, four ADRs, one shipped probe pack, and one sample-app fixture to the shipped shelf. The runtime cost is one probe-pack run per shell FBS on the delivery-ci-workflows gate (approximately 5 to 15 seconds per pack invocation against a live server). No runtime dependency added to the applying project's `package.json`; the probe pack drives the browser the runner provisions through the pinned Playwright MCP or the project's own `playwright` when installed. The elicited parameters (data source shape, page size, URL-state, selection persistence) shape the applying project's surface without expanding the shipped shelf.

package/blueprints/application-datatable/probe-packs/application-datatable.pack.mjs

@@ -0,0 +1,240 @@
+// application-datatable probe pack (v1.0.0).
+//
+// Six runtime-observable checks anchored to the blueprint's ACs:
+//   AC-17101-1 sort click reorders rows (server-side sort)
+//   AC-17102-1 filter chrome text-search issues q=<value> request
+//   AC-17103-2 pagination announcement via aria-live "Page N of M"
+//   AC-17104-3 bulk-action confirmation focus return
+//   AC-17105-1 state region distinctness (empty / loading / error / no-results)
+//   AC-17106-1 column reorder keyboard alternative
+//
+// Every check drives the real Playwright browser the runner injects
+// (see rcf-lite src/browser-verify/pack-browser.js). Runs against a
+// server-side implementation of the shell: a keyboard-reachable sort
+// control, a text filter that issues fetch('/api/rows?q=...'),
+// pagination with an aria-live status region, row selection with a
+// bulk action that opens an aria-modal dialog and returns focus on
+// close, four distinct query-driven states, and a non-drag column
+// reorder path.
+
+export default {
+  packName: 'application-datatable',
+  version: '1.0.0',
+  blueprintSlug: 'application-datatable',
+  // Applies to any FBS that realises the datatable shell TAC or whose
+  // navModel routes name a datatable path. The source references both
+  // `tacIds` and `route` so the loader's applicability source-scan
+  // (route / tacIds / blueprint: tag) sees the two legal seams.
+  appliesTo: ({ fbs }) => {
+    const routes = fbs?.designStage?.navModel?.routes ?? [];
+    const tacIds = fbs?.contextRequirements?.tacIds ?? [];
+    if (tacIds.includes('TAC-1801-application-datatable-shell')) return true;
+    return routes.some((r) => typeof r?.path === 'string' && /datatable-shell|\/dt(\/|$)/.test(r.path));
+  },
+  boot: { bootCommand: null, waitForUrl: null, waitForSelector: null },
+  checks: [
+    {
+      id: 'AC-17101-1',
+      severity: 'block',
+      description: 'Sort click reorders rendered rows to match server sort order',
+      run: async ({ browser, fetch, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(runtimeUrl + '/');
+        const initialIds = await browser.evaluate(() =>
+          Array.from(document.querySelectorAll('table[role="grid"] tbody tr'))
+            .map((tr) => Number(tr.getAttribute('data-id'))));
+        if (!Array.isArray(initialIds) || initialIds.length === 0) {
+          return { verdict: 'fail', detail: 'no rows rendered: ' + JSON.stringify(initialIds) };
+        }
+        await browser.click('button.sortControl[data-column="score"]', 'score sort control');
+        // Give the client a beat to fetch and re-render.
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        const sortedIds = await browser.evaluate(() =>
+          Array.from(document.querySelectorAll('table[role="grid"] tbody tr'))
+            .map((tr) => Number(tr.getAttribute('data-id'))));
+        const apiRes = await fetch(runtimeUrl + '/api/rows?sort=score:asc&page=1&pageSize=3');
+        const apiPayload = await apiRes.json();
+        const apiIds = apiPayload.rows.map((r) => r.id);
+        if (JSON.stringify(sortedIds) === JSON.stringify(initialIds)) {
+          return { verdict: 'fail', detail: 'sort click did not change row order: initial=' + JSON.stringify(initialIds) };
+        }
+        if (JSON.stringify(sortedIds) !== JSON.stringify(apiIds)) {
+          return { verdict: 'fail', detail: 'rendered order ' + JSON.stringify(sortedIds) + ' does not match server sort ' + JSON.stringify(apiIds) };
+        }
+        return { verdict: 'pass', detail: 'initial=' + JSON.stringify(initialIds) + ' sorted=' + JSON.stringify(sortedIds) };
+      },
+    },
+    {
+      id: 'AC-17102-1',
+      severity: 'block',
+      description: 'Filter chrome text search issues q=<value> request and narrows rendered rows',
+      run: async ({ browser, fetch, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(runtimeUrl + '/');
+        await browser.type('input#filterInput', 'Alpha', 'filter input');
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        const names = await browser.evaluate(() =>
+          Array.from(document.querySelectorAll('table[role="grid"] tbody tr td:nth-child(3)'))
+            .map((td) => td.textContent.trim()));
+        const apiRes = await fetch(runtimeUrl + '/api/rows?q=Alpha&page=1&pageSize=3');
+        const apiPayload = await apiRes.json();
+        if (apiPayload.q !== 'Alpha') {
+          return { verdict: 'fail', detail: 'server did not read q parameter; payload.q=' + JSON.stringify(apiPayload.q) };
+        }
+        const expected = apiPayload.rows.map((r) => r.name);
+        if (JSON.stringify(names) !== JSON.stringify(expected)) {
+          return { verdict: 'fail', detail: 'filter did not narrow rows: rendered=' + JSON.stringify(names) + ' expected=' + JSON.stringify(expected) };
+        }
+        return { verdict: 'pass', detail: 'filter q=Alpha rendered ' + JSON.stringify(names) };
+      },
+    },
+    {
+      id: 'AC-17103-2',
+      severity: 'block',
+      description: 'Pagination announcement uses an aria-live region reading Page N of M',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(runtimeUrl + '/');
+        const initial = await browser.evaluate(() => {
+          const live = document.getElementById('paginationLive');
+          return { text: live?.textContent ?? '', ariaLive: live?.getAttribute('aria-live') ?? null };
+        });
+        if (initial.ariaLive !== 'polite') {
+          return { verdict: 'fail', detail: 'pagination status region missing aria-live=polite: ' + JSON.stringify(initial) };
+        }
+        if (!/^Page \d+ of \d+$/.test(initial.text)) {
+          return { verdict: 'fail', detail: 'initial pagination text does not match "Page N of M": ' + JSON.stringify(initial.text) };
+        }
+        await browser.click('button#pageNext', 'next page button');
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        const next = await browser.evaluate(() => document.getElementById('paginationLive')?.textContent ?? '');
+        if (!/^Page 2 of \d+$/.test(next)) {
+          return { verdict: 'fail', detail: 'next-page announcement did not update: ' + JSON.stringify(next) };
+        }
+        return { verdict: 'pass', detail: 'initial=' + JSON.stringify(initial.text) + ' next=' + JSON.stringify(next) };
+      },
+    },
+    {
+      id: 'AC-17104-3',
+      severity: 'block',
+      description: 'Bulk-action confirmation dialog opens as aria-modal and returns focus to the originating row on close',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(runtimeUrl + '/');
+        await browser.click('input.rowSelect[data-id="1"]', 'select row 1');
+        await browser.click('button#bulkAction', 'bulk action button');
+        await new Promise((resolve) => setTimeout(resolve, 300));
+        const opened = await browser.evaluate(() => {
+          const dialog = document.getElementById('bulkDialog');
+          return {
+            hidden: dialog?.hidden ?? true,
+            role: dialog?.getAttribute('role') ?? null,
+            ariaModal: dialog?.getAttribute('aria-modal') ?? null,
+            ariaLabelledBy: dialog?.getAttribute('aria-labelledby') ?? null,
+            ariaDescribedBy: dialog?.getAttribute('aria-describedby') ?? null,
+            focused: document.activeElement?.id ?? null,
+          };
+        });
+        if (opened.hidden || opened.role !== 'dialog' || opened.ariaModal !== 'true') {
+          return { verdict: 'fail', detail: 'dialog did not open with role=dialog and aria-modal=true: ' + JSON.stringify(opened) };
+        }
+        if (!opened.ariaLabelledBy || !opened.ariaDescribedBy) {
+          return { verdict: 'fail', detail: 'dialog missing aria-labelledby / aria-describedby: ' + JSON.stringify(opened) };
+        }
+        if (opened.focused !== 'bulkConfirm') {
+          return { verdict: 'fail', detail: 'confirm control did not receive focus on open: ' + JSON.stringify(opened) };
+        }
+        await browser.click('button#bulkCancel', 'cancel bulk');
+        await new Promise((resolve) => setTimeout(resolve, 300));
+        const closed = await browser.evaluate(() => ({
+          hidden: document.getElementById('bulkDialog')?.hidden ?? false,
+          focused: document.activeElement?.getAttribute?.('data-id') ?? document.activeElement?.id ?? null,
+          focusedTag: document.activeElement?.tagName ?? null,
+          focusedType: document.activeElement?.getAttribute?.('type') ?? null,
+        }));
+        if (!closed.hidden) {
+          return { verdict: 'fail', detail: 'dialog did not close: ' + JSON.stringify(closed) };
+        }
+        if (closed.focused !== '1' || closed.focusedType !== 'checkbox') {
+          return { verdict: 'fail', detail: 'focus did not return to row 1 checkbox: ' + JSON.stringify(closed) };
+        }
+        return { verdict: 'pass', detail: 'dialog open+close: opened=' + JSON.stringify(opened) + ' closed=' + JSON.stringify(closed) };
+      },
+    },
+    {
+      id: 'AC-17105-1',
+      severity: 'block',
+      description: 'Empty, loading, error and no-results states each render a distinct role=region with aria-live=polite',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        const states = [
+          { name: 'empty', url: runtimeUrl + '/?state=empty', expectId: 'emptyRegion' },
+          { name: 'loading', url: runtimeUrl + '/?state=loading', expectId: 'loadingRegion' },
+          { name: 'error', url: runtimeUrl + '/?state=error', expectId: 'errorRegion' },
+        ];
+        const observed = [];
+        for (const state of states) {
+          await browser.goto(state.url);
+          const info = await browser.evaluate((id) => {
+            const el = document.getElementById(id);
+            if (!el) return { present: false };
+            return {
+              present: true,
+              role: el.getAttribute('role'),
+              ariaLive: el.getAttribute('aria-live'),
+            };
+          }, state.expectId);
+          if (!info.present || info.role !== 'region' || info.ariaLive !== 'polite') {
+            return { verdict: 'fail', detail: 'state ' + state.name + ' missing region+aria-live: ' + JSON.stringify(info) };
+          }
+          observed.push({ state: state.name, info });
+        }
+        await browser.goto(runtimeUrl + '/?q=ZZZ');
+        await new Promise((resolve) => setTimeout(resolve, 400));
+        const noResults = await browser.evaluate(() => {
+          const el = document.getElementById('noResultsRegion');
+          if (!el) return { present: false };
+          return {
+            present: true,
+            hidden: el.hidden,
+            role: el.getAttribute('role'),
+            ariaLive: el.getAttribute('aria-live'),
+          };
+        });
+        if (!noResults.present || noResults.role !== 'region' || noResults.ariaLive !== 'polite') {
+          return { verdict: 'fail', detail: 'no-results region shape wrong: ' + JSON.stringify(noResults) };
+        }
+        return { verdict: 'pass', detail: 'observed=' + JSON.stringify(observed) + ' noResults=' + JSON.stringify(noResults) };
+      },
+    },
+    {
+      id: 'AC-17106-1',
+      severity: 'block',
+      description: 'Column reorder has a non-drag keyboard-reachable path (WCAG 2.5.7)',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(runtimeUrl + '/');
+        const buttons = await browser.evaluate(() =>
+          Array.from(document.querySelectorAll('button.columnMove')).map((b) => ({
+            column: b.getAttribute('data-column'),
+            direction: b.getAttribute('data-direction'),
+            ariaLabel: b.getAttribute('aria-label'),
+            tag: b.tagName,
+          })));
+        if (buttons.length === 0) {
+          return { verdict: 'fail', detail: 'no keyboard column-move buttons found' };
+        }
+        const initialOrder = await browser.evaluate(() =>
+          Array.from(document.querySelectorAll('table[role="grid"] thead th[data-column]')).map((th) => th.getAttribute('data-column')));
+        await browser.click('button.columnMove[data-column="score"][data-direction="left"]', 'move score left');
+        await new Promise((resolve) => setTimeout(resolve, 300));
+        const afterOrder = await browser.evaluate(() =>
+          Array.from(document.querySelectorAll('table[role="grid"] thead th[data-column]')).map((th) => th.getAttribute('data-column')));
+        if (JSON.stringify(initialOrder) === JSON.stringify(afterOrder)) {
+          return { verdict: 'fail', detail: 'column reorder button did not change header order: ' + JSON.stringify(initialOrder) };
+        }
+        return { verdict: 'pass', detail: 'initial=' + JSON.stringify(initialOrder) + ' after=' + JSON.stringify(afterOrder) + ' buttons=' + JSON.stringify(buttons.length) };
+      },
+    },
+  ],
+};

package/blueprints/application-empty-error-states/CHANGELOG.md

@@ -0,0 +1,9 @@
+# application-empty-error-states CHANGELOG
+
+## 1.0.0 (visual round T-1, spec 2026-09-06)
+
+- First ratified version of the shelf's empty-and-error-states blueprint. Five REQs (state catalogue with eight named states, recovery-action contract, announcement contract with role region and aria-live polite, least-privilege 5xx and 403 posture, offline state with write-buffer and reconnection semantics), eight USs 22101-22108 binding one runtime-observable AC per named state, three TACs 2301-2303 (state-machine, recovery-action router, offline write-buffer), three ADRs 2301-2303 (HTTP status contract per RFC 9110 as recommendedDefault, stack-trace visibility elicited with recommendedDefault true, offline strategy across write-buffer read-only-banner and refuse-writes elicited). No new global topics.
+- Ships `probe-packs/application-empty-error-states.pack.mjs`: eight surface-observable browser-verify checks anchored one per named state (`AC-22101-1` not-found, `AC-22102-1` forbidden, `AC-22103-1` server-error, `AC-22104-1` permission-denied, `AC-22105-1` offline, `AC-22106-1` empty-list, `AC-22107-1` no-search-results, `AC-22108-1` error-boundary). Every URL is composed by the `withUrl(runtimeUrl, path)` helper per the round 3 T-3 fix train; no bare string concatenation. The pack-level `appliesTo` predicate references BOTH `tacIds` (TAC-2301) AND `route` (the operator-configured error-shell path glob).
+- Ships a dependency-free sample-app fixture at `packages/rcf-lite/test/fixtures/probe-pack-application-empty-error-states/` with a Node HTTP server realising all eight states honestly under `/probe/<name>` and break switches (`?break=stack-trace`, `?break=leak-id`, `?break=no-recovery`, `?break=no-live-region`) driving the negative runs from a single boot. The fixture ships its own README naming PORT, every `?state=`, every `?break=`, the manual boot line and the two-line gate-reviewer boot.
+- Declares `suggestedCompanions` `logging` (every rendered error state writes one request-scoped log line with the correlation identifier) and `errorHandling` (the error-boundary state constructs an internal error record from the caught exception). Does NOT declare `providesRoles` (leaf blueprint per spec; loader refuses an empty `providesRoles` array when set, so the leaf-blueprint intent is expressed by omitting the field). Does NOT declare `capabilities` and does NOT declare `requiresAppliedCapabilities` (no auth required).
+- Sixth shipped consumer of T-0's probe-pack runner extension. T-3 `application-forms-wizard` consumes this blueprint for its "no in-progress forms" empty state; T-4 `application-account-settings` consumes this blueprint for its access-denied and empty-history states.