@supersuit/suggest-a-change 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.9 (2026-10-17)
+
+- **The door helpers are exported from `./server`.** `json`, `signIn`, `notFound`, `cappedText` and `peek` are what an app's own route wrapper needs to answer as the handlers do and never read a body past a cap. Two apps (cofounders-template, first-years-template) carried byte-identical copies; they now import these. The handlers use the same functions, so there is one copy of the door. No behaviour change.
+
+## 0.1.8 (2026-10-17)
+
+- **The news reaches a person whose entry sits in a menu.** In the Cofounders and Us apps the entry lives in a three-dot menu that stays closed and remounts it on every open, so the 0.1.7 dot was never seen and the toast was drawn inside the closed menu. New in `./client`: `<SuggestNews adapters>`, mounted once at the root, shows the toast with no entry on screen (and keeps the outbox moving); `useSuggestNews(adapters)` returns `{ moved }` for the menu's trigger; `<SuggestDot adapters moved>` draws the entry's dot there (nothing at 0), and the class `sac-dot-host` gives the trigger the `position: relative` it needs. The toast is once per page load and account however many times the entry mounts, whichever of these asks first. `<SuggestEntry>` keeps its own dot and, alone, behaves as in 0.1.7.
+
 ## 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`.

package/README.md

@@ -73,7 +73,31 @@ 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).
+**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 page load 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).
+
+**When the entry sits in a menu.** A host that shows the entry inside a menu that stays closed (a three-dot menu, often remounting its rows on every open) would never show the dot, and the toast would be drawn inside the closed menu. Mount `<SuggestNews>` once at the app's root, always mounted: it asks `mine()` when it mounts, shows the page load's one toast with no entry on screen, and keeps the outbox moving. Put the dot on the menu's own trigger with `useSuggestNews(adapters)`, which returns `{ moved }`, and `<SuggestDot>`, which draws the entry's dot (nothing when `moved` is 0). The trigger needs `position: relative`; the class `sac-dot-host` does it. The toast is once per page load and account however many times the entry mounts, whichever of these asks first. The entry in the menu keeps its own dot.
+
+```tsx
+import { SuggestDot, SuggestEntry, SuggestNews, useSuggestNews } from "@supersuit/suggest-a-change/client";
+
+// once, at the root
+<SuggestNews adapters={adapters} />
+
+// the menu's trigger
+function MoreButton({ onClick }: { onClick(): void }) {
+  const { moved } = useSuggestNews(adapters);
+  return (
+    <button type="button" className="sac-dot-host" aria-label="More" onClick={onClick}>
+      ...<SuggestDot adapters={adapters} moved={moved} />
+    </button>
+  );
+}
+
+// inside the menu, as before
+<SuggestEntry adapters={adapters} role="menuitem" onOpen={() => setOpen(true)} />
+```
+
+`<SuggestNews>` also takes `children`, a function given `{ moved }`, for a root that draws the trigger itself. A host using only the hook renders `<Toasts />` somewhere always mounted so the toast has a place to show.
 
 **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`.
 
@@ -188,6 +212,8 @@ A client adapter's `uploadPart` asks `upload-url`, PUTs the bytes straight to st
 
 The role stored on a report comes from the signed-in member and the `maintainers` list. A `who` sent by the phone is ignored; a report carrying `timeline`, `status`, `plan` or `decision` is refused. `sniffType(firstBytes)` names a file by its bytes (jpeg, png, webp, heic/heif, gif, mp4/mov, webm, m4a/aac, mp3, wav, ogg/opus; anything else is `null`) and `finalize` refuses a file whose bytes are not the type it was declared as.
 
+**A wrapper of your own answers in the module's words.** When an app's route has to check a caller or read one field before the handler runs, it uses the same door the handlers use: `json(status, body)` (JSON, never cached), `signIn()` (401) and `notFound()` (404), `cappedText(req, cap)` (the body as text, or a 413 `Response` past `cap` bytes, by the declared length and again by counting what arrives; no body reads as `""`), and `peek(text)` (a JSON object, or `{}` for anything else, for reading one field while the module judges the body). Copying these into an app made a second door that could drift from the first.
+
 **Settle carries a revision.** `agentList` gives each report a `revision`; the Mac sends it back with `settle`, and the store settles only if the report still has exactly that content. A follow-up or file that arrived in between answers 409 `stale`, drops the claim, and the next list offers the report with the addition. Adapters compute the same value with `reportRevision`.
 
 **The collector MUST verify.** `agentFile` answers the verified `bytes` and `sha256`; a Mac that downloads the link must check both before it trusts the file.

package/dist/client/entry.d.ts

@@ -1,10 +1,33 @@
-import { type AriaRole } from 'react';
+import { type AriaRole, type ReactNode } from 'react';
 import type { Adapters } from './adapters.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. */
 export declare function KeepSending({ adapters }: {
     adapters: Adapters;
 }): null;
+/** For a host that shows the entry where it is not always visible (inside a menu): call this where the menu's trigger is
+ *  drawn. It asks the app once per mount and returns how many of this person's suggestions moved since they last opened
+ *  them (draw `<SuggestDot>` with it). The page load's one toast is shown by whichever of this, `<SuggestNews>` or the
+ *  entry asks first; a host using only this hook must also render `<Toasts />` somewhere always mounted. */
+export declare function useSuggestNews(adapters: Adapters): {
+    moved: number;
+};
+/** Mount once at the app's root, always mounted: shows the page load's one toast when a suggestion moved, with no entry
+ *  on screen, and keeps the outbox moving (as `<KeepSending>` does). `children`, if given, receives `{ moved }`. */
+export declare function SuggestNews({ adapters, children }: {
+    adapters: Adapters;
+    children?: (news: {
+        moved: number;
+    }) => ReactNode;
+}): import("react").JSX.Element;
+/** The entry's dot, for a host's own trigger (the three-dot button of a menu the entry sits in). Draws nothing when
+ *  `moved` is 0. It is positioned like the entry's dot, so the trigger needs `position: relative` (the class
+ *  `sac-dot-host` in the module's styles does it). */
+export declare function SuggestDot({ adapters, moved: count, className }: {
+    adapters: Adapters;
+    moved: number;
+    className?: string;
+}): import("react").JSX.Element | null;
 export declare function SuggestEntry({ adapters, onOpen, className, role }: {
     adapters: Adapters;
     onOpen(): void;

package/dist/client/entry.js

@@ -16,18 +16,14 @@ export function KeepSending({ adapters }) {
     useRuntime(adapters);
     return null;
 }
-export function SuggestEntry({ adapters, onOpen, className, role }) {
+// THE NEWS: once per mount, asks the app for this person's reports and compares each with what they last opened. A move
+// since then is counted (the dot), and the newest one gets the page load's one toast, whichever of the entry or a
+// root-mounted SuggestNews asks first (the guard is per page load and account, in seen.ts). Opening a report anywhere
+// recounts. `toasted` says this mount showed the toast, so a standalone entry knows to draw a toast host for it.
+function useNews(adapters, rt) {
     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.
+    const [toasted, setToasted] = useState(false);
     useEffect(() => {
         setNews(0);
         if (!rt)
@@ -65,13 +61,47 @@ export function SuggestEntry({ adapters, onOpen, className, role }) {
             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);
+            setToasted(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]);
+    return { moved: news, toasted };
+}
+/** For a host that shows the entry where it is not always visible (inside a menu): call this where the menu's trigger is
+ *  drawn. It asks the app once per mount and returns how many of this person's suggestions moved since they last opened
+ *  them (draw `<SuggestDot>` with it). The page load's one toast is shown by whichever of this, `<SuggestNews>` or the
+ *  entry asks first; a host using only this hook must also render `<Toasts />` somewhere always mounted. */
+export function useSuggestNews(adapters) {
+    const { rt } = useRuntime(adapters);
+    return { moved: useNews(adapters, rt).moved };
+}
+/** Mount once at the app's root, always mounted: shows the page load's one toast when a suggestion moved, with no entry
+ *  on screen, and keeps the outbox moving (as `<KeepSending>` does). `children`, if given, receives `{ moved }`. */
+export function SuggestNews({ adapters, children }) {
+    const news = useSuggestNews(adapters);
+    return _jsxs(_Fragment, { children: [_jsx(Toasts, {}), children ? children(news) : null] });
+}
+/** The entry's dot, for a host's own trigger (the three-dot button of a menu the entry sits in). Draws nothing when
+ *  `moved` is 0. It is positioned like the entry's dot, so the trigger needs `position: relative` (the class
+ *  `sac-dot-host` in the module's styles does it). */
+export function SuggestDot({ adapters, moved: count, className }) {
+    const S = stringsFor(adapters.words);
+    if (!count)
+        return null;
+    return _jsxs(_Fragment, { children: [_jsx("span", { className: `sac-entry-dot${className ? ` ${className}` : ''}`, "data-sac-moved": "", "aria-hidden": "true" }), _jsx("span", { className: "sac-sr", children: S.entryMoved })] });
+}
+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 { moved: news, toasted: toasting } = useNews(adapters, rt);
+    useEffect(() => { setWhy(''); }, [adapters]);
+    useClearOnSignOut(rt, who, adapters.words.app);
     async function press() {
         setBusy(true);
         let who = null;
@@ -89,7 +119,7 @@ export function SuggestEntry({ adapters, onOpen, className, role }) {
         setWhy('');
         onOpen();
     }
-    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] }));
+    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, _jsx(SuggestDot, { adapters: adapters, moved: news })] }), 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/seen.js

@@ -60,7 +60,8 @@ export function moved(store, id, rows) {
         return out;
     });
 }
-/** One toast per app open, per account: a remounted entry in the same open does not say it again. */
+/** One toast per page load, per account, whoever asks: a remounted entry (a menu that remounts it on every open) or a
+ *  root-mounted SuggestNews beside it never says it again until the page is loaded again. */
 const toasted = new Set();
 export function firstToastThisOpen(id) {
     const k = seenKey(id);

package/dist/server/handlers.js

@@ -10,6 +10,7 @@
 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';
+import { json, notFound, signIn, cappedText } from './http.js';
 /** What a collector saw of a report: its verified files and its follow-ups. A store computes this from its own copy,
  *  inside `settle`, and settles only when it equals what the collector says it collected. */
 export function reportRevision(r) {
@@ -35,40 +36,17 @@ export const INCOMPLETE_GRACE_MS = 60 * 60_000;
 const FILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
 const FOLLOW = /^[A-Za-z0-9_-]{1,64}$/;
 const FORBIDDEN = ['timeline', 'status', 'plan', 'decision', 'files', 'receivedAt', 'followUps', 'claimedBy', 'settledBy'];
-const json = (status, body) => new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } });
-const notFound = () => json(404, { error: 'not found' });
-const signIn = () => json(401, { error: 'sign in first' });
 const bad = (error) => json(400, { error });
 const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 /** Reads a JSON object body, refusing past `BODY_CAP` by the header and again by counting what arrives. */
 async function readBody(req, cap = BODY_CAP, optional = false) {
-    const declared = Number(req.headers.get('content-length'));
-    if (Number.isFinite(declared) && declared > cap)
-        return { res: json(413, { error: 'too large' }) };
-    if (!req.body)
+    if (!req.body && !(Number(req.headers.get('content-length')) > cap))
         return optional ? { body: {} } : { res: bad('a JSON body is needed') };
-    const reader = req.body.getReader();
-    const chunks = [];
-    let n = 0;
-    for (;;) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        n += value.byteLength;
-        if (n > cap) {
-            await reader.cancel().catch(() => { });
-            return { res: json(413, { error: 'too large' }) };
-        }
-        chunks.push(value);
-    }
-    const all = new Uint8Array(n);
-    let o = 0;
-    for (const c of chunks) {
-        all.set(c, o);
-        o += c.byteLength;
-    }
+    const text = await cappedText(req, cap);
+    if (typeof text !== 'string')
+        return { res: text };
     try {
-        const v = JSON.parse(new TextDecoder().decode(all));
+        const v = JSON.parse(text);
         return isObj(v) ? { body: v } : optional ? { body: {} } : { res: bad('a JSON object is needed') };
     }
     catch {

package/dist/server/http.d.ts

@@ -0,0 +1,10 @@
+/** A JSON response that is never cached. */
+export declare const json: (status: number, body: unknown) => Response;
+/** 401, the module's answer to a caller it does not know. */
+export declare const signIn: () => Response;
+/** 404, the module's answer to a report that is gone or not the caller's (the two are never told apart). */
+export declare const notFound: () => Response;
+/** The body as text, or a 413 once it passes `cap` bytes: by its declared length, and again by counting what arrives. A request with no body reads as ''. */
+export declare function cappedText(req: Request, cap: number): Promise<string | Response>;
+/** A JSON object out of text, or an empty one: the module judges the body itself; a wrapper only peeks at a field. */
+export declare function peek(text: string): Record<string, unknown>;

package/dist/server/http.js

@@ -0,0 +1,49 @@
+// The door, in the module's own words: the answers the handlers give for "who are you" and "no such report", a body
+// read that stops at a cap, and a peek at one field. Exported so an app's own route wrapper (one that has to check a
+// caller, or read a field, before the module sees the request) answers exactly as the module does and never reads a
+// body past the cap. Web-standard APIs only.
+/** A JSON response that is never cached. */
+export const json = (status, body) => new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } });
+/** 401, the module's answer to a caller it does not know. */
+export const signIn = () => json(401, { error: 'sign in first' });
+/** 404, the module's answer to a report that is gone or not the caller's (the two are never told apart). */
+export const notFound = () => json(404, { error: 'not found' });
+/** The body as text, or a 413 once it passes `cap` bytes: by its declared length, and again by counting what arrives. A request with no body reads as ''. */
+export async function cappedText(req, cap) {
+    const declared = Number(req.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > cap)
+        return json(413, { error: 'too large' });
+    if (!req.body)
+        return '';
+    const reader = req.body.getReader();
+    const chunks = [];
+    let n = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        n += value.byteLength;
+        if (n > cap) {
+            await reader.cancel().catch(() => { });
+            return json(413, { error: 'too large' });
+        }
+        chunks.push(value);
+    }
+    const all = new Uint8Array(n);
+    let o = 0;
+    for (const c of chunks) {
+        all.set(c, o);
+        o += c.byteLength;
+    }
+    return new TextDecoder().decode(all);
+}
+/** A JSON object out of text, or an empty one: the module judges the body itself; a wrapper only peeks at a field. */
+export function peek(text) {
+    try {
+        const v = JSON.parse(text);
+        return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/server/index.d.ts

@@ -1,5 +1,6 @@
 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 { json, signIn, notFound, cappedText, peek } from './http.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,6 @@
 // "@supersuit/suggest-a-change/server": web-standard APIs only, no runtime dependency, nothing from react or the client.
 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 { json, signIn, notFound, cappedText, peek } from './http.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.7",
+  "version": "0.1.9",
   "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/client/entry.tsx

@@ -2,9 +2,9 @@
 // THE ENTRY: one control, `data-suggest-entry`, which is the contract the screen checker looks for.
 // Signed out, it opens nothing and says why. Signed in, it hands over to the host (`onOpen`), which
 // shows the sheet. `<ReportProblem>` is the same control for an error screen, already filled in.
-import { useEffect, useState, type AriaRole } from 'react'
+import { useEffect, useState, type AriaRole, type ReactNode } from 'react'
 import type { Adapters } from './adapters.ts'
-import { useRuntime } from './runtime.ts'
+import { useRuntime, type Runtime } from './runtime.ts'
 import { firstToastThisOpen, moved, onSeen } from './seen.ts'
 import { SuggestSheet } from './sheet.tsx'
 import { toast, Toasts } from './toast.tsx'
@@ -18,18 +18,14 @@ export function KeepSending({ adapters }: { adapters: Adapters }) {
   return null
 }
 
-export function SuggestEntry({ adapters, onOpen, className, role }: { adapters: Adapters; onOpen(): void; className?: string; /** An ARIA role for the button (for example `menuitem` when the host shows it as a menu row). Unset by default. */ role?: AriaRole }) {
+// THE NEWS: once per mount, asks the app for this person's reports and compares each with what they last opened. A move
+// since then is counted (the dot), and the newest one gets the page load's one toast, whichever of the entry or a
+// root-mounted SuggestNews asks first (the guard is per page load and account, in seen.ts). Opening a report anywhere
+// recounts. `toasted` says this mount showed the toast, so a standalone entry knows to draw a toast host for it.
+function useNews(adapters: Adapters, rt: Runtime | null): { moved: number; toasted: boolean } {
   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.
+  const [toasted, setToasted] = useState(false)
   useEffect(() => {
     setNews(0)
     if (!rt) return
@@ -52,13 +48,50 @@ export function SuggestEntry({ adapters, onOpen, className, role }: { adapters:
       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)
+      setToasted(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])
+  return { moved: news, toasted }
+}
+
+/** For a host that shows the entry where it is not always visible (inside a menu): call this where the menu's trigger is
+ *  drawn. It asks the app once per mount and returns how many of this person's suggestions moved since they last opened
+ *  them (draw `<SuggestDot>` with it). The page load's one toast is shown by whichever of this, `<SuggestNews>` or the
+ *  entry asks first; a host using only this hook must also render `<Toasts />` somewhere always mounted. */
+export function useSuggestNews(adapters: Adapters): { moved: number } {
+  const { rt } = useRuntime(adapters)
+  return { moved: useNews(adapters, rt).moved }
+}
+
+/** Mount once at the app's root, always mounted: shows the page load's one toast when a suggestion moved, with no entry
+ *  on screen, and keeps the outbox moving (as `<KeepSending>` does). `children`, if given, receives `{ moved }`. */
+export function SuggestNews({ adapters, children }: { adapters: Adapters; children?: (news: { moved: number }) => ReactNode }) {
+  const news = useSuggestNews(adapters)
+  return <><Toasts />{children ? children(news) : null}</>
+}
+
+/** The entry's dot, for a host's own trigger (the three-dot button of a menu the entry sits in). Draws nothing when
+ *  `moved` is 0. It is positioned like the entry's dot, so the trigger needs `position: relative` (the class
+ *  `sac-dot-host` in the module's styles does it). */
+export function SuggestDot({ adapters, moved: count, className }: { adapters: Adapters; moved: number; className?: string }) {
+  const S = stringsFor(adapters.words)
+  if (!count) return null
+  return <><span className={`sac-entry-dot${className ? ` ${className}` : ''}`} data-sac-moved="" aria-hidden="true" /><span className="sac-sr">{S.entryMoved}</span></>
+}
+
+export function SuggestEntry({ adapters, onOpen, className, role }: { adapters: Adapters; onOpen(): void; className?: string; /** An ARIA role for the button (for example `menuitem` when the host shows it as a menu row). Unset by default. */ role?: AriaRole }) {
+  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 { moved: news, toasted: toasting } = useNews(adapters, rt)
+  useEffect(() => { setWhy('') }, [adapters])
+  useClearOnSignOut(rt, who, adapters.words.app)
   async function press() {
     setBusy(true)
     let who = null
@@ -72,7 +105,7 @@ export function SuggestEntry({ adapters, onOpen, className, role }: { adapters:
     <span className="sac-entry-wrap">
       <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}
+        <SuggestDot adapters={adapters} moved={news} />
       </button>
       {why ? <span role="status" className="sac-entry-why">{why}</span> : null}
       {toasting ? <Toasts /> : null}

package/src/client/seen.ts

@@ -61,7 +61,8 @@ export function moved(store: Store, id: Id, rows: { id: string; status: string }
   })
 }
 
-/** One toast per app open, per account: a remounted entry in the same open does not say it again. */
+/** One toast per page load, per account, whoever asks: a remounted entry (a menu that remounts it on every open) or a
+ *  root-mounted SuggestNews beside it never says it again until the page is loaded again. */
 const toasted = new Set<string>()
 export function firstToastThisOpen(id: Id): boolean {
   const k = seenKey(id)

package/src/client/styles.css

@@ -45,7 +45,7 @@
 .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, .sac-dot-host { 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; }

package/src/server/handlers.ts

@@ -10,6 +10,7 @@
 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'
+import { json, notFound, signIn, cappedText } from './http.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. */
@@ -129,34 +130,17 @@ const FILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/
 const FOLLOW = /^[A-Za-z0-9_-]{1,64}$/
 const FORBIDDEN = ['timeline', 'status', 'plan', 'decision', 'files', 'receivedAt', 'followUps', 'claimedBy', 'settledBy']
 
-const json = (status: number, body: unknown): Response =>
-  new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } })
-const notFound = () => json(404, { error: 'not found' })
-const signIn = () => json(401, { error: 'sign in first' })
 const bad = (error: string) => json(400, { error })
 const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
 
 type Body = { body: Record<string, unknown> } | { res: Response }
 /** Reads a JSON object body, refusing past `BODY_CAP` by the header and again by counting what arrives. */
 async function readBody(req: Request, cap = BODY_CAP, optional = false): Promise<Body> {
-  const declared = Number(req.headers.get('content-length'))
-  if (Number.isFinite(declared) && declared > cap) return { res: json(413, { error: 'too large' }) }
-  if (!req.body) return optional ? { body: {} } : { res: bad('a JSON body is needed') }
-  const reader = req.body.getReader()
-  const chunks: Uint8Array[] = []
-  let n = 0
-  for (;;) {
-    const { done, value } = await reader.read()
-    if (done) break
-    n += value.byteLength
-    if (n > cap) { await reader.cancel().catch(() => {}); return { res: json(413, { error: 'too large' }) } }
-    chunks.push(value)
-  }
-  const all = new Uint8Array(n)
-  let o = 0
-  for (const c of chunks) { all.set(c, o); o += c.byteLength }
+  if (!req.body && !(Number(req.headers.get('content-length')) > cap)) return optional ? { body: {} } : { res: bad('a JSON body is needed') }
+  const text = await cappedText(req, cap)
+  if (typeof text !== 'string') return { res: text }
   try {
-    const v = JSON.parse(new TextDecoder().decode(all))
+    const v = JSON.parse(text)
     return isObj(v) ? { body: v } : optional ? { body: {} } : { res: bad('a JSON object is needed') }
   } catch { return optional ? { body: {} } : { res: bad('the body is not JSON') } }
 }

package/src/server/http.ts

@@ -0,0 +1,38 @@
+// The door, in the module's own words: the answers the handlers give for "who are you" and "no such report", a body
+// read that stops at a cap, and a peek at one field. Exported so an app's own route wrapper (one that has to check a
+// caller, or read a field, before the module sees the request) answers exactly as the module does and never reads a
+// body past the cap. Web-standard APIs only.
+
+/** A JSON response that is never cached. */
+export const json = (status: number, body: unknown): Response =>
+  new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } })
+/** 401, the module's answer to a caller it does not know. */
+export const signIn = (): Response => json(401, { error: 'sign in first' })
+/** 404, the module's answer to a report that is gone or not the caller's (the two are never told apart). */
+export const notFound = (): Response => json(404, { error: 'not found' })
+
+/** The body as text, or a 413 once it passes `cap` bytes: by its declared length, and again by counting what arrives. A request with no body reads as ''. */
+export async function cappedText(req: Request, cap: number): Promise<string | Response> {
+  const declared = Number(req.headers.get('content-length'))
+  if (Number.isFinite(declared) && declared > cap) return json(413, { error: 'too large' })
+  if (!req.body) return ''
+  const reader = req.body.getReader()
+  const chunks: Uint8Array[] = []
+  let n = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    n += value.byteLength
+    if (n > cap) { await reader.cancel().catch(() => {}); return json(413, { error: 'too large' }) }
+    chunks.push(value)
+  }
+  const all = new Uint8Array(n)
+  let o = 0
+  for (const c of chunks) { all.set(c, o); o += c.byteLength }
+  return new TextDecoder().decode(all)
+}
+
+/** A JSON object out of text, or an empty one: the module judges the body itself; a wrapper only peeks at a field. */
+export function peek(text: string): Record<string, unknown> {
+  try { const v = JSON.parse(text) as unknown; return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {} } catch { return {} }
+}

package/src/server/index.ts

@@ -1,6 +1,7 @@
 // "@supersuit/suggest-a-change/server": web-standard APIs only, no runtime dependency, nothing from react or the client.
 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 { json, signIn, notFound, cappedText, peek } from './http.ts'
 export { sniffType, sameType, canonicalType, ACCEPTED_TYPES } from './sniff.ts'
 export { effectiveLimits } from './rate.ts'
 export type { Limits } from './rate.ts'