devmandan's picture
Claude Opus 5.5
PNG files that say how they were made, checked in your browser
de7cd1e verified
Raw History Blame Contribute Delete
15.7 kB
// A PNG file's own record of how it was made: one text chunk keyed qr-made, read in this browser (png.js) and checked
// against the file's reading before any of it is used, with record.json's limits and tolerances and the QR standard's
// tables, each with its source. Every upload sends the file without its qr-made chunks, valid or not, and that copy is
// kept until the picture goes, so nothing of the record is ever sent and the reading is the same without it. A record
// that checks out marks the picture The original graphic by itself, once, and only while the visitor hasn't chosen
// (plan_view.js), and says so; record_view.js words its lines. Nothing is stored.
import { getJson, t } from './copy.js';
import { choice, framePpm, squares } from './plan.js';
import { MAX_BYTES, measure } from './upload.js';
import { KEYWORD, crcOk, cuts, isText, markClean, pngFile, strip, walk } from './png.js';
import { compare, formatOf, sideOf, unpack, versionOk } from './squares.js';
import { sayTestNote } from './test_view.js';
let R = null; // web/data/record.json, or null: no record is read, and every qr-made chunk is still removed
const CHECKED = ['read', 'unchecked', 'mismatch', 'verified']; // the states of a record whose chunk and hash held
const FACTS = ['ec_level', 'mask', 'squares', 'raw_sha256']; // zxing-cpp's facts, which a record is checked against
const ART_KINDS = ['none', 'spare-data', 'changes-squares', 'drawn-over'];
const CAPITAL_KINDS = ['none', 'scheme-and-host', 'whole-link'];
const SINGLE_ART = ['none', 'spare-data']; // art that leaves a code's margin alone, so the margin is compared
const B64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/; // standard base64, padded, no spaces
const HEX64 = /^[0-9a-f]{64}$/;
const FORMATS = 32; // the standard's format codewords: two bits of error correction, then three of mask
const isObj = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
const num = (x) => typeof x === 'number' && Number.isFinite(x);
const whole = (x, lo = 0, hi = Number.MAX_SAFE_INTEGER) => Number.isSafeInteger(x) && x >= lo && x <= hi;
const share = (x) => num(x) && x >= 0 && x <= 1;
const given = (x) => x != null; // an optional field: missing, or null, is left out
const ints = (a) => Array.isArray(a) && a.every((x) => whole(x));
/** A text of ASCII characters only: then a byte's place in the content is a character's place in the text. */
export const ascii = (s) => typeof s === 'string' && /^[\x00-\x7f]*$/.test(s);
/** app.js, at the start: record.json. Never throws: a missing file, or a value outside its type, leaves every record
* unread (their chunks are still removed before sending). */
export async function loadRecord(url) {
try {
const s = await getJson(url);
R = fits(s) ? s : null;
} catch {
R = null;
}
}
/** What the code relies on: whole numbers for the limits, finite figures and shares for the tolerances, the
* standard's tables as whole numbers, and the keyword png.js removes. */
function fits(s) {
const { record: r, names: l, checks: c, dots, standard: st } = isObj(s) ? s : {};
const ec = isObj(st?.format_ec) && Object.values(st.format_ec).every((x) => whole(x, 0, 3));
return isObj(r) && r.keyword === KEYWORD && whole(r.form, 1) && whole(r.max_chunks, 1) && whole(r.max_chunk_bytes, 1)
&& whole(r.max_depth, 1) && whole(l?.max_code_points, 1) && isObj(c) && num(c.box_squares) && c.box_squares >= 0
&& share(c.ppm_share) && share(c.squares_share) && whole(c.margin_cap) && share(dots?.small_below) && ec
&& ints(st.format) && st.format.length === FORMATS && isObj(st.version) && Object.values(st.version).every((x) => whole(x))
&& isObj(st.alignment) && Object.values(st.alignment).every(ints);
}
export const recordSettings = () => R;
/** A record that checked out on the picture's reading, and found the code mirrored: no design test (test.js). */
export const mirroredByRecord = (p) => p.made?.state === 'verified' && p.made.squares?.mirrored === true;
/** The record's fields, only once they checked out on the picture's reading. */
export const verifiedRecord = (p) => (p.made?.state === 'verified' ? p.made.rec : null);
/** app.js pump(): the picture's reading, sent without its qr-made chunks (the copy is made once and kept as p.file,
* which Try again and a design test send too); then the record, read once, is checked against this reading, and
* marks the picture when it checks out. */
export async function measureFile(p, signal) {
p.made ||= await readFile(p.file);
p.file = p.made.file;
const r = await measure(p.file, signal);
check(p, r);
return r;
}
/** The file's chunks, read once (all of a PNG of at most MAX_BYTES; of any other file, its first 8 bytes): the copy
* every upload sends, and the record when its chunk reads and its hash holds. Never throws: a file whose bytes
* can't be read keeps itself, with no record (no upload can read it either). */
async function readFile(file) {
const made = { file, found: false, state: 'none', why: '', rec: null, squares: null, marked: false, chosen: false };
try {
if (file.size > MAX_BYTES) return made; // never sent (upload.js)
if (!(await pngFile(file))) {
markClean(file);
return made;
}
const bytes = new Uint8Array(await file.arrayBuffer());
const w = walk(bytes, R ? R.record.max_chunks : 0);
made.file = strip(file, cuts(bytes, w));
markClean(made.file);
made.found = w.keyed.length > 0;
if (made.found && R && globalThis.crypto?.subtle) Object.assign(made, await recordOf(bytes, w));
} catch {
made.state = 'none'; // no record; the copy, if made, stays the one sent
}
return made;
}
/** The record from a file whose walk ended at IEND within max_chunks, with exactly one chunk keyed qr-made:
* uncompressed, whole, at most max_chunk_bytes, its CRC right, its text JSON nested no deeper than the record, of
* this page's form, every listed field in range; then the file's own hash against file.image_sha256. A newer form
* says so; any other fault is "couldn't be read". No hash, no record. */
async function recordOf(bytes, w) {
const L = R.record;
const aside = (why, state = 'unreadable') => ({ state, why });
if (w.ended !== 'iend') return aside(w.ended);
if (w.count > L.max_chunks) return aside('chunks');
if (w.keyed.length !== 1) return aside('several');
const chunk = w.keyed[0];
if (chunk.type === 'zTXt') return aside('compressed');
if (chunk.length > L.max_chunk_bytes) return aside('size');
if (!crcOk(bytes, chunk)) return aside('crc');
const text = textOf(bytes.subarray(chunk.dataStart, chunk.dataStart + chunk.length), chunk.type);
let rec = null;
try {
rec = text == null ? null : JSON.parse(text);
} catch { /* not JSON */ }
if (!isObj(rec)) return aside(text == null ? 'text' : 'json');
if (Number.isInteger(rec.qr_made) && rec.qr_made > L.form) return aside('form', 'newer');
if (rec.qr_made !== L.form) return aside('form');
if (deeper(rec, L.max_depth)) return aside('depth');
const field = FIELDS.find(([, holds]) => !holds(rec));
if (field) return aside(field[0]);
let hash = '';
try {
hash = await imageHash(bytes, w.chunks);
} catch {
return { state: 'none', why: 'digest' };
}
return hash === rec.file.image_sha256 ? { state: 'read', why: '', rec } : aside('hash', 'saved');
}
/** The record's text: a tEXt chunk's as ISO-8859-1, byte for byte; an uncompressed iTXt chunk's after its language
* tag and translated keyword (whatever they hold, each ending in a NUL), as UTF-8 that must be valid; else null. */
function textOf(data, type) {
const from = KEYWORD.length + 1; // after the keyword and its NUL
if (type === 'tEXt') return Array.from(data.subarray(from), (b) => String.fromCharCode(b)).join('');
if (data.length < from + 2 || data[from] !== 0) return null; // its compression flag: 0, uncompressed
const lang = data.indexOf(0, from + 2);
const name = lang < 0 ? -1 : data.indexOf(0, lang + 1);
if (name < 0) return null;
try {
return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(data.subarray(name + 1));
} catch {
return null;
}
}
/** Whether JSON nests deeper than max: the record itself is 1, its code 2, the code's box or grid 3. */
const deeper = (x, max) => x !== null && typeof x === 'object' && (max < 1 || Object.values(x).some((y) => deeper(y, max - 1)));
/** SHA-256 over every chunk walked, in file order, whole (length, type, data and CRC), but the text chunks. */
async function imageHash(bytes, chunks) {
const kept = chunks.filter((c) => !isText(c.type));
const all = new Uint8Array(kept.reduce((n, c) => n + c.end - c.start, 0));
let at = 0;
for (const c of kept) {
all.set(bytes.subarray(c.start, c.end), at);
at += c.end - c.start;
}
const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', all));
return Array.from(digest, (b) => b.toString(16).padStart(2, '0')).join('');
}
/** The fields read, in order, each with its range; unknown keys are ignored. The control names never fail a record
* (record_view.js cleans them). */
const FIELDS = [
['code', (r) => isObj(r.code)],
['code.version', (r) => whole(r.code.version, 1, 40)],
['code.error_correction', (r) => typeof r.code.error_correction === 'string' && Object.hasOwn(R.standard.format_ec, r.code.error_correction)],
['code.mask', (r) => whole(r.code.mask, 0, 7)],
['code.inverted', (r) => typeof r.code.inverted === 'boolean'],
['code.margin', (r) => whole(r.code.margin)],
['code.pixels_per_square', (r) => num(r.code.pixels_per_square) && r.code.pixels_per_square > 0],
['code.box', ({ code: { box: b } }) => Array.isArray(b) && b.length === 3 && b.every(num) && b[0] >= 0 && b[1] >= 0 && b[2] > 0],
['code.grid', ({ code: { grid: g } }) => !given(g) || (isObj(g) && num(g.pitch) && g.pitch > 0 && whole(g.columns, 1) && whole(g.rows, 1))],
['code.matrix', (r) => typeof r.code.matrix === 'string' && B64.test(r.code.matrix)],
['code.dots', ({ code: { dots: d } }) => !given(d) || d === 'varies' || (num(d) && d > 0 && d <= 1)],
['content', (r) => isObj(r.content)],
['content.sha256', (r) => HEX64.test(r.content.sha256)],
['content.bytes', (r) => whole(r.content.bytes)],
['content.link_bytes', ({ content: c }) => !given(c.link_bytes) || whole(c.link_bytes, 0, c.bytes - 1)],
['content.capitals', (r) => CAPITAL_KINDS.includes(r.content.capitals)],
['art', (r) => ART_KINDS.includes(r.art)],
['file', (r) => isObj(r.file)],
['file.image_sha256', (r) => HEX64.test(r.file.image_sha256)],
];
/** The record against the reading: zxing-cpp's facts there, else "couldn't be checked"; then its code, content,
* place and squares, a fault in any of them "don't match its code". A comparison whose reading value is missing is
* left out. A record that checks out keeps the square check's counts, and marks the picture. Never throws. */
function check(p, r) {
const m = p.made;
if (!CHECKED.includes(m.state)) return;
m.squares = null;
let why = 'facts';
try {
if (FACTS.every((k) => r?.[k] != null)) why = codeFault(m.rec, r) || contentFault(m.rec, r) || placeFault(m.rec, r) || squaresFault(m, r);
} catch {
why = 'reading';
}
m.why = why;
m.state = !why ? 'verified' : why === 'facts' ? 'unchecked' : 'mismatch';
if (!why) mark(p);
}
/** The code: zxing-cpp's version (the size of its squares, and the checks' when a scanner gave it), error correction,
* mask and inversion; the matrix n × n, its pad bits 0, and its own format and version bits saying the same. */
function codeFault(rec, r) {
const c = rec.code;
const k = r.checks;
const n = squares(c.version);
if (sideOf(r.squares) !== n || (k?.modules_from === 'scanner' && k.version !== c.version)) return 'version';
if (c.error_correction !== r.ec_level || c.mask !== r.mask) return 'ec_mask';
if (given(k?.contrast?.inverted) && k.contrast.inverted !== c.inverted) return 'inverted';
const meant = unpack(c.matrix, n);
if (!meant) return 'matrix';
const f = formatOf(meant, n, R.standard);
return f && f.ec === c.error_correction && f.mask === c.mask && versionOk(meant, n, R.standard, c.version) ? '' : 'bits';
}
/** The content: its hash and byte count; and where a link ends, "#" then digits in the text the page holds (only an
* ASCII one), or a text cut before it. */
function contentFault(rec, r) {
const c = rec.content;
if (c.sha256 !== r.raw_sha256 || (given(r.raw_bytes) && c.bytes !== r.raw_bytes)) return 'content';
const held = r.content;
const lb = c.link_bytes;
if (!given(lb) || !ascii(held?.text)) return '';
if (lb >= held.text.length) return held.cut ? '' : 'link';
return held.text[lb] === '#' && /^[0-9]*$/.test(held.text.slice(lb + 1)) ? '' : 'link';
}
/** Where it sits: pixels per square within ppm_share of the reading's; the box (or, for a picture that repeats the
* code, a cell of its grid) within box_squares of the reading's corners, by their bounding box, whatever the code's
* turn; and the margin of a single code whose art leaves it alone, up to the margin check's cap, only where that
* check measured it at margin_min_ppm or more (sizes.json), not under, not capped. */
function placeFault(rec, r) {
const c = rec.code;
const k = r.checks || {};
const native = k.ppm?.native;
if (native > 0 && Math.abs(c.pixels_per_square - native) > R.checks.ppm_share * native) return 'ppm';
if (Array.isArray(k.quad)) {
const [xs, ys] = [k.quad.map((q) => q[0]), k.quad.map((q) => q[1])];
let [x0, y0] = c.box;
const g = c.grid;
if (g) {
const [j, i] = [Math.round((Math.min(...xs) - x0) / g.pitch), Math.round((Math.min(...ys) - y0) / g.pitch)];
if (i < 0 || i >= g.rows || j < 0 || j >= g.columns) return 'cell';
[x0, y0] = [x0 + j * g.pitch, y0 + i * g.pitch];
}
const side = c.box[2];
const off = Math.max(Math.abs(Math.min(...xs) - x0), Math.abs(Math.min(...ys) - y0), Math.abs(Math.max(...xs) - x0 - side), Math.abs(Math.max(...ys) - y0 - side));
const span = Math.max(Math.max(...xs) - Math.min(...xs), Math.max(...ys) - Math.min(...ys)); // corners' box side
if (!(off <= R.checks.box_squares * (native > 0 ? native : span / squares(c.version)))) return 'box';
}
const q = k.quiet;
const ppm = framePpm(r, r.frames?.[0]?.[0]);
const compared = !c.grid && SINGLE_ART.includes(rec.art) && given(q?.modules) && !q.under && !q.capped && ppm >= choice('margin_min_ppm');
return compared && Math.min(c.margin, R.checks.margin_cap) !== q.modules ? 'margin' : '';
}
/** The squares: at most squares_share of them read the other way, comparing the code mirrored too; the counts kept. */
function squaresFault(m, r) {
const v = m.rec.code.version;
const n = squares(v);
const s = compare(unpack(m.rec.code.matrix, n), unpack(r.squares, n, false), n, v, R.standard);
if (s.wrong > R.checks.squares_share * s.N) return 'squares';
m.squares = { N: s.N, wrong: s.wrong, f: s.f, g: s.g, mirrored: s.mirrored };
return '';
}
/** A record that checks out marks its picture The original graphic, once, unless the visitor has chosen what it
* shows: before the page says it was read, so every answer gives the picture's own width. testNote says so, before
* anything its design test then says there. The visitor's last choice, for the next picture, stays as it was. */
function mark(p) {
const m = p.made;
if (m.marked || m.chosen) return;
p.kind = 'graphic';
m.marked = true;
sayTestNote(t('made.record.announce_named', { n: p.n, name: p.name, line: t('made.record.marked') }));
}