sign-off-axi 0.5.7 → 0.5.9

package/README.md

@@ -87,6 +87,7 @@ One line on what the agent runs per kind; the full reference is [docs/question-k
 |---|---|---|
 | Yes or no, pick one | `raise --ask-ref <captain-message-id-or-hold-id> --title ... --recommend ...` | buttons, the recommended one first |
 | Design pick (mocks A/B/C) | `post --type design --mock a=... --mock b=... --link a=<url>` | mocks side by side, an Open live link under each option that has a `--link`, a note on any part |
+| Design review (screens of a product) | `post --kind design --from design.json` | nothing in Decide: it waits under **Designs** for Main to review; once Main passes every screen, the lead posts one card per product that opens them all, phone and desktop, and Main's `promote <key>` puts that card in Decide |
 | Proof update | `post --type evidence --media shot.png` | the capture, its result, Pass / Fail / Needs work |
 | Proof with a file to install | `post --type evidence --media shot.png --attach app.apk` | the capture, and the file with its size and a Download button (any type, up to 1 GB, `SIGN_OFF_ATTACH_MAX_MB` to change) |
 | Explainer video | `post --type explainer --media clip.mp4 --chapter 0:00=Start` | a player with chapter buttons, then Yes or No |
@@ -118,6 +119,7 @@ sign-off stands alone: the CLI and the skill need no other tool and no superviso
 - [Question kinds](docs/question-kinds.md): the reference for each kind.
 - [Contract](docs/contract.md): the message rules agents post by.
 - [File formats](docs/file-formats.md): board and message files.
+- [Vision](VISION.md): who sign-off is for and where it is going.
 
 ## Development
 

package/dist/cli.js

@@ -7,15 +7,17 @@ import { accessSync, chmodSync, closeSync, constants, copyFileSync, createReadSt
 import { lookup } from 'node:dns/promises';
 import { availableParallelism, homedir, tmpdir, userInfo } from 'node:os';
 import { Worker } from 'node:worker_threads';
+import { brotliCompressSync, constants as zlib, gzipSync } from 'node:zlib';
 import { pipeline } from 'node:stream';
 import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { parseArgs } from 'node:util';
 import { encode } from '@toon-format/toon';
 import { acknowledgeOwner, checkOwner, deliveries, dispatchOwners, registerOwner } from './owner.js';
 import { AxiError, runAxiCli } from 'axi-sdk-js';
-import { ATTACH_DEFAULT_MB, ATTACH_MAX, ATTACH_NAME, CHAPTERS_MAX, SIGNED_IN, CLEARED, InputError, MEDIA_MAX, NOTE_MAX, REPLY, answersPath, appendAnnotation, appendPartComment, annotationsPath, markCommentsRead, readPartComments, replyComment, asks, appendAnswer, appendDismissed, appendSendBack, appendDesignAnswer, appendMessage, appendRound, awaitsVerdict, lapsed, askEngagement, checkEngagement, markEngagementSeen, appendRead, appendOpened, readOpened, answerDeeper, askDeeper, deeperPath, guidePart, markDeeperRead, readDeeper, readReads, seenAt, isKey, loadDecisions, markDelivered, markSeen, messagesPath, readAnnotations, readAnswers, reading, readDismissed, readItems, sameDecision, readMessages, readRounds, roundsPath, seenBy, seenPath, sentIds, unreadable as reasonOf, writeItems } from './store.js';
+import { ATTACH_DEFAULT_MB, ATTACH_MAX, ATTACH_NAME, CHAPTERS_MAX, SIGNED_IN, CLEARED, InputError, MEDIA_MAX, NOTE_MAX, REPLY, answersPath, appendAnnotation, appendPartComment, annotationsPath, markCommentsRead, readPartComments, replyComment, asks, appendAnswer, appendDismissed, appendPromoted, appendSendBack, appendDesignAnswer, appendMessage, appendRound, awaitsVerdict, lapsed, askEngagement, checkEngagement, markEngagementSeen, appendRead, appendOpened, readOpened, answerDeeper, askDeeper, deeperPath, guidePart, markDeeperRead, readDeeper, readReads, seenAt, isKey, loadDecisions, markDelivered, markSeen, messagesPath, readAnnotations, readAnswers, reading, readDismissed, readItems, readPromoted, sameDecision, readMessages, readRounds, roundsPath, seenBy, seenPath, sentIds, unreadable as reasonOf, writeItems } from './store.js';
 import { ContractError, KINDS, MEDIA_BYTES, REPORT_INIT, checkMessage, diagramPages, diagramViews, guided, mediaFiles, parseMessage, reportPage } from './contract.js';
 import { faults, isStill } from './evidence-text.js';
+import { copiesOf } from './images.js';
 import { deliverVault, errors, readVaultExpiry, sweepVault, takeVaultExpiries, VaultError } from './vault.js';
 const FORMAT = 'https://github.com/umeranjum17/sign-off/blob/main/docs/file-formats.md';
 const CONTRACT = 'https://github.com/umeranjum17/sign-off/blob/main/docs/contract.md';
@@ -30,8 +32,8 @@ const AGENTS = {
     'gemini-cli': { bin: 'gemini', dir: '.agents/skills', home: join(homedir(), '.gemini', 'skills') },
 };
 const TOP_HELP = `usage: sign-off-axi [command] [board.json] [flags]
-commands[23]:
-  (none)=list, raise, post, answers, wait, poll, deeper, owner, open, status, stop, serve, export, init, report, signin, dismiss, restore, refile, doctor, notify, validate, help
+commands[24]:
+  (none)=list, raise, post, answers, wait, poll, deeper, owner, open, status, stop, serve, export, init, report, signin, dismiss, restore, promote, refile, doctor, notify, validate, help
 board: the nearest .sign-off/ board (the walk's bounds and SIGN_OFF_HOME: README, "Test runs never touch your board"), else ~/.sign-off/decisions.json; a board file given always wins
 flags: --full and --json on list, answers and wait, --events on wait, --json on status, --filer on post, raise and wait, --help on every command, -v/--version
 examples:
@@ -225,7 +227,7 @@ An empty items list removes that filer's items.
 --type diagram and --type interactive are a decision shown with a picture: --view names one board-relative file,
 an image (.svg, .png, .jpg, .jpeg, .webp, 5 MB or less) shown at card width for a diagram, or one self-contained .html page for interactive.
 The page runs in a sandboxed frame: no fetch, no remote files, no access to the dashboard or its tab. Answers work as for a decision.
---type evidence posts the next numbered update (key update-<number>): 1 to ${MEDIA_MAX} screenshots or recordings (.png, .jpg, .jpeg, .webp, .mp4, .webm, 50 MB each), copied into evidence/<number>/ next to the board, with a short note and an optional commit or PR link. A still that is not a picture of the product is refused: mostly text (a log, receipt or summary), a colour-bar test card or a placeholder card. Post a real capture of the running product; a colour-bar or placeholder card already posted is not shown on the board.
+--type evidence posts the next numbered update (key update-<number>): 1 to ${MEDIA_MAX} screenshots or recordings (.png, .jpg, .jpeg, .webp, .mp4, .webm, 50 MB each), copied into evidence/<number>/ next to the board (each still also gets a lighter copy and a thumbnail there, which the board shows; the original stays and opens full size), with a short note and an optional commit or PR link. A still that is not a picture of the product is refused: mostly text (a log, receipt or summary), a colour-bar test card or a placeholder card. Post a real capture of the running product; a colour-bar or placeholder card already posted is not shown on the board.
 --attach <file> (up to ${ATTACH_MAX}, any file type, such as an Android .apk) adds a file the user downloads from the card, over the board link, on a phone or tablet. It is copied (never read into memory) into evidence/<number>/ and streamed on download. A file over ${ATTACH_DEFAULT_MB} MB is refused; raise the limit with SIGN_OFF_ATTACH_MAX_MB=<megabytes>. An update may have only --attach files and no --media.
 The user gives a verdict, pass, fail or needs-work, with an optional note; read it with answers or wait --key update-<number>.
 --type explainer is a decision shown with a narrated video you made: one --media .mp4 or .webm (50 MB or less), copied into evidence/<number>/ like evidence
@@ -254,6 +256,7 @@ examples:
   sign-off-axi post --kind plan --from plan.json --filer agent-41
   sign-off-axi post --kind design --from design.json --filer agent-41
 A design message lists project journeys, per-screen image or HTML view variants, and a card preview; post checks every asset stays under the board folder.
+A design shows under Designs for Main to review, never in the user's Decide or any count of asks, until Main runs promote (see promote --help).
   sign-off-axi post .sign-off/decisions.json --type interactive --title "Does the sign-in flow feel right?" --view mocks/sign-in/demo.html --option yes=Yes --option no="Needs work" --recommend yes
   sign-off-axi post --type evidence --title "Sign-in screen on a phone" --about "The new screen loads in 1 second." --media phone.png --media flow.mp4 --link https://github.com/acme/app/pull/12
   sign-off-axi post --type evidence --title "Debug build for the phone" --about "The app installs and signs in." --media phone.png --attach app-debug.apk
@@ -286,6 +289,15 @@ examples:
 `,
     restore: `usage: sign-off-axi restore <key> [board.json]
 Brings back a card that dismiss hid. See \`sign-off-axi dismiss --help\`.
+`,
+    promote: `usage: sign-off-axi promote <key> [board.json] [--undo]
+For Main only, never a lead. A design review a lead posts (post --kind design) shows under Designs, where Main reviews it; it never waits in Decide or counts as the user's ask.
+Once Main has passed every screen, the lead posts one design per product that opens all its screens, phone and desktop, and Main promotes that one card:
+it then waits in Decide, counts there and notifies like any ask until the user answers it. --undo puts it back under Designs only.
+It writes one line to <board>.promoted.jsonl beside the board; no post, feed or board request writes that file.
+examples:
+  sign-off-axi promote fleet-dashboard-prototype
+  sign-off-axi promote fleet-dashboard-prototype --undo
 `,
     report: `usage: sign-off-axi report init <folder> [--plan] [--page]
 Writes the guided template to fill: <folder>/report.json, or <folder>/plan.json with --plan. A file already there is kept.
@@ -572,6 +584,8 @@ const waitFor = (on, filer, key) => (filer ? `Run \`sign-off-axi wait${on} --fil
     : `Run \`sign-off-axi wait${on}${key ? ` --key ${key}` : ''}\` to block until the user answers`);
 /** Still waiting on the user: not answered, not dismissed, not an expired sign-in, and something to answer (an item with no options and no reply is only shown). */
 const waits = (d) => asks(d) && !lapsed(d) && !d.dismissed && awaitsVerdict(d.type, d.answer);
+/** Waiting on the user, as Decide counts it: a design review waits on Main instead until Main promotes it (web/index.html area() says the same); its poster's wait still waits for the verdict. */
+const asksUser = (d) => waits(d) && (d.kind !== 'design' || !!d.promoted);
 /** The items that archive after a day: all of them, except on a board another program feeds, which owns what it shows. */
 const archivable = (file, decisions) => ((x) => (x.readonly === true || x.answers_only === true ? [] : decisions))(readItems(file).extra);
 /** The board's decisions with their latest answer; a missing board file is an empty board.
@@ -584,7 +598,8 @@ function board(file, say = warn) {
     for (const key of Object.keys(answers))
         if (!decisions.some((d) => d.key === key))
             say(`left out the answer for ${key}: that question is no longer in ${basename(file)}`);
-    return decisions.map((d) => ({ ...d, answer: Object.hasOwn(answers, d.key) ? answers[d.key] : undefined, dismissed: hidden.has(d.key) }));
+    const promoted = new Set(readPromoted(file, say));
+    return decisions.map((d) => ({ ...d, answer: Object.hasOwn(answers, d.key) ? answers[d.key] : undefined, dismissed: hidden.has(d.key), ...(promoted.has(d.key) && { promoted: true }) }));
 }
 function ready(file, on, root) {
     if (!existsSync(file))
@@ -604,7 +619,7 @@ function ready(file, on, root) {
 }
 function list(args) {
     const { file, values, on } = parse('list', args, TIERS);
-    const rows = board(file), waiting = rows.filter(waits), answered = rows.filter((d) => d.answer && !awaitsVerdict(d.type, d.answer) && !d.dismissed).length;
+    const rows = board(file), waiting = rows.filter(asksUser), answered = rows.filter((d) => d.answer && !awaitsVerdict(d.type, d.answer) && !d.dismissed).length;
     if (values.json)
         return JSON.stringify({ board: file, decisions: rows.map(({ dismissed, ...d }) => ({ ...d, ...(d.type === 'signin' && { link: undefined }), ...(dismissed && { dismissed }) })) });
     const help = [
@@ -614,7 +629,7 @@ function list(args) {
     ];
     const where = tilde(file) + (existsSync(file) ? '' : ' (no file yet; raise creates it)');
     if (values.full) {
-        return toon({ board: where, decisions: rows.map((d) => ({ key: d.key, status: awaitsVerdict(d.type, d.answer) ? (d.dismissed ? 'dismissed' : d.type === 'evidence' ? 'shown' : 'waiting') : d.answer.answer, title: d.title, about: d.about ?? '', detail: d.detail ?? '',
+        return toon({ board: where, decisions: rows.map((d) => ({ key: d.key, status: awaitsVerdict(d.type, d.answer) ? (d.dismissed ? 'dismissed' : d.type === 'evidence' ? 'shown' : d.kind === 'design' && !d.promoted ? 'in review' : 'waiting') : d.answer.answer, title: d.title, about: d.about ?? '', detail: d.detail ?? '',
                 recommend: d.recommend_value ?? '', default_if_silent: d.default_if_silent ?? '', close: d.close })) }, help);
     }
     return toon({
@@ -1200,6 +1215,24 @@ function dismiss(restoring) {
         });
     };
 }
+/** promote <key> [board.json] [--undo]: Main puts a design review it passed in front of the user, in Decide; --undo takes it back to Designs. */
+function promote(args) {
+    const at = args.findIndex((a) => !a.startsWith('-') && !existsSync(a) && !a.endsWith('.json')), key = args[at];
+    if (at < 0 || !isKey(key))
+        throw fail('promote needs a design card key', 'VALIDATION_ERROR', 'sign-off-axi promote <key> [board.json]');
+    const { file, named, values, on } = parse('promote', args.filter((_, i) => i !== at), { undo: { type: 'boolean' } });
+    return locked(`${file}.lock`, () => {
+        const d = board(file).find((x) => x.key === key);
+        if (!d)
+            throw fail(`no card with key ${key} on ${tilde(file)}`, 'NOT_FOUND', `Run \`sign-off-axi list${on} --full\` to see the keys`);
+        if (d.kind !== 'design')
+            throw fail(`${key} is not a design review`, 'VALIDATION_ERROR', 'Only a design posted with post --kind design is promoted; every other ask already waits in Decide');
+        const before = waitingKeys(file);
+        appendPromoted(file, key, !values.undo);
+        notifyEntered(file, named, before);
+        return toon({ board: tilde(file), [values.undo ? 'unpromoted' : 'promoted']: [key] }, [values.undo ? `It shows under Designs only. Run \`sign-off-axi promote${on} ${key}\` to put it in Decide again` : `It waits in Decide. Run \`sign-off-axi promote${on} ${key} --undo\` to take it back`]);
+    });
+}
 /** refile <key> [board.json] --media <file>...: an old proof posted as a Pass/Fail ask becomes an evidence update (title and note kept), and the ask is dismissed. */
 async function refile(args) {
     const at = args.findIndex((a) => !a.startsWith('-') && !existsSync(a) && !a.endsWith('.json')), key = args[at];
@@ -1417,11 +1450,23 @@ function postMedia(file, named, on, values, type, filer, message) {
         }
         const key = own || `update-${number}`, dir = join(store, String(number));
         let media, attachments = [];
+        const full = [];
         try {
             media = sources.map((src, i) => {
                 const bytes = readFileSync(src), path = `evidence/${number}/${i + 1}${extname(src).toLowerCase()}`;
                 writeFileSync(join(dir, `${i + 1}${extname(src).toLowerCase()}`), bytes, { mode: 0o600 });
-                return { path, sha256: sha256(bytes), bytes: bytes.length };
+                // The original stays as it was posted; the board shows a lighter copy of a still where one weighs less.
+                const made = isStill(src) ? copiesOf(bytes, extname(src)) : {}, refs = {};
+                for (const size of ['light', 'thumb']) {
+                    const c = made[size];
+                    if (!c)
+                        continue;
+                    writeFileSync(join(dir, `${i + 1}-${size}${c.ext}`), c.bytes, { mode: 0o600 });
+                    refs[size] = { path: `evidence/${number}/${i + 1}-${size}${c.ext}`, sha256: sha256(c.bytes), bytes: c.bytes.length, width: c.width, height: c.height };
+                }
+                if (made.reason)
+                    full.push(`Capture ${i + 1} shows at full size: ${made.reason}`);
+                return { path, sha256: sha256(bytes), bytes: bytes.length, ...refs };
             });
             // An attachment is copied by the kernel and hashed in chunks: the file is never held in memory.
             attachments = attached.map(({ src, ext, name }, i) => {
@@ -1459,7 +1504,7 @@ function postMedia(file, named, on, values, type, filer, message) {
         notifyEntered(file, named, before);
         if (explainer)
             return toon({ board: tilde(file), raised: [{ key, status: 'raised', title }] }, [`Run \`sign-off-axi open${on}\` so the user can watch and answer`, waitFor(on, filer, key)]);
-        return toon({ board: tilde(file), posted: [{ key, number, media: media.length, ...(attachments.length && { attached: attachments.length }), title, ...(message && { status: 'posted' }) }] });
+        return toon({ board: tilde(file), posted: [{ key, number, media: media.length, ...(attachments.length && { attached: attachments.length }), title, ...(message && { status: 'posted' }) }] }, full);
     });
 }
 /** post --type report: the flags as one report message, posted as post --kind report posts it. A report with no page is refused before anything is read. */
@@ -1957,7 +2002,7 @@ const skillInstalled = (dir, agent) => [join(dir, AGENTS[agent].dir), AGENTS[age
     .some((skills) => existsSync(join(skills, 'sign-off-axi', 'SKILL.md')));
 const SKILL_ADD = ['-y', 'skills', 'add', 'umeranjum17/sign-off', '--skill', 'sign-off-axi', '-y', '-a'];
 const skillAdd = (agents) => `npx ${[...SKILL_ADD, ...agents].join(' ')}`;
-const GITIGNORE = 'mocks/\nevidence/\n*.answers.jsonl\n*.rounds.jsonl\n*.messages.jsonl\n*.annotations.jsonl\n*.seen.jsonl\n*.dismissed.jsonl\n*.reads.jsonl\n*.deeper.jsonl\n*.owners.json\n*.delivery.jsonl\n*.board.pid\n*.board.log\nnotify.log\n*.token\n*.export.html\n';
+const GITIGNORE = 'mocks/\nevidence/\n*.answers.jsonl\n*.rounds.jsonl\n*.messages.jsonl\n*.annotations.jsonl\n*.seen.jsonl\n*.dismissed.jsonl\n*.promoted.jsonl\n*.reads.jsonl\n*.deeper.jsonl\n*.owners.json\n*.delivery.jsonl\n*.board.pid\n*.board.log\nnotify.log\n*.token\n*.export.html\n';
 /** The board, port, bind and hosts in <so>/config.yaml (the `key: value` lines init writes). A bad line falls back on its own default
  * (decisions.json, 4410) and `problems` says what is wrong; a file that cannot be read throws. */
 function readSetup(so) {
@@ -2041,7 +2086,7 @@ const tokenMissing = (n) => n.muxr
     : n.token_env && !process.env[n.token_env] ? `${n.token_env} is not set` : undefined;
 const NOTIFY_SENDER = `void (async()=>{const delays=[2000,10000,60000],f=process.env.SIGN_OFF_NOTIFY_TOKEN_FILE;for(let i=0;i<4;i++){try{const t=f?require('node:fs').readFileSync(f,'utf8').trim():process.env.SIGN_OFF_NOTIFY_TOKEN;if((await fetch(process.env.SIGN_OFF_NOTIFY_URL,{method:'POST',headers:{'content-type':'application/json',...(t&&{authorization:'Bearer '+t})},body:process.env.SIGN_OFF_NOTIFY_BODY,signal:AbortSignal.timeout(10000)})).ok)return}catch{}if(i<3)await new Promise(r=>setTimeout(r,delays[i]))}require('node:fs').appendFileSync(process.env.SIGN_OFF_NOTIFY_LOG,new Date().toISOString()+' notification send failed for card '+process.env.SIGN_OFF_NOTIFY_ID+'\\n')})();`;
 /** Cards worth a notice: those waiting on the user, and a new evidence update (shown, never waiting). */
-const notifies = (d) => waits(d) || (d.type === 'evidence' && !d.dismissed);
+const notifies = (d) => asksUser(d) || (d.type === 'evidence' && !d.dismissed);
 /** The cards that would notify before a write: one that notifies after the write but not before it is new to the user. */
 function waitingKeys(file) {
     try {
@@ -2502,7 +2547,7 @@ async function exportBoard(args) {
     let missing = 0;
     // The same URLs the page asks the server for, read through the same hash and path checks.
     const inline = async (url, query, document = false) => {
-        const [code, body] = await route({ method: 'GET', url }).catch(() => [404, null]);
+        const [code, body] = await route({ method: 'GET', url, headers: {} }).catch(() => [404, null]);
         if (code !== 200) {
             missing++;
             return;
@@ -2524,8 +2569,9 @@ async function exportBoard(args) {
             await inline(at(d.key, '', d.view), undefined, true);
         if (d.preview)
             await inline(at(d.key, '', d.preview));
-        for (const i of (d.media ?? []).keys())
-            await inline(`/api/media?key=${q(d.key)}&i=${i}`);
+        for (const [i, m] of (d.media ?? []).entries())
+            for (const v of ['', ...['light', 'thumb'].filter((v) => m[v])])
+                await inline(`/api/media?key=${q(d.key)}&i=${i}${v && `&v=${v}`}`);
         for (const m of d.evidenceCard?.media ?? [])
             await inline(m.url);
     }
@@ -2539,6 +2585,26 @@ async function exportBoard(args) {
     return toon({ board: tilde(parsed.file), exported: tilde(out), items: frozen.decisions.length, inlined: Object.keys(files).length, ...(missing && { missing }) }, [`Open ${tilde(out)} in a browser: one read-only file, no server needed`]);
 }
 const page = readFileSync(new URL('../web/index.html', import.meta.url));
+/** Text a browser fetches is sent compressed when it takes that: the page and the board's state are mostly text and shrink 4-8x, which on a
+ * phone's network is most of the wait. Brotli at a fast level for each reply; the page itself is squeezed once, on its first request. */
+const COMPRESSIBLE = /^(text\/|application\/(json|javascript|manifest\+json)|image\/svg)/;
+const squeeze = (req, bytes) => {
+    const takes = String(req.headers['accept-encoding'] ?? '');
+    if (bytes.length < 1024)
+        return { bytes };
+    if (/\bbr\b/.test(takes))
+        return { bytes: brotliCompressSync(bytes, { params: { [zlib.BROTLI_PARAM_QUALITY]: 5, [zlib.BROTLI_PARAM_SIZE_HINT]: bytes.length } }), encoding: 'br' };
+    if (/\bgzip\b/.test(takes))
+        return { bytes: gzipSync(bytes, { level: 6 }), encoding: 'gzip' };
+    return { bytes };
+};
+const pageTag = `"${createHash('sha256').update(page).digest('hex').slice(0, 32)}"`;
+// Level 9 takes about 50 ms and level 11 over half a second for 7% less, so the page is squeezed at 9.
+const squeezed = {};
+const pageAs = (encoding) => (squeezed[encoding] ??= encoding === 'br'
+    ? brotliCompressSync(page, { params: { [zlib.BROTLI_PARAM_QUALITY]: 9, [zlib.BROTLI_PARAM_SIZE_HINT]: page.length } }) : gzipSync(page, { level: 9 }));
+/** The browser keeps a reply and asks again with its tag, so an unchanged page, state or file costs a 304 and no body. */
+const unchanged = (req, tag) => req.headers['if-none-match']?.split(/\s*,\s*/).includes(tag) ?? false;
 /** The board's design tokens, favicon, home-screen icon and install manifest, served beside the page; see web/tokens.css and web/icon.svg. */
 const ICONS = Object.fromEntries([['tokens.css', 'text/css; charset=utf-8'], ['icon.svg', 'image/svg+xml'], ['apple-touch-icon.png', 'image/png'], ['icon-192.png', 'image/png'], ['icon-512.png', 'image/png'], ['icon-maskable-512.png', 'image/png'], ['manifest.webmanifest', 'application/manifest+json']]
     .map(([name, type]) => [`/${name}`, { type, bytes: readFileSync(new URL(`../web/${name}`, import.meta.url)) }]));
@@ -2641,15 +2707,17 @@ const state = () => {
     // The page marks sent comments in annotations, so answers and rounds go without theirs: a read-only board or an export carries none.
     const answers = Object.fromEntries(Object.entries(readAnswers(file, warn)).map(([k, { comments: _, ...a }]) => [k, a])), taken = seenBy(file);
     const rounds = readRounds(file, warn).map(({ comments: _, ...r }) => r);
+    // The board file is read once for the whole state: it can hold thousands of items.
+    const { extra } = readItems(file), fed = extra.readonly === true || extra.answers_only === true, items = loadDecisions(file);
     return {
         file,
         mockBase: `/mock/${loopback(bind) ? 'local' : mockPass(tokenOf(file))}/`,
         // Who filed an item stays in the file: the page only learns that its filer took the answer.
         // A sign-in's start command stays on this host too: the page only learns that a tap makes a new link, and how the last run went.
-        decisions: loadDecisions(file).filter((d) => !fakeEvidence(d)).map(({ filer: _, start, ...d }) => ({ ...d, ...(d.type === 'design' && answers[d.key]?.answer === 'approve' && { status: 'approved' }), ...(start && { start: true, run: signinState(d.key) }), evidenceCard: d.evidence ? evidenceCard(d.evidence) : null,
+        decisions: items.filter((d) => !fakeEvidence(d)).map(({ filer: _, start, ...d }) => ({ ...d, ...(d.type === 'design' && answers[d.key]?.answer === 'approve' && { status: 'approved' }), ...(start && { start: true, run: signinState(d.key) }), evidenceCard: d.evidence ? evidenceCard(d.evidence) : null,
             ...(d.mocks && { mocks: d.mocks.map((m) => ({ ...m, hash: mockHash(m.path) })) }) })),
-        readonly: readOnly(),
-        answers_only: answersOnly(),
+        readonly: extra.readonly === true,
+        answers_only: extra.answers_only === true,
         ...profile(),
         answers,
         seen: Object.values(answers).filter(taken).map((a) => a.key),
@@ -2660,19 +2728,28 @@ const state = () => {
         delivery: deliveries(file),
         rounds,
         messages: readMessages(file, warn),
-        annotations: readOnly() || answersOnly() ? [] : ((sent) => readAnnotations(file, warn).map((a) => (sent.has(a.id) ? { ...a, sent: true } : a)))(sentIds(file)),
-        comments: readOnly() || answersOnly() ? [] : readPartComments(file),
-        dismissed: readDismissed(file, answers, rounds, warn, archivable(file, loadDecisions(file))),
+        annotations: fed ? [] : ((sent) => readAnnotations(file, warn).map((a) => (sent.has(a.id) ? { ...a, sent: true } : a)))(sentIds(file)),
+        comments: fed ? [] : readPartComments(file),
+        dismissed: readDismissed(file, answers, rounds, warn, fed ? [] : items),
+        promoted: readPromoted(file, warn),
     };
 };
 /** A mock file's sha256 now, or null when it is gone: a comment shows only on the exact file it was made on.
- * ponytail: hashes every mock on each state read; cache by mtime if boards carry many big mocks. */
-const mockHash = (path) => { try {
-    return sha256(readFileSync(under(dirname(file), mockFile(path))));
-}
-catch {
-    return null;
-} };
+ * Kept per file while its size, change time and inode stay the same, so a state read does not rehash every mock. */
+const mockHashes = new Map();
+const mockHash = (path) => {
+    try {
+        const actual = under(dirname(file), mockFile(path)), st = statSync(actual), at = `${st.ino}:${st.size}:${st.mtimeMs}:${st.ctimeMs}`, kept = mockHashes.get(actual);
+        if (kept?.at === at)
+            return kept.hash;
+        const hash = sha256(readFileSync(actual));
+        mockHashes.set(actual, { at, hash });
+        return hash;
+    }
+    catch {
+        return null;
+    }
+};
 /** The comments that go with a card's next answer or round: not sent yet, and made on the mock file the card shows now. */
 const unsent = (d) => {
     const sent = sentIds(file), now = new Map((d.mocks ?? []).map((m) => [m.value, mockHash(m.path)]));
@@ -2830,18 +2907,22 @@ async function route(req) {
     }
     if (req.method === 'GET' && req.url?.startsWith('/api/media?')) {
         const q = new URL(req.url, 'http://localhost').searchParams;
-        const m = loadDecisions(file).find((d) => d.key === q.get('key'))?.media?.[Number(q.get('i') || NaN)];
-        const type = m && mediaTypes[extname(m.path).toLowerCase()];
+        // v=light or v=thumb asks for the copy post made of a still; with no v, the file as it was posted.
+        const v = q.get('v'), posted = loadDecisions(file).find((d) => d.key === q.get('key'))?.media?.[Number(q.get('i') || NaN)];
+        const m = v === null ? posted : v === 'light' || v === 'thumb' ? posted?.[v] : undefined, type = m && mediaTypes[extname(m.path).toLowerCase()];
         if (!m || !type)
             return [404, { error: 'Evidence is unavailable' }];
         try {
-            const actual = under(dirname(file), m.path);
+            const actual = under(dirname(file), m.path), forever = q.get('h') === m.sha256.slice(0, 16);
             if (statSync(actual).size !== m.bytes)
                 return [404, { error: 'Evidence file changed since it was posted' }];
+            // The browser already holds this exact capture: no read and no hash.
+            if (unchanged(req, `"${m.sha256.slice(0, 32)}"`))
+                return [200, { media: Buffer.alloc(0), type, tag: m.sha256.slice(0, 32), forever }];
             const bytes = readFileSync(actual);
             if (sha256(bytes) !== m.sha256)
                 return [404, { error: 'Evidence file changed since it was posted' }];
-            return [200, { media: bytes, type }];
+            return [200, { media: bytes, type, tag: m.sha256.slice(0, 32), forever }];
         }
         catch {
             return [404, { error: 'Evidence is unavailable' }];
@@ -3200,7 +3281,11 @@ const server = createServer(async (req, res) => {
     if (req.method === 'GET' && req.url === '/favicon.ico')
         return res.writeHead(204).end();
     if (req.method === 'GET' && req.url === '/') {
-        return res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'content-security-policy': "default-src 'self' 'unsafe-inline'" }).end(page);
+        const headers = { 'content-type': 'text/html; charset=utf-8', 'content-security-policy': "default-src 'self' 'unsafe-inline'", etag: pageTag, 'cache-control': 'no-cache', vary: 'accept-encoding' };
+        if (unchanged(req, pageTag))
+            return res.writeHead(304, headers).end();
+        const takes = String(req.headers['accept-encoding'] ?? ''), encoding = /\bbr\b/.test(takes) ? 'br' : /\bgzip\b/.test(takes) ? 'gzip' : undefined, bytes = encoding ? pageAs(encoding) : page;
+        return res.writeHead(200, { ...headers, ...(encoding && { 'content-encoding': encoding }), 'content-length': bytes.length }).end(bytes);
     }
     let status, body;
     try {
@@ -3223,19 +3308,32 @@ const server = createServer(async (req, res) => {
         return bytes ? pipeline(createReadStream(path, { start, end }), res, () => { }) : res.end();
     }
     if (body && typeof body === 'object' && 'media' in body) {
-        const { media: bytes, type, point, page } = body, media = point ? Buffer.concat([bytes, pointer, ...(page ? [page] : [])]) : bytes;
-        const headers = { 'content-type': type, 'x-content-type-options': 'nosniff', 'content-security-policy': FRAME_CSP, 'accept-ranges': 'bytes', 'content-length': media.length };
+        const { media: bytes, type, point, page, tag: stored, forever } = body;
+        const media = point ? Buffer.concat([bytes, pointer, ...(page ? [page] : [])]) : bytes, tag = `"${stored ?? sha256(media).slice(0, 32)}"`;
+        // A capture named by its hash never changes, so the browser keeps it; any other file is asked again with its tag.
+        const kept = { etag: tag, 'cache-control': forever ? 'private, max-age=31536000, immutable' : 'private, no-cache' };
+        if (status === 200 && unchanged(req, tag))
+            return res.writeHead(304, kept).end();
+        const headers = { 'content-type': type, 'x-content-type-options': 'nosniff', 'content-security-policy': FRAME_CSP, 'accept-ranges': 'bytes', 'content-length': media.length, ...(status === 200 && kept) };
         // One byte range, so phone browsers can play and seek a recording.
         const range = /^bytes=(\d*)-(\d*)$/.exec(req.headers.range ?? '');
-        if (!range || (!range[1] && !range[2]))
-            return res.writeHead(status, headers).end(media);
+        if (!range || (!range[1] && !range[2])) {
+            const sent = COMPRESSIBLE.test(type) ? squeeze(req, media) : { bytes: media };
+            return res.writeHead(status, { ...headers, 'content-length': sent.bytes.length, ...(sent.encoding && { 'content-encoding': sent.encoding, vary: 'accept-encoding' }) }).end(sent.bytes);
+        }
         const start = range[1] ? Number(range[1]) : Math.max(0, media.length - Number(range[2]));
         const end = range[1] && range[2] ? Math.min(Number(range[2]), media.length - 1) : media.length - 1;
         if (start > end)
             return res.writeHead(416, { 'content-range': `bytes */${media.length}` }).end();
         return res.writeHead(206, { ...headers, 'content-length': end - start + 1, 'content-range': `bytes ${start}-${end}/${media.length}` }).end(media.subarray(start, end + 1));
     }
-    res.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify(body));
+    const json = Buffer.from(JSON.stringify(body));
+    // The page reads the state again every 20 seconds: unchanged, that read is a 304 with no body.
+    const tag = req.method === 'GET' && status === 200 ? `"${sha256(json).slice(0, 32)}"` : undefined;
+    if (tag && unchanged(req, tag))
+        return res.writeHead(304, { etag: tag, 'cache-control': 'no-cache' }).end();
+    const sent = squeeze(req, json);
+    res.writeHead(status, { 'content-type': 'application/json', 'content-length': sent.bytes.length, ...(sent.encoding && { 'content-encoding': sent.encoding }), vary: 'accept-encoding', ...(tag && { etag: tag, 'cache-control': 'no-cache' }) }).end(sent.bytes);
 });
 const argv = process.argv.slice(2);
 // Flags with no command belong to the default list view (sign-off-axi --json).
@@ -3248,7 +3346,7 @@ await runAxiCli({
     topLevelHelp: TOP_HELP,
     getCommandHelp: (cmd) => HELP[cmd],
     home: axi('list', list),
-    commands: { list: axi('list', list), raise: axi('raise', (args) => post(args, 'raise')), post: axi('post', post), answers: axi('answers', answers), wait: axi('wait', wait), poll: axi('poll', poll), open: axi('open', open), status: axi('status', status), stop: axi('stop', stop), serve: axi('serve', serve), export: axi('export', exportBoard), init: axi('init', init), report: axi('report', report), owner: axi('owner', owner), deeper: axi('deeper', deeper), signin: axi('signin', signin), dismiss: axi('dismiss', dismiss(false)), restore: axi('restore', dismiss(true)), refile: axi('refile', refile), doctor: axi('doctor', doctor), notify: axi('notify', notify), validate, help: ([name, ...rest]) => {
+    commands: { list: axi('list', list), raise: axi('raise', (args) => post(args, 'raise')), post: axi('post', post), answers: axi('answers', answers), wait: axi('wait', wait), poll: axi('poll', poll), open: axi('open', open), status: axi('status', status), stop: axi('stop', stop), serve: axi('serve', serve), export: axi('export', exportBoard), init: axi('init', init), report: axi('report', report), owner: axi('owner', owner), deeper: axi('deeper', deeper), signin: axi('signin', signin), dismiss: axi('dismiss', dismiss(false)), restore: axi('restore', dismiss(true)), promote: axi('promote', promote), refile: axi('refile', refile), doctor: axi('doctor', doctor), notify: axi('notify', notify), validate, help: ([name, ...rest]) => {
             if (rest.length || (name && !HELP[name]))
                 throw fail(`unknown command or argument: ${[name, ...rest].join(' ')}`, 'VALIDATION_ERROR', 'Run `sign-off-axi --help` to see the commands');
             return name ? HELP[name] : TOP_HELP;

package/dist/evidence-text.js

@@ -157,9 +157,11 @@ function convert(file) {
     });
 }
 /** Packed 8-bit RGB of a PNG, every colour type and bit depth, interlaced or not. undefined for a PNG it does not read. */
-function pngRgb(buf) {
+const pngRgb = (buf) => pngPixels(buf, 3)?.data;
+/** A PNG's pixels as packed 8-bit RGB (3 channels) or RGBA (4, with its alpha channel or palette transparency), and its size. */
+export function pngPixels(buf, out) {
     try {
-        let width = 0, height = 0, type = 0, depth = 0, interlace = 0, palette;
+        let width = 0, height = 0, type = 0, depth = 0, interlace = 0, palette, trns;
         const idat = [];
         for (let at = 8; at + 8 <= buf.length;) {
             const len = buf.readUInt32BE(at), name = buf.toString('latin1', at + 4, at + 8), data = buf.subarray(at + 8, at + 8 + len);
@@ -167,6 +169,8 @@ function pngRgb(buf) {
                 [width, height, depth, type, interlace] = [data.readUInt32BE(0), data.readUInt32BE(4), data[8], data[9], data[12]];
             else if (name === 'PLTE')
                 palette = data;
+            else if (name === 'tRNS')
+                trns = data;
             else if (name === 'IDAT')
                 idat.push(data);
             else if (name === 'IEND')
@@ -177,7 +181,7 @@ function pngRgb(buf) {
         if (!channels || ![1, 2, 4, 8, 16].includes(depth) || (type === 3 && (!palette || depth > 8)))
             return undefined;
         const bits = channels * depth, bpp = Math.max(1, bits >> 3), raw = inflateSync(Buffer.concat(idat));
-        const rgb = Buffer.alloc(width * height * 3);
+        const rgb = Buffer.alloc(width * height * out, 255);
         const to8 = (v) => (depth < 8 ? Math.round((v * 255) / ((1 << depth) - 1)) : v);
         let at = 0;
         for (const [x0, y0, dx, dy] of interlace ? ADAM7 : WHOLE) {
@@ -215,25 +219,31 @@ function pngRgb(buf) {
             };
             for (let y = 0; y < ph; y++) {
                 for (let x = 0; x < pw; x++) {
-                    const n = x * channels, o = ((y0 + y * dy) * width + x0 + x * dx) * 3;
+                    const n = x * channels, o = ((y0 + y * dy) * width + x0 + x * dx) * out;
                     if (type === 3) {
-                        const k = sample(y, n) * 3;
+                        const v = sample(y, n), k = v * 3;
                         rgb[o] = palette[k] ?? 0;
                         rgb[o + 1] = palette[k + 1] ?? 0;
                         rgb[o + 2] = palette[k + 2] ?? 0;
+                        if (out === 4)
+                            rgb[o + 3] = trns?.[v] ?? 255;
                     }
                     else if (channels <= 2) {
                         rgb[o] = rgb[o + 1] = rgb[o + 2] = to8(sample(y, n));
+                        if (out === 4 && channels === 2)
+                            rgb[o + 3] = to8(sample(y, n + 1));
                     }
                     else {
                         rgb[o] = to8(sample(y, n));
                         rgb[o + 1] = to8(sample(y, n + 1));
                         rgb[o + 2] = to8(sample(y, n + 2));
+                        if (out === 4 && channels === 4)
+                            rgb[o + 3] = to8(sample(y, n + 3));
                     }
                 }
             }
         }
-        return rgb;
+        return { width, height, data: rgb };
     }
     catch {
         return undefined;