rcf-lite 0.20.0 → 0.22.0

package/blueprints/application-admin-console/contributions/user-stories/application-admin-console-us-21109.json

@@ -0,0 +1,33 @@
+{
+  "usId": "application-admin-console-US-21109",
+  "prdId": "PRD-001",
+  "reqId": "application-admin-console-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Console apply refuses on a bare SPA with the spec 5.5.1 message and honours --allow-no-auth-yet",
+  "asA": "operator applying the admin-console on a project with no auth blueprint yet",
+  "iWant": "the apply to refuse with exit 3 and a message naming security-auth-* explicitly, or to accept an --allow-no-auth-yet override that records a scaffolding-note on the sidecar",
+  "soThat": "a scaffolding pass can land the console files without hiding the fact that the surfaces will refuse at runtime until an auth blueprint is applied",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-21109-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "rcf define blueprint add ./blueprints/application-admin-console on a project with no applied blueprint declaring principalDirectory (and without --allow-no-auth-yet) exits 3; the stderr message begins with \"application-admin-console requires at least one applied security-auth-*\", lists the currently-applied blueprints on the project, and prints the \"Suggested next steps\" block including the four shelf auth slugs. No contribution files are written; the sidecar is not created."
+    },
+    {
+      "id": "AC-21109-2",
+      "testable": true,
+      "scope": "runtime",
+      "description": "With --allow-no-auth-yet passed, the apply proceeds and writes rcf/blueprints/application-admin-console.applied.json with allowNoAuthYet:true and a notes string naming the \"no auth yet\" state; a later rcf define validate reads the sidecar and flags the ungated surfaces."
+    }
+  ],
+  "tacIds": [
+    "TAC-2202-application-admin-console-capability-discovery"
+  ],
+  "tags": [
+    "blueprint:application-admin-console"
+  ],
+  "createdAt": "2026-09-05T01:30:00Z",
+  "updatedAt": "2026-09-05T01:30:00Z"
+}

package/blueprints/application-admin-console/docs/topics.md

@@ -0,0 +1,42 @@
+# application-admin-console: coordination vocabulary
+
+## Global topics
+
+The blueprint claims no new global topics at v1.0.0. The console is a consumer of the identity capability set the applied auth blueprints declare through `capabilities[]`; every ADR (capability vocabulary, baseline roles, invite transport, audit retention) is non-global.
+
+## Deliberately unclaimed topics
+
+- `roleModel` (the shape of a role catalogue: id/label/permission tuples). Reserved for the applied auth blueprint's ADR set; the console reads the applied `roleModel` label vocabulary through the elicited `baseline-roles` answer and does not mint its own role-model global topic.
+- `principalDirectory` (the shape of a principal record). Reserved for the applied auth blueprint's ADR set for the same reason.
+- `tenancy` (the shape of an organisation abstraction). Reserved for a future `application-tenancy-orgs` blueprint (spec section 11).
+- `auditLog` (the audit event stream shape). Reserved for the applied logging companion's ADR set, or a future dedicated audit-log blueprint.
+
+## 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-admin-console.pack.mjs` ships four capability-gated checks anchored to blueprint AC ids:
+
+- `AC-21102-1` users directory (fires only when `principalDirectory` is applied)
+- `AC-21103-1` permission matrix (fires only when `roleModel` is applied)
+- `AC-21104-1` org switcher (fires only when `tenancy` is applied)
+- `AC-21105-1` audit-log surface (fires only when `auditLog` is applied)
+
+The pack applies to any FBS binding `TAC-2201-application-admin-console-shell` or whose navModel routes name an admin path. See `packages/rcf-lite/docs/blueprint-authoring.md` section 8c for the pack authoring rules.

package/blueprints/application-admin-console/guide/application-admin-console.md

@@ -0,0 +1,29 @@
+# application-admin-console: operator guide
+
+## When to reach for it
+
+Your project applies at least one shelf `security-auth-*` blueprint (or a custom identity source declaring `principalDirectory` via the elicitation phase). You need an admin console that identifies principals, manages roles, and reads a change history. You want the console to configure itself from the applied capability set rather than demand configuration.
+
+## When NOT to reach for it
+
+You are shipping a fully-featured, opinionated admin product (Retool, an internal admin CMS, a bespoke ops console). Adopt this blueprint only when a vendor-neutral shell composed from the applied identity blueprint suits your project better than a fixed opinionated console.
+
+You want an anonymous product (no principal directory, no roles). The blueprint refuses at apply on a bare SPA; `--allow-no-auth-yet` accepts the refusal for a scaffolding pass but the surfaces will not activate until an identity capability is applied.
+
+## What stays your call
+
+- Which shelf auth blueprint you apply first (or whether you supply custom auth via the elicitation phase).
+- The elicited additional role labels beyond Owner + Admin + Member + Viewer.
+- The invite transport (email, in-app-only, or custom).
+- The tenancy shape (per-user, per-org, or both) if you apply a tenancy blueprint.
+- The audit-log retention window (default 90 days).
+
+## Mechanism-reach gaps
+
+The blueprint's README lists the runtime-observable ACs the pack does NOT bind directly. Every gap is a candidate for a v1.1.0 minor bump extending the pack; the shipped v1.0.0 pack anchors the four load-bearing surface checks. Combine with the T-1 datatable pack to reach the users and audit shells' state-region contract.
+
+## Promotion signals
+
+- The role catalogue label vocabulary drifts across three or more applied auth blueprints: candidate for a `roleModel` global topic in a v1.1.0 minor.
+- The tenancy shape needs a real shelf provider: candidate for the `application-tenancy-orgs` blueprint (spec section 11).
+- A dedicated audit-log blueprint ships: candidate for the console to consume it directly via `capabilities: ["auditLog"]` rather than through the logging companion.

package/blueprints/application-admin-console/probe-packs/application-admin-console.pack.mjs

@@ -0,0 +1,182 @@
+// application-admin-console probe pack (v1.0.0).
+//
+// Four capability-gated checks anchored to the blueprint AC ids:
+//   AC-21102-1 users directory (fires when principalDirectory applied)
+//   AC-21103-1 permission matrix (fires when roleModel applied)
+//   AC-21104-1 org switcher (fires when tenancy applied)
+//   AC-21105-1 audit-log surface (fires when auditLog applied)
+//
+// Every check drives the real Playwright browser the T-0 runner injects
+// and reads its per-check applicability from the blueprint applied
+// sidecar (rcf/blueprints/application-admin-console.applied.json)
+// written by the apply verb: an absent capability records
+// applicable: false and the aggregate verdict treats the check as
+// neither pass nor fail (spec section 3.3).
+//
+// Sample-app fixture: packages/rcf-lite/test/fixtures/probe-pack-application-admin-console/.
+// The fixture ships a CAPS env or ?caps= query switch mirroring the
+// applied capability set so the pack can be probed for every fixture
+// combination on the shelf gate.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+async function readAppliedCapabilities(projectRoot) {
+  if (!projectRoot) return [];
+  try {
+    const raw = await readFile(join(projectRoot, 'rcf', 'blueprints', 'application-admin-console.applied.json'), 'utf8');
+    const doc = JSON.parse(raw);
+    return Array.isArray(doc.appliedCapabilities) ? doc.appliedCapabilities.slice() : [];
+  } catch {
+    return [];
+  }
+}
+
+function withUrl(runtimeUrl, path) {
+  return new URL(path, runtimeUrl).toString();
+}
+
+export default {
+  packName: 'application-admin-console',
+  version: '1.0.0',
+  blueprintSlug: 'application-admin-console',
+  // Applies to any FBS that realises the console shell TAC or whose
+  // navModel routes name an admin path. Names both `tacIds` and `route`
+  // so the loader source-scan sees the two legal seams.
+  appliesTo: ({ fbs }) => {
+    const routes = fbs?.designStage?.navModel?.routes ?? [];
+    const tacIds = fbs?.contextRequirements?.tacIds ?? [];
+    if (tacIds.includes('TAC-2201-application-admin-console-shell')) return true;
+    return routes.some((r) => typeof r?.path === 'string' && /\/admin(\/|$)/.test(r.path));
+  },
+  boot: { bootCommand: null, waitForUrl: null, waitForSelector: null },
+  checks: [
+    {
+      id: 'AC-21102-1',
+      severity: 'block',
+      description: 'Users directory lists principals by data-user-id, honours applied roleModel by rendering the role column only when applied, and renders a request-access control on the access-denied route',
+      // Fires only when principalDirectory is applied. Reads the
+      // sidecar from projectRoot; probe-pack runner supplies it.
+      appliesTo: async ({ projectRoot }) => {
+        const caps = await readAppliedCapabilities(projectRoot);
+        return caps.includes('principalDirectory');
+      },
+      run: async ({ browser, fetch, runtimeUrl, projectRoot }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        const caps = await readAppliedCapabilities(projectRoot);
+        const shouldHaveRoleColumn = caps.includes('roleModel');
+        await browser.goto(withUrl(runtimeUrl, '/admin/users'));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="users"]');
+          if (!region) return { present: false };
+          const rows = Array.from(region.querySelectorAll('[data-user-id]'));
+          const ids = rows.map((r) => r.getAttribute('data-user-id'));
+          const hasRoleColumn = !!region.querySelector('[data-column="role"]');
+          const invites = rows.map((r) => !!r.querySelector('[data-action="invite"]'));
+          const deactivates = rows.map((r) => !!r.querySelector('[data-action="deactivate"]'));
+          return { present: true, ids, hasRoleColumn, invites, deactivates };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'users surface region [data-surface="users"] not found' };
+        if (dom.ids.length === 0) return { verdict: 'fail', detail: 'users surface rendered no rows with data-user-id' };
+        if (shouldHaveRoleColumn && !dom.hasRoleColumn) return { verdict: 'fail', detail: 'roleModel applied but no [data-column="role"] header found' };
+        if (!shouldHaveRoleColumn && dom.hasRoleColumn) return { verdict: 'fail', detail: 'roleModel NOT applied but [data-column="role"] header found (leak)' };
+        // Access-denied route: negative branch. A non-admin principal
+        // simulated via ?asAdmin=false renders the denied region with
+        // the request-access control.
+        await browser.goto(withUrl(runtimeUrl, '/admin/users?asAdmin=false'));
+        const denied = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="denied"]');
+          if (!region) return { present: false };
+          const control = region.querySelector('[data-action="request-access"]');
+          return { present: true, hasControl: !!control };
+        });
+        if (!denied.present) return { verdict: 'fail', detail: 'access-denied region [data-surface="denied"] not found' };
+        if (!denied.hasControl) return { verdict: 'fail', detail: 'access-denied region missing [data-action="request-access"] control' };
+        return { verdict: 'pass', detail: 'users rows=' + JSON.stringify(dom.ids) + ' roleColumn=' + dom.hasRoleColumn + ' deniedControl=' + denied.hasControl };
+      },
+    },
+    {
+      id: 'AC-21103-1',
+      severity: 'block',
+      description: 'Permission matrix renders as an ARIA APG grid with role=row, role=rowheader, role=columnheader, role=gridcell and announces each permission string on focus via aria-label',
+      appliesTo: async ({ projectRoot }) => {
+        const caps = await readAppliedCapabilities(projectRoot);
+        return caps.includes('roleModel');
+      },
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/admin/roles'));
+        const dom = await browser.evaluate(() => {
+          const grid = document.querySelector('[data-surface="roles"] [role="grid"]');
+          if (!grid) return { present: false };
+          const rows = Array.from(grid.querySelectorAll('[role="row"]'));
+          const columnHeaders = Array.from(grid.querySelectorAll('[role="columnheader"]')).map((h) => h.textContent.trim());
+          const rowHeaders = Array.from(grid.querySelectorAll('[role="rowheader"]')).map((h) => h.textContent.trim());
+          const cells = Array.from(grid.querySelectorAll('[role="gridcell"]'));
+          const cellLabels = cells.map((c) => c.getAttribute('aria-label'));
+          return { present: true, rowCount: rows.length, columnHeaders, rowHeaders, cellLabelSample: cellLabels.slice(0, 3), cellCount: cells.length };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'role=grid not found under [data-surface="roles"]' };
+        if (dom.rowCount < 2) return { verdict: 'fail', detail: 'grid has too few role=row entries: ' + JSON.stringify(dom) };
+        if (dom.columnHeaders.length === 0) return { verdict: 'fail', detail: 'grid missing role=columnheader entries' };
+        if (dom.rowHeaders.length === 0) return { verdict: 'fail', detail: 'grid missing role=rowheader entries' };
+        if (dom.cellCount === 0) return { verdict: 'fail', detail: 'grid missing role=gridcell entries' };
+        // Every cell must carry an aria-label announcing the permission string.
+        if (dom.cellLabelSample.some((l) => !l || l.length === 0)) {
+          return { verdict: 'fail', detail: 'gridcell aria-label absent on at least one cell: ' + JSON.stringify(dom.cellLabelSample) };
+        }
+        return { verdict: 'pass', detail: 'rows=' + dom.rowCount + ' cols=' + JSON.stringify(dom.columnHeaders) + ' rowHeaders=' + JSON.stringify(dom.rowHeaders) + ' cellSample=' + JSON.stringify(dom.cellLabelSample) };
+      },
+    },
+    {
+      id: 'AC-21104-1',
+      severity: 'block',
+      description: 'Org switcher control renders on the shell header only when tenancy is applied',
+      appliesTo: async ({ projectRoot }) => {
+        const caps = await readAppliedCapabilities(projectRoot);
+        return caps.includes('tenancy');
+      },
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/admin'));
+        const dom = await browser.evaluate(() => {
+          const control = document.querySelector('[data-role="org-switcher"]');
+          if (!control) return { present: false };
+          return { present: true, tag: control.tagName, ariaLabel: control.getAttribute('aria-label') };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'org switcher [data-role="org-switcher"] not present on the shell header' };
+        return { verdict: 'pass', detail: 'org-switcher ' + JSON.stringify(dom) };
+      },
+    },
+    {
+      id: 'AC-21105-1',
+      severity: 'block',
+      description: 'Audit-log entries surface with actor, target, before, after, timestamp and correlationId columns; every row enumerable by data-audit-id',
+      appliesTo: async ({ projectRoot }) => {
+        const caps = await readAppliedCapabilities(projectRoot);
+        return caps.includes('auditLog');
+      },
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/admin/audit'));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="audit"]');
+          if (!region) return { present: false };
+          const rows = Array.from(region.querySelectorAll('[data-audit-id]'));
+          const ids = rows.map((r) => r.getAttribute('data-audit-id'));
+          const columns = Array.from(region.querySelectorAll('[data-column]')).map((c) => c.getAttribute('data-column'));
+          const firstRowColumns = rows[0] ? Array.from(rows[0].querySelectorAll('[data-column]')).map((c) => c.getAttribute('data-column')) : [];
+          return { present: true, ids, columns, firstRowColumns };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'audit surface [data-surface="audit"] not found' };
+        if (dom.ids.length === 0) return { verdict: 'fail', detail: 'audit surface rendered no rows with data-audit-id' };
+        const required = ['actor', 'target', 'before', 'after', 'timestamp', 'correlationId'];
+        const missing = required.filter((c) => !dom.firstRowColumns.includes(c));
+        if (missing.length > 0) {
+          return { verdict: 'fail', detail: 'audit entries missing columns: ' + JSON.stringify(missing) + ' present=' + JSON.stringify(dom.firstRowColumns) };
+        }
+        return { verdict: 'pass', detail: 'auditRows=' + dom.ids.length + ' columns=' + JSON.stringify(dom.firstRowColumns) };
+      },
+    },
+  ],
+};

package/blueprints/application-api-rest/docs/topics.md

@@ -29,7 +29,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
 | delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
 | observability-essentials | 7101-7899 | 8xx | shipped v2.0.0 | `statusPageContract` |
-| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.1 | `secretsSource` |
 | security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
 | security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
 | security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
@@ -38,6 +38,18 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
 | observability-logging | 15101-15899 | 16xx | shipped v1.0.0 | `logging` |
 | 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 |
+| 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` |
 
 Suffix-family ids (ADR, TAC): SPA numbers in the 2xx range, this package takes 3xx (ADR-301 to ADR-308, TAC-301 to TAC-306); the next blueprint should take 4xx.
 

package/blueprints/application-charts/CHANGELOG.md

@@ -0,0 +1,12 @@
+# application-charts CHANGELOG
+
+## 1.0.0 (visual round T-2, spec 2026-09-04)
+
+- First ratified version of the shelf's charts blueprint. Four REQs (chart form set, non-colour distinction, text-alternative table, keyboard traversal), six USs binding runtime-observable ACs, two TACs (render shell, keyboard traversal), three ADRs (elicited chart engine with canvas-only refusal, accessible palette light and dark, reduced motion via application-spa tokens). No new global topics.
+- Ships `probe-packs/application-charts.pack.mjs`: three browser-verify checks anchored to AC-18102-1 (non-colour distinction), AC-18103-1 (text-alternative table with cell-per-value contract), AC-18104-1 (keyboard traversal contract with reduced-motion suppression). Every check carries a description field per spec section 9. Second blueprint on the shelf that ships a Playwright probe pack under the T-0 runner extension; first leaf blueprint the T-3 application-dashboard consumes.
+- Ships a sample-app fixture at `packages/rcf-lite/test/fixtures/probe-pack-application-charts/` (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=table`, `?break=pattern` and `?break=keyboard` query switches for the negative runs.
+- Suggests the `logging` and `errorHandling` companions with the ratified spec's reasons.
+
+### Patch note (2026-09-04, T-3 gate follow-up)
+
+- `probe-packs/application-charts.pack.mjs`: navigate with `new URL('', runtimeUrl).toString()` instead of `runtimeUrl + '/'` on the three goto call sites (AC-18102-1, AC-18103-1, AC-18104-1). The concat form stripped a reviewer-supplied `?break=<mode>` from a CLI `--url`; the URL-resolver form preserves the runtime URL verbatim so a reviewer pointing the CLI at `?break=<mode>` sees the negative run naturally. Version stays at 1.0.0; behaviour unchanged on the default apply-side runtime URL.

package/blueprints/application-charts/README.md

@@ -0,0 +1,73 @@
+# Charts blueprint (v1.0.0)
+
+Vendor-neutral chart-component contract for a rcf-lite application. Ships the accessibility, palette, text-alternative and keyboard-traversal discipline every chart on the shipped surface must meet. Ships a Playwright probe pack under `probe-packs/application-charts.pack.mjs` whose three checks are the runtime gate the delivery-ci-workflows runner drives (visual round spec 2026-09-04, section 5.2). No new global topics; suggests the `logging` and `errorHandling` companions. Leaf blueprint: application-dashboard (visual round T-3) consumes it; no other blueprint in this round does.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/application-charts
+```
+
+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 }]`, 15 contributions in the 18xx US band and 19xx ADR/TAC block |
+| Doc set | `contributions/` | 4 REQs, 6 USs, 2 TACs, 3 ADRs, schema-valid and namespaced |
+| Probe pack | `probe-packs/application-charts.pack.mjs` | Three browser-verify checks anchored to AC-18102-1 (non-colour distinction), AC-18103-1 (text-alternative table), AC-18104-1 (keyboard traversal with reduced motion) |
+| Guide | `guide/application-charts.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 |
+
+## 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 chart-engine source and no test files (the probe pack drives the real browser against the applying project's own runtime).
+
+Deliberately not contributed: a choice of chart engine (Recharts, ECharts, Chart.js, D3 primitives, hand-authored SVG); a data-source contract (the applying project sources chart data through the applied `application-api-rest` blueprint or an equivalent); a dashboard layout contract (the applying `application-dashboard` blueprint owns tile placement and hierarchy).
+
+## The engine refusal rule
+
+`ADR-1901` elicits the chart engine at apply, and refuses a canvas-only engine that offers no text-alternative surface. The refusal is documented here on the blueprint's README so applying projects and gate reviewers see the rule in one place:
+
+- Recharts, ECharts, Chart.js and D3 primitives all satisfy the shell contract when paired with the shell's text-alternative table slot. Chart.js's canvas surface is paired with the shell's `<table>` slot; the shell renders both, so screen readers reach the values.
+- A chart engine that renders exclusively to a `<canvas>` and does NOT offer either a shell-rendered `<table>` or an equivalent DOM path is refused at project-side review. The applying project either replaces the engine or supersedes this blueprint with a project-authored engine contract naming the residuals.
+
+## The one runtime gate
+
+`probe-packs/application-charts.pack.mjs` ships three checks the `rcf verify browser` runner invokes on any FBS whose surface matches the pack's `appliesTo` predicate (an FBS that binds `TAC-1901-application-charts-render-shell` or whose nav model routes name a chart or dashboard path). Each check drives the real Playwright browser the runner provisions (through the pinned Playwright MCP or the consuming project's own `playwright` installation), reads the accessibility tree and the DOM, and returns a verdict. A failing block-severity check refuses ship through the existing `browserVerification` aggregate verdict.
+
+The pack fires ONLY when its `appliesTo` returns true; a project whose FBS does not bind the shell TAC or a chart route sees the pack recorded as `applicable: false` and no browser check runs.
+
+## Elicited parameters (ADR-1901, ADR-1902, ADR-1903 and REQ notes)
+
+- **Chart engine**: Recharts, ECharts, Chart.js, D3 primitives, or a hand-authored SVG mount. Elicited at apply, recorded in the manifest; a canvas-only engine with no text-alternative path is refused (ADR-1901).
+- **Default categorical palette**: light and dark accessible-defaults ship as the recommended default; operator brand tokens can override at apply, fall back to the defaults on missing tokens (ADR-1902).
+- **Interactive traversal scope**: either every chart on the surface (default) or only detail-view charts. When only detail views are interactive, the shell binds the keyboard-traversal contract on those charts and skips it on the overview charts (ADR-1901 alternative decision).
+- **Sparkline behaviour**: in-tile (mounted inside a stat tile via `application-dashboard`) or standalone (mounted on the shipped surface as one chart). The shell handles both; the applying project picks per surface.
+
+## Standards trace
+
+WCAG 2.2 AA: 1.4.1 (Use of Colour), 1.4.3 (Contrast Minimum), 1.4.11 (Non-text Contrast), 2.1.1 (Keyboard), 2.3.3 (Animation from Interactions). `standardsTrace` empty on the blueprint; `standardsTraceClause` on each ADR carries the WCAG clause.
+
+## Quality bar
+
+Every chart on the shipped surface mounts through the render shell (TAC-1901). Every multi-series chart carries colour AND a non-colour pattern (data-pattern attribute, stroke-dasharray, hatched fill or marker shape) AND a direct label at the series (AC-18102-1). Every chart is paired with a `<table>` in the same landmark, cell-per-value, focus-reachable through a labelled control (AC-18103-1, AC-18103-2). Every interactive chart exposes a keyboard traversal path with the announced string `<seriesName>, <xValue>, <yValue> <unit>` on focus, and `prefers-reduced-motion: reduce` suppresses transitions (AC-18104-1). Chart engine is elicited at apply and canvas-only-no-text-alternative is refused (ADR-1901, AC-18106-1).
+
+## 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-18101-1 form-set membership**. the pack does not inspect a chart's declared form against the six-form set. A project-side review is the current mechanism. A v1.1 minor bump could add a fourth pack check reading the `data-chart-form` attribute the shell emits and asserting membership.
+- **AC-18101-2 shell-mount routing**. the pack does not inspect the mount seam; a chart bypass to the raw chart-library mount is caught at project-side review. A build-scan pre-check in a v1.1 minor bump can grep the applying project's source for engine-specific mount calls.
+- **AC-18102-2 single-series exemption**. the pack does not skip single-series charts explicitly today; the runner reports `applicable: false` for the check on a surface with only single-series charts based on the DOM inspection. A v1.1 minor bump can formalise the skip on the pack seam.
+- **AC-18103-2 show-table control label and reading order**. the pack asserts the control is present but does not assert the control's accessible-name text or its position in tab order before the chart's data points. A v1.1 minor bump can add a pack check that tabs into the region and reads the tab order.
+- **AC-18104-2 non-interactive-chart exemption**. the pack does not skip non-interactive charts explicitly today; the check fails on a surface whose data points miss `tabindex="0"`, whether or not the chart is interactive. Project-side review names non-interactive charts and the reviewer skips the check by hand.
+- **AC-18105-1 palette contrast**. the pack does not measure contrast ratios today. Palette contrast is a build-scan surface (colour tokens are inspectable from the applied palette module). A v1.1 minor bump can add a Node build-scan pre-check that reads the applied palette and checks the ratios against WCAG 1.4.3 and 1.4.11.
+- **AC-18105-2 palette override fallback**. the fallback behaviour is exercised by the applying project's own tests, not this blueprint's pack. The applying project owns the assertion.
+- **AC-18106-1 canvas-only refusal**. the refusal is documented in the README's engine-refusal rule; project-side review enforces it. A v1.1 minor bump could add a pack pre-check that reads the applied engine and refuses on a canvas-only engine with no `<table>` companion.
+- **AC-18106-2 engine-name marker**. the applying project ships a `data-chart-engine` attribute or an equivalent DOM marker. The pack does not assert this today; a v1.1 minor bump could read the marker and add it to the pack record for downstream tooling.
+
+## Vision-deficiency emulation is a runner-seam gap
+
+The runner has no `emulateVisionDeficiency` seam on the pack browser today (`goto`, `snapshot`, `evaluate`, `click`, `type`, `press`, `screenshot` is the current API). AC-18102-1 is therefore proven at the DOM level: every series carries a non-colour cue AND a direct label. A future runner minor that adds `emulateVisionDeficiency` to the seam lets this pack add a deuteranopia render pass; that follow-up is named under CONCERNS in the T-2 dispatch report as the smallest runner change that would close the class.

package/blueprints/application-charts/blueprint.json

@@ -0,0 +1,26 @@
+{
+  "slug": "application-charts",
+  "version": "1.0.0",
+  "category": "application",
+  "suggestedCompanions": [
+    { "role": "logging", "reason": "Chart rendering telemetry (data-point activation, keyboard traversal) rides the same log surface as the rest of the client; a logging companion supplies the factory the client-side telemetry uses." },
+    { "role": "errorHandling", "reason": "A chart that fails to load surfaces a client-side error record; an error-handling companion supplies the boundary and the record factory." }
+  ],
+  "contributions": [
+    { "id": "application-charts-REQ-001", "kind": "req", "path": "requirements/application-charts-req-001.json" },
+    { "id": "application-charts-REQ-002", "kind": "req", "path": "requirements/application-charts-req-002.json" },
+    { "id": "application-charts-REQ-003", "kind": "req", "path": "requirements/application-charts-req-003.json" },
+    { "id": "application-charts-REQ-004", "kind": "req", "path": "requirements/application-charts-req-004.json" },
+    { "id": "application-charts-US-18101", "kind": "us", "path": "user-stories/application-charts-us-18101.json" },
+    { "id": "application-charts-US-18102", "kind": "us", "path": "user-stories/application-charts-us-18102.json" },
+    { "id": "application-charts-US-18103", "kind": "us", "path": "user-stories/application-charts-us-18103.json" },
+    { "id": "application-charts-US-18104", "kind": "us", "path": "user-stories/application-charts-us-18104.json" },
+    { "id": "application-charts-US-18105", "kind": "us", "path": "user-stories/application-charts-us-18105.json" },
+    { "id": "application-charts-US-18106", "kind": "us", "path": "user-stories/application-charts-us-18106.json" },
+    { "id": "TAC-1901-application-charts-render-shell", "kind": "tac", "path": "tacs/tac-1901-application-charts-render-shell.json" },
+    { "id": "TAC-1902-application-charts-keyboard-traversal", "kind": "tac", "path": "tacs/tac-1902-application-charts-keyboard-traversal.json" },
+    { "id": "ADR-1901-application-charts-engine-choice", "kind": "adr", "path": "adrs/adr-1901-application-charts-engine-choice.json", "elicited": true, "standardsTraceClause": "WCAG 1.4.1 / WCAG 2.1.1" },
+    { "id": "ADR-1902-application-charts-accessible-palette", "kind": "adr", "path": "adrs/adr-1902-application-charts-accessible-palette.json", "recommendedDefault": true, "elicited": true, "standardsTraceClause": "WCAG 1.4.3 / WCAG 1.4.11" },
+    { "id": "ADR-1903-application-charts-motion", "kind": "adr", "path": "adrs/adr-1903-application-charts-motion.json", "recommendedDefault": true, "standardsTraceClause": "WCAG 2.3.3" }
+  ]
+}

package/blueprints/application-charts/contributions/adrs/adr-1901-application-charts-engine-choice.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1901-application-charts-engine-choice",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Elicit the chart engine at apply, and refuse a canvas-only engine that offers no text-alternative surface",
+  "context": "Chart engines have wildly different accessibility postures. Recharts and ECharts render to SVG with keyboard-focusable data points and a DOM the shell can read; Chart.js renders to canvas and needs a paired data-table to reach a screen reader; D3 primitives leave the accessibility contract to the author. A blueprint that hard-picks one engine locks the applying project into that engine's accessibility posture; a blueprint that leaves it wide open lets the project ship a canvas-only chart with no text-alternative path.",
+  "decision": "The chart engine is elicited at apply (Recharts, ECharts, Chart.js, D3 primitives or an operator-named alternative). The shell contract stands regardless of engine (a paired text-alternative table in the same landmark; a keyboard traversal path on interactive charts; a colour-plus-pattern-plus-label series distinction). A chart engine that renders exclusively to a `<canvas>` and offers no text-alternative surface is refused at project-side review; the refusal is documented on the blueprint's README under the engine-refusal rule.",
+  "consequences": "Applying projects pick the engine that fits their existing stack (a Chart.js-heavy project keeps Chart.js and pairs every chart with the text-alternative table the shell renders). A canvas-only engine is refused with a clear reason; the applying project either replaces the engine or supersedes the blueprint with a project-authored engine contract naming the residuals.",
+  "alternativesConsidered": [
+    {
+      "name": "Hard-pick Recharts",
+      "summary": "The blueprint commits Recharts as the shipped engine.",
+      "reasonNotChosen": "React-only, and it locks projects with a Vue or Svelte surface into a foreign runtime. The shell contract is engine-agnostic; there is no reason to pick one at the shelf."
+    },
+    {
+      "name": "Allow any engine including canvas-only with no text-alternative",
+      "summary": "The blueprint accepts any engine choice with no refusal path.",
+      "reasonNotChosen": "The text-alternative REQ-003 is unreachable on a canvas-only engine; the blueprint would ship an AC that cannot be enforced on a compliant apply."
+    }
+  ],
+  "createdAt": "2026-09-04T21:00:00Z",
+  "updatedAt": "2026-09-04T21:00:00Z"
+}

package/blueprints/application-charts/contributions/adrs/adr-1902-application-charts-accessible-palette.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1902-application-charts-accessible-palette",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Ship an accessible-defaults categorical palette (light and dark) with elicited operator overrides",
+  "context": "Categorical palettes are the most common source of colour-blindness defects on chart libraries: many popular defaults (rainbow gradients, the classic ten-colour categorical from d3-scale v1) fail deuteranopia readability at the second and third series. Operators bring brand tokens they want to see on the shipped surface; the tension between brand palette and accessible palette is real.",
+  "decision": "The blueprint ships a light and a dark accessible-defaults categorical palette matched against WCAG 1.4.3 (4.5:1 text contrast) and WCAG 1.4.11 (3:1 non-text contrast) against the applied theme's background. The palettes are the recommended default. Operators supply brand tokens through the shell's palette accessor; missing tokens fall back to the accessible-defaults palette at the same index and the render log records a warning. The applying project verifies contrast on the shipped surface as a build-scan supplement; the pack does not check contrast today.",
+  "consequences": "Applying projects get a contrast-safe palette out of the box and can override with brand tokens without losing the fallback. Contrast checking on the operator palette is the applying project's responsibility; the blueprint's README names it under known mechanism-reach gaps as a v1.1 minor bump candidate for the pack.",
+  "alternativesConsidered": [
+    {
+      "name": "Ship no default palette",
+      "summary": "The blueprint requires the operator to supply a palette at apply.",
+      "reasonNotChosen": "Every applying project would ship the first-pass palette their designer picked, and the accessibility posture would move with the designer's brief. The default carries the shelf's discipline."
+    },
+    {
+      "name": "Ship one palette across light and dark",
+      "summary": "Same series colours in both themes.",
+      "reasonNotChosen": "A colour with 4.5:1 contrast against a white background often reads at 2:1 against a black background; two palettes is the honest shape."
+    }
+  ],
+  "createdAt": "2026-09-04T21:00:00Z",
+  "updatedAt": "2026-09-04T21:00:00Z"
+}

package/blueprints/application-charts/contributions/adrs/adr-1903-application-charts-motion.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1903-application-charts-motion",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Honour prefers-reduced-motion via the application-spa motion tokens on every chart transition",
+  "context": "Chart libraries default to animated entry and update transitions (bars grow from zero, lines sweep left-to-right). `prefers-reduced-motion: reduce` is the WCAG 2.3.3 signal the operator's platform preferences carry; failing to honour it is a common accessibility defect on chart libraries and a hard-to-diagnose vestibular trigger.",
+  "decision": "Every rendered chart on the shipped surface honours the `prefers-reduced-motion: reduce` media query by setting `transition-duration: 0` and `animation-duration: 0` on the animated chart elements (bars, lines, sweep animations, tooltip fades) through a media rule the shell attaches on mount. The rule composes with the application-spa motion tokens (the applying project's shared motion baseline). The pack asserts the media rule is present and effective on the rendered surface (computed style on an animated element under an emulated reduced-motion preference); a chart that ships a transition and misses the media rule fails AC-18104-1.",
+  "consequences": "Every chart on the shipped surface is safe for users who set the reduced-motion preference. The shell owns the CSS attachment; the applying project's engine-specific transitions inherit the rule without a per-engine override.",
+  "alternativesConsidered": [
+    {
+      "name": "Leave motion to the engine",
+      "summary": "Each engine's own reduced-motion handling.",
+      "reasonNotChosen": "Chart.js and D3 primitives do not honour `prefers-reduced-motion` by default; the shell has to do it or the AC is unreachable."
+    },
+    {
+      "name": "Disable all chart transitions unconditionally",
+      "summary": "No chart animates at all, regardless of preference.",
+      "reasonNotChosen": "Motion is a legitimate affordance for operators who want it; the preference gate is the honest shape."
+    }
+  ],
+  "createdAt": "2026-09-04T21:00:00Z",
+  "updatedAt": "2026-09-04T21:00:00Z"
+}

package/blueprints/application-charts/contributions/requirements/application-charts-req-001.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "application-charts-REQ-001",
+  "prdId": "PRD-001",
+  "title": "The application ships the small set of chart forms an operator SaaS actually shows",
+  "description": "The application realises the chart-form set the shelf's spec commits: bar, line, area, pie or donut, single-value with sparkline, and heatmap. Every rendered chart on the shipped surface picks one of these forms and honours the render-shell contract (TAC-1901). A form outside this set is refused at project-side review; a specialised form the applying project needs (a candlestick, a Sankey) supersedes this REQ with a project-authored REQ and is documented as a known deviation.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "The form set is where teams reach for a chart library and pick the wrong tool. Enumerating the forms in the contract closes the ambiguity at ship: every rendered chart on the surface names one of the six forms and inherits its rendering discipline, its accessibility affordances and its text-alternative shape from the shell.",
+  "tags": ["blueprint:application-charts", "category:01-form-set"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T21:00:00Z",
+  "updatedAt": "2026-09-04T21:00:00Z"
+}

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

@@ -0,0 +1,15 @@
+{
+  "reqId": "application-charts-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Every chart series distinguishes on colour plus pattern plus direct label (non-colour distinction, WCAG 1.4.1)",
+  "description": "Every rendered chart with two or more series distinguishes the series through more than colour alone: colour is paired with a pattern (a dashed line, a hatched fill, a marker shape) and a direct label placed at the series (a legend entry alone does not satisfy the AC). A vision-deficiency simulation (deuteranopia is the shelf's default screen) still reads the series distinction. The blueprint's accessible palette (ADR-1902) is the colour default; the pattern and label rules apply regardless of palette.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Colour blindness is the most common visual disability and colour-only series distinction is the most common accessibility defect on chart libraries; the tri-cue (colour, pattern, label) is what WCAG 1.4.1 asks for and what a build-scan or runtime check can prove at the DOM level.",
+  "tags": ["blueprint:application-charts", "category:02-non-colour-distinction"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T21:00:00Z",
+  "updatedAt": "2026-09-04T21:00:00Z"
+}

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

@@ -0,0 +1,15 @@
+{
+  "reqId": "application-charts-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Every chart ships a text-alternative table carrying the same data, focus-reachable in the same landmark",
+  "description": "Every rendered chart on the shipped surface ships a paired `<table>` element in the same landmark as the chart, carrying the same values, cell-per-value: rows for the x-axis or category dimension and columns for each series. The table is either visible under the chart or visually-hidden and focus-reachable through a labelled control (a link or a button). Assistive tech traverses the table cell-by-cell; the values in the table match the values the chart renders.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "A chart is a visual encoding of data; a text-alternative table is the only assistive-tech-reachable form of the same data that fits the existing table-navigation vocabulary. Screen-reader users receive the same information; a canvas-only chart with no text-alternative is inaccessible.",
+  "tags": ["blueprint:application-charts", "category:03-text-alternative"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T21:00:00Z",
+  "updatedAt": "2026-09-04T21:00:00Z"
+}

package/blueprints/application-charts/contributions/requirements/application-charts-req-004.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "application-charts-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Interactive charts honour a keyboard traversal contract and reduced-motion preference (WCAG 2.1.1, WCAG 2.3.3)",
+  "description": "An interactive chart (a chart whose data points are clickable, hoverable or filterable) exposes a keyboard traversal path: each data point receives focus in reading order (left-to-right, top-to-bottom for a single-series chart; series-by-series for a multi-series chart), and the announced string on focus carries the series name, the x-value, the y-value and the unit. `prefers-reduced-motion` suppresses chart transitions on entry and update. A non-interactive chart (a rendered surface with no data-point activation) is exempt from the keyboard traversal AC; the reduced-motion rule applies regardless.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Keyboard-only users need the same data-point granularity a pointer user has, and the announced string is the assistive-tech-visible surface. Reduced-motion respect is the WCAG 2.3.3 clause the shelf inherits from application-spa's motion tokens; a chart that does not honour it fails the same clause.",
+  "tags": ["blueprint:application-charts", "category:04-keyboard-traversal"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T21:00:00Z",
+  "updatedAt": "2026-09-04T21:00:00Z"
+}