commit b1cf3410c8bc3bdc12d977adcee7e653b65e1121
parent 32df695fe2522f3d499f3d13313be71a6a255ce8
Author: triesap <tyson@radroots.org>
Date: Mon, 5 Oct 2026 07:31:57 +0000
web: add persistent notices and status presentation
- Map finite operation and per-target receipt facts to calm copy.
- Keep recipient, archive and exact readback evidence separate.
- Add linked field errors without losing input or keyboard focus.
- Verify scoped components and full web lanes with frozen inputs.
Diffstat:
9 files changed, 695 insertions(+), 0 deletions(-)
diff --git a/web/src/lib/components/ErrorSummary.svelte b/web/src/lib/components/ErrorSummary.svelte
@@ -0,0 +1,23 @@
+<script lang="ts">
+ import { internalHref } from '../navigation-url';
+ let {
+ errors
+ }: { errors: readonly Readonly<{ href: string; text: string }>[] } = $props();
+ const id = $props.id();
+</script>
+
+{#if errors.length}
+ <section class="notice notice--error stack stack--tight" aria-labelledby={id}>
+ <h2 {id}>Check the following fields</h2>
+ <ul>
+ {#each errors as error, index (index)}
+ <li>
+ {#if error.href.startsWith('#') && internalHref(error.href)}<a
+ class="shell-link"
+ href={internalHref(error.href)}>{error.text}</a
+ >{:else}<span>{error.text}</span>{/if}
+ </li>
+ {/each}
+ </ul>
+ </section>
+{/if}
diff --git a/web/src/lib/components/Notice.svelte b/web/src/lib/components/Notice.svelte
@@ -0,0 +1,16 @@
+<script lang="ts">
+ import type { StatusCopy } from '../presentation/status-copy';
+ let { tone = 'info', text }: { tone?: StatusCopy['tone']; text: string } =
+ $props();
+</script>
+
+<p
+ class="notice"
+ class:notice--warning={tone === 'warning'}
+ class:notice--error={tone === 'error'}
+ role="status"
+ aria-live="polite"
+ aria-atomic="true"
+>
+ {text}
+</p>
diff --git a/web/src/lib/components/OperationStatus.svelte b/web/src/lib/components/OperationStatus.svelte
@@ -0,0 +1,28 @@
+<script lang="ts">
+ import Notice from './Notice.svelte';
+ import {
+ statusCopy,
+ receiptCopy,
+ type OperationFact,
+ type TargetReceipt
+ } from '../presentation/status-copy';
+ let {
+ fact,
+ receipts = []
+ }: { fact: OperationFact; receipts?: readonly TargetReceipt[] } = $props();
+ const summary = $derived(statusCopy(fact));
+</script>
+
+<div class="stack stack--tight">
+ <Notice tone={summary.tone} text={summary.text} />
+ {#each receipts as receipt, index (index)}
+ {@const copy = receiptCopy(receipt)}
+ <div class="stack stack--tight">
+ <p class="key">
+ Event: {receipt.eventId} ยท Target: {receipt.destination}
+ </p>
+ <Notice tone={copy.tone} text={copy.text} />
+ <p>{copy.readback}</p>
+ </div>
+ {/each}
+</div>
diff --git a/web/src/lib/presentation/status-copy.ts b/web/src/lib/presentation/status-copy.ts
@@ -0,0 +1,122 @@
+// Presentation facts supplied by an admitted controller, not domain receipts.
+export type OperationFact =
+ | 'saved'
+ | 'save-failed'
+ | 'unsaved'
+ | 'encrypted-saved'
+ | 'preparing'
+ | 'sending'
+ | 'partial'
+ | 'extension-pending'
+ | 'needs-action'
+ | 'stopped'
+ | 'local-read'
+ | 'unknown';
+export type StatusCopy = Readonly<{
+ tone: 'info' | 'warning' | 'error';
+ text: string;
+}>;
+export type TargetReceipt = Readonly<{
+ eventId: string;
+ destination: string;
+ role: 'public' | 'recipient' | 'archive';
+ outcome: 'pending' | 'accepted' | 'refused' | 'timed-out' | 'unknown';
+ readback: 'confirmed' | 'not-observed' | 'unknown';
+}>;
+export function statusCopy(fact: OperationFact): StatusCopy {
+ switch (fact) {
+ case 'saved':
+ return { tone: 'info', text: 'Saved in this browser.' };
+ case 'save-failed':
+ return {
+ tone: 'error',
+ text: 'Your latest changes were not saved. Keep this page open and try again.'
+ };
+ case 'unsaved':
+ return {
+ tone: 'warning',
+ text: 'Not yet saved. Unsent text is lost when this page closes.'
+ };
+ case 'encrypted-saved':
+ return { tone: 'info', text: 'Saved encrypted in this browser.' };
+ case 'preparing':
+ return { tone: 'info', text: 'Preparing encryption.' };
+ case 'sending':
+ return { tone: 'info', text: 'Sending.' };
+ case 'partial':
+ return {
+ tone: 'warning',
+ text: 'Delivery is partial. Check the individual target outcomes.'
+ };
+ case 'extension-pending':
+ return {
+ tone: 'info',
+ text: 'Waiting for your extension. Another approval may be needed.'
+ };
+ case 'needs-action':
+ return {
+ tone: 'warning',
+ text: 'Needs action. Keep the original operation for recovery.'
+ };
+ case 'stopped':
+ return {
+ tone: 'warning',
+ text: 'Stopped scheduling further work. Accepted or uncertain effects are not reversed.'
+ };
+ case 'local-read':
+ return {
+ tone: 'info',
+ text: 'Marked read in this browser only. The sender is not notified.'
+ };
+ default:
+ return {
+ tone: 'warning',
+ text: 'The outcome is unknown. Keep the original operation for reconciliation.'
+ };
+ }
+}
+export function receiptCopy(
+ receipt: TargetReceipt
+): StatusCopy & Readonly<{ readback: string }> {
+ const subject =
+ receipt.role === 'recipient'
+ ? "The recipient's inbox relay"
+ : receipt.role === 'archive'
+ ? 'The sender archive relay'
+ : receipt.role === 'public'
+ ? 'The public listing relay'
+ : undefined;
+ let text = 'The target outcome is unknown.';
+ let tone: StatusCopy['tone'] = 'warning';
+ if (subject)
+ switch (receipt.outcome) {
+ case 'accepted':
+ text = subject + ' accepted the event.';
+ tone = 'info';
+ break;
+ case 'refused':
+ text = subject + ' refused the event. Needs action.';
+ tone = 'error';
+ break;
+ case 'timed-out':
+ text =
+ subject +
+ ' did not respond before the deadline. Acceptance is unknown.';
+ break;
+ case 'pending':
+ text = subject + ' outcome is pending.';
+ break;
+ default:
+ text =
+ receipt.role === 'recipient'
+ ? "We could not confirm whether the recipient's inbox accepted this message."
+ : subject + ' acceptance is unknown.';
+ }
+ const readback =
+ receipt.readback === 'confirmed'
+ ? 'Exact read-back is confirmed for this event and target.'
+ : receipt.readback === 'not-observed'
+ ? 'Exact read-back was not observed for this event and target.'
+ : 'Exact read-back is unknown.';
+ return { tone, text, readback };
+}
diff --git a/web/tests/e2e/harness/notices.svelte b/web/tests/e2e/harness/notices.svelte
@@ -0,0 +1,74 @@
+<script lang="ts">
+ import Notice from '../../../src/lib/components/Notice.svelte';
+ import OperationStatus from '../../../src/lib/components/OperationStatus.svelte';
+ import ErrorSummary from '../../../src/lib/components/ErrorSummary.svelte';
+ import FormField from '../../../src/lib/components/primitives/FormField.svelte';
+ let input = $state('preserved food');
+ let failed = $state(false);
+ let text = $state(
+ 'Waiting for your extension. Another approval may be needed.'
+ );
+</script>
+
+<div class="page page--reading stack">
+ <h1>HC_TEST_ONLY_NOTICES</h1>
+ <form
+ class="stack"
+ onsubmit={(event) => {
+ event.preventDefault();
+ failed = true;
+ }}
+ >
+ <ErrorSummary
+ errors={failed
+ ? [
+ { href: '#food', text: 'Enter a supported food description.' },
+ {
+ href: 'https://example.com',
+ text: 'Unsafe target remains plain text.'
+ }
+ ]
+ : []}
+ />
+ <FormField
+ id="food"
+ label="Food"
+ error={failed ? 'Enter a supported food description.' : undefined}
+ >
+ {#snippet control({ id, describedby, invalid })}<textarea
+ {id}
+ class="input textarea"
+ bind:value={input}
+ aria-describedby={describedby}
+ aria-invalid={invalid}></textarea>{/snippet}
+ </FormField>
+ <button type="submit" class="button button--primary">Review</button>
+ </form>
+ <Notice {text} />
+ <button
+ type="button"
+ class="button button--secondary"
+ onclick={() => {
+ text = 'One source did not respond. These results may be incomplete.';
+ }}>Update information</button
+ >
+ <OperationStatus
+ fact="unknown"
+ receipts={[
+ {
+ role: 'recipient',
+ outcome: 'unknown',
+ readback: 'confirmed',
+ eventId: 'event-A',
+ destination: 'recipient-target'
+ },
+ {
+ role: 'archive',
+ outcome: 'accepted',
+ readback: 'unknown',
+ eventId: 'event-B',
+ destination: 'archive-target'
+ }
+ ]}
+ />
+</div>
diff --git a/web/tests/e2e/notices.spec.ts b/web/tests/e2e/notices.spec.ts
@@ -0,0 +1,256 @@
+import { expect, test } from '@playwright/test';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import {
+ cp,
+ mkdtemp,
+ mkdir,
+ readFile,
+ readdir,
+ rm,
+ writeFile
+} from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createStaticHarness } from '../integration/harness/static.ts';
+
+// Isolated qualification clone: actual components compile into disposable output.
+// The primary static payload and product route source are never overwritten.
+const capsule = fileURLToPath(new URL('../../../', import.meta.url));
+let directory: string;
+let server: Awaited<ReturnType<typeof createStaticHarness>>;
+test.beforeAll(async () => {
+ test.setTimeout(120_000);
+ directory = await mkdtemp(path.join(tmpdir(), 'hcp016-notices-'));
+ try {
+ const checkout = path.join(directory, 'checkout');
+ execFileSync('git', [
+ 'clone',
+ '--quiet',
+ '--no-hardlinks',
+ capsule,
+ checkout
+ ]);
+ for (const relative of [
+ 'web/src/lib/components/Notice.svelte',
+ 'web/src/lib/components/OperationStatus.svelte',
+ 'web/src/lib/components/ErrorSummary.svelte',
+ 'web/src/lib/presentation/status-copy.ts',
+ 'web/tests/unit/status-copy.test.ts',
+ 'web/tests/unit/components/notices.test.ts',
+ 'web/tests/unit/components/NoticeHarness.svelte',
+ 'web/tests/e2e/notices.spec.ts',
+ 'web/tests/e2e/harness/notices.svelte'
+ ]) {
+ await mkdir(path.dirname(path.join(checkout, relative)), {
+ recursive: true
+ });
+ await cp(path.join(capsule, relative), path.join(checkout, relative));
+ }
+ const fixture = await readFile(
+ path.join(capsule, 'web/tests/e2e/harness/notices.svelte'),
+ 'utf8'
+ );
+ await writeFile(
+ path.join(checkout, 'web/src/routes/+page.svelte'),
+ fixture.replaceAll('../../../src/lib/', '../lib/')
+ );
+ await cp(
+ path.join(capsule, 'web/node_modules'),
+ path.join(checkout, 'web/node_modules'),
+ { recursive: true, verbatimSymlinks: true }
+ );
+ const sourceAudit = execFileSync(
+ process.execPath,
+ ['tools/check-source.mjs'],
+ { cwd: path.join(checkout, 'web') }
+ ).toString();
+ const identities = [];
+ for (const relative of [
+ 'web/src/lib/components/AppShell.svelte',
+ 'web/src/lib/components/Notice.svelte',
+ 'web/src/lib/components/OperationStatus.svelte',
+ 'web/src/lib/components/ErrorSummary.svelte',
+ 'web/src/lib/presentation/status-copy.ts',
+ 'web/src/lib/components/primitives/FormField.svelte',
+ 'web/src/lib/components/primitives/Button.svelte',
+ 'web/src/app.css',
+ 'web/src/theme.css',
+ 'web/src/routes/+layout.svelte'
+ ]) {
+ identities.push({
+ name: relative,
+ sha256: createHash('sha256')
+ .update(await readFile(path.join(checkout, relative)))
+ .digest('hex')
+ });
+ }
+ execFileSync(process.execPath, ['tools/build-info.mjs'], {
+ cwd: path.join(checkout, 'web')
+ });
+ const compiled = execFileSync(
+ 'corepack',
+ ['pnpm', 'exec', 'vite', 'build'],
+ {
+ cwd: path.join(checkout, 'web'),
+ stdio: 'pipe',
+ timeout: 90_000
+ }
+ );
+ async function payload(
+ directory: string,
+ prefix = ''
+ ): Promise<{ path: string; sha256: string }[]> {
+ const files = [];
+ for (const entry of await readdir(directory, { withFileTypes: true })) {
+ const relative = prefix + entry.name;
+ if (entry.isDirectory())
+ files.push(
+ ...(await payload(path.join(directory, entry.name), relative + '/'))
+ );
+ else
+ files.push({
+ path: relative,
+ sha256: createHash('sha256')
+ .update(await readFile(path.join(directory, entry.name)))
+ .digest('hex')
+ });
+ }
+ return files.sort((left, right) => left.path.localeCompare(right.path));
+ }
+ console.log(
+ JSON.stringify({
+ fixture: 'HCP016_TEST_ONLY_COMPILE',
+ identities,
+ sourceAudit,
+ productionRouteSha256: createHash('sha256')
+ .update(
+ await readFile(path.join(capsule, 'web/src/routes/+page.svelte'))
+ )
+ .digest('hex'),
+ fixtureSourceSha256: createHash('sha256').update(fixture).digest('hex'),
+ compiledRouteSha256: createHash('sha256')
+ .update(
+ await readFile(path.join(checkout, 'web/src/routes/+page.svelte'))
+ )
+ .digest('hex'),
+ compiledLayoutSha256: createHash('sha256')
+ .update(
+ await readFile(path.join(checkout, 'web/src/routes/+layout.svelte'))
+ )
+ .digest('hex'),
+ retention:
+ 'HASHLOGS_ONLY: disposable compiled fixture output is removed after tests',
+ payload: await payload(path.join(checkout, 'web/build')),
+ compiled: compiled.toString(),
+ metadata: JSON.parse(
+ await readFile(
+ path.join(checkout, 'web/build/build-info.json'),
+ 'utf8'
+ )
+ ) as unknown
+ })
+ );
+ server = await createStaticHarness({
+ buildRoot: path.join(checkout, 'web/build')
+ });
+ } catch (error) {
+ await rm(directory, { recursive: true, force: true });
+ throw error;
+ }
+});
+test.afterAll(async () => {
+ await server?.close();
+ if (directory) await rm(directory, { recursive: true, force: true });
+ if (server)
+ expect(server.state()).toEqual({ listening: false, childProcesses: 0 });
+});
+
+for (const width of [320, 1024]) {
+ test(
+ 'persistent notices preserve field values and focus at ' + width + 'px',
+ async ({ browser }) => {
+ const context = await browser.newContext({
+ viewport: { width, height: 900 }
+ });
+ const external: string[] = [];
+ try {
+ await context.route('**/*', (route) => {
+ if (new URL(route.request().url()).origin === server.url)
+ return route.continue();
+ external.push(route.request().url());
+ return route.abort();
+ });
+ const page = await context.newPage();
+ await page.goto(server.url);
+ const field = page.getByRole('textbox', { name: 'Food', exact: true });
+ await field.fill('unchanged multiline\n่');
+ await expect(
+ page.getByRole('heading', { name: 'Check the following fields' })
+ ).toHaveCount(0);
+ await page.getByRole('button', { name: 'Review', exact: true }).click();
+ await expect(field).toHaveValue('unchanged multiline\n่');
+ await expect(field).toHaveAttribute('aria-invalid', 'true');
+ const link = page.getByRole('link', {
+ name: 'Enter a supported food description.',
+ exact: true
+ });
+ await expect(link).toHaveAttribute('href', '#food');
+ await link.focus();
+ await page.keyboard.press('Enter');
+ await expect(field).toBeFocused();
+ await expect(
+ page.getByRole('link', { name: 'Unsafe target remains plain text.' })
+ ).toHaveCount(0);
+ const update = page.getByRole('button', { name: 'Update information' });
+ await update.focus();
+ await page.keyboard.press('Enter');
+ await expect(update).toBeFocused();
+ await expect(
+ page.getByText(
+ 'One source did not respond. These results may be incomplete.'
+ )
+ ).toBeVisible();
+ await expect(field).toHaveValue('unchanged multiline\n่');
+ await expect(link).toBeVisible();
+ await expect(
+ page.getByText(
+ "We could not confirm whether the recipient's inbox accepted this message."
+ )
+ ).toBeVisible();
+ await expect(
+ page.getByText('The sender archive relay accepted the event.')
+ ).toBeVisible();
+ await expect(
+ page.getByText(
+ 'Exact read-back is confirmed for this event and target.'
+ )
+ ).toBeVisible();
+ const measured = await page.evaluate(() => ({
+ width: innerWidth,
+ scroll: globalThis.document.documentElement.scrollWidth,
+ controls: Array.from(
+ globalThis.document.querySelectorAll('button,a.shell-link')
+ ).map((el) => el.getBoundingClientRect().height)
+ }));
+ expect(measured.scroll).toBeLessThanOrEqual(width);
+ for (const height of measured.controls)
+ expect(height).toBeGreaterThanOrEqual(44);
+ console.log(
+ JSON.stringify({
+ fixture: 'HCP016_CONTROLLED_NOTICES_ONLY',
+ measured,
+ inputPreserved: true,
+ informationalFocusPreserved: true,
+ keyboardFieldFocus: true
+ })
+ );
+ expect(external).toEqual([]);
+ expect(await page.evaluate(() => 'nostr' in window)).toBe(false);
+ } finally {
+ await context.close();
+ }
+ }
+ );
+}
diff --git a/web/tests/unit/components/NoticeHarness.svelte b/web/tests/unit/components/NoticeHarness.svelte
@@ -0,0 +1,26 @@
+<script lang="ts">
+ import Notice from '../../../src/lib/components/Notice.svelte';
+ import OperationStatus from '../../../src/lib/components/OperationStatus.svelte';
+ import ErrorSummary from '../../../src/lib/components/ErrorSummary.svelte';
+</script>
+
+<Notice tone="error" text="<img src=x>" />
+<OperationStatus
+ fact="unknown"
+ receipts={[
+ {
+ role: 'archive',
+ outcome: 'accepted',
+ readback: 'confirmed',
+ eventId: 'event-A',
+ destination: 'target-A'
+ }
+ ]}
+/>
+<ErrorSummary
+ errors={[
+ { href: '#food', text: 'Enter food.' },
+ { href: 'https://example.com', text: 'Unsafe destination' },
+ { href: 'javascript:alert(1)', text: 'Unsafe scheme' }
+ ]}
+/>
diff --git a/web/tests/unit/components/notices.test.ts b/web/tests/unit/components/notices.test.ts
@@ -0,0 +1,30 @@
+import { render } from 'svelte/server';
+import { describe, it, expect } from 'vitest';
+import Notice from '../../../src/lib/components/Notice.svelte';
+import ErrorSummary from '../../../src/lib/components/ErrorSummary.svelte';
+import Harness from './NoticeHarness.svelte';
+describe('persistent accessible status and form summary SSR', () => {
+ it('escapes plain text and politely announces without focus/dismissal', () => {
+ const html = render(Notice, {
+ props: { tone: 'error', text: '<img src=x>' }
+ }).body;
+ expect(html).toContain('<img src=x>');
+ expect(html).toContain('aria-live="polite"');
+ expect(html).not.toMatch(/autofocus|onclick|setTimeout|<button/);
+ });
+ it('links only safe same-page fields and associates a heading', () => {
+ const html = render(Harness).body;
+ expect(html).toContain('href="#food"');
+ expect(html).not.toMatch(/href="https:|href="javascript:/);
+ expect(html).toContain('Unsafe destination');
+ expect(html).toContain('aria-labelledby=');
+ expect(html).toContain('sender archive');
+ expect(html).toContain('event-A');
+ expect(html).toContain('target-A');
+ });
+ it('does not flag fields before any errors exist', () => {
+ expect(render(ErrorSummary, { props: { errors: [] } }).body).not.toContain(
+ 'Check the following fields'
+ );
+ });
+});
diff --git a/web/tests/unit/status-copy.test.ts b/web/tests/unit/status-copy.test.ts
@@ -0,0 +1,120 @@
+import { describe, it, expect } from 'vitest';
+import {
+ statusCopy,
+ receiptCopy,
+ type OperationFact
+} from '../../src/lib/presentation/status-copy';
+describe('finite evidence-specific presentation', () => {
+ it('never maps unsupported or unknown to success', () => {
+ for (const state of ['unknown', 'new-future-state', null, undefined, 42])
+ expect(statusCopy(state as OperationFact)).toEqual({
+ tone: 'warning',
+ text: 'The outcome is unknown. Keep the original operation for reconciliation.'
+ });
+ });
+ it('maps local facts precisely', () => {
+ expect(statusCopy('saved').text).toBe('Saved in this browser.');
+ expect(statusCopy('encrypted-saved').text).toBe(
+ 'Saved encrypted in this browser.'
+ );
+ expect(statusCopy('unsaved').text).toContain('Unsent text is lost');
+ });
+ it('distinguishes each role and outcome', () => {
+ for (const role of ['public', 'recipient', 'archive'] as const) {
+ const values = [
+ 'accepted',
+ 'refused',
+ 'timed-out',
+ 'unknown',
+ 'pending'
+ ] as const;
+ const texts = values.map(
+ (outcome) =>
+ receiptCopy({
+ role,
+ outcome,
+ readback: 'unknown',
+ eventId: 'event-A',
+ destination: 'target-A'
+ }).text
+ );
+ expect(new Set(texts).size).toBe(values.length);
+ }
+ expect(
+ receiptCopy({
+ role: 'archive',
+ outcome: 'accepted',
+ readback: 'confirmed',
+ eventId: 'event-A',
+ destination: 'target-A'
+ }).text
+ ).toContain('sender archive');
+ expect(
+ receiptCopy({
+ role: 'archive',
+ outcome: 'accepted',
+ readback: 'confirmed',
+ eventId: 'event-A',
+ destination: 'target-A'
+ }).text
+ ).not.toContain("recipient's inbox relay accepted");
+ });
+ it('does not promote exact readback into acceptance', () => {
+ const copy = receiptCopy({
+ role: 'recipient',
+ outcome: 'unknown',
+ readback: 'confirmed',
+ eventId: 'event-A',
+ destination: 'target-A'
+ });
+ expect(copy.text).toContain('could not confirm');
+ expect(copy.readback).toContain('confirmed');
+ expect(copy.tone).toBe('warning');
+ });
+ it('unknown runtime role/outcome/readback never crashes or becomes accepted', () => {
+ expect(
+ receiptCopy({
+ role: 'future',
+ outcome: 'future',
+ readback: 'future',
+ eventId: 'event-A',
+ destination: 'target-A'
+ } as never)
+ ).toEqual({
+ tone: 'warning',
+ text: 'The target outcome is unknown.',
+ readback: 'Exact read-back is unknown.'
+ });
+ });
+ it('keeps input immutable and ignores unrelated seen metadata', () => {
+ const fact = Object.freeze({
+ role: 'recipient' as const,
+ outcome: 'unknown' as const,
+ readback: 'unknown' as const,
+ eventId: 'event-A',
+ destination: 'target-A',
+ seenRelays: ['relay-A']
+ });
+ expect(receiptCopy(fact).text).toContain('could not confirm');
+ expect(fact.outcome).toBe('unknown');
+ });
+ it('has no unsupported commercial or remote receipt promise', () => {
+ for (const fact of [
+ 'saved',
+ 'save-failed',
+ 'unsaved',
+ 'encrypted-saved',
+ 'preparing',
+ 'sending',
+ 'partial',
+ 'extension-pending',
+ 'needs-action',
+ 'stopped',
+ 'local-read',
+ 'unknown'
+ ] as const)
+ expect(statusCopy(fact).text).not.toMatch(
+ /order placed|delivered|remote read|reserved|guaranteed|permanent|global sync/i
+ );
+ });
+});