@drawcall/feedback 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @drawcall/feedback
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Voice feedback for three.js apps and experiences, on flat screens and in WebXR. Testers open your app with `?feedback`, or a published playtest link, describe what they notice and carry on. The app supplies the context.
+
+```sh
+npx drawcall auth login
+npx drawcall feedback project create "Moonbase"
+```
+
+```ts
+import { feedback } from "@drawcall/feedback";
+
+let wasPaused = false;
+const fb = feedback({
+  project: "fbk_pub_…",
+  renderer,
+  minutes: 10, // shown to testers before they start, with the task
+  task: "Find the crater and say where you got lost.",
+  pause: () => {
+    wasPaused = app.paused;
+    app.paused = true; // freeze the world, never the camera or the user
+    return { scene: app.scene.id }; // the facts someone fixing a report needs first
+  },
+  resume: () => { app.paused = wasPaused; },
+});
+```
+
+Publish a build for testers, always in feedback mode, and send them its link:
+
+```sh
+npx drawcall feedback publish dist
+```
+
+Reviewers get one invitation with their own link, and once they try it out, an email when a new version is ready:
+
+```sh
+npx drawcall feedback reviewer add sam@studio.com --name Sam --trust high
+```
+
+Then see who tested what and their reviewer trust, inspect reports, and resolve verified fixes:
+
+```sh
+npx drawcall feedback list
+npx drawcall feedback show 42 --out ./feedback
+npx drawcall feedback resolve 42
+```
+
+Every command prints JSON, errors too (on stderr, exiting 2 for misuse and 1 otherwise), and `--help` lists the commands. Coding agents read the `feedback` skill in `skills/feedback`, also printed by `npx drawcall feedback skill`.

package/dist/api.d.ts

@@ -0,0 +1,328 @@
+import { z } from "zod";
+/**
+ * The HTTP contract between the browser SDK, the CLI and the Worker at feedback.drawcall.ai. Players write with a
+ * project key, which ships in game code and is therefore public: it can only add sessions and items. Everything that
+ * reads or changes a project needs a Drawcall sign-in.
+ */
+/** A project key: `fbk_pub_` and 16 base62 characters. */
+export declare const keySchema: z.ZodString;
+/** Such as `1.4.0`; see `VERSION_FORMAT`. */
+export declare const versionSchema: z.ZodString;
+/** A reviewer's id, in their link as `?reviewer=<id>`. */
+export declare const reviewerIdSchema: z.ZodString;
+/** The smallest version change a reviewer hears about: `major` for 2.0.0 after 1.4.0, `minor` also for 1.5.0, `patch` for any. */
+export declare const levelSchema: z.ZodEnum<{
+    major: "major";
+    minor: "minor";
+    patch: "patch";
+}>;
+/** The owner's confidence in a reviewer's feedback, independent of their email subscription. New reviewers start low. */
+export declare const trustSchema: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+}>;
+export type Trust = z.infer<typeof trustSchema>;
+/**
+ * `POST /api/v1/sessions`: a tester started the playtest, on one page load. The client makes the id with
+ * `crypto.randomUUID()`, so a retry creates nothing new.
+ */
+export declare const startSessionSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    project: z.ZodString;
+    tester: z.ZodNullable<z.ZodString>;
+    contact: z.ZodNullable<z.ZodEmail>;
+    version: z.ZodNullable<z.ZodString>;
+    url: z.ZodPipe<z.ZodString, z.ZodURL>;
+    device: z.ZodString;
+    reviewer: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    minutes: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+export type StartSession = z.input<typeof startSessionSchema>;
+/**
+ * The answer to `POST /api/v1/sessions`: the tester's reviewer id only when they play through their own emailed link,
+ * else null. `…/:id/join` answers with a random placeholder, never stored, which older published builds need non-null.
+ */
+export interface Started {
+    reviewer: string | null;
+}
+/**
+ * One answer to a closing question: its id and wording as asked, the scale's number or the options picked, and what it
+ * was picked from, so it reads right on its own. Older answers have no `scale` or `options`.
+ */
+export declare const answerSchema: z.ZodObject<{
+    id: z.ZodString;
+    ask: z.ZodString;
+    answer: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodString>]>;
+    scale: z.ZodOptional<z.ZodObject<{
+        min: z.ZodNumber;
+        max: z.ZodNumber;
+        labels: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+    }, z.core.$strip>>;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type Answer = z.infer<typeof answerSchema>;
+/** `POST /api/v1/sessions/:id/join`: a tester leaves their email on the closing screen, to hear about new versions. */
+export declare const joinSchema: z.ZodObject<{
+    email: z.ZodEmail;
+}, z.core.$strip>;
+/** `POST /api/v1/sessions/:id/answers`; a later post replaces it. */
+export declare const answersSchema: z.ZodObject<{
+    answers: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        ask: z.ZodString;
+        answer: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodString>]>;
+        scale: z.ZodOptional<z.ZodObject<{
+            min: z.ZodNumber;
+            max: z.ZodNumber;
+            labels: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+        }, z.core.$strip>>;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** `GET /api/v1/reviewers/:id`: who a reviewer link greets, and for which project. */
+export interface PublicReviewer {
+    project: string;
+    name: string | null;
+}
+/** The `meta` part of `POST /api/v1/items`, sent as JSON next to an `audio` file part. */
+export declare const submissionSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    project: z.ZodString;
+    session: z.ZodUUID;
+    tester: z.ZodNullable<z.ZodString>;
+    contact: z.ZodNullable<z.ZodEmail>;
+    url: z.ZodPipe<z.ZodString, z.ZodURL>;
+    device: z.ZodString;
+    xr: z.ZodNullable<z.ZodString>;
+    state: z.ZodNullable<z.ZodJSONSchema>;
+    text: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>>;
+    overall: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type Submission = z.input<typeof submissionSchema>;
+/** The answer to `POST /api/v1/items`. `empty`: nothing was heard, so nothing was stored. */
+export type Submitted = {
+    status: "stored";
+    n: number;
+    visual: boolean;
+} | {
+    status: "empty";
+};
+/**
+ * `GET /api/v1/projects/:key/public`: confirms a key at startup, and what the intro shows. `minutes`, `note` and
+ * `welcome` never change, for games built with an earlier SDK.
+ */
+export interface PublicProject {
+    name: string;
+    signup: boolean;
+    minutes: null;
+    note: null;
+    welcome: false;
+}
+/** The shapes of the responses, as stored: input rules are checked on the way in, so these use plain types. */
+export declare const projectSchema: z.ZodObject<{
+    key: z.ZodString;
+    name: z.ZodString;
+    notify: z.ZodNullable<z.ZodString>;
+    signup: z.ZodBoolean;
+    site: z.ZodNullable<z.ZodString>;
+    version: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type Project = z.infer<typeof projectSchema>;
+export declare const createProjectSchema: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>;
+export declare const updateProjectSchema: z.ZodObject<{
+    notify: z.ZodOptional<z.ZodBoolean>;
+    signup: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Why an item was resolved, as in an issue tracker. */
+export declare const resolutionSchema: z.ZodEnum<{
+    fixed: "fixed";
+    duplicate: "duplicate";
+    "cannot-reproduce": "cannot-reproduce";
+    "wont-fix": "wont-fix";
+}>;
+export type Resolution = z.infer<typeof resolutionSchema>;
+/** Which items `GET …/sessions` lists; `all` also lists sessions without any. */
+export declare const statusSchema: z.ZodEnum<{
+    open: "open";
+    resolved: "resolved";
+    all: "all";
+}>;
+export declare const itemSchema: z.ZodObject<{
+    n: z.ZodNumber;
+    status: z.ZodEnum<{
+        open: "open";
+        resolved: "resolved";
+    }>;
+    resolution: z.ZodNullable<z.ZodEnum<{
+        fixed: "fixed";
+        duplicate: "duplicate";
+        "cannot-reproduce": "cannot-reproduce";
+        "wont-fix": "wont-fix";
+    }>>;
+    duplicateOf: z.ZodNullable<z.ZodNumber>;
+    comment: z.ZodNullable<z.ZodString>;
+    tester: z.ZodNullable<z.ZodString>;
+    contact: z.ZodNullable<z.ZodString>;
+    trust: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>;
+    at: z.ZodISODateTime;
+    transcript: z.ZodNullable<z.ZodString>;
+    visual: z.ZodBoolean;
+    overall: z.ZodBoolean;
+    screenshot: z.ZodBoolean;
+    audio: z.ZodNullable<z.ZodString>;
+    state: z.ZodNullable<z.ZodJSONSchema>;
+    url: z.ZodString;
+    device: z.ZodString;
+    xr: z.ZodNullable<z.ZodString>;
+    session: z.ZodString;
+    version: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type Item = z.infer<typeof itemSchema>;
+/**
+ * One tester's playtest on one page load. `seenAt` is the last sign of them, so `seenAt - startedAt` is about how long
+ * they played; `finishedAt` is when the game called `finish()`.
+ */
+export declare const sessionSchema: z.ZodObject<{
+    id: z.ZodString;
+    tester: z.ZodNullable<z.ZodString>;
+    contact: z.ZodNullable<z.ZodString>;
+    version: z.ZodNullable<z.ZodString>;
+    url: z.ZodString;
+    device: z.ZodString;
+    startedAt: z.ZodISODateTime;
+    seenAt: z.ZodISODateTime;
+    finishedAt: z.ZodNullable<z.ZodISODateTime>;
+    items: z.ZodArray<z.ZodObject<{
+        n: z.ZodNumber;
+        status: z.ZodEnum<{
+            open: "open";
+            resolved: "resolved";
+        }>;
+        resolution: z.ZodNullable<z.ZodEnum<{
+            fixed: "fixed";
+            duplicate: "duplicate";
+            "cannot-reproduce": "cannot-reproduce";
+            "wont-fix": "wont-fix";
+        }>>;
+        duplicateOf: z.ZodNullable<z.ZodNumber>;
+        comment: z.ZodNullable<z.ZodString>;
+        tester: z.ZodNullable<z.ZodString>;
+        contact: z.ZodNullable<z.ZodString>;
+        trust: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>;
+        at: z.ZodISODateTime;
+        transcript: z.ZodNullable<z.ZodString>;
+        visual: z.ZodBoolean;
+        overall: z.ZodBoolean;
+        screenshot: z.ZodBoolean;
+        audio: z.ZodNullable<z.ZodString>;
+        state: z.ZodNullable<z.ZodJSONSchema>;
+        url: z.ZodString;
+        device: z.ZodString;
+        xr: z.ZodNullable<z.ZodString>;
+        session: z.ZodString;
+        version: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    reviewer: z.ZodNullable<z.ZodString>;
+    trust: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>;
+    answers: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        ask: z.ZodString;
+        answer: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodString>]>;
+        scale: z.ZodOptional<z.ZodObject<{
+            min: z.ZodNumber;
+            max: z.ZodNumber;
+            labels: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+        }, z.core.$strip>>;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type Session = z.infer<typeof sessionSchema>;
+/**
+ * Someone told about new versions, as `GET /api/v1/projects/:key/reviewers` shows them to the owner. Whether the owner
+ * added them or they left their email, they get one invitation with their own link and nothing more until they open
+ * it, which makes them `active`; only then does the owner see their `link`. `toldVersion`: the version last emailed, or
+ * the one live when they joined while playing. `stopped`: they stopped the emails, for good.
+ */
+export declare const reviewerSchema: z.ZodObject<{
+    name: z.ZodNullable<z.ZodString>;
+    email: z.ZodString;
+    trust: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>;
+    every: z.ZodNumber;
+    on: z.ZodEnum<{
+        major: "major";
+        minor: "minor";
+        patch: "patch";
+    }>;
+    link: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    toldAt: z.ZodNullable<z.ZodISODateTime>;
+    toldVersion: z.ZodNullable<z.ZodString>;
+    active: z.ZodBoolean;
+    stopped: z.ZodBoolean;
+}, z.core.$strip>;
+export type Reviewer = z.infer<typeof reviewerSchema>;
+/**
+ * `POST /api/v1/projects/:key/reviewers`: adds a reviewer, or changes the one with that email. Fields left out keep
+ * their value. An address that stopped the emails is refused with 409, as is `DELETE …/reviewers/:email` on it.
+ */
+export declare const addReviewerSchema: z.ZodObject<{
+    email: z.ZodEmail;
+    name: z.ZodOptional<z.ZodString>;
+    every: z.ZodOptional<z.ZodNumber>;
+    on: z.ZodOptional<z.ZodEnum<{
+        major: "major";
+        minor: "minor";
+        patch: "patch";
+    }>>;
+    trust: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+}, z.core.$strip>;
+/** `POST /api/v1/projects/:key/releases`: starts uploading a version, which can be published only once. */
+export declare const releaseSchema: z.ZodObject<{
+    version: z.ZodString;
+}, z.core.$strip>;
+/** `POST …/releases/:version/publish`. The images and videos the notes point to go to `…/media/<path>` first. */
+export declare const publishSchema: z.ZodObject<{
+    notes: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** A path inside a build, as `PUT …/releases/:version/files/<path>` takes it: relative and `/`-separated. */
+export declare const filePathSchema: z.ZodString;
+/** `POST …/items/resolve`. */
+export declare const resolveSchema: z.ZodObject<{
+    n: z.ZodArray<z.ZodNumber>;
+    resolution: z.ZodDefault<z.ZodEnum<{
+        fixed: "fixed";
+        duplicate: "duplicate";
+        "cannot-reproduce": "cannot-reproduce";
+        "wont-fix": "wont-fix";
+    }>>;
+    of: z.ZodOptional<z.ZodNumber>;
+    comment: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** `POST …/items/reopen`: drops the items' resolution. */
+export declare const reopenSchema: z.ZodObject<{
+    n: z.ZodArray<z.ZodNumber>;
+}, z.core.$strip>;

package/dist/api.js

@@ -0,0 +1,202 @@
+import { z } from "zod";
+import { CONTROL, LIMITS, stripControl, VERSION_FORMAT } from "./service.js";
+/**
+ * The HTTP contract between the browser SDK, the CLI and the Worker at feedback.drawcall.ai. Players write with a
+ * project key, which ships in game code and is therefore public: it can only add sessions and items. Everything that
+ * reads or changes a project needs a Drawcall sign-in.
+ */
+/** A project key: `fbk_pub_` and 16 base62 characters. */
+export const keySchema = z.string().regex(/^fbk_pub_[0-9A-Za-z]{16}$/);
+/** No control characters, see `CONTROL`. Checked before URL parsing, which would silently drop tabs and newlines. */
+const plain = z.string().refine(text => !CONTROL.test(text), "Remove control characters");
+/** The control characters typed text may hold: tabs and line breaks. */
+const LINES = "\t\n";
+/** Typed text, which may also hold `LINES`. */
+const typed = z.string().refine(text => stripControl(text, LINES) === text, "Remove control characters");
+/** Only http(s): other schemes such as `javascript:` would be links nobody should follow. */
+const urlSchema = plain.pipe(z.url({ protocol: /^https?$/, normalize: true }));
+/** Checked like the browser's email field, so an address the intro accepts is never refused later. */
+const contactSchema = z.email({ pattern: z.regexes.html5Email }).max(LIMITS.contact);
+/** Such as `1.4.0`; see `VERSION_FORMAT`. */
+export const versionSchema = z.string().regex(VERSION_FORMAT, `Use up to ${LIMITS.version} letters, digits and . _ + -`);
+/** A reviewer's id, in their link as `?reviewer=<id>`. */
+export const reviewerIdSchema = z.string().regex(/^[0-9A-Za-z]{12}$/);
+/** The smallest version change a reviewer hears about: `major` for 2.0.0 after 1.4.0, `minor` also for 1.5.0, `patch` for any. */
+export const levelSchema = z.enum(["major", "minor", "patch"]);
+/** The owner's confidence in a reviewer's feedback, independent of their email subscription. New reviewers start low. */
+export const trustSchema = z.enum(["low", "medium", "high"]);
+/** At most how often a reviewer is emailed, in days. */
+const everySchema = z.number().int().min(1).max(365);
+const nameSchema = plain.trim().min(1).max(LIMITS.name);
+/**
+ * `POST /api/v1/sessions`: a tester started the playtest, on one page load. The client makes the id with
+ * `crypto.randomUUID()`, so a retry creates nothing new.
+ */
+export const startSessionSchema = z.object({
+    id: z.uuid(),
+    project: keySchema,
+    tester: plain.min(1).max(LIMITS.name).nullable(),
+    contact: contactSchema.nullable(),
+    version: versionSchema.nullable(),
+    url: urlSchema,
+    device: plain.max(LIMITS.device),
+    /** The reviewer the link or this browser names; their stored name and email stand for the tester's. */
+    reviewer: reviewerIdSchema.nullable().default(null),
+    /** The game's `minutes` option. */
+    minutes: z.number().int().min(1).max(LIMITS.minutes).nullable().default(null),
+});
+const optionSchema = plain.min(1).max(LIMITS.option);
+/**
+ * One answer to a closing question: its id and wording as asked, the scale's number or the options picked, and what it
+ * was picked from, so it reads right on its own. Older answers have no `scale` or `options`.
+ */
+export const answerSchema = z.object({
+    id: plain.min(1).max(LIMITS.id),
+    ask: plain.min(1).max(LIMITS.ask),
+    answer: z.union([z.number().finite(), z.array(optionSchema).min(1).max(LIMITS.options)]),
+    scale: z.object({ min: z.number().finite(), max: z.number().finite(), labels: z.tuple([optionSchema, optionSchema]).optional() }).optional(),
+    options: z.array(optionSchema).min(2).max(LIMITS.options).optional(),
+});
+/** `POST /api/v1/sessions/:id/join`: a tester leaves their email on the closing screen, to hear about new versions. */
+export const joinSchema = z.object({ email: contactSchema });
+/** `POST /api/v1/sessions/:id/answers`; a later post replaces it. */
+export const answersSchema = z.object({ answers: z.array(answerSchema).min(1).max(LIMITS.questions) });
+/** The `meta` part of `POST /api/v1/items`, sent as JSON next to an `audio` file part. */
+export const submissionSchema = z.object({
+    /** Made with `crypto.randomUUID()`, so a retried POST never creates a second item. */
+    id: z.uuid(),
+    project: keySchema,
+    session: z.uuid(),
+    tester: plain.min(1).max(LIMITS.name).nullable(),
+    contact: contactSchema.nullable(),
+    url: urlSchema,
+    /** "Quest 3 · Quest Browser 37", "Mac · Chrome 141". */
+    device: plain.max(LIMITS.device),
+    /** The XR session mode while recording, such as "immersive-vr". */
+    xr: plain.max(32).nullable(),
+    /** What the game's `pause()` returned. */
+    state: z.json().nullable(),
+    /**
+     * Typed feedback, when the microphone was denied; an item has either `text` or an audio part. Control characters
+     * beyond `LINES` are stripped rather than refused, since the tester never sees why and the feedback would be lost.
+     */
+    text: z.string().max(LIMITS.text).transform(text => stripControl(text, LINES)).pipe(z.string().min(1)).optional(),
+    /** Feedback on the whole experience from the closing screen, so never visual. */
+    overall: z.boolean().default(false),
+});
+/** The shapes of the responses, as stored: input rules are checked on the way in, so these use plain types. */
+export const projectSchema = z.object({
+    key: z.string(),
+    name: z.string(),
+    /** The owner's account address that "new feedback" emails go to, or null when they are off. */
+    notify: z.string().nullable(),
+    /** Whether testers are asked for their name and email; leaving an email makes them a reviewer. */
+    signup: z.boolean(),
+    /** Where `publish` serves the game, and the version live there. */
+    site: z.string().nullable(),
+    version: z.string().nullable(),
+    createdAt: z.iso.datetime(),
+});
+export const createProjectSchema = z.object({ name: plain.trim().min(1).max(100) });
+/** Changes only the fields given. */
+const change = (update) => Object.values(update).some(value => value !== undefined);
+export const updateProjectSchema = z.object({ notify: z.boolean(), signup: z.boolean() }).partial().refine(change, "Give a setting to change");
+/** Why an item was resolved, as in an issue tracker. */
+export const resolutionSchema = z.enum(["fixed", "duplicate", "cannot-reproduce", "wont-fix"]);
+/** Which items `GET …/sessions` lists; `all` also lists sessions without any. */
+export const statusSchema = z.enum(["open", "resolved", "all"]);
+export const itemSchema = z.object({
+    n: z.number().int().positive(),
+    status: z.enum(["open", "resolved"]),
+    resolution: resolutionSchema.nullable(),
+    duplicateOf: z.number().int().positive().nullable(),
+    /** The owner's word on the resolution. */
+    comment: z.string().nullable(),
+    tester: z.string().nullable(),
+    contact: z.string().nullable(),
+    /** The linked reviewer's current trust; low without a reviewer link, even when the typed email matches. */
+    trust: trustSchema,
+    at: z.iso.datetime(),
+    /** Null when transcription failed. */
+    transcript: z.string().nullable(),
+    /** Whether it is about something visible; never for overall feedback. */
+    visual: z.boolean(),
+    overall: z.boolean(),
+    /** Whether the player showed something, served at `…/items/:n/screenshot`. */
+    screenshot: z.boolean(),
+    /** The recording's MIME type, served at `…/items/:n/audio`, or null for typed feedback. */
+    audio: z.string().nullable(),
+    state: z.json().nullable(),
+    url: z.string(),
+    device: z.string(),
+    xr: z.string().nullable(),
+    session: z.string(),
+    version: z.string().nullable(),
+});
+/**
+ * One tester's playtest on one page load. `seenAt` is the last sign of them, so `seenAt - startedAt` is about how long
+ * they played; `finishedAt` is when the game called `finish()`.
+ */
+export const sessionSchema = z.object({
+    id: z.string(),
+    tester: z.string().nullable(),
+    contact: z.string().nullable(),
+    version: z.string().nullable(),
+    url: z.string(),
+    device: z.string(),
+    startedAt: z.iso.datetime(),
+    seenAt: z.iso.datetime(),
+    finishedAt: z.iso.datetime().nullable(),
+    /** Its items of the listed status, oldest first. */
+    items: z.array(itemSchema),
+    reviewer: z.string().nullable(),
+    /** The linked reviewer's current trust, also for sessions without items; low without a reviewer link. */
+    trust: trustSchema,
+    answers: z.array(answerSchema).nullable(),
+});
+/**
+ * Someone told about new versions, as `GET /api/v1/projects/:key/reviewers` shows them to the owner. Whether the owner
+ * added them or they left their email, they get one invitation with their own link and nothing more until they open
+ * it, which makes them `active`; only then does the owner see their `link`. `toldVersion`: the version last emailed, or
+ * the one live when they joined while playing. `stopped`: they stopped the emails, for good.
+ */
+export const reviewerSchema = z.object({
+    name: z.string().nullable(),
+    email: z.string(),
+    trust: trustSchema,
+    every: z.number(),
+    on: levelSchema,
+    link: z.string().nullable(),
+    createdAt: z.iso.datetime(),
+    toldAt: z.iso.datetime().nullable(),
+    toldVersion: z.string().nullable(),
+    active: z.boolean(),
+    stopped: z.boolean(),
+});
+/**
+ * `POST /api/v1/projects/:key/reviewers`: adds a reviewer, or changes the one with that email. Fields left out keep
+ * their value. An address that stopped the emails is refused with 409, as is `DELETE …/reviewers/:email` on it.
+ */
+export const addReviewerSchema = z.object({
+    email: contactSchema, name: nameSchema.optional(), every: everySchema.optional(), on: levelSchema.optional(), trust: trustSchema.optional(),
+});
+/** `POST /api/v1/projects/:key/releases`: starts uploading a version, which can be published only once. */
+export const releaseSchema = z.object({ version: versionSchema });
+/** `POST …/releases/:version/publish`. The images and videos the notes point to go to `…/media/<path>` first. */
+export const publishSchema = z.object({ notes: typed.trim().min(1).max(LIMITS.notes).optional() });
+/** A path inside a build, as `PUT …/releases/:version/files/<path>` takes it: relative and `/`-separated. */
+export const filePathSchema = plain.max(512).refine(path => path.split("/").every(part => part !== "" && part !== "." && part !== ".." && !part.includes("\\")), "Not a relative file path");
+const numbersSchema = z.array(z.number().int().positive()).min(1).max(100);
+/** `POST …/items/resolve`. */
+export const resolveSchema = z
+    .object({
+    n: numbersSchema,
+    resolution: resolutionSchema.default("fixed"),
+    /** The item a duplicate repeats. */
+    of: z.number().int().positive().optional(),
+    comment: plain.trim().min(1).max(500).optional(),
+})
+    .refine(body => (body.resolution === "duplicate") === (body.of !== undefined), "A duplicate needs `of`, the item it repeats, and only a duplicate takes one")
+    .refine(body => body.of === undefined || !body.n.includes(body.of), "An item can't be a duplicate of itself");
+/** `POST …/items/reopen`: drops the items' resolution. */
+export const reopenSchema = z.object({ n: numbersSchema });

package/dist/browser/device.d.ts

@@ -0,0 +1,13 @@
+import type { Target } from "../index.ts";
+/** "Quest 3 · Quest Browser 37", "Mac · Chrome 141": for reproducing, so only what the user agent states. */
+export declare function describeDevice(agent: string): string;
+/**
+ * Where feedback runs, as the `devices` presets name it. Quest Browser hides the controllers from 2D pages, so there the
+ * walkthrough only shows them.
+ */
+export type Device = Extract<Target, string>;
+export declare function detect(): Device;
+/** Whether this device is one the playtest is for. A game's own test that throws is a bug, so it rejects. */
+export declare function targeted(targets: Target[], device: Device): Promise<boolean>;
+/** The targets as a phrase: "Meta Quest", "a computer or a phone", "Meta Quest, Apple Vision Pro or a phone". */
+export declare function phrase(targets: Target[]): string;

package/dist/browser/device.js

@@ -0,0 +1,64 @@
+import { LIMITS } from "../service.js";
+/** "Quest 3 · Quest Browser 37", "Mac · Chrome 141": for reproducing, so only what the user agent states. */
+export function describeDevice(agent) {
+    return [platform(agent), browser(agent)].filter(part => part !== null).join(" · ").slice(0, LIMITS.device);
+}
+/** How the presets read in a sentence such as "This test is for Meta Quest", each kept on one line. */
+const PRESETS = { desktop: "a\u00a0computer", phone: "a\u00a0phone", quest: "Meta\u00a0Quest" };
+export function detect() {
+    if (isQuest(navigator.userAgent))
+        return "quest";
+    return matchMedia("(pointer: coarse)").matches ? "phone" : "desktop";
+}
+/** Whether this device is one the playtest is for. A game's own test that throws is a bug, so it rejects. */
+export async function targeted(targets, device) {
+    for (const target of targets) {
+        if (typeof target === "string" ? target === device : await target.matches())
+            return true;
+    }
+    return false;
+}
+/** The targets as a phrase: "Meta Quest", "a computer or a phone", "Meta Quest, Apple Vision Pro or a phone". */
+export function phrase(targets) {
+    const names = targets.map(target => (typeof target === "string" ? PRESETS[target] : target.name));
+    return names.length < 2 ? (names[0] ?? "") : `${names.slice(0, -1).join(", ")} or ${names.at(-1)}`;
+}
+function isQuest(agent) {
+    return agent.includes("OculusBrowser");
+}
+function platform(agent) {
+    if (isQuest(agent))
+        return agent.match(/Quest (?:\d+S?|Pro)/)?.[0] ?? "Quest";
+    if (agent.includes("iPhone"))
+        return "iPhone";
+    if (agent.includes("iPad"))
+        return "iPad";
+    if (agent.includes("Android"))
+        return "Android";
+    if (agent.includes("Mac OS X"))
+        return "Mac";
+    if (agent.includes("Windows"))
+        return "Windows";
+    if (agent.includes("CrOS"))
+        return "ChromeOS";
+    if (agent.includes("Linux"))
+        return "Linux";
+    return null;
+}
+const BROWSERS = [
+    ["Quest Browser", /OculusBrowser\/(\d+)/],
+    ["Edge", /Edg(?:A|iOS)?\/(\d+)/],
+    ["Opera", /OPR\/(\d+)/],
+    ["Samsung Internet", /SamsungBrowser\/(\d+)/],
+    ["Firefox", /(?:Firefox|FxiOS)\/(\d+)/],
+    ["Chrome", /(?:Chrome|CriOS)\/(\d+)/],
+    ["Safari", /Version\/(\d+(?:\.\d+)?).*Safari/],
+];
+function browser(agent) {
+    for (const [name, pattern] of BROWSERS) {
+        const version = agent.match(pattern)?.[1];
+        if (version)
+            return `${name} ${version}`;
+    }
+    return null;
+}

package/dist/browser/ending.d.ts

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