@drawcall/feedback 0.0.0-stage → 0.1.0

package/dist/browser/style.js

@@ -0,0 +1,214 @@
+/** Sets the game's `theme` on the shadow host, whose own style outranks the `:host` defaults. */
+export function paint(host, theme = {}) {
+    const tokens = {
+        "--font": theme.font,
+        "--background": theme.background,
+        "--glass": theme.surface,
+        "--text": theme.text,
+        "--accent": theme.accent,
+        "--on-accent": theme.onAccent,
+        "--radius": theme.radius === undefined ? undefined : `${theme.radius}px`,
+    };
+    for (const [name, value] of Object.entries(tokens))
+        if (value !== undefined)
+            host.style.setProperty(name, value);
+}
+/**
+ * Everything the SDK shows, kept flat: surfaces told apart by fill alone, one radius, one accent, and red only for
+ * recording. Dark by default; every quieter shade is mixed from `--text`, so any theme keeps its contrast steps. Three
+ * layers: the cover (the intro's and the closing screen's page), feedback mode over the game (a frame, a caption and
+ * the typing sheet), and the corner button on top.
+ */
+export const STYLE = `
+:host { all: initial;
+  --font: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; --mono: ui-monospace, "SF Mono", Menlo, monospace;
+  --text: #f5f5f7; --background: #121214; --glass: rgba(24, 24, 26, 0.92); --radius: 8px;
+  --accent: #fff; --on-accent: #111113; --record: #ff453a;
+  --muted: color-mix(in srgb, var(--text) 62%, transparent); --faint: color-mix(in srgb, var(--text) 50%, transparent);
+  --fill: color-mix(in srgb, var(--text) 8%, transparent); --raised: color-mix(in srgb, var(--text) 14%, transparent);
+  --ease: cubic-bezier(0.2, 0.8, 0.2, 1); }
+* { box-sizing: border-box; }
+[hidden] { display: none !important; }
+p { margin: 0; }
+:focus { outline: none; }
+:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+h1:focus-visible { outline: none; }
+kbd { display: inline-block; min-width: 1.6em; height: 1.6em; padding: 0 0.4em; margin: 0 0.1em; border-radius: 4px;
+  background: var(--raised); vertical-align: 0.05em; font: 500 0.85em/1.5em var(--mono); text-align: center; color: var(--text); }
+h1 kbd, .lines kbd { font-size: 0.65em; vertical-align: 0.2em; }
+input, textarea { display: block; width: 100%; margin: 0; padding: 0 12px; border: 0; border-radius: var(--radius);
+  background: var(--fill); color: var(--text); font: 400 16px/24px var(--font); }
+input { height: 48px; }
+textarea { padding: 12px; resize: none; }
+input:focus-visible, textarea:focus-visible { outline: 1.5px solid var(--muted); outline-offset: -1.5px; }
+::placeholder { color: var(--faint); }
+button { border: 0; font: 500 16px var(--font); color: var(--text); cursor: pointer; }
+button:disabled { opacity: 0.6; cursor: default; }
+.primary { height: 48px; padding: 0 28px; border-radius: var(--radius); background: var(--accent); color: var(--on-accent); font-weight: 600; }
+.secondary { height: 48px; padding: 0 20px; border-radius: var(--radius); background: var(--fill); }
+.secondary:hover { background: var(--raised); }
+/* A quiet text button; on Quest the one control on the cover its clicks reach. */
+.quiet { padding: 0; background: none; color: var(--muted); font: inherit; text-decoration: underline;
+  text-underline-offset: 3px; pointer-events: auto; }
+.quiet:hover { color: var(--text); }
+.dot { display: inline-block; width: 0.4em; height: 0.4em; margin-right: 0.35em; border-radius: 50%; background: var(--record);
+  vertical-align: 0.12em; animation: pulse 1.6s ease-in-out infinite; }
+@keyframes pulse { 50% { opacity: 0.55; } }
+@keyframes fade { from { opacity: 0; } }
+@keyframes slide { from { translate: -100%; } to { translate: 250%; } }
+@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation: none !important; transition: none !important; } }
+
+/* The cover: one calm, opaque page with a wide centred column of large type, while the game renders behind it. */
+.cover { position: fixed; inset: 0; z-index: 2147483646; display: flex; overflow-y: auto; overscroll-behavior: contain;
+  padding: max(48px, env(safe-area-inset-top)) max(24px, env(safe-area-inset-right)) max(48px, env(safe-area-inset-bottom))
+    max(24px, env(safe-area-inset-left));
+  background: var(--background); font: 400 16px/24px var(--font); color: var(--text); -webkit-font-smoothing: antialiased;
+  animation: fade 200ms var(--ease); }
+/* On Quest, clicks reach the game's Enter VR button, and its last step lets the game show through, dimmed. */
+.cover.through { pointer-events: none; }
+.cover.clear { background: color-mix(in srgb, var(--background) 72%, transparent); }
+.card { width: 100%; max-width: 680px; margin: auto; }
+.logo { display: block; max-width: 200px; max-height: 40px; margin-bottom: 32px; object-fit: contain; object-position: left; }
+h1 { margin: 0; font-size: 36px; line-height: 44px; font-weight: 600; letter-spacing: -0.02em; text-wrap: balance; }
+h2 { margin: 0 0 4px; font-size: 14px; line-height: 20px; font-weight: 500; color: var(--muted); }
+.lead { margin-top: 24px; font-size: 20px; line-height: 28px; text-wrap: pretty; }
+.meta { margin-top: 8px; color: var(--muted); }
+.brief, form { margin-top: 32px; }
+.cover .primary { min-width: 240px; }
+fieldset { display: grid; grid-template-columns: 1fr 1fr; gap: 12px 16px; min-width: 0; margin: 0 0 28px; padding: 0; border: 0; }
+legend { float: left; width: 100%; padding: 0; }
+label { display: grid; gap: 6px; min-width: 0; font-size: 14px; line-height: 20px; color: var(--muted); }
+.hint { grid-column: 1 / -1; margin: -12px 0 4px; }
+form > .quiet { display: block; margin-top: 16px; }
+.fine { margin-top: 16px; font-size: 14px; line-height: 20px; color: var(--faint); text-wrap: pretty; }
+.actions { display: flex; flex-wrap: wrap; align-items: center; gap: 12px 16px; margin-top: 28px; }
+/* A link to open on another device, in full so it can be read off and typed. */
+.url { display: flex; align-items: center; gap: 12px; margin-top: 28px; padding: 8px 8px 8px 16px; border-radius: var(--radius);
+  background: var(--fill); }
+.url .secondary { flex: none; height: 40px; }
+.url code { flex: 1; min-width: 0; overflow-wrap: anywhere; font: 400 14px/20px var(--mono); user-select: all; }
+
+/* The walkthrough: one miniature of the screen per step, the same size on every step, so the controls stay put. */
+.walk { display: grid; grid-template-rows: auto auto minmax(124px, auto) auto; gap: 24px; }
+.walk h1 { font-size: 28px; line-height: 36px; font-weight: 500; letter-spacing: -0.01em; text-wrap: pretty; }
+.progress, .controls { display: flex; flex-wrap: wrap; justify-content: space-between; gap: 8px 24px; font-size: 14px;
+  line-height: 20px; color: var(--muted); }
+.controls { justify-content: start; font-size: 16px; }
+.example { font-size: 12px; letter-spacing: 0.04em; text-transform: uppercase; color: var(--faint); }
+.note { margin-top: 8px; color: var(--muted); }
+.screen { position: relative; overflow: hidden; height: 168px; border-radius: var(--radius); background: var(--fill); }
+.screen.short { height: 84px; }
+.screen.framed { outline: 2px solid var(--faint); outline-offset: -2px; }
+.screen .lines { position: absolute; top: 16px; left: 50%; width: max-content; max-width: 160%; transform: translateX(-50%) scale(0.58);
+  transform-origin: top center; }
+.screen .lines p + p { font-size: 19px; }
+.screen .dock { position: absolute; right: 20px; bottom: 20px; transform: scale(1.5); transform-origin: bottom right; }
+.screen .sheet { position: absolute; inset: 16px 20%; display: grid; grid-template-rows: auto 1fr; gap: 8px; padding: 8px;
+  border-radius: var(--radius); background: var(--background); font: 400 11px/16px var(--font); color: var(--muted); }
+.screen .sheet div { display: flex; justify-content: space-between; }
+.screen .sheet b { font-size: 12px; color: var(--text); }
+.screen .sheet i { padding: 0 8px; border-radius: 4px; background: var(--accent); color: var(--on-accent); font-style: normal; }
+.screen .sheet span { border-radius: 4px; background: var(--fill); }
+.screen .keys ~ .sheet { left: 188px; right: 20px; }
+.keys { position: absolute; top: 20px; left: 20px; }
+.keys svg { display: block; height: 96px; }
+.keys rect { fill: var(--raised); }
+.keys text { fill: var(--muted); font: 500 10px var(--font); text-anchor: middle; }
+.keys .lit rect { fill: var(--accent); }
+.keys .lit text { fill: var(--on-accent); font: 600 13px var(--mono); }
+.screen.hands { display: flex; align-items: center; justify-content: center; gap: 32px; }
+.screen.hands img { height: 136px; }
+
+/* The closing screen: the game's questions, where a slider shows no value until touched, and the last word. */
+.questions { display: grid; gap: 28px; margin-bottom: 28px; }
+.question { display: grid; grid-template-columns: 1fr; gap: 10px; margin: 0; }
+.ask { display: flex; justify-content: space-between; gap: 16px; padding: 0; font-size: 16px; line-height: 24px; font-weight: 500;
+  color: var(--text); }
+.value { color: var(--accent); font-variant-numeric: tabular-nums; }
+input[type="range"] { height: 32px; padding: 0; background: none; accent-color: var(--accent); }
+input[type="range"].unset { opacity: 0.5; }
+.ends, .options { display: flex; flex-wrap: wrap; justify-content: space-between; gap: 8px 16px; font-size: 14px; color: var(--muted); }
+.options { justify-content: start; gap: 8px; }
+.option { position: relative; display: flex; align-items: center; height: 44px; padding: 0 16px; border-radius: var(--radius);
+  background: var(--fill); color: var(--text); font-size: 16px; cursor: pointer; }
+.option:has(:checked) { background: var(--accent); color: var(--on-accent); }
+.option:has(:focus-visible) { outline: 1.5px solid var(--muted); outline-offset: 2px; }
+.option input { position: absolute; inset: 0; height: 100%; opacity: 0; pointer-events: none; }
+.reply { border-radius: var(--radius); background: var(--fill); }
+.reply textarea { min-height: 112px; background: none; resize: vertical; }
+.voice { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; min-height: 112px; padding: 12px 16px;
+  font-variant-numeric: tabular-nums; }
+.voice > span { flex: 1; }
+.voice .secondary, .reply .record { height: 40px; background: var(--raised); }
+.reply .record { margin: 0 8px 8px auto; border-radius: var(--radius); display: flex; align-items: center; gap: 6px; padding: 0 12px; font-size: 14px; }
+.join { margin-top: 28px; max-width: 360px; }
+.status { margin-top: 12px; font-size: 14px; line-height: 20px; color: var(--muted); }
+
+/* Feedback mode: a frame round the viewport, light with a thin dark line inside to show over any scene, and a caption. */
+.mode { position: fixed; inset: 0; z-index: 2147483646; display: flex; flex-direction: column; align-items: center; gap: 8px;
+  padding: max(40px, env(safe-area-inset-top)) 48px 0; pointer-events: none; text-align: center; font: 400 16px/24px var(--font); color: var(--text);
+  transition: opacity 300ms var(--ease); animation: fade 180ms var(--ease); }
+.mode::before { content: ""; position: absolute; inset: 0; z-index: 1; border: 3px solid rgba(255, 255, 255, 0.85);
+  outline: 2px solid rgba(0, 0, 0, 0.6); outline-offset: -5px; }
+.mode.leaving { opacity: 0; }
+.lines { display: grid; justify-items: center; gap: 4px; max-width: 100%; padding: 12px 20px; border-radius: var(--radius);
+  background: var(--glass); -webkit-backdrop-filter: blur(20px); backdrop-filter: blur(20px); text-align: center; }
+.lines p:first-child { max-width: 800px; font: 600 28px/36px var(--font); letter-spacing: -0.01em; text-wrap: pretty; }
+.lines p + p { font: 400 16px/24px var(--font); color: var(--muted); }
+.tick { font-variant-numeric: tabular-nums; white-space: nowrap; }
+.lines p:first-child .tick { font-weight: 400; color: var(--muted); }
+.bar { position: relative; overflow: hidden; width: 120px; height: 3px; margin: 8px 0 4px; border-radius: 2px;
+  background: color-mix(in srgb, var(--text) 20%, transparent); }
+.bar::after { content: ""; position: absolute; inset: 0; width: 40%; border-radius: 2px; background: var(--text);
+  animation: slide 1.4s ease-in-out infinite; }
+.mode > .quiet { padding: 4px 8px; color: var(--text); font: 500 14px/20px var(--font); }
+/* The typing sheet: a card with a large field over the dimmed, paused game; it has the caption's words. */
+.mode:has(.sheet) > :not(.sheet) { display: none; }
+.sheet { position: fixed; inset: 0; display: flex; align-items: center; justify-content: center; padding: 24px;
+  background: color-mix(in srgb, var(--background) 60%, transparent); pointer-events: auto; text-align: left; }
+.mode .sheet > div { display: grid; gap: 12px; width: 100%; max-width: 640px; padding: 16px; border-radius: calc(var(--radius) * 1.5);
+  background: var(--background); }
+.head { display: grid; grid-template-columns: 1fr auto 1fr; align-items: center; gap: 12px; }
+.head h2 { margin: 0; font: 600 18px/24px var(--font); color: var(--text); }
+.head .quiet { justify-self: start; text-decoration: none; }
+.head .primary { justify-self: end; height: 40px; padding: 0 20px; }
+.sheet textarea { min-height: 40vh; }
+.foot { display: flex; flex-wrap: wrap; justify-content: space-between; gap: 8px 16px; font: 400 14px/20px var(--font); color: var(--muted); }
+/* A phone's sheet is edge to edge over the space the on-screen keyboard leaves. */
+.sheet.phone { bottom: auto; height: 100%; padding: 0; align-items: stretch; }
+.mode .sheet.phone > div { max-width: none; grid-template-rows: auto 1fr auto; border-radius: 0; padding: max(12px, env(safe-area-inset-top)) 16px 12px; }
+.sheet.phone textarea { min-height: 0; height: 100%; }
+
+/* The corner button, 16 px from the edges, over everything. */
+.dock { position: fixed; right: max(16px, env(safe-area-inset-right)); bottom: max(16px, env(safe-area-inset-bottom)); z-index: 2147483647; }
+.corner { position: relative; overflow: hidden; display: inline-flex; align-items: center; gap: 6px; height: 40px; padding: 0 8px 0 10px;
+  border-radius: var(--radius); background: var(--glass); -webkit-backdrop-filter: blur(20px); backdrop-filter: blur(20px);
+  font: 500 14px var(--font); white-space: nowrap; transition: transform 120ms var(--ease), background-color 120ms var(--ease); }
+.corner.touch { height: 48px; padding: 0 16px 0 12px; }
+.corner svg { flex: none; width: 20px; height: 20px; }
+.corner kbd { margin: 0 0 0 2px; }
+.corner:hover { background: color-mix(in srgb, var(--glass), var(--text) 8%); }
+.corner:active { transform: scale(0.96); }
+/* Over the cover's backdrop the glass would vanish; the walkthrough's last step lights it. */
+.corner.raised { background: var(--raised); }
+.corner.lit, .corner.lit:hover { background: var(--accent); color: var(--on-accent); }
+.corner.lit kbd { background: color-mix(in srgb, var(--on-accent) 10%, transparent); color: var(--on-accent); }
+.corner[aria-disabled="true"] > * { opacity: 0.35; }
+.corner[aria-label="Send recording"] svg { animation: pulse 1.6s ease-in-out infinite; }
+/* A hold fills the button from the left. */
+.corner::before { content: ""; position: absolute; inset: 0; background: color-mix(in srgb, var(--text) 20%, transparent);
+  transform-origin: left; transform: scaleX(var(--hold, 0)); pointer-events: none; }
+
+/* A phone gets the same pages in one column, with room at the bottom for the corner button. */
+@media (max-width: 560px) {
+  .cover { padding: max(32px, env(safe-area-inset-top)) 20px calc(max(16px, env(safe-area-inset-bottom)) + 72px); }
+  h1 { font-size: 28px; line-height: 36px; }
+  .walk h1, .lines p:first-child { font-size: 24px; line-height: 32px; }
+  .cover .primary { width: 100%; }
+  fieldset { grid-template-columns: 1fr; }
+  .walk { grid-template-rows: auto auto minmax(160px, auto) auto; }
+  .screen { height: 156px; }
+  .screen .dock { right: 12px; bottom: 12px; transform: scale(1.25); }
+  .mode { padding: max(64px, env(safe-area-inset-top)) 24px 0; }
+}
+`;

package/dist/browser/turn.d.ts

@@ -0,0 +1,23 @@
+import { type Kind } from "./input.ts";
+import type { Context } from "./run.ts";
+import type { Session } from "./session.ts";
+import type { View } from "./ui.ts";
+/** How long the player has to put a visual problem in view and press again. */
+export declare const SHOW_MS = 15000;
+/** Feedback mode's caption while recording, which the walkthrough's miniature shows word for word. */
+export declare function talking(kind: Kind, seconds: () => number): View;
+/** The ask to show it; `left` says how many seconds it has left. */
+export declare function asking(kind: Kind, left: () => number): View;
+/** Seconds as "m:ss". */
+export declare function clock(seconds: number): string;
+/**
+ * One piece of feedback, from the start press to its outcome, the same on every device. The start tone enters feedback
+ * mode, which stays through recording or typing, the wait for the classifier and the ask for a screenshot; a spoken
+ * "Thanks!" leaves it once feedback is sent, and a line with a low tone says why when nothing is. The game is paused
+ * until then. Uploads still running finish after `resume()`, and only a failure of theirs shows afterwards.
+ *
+ * On a flat screen a tester who chose typing gets the typing sheet, and so does one whose microphone is denied or
+ * broken; either can switch to the other way within the turn, which is remembered. In XR, without a microphone it ends
+ * at once.
+ */
+export declare function turn(ctx: Context, session: Session, kind: Kind): Promise<void>;

package/dist/browser/turn.js

@@ -0,0 +1,274 @@
+import { LIMITS } from "../service.js";
+import { act } from "./input.js";
+import { record } from "./mic.js";
+import { encode } from "./frame.js";
+import { advice, attach, Refused, submit } from "./server.js";
+import { after, sleep, wait } from "./wait.js";
+/** How long the player has to put a visual problem in view and press again. */
+export const SHOW_MS = 15_000;
+/**
+ * How long the game stays paused for the classifier after the player stops. Only a visual answer asks for a
+ * screenshot; without an answer by then the turn ends without one and the upload finishes in the background.
+ */
+const CLASSIFY_MS = 12_000;
+/** How long a screenshot may wait for the game's next frame. */
+const FRAME_MS = 2000;
+/** A stalled XR cue must not keep the app paused or prevent recording. */
+const CUE_MS = 12_000;
+/**
+ * What the tester sees and hears of each outcome, and for how long. XR shows nothing, so there `voice` says what the
+ * view would, in place of the tone.
+ */
+const OUTCOMES = {
+    stored: { view: { big: ["Thanks!"] }, ms: 1000, sound: "thanks" },
+    pending: { view: { big: ["Still sending"], small: ["You can keep playing while it finishes."] }, ms: 1000, voice: "sending" },
+    unheard: { view: { big: ["Didn't catch that"], small: ["Nothing was sent. Try again anytime."] }, ms: 2500, sound: "nothing", voice: "unheard" },
+    cancelled: { view: { big: ["Cancelled"], small: ["Nothing was sent."] }, ms: 1500, sound: "nothing" },
+    nomic: { ms: 0, sound: "failed", voice: "nomic" },
+    refused: { view: { big: ["Couldn't send"], small: [`Your feedback wasn't saved. ${advice(true, "try again")}`] }, ms: 2500, sound: "failed", voice: "failed" },
+    failed: { view: { big: ["Couldn't send"], small: [`Your feedback wasn't saved. ${advice(false, "try again")}`] }, ms: 2500, sound: "failed", voice: "failed" },
+};
+/** Feedback mode's caption while recording, which the walkthrough's miniature shows word for word. */
+export function talking(kind, seconds) {
+    // Only a keyboard has an Escape key; a phone sends or runs out the clock.
+    const cancel = kind === "key" ? [" · Esc to cancel"] : [];
+    return { big: ["Recording ", { tick: () => clock(seconds()) }], small: ["Describe what you noticed · ", ...act(kind, " to send", "Send"), ...cancel], recording: true };
+}
+/** The ask to show it; `left` says how many seconds it has left. */
+export function asking(kind, left) {
+    return {
+        big: ["Make sure it's in view, then ", ...act(kind, " again", "Take screenshot"), "."],
+        small: ["Sending without a screenshot in ", { tick: () => `${left()}s` }],
+    };
+}
+/** Seconds as "m:ss". */
+export function clock(seconds) {
+    const whole = Math.floor(seconds);
+    return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, "0")}`;
+}
+/**
+ * One piece of feedback, from the start press to its outcome, the same on every device. The start tone enters feedback
+ * mode, which stays through recording or typing, the wait for the classifier and the ask for a screenshot; a spoken
+ * "Thanks!" leaves it once feedback is sent, and a line with a low tone says why when nothing is. The game is paused
+ * until then. Uploads still running finish after `resume()`, and only a failure of theirs shows afterwards.
+ *
+ * On a flat screen a tester who chose typing gets the typing sheet, and so does one whose microphone is denied or
+ * broken; either can switch to the other way within the turn, which is remembered. In XR, without a microphone it ends
+ * at once.
+ */
+export async function turn(ctx, session, kind) {
+    const { ui, sounds, input, tester, frames, signal } = ctx;
+    const xr = ctx.options.renderer.xr.getSession();
+    /** In XR, where nothing shows, a voice line guides each step; it names the gesture of the input that started. */
+    const hand = xr && (kind === "controller" || kind === "hand") ? kind : null;
+    const state = session.pause();
+    const later = [];
+    /**
+     * Calls `run` once the XR session has ended, at once when it already has, as after a recording the end stopped. The
+     * turn then goes on without a screenshot, so the game resumes instead of staying paused for a player who left.
+     */
+    const exit = (run, over) => {
+        if (!xr)
+            return;
+        if (ctx.options.renderer.xr.getSession() !== xr)
+            return run();
+        xr.addEventListener("end", run, { signal: over });
+    };
+    const cue = () => {
+        sounds.play("start");
+        input.pulse(kind, 0.8, 80);
+    };
+    /** Records until a tap, a hidden tab, the end of the XR session or the recording's caps. Escape cancels on a keyboard. */
+    const speak = async () => {
+        const discard = new AbortController();
+        // Said before recording starts, so the recording doesn't pick it up; the start tone then marks the start.
+        if (hand) {
+            await wait(signal, (done, over) => {
+                sounds.clip(`speak-${hand}`, over).then(() => done(), error => {
+                    console.error("feedback: could not play the recording cue", error);
+                    done();
+                });
+                after(CUE_MS, () => {
+                    console.error("feedback: the recording cue timed out");
+                    done();
+                }, over);
+                exit(() => done(), over);
+            });
+            if (ctx.options.renderer.xr.getSession() !== xr)
+                return "cancelled";
+        }
+        const recording = await record(sounds.context, AbortSignal.any([signal, discard.signal]));
+        if (typeof recording === "string")
+            return recording;
+        // On a flat screen the cue came before, covering the permission prompt.
+        if (xr)
+            cue();
+        const seconds = () => (performance.now() - recording.since) / 1000;
+        ui.show(talking(kind, seconds));
+        ui.action("Send recording");
+        const end = await wait(signal, (done, over) => {
+            input.on(kind, () => done("stop"), over);
+            void recording.audio.then(() => done("stop"));
+            document.addEventListener("visibilitychange", () => {
+                if (document.hidden)
+                    done("stop");
+            }, { signal: over });
+            // With the pointer locked, the browser takes the first Escape to unlock it, and the next one reaches here.
+            if (kind === "key")
+                input.escape(() => done("cancel"), over);
+            if (!xr)
+                return ui.link("Type instead", () => done("type"), over);
+            exit(() => done("stop"), over);
+            // XR shows nothing, so ticks count down the last seconds.
+            const ticks = setInterval(() => {
+                if (LIMITS.seconds - seconds() <= 10)
+                    sounds.play("tick");
+            }, 1000);
+            over.addEventListener("abort", () => clearInterval(ticks));
+        }).finally(() => ui.action("Give feedback"));
+        if (end !== "stop") {
+            discard.abort();
+            return end === "cancel" ? "cancelled" : "type";
+        }
+        recording.stop();
+        return (await recording.audio) ?? "unheard";
+    };
+    /**
+     * Uploads what the player said or typed and waits for the classifier. Only feedback it calls visual asks for a
+     * screenshot, attached once taken; without one the Worker completes the item later.
+     */
+    const send = async (submission, audio) => {
+        const posted = submit(submission, audio, signal).catch((error) => {
+            if (!signal.aborted)
+                console.error("feedback: could not send", error);
+            return error instanceof Refused ? "refused" : "failed";
+        });
+        ui.show({ big: ["Got it, one moment…"], small: ["Everything is paused."], waiting: true });
+        ui.dim();
+        if (hand)
+            sounds.say("sending");
+        const answer = await wait(signal, (done, over) => {
+            void posted.then(done);
+            after(CLASSIFY_MS, () => done(null), over);
+            exit(() => done(null), over);
+        });
+        if (!answer) {
+            later.push(posted.then(outcomeOf));
+            return "pending";
+        }
+        if (typeof answer === "string" || answer.status === "empty" || !answer.visual)
+            return outcomeOf(answer);
+        const picture = await show();
+        // The item is stored either way; a lost screenshot only lacks the picture. Encoding can take seconds in XR, so it
+        // and the upload finish after the turn.
+        if (picture) {
+            encode(picture).then(jpeg => attach(submission.id, jpeg, signal)).catch((error) => {
+                if (!signal.aborted)
+                    console.error("feedback: could not attach the screenshot", error);
+            });
+        }
+        return "stored";
+    };
+    /** Asks the player to show what they mean, and takes the screenshot on their next press, or none after 15 s. */
+    const show = async () => {
+        const deadline = performance.now() + SHOW_MS;
+        ui.show(asking(kind, () => Math.max(0, Math.ceil((deadline - performance.now()) / 1000))));
+        ui.action("Take screenshot");
+        // Said on every device: in XR nothing else shows it, and on a flat screen it is easy to miss while playing.
+        sounds.say(hand ? `show-${hand}` : "show");
+        const tapped = await wait(signal, (done, over) => {
+            input.on(kind, () => done(true), over);
+            after(SHOW_MS, () => done(false), over);
+            exit(() => done(false), over);
+        }).finally(() => ui.action("Give feedback"));
+        if (!tapped)
+            return null;
+        ui.dim();
+        try {
+            const picture = await wait(signal, (done, over, fail) => {
+                frames.take(over).then(done, fail);
+                after(FRAME_MS, () => done(null), over);
+            });
+            if (!picture)
+                console.error("feedback: the experience rendered no frame to take the screenshot from");
+            return picture;
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            console.error("feedback: could not take the screenshot", error);
+            return null;
+        }
+    };
+    const give = async () => {
+        if (!xr)
+            cue();
+        let typing = !xr && tester.typing;
+        // Whether the microphone may still work, so the sheet offers it.
+        let speakable = true;
+        for (;;) {
+            if (typing) {
+                // Only flat inputs type: a gamepad stands in for the keyboard.
+                const typed = await ui.sheet(kind === "touch" ? "touch" : "key", speakable, signal);
+                if (typed === null)
+                    return "cancelled";
+                if (typed !== "speak")
+                    return send(session.item({ state, text: typed }), null);
+                tester.chooseTyping(false);
+                typing = false;
+                cue();
+                continue;
+            }
+            const spoken = await speak();
+            if (spoken === "denied" || spoken === "broken") {
+                if (xr)
+                    return "nomic";
+                [typing, speakable] = [true, false];
+            }
+            else if (spoken === "type") {
+                tester.chooseTyping(true);
+                typing = true;
+            }
+            else {
+                return spoken instanceof Blob ? send(session.item({ xr, state }), spoken) : spoken;
+            }
+        }
+    };
+    ui.busy = true;
+    try {
+        const outcome = await give();
+        tell(ctx, outcome, false, hand !== null);
+        await sleep(OUTCOMES[outcome].ms, signal);
+    }
+    finally {
+        ui.busy = false;
+        ui.leave();
+        ui.action("Give feedback");
+        ctx.options.resume?.();
+    }
+    // A pending upload's outcome shows unless a newer turn holds the screen; failures are also logged when sent.
+    for (const upload of later) {
+        void upload.then(outcome => {
+            if (!signal.aborted && !ui.busy)
+                tell(ctx, outcome, true, hand !== null);
+        });
+    }
+}
+/** Shows and sounds the outcome; `spoken` says it in words where the view isn't seen. */
+function tell({ ui, sounds }, outcome, flash, spoken) {
+    const { view, ms, sound, voice } = OUTCOMES[outcome];
+    if (view && flash)
+        ui.flash(view, ms);
+    else if (view)
+        ui.show(view);
+    if (sound === "thanks")
+        sounds.say("thanks");
+    else if (spoken && voice)
+        sounds.say(voice);
+    else if (sound)
+        sounds.play(sound);
+}
+function outcomeOf(answer) {
+    if (typeof answer === "string")
+        return answer;
+    return answer.status === "empty" ? "unheard" : "stored";
+}

package/dist/browser/ui.d.ts

@@ -0,0 +1,88 @@
+import type { Theme } from "../index.ts";
+import type { Device } from "./device.ts";
+import { type Press } from "./input.ts";
+/** A line of text; `{ key }` renders as a key cap, and `{ tick }` as text redrawn every 250 ms, such as a countdown. */
+export type Text = (string | {
+    key: string;
+} | {
+    tick: () => string;
+})[];
+/** What feedback mode shows: a big line and a small one, with a red dot while recording or a bar while waiting. */
+export interface View {
+    big: Text;
+    small?: Text;
+    recording?: true;
+    waiting?: true;
+}
+/** What a press of the corner button does at the moment, as its label tells screen readers and its face shows. */
+export type Action = "Give feedback" | "Send recording" | "Take screenshot";
+/** The typing sheet's heading. */
+export declare const PROMPT = "What feels off?";
+type Child = Node | string | null;
+/** An element with `props` and `children`; null children are left out. */
+export declare function h<K extends keyof HTMLElementTagNameMap>(tag: K, props?: Partial<HTMLElementTagNameMap[K]>, ...children: Child[]): HTMLElementTagNameMap[K];
+export declare const kbd: (key: string) => HTMLElement;
+export declare const button: (className: string, label: string) => HTMLButtonElement;
+/** The corner button's face: a glyph, what a press does, and on a keyboard the key that does it. */
+export declare function face(kind: Press, action: Action): string;
+/**
+ * Puts the lines of `view` on a plate; `ticks` collects what redraws their `{ tick }` parts, which screen readers skip
+ * since feedback mode's plate announces every change.
+ */
+export declare function plate({ big, small, recording, waiting }: View, ticks?: (() => void)[], lines?: HTMLDivElement): HTMLElement;
+/**
+ * Everything the SDK shows, in one shadow root on the page: the cover, feedback mode and the corner button. DOM only,
+ * so never in the screenshot, which is drawn from the canvas; in XR none of it is visible and sounds carry the flow.
+ * Keys and presses inside it don't reach the game, so one that locks the pointer or shoots on a click doesn't take them
+ * too; the SDK's own window capture listeners still see them. Releases still reach the game, so nothing held when it
+ * appeared stays stuck down. Gone on abort.
+ */
+export declare class Ui {
+    #private;
+    readonly root: ShadowRoot;
+    readonly theme: Theme;
+    /** Whether a turn holds the screen, whose captions and sounds an earlier turn's late outcome must leave alone. */
+    busy: boolean;
+    /** The corner button's clicks call `press` with the input they count as. */
+    constructor(device: Device, press: (kind: Press) => void, theme: Theme | undefined, signal: AbortSignal);
+    /** Shows `view` in feedback mode, entering it if needed. */
+    show(view: View): void;
+    /** Shows `view` for `ms`, then leaves, unless something else shows first. */
+    flash(view: View, ms: number): void;
+    /** Fades out, which ends feedback mode on screen. */
+    leave(): void;
+    /** A link under the caption that switches how feedback is given, such as "Type instead", until `signal` aborts. */
+    link(label: string, run: () => void, signal: AbortSignal): void;
+    /** Hides the corner button while something else takes the screen, raises it over the cover, or lights it up. */
+    corner(look: "hidden" | "shown" | "raised" | "lit"): void;
+    action(label: Action): void;
+    /** Dims the corner button while a press does nothing, until the next `action`. */
+    dim(): void;
+    /** A hold's progress, 0 to 1, filling the corner button. Without one, only the hold's sound shows it. */
+    hold(progress: number): void;
+    /**
+     * The typing sheet, in feedback mode's frame with the corner button hidden behind it. Resolves with the text on Send,
+     * with "speak" for "Speak instead" when `speakable`, and with null on Cancel, Escape, or the feedback key in an empty
+     * field. On a keyboard Enter sends and Shift+Enter starts a new line; on a phone Enter is a new line, and the sheet
+     * fills the space above the on-screen keyboard.
+     */
+    sheet(kind: Press, speakable: boolean, signal: AbortSignal): Promise<string | "speak" | null>;
+    /** A full-screen cover, under the corner button, until disposed. */
+    cover(): Cover;
+}
+/**
+ * The page of the intro and the closing screen: a modal dialog until released, while the game keeps rendering behind
+ * it. Opening it gives back the pointer a game's mouse look holds, and leaves a fullscreen canvas, which would hide it.
+ */
+export declare class Cover {
+    #private;
+    constructor(ui: Ui);
+    /** Replaces the page, under the game's logo unless `bare`, and focuses its heading, which names the dialog. */
+    show(nodes: Node[], bare?: boolean): void;
+    /** Stops being modal, so focus and screen readers reach what lies outside, such as the corner button. */
+    release(): void;
+    /** Lets clicks through to the game, and with `clear` lets it show through, dimmed. */
+    through(clear?: boolean): void;
+    dispose(): void;
+}
+export {};