@supersuit/suggest-a-change 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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`).
+- **The microphone sits inside its text box.** Bottom right of a text area, centred at the right of a one-line input, a 44px target, with the box's padding keeping text clear of it (`.sac-voice-box`, `.sac-voice-multi`, `.sac-voice-single`). The `[data-voice-field]` / `[data-voice-control]` contract is unchanged.
+- **Words.** `holdToTalk` now defaults to "Tap to talk", `stopTalking` to "Tap to stop", and the placeholders say "tap the microphone and say it". The keys keep their names.
+
 ## 0.2.4 (2026-10-26)
 
 - **The list of what a suggestion carries is folded by default.** With a destination, the sheet above Send says one line, "Files an issue on <repo> (private)" or, in `--sac-danger` and never folded, "(public: anyone can read it)", then a toggle "What it carries (N)" counting what will go (the always rows plus each ticked one). Tapping it opens the full list with its tick boxes, reasons and account line; unticking inside still leaves an item out and lowers the count. Without a destination the tick boxes fold under the one line as "Also shared (N)". The toggle is a `<button aria-expanded aria-controls>` with a 44px target (`.sac-fold`); the app's `destinationNote` stays visible outside the fold. New replaceable words: `filesOn`, `privateShort`, `publicShort`, `carriesToggle`, `alsoSharedToggle`, `carriesLead`. `destinationWords` is unchanged. Earned by the operator's read of the open list on a phone: "it's a little bit disturbing with all the checkboxes shown."

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.
+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

@@ -1,17 +1,25 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-// THE MODULE'S OWN VOICE FIELD, for hosted apps that have no golden one. A text area with a hold-to-talk
-// button beside it, in one [data-voice-field] container with nothing else typeable in it. A take is
+// THE MODULE'S OWN VOICE FIELD, for hosted apps that have no golden one. A text area with its microphone
+// 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.
 //
-// Holding the button records; letting go (or leaving it) stops. For anyone who cannot hold, Space or
-// Enter on the focused button starts a take and again stops it.
+// A tap starts a take that keeps recording until the next tap (or the time limit); a press held longer
+// than a tap records until it is let go, as hold-to-talk always did. Leaving the button, or a pointer the
+// browser cancels (iOS Safari does when its microphone prompt appears), never ends a tapped take. The
+// recorder is asked synchronously inside the press, with nothing awaited first, so iOS Safari treats the
+// microphone request as part of the gesture. Space or Enter on the focused button starts and stops a take.
+// (The operator, 2026-10-26: a tap on the hold-only button did nothing, because the release ended the take
+// before the microphone had answered.)
 import { useEffect, useRef, useState } from 'react';
 import { startTake as defaultStartTake } from './recorder.js';
 import { toast } from './toast.js';
 import { DEFAULT_STRINGS } from './words.js';
+/** A press shorter than this is a tap: it starts a take that a second tap stops. */
+const TAP_MS = 350;
 export function DefaultField(props) {
     const { rt, id, label, value, onChange, placeholder, multiline = false, type = 'text', upload, onHeard, onKept, onHearing, disabled, startTake = defaultStartTake, maxMs, labels, scope } = props;
     const L = labels ?? DEFAULT_STRINGS;
@@ -21,6 +29,8 @@ export function DefaultField(props) {
     const take = useRef(null);
     const wanted = useRef(false);
     const timer = useRef(null);
+    // The press in progress that started a take: when it began. Null between presses, and for a press that stopped one.
+    const press = useRef(null);
     const latest = useRef(value);
     latest.current = value;
     const cb = useRef({ onChange, upload, onHeard, onKept, onHearing });
@@ -85,8 +95,32 @@ export function DefaultField(props) {
     }
     useEffect(() => () => { wanted.current = false; if (timer.current)
         clearTimeout(timer.current); void take.current?.cancel(); }, []);
-    const control = (_jsx("button", { type: "button", "data-voice-control": "", className: "sac-record", "aria-pressed": recording, "aria-label": canRecord ? `${recording ? L.stopTalking : L.holdToTalk}: ${label}` : `${L.voiceUnavailable}: ${label}`, disabled: disabled || !canRecord, onPointerDown: (e) => { e.preventDefault(); void begin(); }, onPointerUp: () => void end(), onPointerLeave: () => { if (wanted.current)
-            void end(); }, onPointerCancel: () => void end(), onContextMenu: (e) => e.preventDefault(), onKeyDown: (e) => {
+    const control = (_jsx("button", { type: "button", "data-voice-control": "", className: "sac-record", "aria-pressed": recording, "aria-label": canRecord ? `${recording ? L.stopTalking : L.holdToTalk}: ${label}` : `${L.voiceUnavailable}: ${label}`, disabled: disabled || !canRecord, onPointerDown: (e) => {
+            e.preventDefault();
+            // A take already going (a tapped one): this press stops it.
+            if (take.current || wanted.current) {
+                press.current = null;
+                void end();
+                return;
+            }
+            press.current = Date.now();
+            void begin(); // startTake is called before begin's first await: still inside the gesture
+        }, onPointerUp: () => {
+            const at = press.current;
+            press.current = null;
+            // A tap keeps recording until the next tap; a hold stops on release.
+            if (at !== null && Date.now() - at >= TAP_MS)
+                void end();
+        }, onPointerLeave: () => {
+            // Sliding off a held press stops it, as hold-to-talk did; a tapped take, or one still starting, goes on.
+            const at = press.current;
+            press.current = null;
+            if (at !== null && take.current && Date.now() - at >= TAP_MS)
+                void end();
+        }, onPointerCancel: () => {
+            // The browser took the pointer (a permission prompt, a scroll): the take carries on as a tapped one.
+            press.current = null;
+        }, onContextMenu: (e) => e.preventDefault(), onKeyDown: (e) => {
             if (e.key !== ' ' && e.key !== 'Enter')
                 return;
             e.preventDefault();
@@ -95,5 +129,5 @@ export function DefaultField(props) {
             void (take.current || wanted.current ? end() : begin());
         }, children: _jsx("span", { "aria-hidden": "true", className: "sac-record-dot" }) }));
     const shared = { id: `sac-field-${id}`, value, placeholder, disabled, className: 'sac-input', onChange: (e) => onChange(e.target.value) };
-    return (_jsxs("div", { "data-voice-field": "", className: "sac-voice", "data-recording": recording ? '' : undefined, children: [control, _jsx("label", { htmlFor: `sac-field-${id}`, className: "sac-sr", children: label }), multiline ? _jsx("textarea", { rows: 3, ...shared }) : _jsx("input", { type: type, ...shared })] }));
+    return (_jsxs("div", { "data-voice-field": "", className: "sac-voice", "data-recording": recording ? '' : undefined, children: [_jsx("label", { htmlFor: `sac-field-${id}`, className: "sac-sr", children: label }), _jsxs("div", { className: `sac-voice-box ${multiline ? 'sac-voice-multi' : 'sac-voice-single'}`, children: [multiline ? _jsx("textarea", { rows: 3, ...shared }) : _jsx("input", { type: type, ...shared }), control] })] }));
 }

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/client/words.d.ts

@@ -57,6 +57,7 @@ export interface Strings {
     mineTitle: string;
     mineEmpty: string;
     back: string;
+    /** The microphone's name while idle. The key keeps its old name; a tap starts it, and holding works too. */
     holdToTalk: string;
     stopTalking: string;
     micDenied: string;

package/dist/client/words.js

@@ -20,9 +20,9 @@ export const DEFAULT_STRINGS = {
     optional: 'optional',
     sayItLegend: 'Say it',
     sayItLabel: 'Your suggestion',
-    sayItPlaceholder: 'What would you change? Type it, or hold the microphone and say it',
-    sayItPlaceholderBroken: 'What happened, what you expected, and how to make it happen again. Type it, or hold the microphone and say it',
-    sayItPlaceholderFeedback: 'Whatever is on your mind. Type it, or hold the microphone and say it',
+    sayItPlaceholder: 'What would you change? Type it, or tap the microphone and say it',
+    sayItPlaceholderBroken: 'What happened, what you expected, and how to make it happen again. Type it, or tap the microphone and say it',
+    sayItPlaceholderFeedback: 'Whatever is on your mind. Type it, or tap the microphone and say it',
     showItLegend: 'Show it',
     addImages: 'Add a screenshot or photo',
     addVideo: 'Add a short video',
@@ -51,8 +51,8 @@ export const DEFAULT_STRINGS = {
     mineTitle: 'My suggestions',
     mineEmpty: 'You have not sent a suggestion yet.',
     back: 'Back',
-    holdToTalk: 'Hold to talk',
-    stopTalking: 'Stop and keep the recording',
+    holdToTalk: 'Tap to talk',
+    stopTalking: 'Tap to stop',
     micDenied: 'The microphone could not be used. You can type it instead.',
     voiceUnavailable: 'Voice notes cannot be added here',
     loading: '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.4",
+  "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

@@ -1,12 +1,18 @@
 'use client'
-// THE MODULE'S OWN VOICE FIELD, for hosted apps that have no golden one. A text area with a hold-to-talk
-// button beside it, in one [data-voice-field] container with nothing else typeable in it. A take is
+// THE MODULE'S OWN VOICE FIELD, for hosted apps that have no golden one. A text area with its microphone
+// 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.
 //
-// Holding the button records; letting go (or leaving it) stops. For anyone who cannot hold, Space or
-// Enter on the focused button starts a take and again stops it.
+// A tap starts a take that keeps recording until the next tap (or the time limit); a press held longer
+// than a tap records until it is let go, as hold-to-talk always did. Leaving the button, or a pointer the
+// browser cancels (iOS Safari does when its microphone prompt appears), never ends a tapped take. The
+// recorder is asked synchronously inside the press, with nothing awaited first, so iOS Safari treats the
+// microphone request as part of the gesture. Space or Enter on the focused button starts and stops a take.
+// (The operator, 2026-10-26: a tap on the hold-only button did nothing, because the release ended the take
+// before the microphone had answered.)
 import { useEffect, useRef, useState } from 'react'
 import type { FieldProps } from './adapters.ts'
 import { startTake as defaultStartTake } from './recorder.ts'
@@ -15,6 +21,8 @@ import { DEFAULT_STRINGS } from './words.ts'
 
 
 type Take = Awaited<ReturnType<typeof defaultStartTake>>
+/** A press shorter than this is a tap: it starts a take that a second tap stops. */
+const TAP_MS = 350
 
 export function DefaultField(props: FieldProps) {
   const { rt, id, label, value, onChange, placeholder, multiline = false, type = 'text', upload, onHeard, onKept, onHearing, disabled, startTake = defaultStartTake, maxMs, labels, scope } = props
@@ -25,6 +33,8 @@ export function DefaultField(props: FieldProps) {
   const take = useRef<Take | null>(null)
   const wanted = useRef(false)
   const timer = useRef<ReturnType<typeof setTimeout> | null>(null)
+  // The press in progress that started a take: when it began. Null between presses, and for a press that stopped one.
+  const press = useRef<number | null>(null)
   const latest = useRef(value)
   latest.current = value
   const cb = useRef({ onChange, upload, onHeard, onKept, onHearing })
@@ -75,10 +85,29 @@ export function DefaultField(props: FieldProps) {
       aria-pressed={recording}
       aria-label={canRecord ? `${recording ? L.stopTalking : L.holdToTalk}: ${label}` : `${L.voiceUnavailable}: ${label}`}
       disabled={disabled || !canRecord}
-      onPointerDown={(e) => { e.preventDefault(); void begin() }}
-      onPointerUp={() => void end()}
-      onPointerLeave={() => { if (wanted.current) void end() }}
-      onPointerCancel={() => void end()}
+      onPointerDown={(e) => {
+        e.preventDefault()
+        // A take already going (a tapped one): this press stops it.
+        if (take.current || wanted.current) { press.current = null; void end(); return }
+        press.current = Date.now()
+        void begin() // startTake is called before begin's first await: still inside the gesture
+      }}
+      onPointerUp={() => {
+        const at = press.current
+        press.current = null
+        // A tap keeps recording until the next tap; a hold stops on release.
+        if (at !== null && Date.now() - at >= TAP_MS) void end()
+      }}
+      onPointerLeave={() => {
+        // Sliding off a held press stops it, as hold-to-talk did; a tapped take, or one still starting, goes on.
+        const at = press.current
+        press.current = null
+        if (at !== null && take.current && Date.now() - at >= TAP_MS) void end()
+      }}
+      onPointerCancel={() => {
+        // The browser took the pointer (a permission prompt, a scroll): the take carries on as a tapped one.
+        press.current = null
+      }}
       onContextMenu={(e) => e.preventDefault()}
       onKeyDown={(e) => {
         if (e.key !== ' ' && e.key !== 'Enter') return
@@ -93,9 +122,11 @@ export function DefaultField(props: FieldProps) {
   const shared = { id: `sac-field-${id}`, value, placeholder, disabled, className: 'sac-input', onChange: (e: { target: { value: string } }) => onChange(e.target.value) }
   return (
     <div data-voice-field="" className="sac-voice" data-recording={recording ? '' : undefined}>
-      {control}
       <label htmlFor={`sac-field-${id}`} className="sac-sr">{label}</label>
-      {multiline ? <textarea rows={3} {...shared} /> : <input type={type} {...shared} />}
+      <div className={`sac-voice-box ${multiline ? 'sac-voice-multi' : 'sac-voice-single'}`}>
+        {multiline ? <textarea rows={3} {...shared} /> : <input type={type} {...shared} />}
+        {control}
+      </div>
     </div>
   )
 }

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/client/styles.css

@@ -37,11 +37,22 @@
 .sac-select { font: inherit; font-size: 16px; min-height: 36px; padding: 4px 10px; color: inherit; background: var(--sac-bg); border: 1px solid var(--sac-border); border-radius: var(--sac-radius); }
 /* Saying it is the sheet's biggest thing, whatever field the host puts in it. */
 .sac-sayit textarea { min-height: 9rem; }
-.sac-voice { display: flex; align-items: flex-end; gap: 8px; min-width: 0; }
+.sac-voice { min-width: 0; }
 .sac-input, .sac-voice textarea, .sac-voice input { flex: 1; min-width: 0; min-height: 44px; font: inherit; font-size: 16px; color: inherit; background: var(--sac-bg); border: 1px solid var(--sac-border); border-radius: var(--sac-radius); padding: 10px 12px; box-sizing: border-box; }
 .sac-record { flex: none; width: 48px; height: 48px; min-width: 44px; min-height: 44px; border-radius: 50%; border: 1px solid var(--sac-border); background: var(--sac-bg); display: grid; place-items: center; touch-action: none; user-select: none; -webkit-user-select: none; -webkit-touch-callout: none; cursor: pointer; }
 .sac-record-dot { width: 18px; height: 18px; border-radius: 50%; background: var(--sac-danger); }
 .sac-voice[data-recording] .sac-record { border-color: var(--sac-danger); box-shadow: 0 0 0 4px color-mix(in srgb, var(--sac-danger) 25%, transparent); }
+/* Recording: the dot becomes a stop square, so a tapped take reads as "tap to stop". */
+.sac-voice[data-recording] .sac-record-dot { border-radius: 3px; width: 16px; height: 16px; }
+/* The microphone sits inside its text box: bottom right of a text area, centred at the right of a one-line input.
+   The box keeps its text clear of it. */
+.sac-voice-box { position: relative; display: flex; min-width: 0; }
+.sac-voice-box > textarea, .sac-voice-box > input { padding-right: 60px; }
+.sac-voice-multi > textarea { padding-bottom: 56px; }
+.sac-voice-single > input { min-height: 56px; }
+.sac-voice-box > .sac-record { position: absolute; right: 6px; }
+.sac-voice-multi > .sac-record { bottom: 6px; }
+.sac-voice-single > .sac-record { top: 50%; transform: translateY(-50%); }
 .sac-button, .sac-entry, .sac-row-button { font: inherit; font-size: 16px; min-height: 44px; min-width: 44px; padding: 8px 14px; border-radius: var(--sac-radius); border: 1px solid var(--sac-border); background: var(--sac-bg); color: var(--sac-fg); cursor: pointer; }
 .sac-primary { background: var(--sac-accent); color: var(--sac-accent-fg); border-color: var(--sac-accent); }
 .sac-button:disabled { opacity: 0.5; cursor: not-allowed; }
@@ -86,4 +97,5 @@
 .sac-entry-why { margin-left: 8px; color: var(--sac-muted); font-size: 0.9rem; }
 .sac-sheet :focus-visible, .sac-entry:focus-visible, .sac-button:focus-visible, .sac-record:focus-visible, .sac-row-button:focus-visible { outline: 3px solid var(--sac-focus); outline-offset: 2px; }
 @media (min-width: 640px) { .sac-backdrop { align-items: center; } .sac-sheet { border-radius: var(--sac-radius); } }
-@media (prefers-reduced-motion: no-preference) { .sac-voice[data-recording] .sac-record { transition: box-shadow 0.15s; } .sac-fold-mark { transition: transform 0.15s; } }
+@keyframes sac-pulse { 0%, 100% { box-shadow: 0 0 0 4px color-mix(in srgb, var(--sac-danger) 25%, transparent); } 50% { box-shadow: 0 0 0 8px color-mix(in srgb, var(--sac-danger) 10%, transparent); } }
+@media (prefers-reduced-motion: no-preference) { .sac-voice[data-recording] .sac-record { transition: box-shadow 0.15s; animation: sac-pulse 1.4s ease-in-out infinite; } .sac-fold-mark { transition: transform 0.15s; } }

package/src/client/words.ts

@@ -63,6 +63,7 @@ export interface Strings {
   mineTitle: string
   mineEmpty: string
   back: string
+  /** The microphone's name while idle. The key keeps its old name; a tap starts it, and holding works too. */
   holdToTalk: string
   stopTalking: string
   micDenied: string
@@ -143,9 +144,9 @@ export const DEFAULT_STRINGS: Strings = {
   optional: 'optional',
   sayItLegend: 'Say it',
   sayItLabel: 'Your suggestion',
-  sayItPlaceholder: 'What would you change? Type it, or hold the microphone and say it',
-  sayItPlaceholderBroken: 'What happened, what you expected, and how to make it happen again. Type it, or hold the microphone and say it',
-  sayItPlaceholderFeedback: 'Whatever is on your mind. Type it, or hold the microphone and say it',
+  sayItPlaceholder: 'What would you change? Type it, or tap the microphone and say it',
+  sayItPlaceholderBroken: 'What happened, what you expected, and how to make it happen again. Type it, or tap the microphone and say it',
+  sayItPlaceholderFeedback: 'Whatever is on your mind. Type it, or tap the microphone and say it',
   showItLegend: 'Show it',
   addImages: 'Add a screenshot or photo',
   addVideo: 'Add a short video',
@@ -174,8 +175,8 @@ export const DEFAULT_STRINGS: Strings = {
   mineTitle: 'My suggestions',
   mineEmpty: 'You have not sent a suggestion yet.',
   back: 'Back',
-  holdToTalk: 'Hold to talk',
-  stopTalking: 'Stop and keep the recording',
+  holdToTalk: 'Tap to talk',
+  stopTalking: 'Tap to stop',
   micDenied: 'The microphone could not be used. You can type it instead.',
   voiceUnavailable: 'Voice notes cannot be added here',
   loading: 'Loading',

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 },
   })