rcf-lite 0.21.0 → 0.22.0

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"
+}

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

@@ -0,0 +1,29 @@
+{
+  "usId": "application-empty-error-states-US-22104",
+  "prdId": "PRD-001",
+  "reqId": "application-empty-error-states-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The permission-denied state names a class-level cause and never the per-resource id",
+  "asA": "authenticated operator hitting a 403 with a per-resource cause",
+  "iWant": "the permission-denied state to render a class-level cause string (for example \"admin scope required\") not the resource id",
+  "soThat": "I get an actionable class-level explanation and no resource identifier leaks into the surface",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-22104-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "Given a mocked 403 response with a per-resource cause, the permission-denied state renders inside role=\"region\" with a class-level cause string (matches /^[A-Za-z][A-Za-z0-9 ]+$/ with no digits-run of four or more) and a [data-action=\"request-access\"] control. The pack drives /probe/permission-denied, reads the cause string, and refuses when the string contains a resource-id shape (four or more consecutive digits, or a UUID pattern, or a slug-shape id preceded by resource identifiers like \"resource=\" or \"id=\")."
+    }
+  ],
+  "tacIds": [
+    "TAC-2301-application-empty-error-states-state-machine",
+    "TAC-2302-application-empty-error-states-recovery-router"
+  ],
+  "tags": [
+    "blueprint:application-empty-error-states",
+    "state:permission-denied"
+  ],
+  "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-22105.json

@@ -0,0 +1,29 @@
+{
+  "usId": "application-empty-error-states-US-22105",
+  "prdId": "PRD-001",
+  "reqId": "application-empty-error-states-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The offline state renders on navigator.onLine false, buffers a synthetic write, and announces reconnection through a polite live-region wrapper",
+  "asA": "operator whose network drops mid-session",
+  "iWant": "the offline state to render with a read-only banner, my writes to buffer locally with an idempotency token, and a polite reconnection announcement when the network comes back",
+  "soThat": "I keep working through a network drop and my writes flush cleanly with no duplicates when the network returns",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-22105-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "Given navigator.onLine simulated false via the runtime seam (page.setOffline(true) on the project route, an offline endpoint on the sample-app route the pack uses instead), the offline state renders inside role=\"region\" with a read-only banner naming offline mode. A synthetic write buffers to window.__offlineBuffer with an idempotency token and a monotonic sequence. On the reconnect signal (navigator.onLine true or the sample-app /probe/offline?reconnect route) the polite live-region wrapper with data-live-region=\"polite\" carries a reconnection announcement. The pack drives /probe/offline, reads the banner, the buffer entry and the polite wrapper text."
+    }
+  ],
+  "tacIds": [
+    "TAC-2301-application-empty-error-states-state-machine",
+    "TAC-2303-application-empty-error-states-offline-buffer"
+  ],
+  "tags": [
+    "blueprint:application-empty-error-states",
+    "state:offline"
+  ],
+  "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-22106.json

@@ -0,0 +1,29 @@
+{
+  "usId": "application-empty-error-states-US-22106",
+  "prdId": "PRD-001",
+  "reqId": "application-empty-error-states-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The empty-list state renders with a distinct visual and a creation-affordance recovery control",
+  "asA": "operator opening a listing surface that has no rows",
+  "iWant": "the empty-list state to render with a distinct visual and a creation-affordance recovery control",
+  "soThat": "I know the surface loaded successfully and my next action is to create the first row, not to reload",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-22106-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "Given a listing endpoint returning an empty array, the empty-list state renders inside role=\"region\" with a data-visual=\"empty-list\" wrapper (distinct from data-visual=\"loading\" and data-visual=\"loaded\") and a keyboard-reachable [data-recovery=\"create\"] control. The pack drives /probe/empty-list, reads the region and the wrapper attribute, and asserts the recovery control exists and carries an accessible name."
+    }
+  ],
+  "tacIds": [
+    "TAC-2301-application-empty-error-states-state-machine",
+    "TAC-2302-application-empty-error-states-recovery-router"
+  ],
+  "tags": [
+    "blueprint:application-empty-error-states",
+    "state:empty-list"
+  ],
+  "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-22107.json

@@ -0,0 +1,29 @@
+{
+  "usId": "application-empty-error-states-US-22107",
+  "prdId": "PRD-001",
+  "reqId": "application-empty-error-states-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The no-search-results state renders with a distinct visual and a clear-filters recovery control",
+  "asA": "operator running a search or filter that yields zero rows",
+  "iWant": "the no-search-results state to render with a distinct visual and a clear-filters recovery control",
+  "soThat": "I distinguish this state from empty-list and my next action is to widen the query, not to create a row",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-22107-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "Given a search or filter yielding zero rows, the no-search-results state renders inside role=\"region\" with a data-visual=\"no-search-results\" wrapper distinct from empty-list, echoing the query terms verbatim inside a data-query wrapper, and a keyboard-reachable [data-recovery=\"clear-filters\"] control that removes the search parameters on click. The pack drives /probe/search?q=needle, reads the region, the wrapper attribute, the echoed query and the recovery control."
+    }
+  ],
+  "tacIds": [
+    "TAC-2301-application-empty-error-states-state-machine",
+    "TAC-2302-application-empty-error-states-recovery-router"
+  ],
+  "tags": [
+    "blueprint:application-empty-error-states",
+    "state:no-search-results"
+  ],
+  "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-22108.json

@@ -0,0 +1,29 @@
+{
+  "usId": "application-empty-error-states-US-22108",
+  "prdId": "PRD-001",
+  "reqId": "application-empty-error-states-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The error-boundary state renders on a client-side render failure with a role=alert announcement",
+  "asA": "operator hitting a client-side render exception",
+  "iWant": "the error-boundary state to render inside role=\"alert\" with a retry recovery hook and no stack detail",
+  "soThat": "the assistive tech announces the failure immediately (assertive, not polite) and I have an escape from a broken render",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-22108-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "Given a synthetic client-side render exception thrown via page.evaluate (or the sample-app /probe/error-boundary?crash=1 route), the error-boundary state renders inside role=\"alert\" with a keyboard-reachable [data-recovery=\"retry\"] control, a plain summary line and no stack-frame content matching the sensitive-pattern list. The pack drives /probe/error-boundary?crash=1, reads the region, the retry control and the 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:error-boundary"
+  ],
+  "createdAt": "2026-09-06T15:40:00Z",
+  "updatedAt": "2026-09-06T15:40:00Z"
+}

package/blueprints/application-empty-error-states/docs/topics.md

@@ -0,0 +1,53 @@
+# application-empty-error-states: coordination vocabulary
+
+## Global topics
+
+The blueprint claims no new global topics at v1.0.0. Every ADR (HTTP status contract, stack-trace visibility, offline strategy) is non-global.
+
+## Deliberately unclaimed topics
+
+- `errorEnvelope` (the shape of a server error response body). Reserved for the applied API blueprint (`application-api-rest` claims it today); this blueprint reads the HTTP status code, not the envelope body shape, so no claim collides.
+- `sensitivePatternsRegistry` (the tokeniser vocabulary the 500 surface refuses on). Reserved for a future v1.1.0 minor bump if three or more consumer blueprints start elicitizing the same extensions. Held here as an unclaimed topic so a composing author sees the reservation.
+- `stateVisualTokens` (the palette, spacing and typography per state). Reserved for `application-spa` which owns the visual tokens; this blueprint owns the state list and the recovery-action router.
+
+## 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.
+
+## Composition with application-spa
+
+`application-spa` REQ-006 ships empty, loading, error, banner and alert components as part of its component library. Applying this blueprint alongside `application-spa` composes cleanly: SPA holds the tab-title convention and the state-visual tokens; this blueprint holds the state list, the recovery-action router and the runtime enforcement pack. No `scope: "global"` ADR conflict.
+
+## Composition with application-notifications-in-app
+
+The `forbidden` and `permission-denied` states POST request-access submissions to the applied notification centre. When `application-notifications-in-app` is applied, the pack asserts the applied notification centre receives the submission (a v1.1.0 mechanism-reach gap today; the current pack asserts the control's shape only). No global-topic overlap.
+
+## Probe pack
+
+`probe-packs/application-empty-error-states.pack.mjs` ships eight surface-observable checks anchored to blueprint AC ids, one per named state:
+
+- `AC-22101-1` not-found (heading, parent-surface link, search entry, tab title)
+- `AC-22102-1` forbidden (request-access control, no resource-id leak)
+- `AC-22103-1` server-error (retry, no stack trace, no path shape, no env-key shape)
+- `AC-22104-1` permission-denied (class-level cause, no resource id)
+- `AC-22105-1` offline (banner, buffered synthetic write, polite reconnection announcement)
+- `AC-22106-1` empty-list (distinct visual wrapper, creation-affordance recovery)
+- `AC-22107-1` no-search-results (distinct visual wrapper, echoed query, clear-filters recovery)
+- `AC-22108-1` error-boundary (role=alert, retry control, no stack detail)
+
+The pack applies to any FBS binding `TAC-2301-application-empty-error-states-state-machine` or whose navModel routes name an operator-configured error-shell path (matching `/probe/(not-found|forbidden|server-error|permission-denied|offline|empty-list|search|error-boundary)`). See `packages/rcf-lite/docs/blueprint-authoring.md` section 8c for the pack authoring rules.

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

@@ -0,0 +1,50 @@
+# application-empty-error-states: operator guide
+
+## When to reach for it
+
+Your project renders any surface whose input can be empty, whose network call can fail, whose user can lack scope, or whose client can crash mid-render. That covers every SPA that hits an API and every routed page that can dereference an id. You want one contract for the eight named states, one recovery-action router per state, one polite live-region for progress announcements, and a runtime pack that refuses ship on a stack-trace leak, a resource-id leak, a missing recovery affordance, or a dropped live-region wrapper.
+
+## The eight named states
+
+The blueprint enumerates the eight states in the ratified order below. Every README, guide, pack `checks[]` and `docs/topics.md` row across the family names the same eight slugs.
+
+- `not-found`: routed page dereferences an id that has been removed or was never there.
+- `forbidden`: caller is authenticated but the target resource refuses; the surface offers a request-access affordance.
+- `server-error`: a 500-class failure the client cannot recover from without a retry.
+- `offline`: the client has lost the network; the surface announces the transition and, on reconnection, replays it through the polite live-region wrapper.
+- `permission-denied`: the caller lacks a scope the target resource requires; the surface names the missing scope in the cause without leaking the resource id.
+- `empty-list`: a collection surface has zero rows and offers the recovery-action router entry (create, clear filters, or invite, per project wiring).
+- `no-search-results`: a query returned an empty set; the surface echoes the query verbatim and suggests broadening it.
+- `error-boundary`: a client-side render exception was caught; the surface renders under `role="alert"` and offers a route-level recovery.
+
+## When NOT to reach for it
+
+Your product is a marketing site or a static content surface with no dynamic state. The eight states model a live workspace; a static site has no offline mode, no per-resource forbidden state, no client-side render boundary, and forcing the model on a static site adds mechanism without payoff.
+
+Your product has already committed to an opinionated single-vendor state library (Sentry with a bespoke boundary, a framework-specific error module) whose contract is materially different from the eight-state catalogue. Adopt this blueprint only when the vendor library composes with the state-machine TAC rather than replacing it.
+
+## What stays your call
+
+- The visual design of each state region. The blueprint contributes WHAT surfaces under WHAT condition; the palette, spacing and typography are your project's design system's call.
+- Whether the 500 surface hides the stack trace in staging (ADR-2302 elicited toggle) or hides it everywhere (the recommended default).
+- The offline strategy: write-buffer (the default), read-only-banner, or refuse-writes (ADR-2303 elicited enum).
+- The request-access endpoint the forbidden and permission-denied surfaces POST to. The blueprint declares the shape (`POST /api/request-access` with a JSON body); the endpoint's server-side handling is your call.
+- The parent-surface path and clear-filters callback the recovery-action router wires into the rendered controls.
+
+## What a good outcome looks like
+
+The pack fires on every FBS whose surface renders a routed page or a listing, and every check returns `pass` on the honest render and `fail` on the corresponding break switch. Your CI runs the fixture round-trip on every PR that touches a state region. Your operator sees eight distinct visuals in a screenshot review and can pick out which state a screenshot represents without reading the copy. Your accessibility audit's live-region check on the polite wrapper passes because the wrapper preseeded at page render, not on state entry. Your production 500 surface never leaks a source path, an environment variable, or a backtrace frame.
+
+## 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. Combine with `application-notifications-in-app` to route request-access submissions through the shipped notification centre and with `application-spa` to inherit the tab-title convention and the state-visual tokens.
+
+## Promotion signals
+
+- Three or more consumer blueprints (forms-wizard, account-settings, dashboard, admin-console) start elicitizing the same sensitive-pattern extension for the 500 surface. Candidate: a `sensitivePatternsRegistry` global topic in a v1.1.0 minor.
+- The offline-buffer TAC needs a shared engine across a persistence blueprint and this UI blueprint. Candidate: a dedicated `application-offline-sync` blueprint absorbing the write-buffer.
+- The recovery-shape enum needs a request-access-inline shape (inline form rather than a POST). Candidate: a v1.1.0 minor bump extending TAC-2302's recovery-shape closed set.
+
+## Costs to be honest about
+
+Realising all eight states honestly in a client is a chunk of code even after adopting the TACs; project-side wiring per framework is at least an afternoon per state. The pack is Playwright-first, so a project without a running dev server at gate time cannot fire it. The offline TAC assumes IndexedDB by default; a WebView with a locked-down storage policy elicits an alternative per ADR-2303 and takes a small amount of adapter code.