@drawcall/feedback 0.0.0-stage → 0.1.0

package/dist/cli/commands.js

@@ -0,0 +1,153 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { z } from "zod";
+import { blob, packageVersion, releaseNotes, save, walk } from "./files.js";
+/** A mistake in the command line, found before any request. */
+export class UsageError extends Error {
+}
+function parse(args, options) {
+    try {
+        return parseArgs({ args, options, allowPositionals: true, allowNegative: true, strict: true });
+    }
+    catch (error) {
+        throw new UsageError(error instanceof Error ? error.message : String(error));
+    }
+}
+const STRING = { type: "string" };
+const FLAG = { type: "boolean" };
+function command(spec, run) {
+    const scoped = spec.scoped ?? true;
+    return {
+        usage: spec.usage, about: spec.about, scoped,
+        async run(args, api) {
+            const { values, positionals } = parse(args, { ...spec.flags, project: STRING });
+            const key = "project" in values && typeof values.project === "string" ? values.project : undefined;
+            if (!scoped && key !== undefined)
+                throw new UsageError("Unknown option '--project'");
+            // A usage that doesn't start with an argument, such as `<n>`, takes none.
+            if (!spec.usage.startsWith("<") && positionals.length)
+                throw new UsageError(`Unexpected argument "${positionals[0]}"`);
+            return run({ ...api, values, positionals, project: () => api.project(key) });
+        },
+    };
+}
+function one(positionals) {
+    const [first, ...rest] = positionals;
+    if (first === undefined || rest.length)
+        throw new UsageError(`Expected one argument, got ${positionals.length}`);
+    return first;
+}
+/** An item number, written `42` or `#42`. */
+function number(value) {
+    const match = /^#?([1-9]\d*)$/.exec(value);
+    if (!match?.[1])
+        throw new UsageError(`"${value}" is not an item number`);
+    return Number(match[1]);
+}
+function numbers(positionals) {
+    if (!positionals.length)
+        throw new UsageError("Give item numbers");
+    return positionals.map(number);
+}
+/** A relative `/`-separated path with each part encoded for a URL. */
+const encode = (path) => path.split("/").map(encodeURIComponent).join("/");
+export const commands = {
+    list: command({
+        usage: "[--status open|resolved|all] [--tester <name>] [--version <v>]",
+        about: "Sessions, newest first, each with its items of --status (default open) and current reviewer trust",
+        flags: { status: STRING, tester: STRING, version: STRING },
+    }, async ({ values, project, json }) => {
+        const filter = Object.entries({ status: values.status ?? "open", tester: values.tester, version: values.version });
+        const query = new URLSearchParams(filter.filter((entry) => entry[1] !== undefined));
+        return json("GET", `${await project()}/sessions?${query}`);
+    }),
+    show: command({ usage: "<n> [--out <dir>]", about: "One item with current reviewer trust; --out saves its screenshot and audio there, adding their paths as `saved`", flags: { out: STRING } }, async ({ values, positionals, project, call, json }) => {
+        const n = number(one(positionals));
+        const path = `${await project()}/items/${n}`;
+        if (values.out === undefined)
+            return json("GET", path);
+        const item = z.looseObject({ n: z.number(), screenshot: z.boolean(), audio: z.string().nullable() }).parse(await json("GET", path));
+        const download = async (kind) => new Uint8Array(await (await call("GET", `${path}/${kind}`)).arrayBuffer());
+        return { ...item, saved: await save(item, values.out, download) };
+    }),
+    resolve: command({
+        usage: "<n...> [--reason fixed|duplicate|cannot-reproduce|wont-fix] [--of <n>] [--comment <text>]",
+        about: "Resolves items, as fixed unless --reason says why; --of <n> marks them duplicates of item n",
+        flags: { reason: STRING, of: STRING, comment: STRING },
+    }, async ({ values, positionals, project, json }) => {
+        const of = values.of === undefined ? undefined : number(values.of);
+        const body = { n: numbers(positionals), resolution: values.reason ?? (of === undefined ? "fixed" : "duplicate"), of, comment: values.comment };
+        return json("POST", `${await project()}/items/resolve`, body);
+    }),
+    reopen: command({ usage: "<n...>", about: "Opens resolved items again", flags: {} }, async ({ positionals, project, json }) => {
+        const n = numbers(positionals);
+        return json("POST", `${await project()}/items/reopen`, { n });
+    }),
+    publish: command({
+        usage: "<dir> [--version <v>] [--notes <file.md>]",
+        about: "Puts the build in <dir> live for testers as --version, default package.json's; --notes sends release notes, with the images and videos they point to",
+        flags: { version: STRING, notes: STRING },
+    }, async ({ values, positionals, project, call, json }) => {
+        const dir = one(positionals);
+        const version = values.version ?? await packageVersion();
+        if (!version)
+            throw new UsageError("Give --version, or run this where package.json has a version");
+        const paths = await walk(dir);
+        if (!paths.includes("index.html"))
+            throw new Error(`${dir} has no index.html at its top; build the app first`);
+        // Read before anything is uploaded, so a missing image fails the publish at once.
+        const notes = values.notes === undefined ? undefined : await releaseNotes(values.notes);
+        const releases = `${await project()}/releases`;
+        const release = `${releases}/${encodeURIComponent(version)}`;
+        await call("POST", releases, { version });
+        for (let i = 0; i < paths.length; i += 6) {
+            await Promise.all(paths.slice(i, i + 6).map(async (path) => call("PUT", `${release}/files/${encode(path)}`, await blob(join(dir, path)))));
+        }
+        for (const [path, file] of notes?.media ?? [])
+            await call("PUT", `${release}/media/${encode(path)}`, file);
+        return json("POST", `${release}/publish`, { notes: notes?.markdown });
+    }),
+    "reviewer list": command({ usage: "", about: "The people emailed about new versions, with their trust levels", flags: {} }, async ({ project, json }) => json("GET", `${await project()}/reviewers`)),
+    "reviewer add": command({
+        usage: "<email> [--name <name>] [--trust low|medium|high] [--every <days>] [--on major|minor|patch]",
+        about: "Adds a reviewer, or changes only the supplied settings of the one with that email; --trust: confidence in their feedback (default low); --every: days at least between emails (default 7); --on: smallest version change emailed (default major)",
+        flags: { name: STRING, trust: STRING, every: STRING, on: STRING },
+    }, async ({ values, positionals, project, json }) => {
+        const body = { email: one(positionals), name: values.name, trust: values.trust, every: values.every === undefined ? undefined : Number(values.every), on: values.on };
+        return json("POST", `${await project()}/reviewers`, body);
+    }),
+    "reviewer remove": command({ usage: "<email>", about: "Stops emailing a reviewer", flags: {} }, async ({ positionals, project, call }) => {
+        const email = one(positionals);
+        await call("DELETE", `${await project()}/reviewers/${encodeURIComponent(email)}`);
+        return { removed: email };
+    }),
+    "project create": command({ usage: "<name>", about: "Creates a project, with a `snippet` to start the integration from", flags: {}, scoped: false }, async ({ positionals, json }) => {
+        const project = z.looseObject({ key: z.string() }).parse(await json("POST", "projects", { name: one(positionals) }));
+        return { ...project, snippet: snippet(project.key) };
+    }),
+    "project list": command({ usage: "", about: "Your projects", flags: {}, scoped: false }, async ({ json }) => json("GET", "projects")),
+    "project set": command({
+        usage: "[--notify|--no-notify] [--signup|--no-signup]",
+        about: "--notify: emails you about new feedback; --signup: asks testers for their name and email",
+        flags: { notify: FLAG, signup: FLAG },
+    }, async ({ values, project, json }) => json("PATCH", await project(), { notify: values.notify, signup: values.signup })),
+    skill: command({ usage: "", about: "Prints the agent skill as text, which explains all of this", flags: {}, scoped: false }, async () => readFile(new URL("../../skills/feedback/SKILL.md", import.meta.url), "utf8")),
+};
+function snippet(key) {
+    return `import { feedback } from "@drawcall/feedback";
+
+let wasPaused = false;
+const fb = feedback({
+  project: "${key}",
+  renderer,
+  minutes: 10, // about how long the test takes, shown to testers first
+  task: "Try the new area and say what feels off.",
+  pause: () => {
+    wasPaused = app.paused;
+    app.paused = true; // simulations, animations, timers, audio; never rendering, camera or user movement
+    return { scene: app.scene.id }; // a few ids someone fixing a report would ask for first
+  },
+  resume: () => { app.paused = wasPaused; },
+});`;
+}

package/dist/cli/files.d.ts

@@ -0,0 +1,21 @@
+/** The local files the CLI reads and writes. */
+/** Saves an item's screenshot and audio, fetched by `download`, to `directory` and returns their paths. */
+export declare function save(item: {
+    n: number;
+    screenshot: boolean;
+    audio: string | null;
+}, directory: string, download: (kind: "screenshot" | "audio") => Promise<Uint8Array>): Promise<{
+    screenshot: string | null;
+    audio: string | null;
+}>;
+/** Every file under `directory` as a sorted `/`-separated relative path, leaving out dotfiles such as .DS_Store. */
+export declare function walk(directory: string): Promise<string[]>;
+/** A file as a blob with the type it is served with. */
+export declare function blob(path: string): Promise<Blob>;
+/** The `version` of the package.json in the working directory, or undefined without one. */
+export declare function packageVersion(): Promise<string | undefined>;
+/** The release notes at `file`, with the images and videos they point to. */
+export declare function releaseNotes(file: string): Promise<{
+    markdown: string;
+    media: Array<[string, Blob]>;
+}>;

package/dist/cli/files.js

@@ -0,0 +1,62 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import mime from "mime";
+import { z } from "zod";
+import { attachments } from "../notes.js";
+/** The local files the CLI reads and writes. */
+/** Saves an item's screenshot and audio, fetched by `download`, to `directory` and returns their paths. */
+export async function save(item, directory, download) {
+    await mkdir(directory, { recursive: true });
+    const write = async (kind, name) => {
+        const path = join(directory, name);
+        await writeFile(path, await download(kind));
+        return path;
+    };
+    return {
+        screenshot: item.screenshot ? await write("screenshot", `${item.n}.jpg`) : null,
+        audio: item.audio ? await write("audio", `${item.n}.${extension(item.audio)}`) : null,
+    };
+}
+/** Such as `webm` for `audio/webm;codecs=opus`. */
+function extension(type) {
+    const match = /^audio\/([\w.+-]+)/.exec(type);
+    if (!match?.[1])
+        throw new Error(`Unexpected audio type ${type}`);
+    return match[1];
+}
+/** Every file under `directory` as a sorted `/`-separated relative path, leaving out dotfiles such as .DS_Store. */
+export async function walk(directory) {
+    const entries = await readdir(directory, { recursive: true, withFileTypes: true });
+    return entries
+        .filter(entry => entry.isFile())
+        .map(entry => relative(directory, join(entry.parentPath, entry.name)).split(sep).join("/"))
+        .filter(path => !path.split("/").some(part => part.startsWith(".")))
+        .sort();
+}
+/** A file as a blob with the type it is served with. */
+export async function blob(path) {
+    return new Blob([await readFile(path)], { type: mime.getType(path) ?? "application/octet-stream" });
+}
+/** The `version` of the package.json in the working directory, or undefined without one. */
+export async function packageVersion() {
+    let file;
+    try {
+        file = await readFile("package.json", "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    return z.object({ version: z.string().optional() }).parse(JSON.parse(file)).version;
+}
+/** The release notes at `file`, with the images and videos they point to. */
+export async function releaseNotes(file) {
+    const markdown = await readFile(file, "utf8");
+    const media = await Promise.all(attachments(markdown).map(async (path) => {
+        if (!/^(?:image|video)\//.test(mime.getType(path) ?? ""))
+            throw new Error(`The notes point to ${path}; only images and videos can go with them`);
+        return [path, await blob(join(dirname(file), path))];
+    }));
+    return { markdown, media };
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The CLI's users are agents, so every command prints JSON: the response on stdout, or `{ error }` on stderr with exit
+ * code 1, or `{ error, usage }` with exit code 2 for a mistake in the command line, found before any request.
+ */
+export interface CliHost {
+    fetch: typeof globalThis.fetch;
+    token(): Promise<string | undefined>;
+    stdout(text: string): void;
+    stderr(text: string): void;
+    baseUrl?: string;
+    /** How the user runs this CLI, for the usage in help and errors. */
+    invocation?: string;
+}
+export declare function run(argv: string[], host: CliHost): Promise<number>;

package/dist/cli/index.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { CONTROL, ORIGIN } from "../service.js";
+import { commands, UsageError } from "./commands.js";
+const SIGN_IN = "Not signed in, or the sign-in expired: run `npx drawcall auth login`, or set DRAWCALL_AUTH_TOKEN";
+const ABOUT = "Every command prints JSON. Errors print {\"error\"} on stderr and exit 2 for misuse, 1 otherwise. "
+    + "--project <key> picks the project when you own several.";
+export async function run(argv, host) {
+    const invocation = host.invocation ?? "npx @drawcall/feedback";
+    const usage = (name) => {
+        const command = commands[name];
+        return [invocation, name, command?.usage, command?.scoped && "[--project <key>]"].filter(Boolean).join(" ");
+    };
+    if (argv[0] === "help" || argv.includes("--help") || argv.includes("-h")) {
+        host.stdout(stringify(help(argv[0] === "help" ? argv.slice(1) : argv, usage)));
+        return 0;
+    }
+    const name = [argv.slice(0, 2).join(" "), argv[0] ?? ""].find(name => Object.hasOwn(commands, name));
+    const command = name === undefined ? undefined : commands[name];
+    if (name === undefined || !command) {
+        const group = Object.keys(commands).filter(name => name.startsWith(`${argv[0]} `));
+        const error = group.length ? `Give one of ${group.join(", ")}` : argv.length ? `Unknown command "${argv[0]}"` : "Give a command";
+        host.stderr(stringify({ error: `${error}; see \`${invocation} --help\``, usage: `${invocation} <command>` }));
+        return 2;
+    }
+    try {
+        const result = await command.run(argv.slice(name.split(" ").length), api(host, invocation));
+        // Only `skill` answers with text, the skill itself.
+        host.stdout(typeof result === "string" ? result : stringify(result));
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            host.stderr(stringify({ error: error.message, usage: usage(name) }));
+            return 2;
+        }
+        host.stderr(stringify({ error: error instanceof Error ? error.message : String(error) }));
+        return 1;
+    }
+}
+/** The commands the words in `argv` name, such as all `reviewer` ones for `reviewer --help`; all of them without any. */
+function help(argv, usage) {
+    const under = (words) => Object.keys(commands).filter(name => `${name} `.startsWith(words.length ? `${words.join(" ")} ` : ""));
+    const words = argv.filter(arg => !arg.startsWith("-")).slice(0, 2);
+    // Drops words that name no command, such as the 42 of `show 42 --help`.
+    while (words.length && !under(words).length)
+        words.pop();
+    return { about: ABOUT, commands: Object.fromEntries(under(words).map(name => [name, { usage: usage(name), about: commands[name]?.about }])) };
+}
+/** The signed-in routes of feedback.drawcall.ai. */
+function api(host, invocation) {
+    const base = new URL("/api/v1/", host.baseUrl ?? ORIGIN);
+    let token;
+    /** Sends a blob as its own type, anything else as JSON. */
+    async function call(method, path, body) {
+        const bearer = await (token ??= host.token());
+        if (!bearer)
+            throw new Error(SIGN_IN);
+        const headers = { authorization: `Bearer ${bearer}` };
+        if (body !== undefined && !(body instanceof Blob))
+            headers["content-type"] = "application/json";
+        const payload = body instanceof Blob || body === undefined ? body : JSON.stringify(body);
+        const response = await host.fetch(new URL(path, base), { method, headers, body: payload });
+        if (response.ok)
+            return response;
+        if (response.status === 401)
+            throw new Error(SIGN_IN);
+        const error = z.object({ message: z.string() }).safeParse(await response.json().catch(() => undefined));
+        throw new Error(`Feedback request failed (${response.status})${error.success ? `: ${error.data.message}` : ""}`);
+    }
+    const json = async (method, path, body) => (await call(method, path, body)).json();
+    async function project(key) {
+        const projects = z.array(z.object({ key: z.string(), name: z.string() })).parse(await json("GET", "projects"));
+        if (key) {
+            if (!projects.some(project => project.key === key))
+                throw new Error(`You have no project ${key}; \`${invocation} project list\` shows yours`);
+            return `projects/${key}`;
+        }
+        const [only, ...others] = projects;
+        if (!only)
+            throw new Error(`You have no projects yet; create one with \`${invocation} project create <name>\``);
+        if (others.length)
+            throw new Error(`You own ${projects.length} projects, so pass --project with one of ${projects.map(one => `${one.key} (${one.name})`).join(", ")}`);
+        return `projects/${only.key}`;
+    }
+    return { call, json, project };
+}
+/**
+ * Pretty JSON with every `CONTROL` character in its strings escaped: `JSON.stringify` escapes only C0 ones, and a
+ * terminal acts on raw C1 ones just the same, such as U+009B, which starts a control sequence. Its own line breaks stay.
+ */
+function stringify(data) {
+    return JSON.stringify(data, null, 2)
+        .replace(new RegExp(CONTROL, "g"), char => (char === "\n" ? char : `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`));
+}

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+import type { WebGLRenderer } from "three";
+import type { WebGPURenderer } from "three/webgpu";
+export type Renderer = WebGLRenderer | WebGPURenderer;
+/**
+ * The look of everything feedback shows: the intro and the captions and button over the app. Colors take any CSS
+ * color; the muted text and quiet fills are mixed from `text`, so a light theme works as well as a dark one.
+ */
+export interface Theme {
+    /** A logo image's URL, shown at the top of the intro. */
+    logo?: string;
+    /** A CSS font-family. A web font must already be loaded by the page. */
+    font?: string;
+    /** The intro's page. */
+    background?: string;
+    /** The plates behind captions and the corner button, slightly translucent over the app. */
+    surface?: string;
+    text?: string;
+    /** Buttons and highlights, such as Start and Send. */
+    accent?: string;
+    /** Text on `accent`. */
+    onAccent?: string;
+    /** Corner radius in pixels. */
+    radius?: number;
+}
+/**
+ * A device a test can be for: a preset the intro already tells apart (Meta Quest's browser, a touch phone or
+ * tablet, or anything else as a computer), or the app's own check with the name testers read, such as
+ * `{ name: "Apple Vision Pro", matches: () => /VisionOS/.test(navigator.userAgent) }`.
+ */
+export type Target = "desktop" | "phone" | "quest" | {
+    name: string;
+    matches: () => boolean | Promise<boolean>;
+};
+/**
+ * A question on the closing screen, after the app calls `finish()`. Every one is optional for the tester. `id` names
+ * it in the answers, so keep it stable when the wording changes between versions. A `scale` is a slider from `min` to
+ * `max`, with words for its two ends; a `choice` takes one of its `options`, or several when `multiple`.
+ */
+export type Question = {
+    type: "scale";
+    id: string;
+    ask: string;
+    min: number;
+    max: number;
+    step?: number;
+    labels?: [string, string];
+} | {
+    type: "choice";
+    id: string;
+    ask: string;
+    options: string[];
+    multiple?: boolean;
+};
+export interface FeedbackOptions {
+    /** The public project key, `fbk_pub_…`. */
+    project: string;
+    /**
+     * The renderer whose frames the tester can show. The screenshot is taken from the next frame it renders, so an app
+     * that renders on demand (such as React Three Fiber's `frameloop="demand"`) must keep rendering while feedback is on.
+     */
+    renderer: Renderer;
+    /**
+     * The build being tested, such as `1.4.0`, recorded with each session: up to 32 letters, digits and `. _ + -`. A page
+     * `publish` serves always records the published version instead.
+     */
+    version?: string;
+    /** About how long the test takes, in whole minutes up to 120, shown to testers before they start. */
+    minutes?: number;
+    /** What testers are asked to do, shown before they start, such as "Find the crater and say what feels off." */
+    task?: string;
+    theme?: Theme;
+    /**
+     * The devices the test is for, when only some are. On any other, the intro first says which ones, with the link
+     * to open there, and lets the tester go on anyway; the device is recorded with their session either way.
+     */
+    devices?: Target[];
+    /**
+     * Asked on the closing screen, above the space for a last word; answers are stored with the tester's session. Up to 20,
+     * each with an id of up to 64 characters, wording of up to 200, and up to 20 options or labels of up to 200 each.
+     */
+    questions?: Question[];
+    /**
+     * Runs when a feedback turn starts, never for the intro or at load. Freezes the simulation, never rendering or the
+     * user's movement, and returns a few plain-JSON facts. When it throws, the turn goes on without them.
+     */
+    pause?: () => unknown;
+    /**
+     * Undoes `pause()`. Runs once the tester is done: after they show what they mean, or once their feedback is known
+     * to need no screenshot, at most about 12 s after they stop talking. Also runs at dispose. The upload may still be
+     * running; its outcome shows once it is done.
+     */
+    resume?: () => void;
+}
+export interface Feedback {
+    /**
+     * Call where the experience ends. Records that the tester went through it, then, once any feedback in progress is
+     * done, shows the closing screen: the app's `questions` and an optional last word on the whole experience, written or
+     * spoken, then thanks with the offer to try again, since the finished app stays behind it. That screen is a page,
+     * so an XR session ends for it. Once per page load; it does nothing outside feedback mode.
+     */
+    finish(): void;
+    /** Stops recording, resumes if paused, and unhooks the renderer. */
+    dispose(): void;
+}
+/**
+ * Turns on voice feedback when the URL has `?feedback`, or on a page `publish` serves. Otherwise it only
+ * reads the URL, the page's meta tags and web storage, and loads nothing else.
+ */
+export declare function feedback(options: FeedbackOptions): Feedback;

package/dist/index.js

@@ -0,0 +1,75 @@
+import { readTester } from "./tester.js";
+import { CONTROL, LIMITS, VERSION_FORMAT, VERSION_META } from "./service.js";
+/**
+ * Turns on voice feedback when the URL has `?feedback`, or on a page `publish` serves. Otherwise it only
+ * reads the URL, the page's meta tags and web storage, and loads nothing else.
+ */
+export function feedback(options) {
+    // Checked on every load, so a mistake shows while developing rather than only at the end of a test.
+    check(options);
+    const published = typeof document === "undefined" ? null : (document.querySelector(`meta[name="${VERSION_META}"]`)?.content ?? null);
+    const tester = currentTester(published !== null);
+    if (!tester)
+        return { finish() { }, dispose() { } };
+    const disposal = new AbortController();
+    let finish = () => { };
+    const finished = new Promise(resolve => (finish = resolve));
+    void import("./browser/run.js").then(({ run }) => run({ options, tester, version: published ?? options.version ?? null, finished, signal: disposal.signal }));
+    return { finish, dispose: () => disposal.abort() };
+}
+/** Holds the options to what the service accepts, which would otherwise refuse the session or its answers. */
+function check({ version, minutes, questions = [] }) {
+    if (version !== undefined && !VERSION_FORMAT.test(version)) {
+        throw new Error(`feedback: version takes up to ${LIMITS.version} letters, digits and . _ + -, starting with a letter or digit, not "${version}"`);
+    }
+    if (minutes !== undefined && !(Number.isInteger(minutes) && minutes >= 1 && minutes <= LIMITS.minutes)) {
+        throw new Error(`feedback: minutes takes a whole number from 1 to ${LIMITS.minutes}, not ${minutes}`);
+    }
+    if (questions.length > LIMITS.questions)
+        throw new Error(`feedback: ${questions.length} questions, over the ${LIMITS.questions} allowed`);
+    const ids = new Set();
+    for (const question of questions) {
+        const { id } = question;
+        text(id, LIMITS.id, "a question's id");
+        text(question.ask, LIMITS.ask, `question "${id}"`);
+        if (ids.has(id))
+            throw new Error(`feedback: two questions have the id "${id}"`);
+        ids.add(id);
+        if (question.type === "scale") {
+            const { min, max, step = 1, labels = [] } = question;
+            if (!(Number.isFinite(min) && Number.isFinite(max) && min < max))
+                throw new Error(`feedback: question "${id}" needs min below max`);
+            if (!(Number.isFinite(step) && step > 0))
+                throw new Error(`feedback: question "${id}" needs a step above 0`);
+            for (const label of labels)
+                text(label, LIMITS.option, `a label of question "${id}"`);
+        }
+        else {
+            const { options } = question;
+            if (options.length < 2 || options.length > LIMITS.options) {
+                throw new Error(`feedback: question "${id}" needs from 2 to ${LIMITS.options} options, not ${options.length}`);
+            }
+            for (const option of options)
+                text(option, LIMITS.option, `an option of question "${id}"`);
+        }
+    }
+}
+/** Text the service stores: not empty, at most `max` characters, and plain. */
+function text(value, max, what) {
+    if (!value || value.length > max)
+        throw new Error(`feedback: ${what} takes from 1 to ${max} characters, not ${value.length}`);
+    if (CONTROL.test(value))
+        throw new Error(`feedback: ${what} holds a control character`);
+}
+function currentTester(published) {
+    if (typeof location === "undefined")
+        return null;
+    try {
+        return readTester(location.search, { session: sessionStorage, local: localStorage }, published);
+    }
+    catch (error) {
+        // Sandboxed iframes throw on any storage access; an app must keep running there, just without feedback.
+        console.warn("feedback: web storage is blocked here, so feedback mode stays off", error);
+        return null;
+    }
+}

package/dist/notes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Release notes: Markdown that `publish --notes` sends with a version, and reviewers get in their email. Images and
+ * videos it points to by relative path, such as `![The new door](shots/door.gif)`, are uploaded with it.
+ */
+/** Whether a target is a file next to the notes rather than a URL, a page anchor or a site-absolute path. */
+export declare function isLocal(target: string): boolean;
+/** A local target as the `/`-separated path it is uploaded at, such as `shots/door.gif` for `./shots/door.gif`. */
+export declare function localPath(target: string): string;
+/** The local files the notes point to, each once. */
+export declare function attachments(markdown: string): string[];
+/** The notes with every local target replaced by `url(path)`, for the plain-text email. */
+export declare function absolute(markdown: string, url: (path: string) => string): string;

package/dist/notes.js

@@ -0,0 +1,23 @@
+/**
+ * Release notes: Markdown that `publish --notes` sends with a version, and reviewers get in their email. Images and
+ * videos it points to by relative path, such as `![The new door](shots/door.gif)`, are uploaded with it.
+ */
+/** A Markdown link or image target, `](target)` or `](<target> "title")`. */
+const TARGET = /\]\(\s*<?([^)\s>]+)>?(?:\s+(?:"[^"]*"|'[^']*'))?\s*\)/g;
+/** Whether a target is a file next to the notes rather than a URL, a page anchor or a site-absolute path. */
+export function isLocal(target) {
+    return !/^(?:[a-z][a-z0-9+.-]*:|\/|#)/i.test(target);
+}
+/** A local target as the `/`-separated path it is uploaded at, such as `shots/door.gif` for `./shots/door.gif`. */
+export function localPath(target) {
+    return decodeURI(target).replace(/^(?:\.\/)+/, "");
+}
+/** The local files the notes point to, each once. */
+export function attachments(markdown) {
+    const paths = [...markdown.matchAll(TARGET)].map(match => match[1] ?? "").filter(isLocal).map(localPath);
+    return [...new Set(paths)];
+}
+/** The notes with every local target replaced by `url(path)`, for the plain-text email. */
+export function absolute(markdown, url) {
+    return markdown.replace(TARGET, (whole, target) => (isLocal(target) ? whole.replace(target, url(localPath(target))) : whole));
+}

package/dist/service.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Where the service runs and what it accepts. Free of zod, so the browser SDK can import it without shipping a
+ * schema library; `api.ts` builds its schemas on these.
+ */
+export declare const ORIGIN = "https://feedback.drawcall.ai";
+/**
+ * The `<meta>` the service adds to each page of a published build, holding its version. Its presence alone turns
+ * feedback mode on.
+ */
+export declare const VERSION_META = "drawcall-feedback-version";
+export declare const LIMITS: {
+    /** Bytes of `JSON.stringify(state)`. */
+    readonly state: number;
+    readonly audio: number;
+    /** Seconds of recording. */
+    readonly seconds: 90;
+    /** Characters of typed feedback. */
+    readonly text: 2000;
+    readonly screenshot: number;
+    /** Characters of a version's release notes. */
+    readonly notes: 20000;
+    /** Bytes of one image or video the release notes point to. */
+    readonly media: number;
+    /** Characters of a version, such as `1.4.0`. */
+    readonly version: 32;
+    /** The game's `minutes` option, the playtest's length in whole minutes. */
+    readonly minutes: 120;
+    /** Closing questions a game asks, and so answers a session stores. */
+    readonly questions: 20;
+    /** Options of one choice question. */
+    readonly options: 20;
+    /** Characters of a closing question's id. */
+    readonly id: 64;
+    /** Characters of a closing question's wording. */
+    readonly ask: 200;
+    /** Characters of one option of a choice question, or one end's label of a scale. */
+    readonly option: 200;
+    /** Characters of a tester's name. */
+    readonly name: 64;
+    /** Characters of an email address. */
+    readonly contact: 254;
+    /** Characters of the device description. */
+    readonly device: 200;
+};
+/** A version: letters, digits and `. _ + -`, starting with a letter or digit; safe in a URL path and an HTML attribute as it is. */
+export declare const VERSION_FORMAT: RegExp;
+/**
+ * A character plain text never holds: a C0 or C1 control character, which could rewrite the owner's terminal, or a bidi
+ * control, which could make text read differently than it runs where it ends up in a shell command or an email.
+ */
+export declare const CONTROL: RegExp;
+/** `text` without `CONTROL` characters, except those `keep` lists, such as "\t\n" for text typed in a field of its own. */
+export declare function stripControl(text: string, keep?: string): string;