@drawcall/feedback 0.0.0-stage → 0.1.0

package/dist/browser/intro.js

@@ -0,0 +1,172 @@
+import { LIMITS } from "../service.js";
+import { phrase, targeted } from "./device.js";
+import { close, openMic } from "./mic.js";
+import { findReviewer } from "./server.js";
+import { Session } from "./session.js";
+import { button, h } from "./ui.js";
+import { wait } from "./wait.js";
+import { walkthrough } from "./walkthrough.js";
+/** What a tester's email is for, wherever they may leave it. A sign-up hears of new versions once they play its link. */
+export const EMAIL_USE = "Leave an email to get your own link for new versions, and for questions about your feedback.";
+/**
+ * The full-screen cover on every load in feedback mode. On a device the playtest isn't for, it first says which
+ * devices it is for, so the tester can switch or go on anyway. The invite says what the player is asked to do and why,
+ * and takes optional details; Start, or entering VR, starts the session, then asks for the microphone and lets sound
+ * play. The walkthrough then shows how feedback works on this device. A microphone that fails counts as none, so the
+ * walkthrough teaches typing instead. A broken intro must not cost the playtest its feedback, so it is logged, and the
+ * session starts anyway.
+ */
+export async function intro(ctx, version) {
+    const { options, tester, ui, signal } = ctx;
+    const cover = ui.cover();
+    const failed = (error) => {
+        if (signal.aborted)
+            throw error;
+        console.error("feedback: the intro failed", error);
+        return false;
+    };
+    // The invite has its own button; the walkthrough brings the corner button back.
+    ui.corner("hidden");
+    try {
+        const started = await welcome(ctx, cover).catch(failed);
+        const session = new Session(options, tester, version, signal);
+        if (started)
+            await teach(ctx, cover).catch(failed);
+        return session;
+    }
+    finally {
+        cover.dispose();
+        ui.corner("shown");
+    }
+}
+/** Resolves with true once the tester presses Start, or with false once they enter VR, as Quest Browser can on its own. */
+async function welcome(ctx, cover) {
+    const { devices } = ctx.options;
+    if (devices?.length && !(await targeted(devices, ctx.device)))
+        await notice(ctx, cover, phrase(devices));
+    const form = invite(ctx, cover, await known(ctx));
+    return wait(ctx.signal, (done, over) => {
+        form.addEventListener("submit", () => done(true), { signal: over });
+        entered(ctx, () => done(false), over);
+    });
+}
+/** The walkthrough for how the tester gives feedback. One who chose typing is never asked for the microphone. */
+async function teach(ctx, cover) {
+    const { typing } = ctx.tester;
+    const mic = typing ? null : await openMic(ctx.signal);
+    if (mic instanceof MediaStream)
+        close(mic);
+    ctx.ui.corner("raised");
+    const means = mic instanceof MediaStream ? "speak" : typing ? "type" : "nomic";
+    await walkthrough(ctx, cover, means, (run, over) => entered(ctx, run, over));
+}
+/**
+ * The invite, written for someone who only clicked a link: what is asked of them, the game's `task`, the optional
+ * details, Start, and what's recorded. A known reviewer is greeted by name and asked for no details; anyone else is
+ * asked only when the project takes sign-ups, and leaving an email makes them a reviewer. Returns its form, whose
+ * submit starts.
+ */
+function invite({ options, tester, device, project }, cover, greeted) {
+    const { minutes, task } = options;
+    const length = minutes ? `About ${minutes} minute${minutes === 1 ? "" : "s"}` : null;
+    // The project's name joins it once the service confirms the key.
+    const meta = h("p", { className: "meta", hidden: !length }, length ?? "");
+    const name = h("input", { name: "name", autocomplete: "name", maxLength: LIMITS.name, value: tester.name ?? "" });
+    const contact = h("input", { name: "email", type: "email", autocomplete: "email", maxLength: LIMITS.contact, value: tester.contact ?? "" });
+    const start = h("button", { className: "primary", type: "submit" }, "Allow mic & start");
+    // With the microphone already allowed there is nothing to allow or wait for.
+    let granted = false;
+    void allowed().then(yes => {
+        granted = yes;
+        if (yes && !start.disabled)
+            start.textContent = "Start";
+    });
+    // Shown once the project says it takes sign-ups.
+    const details = greeted ? null : h("fieldset", { hidden: true }, h("legend", {}, h("h2", {}, "Your details (optional)")), h("p", { className: "hint" }, EMAIL_USE), h("label", {}, "Your name", name), h("label", {}, "Your email", contact));
+    void project.then(found => {
+        if (!found)
+            return;
+        meta.textContent = length ? `${found.name} · ${length}` : found.name;
+        meta.hidden = false;
+        if (details)
+            details.hidden = !found.signup;
+    });
+    // VR has only speaking, so Quest's invite doesn't offer typing.
+    const type = device === "quest" ? null : h("button", { className: "quiet", type: "submit" }, "Start without mic, type instead");
+    const recorded = `Only your voice between ${device === "phone" ? "taps" : "presses"} is recorded, plus a screenshot when asked.`;
+    // Playing through a link signs a reviewer up for new-version emails, so they read it before they start. An id this
+    // browser holds from a sign-up signs up nobody: only its invitation's link does.
+    const emails = greeted && tester.linked ? "By starting, you'll get an email when a new version is ready. Each one has a link to stop them." : null;
+    const form = h("form", {}, details, start, type, h("p", { className: "fine" }, recorded), emails ? h("p", { className: "fine" }, emails) : null);
+    const lead = "Start for a short spoken guide, then try it out and say what you notice.";
+    cover.show([
+        h("h1", {}, greeted ? (tester.name ? `Hello, ${tester.name}` : "Hello again") : "You've been invited to give feedback"),
+        meta,
+        h("p", { className: "lead" }, greeted ? `You've been invited to give feedback. ${lead}` : lead),
+        ...(task ? [h("div", { className: "brief" }, h("h2", {}, "Your task"), h("p", {}, task))] : []),
+        form,
+    ]);
+    // Never a native submit, which would reload the page; disabled buttons also end double clicks and Enter.
+    form.addEventListener("submit", event => {
+        event.preventDefault();
+        const typed = event.submitter !== null && event.submitter === type;
+        if (type)
+            tester.chooseTyping(typed);
+        start.disabled = true;
+        if (type)
+            type.disabled = true;
+        if (!granted && !typed)
+            start.textContent = "Waiting for microphone…";
+        if (details && !details.hidden)
+            tester.enter(name.value, contact.value);
+    });
+    return form;
+}
+/** Whether the tester is a reviewer the service knows, whose stored name then stands for theirs. */
+async function known({ options, tester }) {
+    if (!tester.reviewer)
+        return false;
+    try {
+        const reviewer = await findReviewer(options.project, tester.reviewer);
+        tester.found(reviewer);
+        return reviewer !== null;
+    }
+    catch (error) {
+        // The service checks the id again when the session starts; until then the tester is greeted like anyone.
+        console.error("feedback: could not check the reviewer", error);
+        return false;
+    }
+}
+/**
+ * Resolves once the tester chooses to go on, on a device the playtest isn't for. The link, which a reviewer's names
+ * them in, is the easiest way to the right device, so it is shown in full and can be copied.
+ */
+async function notice({ signal }, cover, devices) {
+    const copy = button("secondary", "Copy link");
+    copy.addEventListener("click", () => {
+        navigator.clipboard.writeText(location.href).then(() => (copy.textContent = "Copied"), 
+        // Without clipboard access the link stays selectable.
+        error => console.error("feedback: could not copy the link", error));
+    });
+    const go = button("quiet", "Continue on this device");
+    cover.show([
+        h("h1", {}, `This test is for ${devices}`),
+        h("p", { className: "lead" }, `Testing is focused on ${devices} right now, and this looks like a different device. If you can, open this link there instead.`),
+        h("div", { className: "url" }, h("code", {}, location.href), copy),
+        h("div", { className: "actions" }, go),
+    ]);
+    await wait(signal, (done, over) => go.addEventListener("click", () => done(undefined), { signal: over }));
+}
+/** Whether the microphone is already allowed. Safari and Firefox may not answer for it, which counts as no. */
+async function allowed() {
+    const status = await navigator.permissions.query({ name: "microphone" }).catch(() => null);
+    return status?.state === "granted";
+}
+/** Calls `run` when an XR session starts, at once when one already has, as during the microphone prompt. */
+function entered({ options }, run, signal) {
+    const xr = options.renderer.xr;
+    if (xr.isPresenting)
+        return run();
+    xr.addEventListener("sessionstart", run);
+    signal.addEventListener("abort", () => xr.removeEventListener("sessionstart", run), { once: true });
+}

package/dist/browser/mic.d.ts

@@ -0,0 +1,20 @@
+/** Why there is no microphone: the player denied it or has none, or it is broken, which is logged. */
+export type NoMic = "denied" | "broken";
+export interface Recording {
+    /** When it started, on `performance.now()`'s clock. */
+    since: number;
+    /**
+     * Resolves once it stopped: by `stop()`, at the time or size cap, so a long take is sent shortened rather than
+     * refused, or when the microphone went away. Null when the level never reached speech.
+     */
+    audio: Promise<Blob | null>;
+    stop(): void;
+}
+/**
+ * Opens the microphone. Close it right after use: a stream left open makes iOS lower and reroute the game's audio.
+ * Rejects at once when `signal` aborts, even during the permission prompt; a stream granted later is closed.
+ */
+export declare function openMic(signal: AbortSignal): Promise<MediaStream | NoMic>;
+export declare function close(stream: MediaStream): void;
+/** Records the microphone until stopped; aborting `signal` stops it too, and the microphone closes either way. */
+export declare function record(context: AudioContext, signal: AbortSignal): Promise<Recording | NoMic>;

package/dist/browser/mic.js

@@ -0,0 +1,98 @@
+import { LIMITS } from "../service.js";
+import { wait } from "./wait.js";
+/** RMS that counts as speech, and how many 50 ms samples in a row must reach it. Below that, nothing was heard. */
+const SPEECH = 0.02;
+const SPEECH_SAMPLES = 4;
+const FORMATS = ["audio/webm;codecs=opus", "audio/mp4"];
+/** Room left below the audio cap for what the recorder still buffers when it stops; it hands over data every second. */
+const MARGIN = 64 * 1024;
+/**
+ * Opens the microphone. Close it right after use: a stream left open makes iOS lower and reroute the game's audio.
+ * Rejects at once when `signal` aborts, even during the permission prompt; a stream granted later is closed.
+ */
+export async function openMic(signal) {
+    // Async, so that an insecure page, which has no `mediaDevices`, rejects like any other failure.
+    const asked = (async () => navigator.mediaDevices.getUserMedia({ audio: true }))();
+    try {
+        return await wait(signal, (done, _, fail) => void asked.then(done, fail));
+    }
+    catch (error) {
+        if (signal.aborted) {
+            asked.then(close, () => { });
+            throw error;
+        }
+        if (error instanceof DOMException && (error.name === "NotAllowedError" || error.name === "NotFoundError"))
+            return "denied";
+        console.error("feedback: the microphone failed", error);
+        return "broken";
+    }
+}
+export function close(stream) {
+    for (const track of stream.getTracks())
+        track.stop();
+}
+/** Records the microphone until stopped; aborting `signal` stops it too, and the microphone closes either way. */
+export async function record(context, signal) {
+    const stream = await openMic(signal);
+    if (typeof stream === "string")
+        return stream;
+    try {
+        return start(context, stream, signal);
+    }
+    catch (error) {
+        // Such as Firefox, whose analyser refuses a microphone at another sample rate than the AudioContext.
+        close(stream);
+        console.error("feedback: could not record the microphone", error);
+        return "broken";
+    }
+}
+function start(context, stream, signal) {
+    const mimeType = FORMATS.find(format => MediaRecorder.isTypeSupported(format));
+    if (!mimeType)
+        throw new Error("feedback: this browser can record neither webm/opus nor mp4");
+    const recorder = new MediaRecorder(stream, { mimeType, audioBitsPerSecond: 32_000 });
+    const stop = () => recorder.state !== "inactive" && recorder.stop();
+    const chunks = [];
+    let bytes = 0;
+    recorder.addEventListener("dataavailable", event => {
+        chunks.push(event.data);
+        bytes += event.data.size;
+        if (bytes >= LIMITS.audio - MARGIN)
+            stop();
+    });
+    const source = context.createMediaStreamSource(stream);
+    const analyser = new AnalyserNode(context, { fftSize: 2048 });
+    source.connect(analyser);
+    const samples = new Float32Array(analyser.fftSize);
+    // Without a running AudioContext there is no level, so the service decides whether anything was said.
+    let measured = false;
+    let heard = false;
+    let loud = 0;
+    const meter = setInterval(() => {
+        if (context.state !== "running")
+            return;
+        measured = true;
+        analyser.getFloatTimeDomainData(samples);
+        loud = rms(samples) >= SPEECH ? loud + 1 : 0;
+        heard ||= loud >= SPEECH_SAMPLES;
+    }, 50);
+    const cap = setTimeout(stop, LIMITS.seconds * 1000);
+    signal.addEventListener("abort", stop, { once: true });
+    const audio = new Promise(resolve => {
+        recorder.addEventListener("stop", () => {
+            clearTimeout(cap);
+            clearInterval(meter);
+            source.disconnect();
+            close(stream);
+            resolve(heard || !measured ? new Blob(chunks, { type: mimeType }) : null);
+        }, { once: true });
+    });
+    recorder.start(1000);
+    return { since: performance.now(), audio, stop };
+}
+function rms(samples) {
+    let sum = 0;
+    for (const sample of samples)
+        sum += sample * sample;
+    return Math.sqrt(sum / samples.length);
+}

package/dist/browser/pictures/LICENSE

@@ -0,0 +1,24 @@
+controller.webp is rendered from the Meta Quest Touch Plus left controller model in
+@webxr-input-profiles/assets 1.0.20 (https://github.com/immersive-web/webxr-input-profiles), under this licence:
+
+MIT License
+
+Copyright (c) 2019 Amazon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice (including the next
+paragraph) shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
+OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/browser/run.d.ts

@@ -0,0 +1,32 @@
+import type { PublicProject } from "../api.ts";
+import type { FeedbackOptions } from "../index.ts";
+import type { Tester } from "../tester.ts";
+import { type Device } from "./device.ts";
+import { Frames } from "./frame.ts";
+import { Input } from "./input.ts";
+import { Sounds } from "./sounds.ts";
+import { Ui } from "./ui.ts";
+/** What the intro, the turns and the ending work with. `signal` aborts on dispose. */
+export interface Context {
+    options: FeedbackOptions;
+    tester: Tester;
+    device: Device;
+    signal: AbortSignal;
+    input: Input;
+    ui: Ui;
+    sounds: Sounds;
+    frames: Frames;
+    /** What testers see of the project, or null when the key is invalid or the check failed; both are logged. */
+    project: Promise<Pick<PublicProject, "name" | "signup"> | null>;
+}
+/**
+ * Feedback mode, loaded only when it is on: the intro, feedback turns until the game calls `finish()`, then the ending.
+ * `version`: the build being tested, if known.
+ */
+export declare function run({ options, tester, version, finished, signal }: {
+    options: FeedbackOptions;
+    tester: Tester;
+    version: string | null;
+    finished: Promise<void>;
+    signal: AbortSignal;
+}): Promise<void>;

package/dist/browser/run.js

@@ -0,0 +1,78 @@
+import { detect } from "./device.js";
+import { ending } from "./ending.js";
+import { Frames } from "./frame.js";
+import { Input, learnHotkey } from "./input.js";
+import { intro } from "./intro.js";
+import { checkProject } from "./server.js";
+import { Sounds } from "./sounds.js";
+import { turn } from "./turn.js";
+import { Ui } from "./ui.js";
+import { wait } from "./wait.js";
+/**
+ * Feedback mode, loaded only when it is on: the intro, feedback turns until the game calls `finish()`, then the ending.
+ * `version`: the build being tested, if known.
+ */
+export async function run({ options, tester, version, finished, signal }) {
+    if (signal.aborted)
+        return;
+    const project = checkProject(options.project).catch(error => {
+        console.error("feedback: could not check the project key", error);
+        return null;
+    });
+    await learnHotkey();
+    const device = detect();
+    const input = new Input(signal);
+    const sounds = new Sounds(signal);
+    const ui = new Ui(device, kind => input.corner(kind), options.theme, signal);
+    // A hold fills the corner button, with a rising tone and a pulse at each fifth.
+    let fifth = 0;
+    input.onHold = (kind, progress) => {
+        ui.hold(progress);
+        const next = Math.floor(progress * 5);
+        if (next > fifth) {
+            sounds.hold(progress);
+            input.pulse(kind, 0.3, 20);
+        }
+        fifth = next;
+    };
+    // The first time each XR input shows up in this browser, outside a turn, a voice line explains its hold.
+    const hinted = new Set();
+    const frames = new Frames(options.renderer, frame => {
+        input.poll(frame);
+        const hand = input.hand;
+        if (!hand || ui.busy || hinted.has(hand))
+            return;
+        hinted.add(hand);
+        if (tester.firstHint(hand))
+            sounds.say(`hold-${hand}`);
+    }, signal);
+    const ctx = { options, tester, device, signal, input, ui, sounds, frames, project };
+    try {
+        const session = await intro(ctx, version);
+        for (;;) {
+            const kind = await wait(signal, (done, over) => {
+                input.on(null, done, over);
+                void finished.then(() => done(null));
+            });
+            if (!kind)
+                break;
+            try {
+                await turn(ctx, session, kind);
+            }
+            catch (error) {
+                if (signal.aborted)
+                    throw error;
+                // One broken turn shouldn't end feedback for the rest of the playtest. Send failures end the turn themselves.
+                console.error("feedback:", error);
+                ui.flash({ big: ["Something went wrong"], small: ["Your feedback may not have been saved."] }, 2500);
+                sounds.play("failed");
+            }
+        }
+        session.finish();
+        await ending(ctx, session);
+    }
+    catch (error) {
+        if (!signal.aborted)
+            throw error;
+    }
+}

package/dist/browser/server.d.ts

@@ -0,0 +1,22 @@
+import type { Answer, PublicProject, PublicReviewer, StartSession, Submission, Submitted } from "../api.ts";
+/** A request that can't succeed however often it is sent: the server refused it, or it breaks a limit. */
+export declare class Refused extends Error {
+}
+/** What the tester can do after a send failed: nothing when it was `refused`, else check their connection and `retry`. */
+export declare function advice(refused: boolean, retry: string): string;
+/** Logs which project the key belongs to, so a wrong key shows on load, and resolves with what testers see of it. */
+export declare function checkProject(key: string): Promise<Pick<PublicProject, "name" | "signup"> | null>;
+/** Who a reviewer link greets; null when `project` has no such reviewer, such as one who stopped the emails. */
+export declare function findReviewer(project: string, id: string): Promise<Pick<PublicReviewer, "name"> | null>;
+export declare function submit(submission: Submission, audio: Blob | null, signal: AbortSignal): Promise<Submitted>;
+/** Sent only after `submit` succeeded, so the item exists. */
+export declare function attach(id: string, jpeg: Blob, signal: AbortSignal): Promise<void>;
+/** Starts a session; resolves with the tester's reviewer id when they play through their own link, else null. */
+export declare function startSession(start: StartSession, signal: AbortSignal): Promise<string | null>;
+/** Signs the session's tester up as a reviewer. The answer's id is a placeholder: their own link comes by email. */
+export declare function joinReviewers(session: string, email: string, signal: AbortSignal): Promise<void>;
+export declare function storeAnswers(session: string, answers: Answer[], signal: AbortSignal): Promise<void>;
+/** Marks the session finished; it outlives the page, since the game may navigate away right after. */
+export declare function finishSession(session: string): Promise<void>;
+/** Marks the session seen from a page being hidden; without a body it needs no CORS preflight, which it can't wait for. */
+export declare function seeSession(session: string): Promise<void>;

package/dist/browser/server.js

@@ -0,0 +1,147 @@
+import { LIMITS, ORIGIN } from "../service.js";
+/** Vite dev can point the SDK at a local Worker. */
+const origin = (import.meta.env?.DEV && import.meta.env.VITE_DRAWCALL_FEEDBACK_URL) || ORIGIN;
+/** Pauses between the first attempts, then `PAUSE_MS` until the time runs out. */
+const PAUSES = [1000, 3000];
+const PAUSE_MS = 6000;
+/** One attempt may take this long, since the POST transcribes within its request. */
+const ATTEMPT_MS = 30_000;
+/** Attempts stop starting after this long. The player is already playing again, so it can be generous. */
+const TOTAL_MS = 60_000;
+/** The checks on load don't retry; the intro goes on without them. */
+const CHECK_MS = 8000;
+/** A request that can't succeed however often it is sent: the server refused it, or it breaks a limit. */
+export class Refused extends Error {
+}
+/** What the tester can do after a send failed: nothing when it was `refused`, else check their connection and `retry`. */
+export function advice(refused, retry) {
+    return refused ? "It was refused, so sending it again won't help." : `Check your connection and ${retry}.`;
+}
+/** Logs which project the key belongs to, so a wrong key shows on load, and resolves with what testers see of it. */
+export async function checkProject(key) {
+    const response = await fetch(url(`/projects/${encodeURIComponent(key)}/public`), { signal: AbortSignal.timeout(CHECK_MS) });
+    const text = await response.text();
+    if (!response.ok) {
+        console.error(`feedback: invalid project key "${key}" (${message(response.status, text)})`);
+        return null;
+    }
+    const { name, signup } = parse(text);
+    if (typeof name !== "string" || typeof signup !== "boolean")
+        throw unexpected(text);
+    console.info(`feedback: project ${name}`);
+    return { name, signup };
+}
+/** Who a reviewer link greets; null when `project` has no such reviewer, such as one who stopped the emails. */
+export async function findReviewer(project, id) {
+    const response = await fetch(url(`/reviewers/${encodeURIComponent(id)}`), { signal: AbortSignal.timeout(CHECK_MS) });
+    if (response.status === 404)
+        return null;
+    const text = await response.text();
+    if (!response.ok)
+        throw new Error(`feedback: ${message(response.status, text)}`);
+    const body = parse(text);
+    if (typeof body.project !== "string" || !isName(body.name))
+        throw unexpected(text);
+    return body.project === project ? { name: body.name } : null;
+}
+export async function submit(submission, audio, signal) {
+    if (audio && audio.size > LIMITS.audio)
+        throw new Refused(`feedback: the recording is ${audio.size} bytes, over the ${LIMITS.audio} byte cap`);
+    const body = new FormData();
+    body.append("meta", JSON.stringify(submission));
+    if (audio)
+        body.append("audio", audio, audio.type.startsWith("audio/mp4") ? "audio.mp4" : "audio.webm");
+    const text = await send("/items", { method: "POST", body }, signal);
+    const { status, n, visual } = parse(text);
+    if (status === "empty")
+        return { status };
+    if (status !== "stored" || typeof n !== "number" || typeof visual !== "boolean")
+        throw unexpected(text);
+    return { status, n, visual };
+}
+/** Sent only after `submit` succeeded, so the item exists. */
+export async function attach(id, jpeg, signal) {
+    await send(`/items/${id}/screenshot`, { method: "PUT", body: jpeg, headers: { "content-type": "image/jpeg" } }, signal);
+}
+/** Starts a session; resolves with the tester's reviewer id when they play through their own link, else null. */
+export async function startSession(start, signal) {
+    const text = await post("/sessions", start, signal);
+    const { reviewer } = parse(text);
+    if (!isName(reviewer))
+        throw unexpected(text);
+    return reviewer;
+}
+/** Signs the session's tester up as a reviewer. The answer's id is a placeholder: their own link comes by email. */
+export async function joinReviewers(session, email, signal) {
+    await post(`/sessions/${session}/join`, { email }, signal);
+}
+export async function storeAnswers(session, answers, signal) {
+    await post(`/sessions/${session}/answers`, { answers }, signal);
+}
+/** Marks the session finished; it outlives the page, since the game may navigate away right after. */
+export async function finishSession(session) {
+    await send(`/sessions/${session}/finish`, { method: "POST", keepalive: true });
+}
+/** Marks the session seen from a page being hidden; without a body it needs no CORS preflight, which it can't wait for. */
+export async function seeSession(session) {
+    await send(`/sessions/${session}/seen`, { method: "POST", keepalive: true });
+}
+function url(path) {
+    return `${origin}/api/v1${path}`;
+}
+function post(path, body, signal) {
+    return send(path, { method: "POST", body: JSON.stringify(body), headers: { "content-type": "application/json" } }, signal);
+}
+/**
+ * Retries network errors, timeouts and server-side failures, and resolves with the body of the answer. Safe because
+ * everything sent carries a client-made id. The body is read inside the attempt, so its timeout covers it too. Throws
+ * `Refused` for a 4xx answer, and the last failure once the time is up.
+ */
+async function send(path, init, signal) {
+    const deadline = performance.now() + TOTAL_MS;
+    for (let i = 0;; i++) {
+        let failure;
+        try {
+            const timeout = AbortSignal.timeout(Math.min(ATTEMPT_MS, deadline - performance.now()));
+            const response = await fetch(url(path), { ...init, signal: signal ? AbortSignal.any([signal, timeout]) : timeout });
+            const text = await response.text();
+            if (response.ok)
+                return text;
+            const error = `feedback: ${message(response.status, text)}`;
+            if (response.status < 500 && response.status !== 429)
+                throw new Refused(error);
+            failure = new Error(error);
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            // fetch rejects with a TypeError when the network fails, and a TimeoutError when the attempt ran out of time.
+            if (!(error instanceof TypeError || (error instanceof DOMException && error.name === "TimeoutError")))
+                throw error;
+            failure = error;
+        }
+        const pause = PAUSES[i] ?? PAUSE_MS;
+        if (performance.now() + pause >= deadline)
+            throw failure;
+        await new Promise(resolve => setTimeout(resolve, pause));
+        signal?.throwIfAborted();
+    }
+}
+const isName = (value) => value === null || typeof value === "string";
+function unexpected(text) {
+    return new Error(`feedback: unexpected answer ${text.slice(0, 200)}`);
+}
+/** The status with the Worker's `{ message }`, or with the start of whatever else answered, such as a proxy's page. */
+function message(status, text) {
+    const { message } = parse(text);
+    return `${status} ${typeof message === "string" ? message : text.slice(0, 200)}`;
+}
+/** The fields of a JSON object; none when the text is anything else. */
+function parse(text) {
+    try {
+        const value = JSON.parse(text);
+        return typeof value === "object" && value !== null ? { ...value } : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/browser/session.d.ts

@@ -0,0 +1,31 @@
+import type { Answer, Submission } from "../api.ts";
+import type { FeedbackOptions } from "../index.ts";
+import type { Tester } from "../tester.ts";
+/**
+ * The tester's playtest on this page load, as the service records it: started once, when the tester starts, seen again
+ * each time the page is hidden or closed, and finished when the game calls `finish()`. Its items point at it, so the
+ * owner sees who played which version, for how long, whether to the end, and what they said along the way.
+ */
+export declare class Session {
+    #private;
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    /** Starts the session, retried since every item points at it. Playing through one's own reviewer link enlists. */
+    constructor(options: FeedbackOptions, tester: Tester, version: string | null, signal: AbortSignal);
+    finish(): void;
+    /** Stores the closing screen's answers with the session. Rejects when they can't be, also when it never started. */
+    answer(answers: Answer[]): Promise<void>;
+    /** Joins the tester to the project's reviewers with `email`, from the closing screen. Rejects like `answer`. */
+    join(email: string): Promise<void>;
+    /** An item of this session, from what the tester said or typed, in `xr` when given in an XR session. */
+    item({ xr, state, text, overall }: {
+        xr?: XRSession | null;
+        state?: Submission["state"];
+        text?: string;
+        overall?: true;
+    }): Submission;
+    /**
+     * Calls the game's `pause()` and returns its state as plain JSON within the size cap: the round trip applies toJSON
+     * and drops undefined and functions. Null when it threw, returned nothing JSON can hold, or too much; all logged.
+     */
+    pause(): Submission["state"];
+}