rcf-lite 0.20.0 → 0.22.0

package/blueprints/application-file-upload/contributions/user-stories/application-file-upload-us-23103.json

@@ -0,0 +1,29 @@
+{
+  "usId": "application-file-upload-US-23103",
+  "prdId": "PRD-001",
+  "reqId": "application-file-upload-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A refused file renders an aria-describedby-bound error and moves focus to its retry control, without sending the bytes",
+  "asA": "operator whose selected file is refused by the MIME gate, the size gate or the virus scanner",
+  "iWant": "an inline error that names the refusal reason, is bound to my file row via aria-describedby, and moves my focus to the retry control without sending the file to the server",
+  "soThat": "I learn why the file was refused, do not waste my upload budget on a refused file, and can retry with a corrected file from my keyboard",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-23103-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "When the fixture is seeded with a refused file (MIME mismatch, size cap exceeded, or virus-scan hit), the file row [data-file-row][data-refused=\"true\"] renders a [data-error-message] element whose id is referenced by the row's aria-describedby attribute, the row exposes the closed refusal reason via [data-refusal-reason] (one of mime-refused, size-refused, virus-refused), a [data-recovery=\"retry\"] control receives keyboard focus, and the pack observes zero POST or PATCH requests carrying the refused filename on the browser's request log."
+    }
+  ],
+  "tacIds": [
+    "TAC-2401-application-file-upload-input",
+    "TAC-2402-application-file-upload-transport"
+  ],
+  "tags": [
+    "blueprint:application-file-upload",
+    "affordance:refusal"
+  ],
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

package/blueprints/application-file-upload/contributions/user-stories/application-file-upload-us-23104.json

@@ -0,0 +1,28 @@
+{
+  "usId": "application-file-upload-US-23104",
+  "prdId": "PRD-001",
+  "reqId": "application-file-upload-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The transport uploads files in chunks and, on the tus.io branch, exposes an Upload-Offset header per PATCH",
+  "asA": "operator uploading a large file over a spotty connection",
+  "iWant": "the transport to split my file into chunks and to resume from the last acknowledged offset on retry",
+  "soThat": "an interrupted upload does not re-send bytes I already delivered",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-23104-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "On the ?transport=multipart branch the fixture returns 200 with a completed chunk count higher than 1 on a file large enough to force chunking; the DOM exposes [data-transport=\"multipart\"] and [data-chunks-uploaded] whose numeric value equals the completed chunk count. On the ?transport=tus branch the pack observes at least one PATCH request on the browser's network log whose request headers include Upload-Offset with a numeric value, and the DOM exposes [data-transport=\"tus\"] with [data-chunks-uploaded] > 1."
+    }
+  ],
+  "tacIds": [
+    "TAC-2402-application-file-upload-transport"
+  ],
+  "tags": [
+    "blueprint:application-file-upload",
+    "affordance:chunked-resumable"
+  ],
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

package/blueprints/application-file-upload/contributions/user-stories/application-file-upload-us-23105.json

@@ -0,0 +1,29 @@
+{
+  "usId": "application-file-upload-US-23105",
+  "prdId": "PRD-001",
+  "reqId": "application-file-upload-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "On successful completion the upload surface renders an assertive-slot announcement and per-file remove and retry controls",
+  "asA": "operator whose upload set has just finished",
+  "iWant": "an assertive-slot announcement saying how many files uploaded successfully, plus a keyboard-reachable remove control per completed file",
+  "soThat": "my screen reader tells me the set is done and I can remove a file I no longer want without a page reload",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-23105-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "After the fixture completes the upload set the upload region carries a [data-assertive-slot] element with aria-live=\"assertive\" or role=\"status\" whose textContent matches /^\\d+ files uploaded successfully$/, each completed file row carries [data-file-row][data-file-state=\"complete\"], a keyboard-reachable [data-recovery=\"remove\"] button per row and, after a refused-then-succeeded row, a [data-recovery=\"retry\"] button visible only until the retry succeeds."
+    }
+  ],
+  "tacIds": [
+    "TAC-2401-application-file-upload-input",
+    "TAC-2403-application-file-upload-progress-announcer"
+  ],
+  "tags": [
+    "blueprint:application-file-upload",
+    "affordance:completion"
+  ],
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

package/blueprints/application-file-upload/contributions/user-stories/application-file-upload-us-23106.json

@@ -0,0 +1,28 @@
+{
+  "usId": "application-file-upload-US-23106",
+  "prdId": "PRD-001",
+  "reqId": "application-file-upload-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A network interruption mid-upload resumes from the last acknowledged offset when the connection returns",
+  "asA": "operator uploading through a spotty connection or a captive portal that drops mid-request",
+  "iWant": "the transport to pause on interruption, wait for the connection to return, and resume from the last acknowledged offset without re-sending",
+  "soThat": "a dropped connection does not force me to restart a large upload",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-23106-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "On the ?interrupt=1 branch of the fixture the upload pauses after the first acknowledged chunk, the DOM exposes [data-file-state=\"paused\"] and [data-chunks-uploaded] with a numeric value greater than zero on the paused row, and after the fixture resumes with ?resume=1 the row transitions to [data-file-state=\"complete\"] with the accumulated [data-chunks-uploaded] equal to the total chunk count. The pack asserts no chunk index is re-uploaded (the fixture records the received offsets on the row and never repeats one)."
+    }
+  ],
+  "tacIds": [
+    "TAC-2402-application-file-upload-transport"
+  ],
+  "tags": [
+    "blueprint:application-file-upload",
+    "affordance:resumption"
+  ],
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

package/blueprints/application-file-upload/contributions/user-stories/application-file-upload-us-23107.json

@@ -0,0 +1,28 @@
+{
+  "usId": "application-file-upload-US-23107",
+  "prdId": "PRD-001",
+  "reqId": "application-file-upload-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Progress continues to advance and the polite live-region continues to tick when the browser tab is backgrounded",
+  "asA": "operator who tabs away from the upload while it is running",
+  "iWant": "the upload to continue and the polite live-region to keep receiving ticks so a screen reader can pick up the announcement when I return",
+  "soThat": "backgrounding the tab does not stall the upload or my accessibility affordance",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-23107-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "On the ?background=1 branch of the fixture the fixture drives a visibilitychange event to hidden, the upload continues (the aggregate percent advances between two polite-tick reads separated by at least one polling interval), and the [data-live-region=\"polite\"] wrapper's text updates. The pack reads the wrapper twice with a wait between and asserts the aggregate percent increased and the tick text changed."
+    }
+  ],
+  "tacIds": [
+    "TAC-2403-application-file-upload-progress-announcer"
+  ],
+  "tags": [
+    "blueprint:application-file-upload",
+    "affordance:background-tab-progress"
+  ],
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

package/blueprints/application-file-upload/docs/topics.md

@@ -0,0 +1,58 @@
+# application-file-upload: coordination vocabulary
+
+## Global topics
+
+The blueprint claims no new global topics at v1.0.0. Every ADR (transport branch, accepted set, virus-scan integration) is non-global.
+
+## Deliberately unclaimed topics
+
+- `uploadEnvelope` (the shape of an upload success or completion response body). Reserved for the applied API blueprint (`application-api-rest` claims it today); this blueprint reads the wire-level chunk acknowledgements, not the envelope body shape, so no claim collides.
+- `commonAcceptedSets` (a shelf-wide registry of accepted MIME sets a consumer can reach for). Reserved for a future v1.1.0 minor bump if three or more consumer blueprints start elicitizing the same lists. Held here as an unclaimed topic so a composing author sees the reservation.
+- `objectStorageTransport` (a shared engine for the chunked-and-resumable transport that both an object-storage blueprint and this UI blueprint would reach for). Reserved for a future dedicated `application-file-transport` blueprint; held here so a composing author sees the reservation before minting a new topic.
+- `announcementFormatsCatalogue` (the localised polite and assertive text formats). Reserved for a v1.1.0 minor bump extending the announcer TAC's `announcementFormatsEnum` with a lookup table.
+
+## 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 upload and progress and error components as part of its component library. Applying this blueprint alongside `application-spa` composes cleanly: SPA holds the visual tokens for the upload region; this blueprint holds the input affordances, the transport contract, the refusal contract and the runtime enforcement pack. No `scope: "global"` ADR conflict.
+
+## Composition with application-empty-error-states
+
+A refused upload is a refusal contract state, not an empty or error state; the two blueprints do not overlap on state slugs. A transport-level failure (server 5xx during a chunk PATCH) surfaces through `application-empty-error-states`'s server-error state after the transport's retry budget is exhausted. No global-topic overlap.
+
+## Composition with application-error-handling
+
+Refusals and transport-layer failures construct an internal error record through the applied error-handling factory (`suggestedCompanions: errorHandling`). This blueprint reads the factory's shape; `application-error-handling` owns the shape and its correlation-identifier discipline.
+
+## The four fixture states and the two transport slugs
+
+The four state slugs `idle`, `uploading`, `refused`, `complete` and the two transport slugs `multipart`, `tus` appear identically across the blueprint README, the fixture README, the operator guide, the probe pack `checks[]` descriptions and this file. Extending either enum is a v1.1.0 minor bump; removing or renaming is a v2.0.0 major.
+
+## Probe pack
+
+`probe-packs/application-file-upload.pack.mjs` ships four surface-observable checks anchored to blueprint AC ids, one per contract:
+
+- `AC-23101-1` input surface (file input, drop-zone, keyboard-focusable opener)
+- `AC-23102-1` progress announcer (polite tick format and monotonic advance)
+- `AC-23103-1` refusal contract (aria-describedby error binding, refused bytes never on the wire)
+- `AC-23104-1` chunked transport (multipart chunks or tus Upload-Offset)
+
+The pack applies to any FBS binding `TAC-2401-application-file-upload-input` or whose navModel routes name an operator-configured upload path (matching `/upload`). See `packages/rcf-lite/docs/blueprint-authoring.md` section 8c for the pack authoring rules.

package/blueprints/application-file-upload/guide/application-file-upload.md

@@ -0,0 +1,48 @@
+# application-file-upload: operator guide
+
+## When to reach for it
+
+Your project accepts file uploads from operators, whether one file at a time or a set, whether small text and image assets or large media. You want one contract for the input surface (labelled input plus drop-zone plus keyboard opener per WCAG 2.5.7), one recommended transport that ships resumable-chunked out of the box, one refusal contract that binds errors via `aria-describedby` and never lets refused bytes reach the server, one polite live-region tick that keeps a screen-reader user informed of progress, and a runtime pack that refuses ship on a dropped input, a dropped live-region, a refused file that reached the wire, or a collapsed transport.
+
+## The two transports
+
+The two shipped transport slugs are `multipart` and `tus`. `multipart` is the recommended default (ADR-2401 `recommendedDefault: true`) because every server toolkit accepts it and the client-side code is a Blob split into fixed-size chunks. `tus` is the elicited alternative for projects with a tus server or the third-party tus client library; on the tus branch each chunk is a PATCH request with an `Upload-Offset` header the pack asserts. A third alternative, `vendor-sdk` (S3 multipart, Cloudflare R2 client-direct, Cloudinary widget), is documented in ADR-2401 for projects committed to a vendor; the shipped fixture does not exercise it, and a vendor-sdk project runs the pack against a fixture that mocks the vendor's completion callback.
+
+## The four file-row states
+
+The four shipped state slugs are `idle`, `uploading`, `refused`, `complete`. Every file row on the fixture cycles through this closed set; the same slugs ride `[data-file-state]` on the file row in your applied project. Extending the state set is a v1.1.0 minor bump; removing or renaming a state is a v2.0.0 major.
+
+## When NOT to reach for it
+
+Your product is a marketing site or a static content surface that never accepts an upload. The four contracts model a live upload surface; a static site has no transport, no progress tick, no refusal contract, and forcing the model on a static site adds mechanism without payoff.
+
+Your product has already committed to an opinionated single-vendor upload widget (Uppy with a specific backend, Filepond with a specific plugin set) whose contract is materially different from the input plus refusal plus progress catalogue. Adopt this blueprint only when the vendor widget composes with the input TAC's `collectFiles` factory rather than replacing it.
+
+## What stays your call
+
+- The visual design of the upload region, the file rows and the drop-zone. The blueprint contributes WHAT surfaces under WHAT condition; the palette, spacing and typography are your project's design system's call.
+- The accepted MIME set (ADR-2402 elicited enum). No default; every project elicits its own list of IANA media types.
+- The per-file size cap in bytes (ADR-2402 elicited). No default; every project elicits its own cap.
+- The transport branch (ADR-2401 elicited). Recommended `multipart`; elicit `tus` when a tus server is available or the third-party SDK is on the path; elicit `vendor-sdk` when a vendor SDK is on the path.
+- The virus-scan verifier (ADR-2403 capability-plus-elicit). Every project elicits the verifier or the explicit noop; there is no shelf default and the guide names the risk in plain language for the noop path.
+- The concurrency cap for the transport worker pool. Recommended default 3; a slow-link project elicits a lower cap.
+- The announcer polling interval in milliseconds. Recommended default 250; a project sensitive to CPU cost on a hot page elicits a higher interval.
+- The upload endpoint URL. The blueprint declares the shape (`POST /api/upload/chunk` for multipart, `POST /api/upload/tus` for the tus creation URL); the endpoint's server-side handling is your call.
+
+## What a good outcome looks like
+
+The pack fires on every FBS whose surface renders an upload route, and every check returns `pass` on the honest render (both transport branches) and `fail` on the corresponding break switch. Your CI runs the fixture round-trip on every PR that touches an upload surface. Your operator uploads a file with the keyboard alone and hears the polite tick as it advances. Your production upload surface never lets a refused file's bytes leave the browser. Your production stack ships with an explicit virus-scan verifier or with the noop plus the guide's risk paragraph on file.
+
+## Mechanism-reach gaps
+
+The blueprint's README lists the runtime-observable ACs the pack does NOT bind directly (drop-event round-trip, screen-reader adoption, error-message content, network-interruption resume on multipart, assertive-slot exclusive fire, network interruption resumption, background-tab tick continuity). Every gap is a candidate for a v1.1.0 minor bump extending the pack. Combine with `application-error-handling` to route refusal internal error records through the shipped factory and with `application-spa` to inherit the visual tokens.
+
+## Promotion signals
+
+- Three or more consumer blueprints (forms-wizard, an eventual CSV-import, account-settings avatar upload) start elicitizing the same accepted-set entries. Candidate: a `commonAcceptedSets` global topic in a v1.1.0 minor.
+- The transport TAC needs a shared engine across an object-storage blueprint and this UI blueprint. Candidate: a dedicated `application-file-transport` blueprint absorbing the chunked-and-resumable path.
+- Localisation of the polite and assertive text formats. Candidate: a v1.1.0 minor bump extending the announcer TAC's `announcementFormatsEnum` with a lookup table.
+
+## Costs to be honest about
+
+Realising all three input affordances honestly in a client is a chunk of code even after adopting the TACs; the WCAG 2.5.7 keyboard alternative is often the piece a first cut skips. The pack is Playwright-first, so a project without a running dev server at gate time cannot fire it. The tus branch assumes a tus server or the third-party client; a project that elicits tus without one hits an apply-time refusal on the elicit and unblocks by wiring one in or falling back to multipart.

package/blueprints/application-file-upload/probe-packs/application-file-upload.pack.mjs

@@ -0,0 +1,238 @@
+// application-file-upload probe pack (v1.0.0).
+//
+// Four surface-observable checks, one per contract, anchored to the
+// blueprint's contributed AC ids:
+//   AC-23101-1 input surface       (file input, drop-zone, keyboard-opener)
+//   AC-23102-1 progress announcer  (polite tick format + monotonic advance)
+//   AC-23103-1 refusal contract    (aria-describedby, no bytes for refused)
+//   AC-23104-1 chunked transport   (multipart chunks OR tus Upload-Offset)
+//
+// Every check drives the real Playwright browser the T-0 runner
+// injects. URLs are composed by the withUrl(runtimeUrl, path) helper
+// per the round 3 T-3 fix train; no bare string concatenation.
+//
+// Sample-app fixture:
+// packages/rcf-lite/test/fixtures/probe-pack-application-file-upload/
+// Fixture ships /upload with a ?transport=multipart default and a
+// ?transport=tus alternative plus break switches (?break=no-input,
+// ?break=no-live-region, ?break=send-refused, ?break=no-chunks) so
+// the negative runs can be driven from a single boot.
+
+function withUrl(runtimeUrl, path) {
+  return new URL(path, runtimeUrl).toString();
+}
+
+// Progress tick format the announcer TAC pins per ADR-2402:
+//   "<uploaded> of <total> files, <PP> percent"
+const POLITE_FORMAT = /^\d+ of \d+ files, \d{1,3} percent$/;
+
+export default {
+  packName: 'application-file-upload',
+  version: '1.0.0',
+  blueprintSlug: 'application-file-upload',
+  // Applies to any FBS that binds the input TAC or whose navModel
+  // routes name the operator-configured upload path. References BOTH
+  // `tacIds` AND `route` per the loader source-scan rule (T-0
+  // AC-1701-3, cross-check with authoring standard 8c).
+  appliesTo: ({ fbs }) => {
+    const routes = fbs?.designStage?.navModel?.routes ?? [];
+    const tacIds = fbs?.contextRequirements?.tacIds ?? [];
+    if (tacIds.includes('TAC-2401-application-file-upload-input')) return true;
+    return routes.some((r) => typeof r?.path === 'string' && /\/upload(\/|$|\?)/.test(r.path));
+  },
+  boot: { bootCommand: null, waitForUrl: null, waitForSelector: null },
+  checks: [
+    {
+      id: 'AC-23101-1',
+      severity: 'block',
+      description: 'input surface renders a labelled file input, a drop-zone region and a keyboard-focusable opener that opens the picker on Enter (WCAG 2.5.7)',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/upload'));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="file-upload"]');
+          if (!region) return { present: false };
+          const fileInput = region.querySelector('input[type="file"]');
+          const dropZone = region.querySelector('[data-drop-zone]');
+          const opener = region.querySelector('[data-open-picker]');
+          const inputId = fileInput ? fileInput.id : null;
+          const label = inputId ? document.querySelector(`label[for="${inputId}"]`) : null;
+          const ariaLabel = fileInput ? fileInput.getAttribute('aria-label') : null;
+          const openerFocusable = opener ? opener.tabIndex >= 0 || opener.tagName === 'BUTTON' : false;
+          return {
+            present: true,
+            hasFileInput: !!fileInput,
+            hasDropZone: !!dropZone,
+            hasOpener: !!opener,
+            openerFocusable,
+            hasLabel: !!label,
+            hasAriaLabel: !!ariaLabel,
+          };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'upload region [data-surface="file-upload"] not found' };
+        if (!dom.hasFileInput) return { verdict: 'fail', detail: 'upload region missing input[type="file"]' };
+        if (!dom.hasDropZone) return { verdict: 'fail', detail: 'upload region missing [data-drop-zone]' };
+        if (!dom.hasOpener) return { verdict: 'fail', detail: 'upload region missing keyboard [data-open-picker] control (WCAG 2.5.7: drop-zone must not be the only path)' };
+        if (!dom.openerFocusable) return { verdict: 'fail', detail: '[data-open-picker] control not keyboard-focusable' };
+        if (!dom.hasLabel && !dom.hasAriaLabel) return { verdict: 'fail', detail: 'file input carries neither an associated <label> nor aria-label' };
+        return { verdict: 'pass', detail: 'file input, drop-zone and keyboard opener present; accessible name bound' };
+      },
+    },
+    {
+      id: 'AC-23102-1',
+      severity: 'block',
+      description: 'progress announcer emits a polite tick in the closed format and the aggregate percent advances monotonically during an upload',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/upload?transport=multipart&autostart=1&seed=demo'));
+        // Read the polite wrapper twice with the fixture's polling
+        // interval between so we can prove monotonic advance.
+        const firstRead = await browser.evaluate(() => {
+          const live = document.querySelector('[data-live-region="polite"]');
+          const row = document.querySelector('[data-file-row] [data-file-progress]');
+          return {
+            text: live ? live.textContent.trim() : null,
+            ariaLive: live ? live.getAttribute('aria-live') : null,
+            rowPercent: row ? Number(row.getAttribute('aria-valuenow') ?? row.textContent.trim()) : null,
+          };
+        });
+        // Fixture ticks every ~150ms; poll for advance.
+        const secondRead = await browser.evaluate(async () => {
+          await new Promise((r) => setTimeout(r, 400));
+          const live = document.querySelector('[data-live-region="polite"]');
+          const row = document.querySelector('[data-file-row] [data-file-progress]');
+          return {
+            text: live ? live.textContent.trim() : null,
+            rowPercent: row ? Number(row.getAttribute('aria-valuenow') ?? row.textContent.trim()) : null,
+          };
+        });
+        if (!firstRead.text) return { verdict: 'fail', detail: '[data-live-region="polite"] wrapper missing' };
+        if (firstRead.ariaLive !== 'polite') return { verdict: 'fail', detail: `[data-live-region="polite"] wrapper aria-live expected "polite", got ${JSON.stringify(firstRead.ariaLive)}` };
+        if (!POLITE_FORMAT.test(firstRead.text)) {
+          return { verdict: 'fail', detail: `polite tick text did not match /^\\d+ of \\d+ files, \\d{1,3} percent$/: ${JSON.stringify(firstRead.text)}` };
+        }
+        if (firstRead.rowPercent == null || Number.isNaN(firstRead.rowPercent)) {
+          return { verdict: 'fail', detail: 'per-file [data-file-progress] not present or not numeric' };
+        }
+        if (secondRead.rowPercent == null || secondRead.rowPercent < firstRead.rowPercent) {
+          return { verdict: 'fail', detail: `aggregate progress did not advance monotonically: first=${firstRead.rowPercent}, second=${secondRead.rowPercent}` };
+        }
+        return { verdict: 'pass', detail: `firstTick=${JSON.stringify(firstRead.text)} firstRow=${firstRead.rowPercent} secondRow=${secondRead.rowPercent}` };
+      },
+    },
+    {
+      id: 'AC-23103-1',
+      severity: 'block',
+      description: 'a refused file renders an aria-describedby-bound error, moves focus to the retry control, and is never sent to the server',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/upload?transport=multipart&seed=refused'));
+        const dom = await browser.evaluate(async () => {
+          // Wait for the upload loop to run to completion (or for
+          // the deadline). We can't read the request log honestly
+          // before the loop has had a chance to run: on the
+          // ?break=send-refused negative branch the refused row's
+          // bytes only land after the loop reaches that row. The
+          // fixture completes a two-file demo set in roughly
+          // 2 * 3 * 120ms + jitter = ~800ms.
+          const deadline = Date.now() + 3000;
+          while (Date.now() < deadline) {
+            const slot = document.querySelector('[data-assertive-slot]');
+            if (slot && slot.textContent && slot.textContent.trim().length > 0) break;
+            await new Promise((r) => setTimeout(r, 100));
+          }
+          const region = document.querySelector('[data-surface="file-upload"]');
+          if (!region) return { present: false };
+          const row = region.querySelector('[data-file-row][data-refused="true"]');
+          if (!row) return { present: true, hasRefusedRow: false };
+          const describedBy = row.getAttribute('aria-describedby');
+          const errId = describedBy ? describedBy.split(/\s+/)[0] : null;
+          const err = errId ? row.querySelector(`#${CSS.escape(errId)}`) || document.getElementById(errId) : null;
+          const reason = row.getAttribute('data-refusal-reason');
+          const retry = row.querySelector('[data-recovery="retry"]');
+          const network = Array.isArray(window.__uploadRequestLog) ? window.__uploadRequestLog : [];
+          const refusedFilename = row.getAttribute('data-refused-filename') || null;
+          const sentRefused = refusedFilename
+            ? network.some((r) => r && typeof r.body === 'string' && r.body.includes(refusedFilename))
+            : false;
+          return {
+            present: true,
+            hasRefusedRow: true,
+            hasErr: !!err,
+            errText: err ? err.textContent.trim() : null,
+            reason,
+            hasRetry: !!retry,
+            refusedFilename,
+            sentRefused,
+            network,
+          };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'upload region not found' };
+        if (!dom.hasRefusedRow) return { verdict: 'fail', detail: 'no [data-file-row][data-refused="true"] on the refused seed' };
+        if (!dom.hasErr) return { verdict: 'fail', detail: 'refused row aria-describedby does not resolve to a [data-error-message] element' };
+        const allowedReasons = ['mime-refused', 'size-refused', 'virus-refused'];
+        if (!allowedReasons.includes(dom.reason)) {
+          return { verdict: 'fail', detail: `refused row [data-refusal-reason] expected one of ${JSON.stringify(allowedReasons)}, got ${JSON.stringify(dom.reason)}` };
+        }
+        if (!dom.hasRetry) return { verdict: 'fail', detail: 'refused row missing [data-recovery="retry"] control' };
+        if (dom.sentRefused) {
+          return { verdict: 'fail', detail: `refused filename ${JSON.stringify(dom.refusedFilename)} appears in the upload request log` };
+        }
+        return { verdict: 'pass', detail: `reason=${JSON.stringify(dom.reason)} err=${JSON.stringify(dom.errText)} no refused bytes on the wire (${dom.network.length} recorded upload requests)` };
+      },
+    },
+    {
+      id: 'AC-23104-1',
+      severity: 'block',
+      description: 'the transport uploads in chunks; on the tus branch each PATCH request carries Upload-Offset, on the multipart branch [data-chunks-uploaded] on the DOM exceeds one',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        // Read the transport preference off the base runtimeUrl's own
+        // query string (the withUrl helper resolves a fresh path
+        // against the base, which drops the query). The pack anchors
+        // on the base URL's ?transport= so a caller running the tus
+        // branch passes --url http://.../upload?transport=tus and the
+        // pack observes it here.
+        let configuredTransport = null;
+        try { configuredTransport = new URL(runtimeUrl).searchParams.get('transport'); } catch { /* runtimeUrl may be a bare path in tests */ }
+        const transport = configuredTransport === 'tus' ? 'tus' : 'multipart';
+        await browser.goto(withUrl(runtimeUrl, `/upload?transport=${transport}&seed=large&autostart=1`));
+        const dom = await browser.evaluate(async () => {
+          // Wait for the upload to complete (or for the deadline).
+          // The pack needs to observe the final chunk count, not the
+          // first: an early break at chunks > 0 would read 1 and
+          // spuriously fail the chunked-upload assertion on a fast
+          // fixture. The fixture completes a 5-chunk upload in
+          // roughly 5 * 120ms = 600ms.
+          const deadline = Date.now() + 3000;
+          while (Date.now() < deadline) {
+            const row = document.querySelector('[data-file-row]');
+            const state = row ? row.getAttribute('data-file-state') : null;
+            if (state === 'complete') break;
+            await new Promise((r) => setTimeout(r, 100));
+          }
+          const row = document.querySelector('[data-file-row]');
+          const region = document.querySelector('[data-surface="file-upload"]');
+          const transportAttr = region ? region.getAttribute('data-transport') : null;
+          const chunksUploaded = row ? Number(row.getAttribute('data-chunks-uploaded') ?? '0') : 0;
+          const patchOffsets = Array.isArray(window.__tusPatchOffsets) ? window.__tusPatchOffsets : [];
+          return { transportAttr, chunksUploaded, patchOffsets };
+        });
+        if (dom.transportAttr !== transport) {
+          return { verdict: 'fail', detail: `upload region [data-transport] expected ${JSON.stringify(transport)}, got ${JSON.stringify(dom.transportAttr)}` };
+        }
+        if (dom.chunksUploaded < 2) {
+          return { verdict: 'fail', detail: `[data-chunks-uploaded] expected > 1 (chunked upload), got ${dom.chunksUploaded}` };
+        }
+        if (transport === 'tus') {
+          const numeric = dom.patchOffsets.filter((v) => typeof v === 'number' && Number.isFinite(v));
+          if (numeric.length === 0) {
+            return { verdict: 'fail', detail: `no PATCH request recorded with a numeric Upload-Offset header (window.__tusPatchOffsets=${JSON.stringify(dom.patchOffsets)})` };
+          }
+          return { verdict: 'pass', detail: `tus branch: chunks=${dom.chunksUploaded}, Upload-Offset headers=${JSON.stringify(numeric)}` };
+        }
+        return { verdict: 'pass', detail: `multipart branch: chunks=${dom.chunksUploaded}` };
+      },
+    },
+  ],
+};

package/blueprints/application-forms-wizard/CHANGELOG.md

@@ -0,0 +1,9 @@
+# application-forms-wizard CHANGELOG
+
+## 1.0.0 (visual round T-3, spec 2026-09-06)
+
+- First ratified version of the shelf's forms-wizard blueprint. Five REQs (task-list contract with the closed GOV.UK vocabulary Cannot start yet, Not started, In progress, Completed and an ARIA progressbar wrapper; per-step validation timing with on-blur before first submit then on-change after first failure and a full pass on submit reusing SPA forms-engine TAC-205; error-summary contract with a top-of-page summary, skip links, aria-invalid on the field, aria-describedby to the field-level message and focus moved to the summary heading; summary-review contract with a summary-list per step, Change links per row and answer retention on save; save-and-return contract with a server-side draft table or a client-side local buffer with a sync tick, refuses to ship if neither is wired), eight USs 24101 to 24108 binding one runtime-observable AC per contract plus three cross-cutting cases (linear-vs-free navigation, in-progress list, no-in-progress empty state delegated to application-empty-error-states), three TACs 2501 to 2503 (task-list shell, error-summary contract, draft store), three ADRs 2501 to 2503 (navigation posture linear default with elicited free branch, save-and-return transport with no recommendedDefault so the abandoned-draft loss class does not ship silently, step-indicator shape with task-list default and elicited ARIA progressbar-only or breadcrumb). No new global topics.
+- Ships `probe-packs/application-forms-wizard.pack.mjs`: four surface-observable browser-verify checks anchored one per core contract (`AC-24101-1` task-list, `AC-24103-1` error-summary, `AC-24104-1` summary-review, `AC-24105-1` save-and-return). Every URL is composed by the `withUrl(runtimeUrl, path)` helper per the round 3 T-3 fix train; no bare string concatenation. The pack-level `appliesTo` predicate references BOTH `tacIds` (TAC-2501) AND `route` (the operator-configured wizard-route glob).
+- Ships a dependency-free sample-app fixture at `packages/rcf-lite/test/fixtures/probe-pack-application-forms-wizard/` with a Node HTTP server realising the four wizard surfaces honestly (`/task-list`, `/step/<n>`, `/summary`, `/in-progress`), both save-and-return transports on their query branches (`?draft-store=server` default posting to `/drafts`, `?draft-store=local` writing to `localStorage` with a sync tick), and four break switches (`?break=task-list-vocab`, `?break=no-summary`, `?break=no-retain`, `?break=no-draft`) driving the negative runs from a single boot. The fixture ships its own README naming PORT, every `?step=`, `?draft-store=`, `?nav=`, `?seed=`, `?refused=`, `?preseed=`, `?edit=`, every `?break=`, the manual boot line and the two-line gate-reviewer boot.
+- Declares `suggestedCompanions` `logging` (every step transition, validation failure and save-and-return event writes one request-scoped log line with the correlation identifier and the step slug) and `errorHandling` (the error-summary contract constructs an internal error record per failed field through the applied error-handling factory). Does NOT declare `providesRoles` (leaf blueprint per spec). Does NOT declare `capabilities` and does NOT declare `requiresAppliedCapabilities` (no auth required).
+- Consumes `application-empty-error-states` for the no-in-progress empty state on the /in-progress list surface; the wizard's TAC-2503 delegates the zero-drafts case to the sibling's empty-list state and reads `[data-surface="empty-list"]` with a `[data-recovery="create"]` control from the sibling. T-4 `application-account-settings` will consume this blueprint for its multi-part account setup flow and the summary-review confirm-before-save gate.

package/blueprints/application-forms-wizard/README.md

@@ -0,0 +1,102 @@
+# Forms wizard blueprint (v1.0.0)
+
+Vendor-neutral multi-step forms wizard contract for an rcf-lite application. Ships the GOV.UK Design System task-list pattern with a per-step completion state from the closed vocabulary (Cannot start yet, Not started, In progress, Completed), an ARIA progressbar wrapper on the task-list surface, the per-step validation timing rule (on-blur before first submit, on-change after first failure, full pass on submit), the top-of-page error-summary contract with skip links plus aria-invalid plus focus-to-heading on submit failure, the summary-review pattern with change-per-row and answer retention across an edit-and-save round-trip, and the save-and-return contract with a server-side draft table or a client-side local buffer with a sync tick. Ships a Playwright probe pack under `probe-packs/application-forms-wizard.pack.mjs` whose four checks each anchor one core contract, 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-forms-wizard
+```
+
+Applies 19 contributions (5 REQs, 8 USs, 3 TACs, 3 ADRs) cleanly on any fresh init project. No `requiresAppliedCapabilities`, no auth prerequisite. The three elicits (ADR-2501 navigation posture with recommendedDefault linear, ADR-2502 save-and-return transport with no recommendedDefault, ADR-2503 step-indicator shape with recommendedDefault task-list) either ship recommended defaults so the apply proceeds silently, or (ADR-2502 alone) require a project answer at apply time because the abandoned-draft loss class is genuinely per-project.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version 1.0.0, category `application`, `suggestedCompanions: [logging, errorHandling]`, 19 contributions in the 24xxx / 25xx band |
+| Doc set | `contributions/` | 5 REQs, 8 USs (each carrying one runtime-observable AC), 3 TACs, 3 ADRs |
+| Probe pack | `probe-packs/application-forms-wizard.pack.mjs` | Four surface-observable browser-verify checks, one per core contract |
+| Guide | `guide/application-forms-wizard.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; cross-reference to `application-empty-error-states` for the no-in-progress empty case |
+| Sample-app fixture | `packages/rcf-lite/test/fixtures/probe-pack-application-forms-wizard/` | Dependency-free Node HTTP server the pack is probed against on the shelf gate |
+
+## The task-list vocabulary
+
+The four state strings are a closed enum at v1.0.0. Every task-list row exposes one. A fifth state (Skipped, Locked, or another word) is a v1.1.0 minor bump. Every README, guide, pack `checks[]` and `docs/topics.md` row names the same four strings.
+
+| State | Meaning |
+|---|---|
+| `Cannot start yet` | A prerequisite step is unfinished. On linear navigation the row renders as a non-anchor span. |
+| `Not started` | The step is reachable and has no answers. |
+| `In progress` | The step has partial answers. |
+| `Completed` | The step is fully valid. |
+
+## The validation timing rule
+
+REQ-002 commits to the three-mode timing rule from the GOV.UK Design System error-message pattern. The rule delegates every validation to the SPA blueprint's forms-engine TAC-205 so a project applying `application-spa` does not compose two overlapping engines; a project without `application-spa` supplies an engine of its own choice against TAC-2502's interfaces.
+
+- On blur before the first submit on a step, each field validates on leaving focus.
+- After the first submit failure on a field, subsequent input events on that field update the message on every change (so the operator sees the message clear as they correct it).
+- On the next submit the engine rebuilds the error set from scratch.
+
+## The error-summary contract
+
+On submit refusal the step renders `[data-surface="error-summary"]` at the top of the page with a heading and one skip link per failed field; the skip link's `href` targets the field id. Every failed field carries `aria-invalid="true"` and `aria-describedby` pointing at its per-field error message. On failure focus moves to the summary heading. Per WCAG 2.2 SC 3.3.1 Error Identification and SC 3.3.3 Error Suggestion.
+
+## The summary-review pattern
+
+After every step is Completed the wizard renders `[data-surface="summary-review"]` with one `[data-summary-list-section]` per step. Each section carries a `<dl>` summary list; each row is a `[data-summary-row]` with a `<dt>` label, a `<dd>` value and a `[data-recovery="change"]` link back to the step. Editing on the target step and saving returns to the summary review with every other answer preserved verbatim. Per GOV.UK Design System summary-list pattern; per WCAG 2.2 SC 3.3.4 Error Prevention.
+
+## The save-and-return contract
+
+ADR-2502 commits to two transports without recommendedDefault. The server-side draft table (`POST /drafts` on advance, `GET /drafts` on entry) keys drafts by operator identifier; the client-side local buffer writes into `window.localStorage` under `draft:<wizard-slug>:<step-slug>` and renders `[data-sync-tick]` carrying an ISO-8601 timestamp on every write. A wizard applied without either transport is refused at build gate; ADR-2502 is a required elicit. Per WCAG 2.2 SC 3.3.7 Redundant Entry.
+
+## The no-in-progress empty case
+
+The in-progress-list surface delegates the zero-drafts case to the `application-empty-error-states` empty-list state (`[data-surface="empty-list"]` with a `[data-recovery="create"]` control). The wizard blueprint does not ship its own empty component; a project applying both blueprints reads the same surface from either lane.
+
+## Elicited parameters
+
+- **Step manifest.** The ordered list of steps, one entry per step with a slug, a title and a prerequisites array. Required at apply time; the shipped example manifest is three steps.
+- **Save-and-return transport.** Default: none; ADR-2502 elicits `server-draft-table` or `client-local-buffer`. Required at apply time.
+- **Which steps are optional.** A per-step flag defaulting to `required: true`. Optional steps do not gate the summary review.
+- **Linear or free step navigation.** Default: linear. ADR-2501 elicits `free`.
+- **Step indicator shape.** Default: task-list. ADR-2503 elicits `aria-progressbar-only` or `breadcrumb`.
+
+## The one runtime gate
+
+`probe-packs/application-forms-wizard.pack.mjs` ships four checks the `rcf verify browser` runner invokes on any FBS whose surface binds `TAC-2501-application-forms-wizard-task-list` or whose nav model routes name an operator-configured wizard path. Each check drives the real Playwright browser the runner provisions, reads the DOM and the accessibility tree, 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 across every surface: 2.4.6 Headings and Labels (task-list state per row, summary heading on submit failure), 3.3.1 Error Identification (error-summary names every failed field), 3.3.3 Error Suggestion (per-field message names the correction, not just the fault), 3.3.4 Error Prevention (summary-review is reversible before submit), 3.3.7 Redundant Entry (drafts persist across sessions). GOV.UK Design System task-list pattern, summary-list pattern, complete-multiple-tasks pattern. `standardsTrace` on the blueprint is empty (this is a general-enterprise-practice blueprint); each ADR contribution carries `standardsTraceClause` naming the pattern or SC identifier it implements.
+
+## Known mechanism-reach gaps
+
+Runtime-observable ACs the pack does NOT bind directly (checklist section 6.g), listed individually per AC id:
+
+- **AC-24102-1 validation timing.** The pack asserts the field-level message element and the aria-describedby binding via the fixture's refused branch; it does NOT additionally drive a real focus-and-blur sequence through the browser transport nor probe the transition from on-blur-only to on-change-after-failure. A v1.1.0 minor bump can drive keyboard events and diff the message text across events.
+- **AC-24101-1 focus-move-to-task-list.** The pack asserts the task-list rows and the progressbar values; it does NOT additionally probe that focus lands on the task-list on route entry. A v1.1.0 minor bump can drive the accessibility tree and diff.
+- **AC-24103-1 tab-order sweep.** The pack asserts focus lands on the summary heading; it does NOT additionally probe the full tab order across the failed fields. A v1.1.0 minor bump can walk the tab order.
+- **AC-24106-1 linear-vs-free anchor rendering.** The pack does not have a dedicated check; the fixture's `?nav=free` and `?nav=linear` branches render honestly and consumers can probe the shape by inspection. A v1.1.0 minor bump can add a fifth check anchoring AC-24106-1 directly.
+- **AC-24107-1 in-progress list enumeration.** The pack does not have a dedicated check; the `/in-progress` surface is inspected by the anatomy tests. A v1.1.0 minor bump can add a fifth check anchoring AC-24107-1 directly.
+- **AC-24108-1 empty-state delegation.** The pack does not re-probe the empty-list wrapper here; the sibling `application-empty-error-states` pack already asserts it. Consumers apply both blueprints and the empty case is covered by the sibling pack. A v1.1.0 minor bump can add a cross-check that reads the empty wrapper on the `/in-progress` route.
+- **AC-24105-1 cross-tab hydration.** The pack asserts the localStorage write and the sync tick on the local branch; it does NOT additionally probe cross-tab hydration or server-side dedupe on the server branch. Both are v1.1.0 minor-bump candidates.
+- **AC-24104-1 keyboard-focus-on-change-link.** The pack asserts the change link and the answer retention; it does NOT additionally probe that following the change link places keyboard focus on the target field. A v1.1.0 minor bump can drive the click and read the active element on the target step.
+
+## Companions
+
+`suggestedCompanions` declares `logging` (every step transition, validation failure and save-and-return event writes one request-scoped log line with the correlation identifier and the step slug through the applied logger factory) and `errorHandling` (the error-summary contract constructs an internal error record per failed field through the applied error-handling factory). Neither is required to apply the blueprint; a project without a logging companion still renders every state, it just does not emit a per-step log line.
+
+## Consumers
+
+- `application-account-settings` (T-4 of this round) consumes the wizard task-list pattern for its multi-part account setup flow and the summary-review pattern for its confirm-before-save gate.
+
+## Composition with application-spa
+
+`application-spa` REQ-006 ships the forms-engine (TAC-205) that this blueprint's TAC-2502 delegates validation to. This blueprint composes with SPA; the topic-ownership boundary lives in `docs/topics.md`. SPA holds the forms-engine and the field-component library; this sibling holds the wizard shell, the task-list, the error-summary contract, the summary review and the save-and-return draft store.
+
+## Composition with application-empty-error-states
+
+The in-progress list's zero-drafts case delegates to the sibling's empty-list surface. This blueprint's TAC-2503 does not ship an empty component; the consumer applies both blueprints and the empty case reads consistently across the application. The topic-ownership boundary line lives in `docs/topics.md`, cross-referenced from the sibling's `docs/topics.md`.