rcf-lite 0.20.0 → 0.21.0

package/blueprints/application-notifications-in-app/docs/topics.md

@@ -0,0 +1,39 @@
+# application-notifications-in-app: coordination vocabulary
+
+## Global topics
+
+The blueprint claims no new global topics at v1.0.0. The in-app-notifications contract is a composed application shape; every ADR (priority-to-role mapping, toast timeout floor, centre retention window) is non-global.
+
+## Deliberately unclaimed topics
+
+- `notificationsChannel` (the channel this blueprint owns). Not a global topic; the family-prefix reservation is the discoverable coordination mechanism (see below). A future blueprint that composes across all in-app-adjacent channels (a shared preferences store, for instance) would either share TAC-2103 or supersede this blueprint.
+- `livingRegionMapping` (the priority-to-role mapping). Reserved for the applying project as the ADR-2101 decision, not a global topic; a project that supersedes the mapping authors its own ADR.
+
+## Family-prefix reservation
+
+The `application-notifications-` prefix is reserved for the sibling channel blueprints the shelf will grow into: `-email`, `-push`, `-webhook`. This is a doc-only reservation in v1.0.0 (per spec Q3 default). No sibling channel ships in this round. See the family-prefix row in the shelf band registry below and the blueprint README's "Family-prefix reservation" section.
+
+## 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-notifications-email (reserved) | to be claimed at ship | to be claimed at ship | name-only doc reservation (not shipped) | tba |
+| application-notifications-push (reserved) | to be claimed at ship | to be claimed at ship | name-only doc reservation (not shipped) | tba |
+| application-notifications-webhook (reserved) | to be claimed at ship | to be claimed at ship | name-only doc reservation (not shipped) | tba |
+
+The shelf-wide band registry lives in `packages/rcf-lite/docs/blueprint-authoring.md` section 5.
+
+## Probe pack
+
+`probe-packs/application-notifications-in-app.pack.mjs` ships three checks anchored to blueprint AC ids:
+
+- `AC-20101-1` live-region preseeding on every declared route (both wrappers present AND empty at load)
+- `AC-20102-1` transient toast contract with priority-to-role mapping and timeout measured against the six-second WCAG 2.2.1 floor
+- `AC-20103-1` centre acknowledge round-trip enumerated by `data-notification-id`, reconciled through client and server request logs
+
+Every check carries a `description` field per spec section 9. `appliesTo` binds `TAC-2101-application-notifications-in-app-live-region` OR any FBS route matching `notifications-centre`. See `probe-packs/application-notifications-in-app.pack.mjs` for the source; see `packages/rcf-lite/test/fixtures/probe-pack-application-notifications-in-app/README.md` for the sample-app fixture and the four negative-run break switches.

package/blueprints/application-notifications-in-app/guide/application-notifications-in-app.md

@@ -0,0 +1,47 @@
+# Guide: application-notifications-in-app (v1.0.0)
+
+## What it is
+
+A shipped, vendor-neutral in-app-notifications contract for a rcf-lite application. Ships the live-region preseeding discipline (TAC-2101), the transient-toast contract with the priority-to-role mapping (ADR-2101) and the WCAG 2.2.1 six-second timeout floor (ADR-2102), the notification-centre inbox with the ADR-2103 retention window and the per-item acknowledge round-trip (TAC-2102), the per-user preferences UI with category silence and sibling-channel delegation (TAC-2103), and the delivery-attempt log write path (REQ-005, TAC-2102). Ships a Playwright probe pack that gates ship on the three runtime-observable surfaces the shelf assures: both live-region wrappers are preseeded on every declared route before any notification fires, every toast maps priority to the correct wrapper and role with an announcement measured against the six-second floor, and every centre acknowledge control round-trips to the server with the DOM updating on the response.
+
+## What it deliberately is not
+
+- Not a notifications transport. The in-app slug is the discriminator; sibling channel blueprints under the reserved `application-notifications-` family prefix ship their own transports. This blueprint ships no email, no Web Push, no webhook.
+- Not a notifications store. The delivery-attempt log's persistence layer is the applied `logging` companion's; this blueprint owns the row shape and delegates the write path.
+- Not a preferences store. The preferences UI records intent on the surface (category silence, digest opt-in); the store where those preferences persist is the applying project's, and each sibling channel blueprint reads its own share of the intent.
+
+## When to reach for it
+
+- Any shipped rcf-lite application whose operators need transient toasts, a durable notification centre and per-user category silence. Web SaaS applications, admin consoles, dashboards with alerting.
+- Projects that want the WCAG 4.1.3 status-message discipline and the WCAG 2.2.1 timeout floor enforced at ship without hand-authoring the live-region contract.
+- Projects that expect to add sibling channels (email digest, Web Push, webhooks) later: the family-prefix reservation and the preferences UI's sibling-delegation shape land the discipline early.
+
+## When it does not fit
+
+- Server-to-server notifications with no operator surface. If nobody reads the notification on a screen, this blueprint's contract is expensive noise; use a logging blueprint alone.
+- A project whose notifications are single-channel and channel-first (an SMS-only alert product) where the in-app slot is not the primary surface. The sibling channel blueprint is the fit; the in-app blueprint composes later if the surface grows.
+- Highly bespoke chat-like surfaces (a support-inbox blueprint, a workflow-review inbox) where the accessibility contract differs from the WCAG 4.1.3 status-message discipline. Supersede this blueprint with a project-authored REQ naming the residual, or apply a different chat-oriented blueprint.
+
+## What a good outcome looks like
+
+Every route the applying project ships preseeds both live-region wrappers in the DOM at page load; no announcement race is possible. Every toast writes into exactly one wrapper based on its priority (info to polite as `role="status"`, error to assertive as `role="alert"`) and stays visible for six seconds unless dismissed; the reader hears an interruption exactly when the application asserts one. The notification centre lists notifications within the retention window with every item Tab-reachable and every acknowledge round-tripping to the server. The preferences UI carries per-category silence toggles and clearly labels any sibling channel that is not yet applied. The shipped probe pack runs green on the delivery-ci-workflows gate.
+
+## The operator decisions that remain open
+
+- **Toast timeout floor** (ADR-2102). Six seconds by default; operator elicits a longer dwell time if the surface has a very high notification volume.
+- **Notification categories** (REQ-004). Payment, security and product are the shipped default categories on the fixture; the operator elicits their own category list at apply.
+- **Centre retention window** (ADR-2103). Thirty days by default; operator elicits a longer or shorter window at apply.
+- **Notification centre route path** (REQ-003 note). `/notifications-centre` by default; operator elicits an override for a bespoke route.
+- **Sibling channels applied** (REQ-004 note). Which of `-email`, `-push`, `-webhook` (or a project-authored sibling) is applied on the project; discovered, not elicited, from the manifest.
+
+## Common gotchas
+
+- The two live-region wrappers must be preseeded before the first notification. A lazy-mount defect is silent at the DOM (the wrapper appears "eventually") but loses the first announcement at the assistive-technology layer. The pack refuses ship on this shape.
+- The priority-to-role mapping is fixed at v1.0.0 (info to polite/status, error to assertive/alert). A third priority (`warning`) is a v1.1 minor bump because it changes the role vocabulary; free-form priorities are refused at project-side review.
+- The toast timeout floor is a floor, not a ceiling. Six seconds is the default; an operator-elicited value above the floor is honoured (thirty seconds), a value below the floor is refused at apply. The pack measures the actual elapsed time against the shell root's declared floor and against the six-second baseline; both must clear.
+- The centre enumerates items by `data-notification-id`, per the T-3 gate discipline. A centre implementation that uses only `role="listitem"` on the children (without a per-element id attribute) passes the accessibility contract but does not let the pack enumerate individual items reliably; ship both.
+- The family-prefix reservation is documented; naming a future notifications blueprint outside the family (`application-alerts-email`) reads against the reservation and stops at author-side review.
+
+## Cost honesty
+
+Shipping this blueprint costs the project a design pass on the notification categories and retention window, and a build pass on the live-region factory and the centre inbox surface. It buys the WCAG 4.1.3 and WCAG 2.2.1 disciplines enforced at ship, the ARIA APG alert pattern on the assertive slot, the centre inbox with the acknowledge round-trip, the preferences UI with sibling delegation, and the family-prefix reservation that survives when the shelf grows a second notifications channel. The gate reviewer verifies the pack runs green against the sample-app fixture and reviews the applying project's own notifications surfaces against the ADR set.

package/blueprints/application-notifications-in-app/probe-packs/application-notifications-in-app.pack.mjs

@@ -0,0 +1,328 @@
+// application-notifications-in-app probe pack (v1.0.0).
+//
+// Three runtime-observable checks anchored to the blueprint's ACs:
+//   AC-20101-1 live-region preseeding (both wrappers present AND empty
+//              at load on every declared route)
+//   AC-20102-1 transient toast contract (priority-to-role mapping,
+//              one-shot announcement, timeout measured against the
+//              ADR-2102 six-second floor via data-shown-at /
+//              data-dismissed-at timestamps rather than a sleep in
+//              the pack)
+//   AC-20103-1 centre acknowledge round-trip (Tab-reachable acknowledge
+//              control POSTs to the server, the server responds, the
+//              DOM updates in response; enumerated by data-notification-id
+//              per the T-3 gate discipline, never by role alone)
+//
+// Every check drives the real Playwright browser the T-0 runner
+// injects (packages/rcf-lite/src/browser-verify/pack-browser.js) and
+// asserts on the DOM the applying project renders under TAC-2101
+// (live-region wrappers and toast factory), TAC-2102 (centre inbox
+// and acknowledge round-trip) and the priority-to-role mapping per
+// ADR-2101.
+//
+// The pack has no network-interception seam (T-0 shipped none); the
+// acknowledge round-trip is captured through the request log the
+// sample app exposes on window.__notificationFetches and at
+// GET /__requests. The toast timeout is measured with browser.evaluate
+// reading timestamps the sample app records on the toast element
+// (data-shown-at and data-dismissed-at), polled with a bounded loop
+// so the pack does not sleep for six seconds on the happy path.
+
+export default {
+  packName: 'application-notifications-in-app',
+  version: '1.0.0',
+  blueprintSlug: 'application-notifications-in-app',
+  // Applies to any FBS that realises the live-region TAC or whose
+  // navModel routes include a notifications-centre path. The source
+  // references BOTH `tacIds` and `route` so the T-0 loader's
+  // applicability source-scan sees the two legal seams (route is one
+  // of the three legal predicates).
+  appliesTo: ({ fbs }) => {
+    const routes = fbs?.designStage?.navModel?.routes ?? [];
+    const tacIds = fbs?.contextRequirements?.tacIds ?? [];
+    if (tacIds.includes('TAC-2101-application-notifications-in-app-live-region')) return true;
+    return routes.some((r) => typeof r?.path === 'string' && /notifications-centre/.test(r.path));
+  },
+  boot: { bootCommand: null, waitForUrl: null, waitForSelector: null },
+  checks: [
+    {
+      id: 'AC-20101-1',
+      severity: 'block',
+      description: 'Live-region preseeded on every declared route: both the polite wrapper ([aria-live="polite"] [data-live-region="polite"]) and the assertive wrapper ([role="alert"] [data-live-region="assertive"]) are preseeded and empty in the DOM at page load, before any notification fires. Enumerated by the per-element [data-live-region] attribute (never by aria-live or role alone).',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        const routes = ['/', '/notifications-centre', '/notifications-preferences'];
+        const perRoute = [];
+        for (const path of routes) {
+          // Preserve the reviewer's --url query verbatim across every
+          // route navigation: swap the pathname, keep the search.
+          const target = new URL(runtimeUrl);
+          target.pathname = path;
+          await browser.goto(target.toString());
+          const measurement = await browser.evaluate(() => {
+            const polite = document.querySelector('[data-live-region="polite"]');
+            const assertive = document.querySelector('[data-live-region="assertive"]');
+            function inspect(el) {
+              if (!el) return null;
+              return {
+                tag: el.tagName,
+                ariaLive: el.getAttribute('aria-live'),
+                role: el.getAttribute('role'),
+                dataLiveRegion: el.getAttribute('data-live-region'),
+                childCount: el.childElementCount,
+                textLength: (el.textContent || '').trim().length,
+              };
+            }
+            return { polite: inspect(polite), assertive: inspect(assertive) };
+          });
+          perRoute.push({ path, measurement });
+        }
+        const failures = [];
+        for (const entry of perRoute) {
+          if (!entry.measurement.polite) {
+            failures.push({ path: entry.path, reason: 'polite wrapper missing at page load (preseeded wrappers are required per Sara Soueidan normative guidance)' });
+            continue;
+          }
+          if (!entry.measurement.assertive) {
+            failures.push({ path: entry.path, reason: 'assertive wrapper missing at page load' });
+            continue;
+          }
+          if (entry.measurement.polite.ariaLive !== 'polite') {
+            failures.push({ path: entry.path, reason: 'polite wrapper missing aria-live="polite"' });
+          }
+          if (entry.measurement.assertive.role !== 'alert') {
+            failures.push({ path: entry.path, reason: 'assertive wrapper missing role="alert"' });
+          }
+          if (entry.measurement.polite.textLength > 0 || entry.measurement.polite.childCount > 0) {
+            failures.push({ path: entry.path, reason: 'polite wrapper carries content at page load (must be empty until a notification fires)' });
+          }
+          if (entry.measurement.assertive.textLength > 0 || entry.measurement.assertive.childCount > 0) {
+            failures.push({ path: entry.path, reason: 'assertive wrapper carries content at page load (must be empty until a notification fires)' });
+          }
+        }
+        if (failures.length > 0) {
+          return { verdict: 'fail', detail: 'live-region preseeded contract broken: ' + JSON.stringify(failures) };
+        }
+        return { verdict: 'pass', detail: 'live-region wrappers preseeded and empty on every declared route: ' + JSON.stringify(perRoute.map((r) => ({ path: r.path, polite: r.measurement.polite, assertive: r.measurement.assertive }))) };
+      },
+    },
+    {
+      id: 'AC-20102-1',
+      severity: 'block',
+      description: 'Transient toast contract: an info-priority toast renders inside the polite wrapper with role="status", an error-priority toast renders inside the assertive wrapper with role="alert" (per ADR-2101 priority-to-role mapping); every toast body appears in exactly one wrapper (never both); every toast records data-shown-at and data-dismissed-at, and a timeout-dismissed toast carries an elapsed time at or above the ADR-2102 six-second floor per WCAG 2.2.1.',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        const target = new URL('', runtimeUrl).toString();
+        await browser.goto(target);
+        // Read the shell's declared timeout floor (defaults to six
+        // seconds per ADR-2102; may be overridden above the floor).
+        const shellFloorSeconds = await browser.evaluate(() => {
+          const root = document.querySelector('[data-region="shell-root"]');
+          const value = root && root.getAttribute('data-toast-timeout-floor-seconds');
+          return value ? Number(value) : 6;
+        });
+        // Fire one info toast and one error toast through the triggers
+        // the fixture ships; a real applying project may drive the
+        // same shape via a click on its own trigger, an evaluate hook,
+        // or a background-event dispatch.
+        await browser.click('[data-toast-trigger="info"]');
+        await browser.click('[data-toast-trigger="error"]');
+        // Poll for both toasts to dismiss (bounded loop; cap slightly
+        // above the shell's floor so a six-second floor passes and a
+        // two-second break-timeout run still finishes in time).
+        const capMs = Math.max(shellFloorSeconds * 1000, 6000) + 3500;
+        const outcome = await browser.evaluate(async (capMs) => {
+          const start = Date.now();
+          function toastState() {
+            const infoToast = document.querySelector('[data-toast-priority="info"]');
+            const errorToast = document.querySelector('[data-toast-priority="error"]');
+            return { infoToast, errorToast };
+          }
+          return await new Promise((resolve) => {
+            function tick() {
+              const { infoToast, errorToast } = toastState();
+              const infoDismissedAt = infoToast && infoToast.getAttribute('data-dismissed-at');
+              const errorDismissedAt = errorToast && errorToast.getAttribute('data-dismissed-at');
+              if (infoDismissedAt && errorDismissedAt) {
+                resolve({ done: true });
+                return;
+              }
+              if (Date.now() - start > capMs) {
+                resolve({ done: false });
+                return;
+              }
+              setTimeout(tick, 60);
+            }
+            tick();
+          });
+        }, capMs);
+        if (!outcome || !outcome.done) {
+          return { verdict: 'fail', detail: 'toasts did not dismiss within the polling cap (' + capMs + 'ms); the shell may have failed to fire the toast timer' };
+        }
+        const evidence = await browser.evaluate(() => {
+          const politeWrapper = document.querySelector('[data-live-region="polite"]');
+          const assertiveWrapper = document.querySelector('[data-live-region="assertive"]');
+          function inspect(el) {
+            if (!el) return null;
+            return {
+              id: el.getAttribute('data-toast-id'),
+              priority: el.getAttribute('data-toast-priority'),
+              role: el.getAttribute('role'),
+              parentDataLiveRegion: el.parentElement && el.parentElement.getAttribute('data-live-region'),
+              shownAt: el.getAttribute('data-shown-at'),
+              dismissedAt: el.getAttribute('data-dismissed-at'),
+              body: (el.textContent || '').trim(),
+            };
+          }
+          function texts(wrapper) {
+            if (!wrapper) return [];
+            return Array.from(wrapper.querySelectorAll('[data-toast-id]')).map((t) => (t.textContent || '').trim());
+          }
+          const infoToast = document.querySelector('[data-toast-priority="info"]');
+          const errorToast = document.querySelector('[data-toast-priority="error"]');
+          return {
+            info: inspect(infoToast),
+            error: inspect(errorToast),
+            politeBodies: texts(politeWrapper),
+            assertiveBodies: texts(assertiveWrapper),
+          };
+        });
+        if (!evidence.info) return { verdict: 'fail', detail: 'no info-priority toast rendered after trigger' };
+        if (!evidence.error) return { verdict: 'fail', detail: 'no error-priority toast rendered after trigger' };
+        if (evidence.info.parentDataLiveRegion !== 'polite') {
+          return { verdict: 'fail', detail: 'info toast rendered in wrapper ' + JSON.stringify(evidence.info.parentDataLiveRegion) + ' instead of polite (ADR-2101 mapping broken)' };
+        }
+        if (evidence.info.role !== 'status') {
+          return { verdict: 'fail', detail: 'info toast role is ' + JSON.stringify(evidence.info.role) + ' instead of status (ADR-2101 mapping broken)' };
+        }
+        if (evidence.error.parentDataLiveRegion !== 'assertive') {
+          return { verdict: 'fail', detail: 'error toast rendered in wrapper ' + JSON.stringify(evidence.error.parentDataLiveRegion) + ' instead of assertive (ADR-2101 mapping broken)' };
+        }
+        if (evidence.error.role !== 'alert') {
+          return { verdict: 'fail', detail: 'error toast role is ' + JSON.stringify(evidence.error.role) + ' instead of alert (ADR-2101 mapping broken)' };
+        }
+        // Disjoint-content check (AC-20108-1 support): the info body
+        // does not appear in the assertive wrapper and vice versa.
+        if (evidence.assertiveBodies.some((body) => body === evidence.info.body)) {
+          return { verdict: 'fail', detail: 'info toast body appears in the assertive wrapper (double-post defect)' };
+        }
+        if (evidence.politeBodies.some((body) => body === evidence.error.body)) {
+          return { verdict: 'fail', detail: 'error toast body appears in the polite wrapper (double-post defect)' };
+        }
+        // Timeout floor check (WCAG 2.2.1): elapsed time between
+        // data-shown-at and data-dismissed-at at or above the ADR-2102
+        // floor. Six seconds baseline; an operator-elicited override
+        // raises the floor (never lowers it).
+        const infoElapsed = new Date(evidence.info.dismissedAt).getTime() - new Date(evidence.info.shownAt).getTime();
+        const errorElapsed = new Date(evidence.error.dismissedAt).getTime() - new Date(evidence.error.shownAt).getTime();
+        const floorMs = shellFloorSeconds * 1000;
+        if (infoElapsed < 6000) {
+          return { verdict: 'fail', detail: 'info toast dismissed after ' + infoElapsed + 'ms, below the WCAG 2.2.1 six-second floor (shell declared floor: ' + shellFloorSeconds + 's)' };
+        }
+        if (errorElapsed < 6000) {
+          return { verdict: 'fail', detail: 'error toast dismissed after ' + errorElapsed + 'ms, below the WCAG 2.2.1 six-second floor (shell declared floor: ' + shellFloorSeconds + 's)' };
+        }
+        if (shellFloorSeconds < 6) {
+          return { verdict: 'fail', detail: 'shell root declared a toast timeout floor of ' + shellFloorSeconds + 's, below the ADR-2102 six-second floor' };
+        }
+        return { verdict: 'pass', detail: 'toast contract honoured: info in polite/status (elapsed ' + infoElapsed + 'ms), error in assertive/alert (elapsed ' + errorElapsed + 'ms), floor ' + shellFloorSeconds + 's, ' + evidence.politeBodies.length + ' polite bodies + ' + evidence.assertiveBodies.length + ' assertive bodies, disjoint' };
+      },
+    },
+    {
+      id: 'AC-20103-1',
+      severity: 'block',
+      description: 'Notification centre acknowledge round-trip: the centre lists notifications within the ADR-2103 retention window (default thirty days), each item carries a stable data-notification-id (enumerated per-element, never by role alone), and a Tab-reachable [data-action="acknowledge"] control activates a POST /api/notifications/acknowledge round-trip whose 2xx response flips the item data-acknowledged to true. Reconciled against window.__notificationFetches and /__requests.',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        // Preserve the reviewer's --url query across the route swap.
+        const target = new URL(runtimeUrl);
+        target.pathname = '/notifications-centre';
+        await browser.goto(target.toString());
+        const initial = await browser.evaluate(() => {
+          // Enumerate only the notification wrappers (articles carrying
+          // data-notification-id AND data-acknowledged; the acknowledge
+          // and mark-read controls also carry data-notification-id so
+          // scope the query to article elements).
+          const items = Array.from(document.querySelectorAll('article[data-notification-id]'));
+          return {
+            itemCount: items.length,
+            itemIds: items.map((el) => el.getAttribute('data-notification-id')),
+            itemAcknowledged: items.map((el) => el.getAttribute('data-acknowledged')),
+            centreRegion: Boolean(document.querySelector('[data-region="notifications-centre"]')),
+            markAllRead: Boolean(document.querySelector('[data-action="mark-all-read"]')),
+            initialFetchCount: (window.__notificationFetches || []).length,
+          };
+        });
+        if (!initial.centreRegion) {
+          return { verdict: 'fail', detail: 'centre region not found (missing [data-region="notifications-centre"])' };
+        }
+        if (initial.itemCount === 0) {
+          return { verdict: 'fail', detail: 'centre inbox has zero items; the seeded backlog should render within the retention window' };
+        }
+        if (!initial.markAllRead) {
+          return { verdict: 'fail', detail: 'mark-all-read control missing ([data-action="mark-all-read"])' };
+        }
+        // Pick the first not-yet-acknowledged item and activate its
+        // acknowledge control by clicking. A Tab-driven activation
+        // would exercise the same handler; the runner has no keyboard
+        // seam beyond click / type / press but the fixture places the
+        // acknowledge control inside a <button> so the click is the
+        // same click a keyboard activation would trigger.
+        const firstUnackIndex = initial.itemAcknowledged.findIndex((v) => v !== 'true');
+        if (firstUnackIndex === -1) {
+          return { verdict: 'fail', detail: 'every seeded notification is already acknowledged; cannot exercise the round-trip on an unacknowledged item' };
+        }
+        const targetId = initial.itemIds[firstUnackIndex];
+        await browser.click('[data-action="acknowledge"][data-notification-id="' + targetId + '"]');
+        // Poll for the DOM update (bounded loop; the acknowledge
+        // round-trip should complete in well under a second).
+        const outcome = await browser.evaluate(async (targetId) => {
+          const start = Date.now();
+          return await new Promise((resolve) => {
+            function tick() {
+              const item = document.querySelector('[data-notification-id="' + targetId + '"]');
+              if (item && item.getAttribute('data-acknowledged') === 'true') {
+                resolve({ done: true });
+                return;
+              }
+              if (Date.now() - start > 3000) {
+                resolve({ done: false });
+                return;
+              }
+              setTimeout(tick, 50);
+            }
+            tick();
+          });
+        }, targetId);
+        if (!outcome || !outcome.done) {
+          return { verdict: 'fail', detail: 'acknowledge on notification ' + JSON.stringify(targetId) + ' did not flip data-acknowledged to true within 3s; the POST or the DOM update path is broken' };
+        }
+        // Reconcile the round-trip via window.__notificationFetches
+        // and /__requests: an `acknowledge` client record and an
+        // `acknowledge-server` server record should both exist for
+        // this notificationId.
+        const clientRecords = await browser.evaluate((targetId) => {
+          const fetches = window.__notificationFetches || [];
+          return fetches.filter((f) => f.type === 'acknowledge' && f.notificationId === targetId);
+        }, targetId);
+        if (!clientRecords || clientRecords.length === 0) {
+          return { verdict: 'fail', detail: 'no client-side acknowledge fetch recorded for ' + JSON.stringify(targetId) };
+        }
+        try {
+          const requestsRes = await fetch(new URL('/__requests', runtimeUrl).toString());
+          if (requestsRes.status !== 200) {
+            return { verdict: 'fail', detail: '/__requests endpoint returned ' + requestsRes.status };
+          }
+          const requestsBody = await requestsRes.json();
+          const serverAcks = (Array.isArray(requestsBody) ? requestsBody : []).filter((r) => r.kind === 'acknowledge-server' && r.notificationId === targetId);
+          if (serverAcks.length === 0) {
+            return { verdict: 'fail', detail: 'no server-side acknowledge record for ' + JSON.stringify(targetId) + ' at /__requests' };
+          }
+        } catch (err) {
+          return { verdict: 'fail', detail: '/__requests endpoint unreachable: ' + err.message };
+        }
+        return { verdict: 'pass', detail: 'acknowledge round-trip on ' + JSON.stringify(targetId) + ' completed: ' + initial.itemCount + ' items seeded, client + server records reconciled, data-acknowledged flipped to true' };
+      },
+    },
+  ],
+};

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

@@ -43,6 +43,11 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
 | observability-logging | 15101-15899 | 16xx | shipped v1.0.0 | `logging` |
 | application-error-handling | 16101-16899 | 17xx | shipped v1.0.0 | `errorHandling` |
+| application-datatable | 17101-17899 | 18xx | shipped v1.0.0 | none |
+| application-charts | 18101-18899 | 19xx | shipped v1.0.0 | none |
+| application-dashboard | 19101-19899 | 20xx | shipped v1.0.0 | none |
+| application-notifications-in-app | 20101-20899 | 21xx | shipped v1.0.0 | none |
+| application-admin-console | 21101-21899 | 22xx | shipped v1.0.0 | none |
 
 SPA v1.1.0 stays on the LOW end of its band: v1.0.0 occupied US-1101 through US-1128; v1.1.0 adds US-1129 and US-1130, leaving headroom above 1130 for future minor bumps and for project-side stories that mechanically derive to the 11xx numeric range.
 

package/blueprints/delivery-ci-workflows/docs/topics.md

@@ -49,6 +49,11 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
 | persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
 | observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
+| 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 |
 
 US 6101-6110 sit at the LOW end of the 6101-6899 band on purpose. A project-side story that mechanically derives from `delivery-ci-workflows-REQ-011` into the number `6111` would collide against delivery-ci-workflows-US-6111 in this package; the band leaves headroom at the HIGH end (US 6181-6899) so a project's own stories anchored to delivery-ci-workflows REQs can allocate without conflict. The watchpost run4 lesson applies here too.
 

package/blueprints/deploy-cloudflare-workers/docs/topics.md

@@ -35,6 +35,11 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
 | persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
 | observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
+| 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 |
 
 US 12101-12112 sit at the LOW end of the 12101-12899 band on purpose. A project-side story that mechanically derives from a deploy-cloudflare-workers REQ id into the number `12112` would collide against deploy-cloudflare-workers-US-12112 in this package; the band leaves headroom at the HIGH end (US 12181-12899) so a project's own stories anchored to deploy-cloudflare-workers REQs can allocate without conflict. The watchpost run4 lesson applies here too. Band spacing between the last shipped block (security-secrets-management, 8101-8899, 9xx) and this one (12101-12899, 13xx) leaves the 9xxx-11xxx US bands and the 10xx-12xx suffix blocks open for concurrent-lane authoring so a peer authoring another blueprint in the same PR window does not collide with this one.
 

package/blueprints/email-smtp-resend/docs/topics.md

@@ -31,6 +31,11 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
 | persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
 | observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
+| 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 |
 
 US 4101-4106 sit at the LOW end of the 4101-4899 band on purpose. A project-side story that mechanically derives from an email-smtp-resend REQ id into the number `4106` (leading `4` + sequence `106`) would collide against email-smtp-resend-US-4106 in this package; the band leaves headroom at the HIGH end (US 4181-4899) so a project's own stories anchored to email-smtp-resend REQs can allocate without conflict. The watchpost run4 lesson applies here too.
 

package/blueprints/observability-essentials/docs/topics.md

@@ -50,6 +50,11 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
 | persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
 | observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
+| 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 |
 
 US 7101-7110 sit at the LOW end of the 7101-7899 band on purpose. A project-side story that mechanically derives from an observability-essentials REQs id into the number `7110` would collide against observability-essentials-US-7110 in this package; the band leaves headroom at the HIGH end (US 7181-7899) so a project's own stories anchored to observability-essentials REQs can allocate without conflict. The watchpost run4 lesson applies here too.
 

package/blueprints/observability-logging/CHANGELOG.md

@@ -0,0 +1,5 @@
+# observability-logging CHANGELOG
+
+## 1.1.0 (visual round T-5, spec 2026-09-04 section 5.5.2, Baz Q2 default)
+
+- Declares `capabilities: [auditLog]` on `blueprint.json`. No other change. The new field is additive per section 6 of `blueprint-authoring.md` (an additive optional field with no global-topic change is a minor bump). Keeps a single grammar for capability declaration: consumer blueprints read the union of declared `capabilities[]` on applied blueprints, never the `providesRoles[]` -> capability inference. This is the ratified rule (one grammar, no role-to-capability inference); the section 6a table previously noted `auditLog` as "implicit through the `logging` role" and now names `observability-logging` as the explicit shelf provider. Consumed at apply time by the visual round T-5 `application-admin-console` blueprint to gate the audit-log surface (probe pack check `AC-21105-1`).

package/blueprints/observability-logging/README.md

@@ -1,6 +1,6 @@
 # Logging blueprint (v1.0.0)
 
-Structured single-line JSON emission for a rcf-lite project. General enterprise practice, no vendor lock-in. Ships the shelf-canonical `logging` global topic on `ADR-1601-observability-logging-line-shape` (transferred from `application-api-rest-ADR-304`, retained there as superseded history). Provides the `logging` role for the companion-suggestion mechanism.
+Structured single-line JSON emission for a rcf-lite project. General enterprise practice, no vendor lock-in. Ships the shelf-canonical `logging` global topic on `ADR-1601-observability-logging-line-shape` (transferred from `application-api-rest-ADR-304`, retained there as superseded history). Provides the `logging` role for the companion-suggestion mechanism. From 1.1.0, declares `capabilities: [auditLog]` on `blueprint.json` so the application-admin-console probe pack activates the audit-log surface check `AC-21105-1` when this blueprint is applied on the project (one grammar; consumer blueprints read declared capabilities, never a role-to-capability inference).
 
 ## Apply