rcf-lite 0.20.0 → 0.22.0

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

@@ -0,0 +1,88 @@
+# Empty and error states blueprint (v1.0.0)
+
+Vendor-neutral empty-and-error-states contract for an rcf-lite application. Ships eight named states, one contract per state: `not-found` (404), `forbidden` (403), `server-error` (500), `offline`, `permission-denied` (403 with a per-resource cause), `empty-list`, `no-search-results`, `error-boundary` (client-side render failure). Each state carries a machine-readable status, a distinct visual, a `role="region"` accessible name, one recovery-action shape from a closed enum, and a polite live-region wrapper for progress and reconnection announcements. Ships a Playwright probe pack under `probe-packs/application-empty-error-states.pack.mjs` whose eight checks each anchor one named state, refuse on the corresponding break switch, and fire against the sample-app fixture on the shelf gate.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/application-empty-error-states
+```
+
+Applies 19 contributions (5 REQs, 8 USs, 3 TACs, 3 ADRs) cleanly on any fresh init project. No `requiresAppliedCapabilities`, no auth prerequisite, no elicited-only parameters that block the apply; the two elicits (`ADR-2302` stack-trace visibility and `ADR-2303` offline strategy) carry recommended defaults so the apply proceeds silently and the project can revisit the elicited answers later.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version 1.0.0, category `application`, `suggestedCompanions: [logging, errorHandling]`, 19 contributions in the 23xx / 22xxx band |
+| Doc set | `contributions/` | 5 REQs, 8 USs (8 runtime-observable ACs), 3 TACs, 3 ADRs |
+| Probe pack | `probe-packs/application-empty-error-states.pack.mjs` | Eight surface-observable browser-verify checks, one per named state |
+| Guide | `guide/application-empty-error-states.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 |
+| Sample-app fixture | `packages/rcf-lite/test/fixtures/probe-pack-application-empty-error-states/` | Dependency-free Node HTTP server the pack is probed against on the shelf gate |
+
+## The eight named states
+
+| State | HTTP status | Recovery shape(s) | Announcement | Region wrapper |
+|---|---|---|---|---|
+| `not-found` | 404 | `parent-surface` + `search` | polite live-region | `[data-surface="not-found"]` |
+| `forbidden` | 403 (no per-resource cause) | `request-access` | polite live-region | `[data-surface="forbidden"]` |
+| `server-error` | 5xx | `retry` | polite live-region | `[data-surface="server-error"]` |
+| `permission-denied` | 403 (class-level cause) | `request-access` | polite live-region | `[data-surface="permission-denied"]` |
+| `offline` | (no HTTP; `navigator.onLine` false) | `retry` (implicit on reconnection) | polite live-region for reconnection | `[data-surface="offline"]` |
+| `empty-list` | 200 (empty array on a listing endpoint) | `create` | polite live-region | `[data-surface="empty-list"]` |
+| `no-search-results` | 200 (empty array on a search endpoint) | `clear-filters` | polite live-region | `[data-surface="no-search-results"]` |
+| `error-boundary` | (no HTTP; caught client-side render exception) | `retry` | `role="alert"` (assertive) | `[data-surface="error-boundary"]` |
+
+The eight-state enum is closed at v1.0.0. A ninth state is a v1.1.0 minor bump; a state removed or renamed is a v2.0.0 major.
+
+## Recovery-action router
+
+The closed set of recovery shapes: `parent-surface`, `search`, `request-access`, `retry`, `create`, `clear-filters`, `no-recovery`. Every rendered state carries at least one. The router refuses to render a state without a legitimate shape; a bare state region without any recovery is a build defect the pack catches.
+
+## Offline strategy
+
+`ADR-2303` commits to `write-buffer` as the default (IndexedDB, idempotency token per write, monotonic sequence, flush in sequence on reconnection with server-side dedupe). Elicited alternatives: `read-only-banner` and `refuse-writes`. All three shapes render the offline region and the polite reconnection announcement per REQ-005; the difference is only whether writes queue, disable or refuse.
+
+## Elicited parameters
+
+- **States in scope for v1.** Default: all eight. A project that has not yet shipped offline mode can elicit a reduced set; the pack skips checks whose state is out of scope on that project.
+- **Recovery-action targets per state.** Default: the router's built-ins (parent-surface, search, request-access, retry, create, clear-filters). Projects override the endpoint paths and callbacks per FBS.
+- **Stack-trace visibility in production.** Default: true (hidden). `ADR-2302` elicits an override for staging.
+- **Offline strategy.** Default: `write-buffer`. `ADR-2303` elicits `read-only-banner` or `refuse-writes`.
+
+## The one runtime gate
+
+`probe-packs/application-empty-error-states.pack.mjs` ships eight checks the `rcf verify browser` runner invokes on any FBS whose surface binds `TAC-2301-application-empty-error-states-state-machine` or whose nav model routes name an operator-configured error-shell path. Each check drives the real Playwright browser the runner provisions, reads the accessibility tree and the DOM, and returns a verdict. URLs are composed by the `withUrl(runtimeUrl, path)` helper per the round 3 T-3 fix train; no bare string concatenation.
+
+## Quality bar
+
+WCAG 2.2 AA on every state region: 3.3.1 Error Identification (every error state names the error class in the heading), 2.4.6 Headings and Labels (every region carries a heading and an accessible name), 3.2.4 Consistent Identification (every recovery control carries the same `data-recovery` attribute across states), 4.1.3 Status Messages (every progress and reconnection announcement fires through the polite live-region wrapper), 3.3.3 Error Suggestion (the recovery-action prose names the next action, not just the error). HTTP semantics per RFC 9110 for the status-code contract (ADR-2301). ARIA APG alert pattern on `error-boundary`. `standardsTrace` on the blueprint is empty (this is a general-enterprise-practice blueprint); each ADR contribution carries `standardsTraceClause` naming the clause it implements.
+
+The 500 surface is a CSP-shape enforcement. `AC-22103-1` reads the rendered surface, tokenises against a bundled sensitive-pattern list (backtrace-frame prefix, source-path shape, environment-variable key shape, framework-internal frame prefix, `process.env.NAME` reference), and refuses when any pattern matches.
+
+## Known mechanism-reach gaps
+
+Runtime-observable ACs the pack does NOT bind directly (checklist section 6.g), listed individually per AC id:
+
+- **AC-22101-1 keyboard-focus-on-recovery.** The pack asserts the parent-surface link and the search entry exist and carry the correct `data-recovery` attribute; it does NOT additionally probe that keyboard focus lands on the recovery control on state entry. A v1.1.0 minor bump can drive the browser's accessibility tree and assert focus placement.
+- **AC-22102-1 request-access transport round-trip.** The pack asserts the `[data-action="request-access"]` control exists; it does NOT additionally exercise the POST round-trip and assert the applied notification centre receives the submission. A v1.1.0 minor bump can invoke the click path and inspect the network request log.
+- **AC-22103-1 non-production staging branch.** The pack drives the production branch (`?break=stack-trace` is the negative run for the production posture); the elicited staging-visible branch (`ADR-2302`) is present on the fixture through the same break switch but the pack does not additionally probe the staging-legitimate render.
+- **AC-22104-1 cause-string vocabulary registry.** The pack asserts the class-level cause is present and refuses when a resource-id shape appears; it does NOT additionally cross-check the cause string against a project-side vocabulary registry. A v1.1.0 minor bump can read a project-declared vocabulary file and diff.
+- **AC-22105-1 write-buffer flush order.** The pack asserts a synthetic buffered write is enumerable on `window.__offlineBuffer` and that the polite reconnection announcement fires; it does NOT additionally probe that a multi-entry buffer flushes in sequence with per-entry retry counters. A v1.1.0 minor bump can seed a multi-entry buffer and drive the flush loop.
+- **AC-22106-1 empty-list distinction from loading.** The pack asserts the `[data-visual="empty-list"]` wrapper is present; it does NOT additionally probe that the wrapper is distinct from `[data-visual="loading"]` and `[data-visual="loaded"]` on the same route. A v1.1.0 minor bump can drive the loading branch and diff the wrapper attributes.
+- **AC-22107-1 clear-filters callback shape.** The pack asserts the `[data-recovery="clear-filters"]` control exists and echoes the query; it does NOT additionally exercise the callback and assert the search parameters are removed from the URL. A v1.1.0 minor bump can drive the click path and inspect the resulting URL.
+- **AC-22108-1 boundary retry re-mounts the component.** The pack asserts the `role="alert"` region and the retry control exist; it does NOT additionally probe that the retry re-mounts the crashed component subtree. A v1.1.0 minor bump can drive the click path and inspect the DOM diff.
+
+## Companions
+
+`suggestedCompanions` declares `logging` (every rendered error state writes one request-scoped log line with the correlation identifier the applied logger factory returns) and `errorHandling` (the error-boundary state constructs an internal error record from the caught exception through the applied error-handling factory). Neither is required to apply the blueprint; a project without a logging companion still ships every state region, it just does not emit a per-state log line.
+
+## Consumers
+
+- `application-forms-wizard` (T-3 of this round) consumes the empty-list state as its "no in-progress forms" surface; the wizard's empty branch delegates to this blueprint's TAC-2301 state machine.
+- `application-account-settings` (T-4 of this round) consumes the access-denied path (forbidden and permission-denied) for its scope-gated settings sections and the empty-list state for its empty-history surfaces.
+
+## Composition with application-spa
+
+`application-spa` REQ-006 ships empty, loading, error, banner and alert components as part of its component library. This blueprint composes with SPA; the topic-ownership boundary lives in `docs/topics.md`. SPA owns the tab-title convention and the state-visual tokens; this sibling owns the state list, the recovery-action router and the runtime enforcement pack.

package/blueprints/application-empty-error-states/blueprint.json

@@ -0,0 +1,119 @@
+{
+  "slug": "application-empty-error-states",
+  "version": "1.0.0",
+  "category": "application",
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "Every rendered error state writes one request-scoped log line with the correlation identifier; a logging companion supplies the factory the pipeline calls."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "The error-boundary state constructs an internal error record from the caught exception; an error-handling companion supplies the factory and the boundary."
+    }
+  ],
+  "contributions": [
+    {
+      "id": "application-empty-error-states-REQ-001",
+      "kind": "req",
+      "path": "requirements/application-empty-error-states-req-001.json"
+    },
+    {
+      "id": "application-empty-error-states-REQ-002",
+      "kind": "req",
+      "path": "requirements/application-empty-error-states-req-002.json"
+    },
+    {
+      "id": "application-empty-error-states-REQ-003",
+      "kind": "req",
+      "path": "requirements/application-empty-error-states-req-003.json"
+    },
+    {
+      "id": "application-empty-error-states-REQ-004",
+      "kind": "req",
+      "path": "requirements/application-empty-error-states-req-004.json"
+    },
+    {
+      "id": "application-empty-error-states-REQ-005",
+      "kind": "req",
+      "path": "requirements/application-empty-error-states-req-005.json"
+    },
+    {
+      "id": "application-empty-error-states-US-22101",
+      "kind": "us",
+      "path": "user-stories/application-empty-error-states-us-22101.json"
+    },
+    {
+      "id": "application-empty-error-states-US-22102",
+      "kind": "us",
+      "path": "user-stories/application-empty-error-states-us-22102.json"
+    },
+    {
+      "id": "application-empty-error-states-US-22103",
+      "kind": "us",
+      "path": "user-stories/application-empty-error-states-us-22103.json"
+    },
+    {
+      "id": "application-empty-error-states-US-22104",
+      "kind": "us",
+      "path": "user-stories/application-empty-error-states-us-22104.json"
+    },
+    {
+      "id": "application-empty-error-states-US-22105",
+      "kind": "us",
+      "path": "user-stories/application-empty-error-states-us-22105.json"
+    },
+    {
+      "id": "application-empty-error-states-US-22106",
+      "kind": "us",
+      "path": "user-stories/application-empty-error-states-us-22106.json"
+    },
+    {
+      "id": "application-empty-error-states-US-22107",
+      "kind": "us",
+      "path": "user-stories/application-empty-error-states-us-22107.json"
+    },
+    {
+      "id": "application-empty-error-states-US-22108",
+      "kind": "us",
+      "path": "user-stories/application-empty-error-states-us-22108.json"
+    },
+    {
+      "id": "TAC-2301-application-empty-error-states-state-machine",
+      "kind": "tac",
+      "path": "tacs/tac-2301-application-empty-error-states-state-machine.json"
+    },
+    {
+      "id": "TAC-2302-application-empty-error-states-recovery-router",
+      "kind": "tac",
+      "path": "tacs/tac-2302-application-empty-error-states-recovery-router.json"
+    },
+    {
+      "id": "TAC-2303-application-empty-error-states-offline-buffer",
+      "kind": "tac",
+      "path": "tacs/tac-2303-application-empty-error-states-offline-buffer.json"
+    },
+    {
+      "id": "ADR-2301-application-empty-error-states-status-contract",
+      "kind": "adr",
+      "path": "adrs/adr-2301-application-empty-error-states-status-contract.json",
+      "recommendedDefault": true,
+      "standardsTraceClause": "RFC 9110"
+    },
+    {
+      "id": "ADR-2302-application-empty-error-states-stack-trace-visibility",
+      "kind": "adr",
+      "path": "adrs/adr-2302-application-empty-error-states-stack-trace-visibility.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "OWASP ASVS V7 error handling"
+    },
+    {
+      "id": "ADR-2303-application-empty-error-states-offline-strategy",
+      "kind": "adr",
+      "path": "adrs/adr-2303-application-empty-error-states-offline-strategy.json",
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    }
+  ]
+}

package/blueprints/application-empty-error-states/contributions/adrs/adr-2301-application-empty-error-states-status-contract.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2301-application-empty-error-states-status-contract",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "HTTP status to rendered state mapping follows RFC 9110 semantics",
+  "context": "The blueprint dispatches states from HTTP responses. There are three plausible mappings from status to rendered state: honour RFC 9110 semantics verbatim (404 to not-found, 403 to forbidden, 5xx to server-error, empty 200 to empty-list or no-search-results depending on the endpoint kind); collapse all client errors into a single generic client-error state; or lean on a bespoke response-body flag the server includes to name the state. The first is the least-surprising choice for a shelf blueprint whose surfaces will be composed with vendor libraries that emit plain HTTP; the second loses the affordances (parent-surface link on 404, request-access on 403) that make the state useful; the third couples the client tightly to a server contract the shelf does not otherwise mint.",
+  "decision": "Adopt RFC 9110 semantics verbatim as the state-machine's status mapping. 404 dispatches not-found; 403 dispatches forbidden by default and permission-denied when the response body carries a class-level cause string; 5xx dispatches server-error. An empty 200 response body on a listing endpoint dispatches empty-list; an empty 200 on a search endpoint (identified by a q query parameter or an FBS-declared search route) dispatches no-search-results. This mapping is the recommendedDefault per the ADR contribution field.",
+  "consequences": "Projects composing REST APIs that already answer RFC 9110 status codes get the state dispatch for free. Projects using an RPC-style API layer must wrap their transport in a small adapter that raises the plain status code. The state machine remains stable across vendor libraries (fetch, axios, tRPC clients, GraphQL error-code conventions that project the transport-level status) because the contract is on the status number the machine reads, not on a bespoke body flag.",
+  "alternativesConsidered": [
+    {
+      "name": "Collapse client errors into one generic state",
+      "summary": "Route every 4xx into a single client-error state with a generic recovery.",
+      "reasonNotChosen": "Loses the four recovery-shape specialisations (parent-surface on 404, request-access on 403, retry on 5xx, clear-filters on no-search-results) that make the state actionable and forces every recovery through a generic retry."
+    },
+    {
+      "name": "Bespoke response-body state-name field",
+      "summary": "Require every response body to carry a stateName string the machine reads.",
+      "reasonNotChosen": "Couples the shelf blueprint tightly to a server contract the shelf does not otherwise mint; a vendor library returning plain HTTP would be unsupported by default."
+    }
+  ],
+  "createdAt": "2026-09-06T15:40:00Z",
+  "updatedAt": "2026-09-06T15:40:00Z"
+}

package/blueprints/application-empty-error-states/contributions/adrs/adr-2302-application-empty-error-states-stack-trace-visibility.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2302-application-empty-error-states-stack-trace-visibility",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "The server-error state hides stack traces, source paths and environment-variable keys in production",
+  "context": "The 5xx state is the most tempting surface for a debug leak because a stack trace is the first thing a developer would like on-screen when something breaks. In production the same surface is a probing target for an attacker: a stack trace names framework versions and internal frame layouts; a source path names filesystem structure; an environment-variable key shape names the deploy environment's configuration surface. Staging environments legitimately want the debug detail; production does not.",
+  "decision": "In production the server-error state renders a plain summary line and a retry recovery hook only. The rendered surface refuses any word matching the sensitive-pattern list: backtrace-frame prefixes (\"at <fn>(<file>:<line>:<col>)\" and variants), source paths (leading /, ./, ../), environment-variable key shape (NAME= or process.env.NAME references), and framework-internal frame prefixes. In non-production environments (staging, local) the elicited stack-trace-visible parameter may flip the guard off; the pack still fires on staging so a leak that reaches production is caught before ship. recommendedDefault is true; elicited is true so the operator can flip the guard for staging or for a build that renders the debug region behind a role gate.",
+  "consequences": "Projects on the recommended default get the least-privilege posture with no configuration. Projects that want a debug region in staging author the elicited toggle and add a role-gated debug region behind an operator scope. The pack fires on both branches with the appropriate expectation. A production build that ships with the toggle flipped on refuses the ship gate through this pack's AC-22103-1.",
+  "alternativesConsidered": [
+    {
+      "name": "Always render the stack trace",
+      "summary": "Ship the full stack trace in every environment, on the theory that the operator will see it before an attacker does.",
+      "reasonNotChosen": "In practice an attacker triggers 5xx surfaces at will (bad payloads, malformed routes); the stack trace ships to their browser too. The debug value in production is negligible compared to the leak."
+    },
+    {
+      "name": "Server-side redaction only",
+      "summary": "Rely on the server to strip the stack trace before it reaches the client.",
+      "reasonNotChosen": "The client-side error boundary also renders 5xx surfaces from caught JS exceptions that never touched the server; a server-side redactor cannot cover the client boundary."
+    }
+  ],
+  "createdAt": "2026-09-06T15:40:00Z",
+  "updatedAt": "2026-09-06T15:40:00Z"
+}

package/blueprints/application-empty-error-states/contributions/adrs/adr-2303-application-empty-error-states-offline-strategy.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2303-application-empty-error-states-offline-strategy",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Offline strategy is write-buffer by default with elicited alternatives for read-only-banner and refuse-writes",
+  "context": "Applications differ on what they want to do while offline. A note-taking application wants a write-buffer so the operator keeps working. A financial application wants to refuse writes altogether because a queued write against stale server state is worse than a hard fail. A dashboard application wants a read-only banner and refuses writes silently. There is no single sensible default; the shelf blueprint commits to one and elicits the two alternatives.",
+  "decision": "Default is write-buffer per TAC-2303: writes queue to IndexedDB with an idempotency token and flush on reconnection with server-side dedupe. Elicited alternatives are read-only-banner (the surface renders a banner and every write control disables) and refuse-writes (every write attempt fails locally with a clear message; nothing queues). The elicited answer lives on the applied-blueprint sidecar and the state machine reads it on offline entry. elicited is true; recommendedDefault stays false because the choice is genuinely per-project.",
+  "consequences": "Projects that want the write-buffer get the default with no configuration; the pack drives an offline probe and asserts window.__offlineBuffer is populated. Projects electing read-only-banner get a simpler UI at the cost of losing the operator's in-flight writes. Projects electing refuse-writes get the strictest posture with the clearest failure mode. All three shapes render the offline region and the polite reconnection announcement per REQ-005; the difference is only whether writes queue, disable or refuse.",
+  "alternativesConsidered": [
+    {
+      "name": "Force refuse-writes as the default",
+      "summary": "Refuse every offline write locally; no buffer; no queue.",
+      "reasonNotChosen": "Loses the operator's in-flight work every time the network drops for a few seconds; the most common failure mode (transient loss) becomes the most painful."
+    },
+    {
+      "name": "Server-side sync engine",
+      "summary": "Ship a CRDT or event-sourced sync engine as part of this blueprint.",
+      "reasonNotChosen": "Outside the shelf blueprint's scope (this is a UI-state blueprint, not a persistence blueprint); belongs to a future persistence-sync-engine blueprint if the shelf grows one."
+    }
+  ],
+  "createdAt": "2026-09-06T15:40:00Z",
+  "updatedAt": "2026-09-06T15:40:00Z"
+}

package/blueprints/application-empty-error-states/contributions/requirements/application-empty-error-states-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-empty-error-states-REQ-001",
+  "prdId": "PRD-001",
+  "title": "State catalogue: the eight named empty and error states, each with a machine-readable status and a distinct visual",
+  "description": "The application realises eight named empty and error states, one contract per state: not-found (HTTP 404 on an unknown resource), forbidden (HTTP 403 on an authenticated principal without scope), server-error (HTTP 5xx on an internal failure), offline (navigator.onLine false), permission-denied (HTTP 403 with a per-resource cause), empty-list (a listing endpoint returned an empty array), no-search-results (a search or filter yielded zero rows), error-boundary (a client-side render exception caught by the SPA boundary). Each state carries a machine-readable status (statusCode for HTTP-triggered states, a well-known token for client-triggered states) and a distinct visual so a screenshot review reader can tell them apart at a glance. Vendor-neutral: the blueprint contributes WHAT surfaces under WHAT condition, not the visual design.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec section 5.1, REQ 1.",
+  "tags": [
+    "blueprint:application-empty-error-states",
+    "category:01-state-catalogue"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T15:40:00Z",
+  "updatedAt": "2026-09-06T15:40:00Z"
+}

package/blueprints/application-empty-error-states/contributions/requirements/application-empty-error-states-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-empty-error-states-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Recovery-action contract per state: parent-surface link, search entry, request-access flow, retry hook",
+  "description": "Every rendered state carries at least one recovery action. The recovery-action router maps each named state to one of a fixed four action shapes: parent-surface (a link back up the resource hierarchy, used by not-found and empty-list), search (a search entry, used by not-found and no-search-results), request-access (a POST to a well-known request-access endpoint the applied notification centre can surface, used by forbidden and permission-denied), retry (a client-side re-issue of the failed operation, used by server-error and offline). The router refuses to render a state without a recovery action; a state whose applied surface has no legitimate recovery renders an explicit no-recovery notice with the reason.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec section 5.1, REQ 2.",
+  "tags": [
+    "blueprint:application-empty-error-states",
+    "category:02-recovery-router"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T15:40:00Z",
+  "updatedAt": "2026-09-06T15:40:00Z"
+}

package/blueprints/application-empty-error-states/contributions/requirements/application-empty-error-states-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-empty-error-states-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Announcement contract: role region per state, aria-live polite for progress and reconnection, screen-reader traversal order",
+  "description": "Every rendered state region carries role=\"region\" with an accessible name naming the state (WCAG 2.4.6 Headings and Labels). Progress announcements (retry attempt, reconnection to server) fire through an aria-live=\"polite\" live-region wrapper (WCAG 4.1.3 Status Messages). Screen-reader traversal order is: state heading first, then the recovery action, then any secondary detail; keyboard focus lands on the recovery control on state entry so a keyboard user reaches recovery in one tab. The error-boundary state announces via role=\"alert\" (assertive) rather than polite because the client render failed and the operator has no context.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec section 5.1, REQ 3.",
+  "tags": [
+    "blueprint:application-empty-error-states",
+    "category:03-announcement"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T15:40:00Z",
+  "updatedAt": "2026-09-06T15:40:00Z"
+}

package/blueprints/application-empty-error-states/contributions/requirements/application-empty-error-states-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-empty-error-states-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Server-error surface: no stack trace in production, no resource-id leak on forbidden per least-privilege posture",
+  "description": "The server-error (5xx) state renders in production mode without a stack trace, without a source file path, without any environment-variable key shape (VARNAME=value or process.env.NAME references), and without any framework internal frame prefix. The pack refuses when any word in a bundled sensitive-pattern list matches the rendered surface (path-shape strings, backtrace-frame prefixes, environment-variable key shape). The forbidden (403) and permission-denied (403 with cause) states render without the resource id, without the resource name and without the server-side path so a principal without scope cannot infer resource existence from the error surface. A staging environment override is available via ADR-2302 elicitation.",
+  "category": "security",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec section 5.1, REQ 4. Second risk clause in the round-4 spec calls for a CSP-shape enforcement on the 500 surface.",
+  "tags": [
+    "blueprint:application-empty-error-states",
+    "category:04-least-privilege"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T15:40:00Z",
+  "updatedAt": "2026-09-06T15:40:00Z"
+}

package/blueprints/application-empty-error-states/contributions/requirements/application-empty-error-states-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-empty-error-states-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Offline state: write-buffer contract, navigator.onLine reconnection announcement, per-write reconciliation semantics",
+  "description": "When navigator.onLine reports false the offline state renders with a read-only banner naming the offline mode. Queued writes buffer to an applied local buffer (IndexedDB by default, an elicited alternative per ADR-2303) with an idempotency token per write, a serialised payload, and a monotonically increasing sequence. On reconnection (navigator.onLine true) the offline state announces through the polite live-region wrapper the applied notifications-in-app blueprint has preseeded; queued writes flush in sequence, each with the same idempotency token so a server-side dedupe rejects a re-issue. Per-write reconciliation semantics: on flush success the surface clears the buffer entry; on flush failure the entry is retained with a retry counter and the surface renders a per-write error banner.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec section 5.1, REQ 5.",
+  "tags": [
+    "blueprint:application-empty-error-states",
+    "category:05-offline"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T15:40:00Z",
+  "updatedAt": "2026-09-06T15:40:00Z"
+}

package/blueprints/application-empty-error-states/contributions/tacs/tac-2301-application-empty-error-states-state-machine.json

@@ -0,0 +1,46 @@
+{
+  "tacId": "TAC-2301-application-empty-error-states-state-machine",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Empty and error state machine",
+  "purpose": "Owns the mapping from an FBS surface render (a routed page, a listing surface, a search surface, a client-side render) to the eight named empty and error states and from each state to a recovery-action shape. Reads the runtime signals (HTTP status code, response body shape, navigator.onLine, caught render exception) and dispatches the correct state region plus the correct recovery shape. Every AC in this blueprint anchors on this TAC.",
+  "responsibilities": [
+    "Map HTTP 404 to not-found, 403 to forbidden or permission-denied (see internalStructure), 5xx to server-error, and empty-array response bodies to empty-list or no-search-results (see internalStructure) (AC-22101-1 through AC-22104-1, AC-22106-1, AC-22107-1).",
+    "Map navigator.onLine false to offline and the reconnect signal to the polite reconnection announcement (AC-22105-1).",
+    "Map a caught client-side render exception to error-boundary announced through role=\"alert\" (AC-22108-1).",
+    "Delegate every recovery action to the recovery-action router (TAC-2302) and every offline buffer operation to the offline-buffer TAC (TAC-2303)."
+  ],
+  "internalStructure": "One state-machine module the shell mounts on route entry. On response, the machine reads the HTTP status code plus the response body shape: a 403 with a per-resource cause routes to permission-denied, a bare 403 routes to forbidden; a 200 with an empty array on a search endpoint (route carries a q query parameter) routes to no-search-results, a 200 with an empty array on a listing endpoint routes to empty-list. On navigator.onLine transitions the machine dispatches offline entry and reconnection through the polite live-region wrapper. On a caught render exception (the SPA error boundary) the machine dispatches error-boundary through the assertive alert wrapper. Every dispatch writes the state name into the rendered region as an accessible name and delegates the recovery action to the recovery router. The framework is not prescribed; the machines interfaces are what the project realises against React, Vue, Svelte or vanilla DOM.",
+  "interfaces": [
+    {
+      "name": "renderState",
+      "kind": "factory",
+      "description": "renderState({ statusCode, responseBody, route, onLine, caughtException }) -> { stateName, recoveryShape, regionProps }. The project supplies the runtime signals; the machine returns the state name, the recovery shape the router will realise, and the region props (role, aria-live level, accessible name)."
+    },
+    {
+      "name": "statesEnum",
+      "kind": "shape",
+      "description": "The eight named states are the closed enum { not-found, forbidden, server-error, offline, permission-denied, empty-list, no-search-results, error-boundary }. A ninth state is a blueprint minor bump (see CHANGELOG)."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Recovery-action router",
+      "kind": "tac",
+      "tacId": "TAC-2302-application-empty-error-states-recovery-router",
+      "description": "The state machine hands every rendered state's recovery shape to the router."
+    },
+    {
+      "name": "Offline write-buffer",
+      "kind": "tac",
+      "tacId": "TAC-2303-application-empty-error-states-offline-buffer",
+      "description": "The offline entry dispatches through the write-buffer TAC."
+    }
+  ],
+  "tradeoffs": "One state-machine module keeps the mapping deterministic and lint-checkable but ties every state to a runtime signal the project must expose. Projects that route through a framework's own boundary primitive (React error boundary, Vue errorCaptured) wire the machine into that primitive rather than replacing it. Known mechanism-reach gap: the machine cannot prove keyboard focus lands on the recovery control in every framework's rendering; the pack asserts the control is reachable, project-side smoke tests supplement.",
+  "notes": "See README Known mechanism-reach gaps for the full list.",
+  "createdAt": "2026-09-06T15:40:00Z",
+  "updatedAt": "2026-09-06T15:40:00Z"
+}

package/blueprints/application-empty-error-states/contributions/tacs/tac-2302-application-empty-error-states-recovery-router.json

@@ -0,0 +1,36 @@
+{
+  "tacId": "TAC-2302-application-empty-error-states-recovery-router",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Recovery-action router",
+  "purpose": "Owns the mapping from a state's recovery shape (parent-surface, search, request-access, retry, create, clear-filters) to a concrete rendered control on the state region. The router is the second layer under the state machine; every state that renders passes its recovery shape through the router.",
+  "responsibilities": [
+    "Realise the parent-surface shape as a link with data-recovery=\"parent-surface\" whose href points to the FBS-declared parent path (AC-22101-1, AC-22106-1 when the empty-list has a parent).",
+    "Realise the search shape as a search entry with data-recovery=\"search\" (AC-22101-1, AC-22107-1).",
+    "Realise the request-access shape as a button with data-action=\"request-access\" that POSTs to the FBS-configured request-access endpoint (AC-22102-1, AC-22104-1).",
+    "Realise the retry shape as a button with data-recovery=\"retry\" that re-issues the failed operation (AC-22103-1, AC-22105-1, AC-22108-1).",
+    "Realise the create shape as a link or button with data-recovery=\"create\" (AC-22106-1) and the clear-filters shape as a button with data-recovery=\"clear-filters\" (AC-22107-1)."
+  ],
+  "internalStructure": "One router module the state machine hands each state's recovery shape. The router reads the FBS-configured parent path, request-access endpoint and clear-filters callback and constructs the rendered control. Refuses to render a state without a legitimate recovery shape (an authored no-recovery notice is a legitimate shape; a bare state region without any recovery is a build defect).",
+  "interfaces": [
+    {
+      "name": "renderRecovery",
+      "kind": "factory",
+      "description": "renderRecovery({ shape, config }) -> { element, dataRecoveryAttr, dataActionAttr }. shape is one of parent-surface, search, request-access, retry, create, clear-filters, no-recovery. config carries the FBS-declared paths and callbacks the router needs."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "State machine",
+      "kind": "tac",
+      "tacId": "TAC-2301-application-empty-error-states-state-machine",
+      "description": "The router runs downstream of the state machine's dispatch."
+    }
+  ],
+  "tradeoffs": "A closed set of recovery shapes keeps the state matrix testable but constrains projects that want a bespoke recovery flow to compose a wider shape as no-recovery with a project-side custom region. A future v1.1.0 minor bump can add a request-access-inline shape (inline form rather than a POST) when demand warrants.",
+  "notes": "The recovery-shape enum is closed at v1: parent-surface, search, request-access, retry, create, clear-filters, no-recovery. A new shape is a blueprint minor bump.",
+  "createdAt": "2026-09-06T15:40:00Z",
+  "updatedAt": "2026-09-06T15:40:00Z"
+}

package/blueprints/application-empty-error-states/contributions/tacs/tac-2303-application-empty-error-states-offline-buffer.json

@@ -0,0 +1,40 @@
+{
+  "tacId": "TAC-2303-application-empty-error-states-offline-buffer",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Offline write-buffer",
+  "purpose": "Owns the buffering and reconciliation contract for writes attempted while navigator.onLine is false. Every buffered write carries an idempotency token, a serialised payload and a monotonic sequence; on reconnection the buffer flushes in sequence and the server dedupes on the idempotency token.",
+  "responsibilities": [
+    "Persist every buffered write to the applied local buffer (IndexedDB by default per ADR-2303, an elicited alternative for projects that need it) with an idempotency token, serialised payload and sequence (AC-22105-1).",
+    "Expose window.__offlineBuffer as a read-only enumeration for the pack and for project-side smoke tests (AC-22105-1).",
+    "Announce buffered-write count changes through the polite live-region wrapper on entry and on reconnection (AC-22105-1 via TAC-2301).",
+    "On reconnection, flush the buffer in sequence, retain the entry on flush failure with a retry counter, and clear the entry on flush success."
+  ],
+  "internalStructure": "One buffer module the state machine invokes on offline entry and exit. The buffer wraps the applied storage engine (default IndexedDB via a small adapter interface, elicited alternatives per ADR-2303) with a serialise/deserialise pair and a monotonic counter. The reconciliation loop is idempotent: replaying the flush against the same buffer produces the same server-side effect.",
+  "interfaces": [
+    {
+      "name": "bufferWrite",
+      "kind": "factory",
+      "description": "bufferWrite({ payload, idempotencyToken }) -> { sequence }. Persists the write, returns the sequence assigned. The idempotency token is caller-supplied so the server-side dedupe key is stable across retries."
+    },
+    {
+      "name": "flushBuffer",
+      "kind": "factory",
+      "description": "flushBuffer({ onSuccess, onFailure }) -> { flushed, retained }. Called on reconnection; iterates the buffer in sequence, calling onSuccess or onFailure per entry."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "State machine",
+      "kind": "tac",
+      "tacId": "TAC-2301-application-empty-error-states-state-machine",
+      "description": "The state machine dispatches offline entry and reconnection into this buffer."
+    }
+  ],
+  "tradeoffs": "IndexedDB by default is available in every modern browser but requires the applied surface to run in a browser context (not a WebView with a locked-down storage policy). Projects on a stripped WebView elicit an alternative via ADR-2303. Retention semantics on flush failure are per-write; a global give-up threshold is a project-side concern and not part of the v1 contract.",
+  "notes": "The buffer is a runtime-observable contract; the pack drives an offline probe with a synthetic write and asserts window.__offlineBuffer is populated.",
+  "createdAt": "2026-09-06T15:40:00Z",
+  "updatedAt": "2026-09-06T15:40:00Z"
+}

package/blueprints/application-empty-error-states/contributions/user-stories/application-empty-error-states-us-22101.json

@@ -0,0 +1,29 @@
+{
+  "usId": "application-empty-error-states-US-22101",
+  "prdId": "PRD-001",
+  "reqId": "application-empty-error-states-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The not-found state renders with a naming heading, a parent-surface recovery link, a search entry and a tab title carrying the state name",
+  "asA": "operator following a stale or mistyped link into the application",
+  "iWant": "the not-found state to render with a heading naming the missing resource kind, a recovery link back up to the parent surface and a search entry, and a tab title reading Not found - <app>",
+  "soThat": "I can name the resource I asked for, walk back up the resource hierarchy or search for the right one, and my browser tab distinguishes this state from the loaded surface",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-22101-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "Given a 404 response on a route the SPA declares, the not-found state renders inside a role=\"region\" with an accessible name naming the missing resource kind, a keyboard-reachable recovery link to the parent surface with data-recovery=\"parent-surface\", a search entry with data-recovery=\"search\", and the browser tab title matches /^Not found - .+/. The pack drives the real browser to /probe/not-found and reads all four surface tokens."
+    }
+  ],
+  "tacIds": [
+    "TAC-2301-application-empty-error-states-state-machine",
+    "TAC-2302-application-empty-error-states-recovery-router"
+  ],
+  "tags": [
+    "blueprint:application-empty-error-states",
+    "state:not-found"
+  ],
+  "createdAt": "2026-09-06T15:40:00Z",
+  "updatedAt": "2026-09-06T15:40:00Z"
+}

package/blueprints/application-empty-error-states/contributions/user-stories/application-empty-error-states-us-22102.json

@@ -0,0 +1,29 @@
+{
+  "usId": "application-empty-error-states-US-22102",
+  "prdId": "PRD-001",
+  "reqId": "application-empty-error-states-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The forbidden state renders with a request-access control and refuses to surface a resource id, resource name or path shape",
+  "asA": "authenticated operator without scope on a resource",
+  "iWant": "the forbidden state to render with a request-access control routing to the applied notification centre and no resource-identifying content on the rendered surface",
+  "soThat": "I have a legitimate recovery path and I cannot infer the existence of a resource I am not authorised to see",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-22102-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "Given a 403 response, the forbidden state renders inside role=\"region\" with a keyboard-reachable [data-action=\"request-access\"] control that POSTs to /api/request-access. The rendered surface does NOT contain any word matching the sensitive-pattern list (resource id shape, resource name shape, path-shape strings starting with /). The pack drives /probe/forbidden and reads the region, the control, and the full document text for pattern hits."
+    }
+  ],
+  "tacIds": [
+    "TAC-2301-application-empty-error-states-state-machine",
+    "TAC-2302-application-empty-error-states-recovery-router"
+  ],
+  "tags": [
+    "blueprint:application-empty-error-states",
+    "state:forbidden"
+  ],
+  "createdAt": "2026-09-06T15:40:00Z",
+  "updatedAt": "2026-09-06T15:40:00Z"
+}

package/blueprints/application-empty-error-states/contributions/user-stories/application-empty-error-states-us-22103.json

@@ -0,0 +1,29 @@
+{
+  "usId": "application-empty-error-states-US-22103",
+  "prdId": "PRD-001",
+  "reqId": "application-empty-error-states-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The server-error state renders in production without a stack trace, without a source path and without an environment-variable key shape",
+  "asA": "operator hitting an internal failure",
+  "iWant": "the 5xx state to render a plain summary with a retry recovery hook and no server implementation detail",
+  "soThat": "I get a legible failure without a leak that would help an attacker probe the server",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-22103-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "Given a mocked 500 response, the server-error state renders inside role=\"region\" with a keyboard-reachable [data-recovery=\"retry\"] control; the rendered surface does NOT contain any word matching the sensitive-pattern list (backtrace-frame prefix like \"at \" plus function name plus file colon line, a source path starting with / or ./ or ../, an environment-variable key shape NAME= or process.env.NAME, or a framework-internal frame prefix). The pack drives /probe/server-error and greps the document text against the pattern list."
+    }
+  ],
+  "tacIds": [
+    "TAC-2301-application-empty-error-states-state-machine",
+    "TAC-2302-application-empty-error-states-recovery-router"
+  ],
+  "tags": [
+    "blueprint:application-empty-error-states",
+    "state:server-error"
+  ],
+  "createdAt": "2026-09-06T15:40:00Z",
+  "updatedAt": "2026-09-06T15:40:00Z"
+}