rcf-lite 0.19.0 → 0.21.0

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,35 @@
+# 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 |
+
+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-error-handling/docs/topics.md

@@ -20,5 +20,10 @@
 | Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
 |---|---|---|---|---|
 | application-error-handling | 16101-16899 | 17xx | shipped v1.0.0 | `errorHandling` |
+| 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 |
 
 The shelf-wide band registry lives in `packages/rcf-lite/docs/blueprint-authoring.md` section 5.

package/blueprints/application-notifications-in-app/CHANGELOG.md

@@ -0,0 +1,9 @@
+# application-notifications-in-app CHANGELOG
+
+## 1.0.0 (visual round T-4, spec 2026-09-04)
+
+- First ratified version of the shelf's application-notifications-in-app blueprint. Five REQs (live-region preseeding on every declared route; transient toast contract with priority-to-role mapping, one-shot announcement and timeout floor; notification centre inbox with retention and acknowledge round-trip; per-user preferences UI with category silence and sibling delegation; delivery-attempt log with operator-readable rows), eight USs binding runtime-observable ACs plus three cross-cutting cases (page load with backlog, background event, disjoint-content contract), three TACs (live-region wrappers with the toast factory; centre inbox with retention and acknowledge round-trip; preferences UI with sibling delegation), three ADRs (priority-to-role mapping polite/status vs assertive/alert per WCAG 4.1.3 and the ARIA APG alert pattern; six-second toast timeout floor per WCAG 2.2.1 with elicited overrides above the floor; thirty-day centre retention window with elicited overrides). No new global topics.
+- Reserves the `application-notifications-` family prefix for the sibling channel blueprints the shelf will grow into (`-email`, `-push`, `-webhook`) as a doc-only reservation on the blueprint README and every applying blueprint's `docs/topics.md` shelf band registry per Baz decision 2026-09-04 ("we might support more types of notifications - be clear in the name what these ones are").
+- Ships `probe-packs/application-notifications-in-app.pack.mjs`: three browser-verify checks anchored to blueprint AC ids, every check carrying a description field per spec section 9. `AC-20101-1` live-region preseeded on every declared route (wrappers present AND empty at load, enumerated by `[data-live-region]`). `AC-20102-1` transient toast contract with priority-to-role mapping and timeout measured against the ADR-2102 six-second floor via `data-shown-at`/`data-dismissed-at` timestamps (no six-second sleep in the pack; bounded polling). `AC-20103-1` centre acknowledge round-trip enumerated by `data-notification-id` (per-element attribute per T-3 gate discipline), reconciled through both `window.__notificationFetches` and the server-side request log. Fourth blueprint on the shelf that ships a Playwright probe pack under the T-0 runner extension.
+- Ships a sample-app fixture at `packages/rcf-lite/test/fixtures/probe-pack-application-notifications-in-app/` (dependency-free Node HTTP server) so the pack can be probed at the shelf's own gate; the fixture is the golden the gate reviewer drives, with `?break=preseed`, `?break=role`, `?break=timeout` and `?break=ack` query switches for the negative runs. Three routes (`/`, `/notifications-centre`, `/notifications-preferences`); every route preseeds both live-region wrappers.
+- Suggests the `logging` and `errorHandling` companions with the ratified spec's reasons. `providesRoles` absent, leaf blueprint per the loader contract (an empty array is refused, an omitted field marks the blueprint as a leaf).

package/blueprints/application-notifications-in-app/README.md

@@ -0,0 +1,80 @@
+# Notifications in-app blueprint (v1.0.0)
+
+Vendor-neutral in-app-notifications contract for a rcf-lite application. Ships the live-region preseeding discipline (polite and assertive wrappers present in the DOM before any notification fires per the WAI-ARIA 1.2 normative reference), the transient toast contract with priority-to-role mapping (info to polite/status, error to assertive/alert per WCAG 4.1.3 and the ARIA APG alert pattern), the WCAG 2.2.1 six-second toast timeout floor with operator-elicited overrides above the floor, the notification centre inbox with a thirty-day retention window and a per-item acknowledge round-trip enumerated by `data-notification-id`, the per-user preferences UI with category silence and sibling-channel digest delegation, and the delivery-attempt log write path. Ships a Playwright probe pack under `probe-packs/application-notifications-in-app.pack.mjs` whose three checks are the runtime gate the delivery-ci-workflows runner drives (visual round spec 2026-09-04, section 5.4). No new global topics; suggests the `logging` and `errorHandling` companions. Fourth blueprint on the shelf that ships a Playwright probe pack under the T-0 runner extension.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/application-notifications-in-app
+```
+
+Applies namespaced contributions into the project tree and records `manifest.blueprints[]`. Consumes the `logging` and `errorHandling` companions when they resolve to an applied provider or a registered library; falls back to the shelf providers otherwise.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version 1.0.0, category `application`, `suggestedCompanions: [{ logging }, { errorHandling }]`, `providesRoles` absent (leaf blueprint), 19 contributions in the 20xxx US band and 21xx ADR/TAC block |
+| Doc set | `contributions/` | 5 REQs, 8 USs, 3 TACs, 3 ADRs, schema-valid and namespaced |
+| Probe pack | `probe-packs/application-notifications-in-app.pack.mjs` | Three browser-verify checks anchored to blueprint AC ids: `AC-20101-1` live-region preseeding on every declared route (wrappers present AND empty at load); `AC-20102-1` transient toast contract with priority-to-role mapping and timeout measured against the ADR-2102 floor via `data-shown-at`/`data-dismissed-at`; `AC-20103-1` centre acknowledge round-trip enumerated by `data-notification-id` |
+| Guide | `guide/application-notifications-in-app.md` | Operator-facing: when to reach, when not, mechanism-reach gaps |
+| Coordination vocabulary | `docs/topics.md` | Shelf id band registry update; no new global topics claimed; the family-prefix reservation row |
+
+## What it contributes, and what it deliberately does not
+
+Contributed: REQ, US (with inline ACs), TAC, ADR, plus one shipped probe pack. Adherence is expressed as ACs; the blueprint ships no notifications-framework source and no test files (the probe pack drives the real browser against the applying project's own runtime).
+
+Deliberately not contributed: any transport (email, push, webhook). The in-app slug is the discriminator per Baz decision 2026-09-04: "we might support more types of notifications - be clear in the name what these ones are". Sibling channel blueprints ship their own transport contracts under the reserved `application-notifications-` family prefix.
+
+## Family-prefix reservation
+
+The `application-notifications-` prefix is reserved for the sibling in-app-adjacent channels the shelf will grow into:
+
+- `application-notifications-email`: server-to-user notifications through the applied `email-smtp-resend` companion (or a paired email provider). Owns the email-transport dedupe semantics and the delivery-attempt log rows for the email channel.
+- `application-notifications-push`: Web Push and platform APN/FCM notifications. Owns the subscription lifecycle and the platform-token store.
+- `application-notifications-webhook`: outbound HTTP notifications to operator-configured endpoints. Owns the delivery-retry semantics and the endpoint registry.
+
+The reservation is doc-only in v1.0.0 (per spec Q3 default): the family prefix is named in this README and in every shipped blueprint's `docs/topics.md` shelf band registry as a reserved-slot row. No sibling channel ships in this round. Any future PR that proposes a name outside the family (`application-alerts-email`, `application-messages-push`) reads against this reservation and stops at author-side review.
+
+Digest opt-in on the preferences UI is elicited on the sibling channel, not here: the preferences UI carries a disabled section per sibling channel that is not yet applied, labelled `data-preference-status="sibling not applied"`. When the sibling ships and the applying project applies it, that sibling's own blueprint reads the operator's preference state and drives the digest transport.
+
+## Quality bar
+
+Every route the applying project ships renders with both live-region wrappers preseeded in the DOM before any notification fires (`[aria-live="polite"] [data-live-region="polite"]` and `[role="alert"] [data-live-region="assertive"]`), both empty at page load. Every toast writes into exactly one wrapper based on its priority (info to polite as `role="status"`, error to assertive as `role="alert"`) and records `data-shown-at` and `data-dismissed-at` timestamps a probe can measure the timeout against without sleeping in the pack. Every toast timeout is at or above the WCAG 2.2.1 six-second floor. The notification centre lists notifications inside the ADR-2103 retention window, every item enumerated by `data-notification-id`, every acknowledge control Tab-reachable and round-tripping to `POST /api/notifications/acknowledge` with the DOM updating on the response.
+
+## Known mechanism-reach gaps
+
+Every runtime-observable AC that is not bound to a pack check appears here individually per the T-1 gate discipline (`blueprint-authoring-checklist.md` section 6.g): categories are not enough. The pack has three checks; every other runtime-observable AC on this blueprint is a mechanism-reach gap named below.
+
+- **AC-20101-2 live-region factory identity stable across route changes**. The pack asserts the wrappers are preseeded on every declared route (AC-20101-1); it does not assert the two wrappers are the same DOM nodes across route changes (a factory that recreates the wrappers on route change passes AC-20101-1 but fails AC-20101-2). A v1.1 minor bump could persist a `data-live-region-id` on each wrapper and assert identity across a `browser.click` on a nav link.
+- **AC-20102-2 toast factory library-scope shape**. The pack drives the runtime toast surface (AC-20102-1); the library-scope AC on the factory's own signature is a project-side review concern.
+- **AC-20103-2 centre factory reads through the delivery-log endpoint**. The pack drives the item enumeration and the acknowledge round-trip (AC-20103-1); the library-scope AC on the factory's own delivery-log read is a project-side review concern.
+- **AC-20104-1 preferences category silence**. The preferences surface renders per-category toggles but the pack does not itself activate a silence toggle and assert the round-trip today. A v1.1 minor bump could add a preferences-round-trip check paralleling AC-20103-1.
+- **AC-20104-2 sibling-channel digest section disabled when no sibling applied**. The fixture renders the disabled sections and the pack could inspect them, but the AC's real bite is when a sibling channel ships and the disabled state must lift; this class stays a v1.1 minor bump candidate for when the first sibling ships.
+- **AC-20105-1 delivery-log endpoint shape**. The pack does not enumerate every row on the log (the delivery-log's persistence is delegated to the applied `logging` companion). A v1.1 minor bump could add a log-shape probe that reads `/api/delivery-log`, asserts the row shape and confirms append-only order.
+- **AC-20105-2 delivery-log writes through the applied logging companion factory**. The pack does not inspect the companion's factory today. A v1.1 minor bump could add a companion-boundary check reading a marker the applying project stamps on companion-authored rows.
+- **AC-20106-1 page load with backlog does not saturate the polite queue**. The pack does not itself count polite-queue emissions at load. A v1.1 minor bump could add a MutationObserver-based check that counts inserts into the polite wrapper during the first render tick.
+- **AC-20107-1 background event indistinguishable from operator-driven event**. The pack fires the operator-driven variant (AC-20102-1); a background-event dispatch through `POST /__emit` on the fixture would exercise the same code path and reach the same DOM shape.
+- **AC-20108-1 disjoint content between wrappers**. The pack asserts the disjoint-content rule at the moment it inspects the wrappers, not continuously across the toast lifetime. TAC-2101 notes name this residual; a v1.1 minor bump could add a MutationObserver-based check.
+- **AC-2101-6 family-prefix reservation is documented on the shelf**. This is a doc-observable AC (the reservation paragraph exists in this README and the shelf registry rows). Not runtime-observable; not a mechanism-reach gap in the same sense but named for completeness.
+
+## Elicited parameters (ADR-2101 through ADR-2103 and REQ notes)
+
+The applying project elicits these at apply; the declarative ADR shape (`elicited: true`) records the intent on the manifest. The runner has no apply-time elicitation phase today (w-2026-09-04-dave-022, built in T-5); accept the declarative shape and gather the operator's answers by hand during the apply pass.
+
+- **Toast timeout floor** (ADR-2102): six seconds baseline per WCAG 2.2.1; operator elicits an override above the floor (twelve seconds, thirty seconds); the elicited value lands on `manifest.blueprints[application-notifications-in-app].appliedParameters.toastTimeoutSeconds`. A value below six is refused at apply.
+- **Notification categories** (REQ-004): the operator's category list (payment, security, product, and any project-specific categories). The preferences UI renders one section per elicited category.
+- **Centre retention window** (ADR-2103): thirty days by default; operator elicits an override. Below one day refused at apply.
+- **Notification centre route path** (REQ-003 note): `/notifications-centre` by default; operator elicits an override for a bespoke route.
+- **Digest transports** (REQ-004 note): elicited on the sibling channel blueprint at its apply, not here. This blueprint ships the preferences UI's disabled sibling section only.
+
+## Standards trace
+
+WCAG 4.1.3 Status Messages on the live-region contract (REQ-001, ADR-2101). ARIA APG alert pattern on the assertive slot (ADR-2101). WCAG 2.2.1 Timing Adjustable on the toast timeout floor (ADR-2102). WAI-ARIA 1.2 live regions normative reference (Sara Soueidan's guidance is the shipped project-side citation on the preseeding contract; the standards trace holds against the WAI-ARIA specification directly). `standardsTraceClause` on each ADR carries the primary clause or pattern id.
+
+## Consumers and dependencies
+
+- Consumes the applied `logging` companion (or the shelf provider `observability-logging`) for the delivery-attempt log write path (REQ-005, TAC-2102) and every acknowledge round-trip record. A project without a `logging` companion applied sees the delivery-log endpoint returning an empty rows array, which fails project-side review.
+- Consumes the applied `errorHandling` companion (or the shelf provider `application-error-handling`) for the assertive-slot alert's internal error record when an acknowledge round-trip fails at the server.
+- Reserves the `application-notifications-` family prefix for sibling channel blueprints (see above).
+- Reuses the T-3 pack-browser `resize(width, height)` seam only for future minor bumps; v1.0.0 does not exercise breakpoint reflow in the pack.

package/blueprints/application-notifications-in-app/blueprint.json

@@ -0,0 +1,30 @@
+{
+  "slug": "application-notifications-in-app",
+  "version": "1.0.0",
+  "category": "application",
+  "suggestedCompanions": [
+    { "role": "logging", "reason": "Every acknowledge round-trip and every delivery-attempt row is written through the applied logger; a logging companion supplies the factory the notification centre, the toast surface and the delivery-attempt log write records against." },
+    { "role": "errorHandling", "reason": "The assertive-slot alert routes an internal error record whose error envelope conforms to the applied error contract; an errorHandling companion supplies the record factory and the surface boundary the alert toast renders through." }
+  ],
+  "contributions": [
+    { "id": "application-notifications-in-app-REQ-001", "kind": "req", "path": "requirements/application-notifications-in-app-req-001.json" },
+    { "id": "application-notifications-in-app-REQ-002", "kind": "req", "path": "requirements/application-notifications-in-app-req-002.json" },
+    { "id": "application-notifications-in-app-REQ-003", "kind": "req", "path": "requirements/application-notifications-in-app-req-003.json" },
+    { "id": "application-notifications-in-app-REQ-004", "kind": "req", "path": "requirements/application-notifications-in-app-req-004.json" },
+    { "id": "application-notifications-in-app-REQ-005", "kind": "req", "path": "requirements/application-notifications-in-app-req-005.json" },
+    { "id": "application-notifications-in-app-US-20101", "kind": "us", "path": "user-stories/application-notifications-in-app-us-20101.json" },
+    { "id": "application-notifications-in-app-US-20102", "kind": "us", "path": "user-stories/application-notifications-in-app-us-20102.json" },
+    { "id": "application-notifications-in-app-US-20103", "kind": "us", "path": "user-stories/application-notifications-in-app-us-20103.json" },
+    { "id": "application-notifications-in-app-US-20104", "kind": "us", "path": "user-stories/application-notifications-in-app-us-20104.json" },
+    { "id": "application-notifications-in-app-US-20105", "kind": "us", "path": "user-stories/application-notifications-in-app-us-20105.json" },
+    { "id": "application-notifications-in-app-US-20106", "kind": "us", "path": "user-stories/application-notifications-in-app-us-20106.json" },
+    { "id": "application-notifications-in-app-US-20107", "kind": "us", "path": "user-stories/application-notifications-in-app-us-20107.json" },
+    { "id": "application-notifications-in-app-US-20108", "kind": "us", "path": "user-stories/application-notifications-in-app-us-20108.json" },
+    { "id": "TAC-2101-application-notifications-in-app-live-region", "kind": "tac", "path": "tacs/tac-2101-application-notifications-in-app-live-region.json" },
+    { "id": "TAC-2102-application-notifications-in-app-centre", "kind": "tac", "path": "tacs/tac-2102-application-notifications-in-app-centre.json" },
+    { "id": "TAC-2103-application-notifications-in-app-preferences", "kind": "tac", "path": "tacs/tac-2103-application-notifications-in-app-preferences.json" },
+    { "id": "ADR-2101-application-notifications-in-app-live-region-role-mapping", "kind": "adr", "path": "adrs/adr-2101-application-notifications-in-app-live-region-role-mapping.json", "recommendedDefault": true, "elicited": false, "standardsTraceClause": "WCAG 4.1.3 (Status Messages); ARIA APG alert pattern" },
+    { "id": "ADR-2102-application-notifications-in-app-toast-timeout-floor", "kind": "adr", "path": "adrs/adr-2102-application-notifications-in-app-toast-timeout-floor.json", "recommendedDefault": true, "elicited": true, "standardsTraceClause": "WCAG 2.2.1 (Timing Adjustable)" },
+    { "id": "ADR-2103-application-notifications-in-app-retention-window", "kind": "adr", "path": "adrs/adr-2103-application-notifications-in-app-retention-window.json", "recommendedDefault": true, "elicited": true, "standardsTraceClause": "generic enterprise practice" }
+  ]
+}