@supersuit/suggest-a-change 0.2.5 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.3.0 (2026-11-01)
+
+- **The relay transcribes voice notes.** `createSuggestionRelay({ transcribe })` takes a transcriber, `({ name, mimeType, bytes, staged? }, { signal }) => Promise<string>`, and calls it for each voice note a `file` or `follow-up` brings with no `transcript`, before the privacy catch, so the transcript is caught like the words. A report with only a voice note is now titled from the transcript's first sentence instead of "Suggestion from <app>", under "Voice note (transcribed automatically)" rather than a claim about the owner's Mac. A transcriber that fails, hears nothing, or takes longer than `transcribeTimeoutMs` (default 25 s) never stops the filing: the issue files with the recording and says in plain words why there is no transcript, never the transcriber's error. `capabilities` answers `transcribes`; `RelayCapabilities`, `ComposeOptions.transcriptBy` and `transcriptNote` are new. Earned when voice-only suggestions reached GitHub as "Not transcribed." after the receiving Mac stopped writing transcripts.
+- **My suggestions sets nothing once it is gone.** A report marked seen starts a recount; if the screen unmounted while that recount was reading the seen record, its late answer still set state, which threw `window is not defined` inside React when the page had been torn down (seen 2026-10-29 as an unhandled rejection failing the Helm's vitest run under load). Unmounting now retires every load and recount still in flight, as switching account already did.
+
 ## 0.2.5 (2026-10-26)
 
 - **A tap on the microphone records.** `DefaultField` was hold-only: on a tap the release ended the take before the microphone had answered, so nothing was recorded and nothing said to hold (seen on iPhone Safari). Now a press shorter than 350 ms starts a take that keeps recording until the next tap (or the time limit), and a longer press records until it is let go. Leaving the button, or a pointer the browser cancels (iOS Safari does when its permission prompt appears), never ends a tapped take. `startTake` is still called synchronously inside the press, with nothing awaited before it. While recording the dot turns to a stop square and pulses (under `prefers-reduced-motion: no-preference`).

package/README.md

@@ -52,7 +52,7 @@ const adapters: Adapters = {
 
 `SuggestEntry` also takes `className` and `role` (for example `role="menuitem"` when a host shows it as a menu row); no role is set by default. My suggestions and the detail view keep their last answer from the app on the phone (module-owned IndexedDB, keyed by app and account like a draft), draw it at once with a quiet "Updating" line, and replace it when the app answers; if the app cannot be reached they keep the saved rows and say so. An adapter tells a refusal from an unreachable app: `mine()` and `one()` throw an error with `refused: true` or a `status` of 401, 403 or 404 for a refusal (the saved copy is then deleted), and anything else thrown is unreachable. Saved reports the list no longer holds are pruned, and signing out clears them. A first open with nothing saved shows "Loading".
 
-The entry also keeps the phone's outbox moving while it is mounted (a report sent with the Mac away goes when it is back, with the sheet closed); a host with no always-mounted entry renders `<KeepSending adapters={adapters} />` once, high in the app. The entry carries `data-suggest-entry` (the attribute the screen check looks for; see "The check" below). Signed out, it opens nothing and says why. The receipt says "Got it" only after the adapter has answered `done` for the report and every attachment; until then it says the report is on the phone. Every text field the module renders sits in a `[data-voice-field]` container with a `[data-voice-control]`; a host's `Field` slot must keep that shape (it receives `FieldProps`, which is the Helm's voice field props). A voice note alone is a whole report: the recording is kept and uploaded as a part, and the receiving Mac writes the transcript. `DefaultField` puts its microphone inside the text box (bottom right of a text area, centred at the right of a one-line input, a 44px target, with the text kept clear of it). A tap starts a take that records until the next tap or the time limit; a press held past a tap records until it is let go; leaving the button or a pointer the browser cancels (iOS Safari's microphone prompt) never ends a tapped take. The recorder is asked inside the press with nothing awaited first, so iOS Safari counts the microphone request as part of the gesture. A host's own `Field` should follow the same two rules.
+The entry also keeps the phone's outbox moving while it is mounted (a report sent with the Mac away goes when it is back, with the sheet closed); a host with no always-mounted entry renders `<KeepSending adapters={adapters} />` once, high in the app. The entry carries `data-suggest-entry` (the attribute the screen check looks for; see "The check" below). Signed out, it opens nothing and says why. The receipt says "Got it" only after the adapter has answered `done` for the report and every attachment; until then it says the report is on the phone. Every text field the module renders sits in a `[data-voice-field]` container with a `[data-voice-control]`; a host's `Field` slot must keep that shape (it receives `FieldProps`, which is the Helm's voice field props). A voice note alone is a whole report: the recording is kept and uploaded as a part, and whoever receives it writes the transcript (a relay given `transcribe`, see below, or the owner's Mac). `DefaultField` puts its microphone inside the text box (bottom right of a text area, centred at the right of a one-line input, a 44px target, with the text kept clear of it). A tap starts a take that records until the next tap or the time limit; a press held past a tap records until it is let go; leaving the button or a pointer the browser cancels (iOS Safari's microphone prompt) never ends a tapped take. The recorder is asked inside the press with nothing awaited first, so iOS Safari counts the microphone request as part of the gesture. A host's own `Field` should follow the same two rules.
 
 Styling: structure only, class names prefixed `sac-`. `@supersuit/suggest-a-change/styles.css` is optional defaults (16px inputs so iOS does not zoom, 44px touch targets, safe-area padding on the sheet). Re-skin it with these custom properties:
 
@@ -385,6 +385,7 @@ await relay.status([{ repo: "acme/notes", number: got.number }]); // [{ repo, nu
 
 - **`file`** `{ repo, app?, report, transcript?, files: [{ name, type, bytes (base64) } | { name, type, staged: name }], redacted? }` answers `{ number, url }`. The relay checks the report against the contract and each file against what the report declares, runs the privacy catch itself, saves the files to `suggestion-attachments`, then opens the issue **as the App**, filed by the name `identity()` gives (never the account id, and never a name in the request), with the role and the contact from `identity()` too and the app's name and `app:<label>` from the relay's `apps` table by the request's `app` id (an id not in the table is 400 "unknown app"; with no table no request names an app, and the issue says "in an app" with no app label); the contact only when the report carries `who.contact` (the person left it ticked). At most ten labels. A credential refuses with 422 naming the kind and the field, never the text, whatever `redacted` says. Any other hit refuses with 409 `{ held: true, hits: [{ kind, field }] }` until the filer sends again with `redacted: true`, saying they chose to file without the flagged part; the relay then redacts what it found itself, so raw text is never filed on the filer's word. The catch reads every string that would reach the issue (where, every diagnostic, the context, the trail, the names, the handle), after folding look-alike letters and removing invisible characters. A repeat of the same report answers the same issue; another identity using that report id is 409.
 - **`follow-up`** `{ repo, number, reportId, words, transcript?, files?, redacted? }` adds a comment, only for the identity that filed that report through this relay (anyone else, 403). The same privacy catch runs.
+- **Transcribing voice notes.** Pass `transcribe: async ({ name, mimeType, bytes, staged? }, { signal }) => string` and the relay writes the transcript of every voice note a `file` or `follow-up` brings with no `transcript` (a staged note's bytes are already read; `staged` is its key, for a host that would rather sign a read link). It runs before the privacy catch, so the transcript is caught and redacted like the words; the issue's heading says "Voice note (transcribed automatically)", and a report with no words takes its title from the transcript's first sentence instead of "Suggestion from <app>". All of a request's notes are transcribed at once within `transcribeTimeoutMs` (default `TRANSCRIBE_TIMEOUT_MS`, 25 s, inside a 60 s serverless limit); `signal` aborts when the relay stops waiting. A transcriber that throws, returns nothing, or is too slow never stops the filing: the issue files with the recording and one plain sentence of why (`TRANSCRIPT_MISSING`: the service did not answer in time, failed or refused the recording, or heard no speech), never the transcriber's own error text. A transcript the request carries is used as it is. `capabilities` answers `transcribes: true` when the relay has a transcriber, which is what a host sets the sheet's `Destination.transcribes` from, so the list promises a transcript only when one will be made.
 - **`status`** `{ items: [{ repo, number }] }` answers `{ items: [{ repo, number, status, reason? }] }`, only for issues this identity filed (anything else, 403).
 - **`attach`** is for a filer who opened the issue themselves but cannot push. Reading the issue is the proof they could file there: it must exist, be an issue, be open or closed within a week, and END with the composer's own `## Filed by` line for that report ("Report <id>" anywhere else proves nothing). And a report belongs to the first identity that files or attaches for it: anyone else attaching to it is 403. An issue the relay filed takes files only from the identity that filed it; an issue someone opened themselves takes them only when its author's login is the `githubLogin` that `identity()` vouches for, and nothing is claimed until that proof holds. A request lists each file once and no more of each kind than a report may carry; a follow-up is composed and measured before any file is written, and holds to the report's caps like `attach`.
 

package/dist/client/adapters.d.ts

@@ -42,7 +42,7 @@ export interface FieldProps {
     placeholder?: string;
     multiline?: boolean;
     type?: 'text' | 'search';
-    /** Gets each finished take. The sheet keeps the recording; transcription is the receiving Mac's job. */
+    /** Gets each finished take. The sheet keeps the recording; the transcript is written where it is received (a relay with `transcribe`, or the owner's Mac). */
     upload?: HeardUpload;
     onHeard?(h: {
         audio: string;

package/dist/client/default-field.js

@@ -4,7 +4,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // INSIDE the box (bottom right; centred at the right of a one-line input), in one [data-voice-field]
 // container with nothing else typeable in it. A take is
 // recorded with the module's recorder (written to the phone's database as it is made). Transcription is
-// not done here: the take goes to `upload`, and the receiving Mac writes the transcript. A voice note
+// not done here: the take goes to `upload`, and whoever receives it (a relay with `transcribe`, or the owner's Mac) writes the transcript. A voice note
 // alone is a whole report, so a field with no words and one take is a complete answer.
 //
 // A tap starts a take that keeps recording until the next tap (or the time limit); a press held longer

package/dist/client/mine.js

@@ -31,6 +31,8 @@ export function MySuggestions({ adapters, onOpen }) {
     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); setFresh(new Set()); }, [rt]);
+    // Leaving the screen retires every load and recount still running, as a new account does: none may set state after.
+    useEffect(() => () => { loads.current++; }, []);
     const recount = useCallback(async () => {
         if (!rt || !known.current)
             return;

package/dist/client/sheet.js

@@ -203,7 +203,7 @@ export function SuggestSheet({ adapters, where, onClose, initial }) {
         await chain.current;
         return (await saveDraft(rt.store, key, {})).reportId;
     }, [rt, key]);
-    // A finished take: kept as a copy under this report, and listed. Transcription is the Mac's job.
+    // A finished take: kept as a copy under this report, and listed. The transcript is written where it is received.
     const keepTake = useCallback(async (fieldId, original, blob, ms) => {
         if (!rt || !key)
             return { refused: S.loading };

package/dist/github/compose.d.ts

@@ -46,7 +46,8 @@ export interface Destination {
     account: string;
     /** False when files cannot reach this repo yet (no App installed and the filer cannot push): they wait. */
     attaches: boolean;
-    /** False when nobody transcribes voice notes (an app's own server): the list does not promise a transcript. */
+    /** False when nobody transcribes voice notes (no relay `transcribe` and no Mac that writes one; a relay says which in
+     *  its `capabilities`): the list does not promise a transcript. */
     transcribes?: boolean;
     /** The largest file this destination takes; a larger one is named in the list as staying on the phone. */
     maxInlineBytes?: number;
@@ -104,8 +105,12 @@ export interface ComposeOptions {
     filerRole?: string;
     /** file name -> its link, from an AttachmentHost. A file with no link yet is written as still being added. */
     attachmentUrls?: Record<string, string>;
-    /** The voice notes' transcript, made on the owner's Mac. */
+    /** The voice notes' transcript. */
     transcript?: string;
+    /** Who made it: 'relay' when the relay transcribed it as it filed; otherwise it came with the request (the owner's Mac). */
+    transcriptBy?: 'relay' | 'mac';
+    /** A plain sentence saying a transcript, or part of one, could not be made and why; written under the voice note. */
+    transcriptNote?: string;
     /** The first body, written before any file is saved: every attachment is "being added". */
     pending?: boolean;
 }

package/dist/github/compose.js

@@ -192,6 +192,7 @@ export function composeIssue(report, opts = {}) {
     };
     const words = scrub(text(report.words).trim());
     const transcript = scrub(text(opts.transcript).trim());
+    const note = inline(text(opts.transcriptNote).trim());
     // Only links the host produced, and only plain https ones, become images or links; anything else is still "being added".
     const urls = opts.pending ? {} : Object.fromEntries(Object.entries(opts.attachmentUrls ?? {}).flatMap(([k, u]) => (safeUrl(u) ? [[k, u]] : [])));
     const media = report.media ?? [];
@@ -217,7 +218,9 @@ export function composeIssue(report, opts = {}) {
         if (has.has('words'))
             out.push('## What they said', fence(said), '');
         if (has.has('voice')) {
-            out.push(transcript ? "## Voice note (transcribed on the owner's Mac)" : '## Voice note', heard ? fence(heard) : 'Not transcribed.');
+            out.push(transcript ? (opts.transcriptBy === 'relay' ? '## Voice note (transcribed automatically)' : "## Voice note (transcribed on the owner's Mac)") : '## Voice note', heard ? fence(heard) : (note || 'Not transcribed.'));
+            if (heard && note)
+                out.push('', note);
             const links = voice.filter((v) => urls[v.file]).map((v) => `[${inline(v.file)}](${urls[v.file]})`);
             if (links.length)
                 out.push('', ...links);

package/dist/github/filer.d.ts

@@ -51,11 +51,14 @@ export interface RelayFiler {
 }
 /** Files larger than this go to the relay staged (one signed PUT each) rather than inside the request. */
 export declare const STAGE_OVER_BYTES: number;
+/** `transcribes`: the relay writes a voice note's transcript itself (a host passed `transcribe`); set the sheet's
+ *  `Destination.transcribes` from it. */
 export interface RelayCapabilities {
     actions: string[];
     staging: boolean;
     inlineBytes: number;
     maxBytes?: Record<string, number>;
+    transcribes?: boolean;
 }
 /** `url` is where the relay is mounted; each action is posted to `<url>/<action>`. */
 export declare function relayFiler({ url, headers, fetch }: {

package/dist/github/index.d.ts

@@ -6,7 +6,7 @@ export { fileIssue, updateIssue, addFollowUp, issueStates, issueStatus, fileSugg
 export type { GitHubConfig, FilingConfig, IssueState, FileSuggestionInput, FiledSuggestion, Fetch } from './api.ts';
 export { branchHost, relayHost, toBase64, attachmentUrl, ATTACHMENTS_BRANCH, CONTENTS_API_BYTES } from './hosts.ts';
 export type { AttachmentHost, AttachmentTarget, AttachmentFile } from './hosts.ts';
-export { createSuggestionRelay, createAttachRelay, memoryUsage, RELAY_LIMITS, RELAY_VOICE_BYTES, FILING_LEASE_MS } from './relay.ts';
-export type { SuggestionRelayOptions, AttachRelayOptions, RelayLimits, RelayUsage, RelayIdentity, Reservation, FiledRecord, StagingAdapter } from './relay.ts';
+export { createSuggestionRelay, createAttachRelay, memoryUsage, RELAY_LIMITS, RELAY_VOICE_BYTES, FILING_LEASE_MS, TRANSCRIBE_TIMEOUT_MS, TRANSCRIPT_MISSING } from './relay.ts';
+export type { SuggestionRelayOptions, AttachRelayOptions, RelayLimits, RelayUsage, RelayIdentity, Reservation, FiledRecord, StagingAdapter, RelayVoice, RelayTranscriber } from './relay.ts';
 export { relayFiler, canFileDirectly, STAGE_OVER_BYTES } from './filer.ts';
 export type { RelayFiler, RelayFiling, RelayFile, RelayCapabilities } from './filer.ts';

package/dist/github/index.js

@@ -5,5 +5,5 @@ export { privacyCatch, redact, mayFileAsIs, normalize } from './privacy.js';
 export { composeIssue, whatGoes, destinationWords, pieces, BODY_LIMIT, filedByLine, endsWithFiledBy, FILED_BY } from './compose.js';
 export { fileIssue, updateIssue, addFollowUp, issueStates, issueStatus, fileSuggestion, attachPending, github, GitHubError } from './api.js';
 export { branchHost, relayHost, toBase64, attachmentUrl, ATTACHMENTS_BRANCH, CONTENTS_API_BYTES } from './hosts.js';
-export { createSuggestionRelay, createAttachRelay, memoryUsage, RELAY_LIMITS, RELAY_VOICE_BYTES, FILING_LEASE_MS } from './relay.js';
+export { createSuggestionRelay, createAttachRelay, memoryUsage, RELAY_LIMITS, RELAY_VOICE_BYTES, FILING_LEASE_MS, TRANSCRIBE_TIMEOUT_MS, TRANSCRIPT_MISSING } from './relay.js';
 export { relayFiler, canFileDirectly, STAGE_OVER_BYTES } from './filer.js';

package/dist/github/relay.d.ts

@@ -97,6 +97,28 @@ export interface RelayIdentity {
         handle?: string;
     };
 }
+/** One voice recording handed to the host's transcriber: its file name, its type as audio, and its bytes (read from
+ *  staging already when it was staged; `staged` is then its staging key, for a host that would rather sign a read link). */
+export interface RelayVoice {
+    name: string;
+    mimeType: string;
+    bytes: Uint8Array;
+    staged?: string;
+}
+/** Answers the words said in one recording. `signal` aborts when the relay stops waiting. */
+export type RelayTranscriber = (voice: RelayVoice, o: {
+    signal: AbortSignal;
+}) => Promise<string>;
+/** How long the relay waits for all of a request's transcripts before it files without them. Serverless hosts cap a
+ *  request (Vercel's default is 60 s), so this leaves room for GitHub. */
+export declare const TRANSCRIBE_TIMEOUT_MS = 25000;
+/** The plain words an issue uses for why a transcript is missing. Never the transcriber's own error, which can carry
+ *  anything (a key, a URL, a provider's internals). */
+export declare const TRANSCRIPT_MISSING: {
+    readonly timeout: 'the transcription service did not answer in time';
+    readonly failed: 'the transcription service failed or refused the recording';
+    readonly silent: 'no speech was heard in the recording';
+};
 export interface SuggestionRelayOptions {
     /** The GitHub App the relay acts as: its numeric id and its private key (PEM, PKCS#1 as GitHub issues it, or PKCS#8). */
     app: {
@@ -125,6 +147,11 @@ export interface SuggestionRelayOptions {
     staging?: StagingAdapter;
     /** May lower any limit, never raise one. */
     limits?: Partial<RelayLimits>;
+    /** Writes the transcript of each voice note a `file` or `follow-up` brings with no `transcript`. Without it the issue
+     *  says the note was not transcribed, and `capabilities` says `transcribes: false`. */
+    transcribe?: RelayTranscriber;
+    /** Default TRANSCRIBE_TIMEOUT_MS; all of a request's notes are transcribed at once inside it. */
+    transcribeTimeoutMs?: number;
     usage?: RelayUsage;
     fetch?: Fetch;
     now?: () => number;

package/dist/github/relay.js

@@ -9,6 +9,9 @@
 // - attach: for a filer who opened the issue themselves but cannot push; the relay proves they could file there by
 //   reading the issue and requiring it to carry the report.
 //
+// With `transcribe`, the relay also writes the transcript of each voice note a request brings without one, before the
+// privacy catch, so the transcript is caught like the words. A transcriber that fails or is slow never stops a filing.
+//
 // Web-standard only: Request, Response, fetch, crypto.subtle.
 import { CEILINGS, isRepoName, isReportId, validContact, validateReport } from '../contract.mjs';
 import { cappedText, json } from '../server/http.js';
@@ -92,6 +95,16 @@ export function memoryUsage({ now = () => Date.now() } = {}) {
         async filer(repo, num) { return issues.get(`${repo}#${num}`) ?? null; },
     };
 }
+/** How long the relay waits for all of a request's transcripts before it files without them. Serverless hosts cap a
+ *  request (Vercel's default is 60 s), so this leaves room for GitHub. */
+export const TRANSCRIBE_TIMEOUT_MS = 25_000;
+/** The plain words an issue uses for why a transcript is missing. Never the transcriber's own error, which can carry
+ *  anything (a key, a URL, a provider's internals). */
+export const TRANSCRIPT_MISSING = {
+    timeout: 'the transcription service did not answer in time',
+    failed: 'the transcription service failed or refused the recording',
+    silent: 'no speech was heard in the recording',
+};
 /** How long a filing holds its report before another try may take it over (its process is presumed dead). */
 export const FILING_LEASE_MS = 5 * 60_000;
 const FILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
@@ -282,6 +295,32 @@ export function createSuggestionRelay(opts, only) {
             return json(413, { error: `that file is larger than the ${max} bytes allowed` });
         return { name: x.name, type: real, kind, bytes, ...(stagedKey ? { stagedKey } : {}) };
     }
+    /** The transcript for a request's voice notes: the request's own when it carries one, else the relay's (with a plain
+     *  note for any note it could not transcribe), else none. Never throws. */
+    async function transcriptFor(files, given) {
+        if (typeof given === 'string' && given.trim())
+            return { transcript: given };
+        const voices = files.filter((f) => f.kind === 'voice');
+        if (!opts.transcribe || !voices.length)
+            return {};
+        const ms = opts.transcribeTimeoutMs ?? TRANSCRIBE_TIMEOUT_MS;
+        const stop = new AbortController();
+        let timer;
+        const late = new Promise((res) => { timer = setTimeout(() => { stop.abort(); res('late'); }, ms); });
+        const one = (v) => Promise.resolve()
+            .then(() => opts.transcribe({ name: v.name, mimeType: v.type.replace(/^video\//, 'audio/'), bytes: v.bytes, ...(v.stagedKey ? { staged: v.stagedKey } : {}) }, { signal: stop.signal }))
+            .then((t) => (typeof t === 'string' && t.trim() ? { text: t.trim() } : { fail: TRANSCRIPT_MISSING.silent }), () => ({ fail: TRANSCRIPT_MISSING.failed }));
+        const got = await Promise.race([Promise.all(voices.map(one)), late]);
+        clearTimeout(timer);
+        const results = got === 'late' ? voices.map(() => ({ fail: TRANSCRIPT_MISSING.timeout })) : got;
+        const many = voices.length > 1;
+        const texts = results.flatMap((r, i) => ('text' in r ? [many ? `(${voices[i].name})\n${r.text}` : r.text] : []));
+        const fails = results.flatMap((r, i) => ('fail' in r ? [many ? `${voices[i].name}: ${r.fail}` : r.fail] : []));
+        const note = fails.length
+            ? `The transcript${many ? ` of ${fails.length === voices.length ? 'the recordings' : `${fails.length} of ${voices.length} recordings`}` : ''} could not be made: ${fails.join('; ')}.${texts.length ? '' : ` The recording${many ? 's are' : ' is'} attached.`}`
+            : undefined;
+        return { ...(texts.length ? { transcript: texts.join('\n\n'), by: 'relay' } : {}), ...(note ? { note } : {}) };
+    }
     /** The bytes a request still has to hold today: inline files only, since upload-url held a staged file's up front. */
     const inlineBytesOf = (files) => files.reduce((n, f) => n + (f.stagedKey ? 0 : f.bytes.length), 0);
     const discardStaged = async (files) => {
@@ -381,12 +420,14 @@ export function createSuggestionRelay(opts, only) {
         if (appId !== undefined && opts.apps && (typeof appId !== 'string' || !Object.prototype.hasOwnProperty.call(opts.apps, appId)))
             return bad('unknown app');
         const app = opts.apps && typeof appId === 'string' ? opts.apps[appId] : undefined;
+        // The transcript is made before the catch reads anything, so it is caught like the words.
+        const heard = await transcriptFor(files, body.transcript);
         // Who it is from comes from the host, never the request: the name, the role and the contact.
         const contact = contactFor(me, report.who?.contact);
         const appVersion = typeof report.diagnostics?.appVersion === 'string' ? report.diagnostics.appVersion : undefined;
         const readable = {
             words: report.words, followUps: report.followUps, where: report.where, diagnostics: report.diagnostics,
-            context: report.context, transcript: typeof body.transcript === 'string' ? body.transcript : undefined,
+            context: report.context, transcript: heard.transcript,
             filerName: me.name, appName: app?.name, who: { contact },
             files: files.map((f) => ({ name: f.name })),
         };
@@ -438,6 +479,8 @@ export function createSuggestionRelay(opts, only) {
                 filerName: typeof clean.filerName === 'string' && clean.filerName.trim() ? clean.filerName.trim().slice(0, 100) : 'Someone',
                 filerRole: role,
                 transcript: clean.transcript,
+                ...(heard.by && clean.transcript ? { transcriptBy: heard.by } : {}),
+                ...(heard.note ? { transcriptNote: heard.note } : {}),
                 attachmentUrls,
             });
             const made = await fileIssue({ repo, token, fetch: opts.fetch, api: opts.api }, issue);
@@ -488,7 +531,8 @@ export function createSuggestionRelay(opts, only) {
         if (checked instanceof Response)
             return checked;
         const files = checked;
-        const readable = { words: typeof body.words === 'string' ? body.words.slice(0, 20_000) : '', transcript: typeof body.transcript === 'string' ? body.transcript : undefined, files: files.map((f) => ({ name: f.name })) };
+        const heard = await transcriptFor(files, body.transcript);
+        const readable = { words: typeof body.words === 'string' ? body.words.slice(0, 20_000) : '', transcript: heard.transcript, files: files.map((f) => ({ name: f.name })) };
         const caught = catchIt(readable, account, body.redacted === true);
         if ('res' in caught)
             return caught.res;
@@ -500,7 +544,7 @@ export function createSuggestionRelay(opts, only) {
         const links = files.map((f) => { const url = attachmentUrl(repo, ATTACHMENTS_BRANCH, `${folder}/${f.name}`); return f.kind === 'image' ? `![${f.name}](${url})` : `[${f.name}](${url})`; });
         // A follow-up is the person's own words, so it sits in a fence like the words of the report.
         const fenced = (s) => { const run = Math.max(0, ...[...s.matchAll(/`+/g)].map((m) => m[0].length)); const f = '`'.repeat(Math.max(3, run + 1)); return `${f}\n${s}\n${f}`; };
-        const text = ['## Added later', words.trim() ? fenced(words.trim()) : '', transcript ? `\n### Voice note\n${fenced(transcript.trim())}` : '', links.length ? `\n${links.join('\n')}` : ''].filter(Boolean).join('\n');
+        const text = ['## Added later', words.trim() ? fenced(words.trim()) : '', transcript ? `\n### Voice note\n${fenced(transcript.trim())}` : '', heard.note ? `\n${heard.note}` : '', links.length ? `\n${links.join('\n')}` : ''].filter(Boolean).join('\n');
         if (text.length > BODY_LIMIT)
             return json(413, { error: `that follow-up is longer than GitHub takes in a comment (${BODY_LIMIT} characters)` });
         const held = await reserve(account, reportId, inlineBytesOf(files));
@@ -707,6 +751,7 @@ export function createSuggestionRelay(opts, only) {
     const capabilities = () => json(200, {
         actions: ACTIONS.filter((a) => (only ? a === only : a !== 'upload-url' || Boolean(opts.staging))),
         staging: Boolean(opts.staging),
+        transcribes: Boolean(opts.transcribe),
         inlineBytes: limits.inlineBytes,
         maxBytes: { image: limits.imageBytes, video: limits.videoBytes, voice: limits.voiceBytes },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/suggest-a-change",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "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/adapters.ts

@@ -33,7 +33,7 @@ export interface FieldProps {
   placeholder?: string
   multiline?: boolean
   type?: 'text' | 'search'
-  /** Gets each finished take. The sheet keeps the recording; transcription is the receiving Mac's job. */
+  /** Gets each finished take. The sheet keeps the recording; the transcript is written where it is received (a relay with `transcribe`, or the owner's Mac). */
   upload?: HeardUpload
   onHeard?(h: { audio: string; text: string }): void
   onKept?(t: { key: string; ms: number }): void

package/src/client/default-field.tsx

@@ -3,7 +3,7 @@
 // INSIDE the box (bottom right; centred at the right of a one-line input), in one [data-voice-field]
 // container with nothing else typeable in it. A take is
 // recorded with the module's recorder (written to the phone's database as it is made). Transcription is
-// not done here: the take goes to `upload`, and the receiving Mac writes the transcript. A voice note
+// not done here: the take goes to `upload`, and whoever receives it (a relay with `transcribe`, or the owner's Mac) writes the transcript. A voice note
 // alone is a whole report, so a field with no words and one take is a complete answer.
 //
 // A tap starts a take that keeps recording until the next tap (or the time limit); a press held longer

package/src/client/mine.tsx

@@ -36,6 +36,8 @@ export function MySuggestions({ adapters, onOpen }: { adapters: Adapters; onOpen
   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); setFresh(new Set()) }, [rt])
+  // Leaving the screen retires every load and recount still running, as a new account does: none may set state after.
+  useEffect(() => () => { loads.current++ }, [])
 
   const recount = useCallback(async () => {
     if (!rt || !known.current) return

package/src/client/sheet.tsx

@@ -198,7 +198,7 @@ export function SuggestSheet({ adapters, where, onClose, initial }: { adapters:
     return (await saveDraft(rt!.store, key!, {})).reportId
   }, [rt, key])
 
-  // A finished take: kept as a copy under this report, and listed. Transcription is the Mac's job.
+  // A finished take: kept as a copy under this report, and listed. The transcript is written where it is received.
   const keepTake = useCallback(async (fieldId: string, original: string, blob: Blob, ms: number) => {
     if (!rt || !key) return { refused: S.loading }
     if (ms > ceilings.voiceMs) return { refused: S.voiceTooLong }

package/src/github/compose.ts

@@ -24,7 +24,8 @@ export interface Destination {
   account: string
   /** False when files cannot reach this repo yet (no App installed and the filer cannot push): they wait. */
   attaches: boolean
-  /** False when nobody transcribes voice notes (an app's own server): the list does not promise a transcript. */
+  /** False when nobody transcribes voice notes (no relay `transcribe` and no Mac that writes one; a relay says which in
+   *  its `capabilities`): the list does not promise a transcript. */
   transcribes?: boolean
   /** The largest file this destination takes; a larger one is named in the list as staying on the phone. */
   maxInlineBytes?: number
@@ -61,8 +62,12 @@ export interface ComposeOptions {
   filerRole?: string
   /** file name -> its link, from an AttachmentHost. A file with no link yet is written as still being added. */
   attachmentUrls?: Record<string, string>
-  /** The voice notes' transcript, made on the owner's Mac. */
+  /** The voice notes' transcript. */
   transcript?: string
+  /** Who made it: 'relay' when the relay transcribed it as it filed; otherwise it came with the request (the owner's Mac). */
+  transcriptBy?: 'relay' | 'mac'
+  /** A plain sentence saying a transcript, or part of one, could not be made and why; written under the voice note. */
+  transcriptNote?: string
   /** The first body, written before any file is saved: every attachment is "being added". */
   pending?: boolean
 }
@@ -247,6 +252,7 @@ export function composeIssue(report: Draft, opts: ComposeOptions = {}): Composed
   }
   const words = scrub(text(report.words).trim())
   const transcript = scrub(text(opts.transcript).trim())
+  const note = inline(text(opts.transcriptNote).trim())
   // Only links the host produced, and only plain https ones, become images or links; anything else is still "being added".
   const urls: Record<string, string> = opts.pending ? {} : Object.fromEntries(Object.entries(opts.attachmentUrls ?? {}).flatMap(([k, u]) => (safeUrl(u) ? [[k, u]] : [])))
   const media = report.media ?? []
@@ -274,7 +280,8 @@ export function composeIssue(report: Draft, opts: ComposeOptions = {}): Composed
     const out: string[] = []
     if (has.has('words')) out.push('## What they said', fence(said), '')
     if (has.has('voice')) {
-      out.push(transcript ? "## Voice note (transcribed on the owner's Mac)" : '## Voice note', heard ? fence(heard) : 'Not transcribed.')
+      out.push(transcript ? (opts.transcriptBy === 'relay' ? '## Voice note (transcribed automatically)' : "## Voice note (transcribed on the owner's Mac)") : '## Voice note', heard ? fence(heard) : (note || 'Not transcribed.'))
+      if (heard && note) out.push('', note)
       const links = voice.filter((v) => urls[v.file]).map((v) => `[${inline(v.file)}](${urls[v.file]})`)
       if (links.length) out.push('', ...links)
       if (coming && !has.has('images') && !has.has('video')) out.push('', coming)

package/src/github/filer.ts

@@ -38,7 +38,9 @@ const raw = (b: RelayFile['bytes']): Uint8Array => {
   if (b instanceof ArrayBuffer) return new Uint8Array(b)
   const bin = atob(b); const out = new Uint8Array(bin.length); for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i); return out
 }
-export interface RelayCapabilities { actions: string[]; staging: boolean; inlineBytes: number; maxBytes?: Record<string, number> }
+/** `transcribes`: the relay writes a voice note's transcript itself (a host passed `transcribe`); set the sheet's
+ *  `Destination.transcribes` from it. */
+export interface RelayCapabilities { actions: string[]; staging: boolean; inlineBytes: number; maxBytes?: Record<string, number>; transcribes?: boolean }
 
 /** `url` is where the relay is mounted; each action is posted to `<url>/<action>`. */
 export function relayFiler({ url, headers = {}, fetch }: { url: string; headers?: Record<string, string>; fetch?: Fetch }): RelayFiler {

package/src/github/index.ts

@@ -9,7 +9,7 @@ export { fileIssue, updateIssue, addFollowUp, issueStates, issueStatus, fileSugg
 export type { GitHubConfig, FilingConfig, IssueState, FileSuggestionInput, FiledSuggestion, Fetch } from './api.ts'
 export { branchHost, relayHost, toBase64, attachmentUrl, ATTACHMENTS_BRANCH, CONTENTS_API_BYTES } from './hosts.ts'
 export type { AttachmentHost, AttachmentTarget, AttachmentFile } from './hosts.ts'
-export { createSuggestionRelay, createAttachRelay, memoryUsage, RELAY_LIMITS, RELAY_VOICE_BYTES, FILING_LEASE_MS } from './relay.ts'
-export type { SuggestionRelayOptions, AttachRelayOptions, RelayLimits, RelayUsage, RelayIdentity, Reservation, FiledRecord, StagingAdapter } from './relay.ts'
+export { createSuggestionRelay, createAttachRelay, memoryUsage, RELAY_LIMITS, RELAY_VOICE_BYTES, FILING_LEASE_MS, TRANSCRIBE_TIMEOUT_MS, TRANSCRIPT_MISSING } from './relay.ts'
+export type { SuggestionRelayOptions, AttachRelayOptions, RelayLimits, RelayUsage, RelayIdentity, Reservation, FiledRecord, StagingAdapter, RelayVoice, RelayTranscriber } from './relay.ts'
 export { relayFiler, canFileDirectly, STAGE_OVER_BYTES } from './filer.ts'
 export type { RelayFiler, RelayFiling, RelayFile, RelayCapabilities } from './filer.ts'

package/src/github/relay.ts

@@ -9,6 +9,9 @@
 // - attach: for a filer who opened the issue themselves but cannot push; the relay proves they could file there by
 //   reading the issue and requiring it to carry the report.
 //
+// With `transcribe`, the relay also writes the transcript of each voice note a request brings without one, before the
+// privacy catch, so the transcript is caught like the words. A transcriber that fails or is slow never stops a filing.
+//
 // Web-standard only: Request, Response, fetch, crypto.subtle.
 import { CEILINGS, isRepoName, isReportId, validContact, validateReport } from '../contract.mjs'
 import { cappedText, json } from '../server/http.ts'
@@ -145,6 +148,22 @@ export interface RelayIdentity {
   contact?: { email?: string; phone?: string; handle?: string }
 }
 
+/** One voice recording handed to the host's transcriber: its file name, its type as audio, and its bytes (read from
+ *  staging already when it was staged; `staged` is then its staging key, for a host that would rather sign a read link). */
+export interface RelayVoice { name: string; mimeType: string; bytes: Uint8Array; staged?: string }
+/** Answers the words said in one recording. `signal` aborts when the relay stops waiting. */
+export type RelayTranscriber = (voice: RelayVoice, o: { signal: AbortSignal }) => Promise<string>
+/** How long the relay waits for all of a request's transcripts before it files without them. Serverless hosts cap a
+ *  request (Vercel's default is 60 s), so this leaves room for GitHub. */
+export const TRANSCRIBE_TIMEOUT_MS = 25_000
+/** The plain words an issue uses for why a transcript is missing. Never the transcriber's own error, which can carry
+ *  anything (a key, a URL, a provider's internals). */
+export const TRANSCRIPT_MISSING = {
+  timeout: 'the transcription service did not answer in time',
+  failed: 'the transcription service failed or refused the recording',
+  silent: 'no speech was heard in the recording',
+} as const
+
 export interface SuggestionRelayOptions {
   /** The GitHub App the relay acts as: its numeric id and its private key (PEM, PKCS#1 as GitHub issues it, or PKCS#8). */
   app: { id: number | string; privateKey: string }
@@ -164,6 +183,11 @@ export interface SuggestionRelayOptions {
   staging?: StagingAdapter
   /** May lower any limit, never raise one. */
   limits?: Partial<RelayLimits>
+  /** Writes the transcript of each voice note a `file` or `follow-up` brings with no `transcript`. Without it the issue
+   *  says the note was not transcribed, and `capabilities` says `transcribes: false`. */
+  transcribe?: RelayTranscriber
+  /** Default TRANSCRIBE_TIMEOUT_MS; all of a request's notes are transcribed at once inside it. */
+  transcribeTimeoutMs?: number
   usage?: RelayUsage
   fetch?: Fetch
   now?: () => number
@@ -335,6 +359,30 @@ export function createSuggestionRelay(opts: SuggestionRelayOptions, only?: Actio
     if (bytes.length > max) return json(413, { error: `that file is larger than the ${max} bytes allowed` })
     return { name: x.name, type: real, kind, bytes, ...(stagedKey ? { stagedKey } : {}) }
   }
+  /** The transcript for a request's voice notes: the request's own when it carries one, else the relay's (with a plain
+   *  note for any note it could not transcribe), else none. Never throws. */
+  async function transcriptFor(files: Checked[], given: unknown): Promise<{ transcript?: string; by?: 'relay'; note?: string }> {
+    if (typeof given === 'string' && given.trim()) return { transcript: given }
+    const voices = files.filter((f) => f.kind === 'voice')
+    if (!opts.transcribe || !voices.length) return {}
+    const ms = opts.transcribeTimeoutMs ?? TRANSCRIBE_TIMEOUT_MS
+    const stop = new AbortController()
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const late = new Promise<'late'>((res) => { timer = setTimeout(() => { stop.abort(); res('late') }, ms) })
+    const one = (v: Checked) => Promise.resolve()
+      .then(() => opts.transcribe!({ name: v.name, mimeType: v.type.replace(/^video\//, 'audio/'), bytes: v.bytes, ...(v.stagedKey ? { staged: v.stagedKey } : {}) }, { signal: stop.signal }))
+      .then((t) => (typeof t === 'string' && t.trim() ? { text: t.trim() } : { fail: TRANSCRIPT_MISSING.silent }), () => ({ fail: TRANSCRIPT_MISSING.failed }))
+    const got = await Promise.race([Promise.all(voices.map(one)), late])
+    clearTimeout(timer)
+    const results: ({ text: string } | { fail: string })[] = got === 'late' ? voices.map(() => ({ fail: TRANSCRIPT_MISSING.timeout })) : got
+    const many = voices.length > 1
+    const texts = results.flatMap((r, i) => ('text' in r ? [many ? `(${voices[i].name})\n${r.text}` : r.text] : []))
+    const fails = results.flatMap((r, i) => ('fail' in r ? [many ? `${voices[i].name}: ${r.fail}` : r.fail] : []))
+    const note = fails.length
+      ? `The transcript${many ? ` of ${fails.length === voices.length ? 'the recordings' : `${fails.length} of ${voices.length} recordings`}` : ''} could not be made: ${fails.join('; ')}.${texts.length ? '' : ` The recording${many ? 's are' : ' is'} attached.`}`
+      : undefined
+    return { ...(texts.length ? { transcript: texts.join('\n\n'), by: 'relay' as const } : {}), ...(note ? { note } : {}) }
+  }
   /** The bytes a request still has to hold today: inline files only, since upload-url held a staged file's up front. */
   const inlineBytesOf = (files: Checked[]) => files.reduce((n, f) => n + (f.stagedKey ? 0 : f.bytes.length), 0)
   const discardStaged = async (files: Checked[]) => {
@@ -409,12 +457,14 @@ export function createSuggestionRelay(opts: SuggestionRelayOptions, only?: Actio
     const appId = body.app
     if (appId !== undefined && opts.apps && (typeof appId !== 'string' || !Object.prototype.hasOwnProperty.call(opts.apps, appId))) return bad('unknown app')
     const app = opts.apps && typeof appId === 'string' ? opts.apps[appId] : undefined
+    // The transcript is made before the catch reads anything, so it is caught like the words.
+    const heard = await transcriptFor(files, body.transcript)
     // Who it is from comes from the host, never the request: the name, the role and the contact.
     const contact = contactFor(me, (report.who as { contact?: unknown } | undefined)?.contact)
     const appVersion = typeof (report.diagnostics as { appVersion?: unknown } | undefined)?.appVersion === 'string' ? (report.diagnostics as { appVersion: string }).appVersion : undefined
     const readable = {
       words: report.words, followUps: report.followUps, where: report.where, diagnostics: report.diagnostics,
-      context: report.context, transcript: typeof body.transcript === 'string' ? body.transcript : undefined,
+      context: report.context, transcript: heard.transcript,
       filerName: me.name, appName: app?.name, who: { contact },
       files: files.map((f) => ({ name: f.name })),
     }
@@ -450,6 +500,8 @@ export function createSuggestionRelay(opts: SuggestionRelayOptions, only?: Actio
         filerName: typeof clean.filerName === 'string' && clean.filerName.trim() ? clean.filerName.trim().slice(0, 100) : 'Someone',
         filerRole: role,
         transcript: clean.transcript,
+        ...(heard.by && clean.transcript ? { transcriptBy: heard.by } : {}),
+        ...(heard.note ? { transcriptNote: heard.note } : {}),
         attachmentUrls,
       })
       const made = await fileIssue({ repo, token, fetch: opts.fetch, api: opts.api }, issue)
@@ -477,7 +529,8 @@ export function createSuggestionRelay(opts: SuggestionRelayOptions, only?: Actio
     const checked = await checkMany(Array.isArray(body.files) ? body.files : [], () => undefined, account, reportId)
     if (checked instanceof Response) return checked
     const files = checked
-    const readable = { words: typeof body.words === 'string' ? body.words.slice(0, 20_000) : '', transcript: typeof body.transcript === 'string' ? body.transcript : undefined, files: files.map((f) => ({ name: f.name })) }
+    const heard = await transcriptFor(files, body.transcript)
+    const readable = { words: typeof body.words === 'string' ? body.words.slice(0, 20_000) : '', transcript: heard.transcript, files: files.map((f) => ({ name: f.name })) }
     const caught = catchIt(readable, account, body.redacted === true); if ('res' in caught) return caught.res
     const { words, transcript } = caught.clean
     if (!words.trim() && !transcript && !files.length) return bad('a follow-up needs words or a file')
@@ -486,7 +539,7 @@ export function createSuggestionRelay(opts: SuggestionRelayOptions, only?: Actio
     const links = files.map((f) => { const url = attachmentUrl(repo, ATTACHMENTS_BRANCH, `${folder}/${f.name}`); return f.kind === 'image' ? `![${f.name}](${url})` : `[${f.name}](${url})` })
     // A follow-up is the person's own words, so it sits in a fence like the words of the report.
     const fenced = (s: string) => { const run = Math.max(0, ...[...s.matchAll(/`+/g)].map((m) => m[0].length)); const f = '`'.repeat(Math.max(3, run + 1)); return `${f}\n${s}\n${f}` }
-    const text = ['## Added later', words.trim() ? fenced(words.trim()) : '', transcript ? `\n### Voice note\n${fenced(transcript.trim())}` : '', links.length ? `\n${links.join('\n')}` : ''].filter(Boolean).join('\n')
+    const text = ['## Added later', words.trim() ? fenced(words.trim()) : '', transcript ? `\n### Voice note\n${fenced(transcript.trim())}` : '', heard.note ? `\n${heard.note}` : '', links.length ? `\n${links.join('\n')}` : ''].filter(Boolean).join('\n')
     if (text.length > BODY_LIMIT) return json(413, { error: `that follow-up is longer than GitHub takes in a comment (${BODY_LIMIT} characters)` })
     const held = await reserve(account, reportId, inlineBytesOf(files))
     if (held instanceof Response) return held
@@ -613,6 +666,7 @@ export function createSuggestionRelay(opts: SuggestionRelayOptions, only?: Actio
   const capabilities = () => json(200, {
     actions: ACTIONS.filter((a) => (only ? a === only : a !== 'upload-url' || Boolean(opts.staging))),
     staging: Boolean(opts.staging),
+    transcribes: Boolean(opts.transcribe),
     inlineBytes: limits.inlineBytes,
     maxBytes: { image: limits.imageBytes, video: limits.videoBytes, voice: limits.voiceBytes },
   })