@woosh/meep-engine 3.26.0 → 3.28.0

package/src/core/binary/lz4/lz4_compress_block_hc.js

@@ -0,0 +1,1382 @@
+import { assert } from "../../assert.js";
+import { lsb_32 } from "../lsb_32.js";
+import { LZ4_LEVEL } from "./LZ4_LEVEL.js";
+import { LZ4_MAX_INPUT_SIZE } from "./LZ4_MAX_INPUT_SIZE.js";
+
+/** the shortest match the format can code — the match length field is biased by this */
+const MIN_MATCH = 4;
+
+/** no match starts within this many bytes of the end of a block */
+const MATCH_FIND_LIMIT = 12;
+
+/** the last bytes of a block are literals, and no match may cover them */
+const LAST_LITERALS = 5;
+
+/** below this there is no room for a match at all, so the block is one literal run */
+const MIN_LENGTH = MATCH_FIND_LIMIT + 1;
+
+/** the offset field is sixteen bits, so a match reaches back no further than this */
+const MAX_DISTANCE = 0xFFFF;
+
+/** both length nibbles saturate here, and continue in whole bytes */
+const NIBBLE_MAX = 15;
+
+/** a length continuation codes this much per byte, and a byte below it ends the run */
+const CONTINUATION_MAX = 255;
+
+/**
+ * Literal runs shorter than this are cheaper to copy a byte at a time than to hand to `set`, whose
+ * call overhead dominates until there is a memmove's worth of work behind it. The high-compression
+ * encoder finds more matches than the fast one and so writes *shorter* literal runs on geometry —
+ * about 38 bytes a sequence against 62 — but on text it is the other way round, and the runs there
+ * are long enough that the call pays.
+ */
+const BULK_COPY_LENGTH = 32;
+
+/**
+ * The match length past which the lazy parse stops trying to squeeze a second match in front of
+ * the one it has: the longest match whose length still fits the token's nibble.
+ */
+const OPTIMAL_ML = (NIBBLE_MAX - 1) + MIN_MATCH;
+
+/** Knuth's multiplicative constant, which is what the reference encoder hashes with */
+const HASH_MULTIPLIER = 2654435761;
+
+/**
+ * The high-compression encoder hashes into a table twice the width of the fast one's, because it
+ * keeps a chain per slot rather than a single position and a collision costs a walk rather than a
+ * miss.
+ */
+const HASH_LOG = 15;
+const HASH_SHIFT = 32 - HASH_LOG;
+
+/**
+ * Positions are held in an index space biased by one window, so that a zeroed hash slot reads as a
+ * position a whole window before the block — which is to say, as one no match may reach. That is
+ * what keeps blocks self-contained without a special case in the search: the "is this candidate
+ * inside the block" test the reference already needs is the same test that rejects an empty slot.
+ */
+const IDX_BASE = 0x10000;
+
+/** how many attempts a search makes before pattern analysis is worth its own cost */
+const PATTERN_ANALYSIS_THRESHOLD = 128;
+
+/** positions the shortest path is solved over at once */
+const OPT_NUM = 1 << 12;
+
+/** positions past the last match a solved window also prices, as plain literals */
+const TRAILING_LITERALS = 3;
+
+/** the parse tables carry this many entries, which is the furthest either index above reaches */
+const OPT_TABLE_SIZE = OPT_NUM + TRAILING_LITERALS;
+
+/**
+ * Whether the four bytes under the search are a repeat of a single byte, which is what makes a
+ * chain of consecutive positions worth jumping over rather than walking.
+ */
+const REPEAT_UNTESTED = 0;
+const REPEAT_NOT = 1;
+const REPEAT_CONFIRMED = 2;
+
+/**
+ * What each level searches with, indexed by the level itself. The boundaries that matter are not
+ * the level numbers: the strategy changes at 10, and pattern analysis turns on above
+ * {@link PATTERN_ANALYSIS_THRESHOLD} attempts, which is what makes 9 the first level that has it.
+ *
+ * Entries for 0 and 2 are `null` — the reference gives level 2 different algorithms in different
+ * releases, so this encoder does not offer it. See {@link LZ4_LEVEL}.
+ *
+ * `attempts` is how many chain links a single search walks. `sufficient_length` is the match length
+ * at which a search stops looking for better and the parse takes what it has; it is also what keeps
+ * the optimal parse out of quadratic time on a run of one byte.
+ *
+ * @see https://github.com/lz4/lz4/blob/dev/lib/lz4hc.c — `k_clTable`
+ * @type {({attempts: number, sufficient_length: number, optimal: boolean, full_update: boolean}|null)[]}
+ */
+const LEVEL_TABLE = [
+    null,
+    null,
+    null,
+    { attempts: 4, sufficient_length: 16, optimal: false, full_update: false },
+    { attempts: 8, sufficient_length: 16, optimal: false, full_update: false },
+    { attempts: 16, sufficient_length: 16, optimal: false, full_update: false },
+    { attempts: 32, sufficient_length: 16, optimal: false, full_update: false },
+    { attempts: 64, sufficient_length: 16, optimal: false, full_update: false },
+    { attempts: 128, sufficient_length: 16, optimal: false, full_update: false },
+    { attempts: 256, sufficient_length: 16, optimal: false, full_update: false },
+    { attempts: 96, sufficient_length: 64, optimal: true, full_update: false },
+    { attempts: 512, sufficient_length: 128, optimal: true, full_update: false },
+    { attempts: 16384, sufficient_length: OPT_NUM, optimal: true, full_update: true }
+];
+
+/**
+ * The newest position carrying each four-byte hash, and, per position, the distance back to the
+ * previous position carrying the same one. Together they are the chain a search walks.
+ *
+ * Both are allocated on the first high-compression call rather than at module scope, and the parse
+ * tables below on the first call above level 9. meep ships raw source: a consumer that only ever
+ * *decodes* — which is what the runtime does — would otherwise hold a third of a megabyte of
+ * encoder tables for nothing.
+ *
+ * Module-static once taken, on the same terms as the fast encoder's table: this is straight-line
+ * synchronous code that clears what it needs on entry, so no second call can be part-way through.
+ *
+ * @type {Int32Array|null}
+ */
+let hash_table = null;
+
+/** @type {Uint16Array|null} */
+let chain_table = null;
+
+/** the cheapest coding of the first `n` bytes found so far, and what the last step of it was */
+/** @type {Int32Array|null} */
+let opt_price = null;
+/** @type {Int32Array|null} */
+let opt_offset = null;
+/** @type {Int32Array|null} */
+let opt_match_length = null;
+/** @type {Int32Array|null} */
+let opt_literal_length = null;
+
+/*
+ The call in progress. The reference carries these as a context struct and a pile of pointers; here
+ they are module bindings for the same reason the tables are, and with the same argument for why it
+ is safe. Positions below are *block* positions — zero is the first byte of the input — and the
+ index space the hash and chain tables are keyed in is that plus IDX_BASE.
+*/
+
+/** @type {Uint8Array} */
+let source = null;
+/** @type {DataView} */
+let view = null;
+/** @type {Uint8Array} */
+let destination = null;
+
+/** where block position zero sits in {@link source} */
+let base = 0;
+
+/** bytes of input */
+let input_size = 0;
+
+/** one past the last position a search may start at */
+let match_find_limit = 0;
+
+/** one past the last byte a match may cover */
+let match_limit = 0;
+
+/** positions below this are already on their chain */
+let next_to_update = 0;
+
+/** where the next output byte goes, and one past the last the block may write */
+let out = 0;
+let out_end = 0;
+
+/*
+ What the last search found. The searches run thousands of times over a page and the reference
+ returns a three-field struct from each one; returning an object here would be that many allocations
+ for a value read immediately and never kept.
+*/
+
+/** the length of the match found, less than {@link MIN_MATCH} when there is none */
+let found_length = 0;
+
+/** how far back it reaches */
+let found_offset = 0;
+
+/** how far *before* the position searched from it starts, as a negative number */
+let found_back = 0;
+
+/** where {@link encode_window} left the parse, for the same reason */
+let window_ip = 0;
+let window_anchor = 0;
+
+/**
+ * @param {number} sequence four bytes of input, read little-endian
+ * @returns {number} a slot in {@link hash_table}
+ */
+function hash_of(sequence) {
+    return Math.imul(sequence, HASH_MULTIPLIER) >>> HASH_SHIFT;
+}
+
+/**
+ * Bytes a length continuation takes to carry `remainder`.
+ *
+ * @param {number} remainder what is left of a length once its nibble saturated
+ * @returns {number}
+ */
+function continuation_size(remainder) {
+    return 1 + ((remainder / CONTINUATION_MAX) | 0);
+}
+
+/**
+ * Write a length continuation: whole 255s, then a byte below 255 to end it.
+ *
+ * @param {number} d
+ * @param {number} remainder
+ * @returns {number} the offset just past the last byte written
+ */
+function write_continuation(d, remainder) {
+    let r = remainder;
+    let p = d;
+
+    while (r >= CONTINUATION_MAX) {
+        destination[p++] = CONTINUATION_MAX;
+        r -= CONTINUATION_MAX;
+    }
+
+    destination[p++] = r;
+
+    return p;
+}
+
+/**
+ * Two bytes of the block, with anything outside it reading as zero.
+ *
+ * This exists for one read: the candidate's half of the cheap test the search makes before a full
+ * compare, which looks at the two bytes where the *current best* match would end on either side.
+ * When a search is allowed to start behind the position it was called at — which is what the lazy
+ * parse's second and third searches do — the candidate's half is at `match - look_back + longest - 1`,
+ * and nothing in the arithmetic there stops it landing before the block. The reference reads
+ * whatever the buffer holds; a block that is a window into a larger buffer would then compress
+ * differently depending on what its caller happened to put in front of it, which is not a property
+ * an encoder is allowed to have. Reachable or not, it is cheap to make impossible, and the specs
+ * pin it by compressing the same payload at five offsets inside five different paddings.
+ *
+ * The *searched* side of that test needs no such guard: it sits at `low_limit + longest - 1`, and
+ * `longest` is never more than what a match starting at `low_limit` could cover, so it is inside
+ * the block by construction.
+ *
+ * @param {number} position a block position, which may be outside the block
+ * @returns {number}
+ */
+function read16_in_block(position) {
+    const low = (position >= 0 && position < input_size) ? source[base + position] : 0;
+    const high = (position + 1 >= 0 && position + 1 < input_size) ? source[base + position + 1] : 0;
+
+    return low | (high << 8);
+}
+
+/**
+ * How many bytes beyond the four already known to agree two positions agree on.
+ *
+ * @param {number} a the later position, past its first four bytes
+ * @param {number} b the earlier position, past its first four bytes
+ * @param {number} limit one past the last byte a match may cover
+ * @returns {number}
+ */
+function count_match(a, b, limit) {
+    let p = a;
+    let q = b;
+
+    while (p + 4 <= limit && view.getUint32(base + p, true) === view.getUint32(base + q, true)) {
+        p += 4;
+        q += 4;
+    }
+
+    while (p < limit && source[base + p] === source[base + q]) {
+        p++;
+        q++;
+    }
+
+    return p - a;
+}
+
+/**
+ * How many bytes *before* two positions agree, as a negative number, bounded on both sides.
+ *
+ * @param {number} ip the later position
+ * @param {number} match the earlier position
+ * @param {number} i_min the furthest back `ip` may walk
+ * @param {number} m_min the furthest back `match` may walk
+ * @returns {number} zero or less
+ */
+function count_back(ip, match, i_min, m_min) {
+    const a = i_min - ip;
+    const b = m_min - match;
+    const min = a > b ? a : b;
+
+    let back = 0;
+
+    while ((back - min) > 3) {
+        const v = view.getUint32(base + ip + back - 4, true) ^ view.getUint32(base + match + back - 4, true);
+
+        if (v !== 0) {
+            // the bytes nearest `back` are the high ones of a little-endian word, so the leading
+            // zero bytes of the difference are the ones that agreed
+            return back - (Math.clz32(v) >> 3);
+        }
+
+        back -= 4;
+    }
+
+    while (back > min && source[base + ip + back - 1] === source[base + match + back - 1]) {
+        back--;
+    }
+
+    return back;
+}
+
+/**
+ * How far a repeat of `pattern` runs forward from `position`.
+ *
+ * `pattern` is four bytes of a run whose period divides four — one byte, two bytes, or four — which
+ * is the only shape the caller ever offers it, and what makes reading it four bytes at a time
+ * rather than eight, as the reference does on a 64-bit word, give the same answer.
+ *
+ * @param {number} position
+ * @param {number} end one past the last byte it may look at
+ * @param {number} pattern
+ * @returns {number}
+ */
+function count_pattern(position, end, pattern) {
+    let p = position;
+
+    while (p < end - 3) {
+        const diff = view.getUint32(base + p, true) ^ pattern;
+
+        if (diff === 0) {
+            p += 4;
+            continue;
+        }
+
+        // the first byte that differs is the lowest one set, and the bytes below it agreed
+        return (p - position) + (lsb_32(diff) >> 3);
+    }
+
+    let shift = 0;
+
+    while (p < end && source[base + p] === ((pattern >>> shift) & 0xFF)) {
+        p++;
+        shift = (shift + 8) & 31;
+    }
+
+    return p - position;
+}
+
+/**
+ * How far a repeat of `pattern` runs *backwards* from `position`.
+ *
+ * @param {number} position
+ * @param {number} low the furthest back it may look
+ * @param {number} pattern
+ * @returns {number} zero or more
+ */
+function reverse_count_pattern(position, low, pattern) {
+    let p = position;
+
+    while (p >= low + 4) {
+        if (view.getUint32(base + p - 4, true) !== pattern) {
+            break;
+        }
+
+        p -= 4;
+    }
+
+    // the byte just before `p` is the pattern's last one, and walking back walks the pattern back
+    let shift = 24;
+
+    while (p > low && source[base + p - 1] === ((pattern >>> shift) & 0xFF)) {
+        p--;
+        shift -= 8;
+    }
+
+    return position - p;
+}
+
+/**
+ * Put every position below `position` on its chain.
+ *
+ * Lazily, from wherever the last search left off: a position is only ever wanted by a search that
+ * starts after it, so nothing is built that is never walked. The chain holds, per position, the
+ * *distance* back to the previous position with the same hash, which is what lets it be sixteen
+ * bits wide — a distance further than the window is one no match may use anyway, and saturating it
+ * there ends the walk exactly where the window does.
+ *
+ * @param {number} position a block position
+ */
+function insert(position) {
+    const target = position + IDX_BASE;
+
+    let idx = next_to_update;
+
+    while (idx < target) {
+        const h = hash_of(view.getUint32(base + idx - IDX_BASE, true));
+
+        let delta = idx - hash_table[h];
+
+        if (delta > MAX_DISTANCE) {
+            delta = MAX_DISTANCE;
+        }
+
+        chain_table[idx & 0xFFFF] = delta;
+        hash_table[h] = idx;
+
+        idx++;
+    }
+
+    next_to_update = target;
+}
+
+/**
+ * Walk the chain from `position` and leave the best match it holds in {@link found_length},
+ * {@link found_offset} and {@link found_back}.
+ *
+ * `low_limit` is where the match is allowed to *start*, which the caller sets behind `position`
+ * when it wants a match that reaches back over bytes an earlier one already covers; `found_back`
+ * comes back as how far behind `position` the match actually starts, and is zero or less. `longest`
+ * is what the caller already has, so a search that cannot beat it reports nothing.
+ *
+ * @param {number} position where the four bytes being matched are
+ * @param {number} low_limit the earliest position the match may start at
+ * @param {number} high_limit one past the last byte the match may cover
+ * @param {number} longest the length to beat
+ * @param {number} max_attempts how many links of the chain to walk
+ * @param {boolean} pattern_analysis whether to jump over runs rather than walk them
+ * @param {boolean} chain_swap whether to change chains on a tie
+ */
+function insert_and_get_wider_match(position, low_limit, high_limit, longest, max_attempts, pattern_analysis, chain_swap) {
+    // the call's context, read once: the loop below runs hundreds of millions of times over a
+    // conversion, and a module binding is not a local
+    const bytes = source;
+    const data = view;
+    const origin = base;
+    const length = input_size;
+    const chain = chain_table;
+
+    const ip_index = position + IDX_BASE;
+
+    // A match reaches back a window, and never before the block. Below one window in, those are the
+    // same bound, and the block's own start is what holds — which is also what makes an empty hash
+    // slot, reading as a position a window before the block, fail the test for free.
+    const lowest_match_index = (IDX_BASE + MAX_DISTANCE + 1) > ip_index ? IDX_BASE : ip_index - MAX_DISTANCE;
+
+    const look_back_length = position - low_limit;
+    const pattern = data.getUint32(origin + position, true);
+
+    let attempts = max_attempts;
+    let match_chain_pos = 0;
+    let repeat = REPEAT_UNTESTED;
+    let source_pattern_length = 0;
+    let offset = 0;
+    let s_back = 0;
+
+    insert(position);
+
+    let match_index = hash_table[hash_of(pattern)];
+
+    while (match_index >= lowest_match_index && attempts > 0) {
+        const match_position = match_index - IDX_BASE;
+
+        let match_length = 0;
+
+        attempts--;
+
+        // The cheap rejection: unless the two bytes where the current best match *ends* agree, no
+        // longer match can start here, and the full compare is not worth making. This is the
+        // hottest read in the encoder — once per link of every chain walked — so the candidate's
+        // side takes the guard only on the addresses that need it.
+        const gate = origin + low_limit + longest - 1;
+        const candidate_gate = match_position - look_back_length + longest - 1;
+
+        const candidate_bytes = (candidate_gate >= 0 && candidate_gate + 1 < length)
+            ? (bytes[origin + candidate_gate] | (bytes[origin + candidate_gate + 1] << 8))
+            : read16_in_block(candidate_gate);
+
+        if ((bytes[gate] | (bytes[gate + 1] << 8)) === candidate_bytes) {
+            if (data.getUint32(origin + match_position, true) === pattern) {
+                const back = look_back_length !== 0 ? count_back(position, match_position, low_limit, 0) : 0;
+
+                match_length = MIN_MATCH + count_match(position + MIN_MATCH, match_position + MIN_MATCH, high_limit);
+                match_length -= back;
+
+                if (match_length > longest) {
+                    longest = match_length;
+                    offset = ip_index - match_index;
+                    s_back = back;
+                }
+            }
+        }
+
+        // A tie means this chain has nothing more to offer. The positions inside the match have
+        // chains of their own, and the one that steps furthest back is the one worth following.
+        if (chain_swap && match_length === longest && match_index + longest <= ip_index) {
+            const end = longest - MIN_MATCH + 1;
+
+            let distance_to_next_match = 1;
+            let step = 1;
+            let accel = 1 << 4;
+
+            for (let p = 0; p < end; p += step) {
+                const candidate_distance = chain[(match_index + p) & 0xFFFF];
+
+                step = accel >> 4;
+                accel++;
+
+                if (candidate_distance > distance_to_next_match) {
+                    distance_to_next_match = candidate_distance;
+                    match_chain_pos = p;
+                    accel = 1 << 4;
+                }
+            }
+
+            if (distance_to_next_match > 1) {
+                if (distance_to_next_match > match_index) {
+                    break;
+                }
+
+                match_index -= distance_to_next_match;
+                continue;
+            }
+        }
+
+        // Consecutive positions on one chain are a run of the same byte. Walking it link by link
+        // is what takes the wider levels quadratic on a page of zeros; measuring the run instead
+        // and jumping to the best place in it is what makes them finish at all. It does not make
+        // them *fast*: the reference measures pattern analysis as paying for its own cost by level
+        // 9, on an eight-byte scan this port does at four, and here level 9 still comes out about
+        // 5% slower than level 3 on real pages.
+        if (pattern_analysis && chain[match_index & 0xFFFF] === 1 && match_chain_pos === 0) {
+            const candidate_index = match_index - 1;
+
+            if (repeat === REPEAT_UNTESTED) {
+                if (((pattern & 0xFFFF) === (pattern >>> 16)) && ((pattern & 0xFF) === (pattern >>> 24))) {
+                    repeat = REPEAT_CONFIRMED;
+                    source_pattern_length = count_pattern(position + 4, high_limit, pattern) + 4;
+                } else {
+                    repeat = REPEAT_NOT;
+                }
+            }
+
+            if (repeat === REPEAT_CONFIRMED && candidate_index >= lowest_match_index) {
+                const candidate_position = candidate_index - IDX_BASE;
+
+                if (data.getUint32(origin + candidate_position, true) === pattern) {
+                    const forward_length = count_pattern(candidate_position + 4, high_limit, pattern) + 4;
+
+                    const raw_back = reverse_count_pattern(candidate_position, 0, pattern);
+                    const floor = candidate_index - raw_back > lowest_match_index
+                        ? candidate_index - raw_back
+                        : lowest_match_index;
+                    const back_length = candidate_index - floor;
+
+                    const segment_length = back_length + forward_length;
+
+                    if (segment_length >= source_pattern_length && forward_length <= source_pattern_length) {
+                        // the run here is long enough to hold the whole of the run at `position`,
+                        // and this is where the two line up
+                        match_index = candidate_index + forward_length - source_pattern_length;
+                    } else {
+                        // otherwise take the far end of the run, which is the longest match in it
+                        match_index = floor;
+
+                        if (look_back_length === 0) {
+                            const max_length = segment_length < source_pattern_length
+                                ? segment_length
+                                : source_pattern_length;
+
+                            if (longest < max_length) {
+                                if (ip_index - match_index > MAX_DISTANCE) {
+                                    break;
+                                }
+
+                                longest = max_length;
+                                offset = ip_index - match_index;
+                            }
+
+                            const distance_to_next_pattern = chain[match_index & 0xFFFF];
+
+                            if (distance_to_next_pattern > match_index) {
+                                break;
+                            }
+
+                            match_index -= distance_to_next_pattern;
+                        }
+                    }
+
+                    continue;
+                }
+            }
+        }
+
+        match_index -= chain[(match_index + match_chain_pos) & 0xFFFF];
+    }
+
+    found_length = longest;
+    found_offset = offset;
+    found_back = s_back;
+}
+
+/**
+ * The same search, made from the position the match must start at — so it cannot reach behind, and
+ * {@link found_back} comes back zero.
+ *
+ * @param {number} position
+ * @param {number} high_limit
+ * @param {number} max_attempts
+ * @param {boolean} pattern_analysis
+ */
+function insert_and_find_best_match(position, high_limit, max_attempts, pattern_analysis) {
+    insert_and_get_wider_match(position, position, high_limit, MIN_MATCH - 1, max_attempts, pattern_analysis, false);
+}
+
+/**
+ * Write one sequence: the token, the literal run in front of the match, the match's offset, and
+ * whatever its length spilled into.
+ *
+ * Where the fast encoder splits this — it knows a match's length only after it has written the
+ * token the length shares with the literal count — the high-compression parses hand a whole
+ * sequence over at once, so it is written as one unit and bounds-checked at the two points the
+ * output can actually run out.
+ *
+ * @param {number} anchor the first literal
+ * @param {number} position one past the last literal, and the first byte of the match
+ * @param {number} match_length
+ * @param {number} offset how far back the match reaches
+ * @throws {Error} if the sequence does not fit the space given
+ */
+function encode_sequence(anchor, position, match_length, offset) {
+    const literal_length = position - anchor;
+    const literal_saturated = literal_length >= NIBBLE_MAX;
+    const coded_match_length = match_length - MIN_MATCH;
+    const match_saturated = coded_match_length >= NIBBLE_MAX;
+
+    let required = 1 + literal_length;
+
+    if (literal_saturated) {
+        required += continuation_size(literal_length - NIBBLE_MAX);
+    }
+
+    if (out + required > out_end) {
+        throw new Error(
+            `lz4 sequence of ${literal_length} literals needs ${required} bytes, and only ${out_end - out} are left`
+        );
+    }
+
+    const token = out++;
+
+    destination[token] = ((literal_saturated ? NIBBLE_MAX : literal_length) << 4)
+        | (match_saturated ? NIBBLE_MAX : coded_match_length);
+
+    if (literal_saturated) {
+        out = write_continuation(out, literal_length - NIBBLE_MAX);
+    }
+
+    if (literal_length >= BULK_COPY_LENGTH) {
+        destination.set(source.subarray(base + anchor, base + anchor + literal_length), out);
+    } else {
+        for (let i = 0; i < literal_length; i++) {
+            destination[out + i] = source[base + anchor + i];
+        }
+    }
+
+    out += literal_length;
+
+    let match_required = 2;
+
+    if (match_saturated) {
+        match_required += continuation_size(coded_match_length - NIBBLE_MAX);
+    }
+
+    if (out + match_required > out_end) {
+        throw new Error(
+            `lz4 match of ${match_length} needs ${match_required} bytes, and only ${out_end - out} are left`
+        );
+    }
+
+    destination[out++] = offset & 0xFF;
+    destination[out++] = (offset >> 8) & 0xFF;
+
+    if (match_saturated) {
+        out = write_continuation(out, coded_match_length - NIBBLE_MAX);
+    }
+}
+
+/**
+ * Close the block with its trailing literals, and no match behind them.
+ *
+ * @param {number} anchor
+ * @param {number} end
+ * @throws {Error} if they do not fit the space given
+ */
+function write_last_literals(anchor, end) {
+    const literal_length = end - anchor;
+    const saturated = literal_length >= NIBBLE_MAX;
+
+    let required = 1 + literal_length;
+
+    if (saturated) {
+        required += continuation_size(literal_length - NIBBLE_MAX);
+    }
+
+    if (out + required > out_end) {
+        throw new Error(
+            `lz4 sequence of ${literal_length} literals needs ${required} bytes, and only ${out_end - out} are left`
+        );
+    }
+
+    destination[out++] = (saturated ? NIBBLE_MAX : literal_length) << 4;
+
+    if (saturated) {
+        out = write_continuation(out, literal_length - NIBBLE_MAX);
+    }
+
+    if (literal_length >= BULK_COPY_LENGTH) {
+        destination.set(source.subarray(base + anchor, base + anchor + literal_length), out);
+    } else {
+        for (let i = 0; i < literal_length; i++) {
+            destination[out + i] = source[base + anchor + i];
+        }
+    }
+
+    out += literal_length;
+}
+
+/**
+ * Levels 3 to 9: walk the chain, and parse lazily.
+ *
+ * The parse holds up to three matches at once — the one in hand, one starting two bytes before it
+ * ends, and one starting three bytes before *that* ends — and trims the earlier ones against the
+ * later so that a long match is never cut short by a short one that happened to be found first.
+ * Where they overlap it is the *bytes* that decide, not the order: a match is shortened only as far
+ * as the one behind it can pay for.
+ *
+ * @param {number} max_attempts
+ * @param {boolean} pattern_analysis
+ */
+function compress_hash_chain(max_attempts, pattern_analysis) {
+    let ip = 0;
+    let anchor = 0;
+
+    let start0 = 0;
+    let start2 = 0;
+    let start3 = 0;
+
+    let m0_length = 0;
+    let m0_offset = 0;
+    let m1_length = 0;
+    let m1_offset = 0;
+    let m2_length = 0;
+    let m2_offset = 0;
+    let m3_length = 0;
+    let m3_offset = 0;
+
+    main: while (ip <= match_find_limit) {
+        insert_and_find_best_match(ip, match_limit, max_attempts, pattern_analysis);
+
+        m1_length = found_length;
+        m1_offset = found_offset;
+
+        if (m1_length < MIN_MATCH) {
+            ip++;
+            continue;
+        }
+
+        // kept in case the search below walks so far forward that the first match is worth going
+        // back for
+        start0 = ip;
+        m0_length = m1_length;
+        m0_offset = m1_offset;
+
+        search2: for (;;) {
+            if (ip + m1_length <= match_find_limit) {
+                start2 = ip + m1_length - 2;
+
+                insert_and_get_wider_match(start2, ip, match_limit, m1_length, max_attempts, pattern_analysis, false);
+
+                m2_length = found_length;
+                m2_offset = found_offset;
+                start2 += found_back;
+            } else {
+                m2_length = 0;
+                m2_offset = 0;
+            }
+
+            if (m2_length <= m1_length) {
+                encode_sequence(anchor, ip, m1_length, m1_offset);
+
+                ip += m1_length;
+                anchor = ip;
+
+                continue main;
+            }
+
+            if (start0 < ip && start2 < ip + m0_length) {
+                // squeezing this match between the one it replaced and the better one found past
+                // it costs more than going back and taking the first one
+                ip = start0;
+                m1_length = m0_length;
+                m1_offset = m0_offset;
+            }
+
+            if ((start2 - ip) < 3) {
+                // nothing would be left of the first match, so it goes
+                ip = start2;
+                m1_length = m2_length;
+                m1_offset = m2_offset;
+
+                continue search2;
+            }
+
+            search3: for (;;) {
+                if ((start2 - ip) < OPTIMAL_ML) {
+                    let new_length = m1_length;
+
+                    if (new_length > OPTIMAL_ML) {
+                        new_length = OPTIMAL_ML;
+                    }
+
+                    if (ip + new_length > start2 + m2_length - MIN_MATCH) {
+                        new_length = (start2 - ip) + m2_length - MIN_MATCH;
+                    }
+
+                    const correction = new_length - (start2 - ip);
+
+                    if (correction > 0) {
+                        start2 += correction;
+                        m2_length -= correction;
+                    }
+                }
+
+                if (start2 + m2_length <= match_find_limit) {
+                    start3 = start2 + m2_length - 3;
+
+                    insert_and_get_wider_match(start3, start2, match_limit, m2_length, max_attempts, pattern_analysis, false);
+
+                    m3_length = found_length;
+                    m3_offset = found_offset;
+                    start3 += found_back;
+                } else {
+                    m3_length = 0;
+                    m3_offset = 0;
+                }
+
+                if (m3_length <= m2_length) {
+                    // two matches, and nothing better behind them
+                    if (start2 < ip + m1_length) {
+                        m1_length = start2 - ip;
+                    }
+
+                    encode_sequence(anchor, ip, m1_length, m1_offset);
+
+                    ip += m1_length;
+                    anchor = ip;
+
+                    ip = start2;
+
+                    encode_sequence(anchor, ip, m2_length, m2_offset);
+
+                    ip += m2_length;
+                    anchor = ip;
+
+                    continue main;
+                }
+
+                if (start3 < ip + m1_length + 3) {
+                    // no room for the middle match
+                    if (start3 >= ip + m1_length) {
+                        if (start2 < ip + m1_length) {
+                            const correction = (ip + m1_length) - start2;
+
+                            start2 += correction;
+                            m2_length -= correction;
+
+                            if (m2_length < MIN_MATCH) {
+                                start2 = start3;
+                                m2_length = m3_length;
+                                m2_offset = m3_offset;
+                            }
+                        }
+
+                        encode_sequence(anchor, ip, m1_length, m1_offset);
+
+                        ip += m1_length;
+                        anchor = ip;
+
+                        ip = start3;
+                        m1_length = m3_length;
+                        m1_offset = m3_offset;
+
+                        start0 = start2;
+                        m0_length = m2_length;
+                        m0_offset = m2_offset;
+
+                        continue search2;
+                    }
+
+                    start2 = start3;
+                    m2_length = m3_length;
+                    m2_offset = m3_offset;
+
+                    continue search3;
+                }
+
+                // three matches in a row: write the first, and slide the other two down
+                if (start2 < ip + m1_length) {
+                    if ((start2 - ip) < OPTIMAL_ML) {
+                        if (m1_length > OPTIMAL_ML) {
+                            m1_length = OPTIMAL_ML;
+                        }
+
+                        if (ip + m1_length > start2 + m2_length - MIN_MATCH) {
+                            m1_length = (start2 - ip) + m2_length - MIN_MATCH;
+                        }
+
+                        const correction = m1_length - (start2 - ip);
+
+                        if (correction > 0) {
+                            start2 += correction;
+                            m2_length -= correction;
+                        }
+                    } else {
+                        m1_length = start2 - ip;
+                    }
+                }
+
+                encode_sequence(anchor, ip, m1_length, m1_offset);
+
+                ip += m1_length;
+                anchor = ip;
+
+                ip = start2;
+                m1_length = m2_length;
+                m1_offset = m2_offset;
+
+                start2 = start3;
+                m2_length = m3_length;
+                m2_offset = m3_offset;
+
+                continue search3;
+            }
+        }
+    }
+
+    write_last_literals(anchor, input_size);
+}
+
+/**
+ * What a literal run costs in bytes: the literals, and the continuation its count spills into.
+ *
+ * @param {number} length
+ * @returns {number}
+ */
+function literals_price(length) {
+    let price = length;
+
+    if (length >= NIBBLE_MAX) {
+        price += 1 + (((length - NIBBLE_MAX) / CONTINUATION_MAX) | 0);
+    }
+
+    return price;
+}
+
+/**
+ * What a whole sequence costs in bytes: a token, a sixteen-bit offset, the literals in front of it,
+ * and the continuation the match length spills into.
+ *
+ * @param {number} literal_length
+ * @param {number} match_length at least {@link MIN_MATCH}
+ * @returns {number}
+ */
+function sequence_price(literal_length, match_length) {
+    let price = 1 + 2 + literals_price(literal_length);
+
+    if (match_length >= NIBBLE_MAX + MIN_MATCH) {
+        price += 1 + (((match_length - (NIBBLE_MAX + MIN_MATCH)) / CONTINUATION_MAX) | 0);
+    }
+
+    return price;
+}
+
+/**
+ * The search the optimal parse makes: from the position itself, so the match cannot reach behind,
+ * and reporting nothing at all unless it beats `min_length` outright.
+ *
+ * @param {number} position
+ * @param {number} high_limit
+ * @param {number} min_length the length to beat, which a caller that has priced everything up to
+ *                            some point sets to what is already covered rather than to the format's
+ *                            minimum — a shorter match there cannot change any price
+ * @param {number} max_attempts
+ */
+function find_longer_match(position, high_limit, min_length, max_attempts) {
+    insert_and_get_wider_match(position, position, high_limit, min_length, max_attempts, true, true);
+
+    if (found_length <= min_length) {
+        found_length = 0;
+        found_offset = 0;
+    }
+}
+
+/**
+ * Recover the path through a solved window, write the sequences on it, and leave the parse just
+ * past the last of them in {@link window_ip} and {@link window_anchor}.
+ *
+ * The table holds, at each position, the step that arrives there most cheaply — which is a step
+ * read *backwards*. Walking those steps from the end of the path rewrites each entry as the step
+ * that *leaves* it, and the same table is then the path read forwards.
+ *
+ * @param {number} ip where the window starts
+ * @param {number} anchor the first literal not yet written
+ * @param {number} from the position the last sequence on the path starts at
+ * @param {number} last_match_pos one past the last position the path covers
+ * @param {number} best_length the last sequence's match length
+ * @param {number} best_offset the last sequence's offset
+ */
+function encode_window(ip, anchor, from, last_match_pos, best_length, best_offset) {
+    let candidate = from;
+    let length = best_length;
+    let offset = best_offset;
+
+    for (;;) {
+        const next_length = opt_match_length[candidate];
+        const next_offset = opt_offset[candidate];
+
+        opt_match_length[candidate] = length;
+        opt_offset[candidate] = offset;
+
+        length = next_length;
+        offset = next_offset;
+
+        if (next_length > candidate) {
+            // the step that arrives here reaches back past the start of the window, so it is the
+            // first sequence of the path and there is nothing behind it
+            break;
+        }
+
+        candidate -= next_length;
+    }
+
+    let p = ip;
+    let a = anchor;
+    let r = 0;
+
+    while (r < last_match_pos) {
+        const match_length = opt_match_length[r];
+
+        // a literal, and possibly several: the path steps over them one at a time
+        if (match_length === 1) {
+            p++;
+            r++;
+            continue;
+        }
+
+        encode_sequence(a, p, match_length, opt_offset[r]);
+
+        p += match_length;
+        a = p;
+        r += match_length;
+    }
+
+    window_ip = p;
+    window_anchor = a;
+}
+
+/**
+ * Levels 10 to 12: solve the parse rather than guess it.
+ *
+ * Over a window of the block, the cheapest coding of the first `n` bytes is built from the cheapest
+ * coding of every shorter prefix, taking a match found at each position as one edge and a literal
+ * as another. The price is in *bytes*, exactly — a token, a two-byte offset, and the continuation
+ * bytes each saturated length field spills into — so this is a genuine shortest path and not a
+ * heuristic with a cost model bolted on. The window is walked back from its end to recover the
+ * path, and the sequences on it are written in order.
+ *
+ * What stops it going quadratic is `sufficient_length`: a match at least that long is taken and
+ * encoded on the spot, with no path solved through it at all. Level 12 raises that to the window
+ * itself and searches every position rather than only those whose price rises, which is what the
+ * last two ten-thousandths of a percent cost — and why an encoder that drops the early exit
+ * entirely, which was measured, spends a hundred times level 12's budget to find nothing.
+ *
+ * @param {number} max_attempts
+ * @param {number} sufficient_length
+ * @param {boolean} full_update
+ */
+function compress_optimal(max_attempts, sufficient_length, full_update) {
+    // the window is what the tables hold, so nothing may be priced past it
+    const enough = sufficient_length >= OPT_NUM ? OPT_NUM - 1 : sufficient_length;
+
+    let ip = 0;
+    let anchor = 0;
+
+    while (ip <= match_find_limit) {
+        const literal_run = ip - anchor;
+
+        find_longer_match(ip, match_limit, MIN_MATCH - 1, max_attempts);
+
+        if (found_length === 0) {
+            ip++;
+            continue;
+        }
+
+        const first_length = found_length;
+        const first_offset = found_offset;
+
+        if (first_length > enough) {
+            // good enough to take on sight
+            encode_sequence(anchor, ip, first_length, first_offset);
+
+            ip += first_length;
+            anchor = ip;
+
+            continue;
+        }
+
+        // the first few positions, as literals carrying on from the run already open
+        for (let r = 0; r < MIN_MATCH; r++) {
+            opt_match_length[r] = 1;
+            opt_offset[r] = 0;
+            opt_literal_length[r] = literal_run + r;
+            opt_price[r] = literals_price(literal_run + r);
+        }
+
+        // and every length the first match can be cut to
+        for (let length = MIN_MATCH; length <= first_length; length++) {
+            opt_match_length[length] = length;
+            opt_offset[length] = first_offset;
+            opt_literal_length[length] = literal_run;
+            opt_price[length] = sequence_price(literal_run, length);
+        }
+
+        let last_match_pos = first_length;
+        let best_length = 0;
+        let best_offset = 0;
+        let from = 0;
+        let solved = false;
+
+        for (let add = 1; add <= TRAILING_LITERALS; add++) {
+            opt_match_length[last_match_pos + add] = 1;
+            opt_offset[last_match_pos + add] = 0;
+            opt_literal_length[last_match_pos + add] = add;
+            opt_price[last_match_pos + add] = opt_price[last_match_pos] + literals_price(add);
+        }
+
+        for (let cur = 1; cur < last_match_pos; cur++) {
+            const position = ip + cur;
+
+            if (position > match_find_limit) {
+                break;
+            }
+
+            if (full_update) {
+                // A position whose successor already codes at least as cheaply is one nothing can
+                // be gained at — unless the price climbs sharply just past it, where even the
+                // shortest sequence there is would pay for itself.
+                if (
+                    opt_price[cur + 1] <= opt_price[cur]
+                    && opt_price[cur + MIN_MATCH] < opt_price[cur] + 3
+                ) {
+                    continue;
+                }
+            } else if (opt_price[cur + 1] <= opt_price[cur]) {
+                continue;
+            }
+
+            // Below the top level, only a match reaching past everything already priced is compared
+            // at all. It misses a few bytes, and it is most of what levels 10 and 11 cost less than
+            // 12 for.
+            find_longer_match(
+                position,
+                match_limit,
+                full_update ? MIN_MATCH - 1 : last_match_pos - cur,
+                max_attempts
+            );
+
+            if (found_length === 0) {
+                continue;
+            }
+
+            const new_length = found_length;
+            const new_offset = found_offset;
+
+            if (new_length > enough || new_length + cur >= OPT_NUM) {
+                // good enough, or past what the tables hold: stop solving and take it
+                best_length = new_length;
+                best_offset = new_offset;
+                from = cur;
+                last_match_pos = cur + 1;
+                solved = true;
+
+                break;
+            }
+
+            // literals in front of a match here, which the prices past it may not have counted
+            const base_literals = opt_literal_length[cur];
+
+            for (let extra = 1; extra < MIN_MATCH; extra++) {
+                const price = opt_price[cur] - literals_price(base_literals) + literals_price(base_literals + extra);
+                const p = cur + extra;
+
+                if (price < opt_price[p]) {
+                    opt_match_length[p] = 1;
+                    opt_offset[p] = 0;
+                    opt_literal_length[p] = base_literals + extra;
+                    opt_price[p] = price;
+                }
+            }
+
+            // and the match itself, at every length it can be cut to
+            for (let length = MIN_MATCH; length <= new_length; length++) {
+                const p = cur + length;
+
+                let literals;
+                let price;
+
+                if (opt_match_length[cur] === 1) {
+                    // arriving here on literals, so they join the run in front of this match rather
+                    // than being paid for twice
+                    literals = opt_literal_length[cur];
+                    price = (cur > literals ? opt_price[cur - literals] : 0) + sequence_price(literals, length);
+                } else {
+                    literals = 0;
+                    price = opt_price[cur] + sequence_price(0, length);
+                }
+
+                if (p > last_match_pos + TRAILING_LITERALS || price <= opt_price[p]) {
+                    if (length === new_length && last_match_pos < p) {
+                        last_match_pos = p;
+                    }
+
+                    opt_match_length[p] = length;
+                    opt_offset[p] = new_offset;
+                    opt_literal_length[p] = literals;
+                    opt_price[p] = price;
+                }
+            }
+
+            for (let add = 1; add <= TRAILING_LITERALS; add++) {
+                opt_match_length[last_match_pos + add] = 1;
+                opt_offset[last_match_pos + add] = 0;
+                opt_literal_length[last_match_pos + add] = add;
+                opt_price[last_match_pos + add] = opt_price[last_match_pos] + literals_price(add);
+            }
+        }
+
+        if (solved === false) {
+            best_length = opt_match_length[last_match_pos];
+            best_offset = opt_offset[last_match_pos];
+            from = last_match_pos - best_length;
+        }
+
+        encode_window(ip, anchor, from, last_match_pos, best_length, best_offset);
+
+        ip = window_ip;
+        anchor = window_anchor;
+    }
+
+    write_last_literals(anchor, input_size);
+}
+
+/**
+ * Encode one LZ4 block at a compression level.
+ *
+ * A port of the reference implementation's `lz4hc`, without its dictionary and streaming support:
+ * meep compresses one self-contained block with no history, so the external dictionary, the
+ * dictionary context, the pattern rotation across a dictionary boundary, `favorDecSpeed` and
+ * `fillOutput` all drop, and with them about half the reference file. What is left is byte for byte
+ * what `LZ4_compress_HC` writes at the same level.
+ *
+ * **The format does not change.** This emits ordinary LZ4 blocks — the same tokens, the same
+ * sixteen-bit offsets, the same restrictions on where a match may start — so a block written here
+ * at any level decodes under {@link lz4_decompress_block} and under every other reader that exists.
+ * What changes is only how hard the encoder looked: where {@link lz4_compress_block} takes the
+ * first match a hash slot offers, this walks a chain of every position carrying the same hash and
+ * parses the matches it finds against each other.
+ *
+ * What that is worth depends entirely on the payload. On text it is 20% or more; on quantised,
+ * densely packed bytes — geometry pages, say — it is about 2.5%, and almost all of that is already
+ * there at level 3. What it costs is an order of magnitude of throughput: 400 MB/s becomes 50.
+ *
+ * `destination` and `source` must not overlap.
+ *
+ * @see https://github.com/lz4/lz4/blob/dev/lib/lz4hc.c — `LZ4HC_compress_hashChain` and `LZ4HC_compress_optimal`
+ *
+ * @param {Uint8Array} p_destination
+ * @param {number} destination_offset where this block's output starts
+ * @param {number} destination_end one past the last byte the block may write; give it
+ *                                 {@link lz4_compress_bound} bytes and it cannot run out
+ * @param {Uint8Array} p_source
+ * @param {number} source_offset the first byte of input, and the floor a match may reach back to
+ * @param {number} source_end one past the last byte of input
+ * @param {number} level one of {@link LZ4_LEVEL}'s high-compression levels
+ * @returns {number} the offset just past the last byte written
+ * @throws {Error} if the block does not fit the space given for it
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function lz4_compress_block_hc(p_destination, destination_offset, destination_end, p_source, source_offset, source_end, level) {
+    assert.isNonNegativeInteger(destination_offset, 'destination_offset');
+    assert.lessThanOrEqual(destination_end, p_destination.length, 'destination_end');
+    assert.lessThanOrEqual(destination_offset, destination_end, 'destination_offset');
+    assert.isNonNegativeInteger(source_offset, 'source_offset');
+    assert.lessThanOrEqual(source_end, p_source.length, 'source_end');
+    assert.lessThanOrEqual(source_offset, source_end, 'source_offset');
+    // positions are held in an Int32Array, and a conforming block carries no more than this anyway
+    assert.lessThanOrEqual(source_end, LZ4_MAX_INPUT_SIZE, 'source_end');
+    assert.isInteger(level, 'level');
+    // a level outside the ladder is a caller asking for something this encoder does not have, and
+    // clamping it would silently give them a different encoder than the one they named
+    assert.ok(
+        level >= LZ4_LEVEL.HC_MIN && level <= LZ4_LEVEL.HC_MAX,
+        `level must be between ${LZ4_LEVEL.HC_MIN} and ${LZ4_LEVEL.HC_MAX}, was ${level}`
+    );
+
+    // Read *here*, not inside the length check below, so that a level this encoder does not have
+    // fails the same way whatever the input size. The assert above is what refuses one, and a
+    // consumer that strips asserts — which is how meep ships — has only this: without it, level 2
+    // would throw on a page and quietly produce a valid block on anything under thirteen bytes.
+    const parameters = LEVEL_TABLE[level];
+    const attempts = parameters.attempts;
+    const optimal = parameters.optimal;
+
+    destination = p_destination;
+    source = p_source;
+    base = source_offset;
+    input_size = source_end - source_offset;
+
+    out = destination_offset;
+    out_end = destination_end;
+
+    try {
+        if (input_size >= MIN_LENGTH) {
+            if (hash_table === null) {
+                hash_table = new Int32Array(1 << HASH_LOG);
+                chain_table = new Uint16Array(1 << 16);
+            }
+
+            view = new DataView(source.buffer, source.byteOffset, source.byteLength);
+
+            hash_table.fill(0);
+            chain_table.fill(0xFFFF);
+
+            next_to_update = IDX_BASE;
+            match_find_limit = input_size - MATCH_FIND_LIMIT;
+            match_limit = input_size - LAST_LITERALS;
+
+            if (optimal) {
+                if (opt_price === null) {
+                    opt_price = new Int32Array(OPT_TABLE_SIZE);
+                    opt_offset = new Int32Array(OPT_TABLE_SIZE);
+                    opt_match_length = new Int32Array(OPT_TABLE_SIZE);
+                    opt_literal_length = new Int32Array(OPT_TABLE_SIZE);
+                }
+
+                compress_optimal(attempts, parameters.sufficient_length, parameters.full_update);
+            } else {
+                compress_hash_chain(attempts, attempts > PATTERN_ANALYSIS_THRESHOLD);
+            }
+        } else {
+            write_last_literals(0, input_size);
+        }
+    } finally {
+        // However the call ends. A destination too small throws, and without this the encoder would
+        // go on holding that call's buffers — the caller's whole input — until the next successful
+        // one. A caller that catches the throw and carries on is exactly the caller that would
+        // notice: it is the one still running.
+        source = null;
+        view = null;
+        destination = null;
+    }
+
+    return out;
+}