@drawcall/feedback 0.0.0-stage → 0.1.0

package/dist/browser/ending.js

@@ -0,0 +1,241 @@
+import { LIMITS } from "../service.js";
+import { EMAIL_USE } from "./intro.js";
+import { record } from "./mic.js";
+import { advice, Refused, submit } from "./server.js";
+import { CLIPS } from "./sounds.js";
+import { clock } from "./turn.js";
+import { button, h } from "./ui.js";
+import { wait } from "./wait.js";
+const UNHEARD = "Didn't catch that. Record again, or type it.";
+const MIC = `<svg viewBox="0 0 24 24" width="18" height="18" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="2"
+  stroke-linecap="round"><rect x="9" y="3" width="6" height="11" rx="3"/><path d="M5 11a7 7 0 0 0 14 0M12 18v3"/></svg>`;
+/**
+ * The close of the playtest, once the game called `finish()`: a cover asking the game's questions and for an optional
+ * last word on the whole experience, written or spoken. Finish stores the answers with the session and sends the last
+ * word as an overall item; then thanks, by name when known, and stays. The cover is a page, so an XR session ends first.
+ */
+export async function ending(ctx, session) {
+    ctx.ui.corner("hidden");
+    await ctx.options.renderer.xr.getSession()?.end().catch(error => console.error("feedback: could not leave XR", error));
+    const cover = ctx.ui.cover();
+    try {
+        const sent = await ask(ctx, session, cover);
+        await thank(ctx, cover, sent);
+    }
+    finally {
+        cover.dispose();
+    }
+}
+/**
+ * Resolves once Finish sent what the tester left, with true, or with false when they left nothing or the service refused
+ * it, which no retry would change. A tester who isn't a reviewer yet may leave an email to become one, when the project
+ * takes sign-ups.
+ */
+async function ask(ctx, session, cover) {
+    const { options, tester, project, signal } = ctx;
+    const questions = (options.questions ?? []).map(question => (question.type === "scale" ? scale(question) : choice(question)));
+    const status = h("p", { className: "status", role: "alert" });
+    const last = new LastWord(ctx, note => (status.textContent = note));
+    const email = h("input", { name: "email", type: "email", autocomplete: "email", maxLength: LIMITS.contact });
+    const join = tester.reviewer || !(await project)?.signup ? null : h("label", { className: "join" }, "Email (optional)", email, h("span", { className: "fine" }, EMAIL_USE));
+    const finish = h("button", { className: "primary", type: "submit" }, "Finish");
+    const form = h("form", {}, questions.length ? h("div", { className: "questions" }, ...questions.map(question => question.element)) : null, h("div", { className: "question" }, h("div", { className: "ask", id: "last" }, "Anything else? What worked, what didn't, what you'd change."), last.element), join, h("div", { className: "actions" }, finish), status);
+    last.field.setAttribute("aria-labelledby", "last");
+    cover.show([
+        h("h1", {}, tester.name ? `You've reached the end, ${tester.name}` : "You've reached the end"),
+        h("p", { className: "lead" }, questions.length ? "A few last questions. All optional." : "One last thing, if you like. It's optional."),
+        form,
+    ]);
+    // Never a native submit, which would reload the page.
+    form.addEventListener("submit", event => event.preventDefault());
+    const submitted = () => wait(signal, (done, over) => form.addEventListener("submit", () => done(undefined), { signal: over }));
+    const busy = (on) => {
+        finish.disabled = last.disabled = email.disabled = on;
+        finish.textContent = on ? "Sending…" : "Finish";
+    };
+    for (;;) {
+        await submitted();
+        // Finish while recording sends the recording.
+        const audio = await last.audio();
+        const text = last.field.value.trim();
+        const answers = questions.map(question => question.read()).filter(answer => answer !== null);
+        const address = email.value.trim();
+        if (!audio && !text && !answers.length && !address)
+            return false;
+        busy(true);
+        status.textContent = "";
+        try {
+            // Each step is safe to repeat after a later one failed.
+            if (address)
+                await session.join(address);
+            if (answers.length)
+                await session.answer(answers);
+            if (!audio && !text)
+                return true;
+            const answer = await submit(session.item({ overall: true, text: audio ? undefined : text }), audio, signal);
+            if (answer.status === "stored")
+                return true;
+            last.unheard();
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            console.error("feedback: could not send", error);
+            status.textContent = `Couldn't send. ${advice(error instanceof Refused, "press Finish again")}`;
+            if (error instanceof Refused) {
+                // Sending again would fail the same way, so the button only moves on.
+                finish.disabled = false;
+                finish.textContent = "Continue";
+                await submitted();
+                return false;
+            }
+        }
+        busy(false);
+    }
+}
+/**
+ * The last page. Going back to a finished game would only confuse, so it says the tab can be closed, and offers to play
+ * again: a reload, which starts a new session for the same tester.
+ */
+async function thank({ tester, sounds, signal }, cover, sent) {
+    const again = button("secondary", "Start again");
+    cover.show([
+        h("h1", {}, tester.name ? `Thank you, ${tester.name}!` : "Thank you!"),
+        h("p", { className: "lead" }, `${sent ? "Your feedback was sent. " : ""}${CLIPS.end.words}`),
+        h("div", { className: "actions" }, again),
+    ]);
+    sounds.say("end");
+    await wait(signal, (done, over) => again.addEventListener("click", () => done(undefined), { signal: over }));
+    location.reload();
+}
+/**
+ * The last word, in one field: typed, or recorded with the button under it. The button shows only while nothing is
+ * typed, so typed text is never silently dropped for a recording; a recording takes the field's place until deleted. A
+ * microphone that is denied or broken removes the button.
+ */
+class LastWord {
+    field = h("textarea", { name: "overall", maxLength: LIMITS.text, placeholder: "Type here, or record it instead." });
+    element;
+    #ctx;
+    #note;
+    #button = h("button", { className: "record", type: "button" });
+    #voice = h("div", { className: "voice", hidden: true });
+    #recording = null;
+    #audio = null;
+    #nomic = false;
+    /** `note` tells the tester what they should know, such as that nothing was heard. */
+    constructor(ctx, note) {
+        this.#ctx = ctx;
+        this.#note = note;
+        this.#button.innerHTML = `${MIC}<span>Record</span>`;
+        this.#button.addEventListener("click", () => void this.#record());
+        this.field.addEventListener("input", () => this.#show());
+        this.element = h("div", { className: "reply" }, this.field, this.#voice, this.#button);
+        this.#show();
+    }
+    set disabled(disabled) {
+        this.field.readOnly = disabled;
+        for (const button of this.element.querySelectorAll("button"))
+            button.disabled = disabled;
+    }
+    /** The recording, stopping it first if it still runs; null without one. */
+    async audio() {
+        const recording = this.#recording;
+        recording?.stop();
+        await recording?.audio;
+        return this.#audio?.blob ?? null;
+    }
+    /** Drops the recording the service heard nothing in, saying so. */
+    unheard() {
+        this.#audio = null;
+        this.#note(UNHEARD);
+        this.#show();
+    }
+    async #record() {
+        this.#button.disabled = true;
+        const discard = new AbortController();
+        const recording = await record(this.#ctx.sounds.context, AbortSignal.any([this.#ctx.signal, discard.signal])).catch(error => {
+            if (!this.#ctx.signal.aborted)
+                throw error;
+            return null;
+        }).finally(() => (this.#button.disabled = false));
+        if (!recording)
+            return;
+        if (typeof recording === "string") {
+            this.#nomic = true;
+            this.#note(recording === "denied" ? "The mic is off. Type instead, or turn it on in your browser's site settings." : "The mic isn't working, so type instead.");
+            return this.#show();
+        }
+        const current = { ...recording, discard };
+        this.#recording = current;
+        const seconds = () => (performance.now() - recording.since) / 1000;
+        // Built once and only its time updated, so a press on Stop or Cancel lands on the button it started on.
+        const time = h("span", {}, clock(0));
+        const timer = setInterval(() => (time.textContent = clock(seconds())), 250);
+        const stop = button("secondary", "Stop");
+        const cancel = button("quiet", "Cancel");
+        stop.addEventListener("click", recording.stop);
+        cancel.addEventListener("click", () => {
+            this.#recording = null;
+            discard.abort();
+            this.#show();
+        });
+        this.#voice.replaceChildren(h("span", {}, h("span", { className: "dot" }), "Recording ", time, ` · up to ${clock(LIMITS.seconds)}`), stop, cancel);
+        // It also stops by itself at its caps.
+        void recording.audio.then(blob => {
+            clearInterval(timer);
+            if (this.#recording !== current)
+                return;
+            this.#recording = null;
+            this.#audio = blob && { blob, seconds: seconds() };
+            this.#note(blob ? "" : UNHEARD);
+            this.#show();
+        });
+        this.#note("");
+        this.#show();
+    }
+    #show() {
+        const voice = this.#recording !== null || this.#audio !== null;
+        this.field.hidden = voice;
+        this.#voice.hidden = !voice;
+        this.#button.hidden = voice || this.#nomic || this.field.value.trim() !== "";
+        if (!this.#audio || this.#recording)
+            return;
+        const remove = button("secondary", "Delete");
+        remove.addEventListener("click", () => {
+            this.#audio = null;
+            this.#show();
+        });
+        this.#voice.replaceChildren(h("span", {}, `Voice recording ready · ${clock(this.#audio.seconds)}`), remove);
+    }
+}
+/** A slider shows no value until it is moved or clicked, so its starting position never counts as an answer. */
+function scale(question) {
+    const { id, ask, min, max, step = 1, labels } = question;
+    const value = h("output", { className: "value" }, "–");
+    // In the middle, so the untouched slider leans neither way; set after the bounds, which would otherwise clamp it.
+    const middle = min + Math.round((max - min) / 2 / step) * step;
+    const slider = h("input", { type: "range", min: String(min), max: String(max), step: String(step), value: String(middle), className: "unset" });
+    slider.ariaLabel = ask;
+    let touched = false;
+    const touch = () => {
+        touched = true;
+        slider.classList.remove("unset");
+        value.textContent = slider.value;
+    };
+    slider.addEventListener("input", touch);
+    slider.addEventListener("pointerdown", touch);
+    const [low, high] = labels ?? [String(min), String(max)];
+    const element = h("div", { className: "question" }, h("div", { className: "ask" }, h("span", {}, ask), value), slider, h("div", { className: "ends" }, h("span", {}, low), h("span", {}, high)));
+    const range = { min, max, ...(labels && { labels }) };
+    return { element, read: () => (touched ? { id, ask, answer: Number(slider.value), scale: range } : null) };
+}
+function choice({ id, ask, options, multiple = false }) {
+    const boxes = options.map(option => h("input", { type: multiple ? "checkbox" : "radio", name: id, value: option }));
+    const labels = boxes.map(box => h("label", { className: "option" }, box, box.value));
+    const element = h("fieldset", { className: "question" }, h("legend", { className: "ask" }, ask), h("div", { className: "options" }, ...labels));
+    const read = () => {
+        const picked = boxes.filter(box => box.checked).map(box => box.value);
+        return picked.length ? { id, ask, answer: picked, options } : null;
+    };
+    return { element, read };
+}

package/dist/browser/frame.d.ts

@@ -0,0 +1,27 @@
+import type { Renderer } from "../index.ts";
+export interface Size {
+    width: number;
+    height: number;
+}
+/** Scales down to a long edge of 1280 px, never up, with the width a multiple of 64: WebGPU pads rows to 256 bytes. */
+export declare function fit(width: number, height: number): Size;
+/** Reverses the row order of RGBA pixels, for WebGL, which reads rows bottom-up. */
+export declare function flip(pixels: Uint8Array, { width, height }: Size): Uint8Array;
+export declare function canvas2d({ width, height }: Size): {
+    canvas: HTMLCanvasElement;
+    context: CanvasRenderingContext2D;
+};
+export declare function encode(canvas: HTMLCanvasElement): Promise<Blob>;
+/**
+ * Sees every frame the game draws: after each outermost render that reaches the screen or the XR display, so
+ * post-processing included, it calls `each` and feeds a pending screenshot. Unhooked on abort.
+ */
+export declare class Frames {
+    #private;
+    constructor(renderer: Renderer, each: (xr: XRFrame | null) => void, signal: AbortSignal);
+    /**
+     * The next frame the game renders, as a canvas to `encode`; given up when `signal` aborts. Encoding is left out, as
+     * Quest Browser takes seconds to encode a JPEG in XR, while the frame itself comes in a fraction of one.
+     */
+    take(signal: AbortSignal): Promise<HTMLCanvasElement>;
+}

package/dist/browser/frame.js

@@ -0,0 +1,165 @@
+/** Scales down to a long edge of 1280 px, never up, with the width a multiple of 64: WebGPU pads rows to 256 bytes. */
+export function fit(width, height) {
+    const scale = Math.min(1, 1280 / Math.max(width, height));
+    const fitted = Math.max(64, Math.floor((width * scale) / 64) * 64);
+    return { width: fitted, height: Math.max(1, Math.round((fitted * height) / width)) };
+}
+/** Reverses the row order of RGBA pixels, for WebGL, which reads rows bottom-up. */
+export function flip(pixels, { width, height }) {
+    const row = width * 4;
+    const flipped = new Uint8Array(pixels.length);
+    for (let y = 0; y < height; y++)
+        flipped.set(pixels.subarray(y * row, (y + 1) * row), (height - 1 - y) * row);
+    return flipped;
+}
+export function canvas2d({ width, height }) {
+    const canvas = Object.assign(document.createElement("canvas"), { width, height });
+    const context = canvas.getContext("2d");
+    if (!context)
+        throw new Error("feedback: no 2D canvas context");
+    return { canvas, context };
+}
+export function encode(canvas) {
+    return new Promise((resolve, reject) => {
+        canvas.toBlob(blob => (blob ? resolve(blob) : reject(new Error("feedback: could not encode the screenshot"))), "image/jpeg", 0.85);
+    });
+}
+/**
+ * Sees every frame the game draws: after each outermost render that reaches the screen or the XR display, so
+ * post-processing included, it calls `each` and feeds a pending screenshot. Unhooked on abort.
+ */
+export class Frames {
+    #renderer;
+    #signal;
+    #request = null;
+    #copy = null;
+    /** Prepared on the first XR frame, so flat-screen games never load the output pass. */
+    #eye = null;
+    constructor(renderer, each, signal) {
+        this.#renderer = renderer;
+        this.#signal = signal;
+        let depth = 0;
+        const after = (scene, screen) => {
+            if (depth > 0 || !screen)
+                return;
+            each(renderer.xr.isPresenting ? renderer.xr.getFrame() : null);
+            this.#frame(scene);
+        };
+        hook(renderer, "render", render => (scene, camera) => {
+            const screen = toScreen(renderer);
+            depth++;
+            try {
+                render.call(renderer, scene, camera);
+            }
+            finally {
+                depth--;
+            }
+            after(scene, screen);
+        }, signal);
+        // WebGPU's renderAsync draws the frame once its promise settles.
+        if ("isWebGPURenderer" in renderer) {
+            hook(renderer, "renderAsync", render => async (scene, camera) => {
+                const screen = toScreen(renderer);
+                depth++;
+                try {
+                    await render.call(renderer, scene, camera);
+                }
+                finally {
+                    depth--;
+                }
+                after(scene, screen);
+            }, signal);
+        }
+    }
+    /**
+     * The next frame the game renders, as a canvas to `encode`; given up when `signal` aborts. Encoding is left out, as
+     * Quest Browser takes seconds to encode a JPEG in XR, while the frame itself comes in a fraction of one.
+     */
+    take(signal) {
+        return new Promise((resolve, reject) => {
+            const request = { resolve, reject };
+            this.#request = request;
+            signal.addEventListener("abort", () => {
+                if (this.#request === request)
+                    this.#request = null;
+            }, { once: true });
+        });
+    }
+    #frame(scene) {
+        const { xr } = this.#renderer;
+        if (xr.isPresenting && !this.#eye)
+            this.#prepare();
+        const request = this.#request;
+        if (!request)
+            return;
+        if (!xr.isPresenting)
+            return this.#flat(request);
+        // The eye renders synchronously inside the XR frame, right after the game's, so while it loads a later frame takes it.
+        const eye = this.#eye;
+        if (!eye || eye === "loading")
+            return;
+        this.#request = null;
+        if ("failed" in eye)
+            request.reject(eye.failed);
+        else
+            eye.take(scene).then(request.resolve, request.reject);
+    }
+    #prepare() {
+        this.#eye = "loading";
+        import("./xr.js").then(({ prepareEyeShot }) => prepareEyeShot(this.#renderer)).then(eye => {
+            if (this.#signal.aborted)
+                return eye.dispose();
+            this.#eye = eye;
+            this.#signal.addEventListener("abort", () => eye.dispose(), { once: true });
+        }, (error) => {
+            console.error("feedback: could not prepare XR screenshots", error);
+            this.#eye = { failed: error };
+        });
+    }
+    /**
+     * Copies the canvas right after the render, while its drawing buffer is still intact, then hands over the last copy
+     * in the next task. A microtask is too early: async render loops would run it before their post-processing.
+     */
+    #flat(request) {
+        const game = this.#renderer.domElement;
+        try {
+            const copy = this.#copy ?? canvas2d(fit(game.width, game.height));
+            copy.context.drawImage(game, 0, 0, copy.canvas.width, copy.canvas.height);
+            if (this.#copy)
+                return;
+            this.#copy = copy;
+            setTimeout(() => {
+                this.#copy = null;
+                if (this.#request === request)
+                    this.#request = null;
+                request.resolve(copy.canvas);
+            });
+        }
+        catch (error) {
+            // A failed copy fails the screenshot, not the game's render call.
+            this.#request = null;
+            request.reject(error);
+        }
+    }
+}
+/** Wraps the method `key`, until `signal` aborts; put back only if nothing replaced it after, by deleting an own copy. */
+function hook(target, key, wrap, signal) {
+    const own = Object.hasOwn(target, key);
+    const original = target[key];
+    const wrapped = wrap(original);
+    target[key] = wrapped;
+    signal.addEventListener("abort", () => {
+        if (target[key] !== wrapped)
+            return;
+        if (own)
+            target[key] = original;
+        else
+            Reflect.deleteProperty(target, key);
+    }, { once: true });
+}
+function toScreen(renderer) {
+    if ("isWebGPURenderer" in renderer)
+        return renderer.isOutputTarget;
+    const target = renderer.getRenderTarget();
+    return target === null || ("isXRRenderTarget" in target && target.isXRRenderTarget === true);
+}

package/dist/browser/input.d.ts

@@ -0,0 +1,45 @@
+import type { Text } from "./ui.ts";
+/**
+ * The inputs that give feedback. `key` and `touch` start on a single press, and a click of the corner button counts as
+ * one of them; the others are inputs the experience also uses, so they start only after a hold. Every later press is a
+ * tap of the input that started.
+ */
+export type Kind = "key" | "touch" | "gamepad" | Hand;
+/** What gives feedback in an XR session: the left Touch controller, or both tracked hands. */
+export type Hand = "controller" | "hand";
+/** The inputs that start on a single press, each with its own corner button. */
+export type Press = "key" | "touch";
+/**
+ * The feedback key: the one left of 1, below Esc, which every layout has. Browsers name it "Backquote", except on a
+ * Mac with an ISO keyboard (German, UK, …), where macOS reports it as "IntlBackslash" and the key next to the left
+ * Shift as "Backquote". Accepting both keeps the key working there; the extra one is rarely bound by games.
+ */
+export declare const isHotkey: (event: KeyboardEvent) => boolean;
+/** What the key prints on this layout, e.g. "^" on German. Only Chromium can tell, elsewhere this stays "`". */
+export declare let hotkey: string;
+export declare function learnHotkey(): Promise<void>;
+/** "press ` to send", "tap Send": how to act on this input, mid-sentence. A phone's only button names what it does. */
+export declare function act(kind: Kind, after: string, button: string): Text;
+/** Turns raw presses and holds into what a flow waits for: a start, a tap of the started input, and Escape. */
+export declare class Input {
+    #private;
+    /** Called while a start hold fills, from 0 to 1, and with 0 when it is let go early. */
+    onHold: (kind: Kind, progress: number) => void;
+    constructor(signal: AbortSignal);
+    /** Calls `run` on a start (a press of `key` or `touch`, or a full hold of the others) or a tap of `kind`. */
+    on(kind: Kind | null, run: (kind: Kind) => void, signal: AbortSignal): void;
+    /** Calls `run` on Escape outside a text field, which is kept from the game, whose own pause menu would open. */
+    escape(run: () => void, signal: AbortSignal): void;
+    /** A click of the corner button, which counts as the input it stands in for. */
+    corner(kind: Press): void;
+    /** What the tester gives feedback with in the XR session, as of the last poll; null outside XR or while untracked. */
+    get hand(): Hand | null;
+    /**
+     * Polls gamepads and, in XR, the hands; called once per rendered frame. A left controller holds its thumbstick press
+     * and trigger together, which nothing does by accident. Tracked hands hold a pinch on both hands with the two pinches
+     * touching: apps often use a pinch, or a pinch held, on either hand, but not the two brought together.
+     */
+    poll(frame: XRFrame | null): void;
+    /** A short pulse on the controller of `kind`, where it has one. */
+    pulse(kind: Kind, strength: number, ms: number): void;
+}

package/dist/browser/input.js

@@ -0,0 +1,173 @@
+const HOLD_MS = 1000;
+/** Standard-mapping View / Select; xr-standard trigger, which on a tracked hand is the pinch; thumbstick press. */
+const VIEW = 8;
+const TRIGGER = 0;
+const STICK = 3;
+/**
+ * The feedback key: the one left of 1, below Esc, which every layout has. Browsers name it "Backquote", except on a
+ * Mac with an ISO keyboard (German, UK, …), where macOS reports it as "IntlBackslash" and the key next to the left
+ * Shift as "Backquote". Accepting both keeps the key working there; the extra one is rarely bound by games.
+ */
+export const isHotkey = (event) => event.code === "Backquote" || event.code === "IntlBackslash";
+/** What the key prints on this layout, e.g. "^" on German. Only Chromium can tell, elsewhere this stays "`". */
+export let hotkey = "`";
+export async function learnHotkey() {
+    const layout = await navigator.keyboard?.getLayoutMap().catch((error) => {
+        console.warn("feedback: could not read the keyboard layout", error);
+    });
+    const char = layout?.get("Backquote");
+    // No layout prints "<" left of 1, so "<" means the Mac ISO swap above, and the key is "IntlBackslash".
+    if (char)
+        hotkey = (char === "<" ? layout?.get("IntlBackslash") : char) ?? hotkey;
+}
+/** "press ` to send", "tap Send": how to act on this input, mid-sentence. A phone's only button names what it does. */
+export function act(kind, after, button) {
+    if (kind === "touch")
+        return [`tap ${button}`];
+    if (kind === "hand")
+        return [`touch both pinches together${after}`];
+    const key = { key: hotkey, gamepad: "View", controller: "thumbstick + trigger" }[kind];
+    return [kind === "controller" ? "click " : "press ", { key }, after];
+}
+/** Turns raw presses and holds into what a flow waits for: a start, a tap of the started input, and Escape. */
+export class Input {
+    /** Called while a start hold fills, from 0 to 1, and with 0 when it is let go early. */
+    onHold = () => { };
+    #waiters = new Set();
+    #escapes = new Set();
+    #holds = new Map();
+    #xr = null;
+    constructor(signal) {
+        addEventListener("keydown", this.#key, { signal, capture: true });
+    }
+    /** Calls `run` on a start (a press of `key` or `touch`, or a full hold of the others) or a tap of `kind`. */
+    on(kind, run, signal) {
+        this.#listen(this.#waiters, { kind, run }, signal);
+    }
+    /** Calls `run` on Escape outside a text field, which is kept from the game, whose own pause menu would open. */
+    escape(run, signal) {
+        this.#listen(this.#escapes, run, signal);
+    }
+    /** A click of the corner button, which counts as the input it stands in for. */
+    corner(kind) {
+        this.#press(kind, false);
+    }
+    /** What the tester gives feedback with in the XR session, as of the last poll; null outside XR or while untracked. */
+    get hand() {
+        const left = this.#source("left");
+        if (!left)
+            return null;
+        return isHand(left) ? "hand" : "controller";
+    }
+    /**
+     * Polls gamepads and, in XR, the hands; called once per rendered frame. A left controller holds its thumbstick press
+     * and trigger together, which nothing does by accident. Tracked hands hold a pinch on both hands with the two pinches
+     * touching: apps often use a pinch, or a pinch held, on either hand, but not the two brought together.
+     */
+    poll(frame) {
+        this.#xr = frame?.session ?? null;
+        for (const pad of navigator.getGamepads()) {
+            if (pad?.mapping === "standard")
+                this.#track(`pad${pad.index}`, "gamepad", pad.buttons[VIEW]?.pressed === true);
+        }
+        const left = this.#source("left");
+        const pressed = (source, index) => source?.gamepad?.buttons[index]?.pressed === true;
+        this.#track("controller", "controller", left !== null && !isHand(left) && pressed(left, TRIGGER) && pressed(left, STICK));
+        const right = this.#source("right");
+        const joined = frame !== null && pressed(left, TRIGGER) && pressed(right, TRIGGER) && touching(frame, left?.hand, right?.hand);
+        this.#track("hand", "hand", joined);
+    }
+    /** A short pulse on the controller of `kind`, where it has one. */
+    pulse(kind, strength, ms) {
+        if (kind === "controller")
+            void this.#source("left")?.gamepad?.hapticActuators[0]?.pulse(strength, ms);
+        if (kind !== "gamepad")
+            return;
+        for (const pad of navigator.getGamepads()) {
+            void pad?.vibrationActuator?.playEffect("dual-rumble", { duration: ms, strongMagnitude: strength, weakMagnitude: strength });
+        }
+    }
+    #listen(set, item, signal) {
+        if (signal.aborted)
+            return;
+        set.add(item);
+        signal.addEventListener("abort", () => set.delete(item), { once: true });
+    }
+    #source(handedness) {
+        for (const source of this.#xr?.inputSources ?? [])
+            if (source.handedness === handedness && source.gamepad)
+                return source;
+        return null;
+    }
+    #key = (event) => {
+        if (event.repeat || typing(event))
+            return;
+        if (event.key === "Escape" && this.#escapes.size) {
+            event.preventDefault();
+            event.stopPropagation();
+            for (const run of [...this.#escapes])
+                run();
+        }
+        else if (isHotkey(event)) {
+            event.preventDefault();
+            this.#press("key", false);
+        }
+    };
+    #track(id, kind, pressed) {
+        const hold = this.#holds.get(id);
+        if (!pressed) {
+            if (hold && !hold.done)
+                this.onHold(kind, 0);
+            this.#holds.delete(id);
+        }
+        else if (!hold) {
+            this.#holds.set(id, { since: performance.now(), done: false });
+            this.#press(kind, false);
+        }
+        else if (!hold.done) {
+            const progress = Math.min(1, (performance.now() - hold.since) / HOLD_MS);
+            hold.done = progress === 1;
+            if ([...this.#waiters].some(waiter => waiter.kind === null))
+                this.onHold(kind, progress);
+            if (hold.done)
+                this.#press(kind, true);
+        }
+    }
+    #press(kind, held) {
+        const starts = held || kind === "key" || kind === "touch";
+        for (const waiter of [...this.#waiters]) {
+            if (waiter.kind === null ? starts : waiter.kind === kind && !held)
+                waiter.run(kind);
+        }
+    }
+}
+/**
+ * Quest Browser reports a tracked hand with a gamepad whose button 0 is the pinch, and with the generic-hand profiles;
+ * its joints (`source.hand`) come only in a session that asked for hand tracking, the only one with hands at all.
+ */
+function isHand(source) {
+    return Boolean(source.hand) || source.profiles.some(profile => profile.startsWith("generic-hand"));
+}
+/** Pinch midpoints within 7 cm count as touching, allowing for finger width and tracking error. */
+const TOUCH_M = 0.07;
+/** Whether the pinch points of both hands, each midway between thumb tip and index tip, touch. */
+function touching(frame, left, right) {
+    const base = left?.get("wrist");
+    if (!left || !right || !base || !frame.getJointPose)
+        return false;
+    const at = (hand, joint) => {
+        const space = hand.get(joint);
+        return space ? frame.getJointPose?.(space, base)?.transform.position : undefined;
+    };
+    const ends = [at(left, "thumb-tip"), at(left, "index-finger-tip"), at(right, "thumb-tip"), at(right, "index-finger-tip")];
+    const [lt, li, rt, ri] = ends;
+    if (!lt || !li || !rt || !ri)
+        return false;
+    const gap = (axis) => (lt[axis] + li[axis] - rt[axis] - ri[axis]) / 2;
+    return Math.hypot(gap("x"), gap("y"), gap("z")) < TOUCH_M;
+}
+/** Trigger keys are ignored while the tester types. The path's start sees through shadow roots, unlike activeElement. */
+function typing(event) {
+    const element = event.composedPath()[0];
+    return element instanceof HTMLElement && (element.isContentEditable || element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement);
+}

package/dist/browser/intro.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from "./run.ts";
+import { Session } from "./session.ts";
+/** 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 declare 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 declare function intro(ctx: Context, version: string | null): Promise<Session>;