rcf-lite 0.20.0 → 0.22.0

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

@@ -0,0 +1,35 @@
+{
+  "usId": "application-dashboard-US-19101",
+  "prdId": "PRD-001",
+  "reqId": "application-dashboard-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The dashboard shell renders the five required regions on every shipped surface",
+  "asA": "product owner responsible for the shipped dashboard surface",
+  "iWant": "the shell to render a tile row, a chart region, filter chrome, a timeframe picker and an export handle on every dashboard surface",
+  "soThat": "every REQ, TAC and pack check on this blueprint anchors onto a stable, inspectable shell structure rather than a floating layout convention",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-19101-1",
+      "description": "Given a rendered dashboard surface, the DOM carries five labelled `role=\"region\"` elements naming (via `aria-label` or an in-region `<h2>` header) the tile row, the chart region, the filter chrome, the timeframe picker and the export handle. A surface that omits one of the five regions either renders the region as an empty labelled `role=\"region\"` element the pack can inspect or supersedes REQ-001 with a project-authored REQ documenting the omission.",
+      "given": "a rendered dashboard surface",
+      "when": "the accessibility tree is read",
+      "then": "five labelled regions cover the tile row, the chart region, the filter chrome, the timeframe picker and the export handle",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "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.",
+      "given": "the rendered chart region",
+      "when": "the mount seam is inspected",
+      "then": "the chart mounts through the application-charts render shell",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": ["TAC-2001-application-dashboard-tile-grid"],
+  "tags": ["blueprint:application-dashboard"],
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

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

@@ -0,0 +1,35 @@
+{
+  "usId": "application-dashboard-US-19102",
+  "prdId": "PRD-001",
+  "reqId": "application-dashboard-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The primary KPI tile sits top-left in DOM order and in CSS Grid position across the ratified breakpoints",
+  "asA": "reader glancing at the shipped dashboard on a laptop, a tablet and a phone",
+  "iWant": "the primary KPI to land at the top-left first-fixation position on every ratified breakpoint",
+  "soThat": "the F-scan reading pattern lands on the primary KPI first, without a per-surface layout negotiation",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-19102-1",
+      "description": "Given a rendered dashboard surface at each of the three ratified viewports (1440, 1024, 360), the primary KPI tile (`data-tile-role=\"primary-kpi\"`) is the first tile in DOM order within the tile row region; at 1440 and 1024 the tile's computed CSS Grid `grid-column-start` is 1 and `grid-row-start` is 1; at 360 the tile row reflows to one column and the primary KPI's `grid-row-start` is 1 (the top row). The tile carries a `data-kpi-kind` attribute whose value is one of the ADR-2001 enum (revenue, active-users, error-rate, throughput, custom). Probed by the application-dashboard pack check AC-19102-1 (Playwright drives the browser to the dashboard route, resizes the viewport to each of the three widths, reads the DOM order and the computed CSS Grid position, and asserts every breakpoint places the primary KPI top-left).",
+      "given": "a rendered dashboard surface at 1440, 1024 and 360",
+      "when": "the DOM order and the computed CSS Grid position are read",
+      "then": "the primary KPI tile is first in DOM order and top-left in CSS Grid at each of the three widths",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "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.",
+      "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",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": ["TAC-2001-application-dashboard-tile-grid"],
+  "tags": ["blueprint:application-dashboard"],
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

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

@@ -0,0 +1,35 @@
+{
+  "usId": "application-dashboard-US-19103",
+  "prdId": "PRD-001",
+  "reqId": "application-dashboard-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every tile honours the four-state contract with distinct visuals, role region, aria-live polite and non-colour distinction",
+  "asA": "screen-reader user and colour-blind reader on the shipped dashboard",
+  "iWant": "every tile state (loading, empty, error, populated) to carry a distinct visual, a labelled region, an aria-live polite announcer and a non-colour distinction",
+  "soThat": "the tile's current state is reachable regardless of assistive tech and legible regardless of colour perception",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-19103-1",
+      "description": "Given a rendered tile in each of the four states (loading, empty, error, populated), the tile wraps its content in a `role=\"region\"` element carrying `aria-live=\"polite\"` and a labelled state descriptor (`data-tile-state=\"<state>\"`). The state's visual cue is not colour-only: loading carries a skeleton stripe or spinner element, empty carries a labelled empty-state block, error carries a labelled error block with the recorded reason, populated carries the metric value. Every state exposes its accessible name as `<tile title>, <state>` on the wrapping region. Probed by the application-dashboard pack check AC-19103-1 (Playwright drives to `?tile=<id>&state=<state>` for each of the four states on each of two tiles, reads the accessibility tree and the DOM, and asserts every state carries the role region, the aria-live polite, the data-tile-state attribute, and a non-colour visual cue).",
+      "given": "a tile switched into each of the four states",
+      "when": "the DOM and the accessibility tree are read",
+      "then": "each state carries role region, aria-live polite, data-tile-state, a non-colour visual cue and the announced name",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "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.",
+      "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",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2001-application-dashboard-tile-grid"],
+  "tags": ["blueprint:application-dashboard"],
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

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

@@ -0,0 +1,35 @@
+{
+  "usId": "application-dashboard-US-19104",
+  "prdId": "PRD-001",
+  "reqId": "application-dashboard-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A timeframe preset change refetches every tile and chart with the same boundary and updates the as-of stamp",
+  "asA": "operator changing the dashboard timeframe from last-7-days to last-30-days",
+  "iWant": "every tile and chart to refetch with the same from and to boundary and the same preset name",
+  "soThat": "the shell renders a coherent snapshot at one boundary and the as-of stamp reads the same on every tile",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-19104-1",
+      "description": "Given a rendered dashboard surface and an operator-driven timeframe preset change (click a preset control, or select a value from a timeframe menu), one refetch fires per tile and one per rendered chart; every fetch carries the same `from` boundary, the same `to` boundary and the same `preset` name in its query string; once every fetch has returned (or the timeout has elapsed) the shell updates one `data-as-of` attribute on the shell root and every tile carries the same `data-as-of` value in ISO-8601 form. Probed by the application-dashboard pack check AC-19104-1 (Playwright drives to the dashboard route, waits for the initial fetch batch, clicks the second preset control, waits for the new batch, reads the request log from `window.__dashboardFetches` and from `GET /__requests`, and asserts every fetch in the new batch carries the same from/to/preset trio and every tile carries the same `data-as-of` matching the shell root).",
+      "given": "a rendered dashboard surface and a timeframe preset change",
+      "when": "the request log and the DOM are read",
+      "then": "every refetch carries the same from/to/preset and every tile's data-as-of matches the shell root",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "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.",
+      "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",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2002-application-dashboard-filter-chrome"],
+  "tags": ["blueprint:application-dashboard"],
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

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

@@ -0,0 +1,35 @@
+{
+  "usId": "application-dashboard-US-19105",
+  "prdId": "PRD-001",
+  "reqId": "application-dashboard-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The filter chrome exposes accessible controls and refetches every tile with the same boundary",
+  "asA": "operator narrowing the dashboard with a filter chip or a filter input",
+  "iWant": "the filter chrome to expose accessible controls that carry the operator's choice to every fetch and refetch every tile with the same boundary",
+  "soThat": "the shell renders a filtered view at one boundary without drifting between tiles",
+  "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.",
+      "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",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-19105-2",
+      "description": "Given an operator-driven filter change (activate a filter chip, type into a filter input), the shell issues one refetch per tile and one per rendered chart with the same `filter` query parameter set applied to every fetch; the shell's `data-active-filters` attribute updates on the same paint as the refetch batch. This AC is a runtime-observable fan-out clause; the pack asserts the fetch fan-out on the timeframe seam (AC-19104-1) which the fixture drives; the filter fan-out is a mechanism-reach gap the README names for a v1.1 minor bump.",
+      "given": "a rendered dashboard and a filter change",
+      "when": "the request log is read",
+      "then": "every refetch carries the same active-filters set and the shell attribute updates",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2002-application-dashboard-filter-chrome"],
+  "tags": ["blueprint:application-dashboard"],
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

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

@@ -0,0 +1,35 @@
+{
+  "usId": "application-dashboard-US-19106",
+  "prdId": "PRD-001",
+  "reqId": "application-dashboard-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The export handle exposes an accessible format list and delegates PNG-of-chart to the application-charts render shell",
+  "asA": "operator downloading the current dashboard slice",
+  "iWant": "an accessible export handle listing the available formats and delegating PNG-of-chart to the charts render shell",
+  "soThat": "export is keyboard-reachable, the format choice is explicit and the PNG output stays consistent with the rendered chart",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-19106-1",
+      "description": "Given a rendered dashboard surface, the export handle region contains one labelled `<button>` (accessible name reads `Export` or an operator-configured equivalent) that on activation exposes a keyboard-reachable list of formats (a menu, a listbox or a set of `<button>` elements). The rendered format list carries at least the three shipped formats (CSV, PDF, PNG-of-chart) unless ADR-2003's elicited override replaces the set; every format entry carries a `data-export-format` attribute whose value is one of `csv`, `pdf`, `png-chart` or the elicited value. Escape closes the list and returns focus to the export button. Hover-only export dropdowns fail project-side review.",
+      "given": "a rendered dashboard with an export handle",
+      "when": "the operator activates the export button",
+      "then": "an accessible format list opens with the shipped formats, keyboard-reachable, closable on Escape",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-19106-2",
+      "description": "Given a PNG-of-chart export selection, the export handle delegates the PNG generation to the application-charts render shell (TAC-1901): the handle names the chart the operator picked from the chart region (a `data-chart-id` reference on the format entry, or a runtime prompt asking which chart) and the charts shell owns the PNG output. A dashboard shell that ships its own PNG generator inside the dashboard code fails project-side review. This AC is a project-side contract; the pack does not exercise the PNG generation today (no download-capture seam on the pack browser), and the README names the delegation-observation gap under known mechanism-reach gaps.",
+      "given": "a PNG-of-chart export selection",
+      "when": "the export handle activates",
+      "then": "PNG generation delegates to the application-charts render shell",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": ["TAC-2003-application-dashboard-export-handle"],
+  "tags": ["blueprint:application-dashboard"],
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

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

@@ -0,0 +1,35 @@
+{
+  "usId": "application-dashboard-US-19107",
+  "prdId": "PRD-001",
+  "reqId": "application-dashboard-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The applying agent reads the packaged design-guidance asset and honours its ratified surface rules",
+  "asA": "agent applying the application-dashboard blueprint on a shipped surface",
+  "iWant": "a packaged design-guidance asset shipped with the blueprint that names what a good dashboard looks like",
+  "soThat": "the operator-facing design choices (primary KPI kind, tile count, when a table beats a chart, refresh cadence, anti-patterns) are documented in one place I read at apply time",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-19107-1",
+      "description": "The blueprint ships an operator-and-agent-readable design-guidance file at `assets/guidance/dashboard-design.md` covering the eight sections named in spec 5.3.1 (primary KPI placement; tile density and count limits; timeframe and filter chrome; loading, empty and error states; colour and contrast; when a table beats a chart, delegating to application-datatable; refresh cadence and staleness; anti-patterns). Each section names whether the rule hardens into an AC on this blueprint (the section names the AC id) or stays operator guidance the applying agent honours at project-side review. The file cites at least five https:// sources from the five named source families (NN/g dashboard design, Few, Tufte, GOV.UK Design System patterns, WCAG 2.2 Understanding docs).",
+      "given": "the shipped blueprint",
+      "when": "the applying agent reads assets/guidance/dashboard-design.md",
+      "then": "the eight sections and the five https citations are present and each section names AC or guidance",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-19107-2",
+      "description": "The dashboard shell's runtime shape reflects the rules the guidance hardens into ACs: the primary-KPI kind is one of the ADR-2001 enum values (asserted through `data-kpi-kind` on the primary tile; guidance section 1 hardens into AC-19102-1); the shell renders an `as of <ISO-8601>` stamp (guidance section 7 hardens into AC-19104-1); auto-refresh is off unless the elicited interval is set (guidance section 7 hardens into AC-19104-2). A shipped surface that violates any of these rules fails the corresponding pack check or project-side review.",
+      "given": "a rendered dashboard shell",
+      "when": "the shell is inspected against the guidance's hardened rules",
+      "then": "the shape honours the primary-KPI kind, the as-of stamp and the auto-refresh default",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2001-application-dashboard-tile-grid"],
+  "tags": ["blueprint:application-dashboard"],
+  "createdAt": "2026-09-04T22:10:00Z",
+  "updatedAt": "2026-09-04T22:10:00Z"
+}

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

@@ -0,0 +1,50 @@
+# application-dashboard: coordination vocabulary
+
+## Global topics
+
+The blueprint claims no new global topics at v1.0.0. The dashboard-shell contract is a composed application shape; every ADR (primary-KPI kinds, timeframe presets, export formats) is non-global.
+
+## Deliberately unclaimed topics
+
+- `dashboardShell` (the shell composition itself). Not a global topic; a second dashboard-shaped blueprint would either share TAC-2001 or supersede this blueprint.
+- `kpiKind` (the primary-KPI kind enum). Reserved for the applying project as an elicited choice, not a global topic; a second dashboard-shaped blueprint that composes with a different enum would either supersede this blueprint or share the ADR.
+- `refreshCadence` (the timeframe fan-out contract). The application-charts blueprint's ADR-1903 owns the reduced-motion posture; the dashboard's ADR-2002 owns the auto-refresh default. Neither is a global topic; a future observability-adjacent blueprint that composes on refresh cadence would claim its own.
+
+## 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-dashboard.pack.mjs` ships three checks anchored to blueprint AC ids:
+
+- `AC-19102-1` primary-KPI position by DOM order and CSS Grid position at 1440, 1024 and 360
+- `AC-19104-1` timeframe refetch fan-out with matching boundary and as-of stamp
+- `AC-19103-1` per-tile four-state contract with role region, aria-live polite and non-colour distinction
+
+Every check carries a `description` field per spec section 9. `appliesTo` binds `TAC-2001-application-dashboard-tile-grid` OR any FBS route matching an operator-configured dashboard-route glob. See `probe-packs/application-dashboard.pack.mjs` for the source; see `packages/rcf-lite/test/fixtures/probe-pack-application-dashboard/README.md` for the sample-app fixture and the negative-run break switches.
+
+## Packaged design guidance
+
+`assets/guidance/dashboard-design.md` is a shipped operator-and-agent-readable asset covering eight sections (primary KPI placement; tile density and count limits; timeframe and filter chrome; loading, empty and error states; colour and contrast; when a table beats a chart, delegating to application-datatable; refresh cadence and staleness; anti-patterns) with five https-cited sources (NN/g dashboard design, Few, Tufte, GOV.UK Design System patterns, WCAG 2.2 Understanding docs). Each section names whether the rule hardens into an AC on this blueprint or stays operator guidance.
+
+## Consumers and dependencies
+
+- Consumes `application-charts` (visual round T-2): the chart region on every dashboard surface mounts through the application-charts render shell (TAC-1901). The dashboard pack does not duplicate the chart-accessibility ACs; the charts pack fires on the dashboard's chart route through its own applicability predicate.
+- References `application-datatable` (visual round T-1) in the packaged design guidance's section 6 ("when a table beats a chart"). A dashboard whose data really wants a records table applies the datatable blueprint instead of overloading the tile row.
+- Extends the T-0 pack-browser seam with a `resize(width, height)` method; every blueprint after this one that ships a breakpoint-scoped visual AC reuses the seam.

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

@@ -0,0 +1,48 @@
+# Guide: application-dashboard (v1.0.0)
+
+## What it is
+
+A shipped, vendor-neutral analytics-dashboard contract for a rcf-lite application. One tile grid with primary-KPI hierarchy at the ratified breakpoints (TAC-2001), one timeframe picker and filter chrome with a refetch fan-out contract (TAC-2002), one export handle with format delegation to charts (TAC-2003), a packaged design-guidance asset the applying agent reads at apply, and a shipped Playwright probe pack that gates ship on the three runtime-observable surfaces the shelf assures: the primary KPI sits top-left at every ratified breakpoint, a timeframe change refetches every tile with the same boundary and one as-of stamp, and every tile honours the four-state contract with role region, aria-live polite and non-colour distinction.
+
+## What it deliberately is not
+
+- Not a dashboard framework. The shell is a contract; the applying project picks React, Vue, Svelte or hand-authored DOM and writes the mount function against the same DOM contract.
+- Not a chart library. The chart region delegates rendering to the application-charts render shell (TAC-1901); the shell contract and the accessibility ACs on that blueprint apply.
+- Not a records table. When the reader wants to sort, filter, page, select or export a list of records, ship the application-datatable blueprint's table; the tile row is not a replacement.
+- Not a data-source contract. The applying application-api-rest blueprint owns the wire endpoint; the dashboard shell reads the data it is given.
+
+## When to reach for it
+
+- Any shipped surface that renders a mix of stat tiles and one or more charts with a shared timeframe control. Analytics dashboards, admin overview surfaces, per-organisation summary views, ops screens.
+- Projects that want the primary-KPI-hierarchy discipline enforced at ship without hand-authoring per surface.
+- Any project that already applies application-charts and needs the composed dashboard shape on top.
+
+## When it does not fit
+
+- Print-only or export-only dashboard output where the runtime accessibility contract does not apply. A weekly PDF report pipeline is a separate concern.
+- Highly bespoke dashboards outside the tile-row-plus-chart-region shape (a network-topology dashboard, a physical-space dashboard). Those supersede the blueprint with a project-authored shell contract naming the residuals.
+- A dashboard that is really a records table with a header row. Apply application-datatable instead.
+
+## What a good outcome looks like
+
+Every dashboard surface renders the five labelled regions. The primary KPI tile sits top-left in DOM order and top-left in CSS Grid at 1440, 1024 and 360. Every tile carries the four-state contract with a role region wrapper, an aria-live polite announcer and a non-colour visual cue distinct per state. A timeframe preset change fans out one refetch per tile with the same boundary, and the shell renders one shared as-of stamp every tile inherits. The export handle is a labelled button opening a keyboard-reachable format list; PNG-of-chart delegates to the application-charts render shell. Auto-refresh is off unless the operator elicited an interval. The shipped probe pack runs green on the delivery-ci-workflows gate.
+
+## The operator decisions that remain open
+
+- **Primary-KPI kind** (ADR-2001). One of revenue, active-users, error-rate, throughput, custom. A `custom` value carries a short operator name.
+- **Timeframe presets and auto-refresh** (ADR-2002). Three presets by recommendedDefault; operator elicits an override. Auto-refresh off unless the operator elicits an interval.
+- **Export formats** (ADR-2003). Three formats by recommendedDefault (CSV, PDF, PNG-of-chart); operator elicits an override.
+- **Tile inventory and slots**. The full tile list and each tile's CSS Grid slot.
+- **Boundary scope**. Per-user, per-organisation or global; carried on every fetch record.
+
+## Common gotchas
+
+- The primary KPI is a fixed enum (five values plus `custom` with a name). A free-form `data-kpi-kind` is refused at project-side review.
+- The as-of stamp lives on the shell root and every tile carries the same value. A tile whose stamp drifts is a defect.
+- Auto-refresh is off unless the operator opted in with an interval. A dashboard that refreshes every 30 seconds without an opt-in is a common accessibility and cost defect.
+- The export handle carries no PNG generator of its own. PNG-of-chart delegates to the application-charts render shell; a project that ships a chart engine outside the render shell either supersedes the delegation or loses the PNG affordance.
+- The pack fires on any FBS whose surface matches the `appliesTo` predicate. A page with no dashboard shape declares no dashboard route and no tile-grid TAC binding; the pack records `applicable: false`.
+
+## Cost honesty
+
+Shipping this blueprint costs the project a design pass on the tile inventory (which tile is the primary KPI, how many supporting tiles) and an operator conversation on the timeframe and export sets. It buys the accessibility contract on every tile, the fan-out contract on every timeframe change, the packaged design guidance the applying agent reads at apply, and the probe pack that refuses ship on a broken tile grid or a drifted fan-out. The gate reviewer verifies the pack runs green against the sample-app fixture and reviews the applying project's own dashboard surface against the packaged guidance's eight sections.

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

@@ -0,0 +1,231 @@
+// application-dashboard probe pack (v1.0.0).
+//
+// Three runtime-observable checks anchored to the blueprint's ACs:
+//   AC-19102-1 primary-KPI position (DOM order and CSS Grid position at 1440, 1024 and 360)
+//   AC-19104-1 timeframe refetch fan-out (every fetch same from/to/preset, matching as-of stamp)
+//   AC-19103-1 per-tile four-state contract (role region, aria-live polite, non-colour distinction)
+//
+// Every check drives the real Playwright browser the T-0 runner
+// injects (packages/rcf-lite/src/browser-verify/pack-browser.js) and
+// asserts on the DOM the applying project renders under the tile
+// grid TAC (TAC-2001), the fan-out contract TAC (TAC-2002) and the
+// four-state contract on every tile.
+//
+// The runner has no network-interception seam today, so fan-out
+// evidence is captured through a request log the sample app exposes
+// on `window.__dashboardFetches` and at `GET /__requests`; the pack
+// reads both to reconcile the timeframe-preset refetch batch.
+//
+// The runner exposes viewport resize through pack-browser's
+// `resize(width, height)` seam (T-3 extension): the primary-KPI
+// position check drives 1440, 1024 and 360 through the same handle.
+
+export default {
+  packName: 'application-dashboard',
+  version: '1.0.0',
+  blueprintSlug: 'application-dashboard',
+  // Applies to any FBS that realises the dashboard tile-grid TAC or
+  // whose navModel routes match an operator-configured dashboard
+  // route glob. The source references BOTH `tacIds` and `route` so
+  // the T-0 loader's applicability source-scan sees the two legal
+  // seams (route is one of the three legal predicates).
+  appliesTo: ({ fbs }) => {
+    const routes = fbs?.designStage?.navModel?.routes ?? [];
+    const tacIds = fbs?.contextRequirements?.tacIds ?? [];
+    if (tacIds.includes('TAC-2001-application-dashboard-tile-grid')) return true;
+    return routes.some((r) => typeof r?.path === 'string' && /dashboard/.test(r.path));
+  },
+  boot: { bootCommand: null, waitForUrl: null, waitForSelector: null },
+  checks: [
+    {
+      id: 'AC-19102-1',
+      severity: 'block',
+      description: 'Primary-KPI position: at 1440, 1024 and 360 the primary tile is first in DOM order within the tile row and lives at grid-column-start 1, grid-row-start 1 (at 360 the row-start is 1 after the one-column reflow)',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        if (typeof browser.resize !== 'function') {
+          return { verdict: 'fail', detail: 'packBrowser has no resize seam; the T-3 extension has not landed' };
+        }
+        const url = new URL('', runtimeUrl).toString();
+        const widths = [1440, 1024, 360];
+        const perWidth = [];
+        for (const width of widths) {
+          await browser.resize(width, 900);
+          await browser.goto(url);
+          const measurement = await browser.evaluate(() => {
+            const tileRow = document.querySelector('[data-region="tile-row"]');
+            if (!tileRow) return { error: 'no tile-row region' };
+            const tiles = Array.from(tileRow.querySelectorAll('[data-tile-id]'));
+            if (tiles.length === 0) return { error: 'tile row has no tiles' };
+            const primary = tiles.find((el) => el.getAttribute('data-tile-role') === 'primary-kpi');
+            if (!primary) return { error: 'no primary-kpi tile' };
+            const domIndex = tiles.indexOf(primary);
+            const style = window.getComputedStyle(primary);
+            const kpiKind = primary.getAttribute('data-kpi-kind');
+            const kpiName = primary.getAttribute('data-kpi-name');
+            return {
+              domIndex,
+              gridColumnStart: style.gridColumnStart,
+              gridRowStart: style.gridRowStart,
+              kpiKind,
+              kpiName,
+              tileCount: tiles.length,
+              tileIds: tiles.map((el) => el.getAttribute('data-tile-id')),
+              viewportWidth: window.innerWidth,
+            };
+          });
+          perWidth.push({ width, measurement });
+        }
+        const failures = perWidth.filter((r) => {
+          if (r.measurement.error) return true;
+          if (r.measurement.domIndex !== 0) return true;
+          if (r.measurement.gridRowStart !== '1') return true;
+          if (r.width === 1440 || r.width === 1024) {
+            if (r.measurement.gridColumnStart !== '1') return true;
+          }
+          return false;
+        });
+        if (failures.length > 0) {
+          return { verdict: 'fail', detail: 'primary-KPI position broke at: ' + JSON.stringify(failures) };
+        }
+        const enumValues = ['revenue', 'active-users', 'error-rate', 'throughput', 'custom'];
+        const kpiKind = perWidth[0].measurement.kpiKind;
+        if (!enumValues.includes(kpiKind)) {
+          return { verdict: 'fail', detail: 'primary-KPI data-kpi-kind not in ADR-2001 enum: ' + JSON.stringify(kpiKind) };
+        }
+        if (kpiKind === 'custom' && !perWidth[0].measurement.kpiName) {
+          return { verdict: 'fail', detail: 'primary-KPI kind is custom but data-kpi-name is missing' };
+        }
+        return { verdict: 'pass', detail: 'primary-KPI top-left at every breakpoint (tiles: ' + perWidth[0].measurement.tileCount + '): ' + JSON.stringify(perWidth.map((r) => ({ width: r.width, kind: r.measurement.kpiKind, domIndex: r.measurement.domIndex, gcs: r.measurement.gridColumnStart, grs: r.measurement.gridRowStart, tiles: r.measurement.tileCount }))) };
+      },
+    },
+    {
+      id: 'AC-19104-1',
+      severity: 'block',
+      description: 'Timeframe refetch fan-out: a preset change issues one refetch per tile and per chart with the same from/to/preset trio, and every tile updates data-as-of matching the shell root',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        const url = new URL('', runtimeUrl).toString();
+        await browser.resize(1440, 900);
+        await browser.goto(url);
+        const initial = await browser.evaluate(() => {
+          const preset = document.querySelector('[data-region="timeframe-picker"]');
+          const buttons = preset ? Array.from(preset.querySelectorAll('[data-preset]')) : [];
+          const initialPresets = buttons.map((b) => b.getAttribute('data-preset'));
+          return {
+            initialPresets,
+            initialFetches: (window.__dashboardFetches || []).slice(),
+            initialAsOf: document.querySelector('[data-region="shell-root"]')?.getAttribute('data-as-of') || null,
+          };
+        });
+        if (!initial.initialPresets || initial.initialPresets.length < 2) {
+          return { verdict: 'fail', detail: 'timeframe picker missing or has fewer than two presets: ' + JSON.stringify(initial.initialPresets) };
+        }
+        const target = initial.initialPresets.find((p) => p !== 'last-7-days') || initial.initialPresets[1];
+        await browser.click('[data-region="timeframe-picker"] [data-preset="' + target + '"]');
+        await browser.evaluate((preset) => new Promise((resolve) => {
+          const start = Date.now();
+          const check = () => {
+            const root = document.querySelector('[data-region="shell-root"]');
+            const currentPreset = root && root.getAttribute('data-current-preset');
+            const fetches = window.__dashboardFetches || [];
+            const last = fetches[fetches.length - 1];
+            if (currentPreset === preset && last && last.preset === preset) return resolve(true);
+            if (Date.now() - start > 5000) return resolve(false);
+            setTimeout(check, 40);
+          };
+          check();
+        }), target);
+        const evidence = await browser.evaluate((initialCount) => {
+          const root = document.querySelector('[data-region="shell-root"]');
+          const fetches = (window.__dashboardFetches || []).slice(initialCount);
+          const tileRow = document.querySelector('[data-region="tile-row"]');
+          const tiles = tileRow ? Array.from(tileRow.querySelectorAll('[data-tile-id]')) : [];
+          return {
+            fetches,
+            tileAsOfs: tiles.map((el) => ({ tileId: el.getAttribute('data-tile-id'), asOf: el.getAttribute('data-as-of') })),
+            shellAsOf: root ? root.getAttribute('data-as-of') : null,
+            shellPreset: root ? root.getAttribute('data-current-preset') : null,
+            targetPreset: root ? root.getAttribute('data-current-preset') : null,
+          };
+        }, initial.initialFetches.length);
+        try {
+          const requestsRes = await fetch(new URL('/__requests', runtimeUrl).toString());
+          if (requestsRes.status !== 200) {
+            return { verdict: 'fail', detail: '/__requests endpoint returned ' + requestsRes.status };
+          }
+          await requestsRes.json();
+        } catch (err) {
+          return { verdict: 'fail', detail: '/__requests endpoint unreachable: ' + err.message };
+        }
+        const newBatch = evidence.fetches;
+        if (newBatch.length === 0) {
+          return { verdict: 'fail', detail: 'no fetches recorded after timeframe change' };
+        }
+        const first = newBatch[0];
+        const drift = newBatch.filter((f) => f.from !== first.from || f.to !== first.to || f.preset !== first.preset);
+        if (drift.length > 0) {
+          return { verdict: 'fail', detail: 'fan-out drifted boundary or preset: ' + JSON.stringify({ first, drift }) };
+        }
+        if (!evidence.shellAsOf) {
+          return { verdict: 'fail', detail: 'shell root missing data-as-of after fan-out' };
+        }
+        const stampDrift = evidence.tileAsOfs.filter((t) => t.asOf !== evidence.shellAsOf);
+        if (stampDrift.length > 0) {
+          return { verdict: 'fail', detail: 'tile data-as-of drifted from shell: ' + JSON.stringify(stampDrift) };
+        }
+        const isoRe = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+        if (!isoRe.test(evidence.shellAsOf)) {
+          return { verdict: 'fail', detail: 'shell data-as-of not ISO-8601: ' + JSON.stringify(evidence.shellAsOf) };
+        }
+        return { verdict: 'pass', detail: 'timeframe fan-out coherent: ' + JSON.stringify({ preset: first.preset, from: first.from, to: first.to, fetches: newBatch.length, shellAsOf: evidence.shellAsOf, tiles: evidence.tileAsOfs.length }) };
+      },
+    },
+    {
+      id: 'AC-19103-1',
+      severity: 'block',
+      description: 'Per-tile four-state contract: every tile renders each of loading, empty, error and populated inside role region with aria-live polite, a data-tile-state attribute, and a non-colour visual cue distinct per state',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        const states = ['loading', 'empty', 'error', 'populated'];
+        const perState = [];
+        const url = new URL('', runtimeUrl).toString();
+        await browser.resize(1440, 900);
+        for (const state of states) {
+          const target = new URL('', runtimeUrl);
+          target.searchParams.set('tile', 'primary');
+          target.searchParams.set('state', state);
+          await browser.goto(target.toString());
+          const measurement = await browser.evaluate((expectedState) => {
+            const tile = document.querySelector('[data-tile-id="primary"]');
+            if (!tile) return { error: 'no primary tile' };
+            const region = tile.matches('[role="region"]') ? tile : tile.querySelector('[role="region"]');
+            if (!region) return { error: 'primary tile missing role=region wrapper' };
+            const ariaLive = region.getAttribute('aria-live');
+            const actualState = region.getAttribute('data-tile-state') || tile.getAttribute('data-tile-state');
+            const visualCue = tile.querySelector('[data-state-cue]');
+            const cueKind = visualCue ? visualCue.getAttribute('data-state-cue') : null;
+            const accessibleName = region.getAttribute('aria-label') || region.textContent.trim().slice(0, 120);
+            return { expectedState, actualState, ariaLive, cueKind, accessibleName, cueHasContent: Boolean(visualCue && visualCue.textContent.trim().length > 0) };
+          }, state);
+          perState.push({ state, measurement });
+        }
+        const failures = perState.filter((r) => {
+          if (r.measurement.error) return true;
+          if (r.measurement.ariaLive !== 'polite') return true;
+          if (r.measurement.actualState !== r.state) return true;
+          if (!r.measurement.cueKind || r.measurement.cueKind !== r.state) return true;
+          return false;
+        });
+        if (failures.length > 0) {
+          return { verdict: 'fail', detail: 'four-state contract broke on: ' + JSON.stringify(failures) };
+        }
+        const cueKinds = new Set(perState.map((r) => r.measurement.cueKind));
+        if (cueKinds.size !== states.length) {
+          return { verdict: 'fail', detail: 'state visual cues not distinct across states: ' + JSON.stringify(perState.map((r) => ({ state: r.state, cue: r.measurement.cueKind }))) };
+        }
+        return { verdict: 'pass', detail: 'four-state contract honoured across: ' + JSON.stringify(perState.map((r) => ({ state: r.state, cue: r.measurement.cueKind, ariaLive: r.measurement.ariaLive }))) };
+      },
+    },
+  ],
+};

package/blueprints/application-datatable/CHANGELOG.md

@@ -0,0 +1,8 @@
+# application-datatable CHANGELOG
+
+## 1.0.0 (visual round T-1, spec 2026-09-04)
+
+- First ratified version of the shelf's datatable blueprint. Six REQs (table shell, sort semantics, filter chrome, selection and bulk actions, empty / loading / error / no-results states, column visibility / reorder / resize), nine USs binding 27 runtime-observable ACs, three TACs (shell, query adapter, selection model), four ADRs (pattern choice, URL state, page size, selection persistence). No new global topics.
+- Ships `probe-packs/application-datatable.pack.mjs`: six browser-verify checks anchored to AC-17101-1, AC-17102-1, AC-17103-2, AC-17104-3, AC-17105-1, AC-17106-1. First 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-datatable/` (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.
+- Suggests the `logging` and `errorHandling` companions with the ratified spec's reasons.