From 71cf9caeb601e387296cbddcfb95680b8d2c73e8 Mon Sep 17 00:00:00 2001 From: Aqua Date: Fri, 13 Nov 2026 12:17:32 +0000 Subject: [PATCH] aqua-listen: autosave keyed on kit id and clip ids, not the content hash (#51) --- tools/aqua-listen/README.md | 9 +++--- tools/aqua-listen/logic.cjs | 41 ++++++++++++++++++++++++- tools/aqua-listen/smoke.mjs | 56 +++++++++++++++++++++++++++++++++-- tools/aqua-listen/test.mjs | 53 +++++++++++++++++++++++++++++++++ tools/aqua-listen/web/page.js | 14 ++++++--- 5 files changed, 162 insertions(+), 11 deletions(-) diff --git a/tools/aqua-listen/README.md b/tools/aqua-listen/README.md index 44b9f5a..e0c0e7d 100644 --- a/tools/aqua-listen/README.md +++ b/tools/aqua-listen/README.md @@ -18,13 +18,13 @@ A listening-test kit: a folder of sound clips and a manifest become **one HTML f 7. Your answers save themselves in your browser as you go. You can close the tab and come back to the same file later. 8. When done, press **Export my answers**. Your answers appear in a text box. Press **Copy answers (JSON)** and paste them into a message to whoever gave you the page (or press **Share**, or **Select all** and use your phone's Copy). **Download verdict.json** and **Download verdict.md** are separate buttons, one file per tap, for browsers that allow downloads. Nothing leaves your computer except what you copy, share or download. -Privacy: the page has no network access at all (the browser is told to refuse it), no account, no tracking. "Erase my answers" at the bottom wipes what the page saved. +Privacy: the page has no network access at all (the browser is told to refuse it), no account, no tracking. "Erase this kit's saved answers" at the bottom removes what this page saved in this browser for this kit, including an older saved copy of it that the page would otherwise adopt; other pages are not touched. ## For the person building a kit ``` node build.mjs --manifest kit.json --clips ./clips --out ./dist # writes dist/listen.html -node test.mjs # 17 checks, no dependencies, no browser +node test.mjs # 23 checks, no dependencies, no browser node smoke.mjs dist/listen.html # optional browser smoke, see below ``` @@ -42,7 +42,8 @@ node smoke.mjs dist/listen.html # optional - Title, id and group are hidden from the listener and appear only in the export. The intended feel is shown, since "did it land" needs it. - Order is shuffled from a random seed kept with the listener's answers (it is in the export). A pair is shuffled as one unit, with A/B position shuffled inside it. - Audio is embedded as-is (base64), so the page is about 1.4x the clip bytes. The build warns over 100 MB. -- Autosave key is the kit id plus a hash of the manifest and clip bytes: a rebuilt kit with changed clips starts fresh instead of mixing answers. +- Autosave key is the kit id plus the sorted clip ids (`aqua-listen.v2::`), not the content hash: a rebuilt page (edited note, re-rendered clip) keeps the listener's answers, and a kit with a different clip-id set starts fresh while the old entry stays in the browser. Saved state is the shuffle seed, answers by clip id and pair choices by `idA|idB`; a pair's A/B/same value is positional (A is the first of the pair in the seed's order), so it holds only while the manifest's clip order is unchanged. When the new key is empty, the page adopts the fullest earlier `aqua-listen::` save whose answers name only this kit's clips; a save already under the new key is never overwritten. The save also records `pairSig`, the manifest's clip ids in manifest order: on load, a save whose `pairSig` is missing or different keeps its seed and answers and drops its pair picks, so reordering or re-pairing clips never reassigns a pick (an adopted hash-keyed save has no signature and cannot be checked, so its pairs are kept and stamped with the current one). A save missing `pairs`, or with `answers` that is not an object, is normalised to empty rather than crashing the page. "Erase this kit's saved answers" removes the new key and any adoptable hash-keyed save of this kit. +- Known limits: a clip re-rendered under the same id inherits the verdict given to its earlier version, because answers are keyed by id. A stale cached copy of an old page keeps writing to its old hash key, which the new page does not read after it has adopted its copy. ### Export @@ -52,7 +53,7 @@ The blank verdict files this was meant to match were not found under `/opt/commo ### Browser smoke -`PLAYWRIGHT_CORE=/path/to/playwright-core CHROME=/path/to/chrome node smoke.mjs dist/listen.html` ticks through consent, answers a clip, reloads, exports, and fails on any network request or page error. It is not in `node test.mjs` because the repo carries no browser dependency. +`PLAYWRIGHT_CORE=/path/to/playwright-core CHROME=/path/to/chrome node smoke.mjs dist/listen.html` ticks through consent, answers a clip, reloads, exports, then serves the page over a local http server, rebuilds it with a different content hash and checks that answers survive, that a hash-keyed save is adopted, and that erase leaves nothing to resurrect; it fails on any network request or page error. It is not in `node test.mjs` because the repo carries no browser dependency. ### Kits in the repo diff --git a/tools/aqua-listen/logic.cjs b/tools/aqua-listen/logic.cjs index e7aec25..9944372 100644 --- a/tools/aqua-listen/logic.cjs +++ b/tools/aqua-listen/logic.cjs @@ -100,4 +100,43 @@ function verdictMarkdown(v) { return L.join("\n") + "\n"; } -module.exports = { SCHEMA, VERDICTS, DEVICES, AUDIO_EXT, validateManifest, planOrder, buildVerdict, verdictMarkdown, rng }; +// Autosave. The key names the kit by its id and its clip-id set, not by the content hash: a rebuild that fixes a note or +// re-renders a clip is the same kit and keeps the listener's answers; a different clip-id set is a different kit and starts +// fresh (the old entry is left untouched in the browser). Saved state is answers by clip id and pairs by "idA|idB", plus the +// seed; the A/B/same value of a pair is positional (A is the first of the pair in the seed's order), so it stays meaningful +// only while the manifest's clip order is unchanged. +const SAVE_PREFIX = "aqua-listen.v2:"; +function saveKey(manifest) { return `${SAVE_PREFIX}${manifest.kit.id}:${manifest.clips.map((c) => c.id).sort().join(",")}`; } + +// Earlier pages keyed the save by `aqua-listen::<8-hex content hash>`. Given every localStorage entry as +// [{key, state}] (state already parsed, null if unparseable), returns the key of the legacy entry to adopt, or null: +// same kit id, a seed, and answers/pairs that mention only clip ids of this kit. Fullest entry wins (most answered fields); +// ties go to the later key so the choice is deterministic. +function pickLegacySave(manifest, entries) { + const ids = new Set(manifest.clips.map((c) => c.id)), prefix = `aqua-listen:${manifest.kit.id}:`; + let best = null, bestScore = -1; + for (const { key, state } of entries) { + if (typeof key !== "string" || !key.startsWith(prefix) || !/^[0-9a-f]{8}$/.test(key.slice(prefix.length))) continue; + if (!state || typeof state !== "object" || !state.seed || typeof state.answers !== "object" || !state.answers) continue; + const pairs = state.pairs && typeof state.pairs === "object" ? state.pairs : {}; + if (!Object.keys(state.answers).every((id) => ids.has(id))) continue; + if (!Object.keys(pairs).every((k) => k.split("|").every((id) => ids.has(id)))) continue; + const score = Object.values(state.answers).reduce((n, a) => n + (a ? ["verdict", "landed", "reason"].filter((f) => a[f]).length : 0), 0) + Object.keys(pairs).length; + if (score > bestScore || (score === bestScore && key > best)) { best = key; bestScore = score; } + } + return best; +} + +// A save as stored -> the state the page runs on, or null. Normalises answers/pairs to plain objects (a hand-edited or old save +// must not crash the page). pairSig records the manifest's clip order the pair picks were made under; a pick's A/B/same is +// relative to that order, so a save with a missing or different pairSig keeps seed and answers and loses its pairs. A legacy +// (hash-keyed) save has no pairSig and cannot be checked: its pairs are kept and stamped with the current signature. +const pairSig = (manifest) => manifest.clips.map((c) => c.id).join(","); +const plain = (o) => (o && typeof o === "object" && !Array.isArray(o) ? o : {}); +function restoreSave(manifest, saved, legacy) { + if (!saved || typeof saved !== "object" || !saved.seed) return null; + const sig = pairSig(manifest), keep = legacy || saved.pairSig === sig; + return Object.assign({}, saved, { answers: plain(saved.answers), pairs: keep ? plain(saved.pairs) : {}, pairSig: sig }); +} + +module.exports = { SCHEMA, VERDICTS, DEVICES, AUDIO_EXT, validateManifest, planOrder, buildVerdict, verdictMarkdown, rng, saveKey, pickLegacySave, pairSig, restoreSave }; diff --git a/tools/aqua-listen/smoke.mjs b/tools/aqua-listen/smoke.mjs index 91bd3d0..b31282d 100644 --- a/tools/aqua-listen/smoke.mjs +++ b/tools/aqua-listen/smoke.mjs @@ -1,8 +1,11 @@ // Browser smoke for a built page: node smoke.mjs listen.html (needs playwright-core and a Chromium; set PLAYWRIGHT_CORE=/path/to/playwright-core // and optionally CHROME=/path/to/chrome). Not part of `node test.mjs`: the repo has no browser dependency. import { createRequire } from "node:module"; -import { readFileSync } from "node:fs"; -import { resolve } from "node:path"; +import { readFileSync, writeFileSync, mkdtempSync } from "node:fs"; +import { createServer } from "node:http"; +import { tmpdir } from "node:os"; +import { buildKit } from "./build.mjs"; +import { resolve, join } from "node:path"; const { chromium } = createRequire(import.meta.url)(process.env.PLAYWRIGHT_CORE ?? "playwright-core"); const file = resolve(process.argv[2]); const browser = await chromium.launch({ executablePath: process.env.CHROME || undefined }); @@ -46,4 +49,53 @@ await page.click("#export"); check((await page.inputValue("#export-text")).includes('"verdict": "fix"'), "reload loses nothing: export after reload still has the answers"); check(requests.length === 0, `no network requests (${requests.join(", ")})`); check(errors.length === 0, `no page errors (${errors.join("; ")})`); +// ---- Autosave persistence across a rebuild. Served over http at one fixed path so the origin (and localStorage) is the same for +// the page as given (A) and a rebuild of the same kit with a different content hash (B: a note edit and one byte appended to a clip). +const html = readFileSync(file, "utf8"), kit = JSON.parse(html.match(/