@supersuit/suggest-a-change 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.7 (2026-10-17)
+
+- **The person who suggested a change is told when it is being made and when it ends.** `createReportHandlers` takes a required `tellSubmitter(e)`, called once per move to `being-made` or an end (`TOLD`, now in the contract) with `{ member, reportId, status, words, meaning, ended, note? }`. The words are the module's own (`wordsFor`/`meaningFor`), never the report's text; `note` is the one-line reason, on `not-now` only. The planning steps, a repeat, a refused move and a maintainer's own report starting tell nobody, and a failure never fails the move. **Breaking:** without `tellSubmitter` the handlers throw at startup; an app with nobody to tell passes `{ none: "<reason>" }`. The `status` tell event also carries `member` and `status`, and a `not-now` row in the member's list carries its `note`.
+- **In the app, with no setup.** The entry compares each report's status with the one its owner last opened (kept on the phone per app and account, cleared on sign-out): a report that has since started or ended shows a dot on the entry, says New in My suggestions, and the newest move gets one toast per app open ("Your suggestion: Done"; new strings `newMark`, `entryMoved`, `movedToast`). Opening the report clears it. A report seen for the first time is recorded silently, so nothing old is announced.
+- `init` writes a `tellSubmitter` stub into the adapters file and names it in its notes.
+
+## 0.1.6 (2026-10-15)
+
+- **Writes made in the same millisecond leave the phone in the order they were made.** `enqueue` stamps each op with `seq`, and the queue sorts by `at`, then `seq`, then id. Before, ties fell to the id, so a screen that saved a draft and then asked for it to be prepared in one tick sent the prepare first about half the time, and the receiver prepared the draft as it had been.
+
 ## 0.1.5 (2026-10-14)
 
 - **The agent is Pluma.** Every word a person reads now names Pluma, the agent formerly called Freeda: "With Pluma", "Goes to <owner> and Pluma", "Pluma picks it up". The status key `with-freeda` is unchanged, so stored reports and older clients still read. A copy of the contract vendored elsewhere must be taken again: these are new bytes.

package/README.md

@@ -73,6 +73,8 @@ The four diagnostics are the app's version, the time, the screen size and the ph
 
 **Identity.** Every screen asks `adapters.identity()` when it mounts, whenever it is handed a different `adapters` object, and whenever the host calls `refreshIdentity()` (exported from `"./client"`; call it after a sign-in, sign-out or account switch). When the account differs, the old account's rows leave the screen and its waiting reports stay on the phone, to be sent only while that account is signed in; every send re-confirms the account first. Keep `adapters` stable where you can; a parent that rebuilds it every render is safe, only slower (one `identity()` call per render).
 
+**Telling the person in the app, with no setup.** The entry asks `mine()` once when it mounts and compares each report's status with the one this account last opened (kept on the phone beside the cached views, per app and account, and cleared on sign-out). A report that has since been started or ended (`TOLD`) shows a dot on the entry, says New on its row in My suggestions, and the newest such move gets one toast per app open in the module's words (`words.text.movedToast`, given the status's own word and, on `not-now`, the reason: "Your suggestion: Done", "Your suggestion: Not now. too big for now"). Opening the report clears it. A report this phone sees for the first time is recorded silently, so an app taking this release does not announce every old report. The list's `not-now` rows carry their one-line `note` for this. Out of the app, the server's `tellSubmitter` does the telling (below).
+
 **Follow-ups.** Words and voice notes added to a report afterwards are queued in the outbox like the report (a `followUp` write, then one part per voice note), keep the app's refusal with a Try again, and delete their local copy only once they have landed. `StoreAdapter.append` must therefore dedupe by report id and `more.followId`.
 
 ## The check: every screen carries the button
@@ -86,7 +88,7 @@ npx suggest-a-change-check --help
 
 Exit 0 is clean, 1 is problems (each printed with the file and the fix), 2 is a usage error or nothing to check. `--json` prints `{ ok, problems, checked, exempted }`. The flags are `--repo`, `--config`, `--app-dir`, `--adapters` and `--strict`. An app directory with no pages is a usage error (exit 2: nothing was checked), as is an app directory outside the repo.
 
-**Put `suggest-a-change-check --strict` in the app's check script** once the adapters are real. `init` writes stubs that sign nobody in and refuse every report, and marks the file with a `suggest-a-change: STUB` line. Without `--strict` that line is a `warning:` (also in the `--json` `warnings`) and the exit stays 0; with `--strict` it is a problem and the exit is 1. Delete the line when the four adapters are real.
+**Put `suggest-a-change-check --strict` in the app's check script** once the adapters are real. `init` writes stubs that sign nobody in and refuse every report, and marks the file with a `suggest-a-change: STUB` line. Without `--strict` that line is a `warning:` (also in the `--json` `warnings`) and the exit stays 0; with `--strict` it is a problem and the exit is 1. Delete the line when the four adapters are real. The stub also carries `tellSubmitter` for the server half, which `createReportHandlers` requires (see below), and `init` says so in its notes whenever the adapters file has none.
 
 For a Next.js app (app router) it reads source, not a running app:
 
@@ -162,9 +164,12 @@ const h = createReportHandlers({
   app: { name: "Notes" },                 // stamped into every report from here; an app in the body is ignored
   maintainersSince: { mo: "2026-10-01" }, // optional: reports from before this are not offered to that maintainer's Mac
   tell: (e) => notify(e),                 // ids only, never words; a failure never fails the request
+  tellSubmitter: (e) => push(e.member, e.words, e.note), // REQUIRED: tell the person who suggested it (or { none: "<reason>" })
 });
 ```
 
+**Telling the person who suggested it is required.** `tellSubmitter` is called once when a report moves to `being-made` and once when it ends (`live`, `sent-to-template`, `filed`, `not-now`; the list is exported as `TOLD`), with `{ member, reportId, status, words, meaning, ended, note? }`. `words` and `meaning` are the module's own words for the status (`wordsFor`/`meaningFor`, with `app.owner` as the owner's name when given), never the report's text, so a lock screen never shows what someone wrote; `note` is the one-line reason and comes with `not-now` only. The planning steps (`with-freeda`, `planned`, `waiting-on-owner`) tell nobody, a repeat of a status tells nobody, a move the store refused tells nobody, and a maintainer is not told that the work they just started on their own report has started (its end is still told). Send it on the app's own channel (push, email, an activity row) to that member only. A failure never fails the move. `createReportHandlers` throws at startup when `tellSubmitter` is missing; an app that genuinely has nobody to tell passes `tellSubmitter: { none: "only the maintainer uses this app" }`, and an empty reason throws too. The `tell` event for a status move now also carries `member` and `status`.
+
 | Route | Handler | Answers |
 | --- | --- | --- |
 | `POST /api/reports` | `submit` | 200 (a repeat of the same id is 200 too), 400, 401, 413, 422, 429 |

package/dist/client/detail.js

@@ -10,6 +10,7 @@ import { draftKey } from './drafts.js';
 import { recoverTakes } from './recorder.js';
 import { queueFollowUp } from './reports.js';
 import { useRuntime, useTick } from './runtime.js';
+import { markSeen } from './seen.js';
 import { Toasts } from './toast.js';
 import { dropCache, isRefusal, oneCacheKey, readCache, useClearOnSignOut, writeCache } from './view-cache.js';
 import { effectiveCeilings, lengthWords, sizeWords, statusMeaning, statusWords, stringsFor } from './words.js';
@@ -158,6 +159,8 @@ export function SuggestionDetail({ adapters, id }) {
                 setOffline(false);
                 setReport(r);
                 void writeCache(rt.store, ckey, r);
+                // The person has now seen it at this status: its New mark and the entry's dot clear.
+                void markSeen(rt.store, { app: adapters.words.app, account: rt.who.account }, id, statusOf(r));
             }
             else if (refused) {
                 shown.current = false;

package/dist/client/entry.js

@@ -5,8 +5,11 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 // shows the sheet. `<ReportProblem>` is the same control for an error screen, already filled in.
 import { useEffect, useState } from 'react';
 import { useRuntime } from './runtime.js';
+import { firstToastThisOpen, moved, onSeen } from './seen.js';
 import { SuggestSheet } from './sheet.js';
-import { stringsFor } from './words.js';
+import { toast, Toasts } from './toast.js';
+import { useClearOnSignOut } from './view-cache.js';
+import { statusWords, stringsFor } from './words.js';
 /** Keeps the phone's outbox moving (on reconnect and every 15 seconds) for as long as it is mounted, with nothing drawn.
  *  <SuggestEntry> already does this; a host with no always-mounted entry mounts this once, high in the app. */
 export function KeepSending({ adapters }) {
@@ -17,7 +20,58 @@ export function SuggestEntry({ adapters, onOpen, className, role }) {
     const S = stringsFor(adapters.words);
     const [why, setWhy] = useState('');
     const [busy, setBusy] = useState(false);
+    // The runtime keeps the outbox moving while the entry is mounted (what <KeepSending> does).
+    const { rt, who } = useRuntime(adapters);
+    const [news, setNews] = useState(0);
+    const [toasting, setToasting] = useState(false);
     useEffect(() => { setWhy(''); }, [adapters]);
+    useClearOnSignOut(rt, who, adapters.words.app);
+    // Once per mount, asks the app for this person's reports and compares each with what they last opened: a move since
+    // then shows the dot, and the newest one gets the open's one toast. Opening a report (anywhere) clears it.
+    useEffect(() => {
+        setNews(0);
+        if (!rt)
+            return;
+        let live = true;
+        const id = { app: adapters.words.app, account: rt.who.account };
+        let rows = null;
+        const count = async () => {
+            if (!rows)
+                return;
+            const m = await moved(rt.store, id, rows);
+            if (live)
+                setNews(m.length);
+            return m;
+        };
+        void (async () => {
+            try {
+                rows = await adapters.store.mine();
+            }
+            catch {
+                rows = null;
+            }
+            let now = null;
+            try {
+                now = await adapters.identity();
+            }
+            catch {
+                now = null;
+            }
+            if (!live || !rows || !now || now.account !== rt.who.account)
+                return;
+            const m = await count();
+            if (!live || !m?.length || !firstToastThisOpen(id))
+                return;
+            const at = (x) => rows.find((r) => r.id === x)?.at ?? 0;
+            const top = [...m].sort((a, b) => at(b.id) - at(a.id))[0];
+            const note = top.status === 'not-now' ? rows.find((r) => r.id === top.id)?.note : undefined;
+            setToasting(true);
+            toast({ id: `sac-moved-${top.id}`, text: S.movedToast(statusWords(top.status, adapters.words.owner), typeof note === 'string' && note ? note : undefined), ms: 6000 });
+        })();
+        const off = onSeen(() => { void count(); });
+        return () => { live = false; off(); };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [rt]);
     async function press() {
         setBusy(true);
         let who = null;
@@ -35,7 +89,7 @@ export function SuggestEntry({ adapters, onOpen, className, role }) {
         setWhy('');
         onOpen();
     }
-    return (_jsxs("span", { className: "sac-entry-wrap", children: [_jsx(KeepSending, { adapters: adapters }), _jsx("button", { type: "button", role: role, "data-suggest-entry": "", className: `sac-entry${className ? ` ${className}` : ''}`, "aria-busy": busy || undefined, onClick: () => void press(), children: S.entry }), why ? _jsx("span", { role: "status", className: "sac-entry-why", children: why }) : null] }));
+    return (_jsxs("span", { className: "sac-entry-wrap", children: [_jsxs("button", { type: "button", role: role, "data-suggest-entry": "", className: `sac-entry${className ? ` ${className}` : ''}`, "aria-busy": busy || undefined, onClick: () => void press(), children: [S.entry, news ? _jsxs(_Fragment, { children: [_jsx("span", { className: "sac-entry-dot", "data-sac-moved": "", "aria-hidden": "true" }), _jsx("span", { className: "sac-sr", children: S.entryMoved })] }) : null] }), why ? _jsx("span", { role: "status", className: "sac-entry-why", children: why }) : null, toasting ? _jsx(Toasts, {}) : null] }));
 }
 /** For an error screen: opens the sheet as "something is broken", with the screen and what went wrong filled in. */
 export function ReportProblem({ adapters, screen, error }) {

package/dist/client/index.d.ts

@@ -12,5 +12,6 @@ export * from './receipt.tsx';
 export * from './entry.tsx';
 export * from './sheet.tsx';
 export * from './mine.tsx';
+export { seenStatuses, markSeen, moved, onSeen, seenKey, type Seen } from './seen.ts';
 export * from './detail.tsx';
 export { refreshIdentity } from './runtime.ts';

package/dist/client/index.js

@@ -12,5 +12,6 @@ export * from './receipt.js';
 export * from './entry.js';
 export * from './sheet.js';
 export * from './mine.js';
+export { seenStatuses, markSeen, moved, onSeen, seenKey } from './seen.js';
 export * from './detail.js';
 export { refreshIdentity } from './runtime.js';

package/dist/client/mine.js

@@ -7,6 +7,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { SuggestionDetail } from './detail.js';
 import { useRuntime, useTick } from './runtime.js';
+import { moved, onSeen } from './seen.js';
 import { dropCache, isRefusal, mineCacheKey, pruneOnes, readCache, useClearOnSignOut, writeCache } from './view-cache.js';
 import { Toasts } from './toast.js';
 import { statusMeaning, statusWords, stringsFor } from './words.js';
@@ -19,6 +20,8 @@ export function MySuggestions({ adapters, onOpen }) {
     const [open, setOpen] = useState(null);
     const [bad, setBad] = useState('');
     const [updating, setUpdating] = useState(false);
+    // Reports that moved to a telling status since the person last opened them: their rows say New.
+    const [fresh, setFresh] = useState(() => new Set());
     // Another account (or none) shows nothing of the last one's rows.
     const loads = useRef(0);
     // What the app last said (or the phone kept of it) for this account; null until either is known.
@@ -26,7 +29,16 @@ export function MySuggestions({ adapters, onOpen }) {
     // The first answer after mount ends "Updating"; later periodic reloads refresh quietly.
     const answered = useRef(false);
     useClearOnSignOut(rt, who, adapters.words.app);
-    useEffect(() => { loads.current++; known.current = null; answered.current = false; setRows(null); setOpen(null); setBad(''); setUpdating(false); }, [rt]);
+    useEffect(() => { loads.current++; known.current = null; answered.current = false; setRows(null); setOpen(null); setBad(''); setUpdating(false); setFresh(new Set()); }, [rt]);
+    const recount = useCallback(async () => {
+        if (!rt || !known.current)
+            return;
+        const mine_ = loads.current;
+        const m = await moved(rt.store, { app: adapters.words.app, account: rt.who.account }, known.current);
+        if (mine_ === loads.current)
+            setFresh(new Set(m.map((x) => x.id)));
+    }, [adapters.words.app, rt]);
+    useEffect(() => onSeen(() => { void recount(); }), [recount]);
     const load = useCallback(async () => {
         if (!rt)
             return;
@@ -85,6 +97,7 @@ export function MySuggestions({ adapters, onOpen }) {
             void pruneOnes(rt.store, { app: adapters.words.app, account: rt.who.account }, theirs.map((t) => t.id));
             setBad('');
             paint(theirs, local);
+            void recount();
         }
         else if (refused) {
             // The app said no: what the phone held is no longer this person's to see.
@@ -101,7 +114,7 @@ export function MySuggestions({ adapters, onOpen }) {
             setBad(S.couldNotLoadMine);
             paint([], local);
         }
-    }, [adapters, rt, S.couldNotLoadMine, S.offlineShowingSaved]);
+    }, [adapters, rt, recount, S.couldNotLoadMine, S.offlineShowingSaved]);
     useEffect(() => { void load(); }, [load, tick]);
     if (who === null)
         return _jsx("p", { role: "alert", children: S.signedOutMine });
@@ -110,6 +123,6 @@ export function MySuggestions({ adapters, onOpen }) {
     }
     return (_jsxs("section", { className: "sac-mine", "aria-labelledby": "sac-mine-title", children: [_jsx("h2", { id: "sac-mine-title", className: "sac-title", children: S.mineTitle }), bad ? _jsx("p", { role: "alert", className: "sac-error", children: bad }) : null, updating ? _jsx("p", { role: "status", className: "sac-muted", "data-updating": "", children: S.updating }) : null, rows === null ? _jsx("p", { children: S.loading }) : rows.length === 0 ? _jsx("p", { children: S.mineEmpty }) : (_jsx("ul", { className: "sac-list", children: rows.map((r) => {
                     const preview = typeof r.words === 'string' ? r.words : typeof r.title === 'string' ? r.title : '';
-                    return (_jsxs("li", { className: "sac-row", "data-status": r.status, children: [_jsxs("button", { type: "button", className: "sac-row-button", onClick: () => (onOpen ? onOpen(r.id) : setOpen(r.id)), children: [preview ? _jsx("span", { className: "sac-row-words", children: preview }) : null, _jsx("span", { className: "sac-row-status", children: statusWords(r.status, owner) }), _jsx("span", { className: "sac-muted", children: statusMeaning(r.status, owner) })] }), r.error ? (_jsxs(_Fragment, { children: [_jsx("p", { role: "alert", className: "sac-error", children: r.error }), rt ? _jsx("button", { type: "button", className: "sac-button", onClick: () => void rt.retry(r.id), children: S.retry }) : null] })) : null] }, r.id));
+                    return (_jsxs("li", { className: "sac-row", "data-status": r.status, children: [_jsxs("button", { type: "button", className: "sac-row-button", onClick: () => (onOpen ? onOpen(r.id) : setOpen(r.id)), children: [fresh.has(r.id) ? _jsx("span", { className: "sac-new", "data-new": "", children: S.newMark }) : null, preview ? _jsx("span", { className: "sac-row-words", children: preview }) : null, _jsx("span", { className: "sac-row-status", children: statusWords(r.status, owner) }), _jsx("span", { className: "sac-muted", children: statusMeaning(r.status, owner) })] }), r.error ? (_jsxs(_Fragment, { children: [_jsx("p", { role: "alert", className: "sac-error", children: r.error }), rt ? _jsx("button", { type: "button", className: "sac-button", onClick: () => void rt.retry(r.id), children: S.retry }) : null] })) : null] }, r.id));
                 }) })), _jsx(Toasts, {})] }));
 }

package/dist/client/outbox.d.ts

@@ -9,6 +9,8 @@ export interface Op {
     /** The id of the write this one belongs to (a part's report or follow-up). While that write is refused, this one is held, not sent. */
     parent?: string;
     at: number;
+    /** The order this phone made it in, among writes with the same `at`. Written by enqueue. */
+    seq?: number;
     error?: string;
 }
 export type Sent = 'done' | {

package/dist/client/outbox.js

@@ -5,8 +5,11 @@ export function makeOutbox({ store, send, reach }) {
     // the new write existed. Measured on the phone: without this, a second answer sat on the phone
     // until the 15 s tick.
     let again = false;
+    // Two writes in one millisecond (a save, then the step that reads it) keep the order they were made
+    // in. Ordering them by id instead sent the second first about half the time.
+    let made = 0;
     async function pending() {
-        return (await store.all('outbox')).map((r) => r.value).sort((a, b) => a.at - b.at || a.id.localeCompare(b.id));
+        return (await store.all('outbox')).map((r) => r.value).sort((a, b) => a.at - b.at || (a.seq ?? 0) - (b.seq ?? 0) || a.id.localeCompare(b.id));
     }
     async function tell(landed) {
         const all = await pending();
@@ -56,7 +59,7 @@ export function makeOutbox({ store, send, reach }) {
     }
     return {
         pending,
-        async enqueue(op) { await store.put('outbox', op.id, op); await tell(); },
+        async enqueue(op) { await store.put('outbox', op.id, { ...op, seq: op.seq ?? ++made }); await tell(); },
         drain() {
             if (running) {
                 again = true;

package/dist/client/seen.d.ts

@@ -0,0 +1,24 @@
+import type { Store } from './idb.ts';
+type Id = {
+    app: string;
+    account: string;
+};
+export type Seen = Record<string, string>;
+export declare const seenKey: (id: Id) => string;
+/** Called whenever something is marked seen, so a dot drawn elsewhere can clear. */
+export declare function onSeen(fn: () => void): () => void;
+export declare function seenStatuses(store: Store, id: Id): Promise<Seen>;
+/** The person has looked at this report at this status. */
+export declare function markSeen(store: Store, id: Id, reportId: string, status: string): Promise<void>;
+/** The rows that moved to a telling status since the person last looked, in the order given. A report seen for the first
+ *  time is recorded silently (so an app taking this release does not announce every old report), and so is a move to a
+ *  quiet status (the planning steps); a telling move stays unrecorded until the person opens the report. */
+export declare function moved(store: Store, id: Id, rows: {
+    id: string;
+    status: string;
+}[]): Promise<{
+    id: string;
+    status: string;
+}[]>;
+export declare function firstToastThisOpen(id: Id): boolean;
+export {};

package/dist/client/seen.js

@@ -0,0 +1,71 @@
+'use client';
+// WHAT THE PERSON LAST LOOKED AT. Per app and account, the status each of their reports had the last time they
+// opened it. A report whose status has since moved to one they should hear about (`TOLD`: the work starting, and
+// every end) is "moved": the entry shows a dot, My suggestions marks the row New, and one toast says it. Opening
+// the report marks it seen. The record sits beside the cached views, under the same app-and-account key, so another
+// account never reads it and signing out clears it with them (clearViewCache).
+import { TOLD } from '../contract.mjs';
+import { draftKey } from './drafts.js';
+import { readCache, writeCache } from './view-cache.js';
+export const seenKey = (id) => `${draftKey(id)}#view:seen`;
+const listeners = new Set();
+/** Called whenever something is marked seen, so a dot drawn elsewhere can clear. */
+export function onSeen(fn) { listeners.add(fn); return () => { listeners.delete(fn); }; }
+// One write at a time per key, so two screens recording at once never drop each other's entries.
+const chains = new Map();
+function serial(key, job) {
+    const next = (chains.get(key) ?? Promise.resolve()).then(job, job);
+    chains.set(key, next.catch(() => { }));
+    return next;
+}
+export async function seenStatuses(store, id) {
+    const v = await readCache(store, seenKey(id));
+    return v && typeof v === 'object' ? { ...v } : {};
+}
+/** The person has looked at this report at this status. */
+export function markSeen(store, id, reportId, status) {
+    return serial(seenKey(id), async () => {
+        const seen = await seenStatuses(store, id);
+        if (seen[reportId] === status)
+            return;
+        seen[reportId] = status;
+        await writeCache(store, seenKey(id), seen);
+        for (const l of listeners)
+            l();
+    });
+}
+/** The rows that moved to a telling status since the person last looked, in the order given. A report seen for the first
+ *  time is recorded silently (so an app taking this release does not announce every old report), and so is a move to a
+ *  quiet status (the planning steps); a telling move stays unrecorded until the person opens the report. */
+export function moved(store, id, rows) {
+    return serial(seenKey(id), async () => {
+        const seen = await seenStatuses(store, id);
+        const out = [];
+        let changed = false;
+        for (const r of rows) {
+            if (typeof r?.id !== 'string' || typeof r.status !== 'string' || r.status === 'on-phone')
+                continue;
+            const had = seen[r.id];
+            if (had === r.status)
+                continue;
+            if (had === undefined || !TOLD.includes(r.status)) {
+                seen[r.id] = r.status;
+                changed = true;
+                continue;
+            }
+            out.push({ id: r.id, status: r.status });
+        }
+        if (changed)
+            await writeCache(store, seenKey(id), seen);
+        return out;
+    });
+}
+/** One toast per app open, per account: a remounted entry in the same open does not say it again. */
+const toasted = new Set();
+export function firstToastThisOpen(id) {
+    const k = seenKey(id);
+    if (toasted.has(k))
+        return false;
+    toasted.add(k);
+    return true;
+}

package/dist/client/words.d.ts

@@ -90,6 +90,12 @@ export interface Strings {
     addFailed: string;
     overLimit: string;
     stepLabel: string;
+    /** On a row in My suggestions that moved since the person last opened it. */
+    newMark: string;
+    /** Read by a screen reader on the entry when a suggestion has moved (the dot itself is decoration). */
+    entryMoved: string;
+    /** The one toast per open. `words` is the status's own word (wordsFor); `note` is the not-now reason, when there is one. */
+    movedToast: (words: string, note?: string) => string;
 }
 export declare const DEFAULT_STRINGS: Strings;
 export declare function stringsFor(words: Words): Strings;

package/dist/client/words.js

@@ -84,6 +84,9 @@ export const DEFAULT_STRINGS = {
     addFailed: 'That could not be added. Try again.',
     overLimit: 'Something in this suggestion is over a limit. Remove an attachment and try again.',
     stepLabel: 'Where it is',
+    newMark: 'New',
+    entryMoved: 'One of your suggestions has news',
+    movedToast: (words, note) => (note ? `Your suggestion: ${words}. ${note}` : `Your suggestion: ${words}`),
 };
 export function stringsFor(words) {
     return { ...DEFAULT_STRINGS, ...words.text };

package/dist/contract.d.mts

@@ -12,6 +12,7 @@ export declare const CEILINGS: {
 };
 export declare const STATUSES: string[];
 export declare const END: string[];
+export declare const TOLD: string[];
 export declare const FLOW: {
     "on-phone": {
         actor: string;

package/dist/contract.mjs

@@ -13,6 +13,8 @@ export const CEILINGS = {
 };
 export const STATUSES = ["on-phone", "received", "with-freeda", "planned", "waiting-on-owner", "being-made", "live", "sent-to-template", "filed", "not-now"];
 export const END = ["live", "sent-to-template", "filed", "not-now"];
+// The moves the person who suggested a change hears about: the work starting, and every end. The planning steps stay quiet.
+export const TOLD = ["being-made", ...END];
 // actor: who PERFORMS this step (design section 7): sent by the person, received by the app, with Pluma by the Mac. A Helm on the owner's Mac posts straight into
 // the inbox, so a report may go from the phone to Pluma without the hosted app's "received". The owner may decline
 // ("not-now") before Pluma has a plan or before she asks: a report she cannot plan would otherwise have no exit.

package/dist/server/handlers.d.ts

@@ -1,3 +1,4 @@
+import { TOLD } from '../contract.mjs';
 import { type Limits } from './rate.ts';
 /** `by` is the actor (contract FLOW). `holder` is the maintainer whose Mac started or ended the work, written on a being-made
  *  or end entry: the approval on such a report never lapses, and it is how the list and the claim name who has it. */
@@ -131,10 +132,24 @@ export interface HostedStore {
         expiresAt: number;
     }>;
 }
+/** `status` events also carry the report's member and its new status. */
 export interface TellEvent {
     type: 'submitted' | 'followed-up' | 'status' | 'settled';
     reportId: string;
     member?: string;
+    status?: string;
+}
+export { TOLD };
+/** What `tellSubmitter` is handed. `words` and `meaning` are the module's own words for the status (`wordsFor`/`meaningFor`),
+ *  never the report's text, so a lock screen never shows what someone wrote. `note` is the one-line reason, on `not-now` only. */
+export interface SubmitterNews {
+    member: string;
+    reportId: string;
+    status: string;
+    words: string;
+    meaning: string;
+    ended: boolean;
+    note?: string;
 }
 export interface ReportHandlerOptions {
     store: HostedStore;
@@ -153,6 +168,13 @@ export interface ReportHandlerOptions {
     maintainersSince?: Record<string, number | string>;
     /** Told when something happens, with ids and never words. A failure here never fails the request. */
     tell?(event: TellEvent): void | Promise<void>;
+    /** REQUIRED: tells the person who suggested a change that it is being made or has ended, on the app's own channel (push,
+     *  email, an activity row). Called once per telling move (`TOLD`), never on a repeat, never when the store refused the move,
+     *  and never to a maintainer about their own report being made. A failure never fails the move. An app that genuinely
+     *  has nobody to tell passes `{ none: "<reason>" }`; leaving it out throws at startup. */
+    tellSubmitter: ((news: SubmitterNews) => void | Promise<void>) | {
+        none: string;
+    };
     now?: () => number;
 }
 export declare const LEASE_MS: number;

package/dist/server/handlers.js

@@ -7,7 +7,7 @@
 // a report is decided here from the signed-in member and the explicit maintainers list, never from the
 // request. Nothing is uploaded through this server: `uploadUrl` issues a direct-to-storage link with the
 // size and type fixed, and `finalize` checks what actually landed.
-import { END, FLOW, STATUSES, isAcceptedMedia, isReportId, mayMove, validateReport } from '../contract.mjs';
+import { END, FLOW, STATUSES, TOLD, isAcceptedMedia, isReportId, mayMove, meaningFor, validateReport, wordsFor } from '../contract.mjs';
 import { effectiveLimits } from './rate.js';
 import { ACCEPTED_TYPES, canonicalType, sameType } from './sniff.js';
 /** What a collector saw of a report: its verified files and its follow-ups. A store computes this from its own copy,
@@ -17,6 +17,7 @@ export function reportRevision(r) {
     const ups = (r.followUps ?? []).map((f) => f.followId).sort();
     return `f:${files.join(',')}|u:${ups.join(',')}`;
 }
+export { TOLD };
 export const LEASE_MS = 10 * 60_000;
 const WORDS_MAX = 20_000;
 // Sized from the field limits: words and the three answers at 4 bytes a character (any script), plus the rest.
@@ -100,6 +101,15 @@ function declaredFile(r, file) {
 }
 export function createReportHandlers(opts) {
     const { store, identity, agent } = opts;
+    const hook = opts.tellSubmitter;
+    if (typeof hook !== 'function') {
+        const reason = hook && typeof hook === 'object' ? hook.none : undefined;
+        if (hook === undefined || hook === null)
+            throw new Error('createReportHandlers needs tellSubmitter: a function that tells the person who suggested a change when it is being made and when it ends, or { none: "<reason>" } when the app has nobody to tell');
+        if (typeof reason !== 'string' || !reason.trim())
+            throw new Error('tellSubmitter { none } needs a reason: say why this app tells nobody, as { none: "<reason>" }');
+    }
+    const tellSubmitter = typeof hook === 'function' ? hook : null;
     const maintainers = [...opts.maintainers];
     const limits = effectiveLimits(opts.limits);
     const contractCeilings = { images: limits.images, imageBytes: limits.imageBytes, videos: limits.videos, videoBytes: limits.videoBytes, videoMs: limits.videoMs, voiceMs: limits.voiceMs, voiceTotalMs: limits.voiceTotalMs, perPersonPerDay: limits.perPersonPerDay };
@@ -109,6 +119,11 @@ export function createReportHandlers(opts) {
         await opts.tell?.(e);
     }
     catch { /* telling is best effort */ } };
+    const owner = typeof opts.app?.owner === 'string' && opts.app.owner ? opts.app.owner : 'the owner';
+    const news = async (n) => { try {
+        await tellSubmitter?.(n);
+    }
+    catch { /* telling is best effort */ } };
     const isMaintainer = (m) => maintainers.includes(m);
     const roleOf = (m) => (isMaintainer(m) ? 'maintainer' : 'member');
     const wrongMethod = (req, m) => (req.method === m ? null : json(405, { error: 'method not allowed' }));
@@ -259,7 +274,9 @@ export function createReportHandlers(opts) {
         // Filtered again here: a store that over-returns still cannot show another member's report.
         const rows = (await store.listFor(member)).filter((r) => r.who?.member === member);
         rows.sort((a, b) => (a.receivedAt < b.receivedAt ? 1 : -1));
-        return json(200, rows.map((r) => ({ id: r.id, status: lastStatus(r), kind: r.kind, at: Date.parse(r.receivedAt) })));
+        // A declined report carries its one-line reason, which the member's own view already shows; no other note is listed.
+        const reason = (r) => { const t = r.timeline[r.timeline.length - 1]; return t?.status === 'not-now' && t.note ? { note: t.note } : {}; };
+        return json(200, rows.map((r) => ({ id: r.id, status: lastStatus(r), kind: r.kind, at: Date.parse(r.receivedAt), ...reason(r) })));
     }
     async function one(req, id) {
         const m = wrongMethod(req, 'GET');
@@ -572,7 +589,13 @@ export function createReportHandlers(opts) {
                 await store.claimApproval(id, by, APPROVAL_LEASE_MS);
             return json(409, { error: 'the report changed while this was sent; read it again' });
         }
-        await tell({ type: 'status', reportId: id });
+        await tell({ type: 'status', reportId: id, member: r.who?.member, status });
+        const member = r.who?.member;
+        // A maintainer is not told that the work they just started on their own report has started; an end is still news.
+        const ownStart = status === 'being-made' && member === by;
+        if (member && TOLD.includes(status) && !ownStart) {
+            await news({ member, reportId: id, status, words: wordsFor(status, { owner }), meaning: meaningFor(status, { owner }), ended: END.includes(status), ...(status === 'not-now' && note ? { note } : {}) });
+        }
         return json(200, { id, status });
     }
     return { submit, uploadUrl, finalize, mine, one, append, agentList, agentFile, agentSettle, agentClaimApproval, agentReleaseApproval, agentStatus };

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
-export { createReportHandlers, reportRevision, VOICE_BYTES_PER_SECOND, LEASE_MS, BODY_CAP, APPROVAL_LEASE_MS, HELD_MS, READ_TTL_MS, INCOMPLETE_GRACE_MS, VOICE_FILE_BYTES } from './handlers.ts';
-export type { HostedStore, StoredReport, TimelineEntry, FileState, FollowUp, TellEvent, ReportHandlerOptions } from './handlers.ts';
+export { createReportHandlers, reportRevision, TOLD, VOICE_BYTES_PER_SECOND, LEASE_MS, BODY_CAP, APPROVAL_LEASE_MS, HELD_MS, READ_TTL_MS, INCOMPLETE_GRACE_MS, VOICE_FILE_BYTES } from './handlers.ts';
+export type { HostedStore, StoredReport, TimelineEntry, FileState, FollowUp, TellEvent, SubmitterNews, ReportHandlerOptions } from './handlers.ts';
 export { sniffType, sameType, canonicalType, ACCEPTED_TYPES } from './sniff.ts';
 export { effectiveLimits } from './rate.ts';
 export type { Limits } from './rate.ts';

package/dist/server/index.js

@@ -1,5 +1,5 @@
 // "@supersuit/suggest-a-change/server": web-standard APIs only, no runtime dependency, nothing from react or the client.
-export { createReportHandlers, reportRevision, VOICE_BYTES_PER_SECOND, LEASE_MS, BODY_CAP, APPROVAL_LEASE_MS, HELD_MS, READ_TTL_MS, INCOMPLETE_GRACE_MS, VOICE_FILE_BYTES } from './handlers.js';
+export { createReportHandlers, reportRevision, TOLD, VOICE_BYTES_PER_SECOND, LEASE_MS, BODY_CAP, APPROVAL_LEASE_MS, HELD_MS, READ_TTL_MS, INCOMPLETE_GRACE_MS, VOICE_FILE_BYTES } from './handlers.js';
 export { sniffType, sameType, canonicalType, ACCEPTED_TYPES } from './sniff.js';
 export { effectiveLimits } from './rate.js';
 export { runStoreConformance, checks as conformanceChecks } from './conformance.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/suggest-a-change",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "The report format and flow behind a Suggest a change button: what a report is, who acts at each step, the screens, and the check every app runs. The contract has zero dependencies.",
   "type": "module",
   "bin": {

package/src/check/init.mjs

@@ -39,6 +39,7 @@ const stubFor = (app, owner) => `// ${STUB_SENTINEL}. These adapters sign nobody
 // Fill in the four below, then delete this line. "suggest-a-change-check --strict" fails while it is here.
 // The four things this app supplies to Suggest a change; the module owns everything else.
 import type { Adapters } from "${NAME}/client";
+import type { ReportHandlerOptions } from "${NAME}/server";
 
 /** Who is signed in: { account, role } where role is "operator", "member" or "maintainer", or null. */
 export const identity: Adapters["identity"] = async () => null; // TODO: read this app's own session
@@ -57,6 +58,11 @@ export const words: Adapters["words"] = { app: ${JSON.stringify(app)}, owner: ${
 
 /** Attachment limits. May lower the module's ceilings, never raise them. */
 export const limits: Adapters["limits"] = {};
+
+/** For the server half: createReportHandlers({ ..., tellSubmitter }) requires it. Tell e.member that their suggestion
+ *  is being made or has ended, on this app's own channel (push, email, an activity row), using e.words and e.note,
+ *  never the report's text. An app with nobody to tell passes { none: "<reason>" } instead. */
+export const tellSubmitter: ReportHandlerOptions["tellSubmitter"] = async () => {}; // TODO: tell e.member e.words
 `
 
 const componentFor = (adaptersImport) => `"use client";
@@ -143,6 +149,12 @@ export function initApp({ repo, app, owner = 'Owner' }) {
   if (writeIfAbsent(join(root, 'tailor', 'suggest-a-change.ts'), stubFor(id, owner), log, 'tailor/suggest-a-change.ts'))
     log.notes.push('the adapters in tailor/suggest-a-change.ts are stubs: nobody is signed in and every report is refused, so the button opens nothing until you fill them in. Then delete the "suggest-a-change: STUB" line and use "suggest-a-change-check --strict" in your check script')
 
+  // The server half refuses to start without tellSubmitter, so say so wherever the adapters file does not carry one.
+  const tailor = join(root, 'tailor', 'suggest-a-change.ts')
+  const tailorText = existsSync(tailor) ? readFileSync(tailor, 'utf8') : ''
+  if (log.did.includes('wrote tailor/suggest-a-change.ts') || !/\btellSubmitter\b/.test(tailorText))
+    log.notes.push('the server half needs tellSubmitter: createReportHandlers({ ..., tellSubmitter }) throws at startup without it. Tell the person who suggested a change, on this app\'s own channel, when it is being made and when it ends (the stub in tailor/suggest-a-change.ts is where it goes), or pass tellSubmitter: { none: "<reason>" } when the app has nobody to tell')
+
   // 4. The component and the root layout.
   const compPath = join(root, dirname(appDir), 'components', 'suggest-a-change.tsx')
   const adaptersImport = dotted(posix(relative(dirname(compPath), join(root, 'tailor', 'suggest-a-change'))))

package/src/client/detail.tsx

@@ -10,6 +10,7 @@ import { draftKey } from './drafts.ts'
 import { recoverTakes } from './recorder.ts'
 import { queueFollowUp, type Report } from './reports.ts'
 import { useRuntime, useTick, type FollowUp } from './runtime.ts'
+import { markSeen } from './seen.ts'
 import { Toasts } from './toast.tsx'
 import { dropCache, isRefusal, oneCacheKey, readCache, useClearOnSignOut, writeCache } from './view-cache.ts'
 import { effectiveCeilings, lengthWords, sizeWords, statusMeaning, statusWords, stringsFor } from './words.ts'
@@ -137,7 +138,11 @@ export function SuggestionDetail({ adapters, id }: { adapters: Adapters; id: str
       if (!fresh()) return
       if (!now || now.account !== rt.who.account) return
       setUpdating(false)
-      if (r) { shown.current = true; setOffline(false); setReport(r); void writeCache(rt.store, ckey, r) }
+      if (r) {
+        shown.current = true; setOffline(false); setReport(r); void writeCache(rt.store, ckey, r)
+        // The person has now seen it at this status: its New mark and the entry's dot clear.
+        void markSeen(rt.store, { app: adapters.words.app, account: rt.who.account }, id, statusOf(r))
+      }
       else if (refused) { shown.current = false; setOffline(false); void dropCache(rt.store, ckey); setReport(null) }
       else if (shown.current) setOffline(true)
       else setReport(null)

package/src/client/entry.tsx

@@ -5,8 +5,11 @@
 import { useEffect, useState, type AriaRole } from 'react'
 import type { Adapters } from './adapters.ts'
 import { useRuntime } from './runtime.ts'
+import { firstToastThisOpen, moved, onSeen } from './seen.ts'
 import { SuggestSheet } from './sheet.tsx'
-import { stringsFor } from './words.ts'
+import { toast, Toasts } from './toast.tsx'
+import { useClearOnSignOut } from './view-cache.ts'
+import { statusWords, stringsFor } from './words.ts'
 
 /** Keeps the phone's outbox moving (on reconnect and every 15 seconds) for as long as it is mounted, with nothing drawn.
  *  <SuggestEntry> already does this; a host with no always-mounted entry mounts this once, high in the app. */
@@ -19,7 +22,43 @@ export function SuggestEntry({ adapters, onOpen, className, role }: { adapters:
   const S = stringsFor(adapters.words)
   const [why, setWhy] = useState('')
   const [busy, setBusy] = useState(false)
+  // The runtime keeps the outbox moving while the entry is mounted (what <KeepSending> does).
+  const { rt, who } = useRuntime(adapters)
+  const [news, setNews] = useState(0)
+  const [toasting, setToasting] = useState(false)
   useEffect(() => { setWhy('') }, [adapters])
+  useClearOnSignOut(rt, who, adapters.words.app)
+  // Once per mount, asks the app for this person's reports and compares each with what they last opened: a move since
+  // then shows the dot, and the newest one gets the open's one toast. Opening a report (anywhere) clears it.
+  useEffect(() => {
+    setNews(0)
+    if (!rt) return
+    let live = true
+    const id = { app: adapters.words.app, account: rt.who.account }
+    let rows: { id: string; status: string; note?: unknown; at?: number }[] | null = null
+    const count = async () => {
+      if (!rows) return
+      const m = await moved(rt.store, id, rows)
+      if (live) setNews(m.length)
+      return m
+    }
+    void (async () => {
+      try { rows = await adapters.store.mine() } catch { rows = null }
+      let now: { account: string } | null = null
+      try { now = await adapters.identity() } catch { now = null }
+      if (!live || !rows || !now || now.account !== rt.who.account) return
+      const m = await count()
+      if (!live || !m?.length || !firstToastThisOpen(id)) return
+      const at = (x: string) => rows!.find((r) => r.id === x)?.at ?? 0
+      const top = [...m].sort((a, b) => at(b.id) - at(a.id))[0]
+      const note = top.status === 'not-now' ? rows.find((r) => r.id === top.id)?.note : undefined
+      setToasting(true)
+      toast({ id: `sac-moved-${top.id}`, text: S.movedToast(statusWords(top.status, adapters.words.owner), typeof note === 'string' && note ? note : undefined), ms: 6000 })
+    })()
+    const off = onSeen(() => { void count() })
+    return () => { live = false; off() }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [rt])
   async function press() {
     setBusy(true)
     let who = null
@@ -31,9 +70,12 @@ export function SuggestEntry({ adapters, onOpen, className, role }: { adapters:
   }
   return (
     <span className="sac-entry-wrap">
-      <KeepSending adapters={adapters} />
-      <button type="button" role={role} data-suggest-entry="" className={`sac-entry${className ? ` ${className}` : ''}`} aria-busy={busy || undefined} onClick={() => void press()}>{S.entry}</button>
+      <button type="button" role={role} data-suggest-entry="" className={`sac-entry${className ? ` ${className}` : ''}`} aria-busy={busy || undefined} onClick={() => void press()}>
+        {S.entry}
+        {news ? <><span className="sac-entry-dot" data-sac-moved="" aria-hidden="true" /><span className="sac-sr">{S.entryMoved}</span></> : null}
+      </button>
       {why ? <span role="status" className="sac-entry-why">{why}</span> : null}
+      {toasting ? <Toasts /> : null}
     </span>
   )
 }

package/src/client/index.ts

@@ -12,5 +12,6 @@ export * from './receipt.tsx'
 export * from './entry.tsx'
 export * from './sheet.tsx'
 export * from './mine.tsx'
+export { seenStatuses, markSeen, moved, onSeen, seenKey, type Seen } from './seen.ts'
 export * from './detail.tsx'
 export { refreshIdentity } from './runtime.ts'

package/src/client/mine.tsx

@@ -8,6 +8,7 @@ import type { Adapters } from './adapters.ts'
 import { SuggestionDetail } from './detail.tsx'
 import type { Summary } from './reports.ts'
 import { useRuntime, useTick } from './runtime.ts'
+import { moved, onSeen } from './seen.ts'
 import { dropCache, isRefusal, mineCacheKey, pruneOnes, readCache, useClearOnSignOut, writeCache } from './view-cache.ts'
 import { Toasts } from './toast.tsx'
 import { statusMeaning, statusWords, stringsFor } from './words.ts'
@@ -23,6 +24,8 @@ export function MySuggestions({ adapters, onOpen }: { adapters: Adapters; onOpen
   const [open, setOpen] = useState<string | null>(null)
   const [bad, setBad] = useState('')
   const [updating, setUpdating] = useState(false)
+  // Reports that moved to a telling status since the person last opened them: their rows say New.
+  const [fresh, setFresh] = useState<Set<string>>(() => new Set())
 
   // Another account (or none) shows nothing of the last one's rows.
   const loads = useRef(0)
@@ -31,7 +34,15 @@ export function MySuggestions({ adapters, onOpen }: { adapters: Adapters; onOpen
   // The first answer after mount ends "Updating"; later periodic reloads refresh quietly.
   const answered = useRef(false)
   useClearOnSignOut(rt, who, adapters.words.app)
-  useEffect(() => { loads.current++; known.current = null; answered.current = false; setRows(null); setOpen(null); setBad(''); setUpdating(false) }, [rt])
+  useEffect(() => { loads.current++; known.current = null; answered.current = false; setRows(null); setOpen(null); setBad(''); setUpdating(false); setFresh(new Set()) }, [rt])
+
+  const recount = useCallback(async () => {
+    if (!rt || !known.current) return
+    const mine_ = loads.current
+    const m = await moved(rt.store, { app: adapters.words.app, account: rt.who.account }, known.current)
+    if (mine_ === loads.current) setFresh(new Set(m.map((x) => x.id)))
+  }, [adapters.words.app, rt])
+  useEffect(() => onSeen(() => { void recount() }), [recount])
 
   const load = useCallback(async () => {
     if (!rt) return
@@ -73,6 +84,7 @@ export function MySuggestions({ adapters, onOpen }: { adapters: Adapters; onOpen
       void pruneOnes(rt.store, { app: adapters.words.app, account: rt.who.account }, theirs.map((t) => t.id))
       setBad('')
       paint(theirs, local)
+      void recount()
     } else if (refused) {
       // The app said no: what the phone held is no longer this person's to see.
       known.current = null
@@ -86,7 +98,7 @@ export function MySuggestions({ adapters, onOpen }: { adapters: Adapters; onOpen
       setBad(S.couldNotLoadMine)
       paint([], local)
     }
-  }, [adapters, rt, S.couldNotLoadMine, S.offlineShowingSaved])
+  }, [adapters, rt, recount, S.couldNotLoadMine, S.offlineShowingSaved])
   useEffect(() => { void load() }, [load, tick])
 
   if (who === null) return <p role="alert">{S.signedOutMine}</p>
@@ -110,6 +122,7 @@ export function MySuggestions({ adapters, onOpen }: { adapters: Adapters; onOpen
             return (
               <li key={r.id} className="sac-row" data-status={r.status}>
                 <button type="button" className="sac-row-button" onClick={() => (onOpen ? onOpen(r.id) : setOpen(r.id))}>
+                  {fresh.has(r.id) ? <span className="sac-new" data-new="">{S.newMark}</span> : null}
                   {preview ? <span className="sac-row-words">{preview}</span> : null}
                   <span className="sac-row-status">{statusWords(r.status, owner)}</span>
                   <span className="sac-muted">{statusMeaning(r.status, owner)}</span>

package/src/client/outbox.ts

@@ -18,6 +18,8 @@ export interface Op {
   /** The id of the write this one belongs to (a part's report or follow-up). While that write is refused, this one is held, not sent. */
   parent?: string
   at: number
+  /** The order this phone made it in, among writes with the same `at`. Written by enqueue. */
+  seq?: number
   error?: string
 }
 export type Sent = 'done' | { refused: string }
@@ -30,9 +32,12 @@ export function makeOutbox({ store, send, reach }: { store: Store; send(op: Op):
   // the new write existed. Measured on the phone: without this, a second answer sat on the phone
   // until the 15 s tick.
   let again = false
+  // Two writes in one millisecond (a save, then the step that reads it) keep the order they were made
+  // in. Ordering them by id instead sent the second first about half the time.
+  let made = 0
 
   async function pending(): Promise<Op[]> {
-    return (await store.all<Op>('outbox')).map((r) => r.value).sort((a, b) => a.at - b.at || a.id.localeCompare(b.id))
+    return (await store.all<Op>('outbox')).map((r) => r.value).sort((a, b) => a.at - b.at || (a.seq ?? 0) - (b.seq ?? 0) || a.id.localeCompare(b.id))
   }
   async function tell(landed?: string) {
     const all = await pending()
@@ -69,7 +74,7 @@ export function makeOutbox({ store, send, reach }: { store: Store; send(op: Op):
   }
   return {
     pending,
-    async enqueue(op: Op) { await store.put('outbox', op.id, op); await tell() },
+    async enqueue(op: Op) { await store.put('outbox', op.id, { ...op, seq: op.seq ?? ++made }); await tell() },
     drain(): Promise<void> {
       if (running) { again = true; return running }
       return (running = run().finally(() => { running = null }))

package/src/client/seen.ts

@@ -0,0 +1,71 @@
+'use client'
+// WHAT THE PERSON LAST LOOKED AT. Per app and account, the status each of their reports had the last time they
+// opened it. A report whose status has since moved to one they should hear about (`TOLD`: the work starting, and
+// every end) is "moved": the entry shows a dot, My suggestions marks the row New, and one toast says it. Opening
+// the report marks it seen. The record sits beside the cached views, under the same app-and-account key, so another
+// account never reads it and signing out clears it with them (clearViewCache).
+import { TOLD } from '../contract.mjs'
+import { draftKey } from './drafts.ts'
+import type { Store } from './idb.ts'
+import { readCache, writeCache } from './view-cache.ts'
+
+type Id = { app: string; account: string }
+export type Seen = Record<string, string>
+export const seenKey = (id: Id) => `${draftKey(id)}#view:seen`
+
+const listeners = new Set<() => void>()
+/** Called whenever something is marked seen, so a dot drawn elsewhere can clear. */
+export function onSeen(fn: () => void): () => void { listeners.add(fn); return () => { listeners.delete(fn) } }
+
+// One write at a time per key, so two screens recording at once never drop each other's entries.
+const chains = new Map<string, Promise<unknown>>()
+function serial<T>(key: string, job: () => Promise<T>): Promise<T> {
+  const next = (chains.get(key) ?? Promise.resolve()).then(job, job)
+  chains.set(key, next.catch(() => {}))
+  return next
+}
+
+export async function seenStatuses(store: Store, id: Id): Promise<Seen> {
+  const v = await readCache<Seen>(store, seenKey(id))
+  return v && typeof v === 'object' ? { ...v } : {}
+}
+
+/** The person has looked at this report at this status. */
+export function markSeen(store: Store, id: Id, reportId: string, status: string): Promise<void> {
+  return serial(seenKey(id), async () => {
+    const seen = await seenStatuses(store, id)
+    if (seen[reportId] === status) return
+    seen[reportId] = status
+    await writeCache(store, seenKey(id), seen)
+    for (const l of listeners) l()
+  })
+}
+
+/** The rows that moved to a telling status since the person last looked, in the order given. A report seen for the first
+ *  time is recorded silently (so an app taking this release does not announce every old report), and so is a move to a
+ *  quiet status (the planning steps); a telling move stays unrecorded until the person opens the report. */
+export function moved(store: Store, id: Id, rows: { id: string; status: string }[]): Promise<{ id: string; status: string }[]> {
+  return serial(seenKey(id), async () => {
+    const seen = await seenStatuses(store, id)
+    const out: { id: string; status: string }[] = []
+    let changed = false
+    for (const r of rows) {
+      if (typeof r?.id !== 'string' || typeof r.status !== 'string' || r.status === 'on-phone') continue
+      const had = seen[r.id]
+      if (had === r.status) continue
+      if (had === undefined || !TOLD.includes(r.status)) { seen[r.id] = r.status; changed = true; continue }
+      out.push({ id: r.id, status: r.status })
+    }
+    if (changed) await writeCache(store, seenKey(id), seen)
+    return out
+  })
+}
+
+/** One toast per app open, per account: a remounted entry in the same open does not say it again. */
+const toasted = new Set<string>()
+export function firstToastThisOpen(id: Id): boolean {
+  const k = seenKey(id)
+  if (toasted.has(k)) return false
+  toasted.add(k)
+  return true
+}

package/src/client/styles.css

@@ -45,6 +45,9 @@
 .sac-item { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 8px; }
 .sac-row-button { width: 100%; text-align: left; display: flex; flex-direction: column; gap: 2px; }
 .sac-row-status { font-weight: 600; }
+.sac-entry { position: relative; }
+.sac-entry-dot { position: absolute; top: 6px; right: 6px; width: 10px; height: 10px; border-radius: 50%; background: var(--sac-accent); box-shadow: 0 0 0 2px var(--sac-bg); }
+.sac-new { align-self: flex-start; font-size: 0.8rem; font-weight: 600; padding: 1px 8px; border-radius: 999px; background: var(--sac-accent); color: var(--sac-accent-fg); }
 .sac-muted { color: var(--sac-muted); font-size: 0.9rem; }
 .sac-error { color: var(--sac-danger); margin: 0; }
 .sac-receipt-line { font-weight: 600; margin: 0; }

package/src/client/words.ts

@@ -96,6 +96,12 @@ export interface Strings {
   addFailed: string
   overLimit: string
   stepLabel: string
+  /** On a row in My suggestions that moved since the person last opened it. */
+  newMark: string
+  /** Read by a screen reader on the entry when a suggestion has moved (the dot itself is decoration). */
+  entryMoved: string
+  /** The one toast per open. `words` is the status's own word (wordsFor); `note` is the not-now reason, when there is one. */
+  movedToast: (words: string, note?: string) => string
 }
 
 export const DEFAULT_STRINGS: Strings = {
@@ -179,6 +185,9 @@ export const DEFAULT_STRINGS: Strings = {
   addFailed: 'That could not be added. Try again.',
   overLimit: 'Something in this suggestion is over a limit. Remove an attachment and try again.',
   stepLabel: 'Where it is',
+  newMark: 'New',
+  entryMoved: 'One of your suggestions has news',
+  movedToast: (words, note) => (note ? `Your suggestion: ${words}. ${note}` : `Your suggestion: ${words}`),
 }
 
 export function stringsFor(words: Words): Strings {

package/src/contract.mjs

@@ -16,6 +16,8 @@ export const CEILINGS = {
 
 export const STATUSES = ["on-phone", "received", "with-freeda", "planned", "waiting-on-owner", "being-made", "live", "sent-to-template", "filed", "not-now"];
 export const END = ["live", "sent-to-template", "filed", "not-now"];
+// The moves the person who suggested a change hears about: the work starting, and every end. The planning steps stay quiet.
+export const TOLD = ["being-made", ...END];
 
 // actor: who PERFORMS this step (design section 7): sent by the person, received by the app, with Pluma by the Mac. A Helm on the owner's Mac posts straight into
 // the inbox, so a report may go from the phone to Pluma without the hosted app's "received". The owner may decline

package/src/server/handlers.ts

@@ -7,7 +7,7 @@
 // a report is decided here from the signed-in member and the explicit maintainers list, never from the
 // request. Nothing is uploaded through this server: `uploadUrl` issues a direct-to-storage link with the
 // size and type fixed, and `finalize` checks what actually landed.
-import { END, FLOW, STATUSES, isAcceptedMedia, isReportId, mayMove, validateReport } from '../contract.mjs'
+import { END, FLOW, STATUSES, TOLD, isAcceptedMedia, isReportId, mayMove, meaningFor, validateReport, wordsFor } from '../contract.mjs'
 import { effectiveLimits, type Limits } from './rate.ts'
 import { ACCEPTED_TYPES, canonicalType, sameType } from './sniff.ts'
 
@@ -82,7 +82,12 @@ export interface HostedStore {
   readUrl(a: { reportId: string; file: string; ttlMs: number }): Promise<{ url: string; expiresAt: number }>
 }
 
-export interface TellEvent { type: 'submitted' | 'followed-up' | 'status' | 'settled'; reportId: string; member?: string }
+/** `status` events also carry the report's member and its new status. */
+export interface TellEvent { type: 'submitted' | 'followed-up' | 'status' | 'settled'; reportId: string; member?: string; status?: string }
+export { TOLD }
+/** What `tellSubmitter` is handed. `words` and `meaning` are the module's own words for the status (`wordsFor`/`meaningFor`),
+ *  never the report's text, so a lock screen never shows what someone wrote. `note` is the one-line reason, on `not-now` only. */
+export interface SubmitterNews { member: string; reportId: string; status: string; words: string; meaning: string; ended: boolean; note?: string }
 export interface ReportHandlerOptions {
   store: HostedStore
   /** The signed-in member, or null. Anything but `account` is ignored: the role is decided here. */
@@ -98,6 +103,11 @@ export interface ReportHandlerOptions {
   maintainersSince?: Record<string, number | string>
   /** Told when something happens, with ids and never words. A failure here never fails the request. */
   tell?(event: TellEvent): void | Promise<void>
+  /** REQUIRED: tells the person who suggested a change that it is being made or has ended, on the app's own channel (push,
+   *  email, an activity row). Called once per telling move (`TOLD`), never on a repeat, never when the store refused the move,
+   *  and never to a maintainer about their own report being made. A failure never fails the move. An app that genuinely
+   *  has nobody to tell passes `{ none: "<reason>" }`; leaving it out throws at startup. */
+  tellSubmitter: ((news: SubmitterNews) => void | Promise<void>) | { none: string }
   now?: () => number
 }
 
@@ -177,12 +187,21 @@ function declaredFile(r: StoredReport, file: string): Declared | null {
 
 export function createReportHandlers(opts: ReportHandlerOptions) {
   const { store, identity, agent } = opts
+  const hook = opts.tellSubmitter as unknown
+  if (typeof hook !== 'function') {
+    const reason = hook && typeof hook === 'object' ? (hook as { none?: unknown }).none : undefined
+    if (hook === undefined || hook === null) throw new Error('createReportHandlers needs tellSubmitter: a function that tells the person who suggested a change when it is being made and when it ends, or { none: "<reason>" } when the app has nobody to tell')
+    if (typeof reason !== 'string' || !reason.trim()) throw new Error('tellSubmitter { none } needs a reason: say why this app tells nobody, as { none: "<reason>" }')
+  }
+  const tellSubmitter = typeof hook === 'function' ? (hook as (n: SubmitterNews) => void | Promise<void>) : null
   const maintainers = [...opts.maintainers]
   const limits = effectiveLimits(opts.limits)
   const contractCeilings = { images: limits.images, imageBytes: limits.imageBytes, videos: limits.videos, videoBytes: limits.videoBytes, videoMs: limits.videoMs, voiceMs: limits.voiceMs, voiceTotalMs: limits.voiceTotalMs, perPersonPerDay: limits.perPersonPerDay }
   const now = opts.now ?? (() => Date.now())
   const since = (m: string) => { const v = opts.maintainersSince?.[m]; const t = typeof v === 'string' ? Date.parse(v) : v; return t !== undefined && Number.isFinite(t) ? t : undefined }
   const tell = async (e: TellEvent) => { try { await opts.tell?.(e) } catch { /* telling is best effort */ } }
+  const owner = typeof opts.app?.owner === 'string' && opts.app.owner ? opts.app.owner : 'the owner'
+  const news = async (n: SubmitterNews) => { try { await tellSubmitter?.(n) } catch { /* telling is best effort */ } }
   const isMaintainer = (m: string) => maintainers.includes(m)
   const roleOf = (m: string) => (isMaintainer(m) ? 'maintainer' : 'member')
 
@@ -296,7 +315,9 @@ export function createReportHandlers(opts: ReportHandlerOptions) {
     // Filtered again here: a store that over-returns still cannot show another member's report.
     const rows = (await store.listFor(member)).filter((r) => r.who?.member === member)
     rows.sort((a, b) => (a.receivedAt < b.receivedAt ? 1 : -1))
-    return json(200, rows.map((r) => ({ id: r.id, status: lastStatus(r), kind: r.kind, at: Date.parse(r.receivedAt) })))
+    // A declined report carries its one-line reason, which the member's own view already shows; no other note is listed.
+    const reason = (r: StoredReport) => { const t = r.timeline[r.timeline.length - 1]; return t?.status === 'not-now' && t.note ? { note: t.note } : {} }
+    return json(200, rows.map((r) => ({ id: r.id, status: lastStatus(r), kind: r.kind, at: Date.parse(r.receivedAt), ...reason(r) })))
   }
 
   async function one(req: Request, id: string): Promise<Response> {
@@ -510,7 +531,13 @@ export function createReportHandlers(opts: ReportHandlerOptions) {
       if (needsApproval && from !== 'being-made' && PAST_ASKING.includes(status)) await store.claimApproval(id, by, APPROVAL_LEASE_MS)
       return json(409, { error: 'the report changed while this was sent; read it again' })
     }
-    await tell({ type: 'status', reportId: id })
+    await tell({ type: 'status', reportId: id, member: r.who?.member, status })
+    const member = r.who?.member
+    // A maintainer is not told that the work they just started on their own report has started; an end is still news.
+    const ownStart = status === 'being-made' && member === by
+    if (member && TOLD.includes(status) && !ownStart) {
+      await news({ member, reportId: id, status, words: wordsFor(status, { owner }), meaning: meaningFor(status, { owner }), ended: END.includes(status), ...(status === 'not-now' && note ? { note } : {}) })
+    }
     return json(200, { id, status })
   }
 

package/src/server/index.ts

@@ -1,6 +1,6 @@
 // "@supersuit/suggest-a-change/server": web-standard APIs only, no runtime dependency, nothing from react or the client.
-export { createReportHandlers, reportRevision, VOICE_BYTES_PER_SECOND, LEASE_MS, BODY_CAP, APPROVAL_LEASE_MS, HELD_MS, READ_TTL_MS, INCOMPLETE_GRACE_MS, VOICE_FILE_BYTES } from './handlers.ts'
-export type { HostedStore, StoredReport, TimelineEntry, FileState, FollowUp, TellEvent, ReportHandlerOptions } from './handlers.ts'
+export { createReportHandlers, reportRevision, TOLD, VOICE_BYTES_PER_SECOND, LEASE_MS, BODY_CAP, APPROVAL_LEASE_MS, HELD_MS, READ_TTL_MS, INCOMPLETE_GRACE_MS, VOICE_FILE_BYTES } from './handlers.ts'
+export type { HostedStore, StoredReport, TimelineEntry, FileState, FollowUp, TellEvent, SubmitterNews, ReportHandlerOptions } from './handlers.ts'
 export { sniffType, sameType, canonicalType, ACCEPTED_TYPES } from './sniff.ts'
 export { effectiveLimits } from './rate.ts'
 export type { Limits } from './rate.ts'