@joewinke/jatui 0.10.0 → 0.11.0

package/dist/video/advisors/qr.js

@@ -0,0 +1,546 @@
+/**
+ * QR Code (ISO/IEC 18004) encoder: versions 1–10, byte mode, no deps. Ported
+ * verbatim from extension-library `lib/qr.js` (mos-5lzns.27).
+ *
+ * Why hand-rolled. The extension ran under a strict CSP where every CDN-hosted
+ * QR library was unreachable by construction, and there was no build step to
+ * vendor one through. The alternative — pasting a minified blob into the repo —
+ * ships a black box into a codebase whose whole premise is that you can read
+ * it. This is the spec, written out, and PROVEN by the vitest suite that
+ * replaced the `--self-test` block (a reader that decodes our own output, plus
+ * structural assertions against published tables) rather than trusted.
+ *
+ * What it is for: a QR of the current deep link — the player's `?t=` substrate
+ * (video/deepLink.ts) plus the host's own file/URL part — so the video you are
+ * watching moves from the desk to a phone mid-sentence. That URL is 60–120
+ * bytes over a tailnet hostname — a version 3–7 symbol at ECC M. Versions above
+ * 10 would buy capacity this will never use and cost another row in four tables
+ * each, so the ceiling is deliberate and qrMatrix throws at it instead of
+ * quietly growing.
+ *
+ * Guard philosophy, since it cuts both ways here: garbage OPTIONS degrade to
+ * defaults (an unknown ecc string is just "M"), because a slightly
+ * wrong-looking QR still scans. Text that genuinely cannot be represented
+ * THROWS, because the failure mode of the alternative is a symbol that scans
+ * perfectly and sends the phone to a truncated URL — silent, plausible, and
+ * wrong.
+ *
+ *   qrMatrix(text, { ecc = "M", minVersion = 1 }) -> { size, modules }
+ *   qrCanvas(text, { scale = 4, margin = 4, dark, light }) -> HTMLCanvasElement
+ *
+ * The self-test's independent READER (mask/format re-derivation, de-interleave,
+ * round-trip decode) lives with the vitest suite in tests/unit/advisors/ —
+ * deliberately NOT built on the encoder's own reserved map or chosen mask, and
+ * deliberately not shipped in dist.
+ */
+const MAX_VERSION = 10;
+const MODE_BYTE = 0b0100;
+const PAD_BYTES = [0xec, 0x11]; // spec's alternating filler, not zeros
+const ECC_BITS = { L: 1, M: 0, Q: 3, H: 2 }; // NOT 0..3 in level order — spec's own numbering
+// version → [ecCodewordsPerBlock, group1Blocks, group1DataCw, group2Blocks, group2DataCw]
+// Straight from ISO/IEC 18004 table 13–16. The suite cross-checks every row
+// against the independently-known total codeword count, which catches a typo in
+// any of the five numbers.
+const BLOCKS = {
+    L: [
+        [7, 1, 19, 0, 0],
+        [10, 1, 34, 0, 0],
+        [15, 1, 55, 0, 0],
+        [20, 1, 80, 0, 0],
+        [26, 1, 108, 0, 0],
+        [18, 2, 68, 0, 0],
+        [20, 2, 78, 0, 0],
+        [24, 2, 97, 0, 0],
+        [30, 2, 116, 0, 0],
+        [18, 2, 68, 2, 69],
+    ],
+    M: [
+        [10, 1, 16, 0, 0],
+        [16, 1, 28, 0, 0],
+        [26, 1, 44, 0, 0],
+        [18, 2, 32, 0, 0],
+        [24, 2, 43, 0, 0],
+        [16, 4, 27, 0, 0],
+        [18, 4, 31, 0, 0],
+        [22, 2, 38, 2, 39],
+        [22, 3, 36, 2, 37],
+        [26, 4, 43, 1, 44],
+    ],
+    Q: [
+        [13, 1, 13, 0, 0],
+        [22, 1, 22, 0, 0],
+        [18, 2, 17, 0, 0],
+        [26, 2, 24, 0, 0],
+        [18, 2, 15, 2, 16],
+        [24, 4, 19, 0, 0],
+        [18, 2, 14, 4, 15],
+        [22, 4, 18, 2, 19],
+        [20, 4, 16, 4, 17],
+        [24, 6, 19, 2, 20],
+    ],
+    H: [
+        [17, 1, 9, 0, 0],
+        [28, 1, 16, 0, 0],
+        [22, 2, 13, 0, 0],
+        [16, 4, 9, 0, 0],
+        [22, 2, 11, 2, 12],
+        [28, 4, 15, 0, 0],
+        [26, 4, 13, 1, 14],
+        [26, 4, 14, 2, 15],
+        [24, 4, 12, 4, 13],
+        [28, 6, 15, 2, 16],
+    ],
+};
+// total codewords (data + ec) per version — used only to validate BLOCKS
+const TOTAL_CW = [26, 44, 70, 100, 134, 172, 196, 242, 292, 346];
+// alignment-pattern centre coordinates per version (both axes)
+const ALIGN_POS = [
+    [],
+    [6, 18],
+    [6, 22],
+    [6, 26],
+    [6, 30],
+    [6, 34],
+    [6, 22, 38],
+    [6, 24, 42],
+    [6, 26, 46],
+    [6, 28, 50],
+];
+// The eight data masks. Index IS the mask number written into the format info,
+// so the order is load-bearing — do not sort or reorder.
+const MASKS = [
+    (r, c) => (r + c) % 2 === 0,
+    (r) => r % 2 === 0,
+    (r, c) => c % 3 === 0,
+    (r, c) => (r + c) % 3 === 0,
+    (r, c) => (((r / 2) | 0) + ((c / 3) | 0)) % 2 === 0,
+    (r, c) => ((r * c) % 2) + ((r * c) % 3) === 0,
+    (r, c) => (((r * c) % 2) + ((r * c) % 3)) % 2 === 0,
+    (r, c) => (((r + c) % 2) + ((r * c) % 3)) % 2 === 0,
+];
+// ── GF(256) ─────────────────────────────────────────────────────────────────
+// Primitive polynomial x^8+x^4+x^3+x^2+1 (0x11d) — the QR one, not the
+// Data Matrix one (0x12d). Exp table is doubled so a+b needs no modulo.
+const GF_EXP = new Uint8Array(512);
+const GF_LOG = new Uint8Array(256);
+{
+    let x = 1;
+    for (let i = 0; i < 255; i++) {
+        GF_EXP[i] = x;
+        GF_LOG[x] = i;
+        x = (x << 1) ^ (x & 0x80 ? 0x11d : 0);
+    }
+    for (let i = 255; i < 512; i++)
+        GF_EXP[i] = GF_EXP[i - 255];
+}
+const gfMul = (a, b) => a === 0 || b === 0 ? 0 : GF_EXP[GF_LOG[a] + GF_LOG[b]];
+// generator = ∏ (x − α^i), coefficients high degree first
+function rsGenerator(n) {
+    let g = [1];
+    for (let i = 0; i < n; i++) {
+        const next = new Array(g.length + 1).fill(0);
+        for (let j = 0; j < g.length; j++) {
+            next[j] ^= g[j];
+            next[j + 1] ^= gfMul(g[j], GF_EXP[i]);
+        }
+        g = next;
+    }
+    return g;
+}
+// polynomial long division, keeping only the remainder — the EC codewords
+function rsEncode(data, ecLen) {
+    const gen = rsGenerator(ecLen);
+    const rem = new Uint8Array(ecLen);
+    for (const b of data) {
+        const factor = b ^ rem[0];
+        rem.copyWithin(0, 1);
+        rem[ecLen - 1] = 0;
+        for (let i = 0; i < ecLen; i++)
+            rem[i] ^= gfMul(gen[i + 1], factor);
+    }
+    return rem;
+}
+// S_i = block(α^i). All zero ⟺ the block is a valid RS codeword. This is the
+// one check that does not depend on our own encoder being right in the same way
+// twice: it evaluates the finished bytes against the field, full stop.
+function rsSyndromes(block, ecLen) {
+    const out = new Uint8Array(ecLen);
+    for (let i = 0; i < ecLen; i++) {
+        let s = 0;
+        for (const b of block)
+            s = gfMul(s, GF_EXP[i]) ^ b;
+        out[i] = s;
+    }
+    return out;
+}
+// ── bit-level spec pieces ───────────────────────────────────────────────────
+// BCH(15,5) over the format's 5 bits, then XOR 0x5412 so an all-zero format
+// (level M, mask 0) is not an all-light region a scanner could miss.
+function formatBits(ecc, mask) {
+    const data = (ECC_BITS[ecc] << 3) | mask;
+    let rem = data << 10;
+    for (let i = 14; i >= 10; i--)
+        if ((rem >>> i) & 1)
+            rem ^= 0x537 << (i - 10);
+    return ((data << 10) | rem) ^ 0x5412;
+}
+// BCH(18,6). No XOR mask here — version info only exists for v≥7, where the
+// symbol is big enough that the pattern is unambiguous on its own.
+function versionBits(version) {
+    let rem = version << 12;
+    for (let i = 17; i >= 12; i--)
+        if ((rem >>> i) & 1)
+            rem ^= 0x1f25 << (i - 12);
+    return (version << 12) | rem;
+}
+const charCountBits = (version) => (version < 10 ? 8 : 16);
+const dataCodewords = (version, ecc) => {
+    const [, b1, d1, b2, d2] = BLOCKS[ecc][version - 1];
+    return b1 * d1 + b2 * d2;
+};
+const maxBytes = (version, ecc) => Math.max(0, ((dataCodewords(version, ecc) * 8 - 4 - charCountBits(version)) / 8) | 0);
+// ── data encoding ───────────────────────────────────────────────────────────
+function toBytes(text) {
+    // null/undefined encode as the empty symbol rather than "null" — a QR of the
+    // literal word "undefined" is worse than a QR of nothing.
+    const s = text == null ? "" : typeof text === "string" ? text : String(text);
+    return new TextEncoder().encode(s);
+}
+function encodeData(bytes, version, ecc) {
+    const capacityBits = dataCodewords(version, ecc) * 8;
+    const bits = [];
+    const push = (val, len) => {
+        for (let i = len - 1; i >= 0; i--)
+            bits.push((val >>> i) & 1);
+    };
+    push(MODE_BYTE, 4);
+    push(bytes.length, charCountBits(version));
+    for (const b of bytes)
+        push(b, 8);
+    // Terminator, then pad to a byte boundary. In byte mode these are the same
+    // four zeros: the header is 12 or 20 bits, so the stream always sits at 4 mod
+    // 8 here and the terminator never truncates (proven over all 3572
+    // version/level/length combinations — deleting this line changes no output
+    // byte). It stays because the invariant is an accident of byte mode, and the
+    // suite asserts it rather than trusting it.
+    for (let i = 0; i < 4 && bits.length < capacityBits; i++)
+        bits.push(0);
+    while (bits.length % 8 !== 0)
+        bits.push(0);
+    const out = new Uint8Array(capacityBits / 8);
+    for (let i = 0; i < bits.length; i += 8) {
+        let b = 0;
+        for (let j = 0; j < 8; j++)
+            b = (b << 1) | bits[i + j];
+        out[i / 8] = b;
+    }
+    for (let i = bits.length / 8, k = 0; i < out.length; i++, k++)
+        out[i] = PAD_BYTES[k % 2];
+    return out;
+}
+// Split into blocks, EC each, then interleave — a burst of damage that wipes a
+// contiguous strip of the symbol is thereby spread across every block instead
+// of destroying one block outright.
+function interleave(data, version, ecc) {
+    const [ecLen, b1, d1, b2, d2] = BLOCKS[ecc][version - 1];
+    const blocks = [];
+    let off = 0;
+    for (let i = 0; i < b1 + b2; i++) {
+        const n = i < b1 ? d1 : d2;
+        const chunk = data.subarray(off, off + n);
+        off += n;
+        blocks.push({ data: chunk, ec: rsEncode(chunk, ecLen) });
+    }
+    const out = [];
+    for (let i = 0; i < Math.max(d1, d2); i++)
+        for (const b of blocks)
+            if (i < b.data.length)
+                out.push(b.data[i]);
+    for (let i = 0; i < ecLen; i++)
+        for (const b of blocks)
+            out.push(b.ec[i]);
+    return Uint8Array.from(out);
+}
+function drawFunctionPatterns(version) {
+    const size = 4 * version + 17;
+    const modules = Array.from({ length: size }, () => new Array(size).fill(false));
+    const fn = Array.from({ length: size }, () => new Array(size).fill(false));
+    const set = (r, c, v) => {
+        if (r < 0 || r >= size || c < 0 || c >= size)
+            return;
+        modules[r][c] = v;
+        fn[r][c] = true;
+    };
+    // finder + its separator ring as one 9×9 stamp per corner. Chebyshev distance
+    // from the centre gives the concentric rings for free: dark at 0,1,3 — light
+    // at 2 (the gap) and 4+ (the separator).
+    for (const [fr, fc] of [
+        [0, 0],
+        [0, size - 7],
+        [size - 7, 0],
+    ])
+        for (let dr = -1; dr <= 7; dr++)
+            for (let dc = -1; dc <= 7; dc++) {
+                const d = Math.max(Math.abs(dr - 3), Math.abs(dc - 3));
+                set(fr + dr, fc + dc, d !== 2 && d <= 3);
+            }
+    // timing: only the span between the finders, which already own both ends
+    for (let i = 8; i < size - 8; i++) {
+        set(6, i, i % 2 === 0);
+        set(i, 6, i % 2 === 0);
+    }
+    // alignment: every centre pair except the three that would sit on a finder
+    const pos = ALIGN_POS[version - 1];
+    const last = size - 7;
+    for (const r of pos)
+        for (const c of pos) {
+            if ((r === 6 && c === 6) ||
+                (r === 6 && c === last) ||
+                (r === last && c === 6))
+                continue;
+            for (let dr = -2; dr <= 2; dr++)
+                for (let dc = -2; dc <= 2; dc++)
+                    set(r + dr, c + dc, Math.max(Math.abs(dr), Math.abs(dc)) !== 1);
+        }
+    // format-info strips: RESERVED now, valued per-mask later. The two timing
+    // modules that fall inside these strips keep the value set above — the format
+    // placement below jogs around them, which is what the 14−i index is for.
+    for (let i = 0; i <= 8; i++) {
+        fn[8][i] = true;
+        fn[i][8] = true;
+    }
+    for (let i = 0; i < 8; i++) {
+        fn[8][size - 1 - i] = true;
+        fn[size - 1 - i][8] = true;
+    }
+    // NB the dark module at (4·version+9, 8) is deliberately NOT written here —
+    // it sits inside the format region reserved just above, and drawFormatBits
+    // owns its value. Writing it in both places made it un-mutatable: breaking
+    // one copy left the other silently correcting it.
+    if (version >= 7) {
+        // the two copies are transposes of each other, so one loop writes both
+        const vb = versionBits(version);
+        for (let i = 0; i < 18; i++) {
+            const on = ((vb >>> i) & 1) === 1;
+            const r = (i / 3) | 0;
+            const c = size - 11 + (i % 3);
+            set(r, c, on);
+            set(c, r, on);
+        }
+    }
+    return { size, modules, fn };
+}
+// Zigzag up-and-down through two-module-wide columns from the bottom right,
+// skipping the vertical timing column entirely (right===6 → 5).
+function placeData(modules, fn, size, cw) {
+    let i = 0;
+    for (let right = size - 1; right >= 1; right -= 2) {
+        if (right === 6)
+            right = 5;
+        for (let vert = 0; vert < size; vert++)
+            for (let j = 0; j < 2; j++) {
+                const c = right - j;
+                const upward = ((right + 1) & 2) === 0;
+                const r = upward ? size - 1 - vert : vert;
+                if (!fn[r][c] && i < cw.length * 8) {
+                    modules[r][c] = ((cw[i >>> 3] >>> (7 - (i & 7))) & 1) === 1;
+                    i++;
+                }
+            }
+    }
+    return i;
+}
+function drawFormatBits(m, size, ecc, mask) {
+    const bits = formatBits(ecc, mask);
+    const bit = (i) => ((bits >>> i) & 1) === 1;
+    for (let i = 0; i <= 5; i++)
+        m[i][8] = bit(i);
+    m[7][8] = bit(6);
+    m[8][8] = bit(7);
+    m[8][7] = bit(8);
+    for (let i = 9; i < 15; i++)
+        m[8][14 - i] = bit(i);
+    for (let i = 0; i < 8; i++)
+        m[8][size - 1 - i] = bit(i);
+    for (let i = 8; i < 15; i++)
+        m[size - 15 + i][8] = bit(i);
+    m[size - 8][8] = true;
+}
+// The four penalty rules. Lower is better; this is the whole basis for choosing
+// a mask, and the numbers (3/1, 3, 40, 10) are the spec's, not tuned.
+const P3A = [1, 0, 1, 1, 1, 0, 1, 0, 0, 0, 0]; // 1:1:3:1:1 finder-alike + light run
+const P3B = [0, 0, 0, 0, 1, 0, 1, 1, 1, 0, 1]; // …and its mirror
+function penalty(m, size) {
+    let score = 0;
+    const line = new Array(size);
+    const scan = () => {
+        let run = 1;
+        for (let i = 1; i < size; i++) {
+            if (line[i] === line[i - 1]) {
+                run++;
+                if (run === 5)
+                    score += 3;
+                else if (run > 5)
+                    score += 1;
+            }
+            else
+                run = 1;
+        }
+        for (let i = 0; i + 11 <= size; i++) {
+            let a = true;
+            let b = true;
+            for (let k = 0; k < 11 && (a || b); k++) {
+                if (line[i + k] !== P3A[k])
+                    a = false;
+                if (line[i + k] !== P3B[k])
+                    b = false;
+            }
+            if (a)
+                score += 40;
+            if (b)
+                score += 40;
+        }
+    };
+    for (let r = 0; r < size; r++) {
+        for (let i = 0; i < size; i++)
+            line[i] = m[r][i] ? 1 : 0;
+        scan();
+    }
+    for (let c = 0; c < size; c++) {
+        for (let i = 0; i < size; i++)
+            line[i] = m[i][c] ? 1 : 0;
+        scan();
+    }
+    let dark = 0;
+    for (let r = 0; r + 1 < size; r++)
+        for (let c = 0; c + 1 < size; c++) {
+            const v = m[r][c];
+            if (v === m[r][c + 1] && v === m[r + 1][c] && v === m[r + 1][c + 1])
+                score += 3;
+        }
+    for (let r = 0; r < size; r++)
+        for (let c = 0; c < size; c++)
+            if (m[r][c])
+                dark++;
+    score += 10 * Math.floor(Math.abs((dark * 100) / (size * size) - 50) / 5);
+    return score;
+}
+// forcedMask exists for the test suite (exercise all eight placements); the
+// public API never takes one, because "which mask" is not a user-meaningful
+// choice — it is whichever one scans best.
+function buildMatrix(bytes, version, ecc, forcedMask) {
+    const { size, modules, fn } = drawFunctionPatterns(version);
+    const cw = interleave(encodeData(bytes, version, ecc), version, ecc);
+    placeData(modules, fn, size, cw);
+    let best = null;
+    for (let mask = 0; mask < 8; mask++) {
+        if (forcedMask != null && mask !== forcedMask)
+            continue;
+        const m = modules.map((row) => row.slice());
+        const fmask = MASKS[mask];
+        for (let r = 0; r < size; r++)
+            for (let c = 0; c < size; c++)
+                if (!fn[r][c] && fmask(r, c))
+                    m[r][c] = !m[r][c];
+        drawFormatBits(m, size, ecc, mask);
+        const score = penalty(m, size);
+        if (!best || score < best.score)
+            best = { score, modules: m, mask };
+    }
+    return {
+        size,
+        modules: best.modules,
+        mask: best.mask,
+        version,
+        ecc,
+        codewords: cw,
+    };
+}
+function normalizeOpts(opts) {
+    const o = opts && typeof opts === "object" ? opts : {};
+    const raw = typeof o.ecc === "string" ? o.ecc.toUpperCase() : "";
+    const ecc = BLOCKS[raw]
+        ? raw
+        : "M";
+    let minVersion = Math.trunc(Number(o.minVersion));
+    if (!Number.isFinite(minVersion) || minVersion < 1)
+        minVersion = 1;
+    if (minVersion > MAX_VERSION)
+        minVersion = MAX_VERSION;
+    return { ecc, minVersion };
+}
+export function qrMatrix(text, opts) {
+    const { ecc, minVersion } = normalizeOpts(opts);
+    const bytes = toBytes(text);
+    let version = 0;
+    for (let v = minVersion; v <= MAX_VERSION; v++)
+        if (bytes.length <= maxBytes(v, ecc)) {
+            version = v;
+            break;
+        }
+    if (!version)
+        throw new Error(`qr: ${bytes.length} bytes will not fit — version ${MAX_VERSION} at ECC ${ecc} holds ` +
+            `${maxBytes(MAX_VERSION, ecc)}. Shorten the URL or drop to ECC "L".`);
+    const { size, modules } = buildMatrix(bytes, version, ecc, null);
+    return { size, modules };
+}
+export function qrCanvas(text, opts) {
+    if (typeof document === "undefined")
+        throw new Error("qr: qrCanvas needs a document — under node, call qrMatrix and render it yourself.");
+    const o = opts && typeof opts === "object" ? opts : {};
+    // null/undefined mean "unspecified", NOT zero — Number(null) is 0, and a
+    // margin of 0 is a symbol with no quiet zone, which scans far worse than one
+    // with the default. An explicit 0 still gets through.
+    const num = (v, def, lo, hi) => {
+        if (v == null)
+            return def;
+        const n = Math.round(Number(v));
+        return Number.isFinite(n) && n >= lo && n <= hi ? n : def;
+    };
+    const scale = num(o.scale, 4, 1, 64);
+    const margin = num(o.margin, 4, 0, 32); // 4 modules is the spec's minimum quiet zone
+    const dark = typeof o.dark === "string" && o.dark ? o.dark : "#0c0e12";
+    const light = typeof o.light === "string" && o.light ? o.light : "#e2e5ea";
+    const { size, modules } = qrMatrix(text, o);
+    const px = (size + margin * 2) * scale;
+    const canvas = document.createElement("canvas");
+    canvas.width = px;
+    canvas.height = px;
+    // A QR is a hard-edged bitmap: any smoothing on upscale eats the 1-module
+    // gaps a decoder measures. This is the one property that matters if CSS ever
+    // sizes the element away from its intrinsic pixels.
+    canvas.style.imageRendering = "pixelated";
+    canvas.setAttribute("role", "img");
+    canvas.setAttribute("aria-label", `QR code for ${text == null ? "" : String(text)}`);
+    const ctx = canvas.getContext("2d");
+    if (!ctx)
+        return canvas; // context can be refused under memory pressure; a blank canvas beats a throw
+    ctx.fillStyle = light;
+    ctx.fillRect(0, 0, px, px);
+    ctx.fillStyle = dark;
+    // merge horizontal runs into one rect each: same picture, ~5× fewer draw calls,
+    // and no hairline seams between adjacent modules on fractional device pixels
+    for (let r = 0; r < size; r++) {
+        let c = 0;
+        while (c < size) {
+            if (!modules[r][c]) {
+                c++;
+                continue;
+            }
+            let end = c;
+            while (end < size && modules[r][end])
+                end++;
+            ctx.fillRect((margin + c) * scale, (margin + r) * scale, (end - c) * scale, scale);
+            c = end;
+        }
+    }
+    // Nothing here animates — a QR that moves is a QR that does not scan — so
+    // prefers-reduced-motion has nothing to collapse. Callers that fade this
+    // element in should honour it at their own call site.
+    return canvas;
+}
+// The remaining internals are exported for the vitest suite only (the
+// round-trip reader, the published-table cross-checks and the mask/penalty
+// decomposition live in tests/unit/advisors/qr.test.ts). They are internal
+// surface: not re-exported from the package barrel, and not a stability promise.
+export { MAX_VERSION, MODE_BYTE, PAD_BYTES, ECC_BITS, BLOCKS, TOTAL_CW, ALIGN_POS, MASKS, P3A, P3B, GF_EXP, GF_LOG, gfMul, rsGenerator, rsEncode, rsSyndromes, formatBits, versionBits, charCountBits, dataCodewords, maxBytes, toBytes, encodeData, interleave, drawFunctionPatterns, placeData, drawFormatBits, penalty, buildMatrix, };

package/dist/video/advisors/quiet-listening.d.ts

@@ -0,0 +1,73 @@
+/**
+ * "Night ears": loudness-compensated quiet listening. Ported verbatim from
+ * extension-library `lib/quiet-listening.js` (mos-5lzns.27). The graph builder
+ * lands here as mos-5lzns.31's contract promised (audio.ts is that task's
+ * wiring target); `amountFor` is the piece every caller can already use.
+ *
+ * This module owns TONE, never LEVEL. The host's loudness matching already
+ * rides the gain toward a target and a limiter catches the peaks; nothing in
+ * here adds makeup gain, and the fact that it doesn't is the whole reason the
+ * two can run at once without fighting. If this file ever grows a gain node
+ * that isn't pinned at unity, the rider downstream will chase it and you'll get
+ * the pumping that loudness matching was written to stop.
+ *
+ * The problem it does solve: your ears are not flat, and they get less flat the
+ * quieter things are. Equal-loudness contours (Fletcher–Munson, and the ISO 226
+ * revision that corrected them) fall off at both ends as level drops — at 2am
+ * at a volume that won't wake anyone, the bass has gone and the air on top has
+ * gone with it, and what's left is a midrange smear where dialogue used to be.
+ * The usual response is to keep nudging the volume up for the quiet line and
+ * back down for the next loud one. This tilts the spectrum back instead, and
+ * tightens the dynamics just enough that a whispered line rides above the room
+ * noise of a fridge and a fan.
+ *
+ * Rejected: a real ISO 226 inverse curve per SPL. It needs the absolute
+ * playback SPL to mean anything, and a browser cannot know the amp, the
+ * speakers, or the room — a curve derived from a number we can't measure is
+ * theatre. Two shelves and a presence bump are the honest version of the same
+ * idea: right shape, calibration left as one dial the listener can hear.
+ *
+ *   createQuietChain(ctx) -> { input, output, setAmount, dispose }
+ *   amountFor(volume, nightOn, opts) -> 0..1
+ *
+ * Module rules (src/lib/video/README.md): reads no settings, touches no
+ * <video> — the graph builder is the audio graph's one sanctioned exception
+ * and it takes an AudioContext(-shaped) object, never the element.
+ */
+/** Minimal duck-typed surface of an AudioContext this module touches. */
+export interface QuietAudioContext {
+    createGain?: unknown;
+    createBiquadFilter?: unknown;
+    createDynamicsCompressor?: unknown;
+    currentTime?: unknown;
+    [key: string]: unknown;
+}
+interface AudioParamLike {
+    value: number;
+    setTargetAtTime?(value: number, startTime: number, timeConstant: number): void;
+}
+interface AudioNodeLike {
+    gain?: AudioParamLike;
+    frequency?: AudioParamLike;
+    Q?: AudioParamLike;
+    threshold?: AudioParamLike;
+    ratio?: AudioParamLike;
+    knee?: AudioParamLike;
+    attack?: AudioParamLike;
+    release?: AudioParamLike;
+    type?: string;
+    connect?(node: unknown): void;
+    disconnect?(): void;
+}
+export interface QuietChain {
+    input: AudioNodeLike | null;
+    output: AudioNodeLike | null;
+    setAmount(a: unknown): void;
+    dispose(): void;
+}
+export declare function createQuietChain(ctx: QuietAudioContext | null | undefined): QuietChain;
+export interface AmountOpts {
+    knee?: number;
+}
+export declare function amountFor(volume: unknown, nightOn: unknown, opts?: AmountOpts | null): number;
+export {};