@supersuit/suggest-a-change 0.1.13 → 0.2.0

package/dist/client/sheet.js

@@ -1,5 +1,5 @@
 'use client';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // THE SHEET (design section 2): kind, say it, show it, what goes with it, send. Phone first. The kind is one
 // small menu and saying it is one big box for every kind, broken included: the box is what takes the space,
 // so a person sees first that they will be heard out (the operator, 2026-10-19). Everything
@@ -7,6 +7,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // through the outbox, so a closed app loses nothing. A voice note alone is a whole report.
 import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
 import { isAcceptedMedia, sanitizeRoute, typeForFile, validateReport } from '../contract.mjs';
+import { destinationWords, whatGoes } from '../github/compose.js';
+import { validContact } from '../contract.mjs';
+import { collectContext } from './context.js';
 import { useDialog } from './dialog.js';
 import { DefaultField } from './default-field.js';
 import { draftKey, loadDraft, saveDraft } from './drafts.js';
@@ -77,6 +80,39 @@ export function SuggestSheet({ adapters, where, onClose, initial }) {
     const [announce, setAnnounce] = useState('');
     const [sent, setSent] = useState(null);
     const [loaded, setLoaded] = useState(false);
+    const [dest, setDest] = useState(null);
+    // Everything shared so it can be fixed, each with why; all on by default, any one can be left out (`choice`).
+    const [ctx, setCtx] = useState(null);
+    const [contact, setContact] = useState(null);
+    const [choice, setChoice] = useState({});
+    // Where it files, asked once when the sheet opens; until it answers (or with none) the one-line note stays.
+    useEffect(() => {
+        if (!adapters.destination)
+            return;
+        let live = true;
+        adapters.destination().then((d) => { if (live)
+            setDest(d && typeof d.repo === 'string' ? d : null); }, () => { if (live)
+            setDest(null); });
+        return () => { live = false; };
+    }, [adapters]);
+    const contextOptions = useCallback(() => {
+        const c = adapters.context;
+        return typeof c === 'function' ? { extra: c, precise: false } : { extra: c?.items ? () => c.items() : undefined, precise: Boolean(c?.precise) };
+    }, [adapters]);
+    const gather = useCallback(() => collectContext({ identity: who ?? null, where, about: adapters.about, ...contextOptions(), ...(adapters.phone?.now ? { now: adapters.phone.now } : {}) }), [who, where, adapters, contextOptions]);
+    useEffect(() => {
+        if (!who)
+            return;
+        let live = true;
+        void gather().then((c) => { if (live)
+            setCtx(c); });
+        if (adapters.contact)
+            adapters.contact().then((c) => { if (live)
+                setContact(c && !validContact(c).length ? c : null); }, () => { });
+        return () => { live = false; };
+        // where is an object the host may rebuild each render; the context is gathered once per open and again at Send.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [adapters, who]);
     const chain = useRef(Promise.resolve());
     // What is on the sheet, kept in step with state so a second take or picture added a moment later counts the first.
     const voiceRef = useRef([]);
@@ -268,6 +304,22 @@ export function SuggestSheet({ adapters, where, onClose, initial }) {
     ].filter((d) => Boolean(d.value));
     const lineParts = [`this screen (${where.screen}, ${sanitizeRoute(where.route)})`, ...avail.map((d) => d.label)];
     const summary = `${S.goesTo(adapters.words.owner)} ${S.includes(lineParts)}`;
+    // With a destination, the one line becomes the list of exactly what the issue will carry, built by the same function
+    // the issue is written from (`whatGoes`), so the list and the issue cannot drift. It follows the draft as it changes.
+    // Every row of the list, whether or not there is a destination; optional rows carry a tick box.
+    const rows = whatGoes({
+        kind, words, voice: voice.map((v) => ({ file: v.file, ms: v.ms })), media: media.map((m) => ({ file: m.file, type: m.type, bytes: m.bytes })),
+        where: { screen: where.screen, route: sanitizeRoute(where.route) },
+        diagnostics: Object.fromEntries(avail.map((d) => [d.name, d.value])),
+        appName: adapters.about?.app ?? adapters.words.app,
+        ...(dest?.name ? { filerName: dest.name } : {}),
+        ...(ctx ? { context: ctx } : {}),
+        ...(contact ? { who: { contact } } : {}),
+    }, dest ?? { repo: '', public: false, account: '', attaches: true });
+    const isOn = (key, fallback = true) => choice[key] ?? rows.find((r) => r.key === key)?.on ?? fallback;
+    const goes = dest ? rows : null;
+    const destWords = dest ? destinationWords(dest) : null;
+    const optionalRow = (g) => (_jsx("li", { "data-goes": g.key, className: "sac-goes-opt", children: _jsxs("label", { children: [_jsx("input", { type: "checkbox", checked: isOn(g.key), onChange: (e) => setChoice((c) => ({ ...c, [g.key]: e.target.checked })) }), ' ', _jsx("span", { className: "sac-goes-label", children: g.text }), g.value ? _jsxs(_Fragment, { children: [": ", _jsx("span", { className: "sac-goes-value", children: g.value })] }) : null, ' ', _jsxs("span", { className: "sac-muted sac-goes-why", children: ["(", g.why, g.reason ? `; off by default because ${g.reason}` : '', ")"] })] }) }, g.key));
     const hasAnything = Boolean(words.trim() || voice.length || media.length);
     async function send() {
         if (!rt || !who || !key || !hasAnything)
@@ -275,14 +327,22 @@ export function SuggestSheet({ adapters, where, onClose, initial }) {
         setError('');
         await chain.current;
         const d = await saveDraft(rt.store, key, { kind, words, attachments: [...voice.map((v) => v.key), ...media.map((m) => m.key)] });
+        // What was left out never leaves the phone: the context gathered again now (the trail has grown), minus every row
+        // the person unticked, and the diagnostics those rows stand for.
+        const fresh = await gather();
+        const keep = { ...fresh, items: fresh.items.filter((i) => isOn(`ctx:${i.key}`)), routes: isOn('routes') ? fresh.routes : [], taps: isOn('taps') ? fresh.taps : [], errors: isOn('errors') ? fresh.errors : [] };
+        const leftOut = { 'ctx:device': 'device', 'ctx:screen': 'screen', 'ctx:time': 'at' };
         const diagnostics = {};
         for (const x of avail)
-            diagnostics[x.name] = x.value;
+            if (!Object.entries(leftOut).some(([k, d]) => d === x.name && !isOn(k)))
+                diagnostics[x.name] = x.value;
+        const reach = contact && isOn('contact') ? contact : null;
         const report = {
             id: d.reportId,
             kind,
             ...(adapters.about ? { app: Object.fromEntries(Object.entries(adapters.about).filter(([k]) => k !== 'version')) } : {}),
-            who: { member: who.account, role: who.role },
+            who: { member: who.account, role: who.role, ...(reach ? { contact: reach } : {}) },
+            context: keep,
             words: words.trim(),
             voice: voice.map((v) => ({ file: v.file, ms: v.ms, field: v.field })),
             media: await Promise.all(media.map(async (m) => {
@@ -334,5 +394,5 @@ export function SuggestSheet({ adapters, where, onClose, initial }) {
     return (_jsx("div", { className: "sac-backdrop", "data-suggest-sheet": "", children: _jsxs("div", { ref: box, className: "sac-sheet", role: "dialog", "aria-modal": "true", "aria-labelledby": titleId, tabIndex: -1, children: [_jsxs("header", { className: "sac-header", children: [_jsx("h2", { id: titleId, className: "sac-title", children: S.sheetTitle }), onClose ? _jsx("button", { type: "button", className: "sac-button sac-close", onClick: onClose, children: S.close }) : null] }), _jsx("div", { className: "sac-sr", "data-sac-live": "", role: "status", "aria-live": "polite", "aria-atomic": "true", children: announce }), who === undefined ? _jsx("p", { children: S.loading }) : who === null ? _jsx("p", { role: "alert", children: S.signedOut }) : !rt ? _jsx("p", { children: S.loading }) : sent ? (_jsxs("div", { className: "sac-sent", children: [_jsx(Receipt, { adapters: adapters, reportId: sent.id, quiet: true, onLine: setAnnounce }), sent.files.length ? (_jsx("ul", { className: "sac-list", "aria-label": S.attachmentsLabel, children: sent.files.map((f) => {
                                 const p = rt.part(sent.id, f.file);
                                 return (_jsxs("li", { className: "sac-item", "data-attachment-state": p.state, children: [_jsxs("span", { className: "sac-item-name", children: [f.name, f.bytes ? `, ${sizeWords(f.bytes)}` : ''] }), _jsxs("span", { className: "sac-item-state", children: [p.state === 'sending' ? _jsx("progress", { "aria-label": `${S.sending} ${f.name}` }) : null, p.state === 'waiting' ? S.waitingToSend : p.state === 'sending' ? S.sending : p.state === 'sent' ? S.sentWord : S.didNotSend(p.reason ?? '')] }), p.state === 'failed' ? _jsx("button", { type: "button", className: "sac-button", onClick: () => void rt.retry(sent.id), children: S.retry }) : null] }, f.file));
-                            }) })) : null, onClose ? _jsx("button", { type: "button", className: "sac-button sac-primary", onClick: onClose, children: S.done }) : null] })) : (_jsxs("form", { className: "sac-form", onSubmit: (e) => { e.preventDefault(); void send(); }, children: [_jsxs("div", { className: "sac-kind", children: [_jsx("label", { htmlFor: `${titleId}-kind`, children: S.kindLegend }), _jsx("select", { id: `${titleId}-kind`, className: "sac-select", value: kind, onChange: (e) => setKind(e.target.value), children: kinds.map((k) => _jsx("option", { value: k.id, children: k.label }, k.id)) })] }), _jsxs("fieldset", { className: "sac-group sac-sayit", children: [_jsx("legend", { children: S.sayItLegend }), fieldFor('words', S.sayItLabel, words, setWords, { placeholder: kind === 'broken' ? S.sayItPlaceholderBroken : kind === 'feedback' ? S.sayItPlaceholderFeedback : S.sayItPlaceholder }), voice.length ? (_jsx("ul", { className: "sac-list", "aria-label": S.voiceNotesLabel, children: voice.map((v, i) => (_jsxs("li", { className: "sac-item", children: [_jsx("span", { className: "sac-item-name", children: S.voiceNote(i + 1, lengthWords(v.ms)) }), _jsx("button", { type: "button", className: "sac-button", "aria-label": `${S.remove} ${S.voiceNote(i + 1, lengthWords(v.ms))}`, onClick: () => void removeVoice(v), children: S.remove })] }, v.key))) })) : null] }), _jsxs("fieldset", { className: "sac-group", children: [_jsx("legend", { children: S.showItLegend }), _jsxs("div", { className: "sac-actions", children: [_jsx("button", { type: "button", className: "sac-button", onClick: () => fileInput.current?.click(), children: S.addImages }), _jsx("button", { type: "button", className: "sac-button", onClick: () => videoInput.current?.click(), children: S.addVideo }), adapters.snapshot ? _jsx("button", { type: "button", className: "sac-button", onClick: () => void takeScreenshot(), children: S.takeScreenshot }) : null] }), _jsx("input", { ref: fileInput, type: "file", accept: "image/*", multiple: true, hidden: true, "aria-label": S.addImages, "data-sac-images": "", onChange: (e) => { const f = [...(e.target.files ?? [])]; e.target.value = ''; void addMedia(f, 'image'); } }), _jsx("input", { ref: videoInput, type: "file", accept: "video/*", hidden: true, "aria-label": S.addVideo, "data-sac-video": "", onChange: (e) => { const f = [...(e.target.files ?? [])]; e.target.value = ''; void addMedia(f, 'video'); } }), media.length ? (_jsx("ul", { className: "sac-list", "aria-label": S.attachmentsLabel, children: media.map((m) => (_jsxs("li", { className: "sac-item", children: [_jsxs("span", { className: "sac-item-name", children: [m.name, ", ", sizeWords(m.bytes)] }), _jsx("button", { type: "button", className: "sac-button", "aria-label": `${S.remove} ${m.name}`, onClick: () => void removeMedia(m), children: S.remove })] }, m.key))) })) : null] }), _jsx("p", { className: "sac-muted sac-fyi", "data-sac-summary": "", children: summary }), error ? _jsx("p", { role: "alert", className: "sac-error", children: error }) : null, _jsxs("div", { className: "sac-actions", children: [_jsx("button", { type: "submit", className: "sac-button sac-primary", disabled: !hasAnything, "aria-describedby": hasAnything ? undefined : `${titleId}-hint`, children: S.send }), hasAnything ? null : _jsx("span", { id: `${titleId}-hint`, className: "sac-muted", children: S.sendHint })] })] })), _jsx(Toasts, {})] }) }));
+                            }) })) : null, onClose ? _jsx("button", { type: "button", className: "sac-button sac-primary", onClick: onClose, children: S.done }) : null] })) : (_jsxs("form", { className: "sac-form", onSubmit: (e) => { e.preventDefault(); void send(); }, children: [_jsxs("div", { className: "sac-kind", children: [_jsx("label", { htmlFor: `${titleId}-kind`, children: S.kindLegend }), _jsx("select", { id: `${titleId}-kind`, className: "sac-select", value: kind, onChange: (e) => setKind(e.target.value), children: kinds.map((k) => _jsx("option", { value: k.id, children: k.label }, k.id)) })] }), _jsxs("fieldset", { className: "sac-group sac-sayit", children: [_jsx("legend", { children: S.sayItLegend }), fieldFor('words', S.sayItLabel, words, setWords, { placeholder: kind === 'broken' ? S.sayItPlaceholderBroken : kind === 'feedback' ? S.sayItPlaceholderFeedback : S.sayItPlaceholder }), voice.length ? (_jsx("ul", { className: "sac-list", "aria-label": S.voiceNotesLabel, children: voice.map((v, i) => (_jsxs("li", { className: "sac-item", children: [_jsx("span", { className: "sac-item-name", children: S.voiceNote(i + 1, lengthWords(v.ms)) }), _jsx("button", { type: "button", className: "sac-button", "aria-label": `${S.remove} ${S.voiceNote(i + 1, lengthWords(v.ms))}`, onClick: () => void removeVoice(v), children: S.remove })] }, v.key))) })) : null] }), _jsxs("fieldset", { className: "sac-group", children: [_jsx("legend", { children: S.showItLegend }), _jsxs("div", { className: "sac-actions", children: [_jsx("button", { type: "button", className: "sac-button", onClick: () => fileInput.current?.click(), children: S.addImages }), _jsx("button", { type: "button", className: "sac-button", onClick: () => videoInput.current?.click(), children: S.addVideo }), adapters.snapshot ? _jsx("button", { type: "button", className: "sac-button", onClick: () => void takeScreenshot(), children: S.takeScreenshot }) : null] }), _jsx("input", { ref: fileInput, type: "file", accept: "image/*", multiple: true, hidden: true, "aria-label": S.addImages, "data-sac-images": "", onChange: (e) => { const f = [...(e.target.files ?? [])]; e.target.value = ''; void addMedia(f, 'image'); } }), _jsx("input", { ref: videoInput, type: "file", accept: "video/*", hidden: true, "aria-label": S.addVideo, "data-sac-video": "", onChange: (e) => { const f = [...(e.target.files ?? [])]; e.target.value = ''; void addMedia(f, 'video'); } }), media.length ? (_jsx("ul", { className: "sac-list", "aria-label": S.attachmentsLabel, children: media.map((m) => (_jsxs("li", { className: "sac-item", children: [_jsxs("span", { className: "sac-item-name", children: [m.name, ", ", sizeWords(m.bytes)] }), _jsx("button", { type: "button", className: "sac-button", "aria-label": `${S.remove} ${m.name}`, onClick: () => void removeMedia(m), children: S.remove })] }, m.key))) })) : null] }), goes && destWords ? (_jsxs("div", { className: "sac-goes sac-fyi", "data-sac-goes": "", children: [_jsxs("p", { className: "sac-goes-head", children: [_jsx("strong", { children: destWords.headline }), ' (', _jsx("span", { className: destWords.danger ? 'sac-danger' : 'sac-muted', children: destWords.privacy }), ")"] }), _jsx("p", { className: "sac-muted", children: "It will carry:" }), _jsx("ul", { className: "sac-goes-list", children: goes.filter((g) => !g.optional).map((g) => _jsx("li", { "data-goes": g.key, children: g.text }, g.key)) }), goes.some((g) => g.optional) ? _jsx("ul", { className: "sac-goes-opts", "aria-label": S.contextLegend, children: goes.filter((g) => g.optional).map(optionalRow) }) : null, _jsx("p", { className: "sac-muted", children: destWords.account })] })) : (_jsxs("div", { className: "sac-fyi", children: [_jsx("p", { className: "sac-muted sac-fyi", "data-sac-summary": "", children: summary }), rows.some((g) => g.optional) ? _jsx("ul", { className: "sac-goes-opts", "aria-label": S.contextLegend, children: rows.filter((g) => g.optional).map(optionalRow) }) : null] })), error ? _jsx("p", { role: "alert", className: "sac-error", children: error }) : null, _jsxs("div", { className: "sac-actions", children: [_jsx("button", { type: "submit", className: "sac-button sac-primary", disabled: !hasAnything, "aria-describedby": hasAnything ? undefined : `${titleId}-hint`, children: S.send }), hasAnything ? null : _jsx("span", { id: `${titleId}-hint`, className: "sac-muted", children: S.sendHint })] })] })), _jsx(Toasts, {})] }) }));
 }

package/dist/client/words.d.ts

@@ -99,12 +99,21 @@ export interface Strings {
     entryMoved: string;
     /** The one toast per open. `words` is the status's own word (wordsFor); `note` is the not-now reason, when there is one. */
     movedToast: (words: string, note?: string) => string;
+    /** The link to the issue a report became. */
+    issueLink: (n: number) => string;
+    /** The accessible name of the list of context, each row a tick box. */
+    contextLegend: string;
 }
 export declare const DEFAULT_STRINGS: Strings;
 export declare function stringsFor(words: Words): Strings;
 /** The design's status word for a status; a status the contract does not know shows as itself instead of taking the list down. */
 export declare function statusWords(status: string, owner: string): string;
-export declare function statusMeaning(status: string, owner: string): string;
+export declare function statusMeaning(status: string, owner: string, issue?: unknown): string;
+/** The issue a report became, when it is one this module will link: a github.com address and a whole number. */
+export declare function linkableIssue(issue: unknown): {
+    number: number;
+    url: string;
+} | null;
 export type ReceiptState = 'on-phone' | 'received' | 'on-mac';
 /** The receipt's one line (design section 2). `received` is only ever asked for after the adapter said `done`. */
 export declare function receiptWords(state: ReceiptState, words: Pick<Words, 'owner'>): string;

package/dist/client/words.js

@@ -89,6 +89,8 @@ export const DEFAULT_STRINGS = {
     newMark: 'New',
     entryMoved: 'One of your suggestions has news',
     movedToast: (words, note) => (note ? `Your suggestion: ${words}. ${note}` : `Your suggestion: ${words}`),
+    issueLink: (n) => `Issue #${n}`,
+    contextLegend: 'Also shared, so it can be fixed (untick anything to leave it out)',
 };
 export function stringsFor(words) {
     return { ...DEFAULT_STRINGS, ...words.text };
@@ -107,14 +109,21 @@ export function statusWords(status, owner) {
         return String(status);
     }
 }
-export function statusMeaning(status, owner) {
+export function statusMeaning(status, owner, issue) {
     try {
-        return meaningFor(status, { owner });
+        return meaningFor(status, { owner, issue });
     }
     catch {
         return '';
     }
 }
+/** The issue a report became, when it is one this module will link: a github.com address and a whole number. */
+export function linkableIssue(issue) {
+    const i = issue;
+    if (!i || typeof i !== 'object' || !Number.isInteger(i.number) || typeof i.url !== 'string' || !i.url.startsWith('https://github.com/'))
+        return null;
+    return { number: i.number, url: i.url };
+}
 /** The receipt's one line (design section 2). `received` is only ever asked for after the adapter said `done`. */
 export function receiptWords(state, words) {
     if (state === 'received')

package/dist/contract.d.mts

@@ -22,42 +22,52 @@ export declare const FLOW: {
         actor: string;
         next: string[];
     };
-    "with-freeda": {
+    held: {
         actor: string;
         next: string[];
     };
-    planned: {
+    open: {
         actor: string;
         next: string[];
     };
-    "waiting-on-owner": {
+    done: {
         actor: string;
         next: string[];
     };
-    "being-made": {
+    "not-planned": {
         actor: string;
         next: string[];
     };
-    live: {
-        actor: string;
-        next: never[];
-    };
-    "sent-to-template": {
-        actor: string;
-        next: never[];
-    };
-    filed: {
-        actor: string;
-        next: never[];
-    };
-    "not-now": {
-        actor: string;
-        next: never[];
-    };
 };
+export declare const LEGACY: {
+    "with-freeda": string;
+    planned: string;
+    "waiting-on-owner": string;
+    "being-made": string;
+    live: string;
+    "sent-to-template": string;
+    filed: string;
+    "not-now": string;
+};
+/** The status this one means now: a legacy status folded, anything else as it is. */
+export declare const currentStatus: (s: any) => any;
 export declare const mayMove: (from: any, to: any) => boolean;
 export declare const wordsFor: (status: any, { owner }?: {}) => any;
-export declare const meaningFor: (status: any, { owner }?: {}) => any;
+export declare const meaningFor: (status: any, { owner, issue }?: {}) => any;
+export declare function validContact(c: any): string[];
+export declare const CONTEXT_CEILINGS: {
+    items: number;
+    routes: number;
+    taps: number;
+    errors: number;
+};
+export declare const isIsoTime: (v: any) => boolean;
+export declare function validContext(ctx: any): any[];
+/** A GitHub "owner/name": two plain segments, neither "." nor "..", so it can never walk out of /repos/ in a URL.
+ *  @param {unknown} s @returns {s is string} */
+export declare const isRepoName: (s: unknown) => s is string;
+/** The issue a report became: `{ repo: "owner/name", number, url }`, the url on github.com. Problems as a list. */
+export declare function validIssue(issue: any): string[];
 declare const randomSix: () => string;
 export declare function newReportId(now?: Date, rand?: typeof randomSix): string;
 export declare const sanitizeRoute: (url: any) => string;
@@ -73,7 +83,7 @@ export declare function validateReport(raw: any, { ceilings }?: {
         voiceTotalMs: number;
         perPersonPerDay: number;
     } | undefined;
-}): string[];
+}): any[];
 export declare const ACCEPTED_TYPES: string[];
 /** A declared type without its parameters (`audio/webm;codecs=opus`), lowercased, with common aliases folded. */
 export declare const canonicalType: (t: any) => any;

package/dist/contract.mjs

@@ -11,52 +11,132 @@ export const CEILINGS = {
     voiceMs: 300_000, voiceTotalMs: 900_000,
     perPersonPerDay: 20,
 };
-export const STATUSES = ["on-phone", "received", "with-freeda", "planned", "waiting-on-owner", "being-made", "live", "sent-to-template", "filed", "not-now"];
-export const END = ["live", "sent-to-template", "filed", "not-now"];
-// The moves the person who suggested a change hears about: the work starting, and every end. The planning steps stay quiet.
-export const TOLD = ["being-made", ...END];
-// actor: who PERFORMS this step (design section 7): sent by the person, received by the app, with Pluma by the Mac. A Helm on the owner's Mac posts straight into
-// the inbox, so a report may go from the phone to Pluma without the hosted app's "received". The owner may decline
-// ("not-now") before Pluma has a plan or before she asks: a report she cannot plan would otherwise have no exit.
+// A suggestion becomes one ordinary GitHub issue (suggestions-as-github-issues design, section 3), so the statuses a
+// person sees are GitHub's: not sent, received, held before filing, then the issue's own open and closed states.
+export const STATUSES = ["on-phone", "received", "held", "open", "done", "not-planned"];
+// Closed on GitHub. A closed issue can be reopened, so an end is not final: it can go back to "open".
+export const END = ["done", "not-planned"];
+// The moves the person who suggested a change hears about: the issue existing, and every close.
+export const TOLD = ["open", ...END];
+// actor: who PERFORMS this step. Sent by the person, received by the app, held for the owner (the privacy catch stopped
+// it, or the account cannot file yet), filed by the Mac (or an app's own server), closed or reopened on GitHub. A Helm on
+// the owner's Mac posts straight there, so a report may go from the phone to held or open without the app's "received".
 export const FLOW = {
-    "on-phone": { actor: "person", next: ["received", "with-freeda"] },
-    "received": { actor: "app", next: ["with-freeda"] },
-    "with-freeda": { actor: "mac", next: ["planned", "not-now"] },
-    "planned": { actor: "freeda", next: ["waiting-on-owner", "being-made", "not-now"] },
-    "waiting-on-owner": { actor: "owner", next: ["being-made", "filed", "not-now"] },
-    "being-made": { actor: "freeda", next: ["live", "sent-to-template", "filed", "not-now"] },
-    "live": { actor: "freeda", next: [] },
-    "sent-to-template": { actor: "freeda", next: [] },
-    "filed": { actor: "freeda", next: [] },
-    "not-now": { actor: "owner", next: [] },
+    "on-phone": { actor: "person", next: ["received", "held", "open"] },
+    "received": { actor: "app", next: ["held", "open", "not-planned"] },
+    "held": { actor: "owner", next: ["open", "not-planned"] },
+    "open": { actor: "mac", next: ["done", "not-planned"] },
+    "done": { actor: "github", next: ["open"] },
+    "not-planned": { actor: "github", next: ["open"] },
 };
-export const mayMove = (from, to) => Boolean(FLOW[from]?.next.includes(to));
-// The design's status table (section 2), word for word. "planned" is a step inside Pluma's work
-// that the table does not name for a person, so it reads as "With Pluma".
+// THE OLD STATUSES (0.1.x) STAY READABLE. Each folds into what it now means: a report the old pipeline was still
+// working on has not been filed yet (the Mac files it), one it shipped or passed on is done, one declined is not planned.
+export const LEGACY = {
+    "with-freeda": "received",
+    "planned": "received",
+    "waiting-on-owner": "received",
+    "being-made": "received",
+    "live": "done",
+    "sent-to-template": "done",
+    "filed": "done",
+    "not-now": "not-planned",
+};
+/** The status this one means now: a legacy status folded, anything else as it is. */
+export const currentStatus = (s) => LEGACY[s] ?? s;
+export const mayMove = (from, to) => Boolean(FLOW[currentStatus(from)]?.next.includes(to));
+// The design's status table (section 3), word for word.
+const issueWords = (issue) => (Number.isInteger(issue?.number) ? `Filed as issue #${issue.number}` : "Filed as an issue");
 const TABLE = {
-    "on-phone": ["On this phone", () => "Not sent yet; it will send when there is a connection"],
-    "received": ["Received", () => "The app has it, safely stored"],
-    "with-freeda": ["With Pluma", (o) => `${o}'s Mac has picked it up`],
-    "planned": ["With Pluma", (o) => `${o}'s Mac has picked it up`],
-    "waiting-on-owner": [null, (o) => `Pluma has a plan and is asking ${o}`],
-    "being-made": ["Being made", () => "A session is working on it; the current step shows underneath"],
-    "live": ["Done", () => "Shipped in the app, with the date it went live"],
-    "sent-to-template": ["Sent to the template", () => "It became a change to the template every copy of this app uses; it reaches this app once merged"],
-    "filed": ["Filed", () => "It was passed to whoever owns the problem"],
-    "not-now": ["Not now", (o) => `${o} decided against it, with the one-line reason if given`],
+    "on-phone": [() => "On this phone", () => "Not sent yet; it will send when there is a connection"],
+    "received": [() => "Received", () => "The app has it, safely stored"],
+    "held": [(o) => `Waiting on ${o}`, (o) => `${o} looks at it before it is filed`],
+    "open": [() => "Open", (o, issue) => issueWords(issue)],
+    "done": [() => "Done", () => "Closed as completed"],
+    "not-planned": [() => "Not planned", () => "Closed as not planned, with the reason if one was given"],
 };
 const row = (status) => {
-    if (!TABLE[status])
+    const s = currentStatus(status);
+    if (!TABLE[s])
         throw new Error(`${status} is not a status`);
-    return TABLE[status];
+    return TABLE[s];
 };
-export const wordsFor = (status, { owner } = {}) => row(status)[0] ?? `Waiting on ${owner}`;
-export const meaningFor = (status, { owner } = {}) => row(status)[1](owner);
+export const wordsFor = (status, { owner } = {}) => row(status)[0](owner);
+export const meaningFor = (status, { owner, issue } = {}) => row(status)[1](owner, issue);
+// HOW TO REACH THE SENDER: what the app already knows of them, so whoever fixes it can say thanks or ask a question.
+const CONTACT_EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/;
+const CONTACT_PHONE = /^\+?[0-9][0-9 ().-]{5,24}$/;
+export function validContact(c) {
+    if (!c || typeof c !== "object" || Array.isArray(c))
+        return ["who.contact is not an object"];
+    const errs = [];
+    for (const k of Object.keys(c))
+        if (!["email", "phone", "handle"].includes(k))
+            errs.push(`who.contact.${k} is not one of email, phone, handle`);
+    if (c.email !== undefined && (typeof c.email !== "string" || c.email.length > 254 || !CONTACT_EMAIL.test(c.email)))
+        errs.push("who.contact.email is not an email address");
+    if (c.phone !== undefined && (typeof c.phone !== "string" || !CONTACT_PHONE.test(c.phone)))
+        errs.push("who.contact.phone is not a phone number");
+    if (c.handle !== undefined && (typeof c.handle !== "string" || !c.handle.trim() || c.handle.length > 100 || /[\r\n]/.test(c.handle)))
+        errs.push("who.contact.handle is not a short one-line handle");
+    return errs;
+}
+// THE CONTEXT a report carries so it can be fixed: labelled items, each with why it is shared, and the trail that led here.
+export const CONTEXT_CEILINGS = { items: 40, routes: 10, taps: 20, errors: 10 };
+const shortText = (v, max) => typeof v === "string" && v.length <= max;
+/** A time as the module writes one: ISO 8601 with a zone, at most 40 characters, so a time field can never carry text. */
+const ISO_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})$/;
+export const isIsoTime = (v) => typeof v === "string" && v.length <= 40 && ISO_TIME.test(v);
+export function validContext(ctx) {
+    if (!ctx || typeof ctx !== "object" || Array.isArray(ctx))
+        return ["context is not an object"];
+    const errs = [];
+    const list = (name, max, check) => {
+        const v = ctx[name];
+        if (v === undefined)
+            return;
+        if (!Array.isArray(v)) {
+            errs.push(`context.${name} is not a list`);
+            return;
+        }
+        if (v.length > max)
+            errs.push(`context.${name} has ${v.length} entries; the ceiling is ${max}`);
+        v.forEach((x, i) => { const e = x && typeof x === "object" ? check(x) : "is not an object"; if (e)
+            errs.push(`context.${name}.${i} ${e}`); });
+    };
+    list("items", CONTEXT_CEILINGS.items, (x) => !shortText(x.key, 40) || !/^[A-Za-z0-9:_-]+$/.test(x.key) ? "has no plain key"
+        : !shortText(x.label, 80) || !x.label ? "has no short label"
+            : !shortText(x.value, 500) ? "has no value of at most 500 characters"
+                : !shortText(x.why, 200) || !x.why.trim() ? "does not say why it is shared" : null);
+    list("routes", CONTEXT_CEILINGS.routes, (x) => (!shortText(x.route, 300) || /[?#]/.test(x.route) ? "is not a route without its query" : !isIsoTime(x.at) ? "has no ISO time" : null));
+    list("taps", CONTEXT_CEILINGS.taps, (x) => (!shortText(x.label, 80) ? "has no label of at most 80 characters" : !isIsoTime(x.at) ? "has no ISO time" : null));
+    list("errors", CONTEXT_CEILINGS.errors, (x) => (!shortText(x.message, 300) ? "has no message of at most 300 characters" : x.frame !== undefined && !shortText(x.frame, 200) ? "has a frame over 200 characters" : !isIsoTime(x.at) ? "has no ISO time" : null));
+    return errs;
+}
+const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+/** A GitHub "owner/name": two plain segments, neither "." nor "..", so it can never walk out of /repos/ in a URL.
+ *  @param {unknown} s @returns {s is string} */
+export const isRepoName = (s) => typeof s === "string" && REPO.test(s) && !s.split("/").some((p) => p === "." || p === "..");
+/** The issue a report became: `{ repo: "owner/name", number, url }`, the url on github.com. Problems as a list. */
+export function validIssue(issue) {
+    if (!issue || typeof issue !== "object" || Array.isArray(issue))
+        return ["issue is not an object"];
+    const errs = [];
+    if (!isRepoName(issue.repo))
+        errs.push("issue.repo is not owner/name");
+    if (!Number.isInteger(issue.number) || issue.number < 1)
+        errs.push("issue.number is not a positive whole number");
+    if (typeof issue.url !== "string" || !issue.url.startsWith("https://github.com/"))
+        errs.push("issue.url is not a https://github.com/ link");
+    return errs;
+}
 const ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+// The platform's secure random source where there is one (every browser and Node 19+), Math.random only where there is not.
 const randomSix = () => {
+    const c = globalThis.crypto;
+    const bytes = typeof c?.getRandomValues === "function" ? c.getRandomValues(new Uint8Array(6)) : Uint8Array.from({ length: 6 }, () => Math.floor(Math.random() * 256));
     let s = "";
-    for (let i = 0; i < 6; i++)
-        s += ALPHABET[Math.floor(Math.random() * ALPHABET.length)];
+    for (const b of bytes)
+        s += ALPHABET[b % ALPHABET.length];
     return s;
 };
 export function newReportId(now = new Date(), rand = randomSix) {
@@ -92,10 +172,20 @@ export function validateReport(raw, { ceilings = CEILINGS } = {}) {
         errs.push(`kind ${JSON.stringify(raw.kind)} is not one of ${KINDS.join(", ")}`);
     if (!ROLES.includes(raw.who?.role))
         errs.push(`role ${JSON.stringify(raw.who?.role)} is not one of ${ROLES.join(", ")}`);
+    // The one place an email may sit is the sender's own way to be reached, who.contact.email, and only there.
     for (const p of findKey(raw, "email"))
-        errs.push(`${p}: a report never carries an email`);
+        if (p !== "report.who.contact.email")
+            errs.push(`${p}: a report never carries an email`);
+    if (raw.who?.contact !== undefined)
+        errs.push(...validContact(raw.who.contact));
+    if (raw.diagnostics?.at !== undefined && !isIsoTime(raw.diagnostics.at))
+        errs.push("diagnostics.at is not an ISO time");
+    if (raw.context !== undefined)
+        errs.push(...validContext(raw.context));
     if (String(raw.where?.route ?? "").includes("?"))
         errs.push("where.route keeps a query string");
+    if (raw.issue !== undefined)
+        errs.push(...validIssue(raw.issue));
     for (const k of Object.keys(raw.diagnostics ?? {})) {
         if (!DIAGNOSTIC_KEYS.includes(k))
             errs.push(`diagnostics.${k} is not one of ${DIAGNOSTIC_KEYS.join(", ")}`);

package/dist/github/api.d.ts

@@ -0,0 +1,100 @@
+import { type ComposeOptions, type Draft } from './compose.ts';
+import type { AttachmentHost, AttachmentFile } from './hosts.ts';
+import { type RelayFiler } from './filer.ts';
+export type Fetch = typeof globalThis.fetch;
+export interface GitHubConfig {
+    repo: string;
+    token: string;
+    fetch?: Fetch; /** Default https://api.github.com */
+    api?: string;
+}
+export declare class GitHubError extends Error {
+    status: number;
+    body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+/** One REST call. Answers the parsed body, or throws a GitHubError carrying GitHub's status. */
+export declare function github(cfg: {
+    token: string;
+    fetch?: Fetch;
+    api?: string;
+}, method: string, path: string, body?: unknown): Promise<{
+    status: number;
+    body: any;
+}>;
+/** Opens one issue. Missing labels are created first; one that exists (422) or that this account may not create
+ *  (403/404: a read-only filer) is skipped, and GitHub then keeps only the labels the filer may set. */
+export declare function fileIssue(cfg: GitHubConfig, issue: {
+    title: string;
+    body: string;
+    labels: string[];
+}): Promise<{
+    number: number;
+    url: string;
+}>;
+/** Replaces an issue's body (the filer's own issue: read access is enough to edit what you opened). */
+export declare function updateIssue(cfg: GitHubConfig, number: number, change: {
+    body: string;
+}): Promise<void>;
+/** A follow-up the person added later, as a comment on the same issue. */
+export declare function addFollowUp(cfg: GitHubConfig, number: number, body: string): Promise<{
+    id: number;
+    url: string;
+}>;
+export interface IssueState {
+    repo: string;
+    number: number;
+    state: string | null;
+    stateReason: string | null; /** First line of the last comment, on a closed issue: the reason. */
+    reason?: string;
+    missing?: true;
+}
+/** The state of many issues in one GraphQL call (in chunks of 50). Repo names travel as variables, never in the query. */
+export declare function issueStates(cfg: {
+    token: string;
+    fetch?: Fetch;
+    api?: string;
+}, issues: {
+    repo: string;
+    number: number;
+}[]): Promise<IssueState[]>;
+/** GitHub's state onto the person's three: open, done (closed as completed), not planned (as not planned, or a duplicate). */
+export declare function issueStatus({ state, stateReason }: {
+    state: string | null;
+    stateReason?: string | null;
+}): 'open' | 'done' | 'not-planned';
+export interface FileSuggestionInput {
+    /** The report (redacted already, when the privacy catch asked for it). */
+    report: Draft;
+    compose?: Omit<ComposeOptions, 'attachmentUrls' | 'pending'>;
+    /** The bytes of the report's media and voice files, by the names the report gives them. */
+    files: AttachmentFile[];
+    attachments?: AttachmentHost;
+}
+export interface FiledSuggestion {
+    number: number;
+    url: string;
+    attached: Record<string, string>;
+    pending: string[]; /** How it was filed: with the filer's own token, or through a suggestion relay. */
+    via: 'direct' | 'relay';
+}
+/** Where to file: the repo, the filer's own token when they have one, and a relay for when that token cannot file there. */
+export type FilingConfig = Omit<GitHubConfig, 'token'> & {
+    token?: string;
+    relay?: RelayFiler; /** The app's id in the relay's own table, when filing through one. */
+    app?: string;
+};
+/** Saves the files the issue is still waiting for, then edits their links into the body. Call again later with the
+ *  same `attached` to finish what failed: the issue keeps saying a file is coming until it is there. */
+export declare function attachPending(cfg: GitHubConfig, input: FileSuggestionInput & {
+    number: number;
+    attached?: Record<string, string>;
+}): Promise<{
+    attached: Record<string, string>;
+    pending: string[];
+}>;
+/** The whole filing. With a token that can see the repo it files directly, in the order that never shows an incomplete
+ *  issue as complete: open the issue saying what is being added (opening it is the proof the filer can file there),
+ *  save each file against that issue, then edit the links in. With no token, or one that cannot see the repo, and a
+ *  `relay`, the relay files it (the files, then the issue, as its App) for someone with no access at all. */
+export declare function fileSuggestion(cfg: FilingConfig, input: FileSuggestionInput): Promise<FiledSuggestion>;